diff --git a/docs/ADMIN-GUIDE/README.md b/docs/ADMIN-GUIDE/README.md index 0a3f33cf..2aef404b 100644 --- a/docs/ADMIN-GUIDE/README.md +++ b/docs/ADMIN-GUIDE/README.md @@ -7,7 +7,7 @@ This book is the canonical home for installation, configuration, deployment, rou ## Start here - [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries. -- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths. +- [Documentation sitemap](../SITEMAP.md) — resolvable current navigation and authority-gated migration summary. - [Product requirements](../PRD.md) — normative requirements, currently marked draft. - [Operations index](operations/README.md) — current local procedures and explicitly held operational outlines. - [Security index](security/README.md) — current SSO provider configuration. @@ -33,8 +33,9 @@ Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP These are source candidates, not verified runbooks: -- [`_old_structure/guides/admin-guide.md`](../_old_structure/guides/admin-guide.md) — historical source; verify claims before promotion. -- [`_old_structure/guides/deployment.md`](../_old_structure/guides/deployment.md) — historical source; verify commands and deployment assumptions before promotion. +- `_old_structure/guides/admin-guide.md` — quarantined historical source; verify claims before promotion. +- `_old_structure/guides/deployment.md` — quarantined historical source; deployment commands and assumptions remain held. +- See the [documentation catalog](../reports/documentation/2026-08-10-docs-catalog-audit.md) for file-level dispositions. Do not treat a migration candidate as current until its commands, paths, permissions, and safety status are checked against source and tests. diff --git a/docs/API/README.md b/docs/API/README.md index 957cbf0b..2d6fc5a5 100644 --- a/docs/API/README.md +++ b/docs/API/README.md @@ -7,7 +7,7 @@ This directory is the single API documentation boundary. `OPENAPI.yaml` will be ## Start here - [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries. -- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths. +- [Documentation sitemap](../SITEMAP.md) — current API transition status and authority-gated backlog. - [Documentation catalog audit](../reports/documentation/2026-08-10-docs-catalog-audit.md) — current API artifact inventory and migration evidence. ## Contract map diff --git a/docs/DEVELOPER-GUIDE/README.md b/docs/DEVELOPER-GUIDE/README.md index e9a4922a..39699767 100644 --- a/docs/DEVELOPER-GUIDE/README.md +++ b/docs/DEVELOPER-GUIDE/README.md @@ -35,7 +35,7 @@ These are source candidates or stale records, not verified current instructions: - [`archived TUI PRD`](../archive/tui/PRD-TUI_Improvements.md) — contradicted/stale; it references a missing `packages/cli`, while current TUI code is under `packages/mosaic`. - [`archived TUI task ledger`](../archive/tui/TASKS-TUI_Improvements.md) — historical task ledger; its status and worktree claims require revalidation. -- [`_old_structure/guides/dev-guide.md`](../_old_structure/guides/dev-guide.md) — historical source; verify paths and commands before promotion. +- `_old_structure/guides/dev-guide.md` — quarantined historical source; verify paths and commands before promotion. See the [documentation catalog](../reports/documentation/2026-08-10-docs-catalog-audit.md) for its disposition. Do not make a legacy or archived page current by linking it from a chapter as if it were already promoted. diff --git a/docs/SITEMAP.md b/docs/SITEMAP.md index e450a1c0..e95cedf1 100644 --- a/docs/SITEMAP.md +++ b/docs/SITEMAP.md @@ -16,7 +16,7 @@ - [Product requirements](PRD.md) — normative requirements; currently marked draft and retaining authority-gated legacy references. - [Active task rollup](TASKS.md) — orchestrator-owned work state; workers do not modify it. -- [MVP mission manifest](MISSION-MANIFEST.md) — stale rollup retained pending an orchestrator/maintainer disposition decision. +- [MVP mission manifest](MISSION-MANIFEST.md) — declares itself active; current workstream status and stale outbound links await orchestrator/maintainer validation. - [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — complete baseline inventory, evidence labels, broken-link clusters, and migration recommendations. ## User documentation @@ -57,9 +57,12 @@ ## Evidence and planning - [Reports index](reports/README.md) — all tracked report categories and evidence boundaries. +- [Archived missions](archive/missions/README.md) — historical CLI, harness, install UX, and storage-abstraction delivery records. - [P8-003 performance report](reports/qa/p8-003-performance-optimization.md) — historical implementation evidence, not a current SLO. +- [Plans index](plans/README.md) — approved intent and implementation/audit plans. - [Documentation information-architecture design](plans/2026-08-10-docs-information-architecture-design.md) — approved documentation structure decision. - [Documentation catalog-audit plan](plans/2026-08-10-docs-catalog-audit.md) — evidence method and migration acceptance criteria. +- [Scratchpads index](scratchpads/README.md) — working memory and verification records. - [Documentation migration scratchpad](scratchpads/DOCS-IA-002-catalog-audit.md) — coordinator progress, verification, and resumability record. ## Authority-gated migration backlog diff --git a/docs/USER-GUIDE/README.md b/docs/USER-GUIDE/README.md index 94e959d2..269ee134 100644 --- a/docs/USER-GUIDE/README.md +++ b/docs/USER-GUIDE/README.md @@ -7,7 +7,7 @@ This book is the canonical home for end-user workflows, user-visible behavior, p ## Start here - [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries. -- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths. +- [Documentation sitemap](../SITEMAP.md) — resolvable current navigation and authority-gated migration summary. - [Quickstart](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session. - [Web dashboard](product/web-dashboard.md) — current routes, navigation, chat persistence, projects/tasks views, settings, and admin behavior. - [Discord conversations](workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow. @@ -34,8 +34,8 @@ Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP These are source candidates, not current user guidance: -- [`_old_structure/guides/user-guide.md`](../_old_structure/guides/user-guide.md) — historical source; verify every claim before promotion. - The former root `QUICKSTART.md` was an empty placeholder and has been replaced by the current page above. +- `_old_structure/guides/user-guide.md` — quarantined historical source; verify every claim before promotion. See the [documentation catalog](../reports/documentation/2026-08-10-docs-catalog-audit.md) for its disposition. +- The former root `QUICKSTART.md` was an empty placeholder and has been replaced by the current page above. Do not link to the quarantine as a current user path. Create a new page only after classifying its audience, status, and evidence in the migration report. diff --git a/docs/archive/README.md b/docs/archive/README.md index 2d09ee0b..7ff1b838 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -13,6 +13,12 @@ The following branch-specific records are retained because their implementation Do not use these pages as instructions for the current TUI. Current TUI implementation is under `packages/mosaic`; any new requirements require a separately approved plan or PRD. +## Archived missions + +- [`Mission archive index`](missions/README.md) — completed and superseded CLI, harness, install UX, and storage-abstraction mission records. + +Archived mission manifests and task ledgers preserve their original status and context. They do not replace current orchestrator-owned [`docs/TASKS.md`](../TASKS.md) or authorize old installation procedures. + ## Retention rules - Preserve historical wording unless a migration task explicitly requires a rewrite. diff --git a/docs/archive/missions/README.md b/docs/archive/missions/README.md new file mode 100644 index 00000000..7d95fd86 --- /dev/null +++ b/docs/archive/missions/README.md @@ -0,0 +1,37 @@ +# Archived Missions + +> **Status:** Historical mission index. These records describe completed or superseded delivery work and are not current task state, requirements, installation guidance, or command authority. + +## CLI unification — 2026-04-04 + +- [Mission manifest](cli-unification-20260404/MISSION-MANIFEST.md) +- [Task ledger](cli-unification-20260404/TASKS.md) + +## Harness foundation — 2026-03-21 + +- [Mission manifest](harness-20260321/MISSION-MANIFEST.md) +- [Scoped PRD](harness-20260321/PRD.md) + +## Install UX hardening — 2026-04-05 + +- [Mission manifest](install-ux-hardening-20260405/MISSION-MANIFEST.md) +- [Task ledger](install-ux-hardening-20260405/TASKS.md) + +## Install UX v2 — 2026-04-05 + +- [Mission manifest](install-ux-v2-20260405/MISSION-MANIFEST.md) +- [Task ledger](install-ux-v2-20260405/TASKS.md) +- [IUV-M03 design](install-ux-v2-20260405/iuv-m03-design.md) +- [Orchestrator scratchpad](install-ux-v2-20260405/scratchpad.md) + +## Storage abstraction retrofit + +- [Task ledger](storage-abstraction/TASKS.md) + +Historical statuses, commands, package paths, and completion claims are retained for provenance and may not match the current checkout. Use [`docs/TASKS.md`](../../TASKS.md) only for orchestrator-owned current task state. + +## Related + +- [[archive/README|Documentation archive]] +- [[SITEMAP|Documentation sitemap]] +- [[reports/README|Documentation reports]] diff --git a/docs/_old_structure/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md b/docs/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md similarity index 100% rename from docs/_old_structure/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md rename to docs/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md diff --git a/docs/_old_structure/archive/missions/cli-unification-20260404/TASKS.md b/docs/archive/missions/cli-unification-20260404/TASKS.md similarity index 100% rename from docs/_old_structure/archive/missions/cli-unification-20260404/TASKS.md rename to docs/archive/missions/cli-unification-20260404/TASKS.md diff --git a/docs/_old_structure/archive/missions/harness-20260321/MISSION-MANIFEST.md b/docs/archive/missions/harness-20260321/MISSION-MANIFEST.md similarity index 100% rename from docs/_old_structure/archive/missions/harness-20260321/MISSION-MANIFEST.md rename to docs/archive/missions/harness-20260321/MISSION-MANIFEST.md diff --git a/docs/_old_structure/archive/missions/harness-20260321/PRD.md b/docs/archive/missions/harness-20260321/PRD.md similarity index 100% rename from docs/_old_structure/archive/missions/harness-20260321/PRD.md rename to docs/archive/missions/harness-20260321/PRD.md diff --git a/docs/_old_structure/archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md b/docs/archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md similarity index 97% rename from docs/_old_structure/archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md rename to docs/archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md index 9617119c..9a4ee662 100644 --- a/docs/_old_structure/archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md +++ b/docs/archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md @@ -12,7 +12,7 @@ **Progress:** 3 / 3 milestones **Status:** complete **Last Updated:** 2026-04-05 (mission complete) -**Parent Mission:** [cli-unification-20260404](./archive/missions/cli-unification-20260404/MISSION-MANIFEST.md) (complete) +**Parent Mission:** [cli-unification-20260404](../cli-unification-20260404/MISSION-MANIFEST.md) (complete) ## Context diff --git a/docs/_old_structure/archive/missions/install-ux-hardening-20260405/TASKS.md b/docs/archive/missions/install-ux-hardening-20260405/TASKS.md similarity index 100% rename from docs/_old_structure/archive/missions/install-ux-hardening-20260405/TASKS.md rename to docs/archive/missions/install-ux-hardening-20260405/TASKS.md diff --git a/docs/_old_structure/archive/missions/install-ux-v2-20260405/MISSION-MANIFEST.md b/docs/archive/missions/install-ux-v2-20260405/MISSION-MANIFEST.md similarity index 97% rename from docs/_old_structure/archive/missions/install-ux-v2-20260405/MISSION-MANIFEST.md rename to docs/archive/missions/install-ux-v2-20260405/MISSION-MANIFEST.md index d438643f..d82aea21 100644 --- a/docs/_old_structure/archive/missions/install-ux-v2-20260405/MISSION-MANIFEST.md +++ b/docs/archive/missions/install-ux-v2-20260405/MISSION-MANIFEST.md @@ -13,7 +13,7 @@ **Status:** complete **Last Updated:** 2026-04-19 (archived during MVP manifest authoring; IUV-M03 substantively shipped via PR #446 — drill-down menu + provider-first flow + quick start; releases 0.0.27 → 0.0.29) **Archived to:** `docs/archive/missions/install-ux-v2-20260405/` -**Parent Mission:** [install-ux-hardening-20260405](./archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md) (complete — `mosaic-v0.0.25`) +**Parent Mission:** [install-ux-hardening-20260405](../install-ux-hardening-20260405/MISSION-MANIFEST.md) (complete — `mosaic-v0.0.25`) ## Context diff --git a/docs/_old_structure/archive/missions/install-ux-v2-20260405/TASKS.md b/docs/archive/missions/install-ux-v2-20260405/TASKS.md similarity index 100% rename from docs/_old_structure/archive/missions/install-ux-v2-20260405/TASKS.md rename to docs/archive/missions/install-ux-v2-20260405/TASKS.md diff --git a/docs/_old_structure/archive/missions/install-ux-v2-20260405/iuv-m03-design.md b/docs/archive/missions/install-ux-v2-20260405/iuv-m03-design.md similarity index 100% rename from docs/_old_structure/archive/missions/install-ux-v2-20260405/iuv-m03-design.md rename to docs/archive/missions/install-ux-v2-20260405/iuv-m03-design.md diff --git a/docs/_old_structure/archive/missions/install-ux-v2-20260405/scratchpad.md b/docs/archive/missions/install-ux-v2-20260405/scratchpad.md similarity index 100% rename from docs/_old_structure/archive/missions/install-ux-v2-20260405/scratchpad.md rename to docs/archive/missions/install-ux-v2-20260405/scratchpad.md diff --git a/docs/_old_structure/archive/missions/storage-abstraction/TASKS.md b/docs/archive/missions/storage-abstraction/TASKS.md similarity index 100% rename from docs/_old_structure/archive/missions/storage-abstraction/TASKS.md rename to docs/archive/missions/storage-abstraction/TASKS.md diff --git a/docs/plans/README.md b/docs/plans/README.md new file mode 100644 index 00000000..2036d527 --- /dev/null +++ b/docs/plans/README.md @@ -0,0 +1,17 @@ +# Documentation Plans + +> **Status:** Current artifact index. Plans record approved intent and execution approach; they are not current product behavior or operational authority. + +## Documentation migration plans + +- [Information architecture design](2026-08-10-docs-information-architecture-design.md) — approved audience books, artifact boundaries, source-of-truth rules, and migration model. +- [Documentation structure README implementation](2026-08-10-docs-structure-readme.md) — completed implementation plan for the documentation contract and atlas. +- [Documentation catalog and truth audit](2026-08-10-docs-catalog-audit.md) — audit method, evidence statuses, deliverables, and acceptance criteria. + +After a plan is delivered, update the canonical guide, contract, decision, or index. Do not cite a plan as proof that intended behavior shipped. + +## Related + +- [[README|Documentation contract]] +- [[SITEMAP|Documentation sitemap]] +- [[scratchpads/README|Documentation scratchpads]] diff --git a/docs/scratchpads/README.md b/docs/scratchpads/README.md new file mode 100644 index 00000000..67586383 --- /dev/null +++ b/docs/scratchpads/README.md @@ -0,0 +1,16 @@ +# Documentation Scratchpads + +> **Status:** Current artifact index. Scratchpads are working memory and verification records, not product requirements or command authority. + +## Documentation migration records + +- [DOCS-IA-001 — information architecture](DOCS-IA-001.md) — completed structure-design and documentation-contract record. +- [DOCS-IA-002 — catalog audit and migration](DOCS-IA-002-catalog-audit.md) — active coordinator progress, autonomous lane state, verification evidence, and authority blockers. + +Completed scratchpads may remain here when they provide useful delivery provenance. Their conclusions must be reflected in the owning canonical page before the scratchpad is treated as complete. + +## Related + +- [[README|Documentation contract]] +- [[SITEMAP|Documentation sitemap]] +- [[plans/README|Documentation plans]]