This commit is contained in:
Jason Woltje
+2
-1
@@ -197,7 +197,7 @@ The initial structure pass defined the target structure without moving or rewrit
|
||||
- Treat `_old_structure/` as read-only migration quarantine. Do not add new content there.
|
||||
- Treat the current root-level legacy pages (`openapi-tess.yaml` and the task/mission documents) as migration backlog, not permission to create more root files. The former empty `QUICKSTART.md` placeholder now lives as `USER-GUIDE/getting-started/quickstart.md`; the verified SSO runbook lives under `ADMIN-GUIDE/security/`; historical evidence such as the P8-003 performance report belongs under `reports/qa/`.
|
||||
- Candidate destinations include `USER-GUIDE/getting-started/`, `ADMIN-GUIDE/security/`, `DEVELOPER-GUIDE/architecture/`, `API/`, `tasks/`, `plans/`, and `archive/`; classify each page before moving it.
|
||||
- Existing source code and tests still reference legacy paths such as `docs/fleet/` and `docs/federation/`. Update those references deliberately as part of the relevant migration slice; do not delete a referenced path blindly.
|
||||
- `docs/fleet/` is an executable documentation contract consumed by current source and tests; keep that complete book at its canonical path. Federation and other authority surfaces may also have live consumers. Update any such path only through an explicitly coordinated source/test and authority migration.
|
||||
- When a page is moved, update all repository links, source comments, tests, book indexes, and `SITEMAP.md` in the same logical change.
|
||||
- Preserve historical evidence in `reports/`, `tasks/`, `releases/`, or `archive/` instead of mixing it into current guides.
|
||||
- Remove the empty `docs/mosaic-stack/` boundary only after confirming no source, test, or documentation reference requires it.
|
||||
@@ -209,6 +209,7 @@ Classified migration is active and the audience books now contain verified curre
|
||||
|
||||
- The target directories listed above remain the placement contract; some planned chapters are not populated yet.
|
||||
- `docs/_old_structure/` remains available for migration evidence but is not current documentation or command authority.
|
||||
- `docs/fleet/`, `docs/native-kanban-sot/`, `docs/requirements/native-kanban-sot.md`, and the KBN-101 hold-site documents remain at their canonical paths because they are active executable or authority surfaces. Their placement cannot change through documentation-only cleanup.
|
||||
- Root control and API artifacts remain until their authority and destination decisions are approved.
|
||||
- `docs/SITEMAP.md` contains only resolvable current navigation plus a non-linked summary of authority-gated migration groups.
|
||||
- No external publishing platform is assumed. The canonical source remains this repository under `docs/`.
|
||||
|
||||
+17
-3
@@ -19,6 +19,20 @@
|
||||
- [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.
|
||||
|
||||
## Protected current authority and executable books
|
||||
|
||||
These paths remain canonical because current source/tests consume them or because the KBN authority process protects them. Relocation requires an explicitly coordinated authority and consumer migration, not documentation-only cleanup.
|
||||
|
||||
- [Fleet configuration management](fleet/README.md) — executable roster-v2 operator book, schema, examples, and north-star projections.
|
||||
- [Fleet local canary](guides/fleet-local-canary.md) — protected Fleet validation procedure referenced by the current developer hold-site guide.
|
||||
- [Native Kanban/SOT index](native-kanban-sot/INDEX.md) — active canonical KBN contract and workstream index.
|
||||
- [Native Kanban/SOT requirements](requirements/native-kanban-sot.md) — active ratified requirements surface.
|
||||
- [KBN-101 database role split](native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md) — active held database authority contract.
|
||||
- [Developer hold-site guide](guides/dev-guide.md) — protected current KBN-101 development boundary.
|
||||
- [Deployment hold-site guide](guides/deployment.md) — protected, non-operative PostgreSQL/deployment boundary.
|
||||
- [Tier-migration hold-site guide](guides/migrate-tier.md) — protected secure migration route and hold boundary.
|
||||
- [Federation setup hold site](federation/SETUP.md) — protected KBN-101 setup boundary; follow its explicit holds.
|
||||
|
||||
## User documentation
|
||||
|
||||
- [Quickstart](USER-GUIDE/getting-started/quickstart.md) — installed-CLI first-use route with local PGlite safety boundaries.
|
||||
@@ -71,9 +85,9 @@
|
||||
|
||||
The complete file-level backlog remains in the [documentation catalog](reports/documentation/2026-08-10-docs-catalog-audit.md). The groups below are intentionally not linked as current pages:
|
||||
|
||||
- **Fleet configuration:** quarantined pages have executable source/test consumers and require a coordinated path, authority, and test migration.
|
||||
- **Federation:** active-versus-historical workstream status and normative authority require maintainer/orchestrator confirmation.
|
||||
- **Native Kanban/KBN-101:** requirements, task state, reports, and held PostgreSQL procedures require product-owner and orchestrator decisions.
|
||||
- **Fleet configuration:** the executable book is restored at `docs/fleet/`; any future audience-book relocation requires coordinated source/test and authority migration.
|
||||
- **Federation:** the protected KBN-101 setup hold site remains canonical; disposition of the rest of the workstream requires maintainer/orchestrator confirmation.
|
||||
- **Native Kanban/KBN-101:** active SSOT, requirements, and hold-site documents remain canonical; task state and future placement require product-owner, Task-18, and orchestrator decisions.
|
||||
- **Tess:** mixed user, administrator, developer, migration, qualification, and API material requires audience splitting and a decision on active versus historical status.
|
||||
- **Gateway API:** the Tess-scoped OpenAPI artifact must not be renamed into the canonical full-gateway contract until scope, authentication, errors, schemas, and transport coverage are approved.
|
||||
- **Deployment and tier migration:** PostgreSQL, federated, bare-metal, Compose, Gateway/Web activation, and migration-runner procedures remain held under the repository safety policy.
|
||||
|
||||
+1
-1
@@ -129,7 +129,7 @@ systemctl --user restart mosaic-agent@<name>
|
||||
|
||||
Full recovery runbook and the three-layer #791 protection model (manifest
|
||||
ownership → pre-update snapshot/restore → regen): see
|
||||
[Upgrade Safety & Recovery](./upgrade-safety-and-recovery.md).
|
||||
[Upgrade Safety & Recovery](../ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md).
|
||||
|
||||
## Release Preflight
|
||||
|
||||
@@ -7,6 +7,8 @@ Use the canonical guide, API contract, source, and tests to determine current be
|
||||
## Documentation evidence
|
||||
|
||||
- [Documentation catalog and truth audit](documentation/2026-08-10-docs-catalog-audit.md) — migration inventory and static truth assessment.
|
||||
- [Fleet documentation IA closure](documentation/758-fleet-config-ia-closure.md) — active Fleet documentation acceptance evidence; the executable book remains at `docs/fleet/`.
|
||||
- [Fleet documentation deferrals](deferred/758-fleet-config-deferrals.md) — explicit holds and deferred live-action boundaries.
|
||||
- [Issue #756 documentation checklist](documentation/756-discord-plugin-checklist.md) — historical completion checklist for the official Discord plugin workstream.
|
||||
- [Framework consistency audit — 2026-02-17](documentation/AUDIT-2026-02-17-framework-consistency.md) — historical framework consistency and remediation snapshot.
|
||||
- [Compaction-refresh #830 checklist](compaction-refresh/830-documentation-checklist.md) — historical incomplete-at-snapshot documentation checklist.
|
||||
@@ -32,8 +34,7 @@ These reports preserve the review sequence for issue #751. Their GO verdicts app
|
||||
- [Initial independent NO-GO](native-kanban-sot/canon-initial-review-no-go.md) — original blocking review.
|
||||
- [Independent re-review GO](native-kanban-sot/canon-final-rereview-go.md) — follow-up closure review.
|
||||
- [Ultron final GO](native-kanban-sot/ultron-final-go.md) — historical final-gate record.
|
||||
|
||||
The KBN-101 security review remains migration-coupled to its requirements and held database workstream.
|
||||
- [KBN-101 security/architecture review](native-kanban-sot/kbn-101-contract-security-review-82ce325.md) — active review evidence coupled to the held KBN-101 authority surface.
|
||||
|
||||
## Retention rules
|
||||
|
||||
|
||||
@@ -92,6 +92,15 @@ Shared indexes, navigation, audit records, integration review, and final commits
|
||||
- [x] Archive the two unreferenced Matrix/MACP RFCs byte-identically as historical drafts, cross-referenced to the canonical unimplemented-Matrix boundary.
|
||||
- [x] Archive two unreferenced standalone designs byte-identically; retain the coupled #791 design and normative framework constitution in quarantine.
|
||||
- [x] Migrate three #751 Native Kanban review reports byte-identically to their already-referenced canonical evidence paths; retain KBN-101 and Fleet reports with gated workstreams.
|
||||
- [x] Reconcile PR #1210 with current `next`: restore the complete Fleet executable book, active Native Kanban/KBN SSOT, KBN-101 reports, and eight protected #1187 hold sites byte-exactly from provider base `216cd722`.
|
||||
|
||||
## PR #1210 integration reconciliation
|
||||
|
||||
CI pipeline 2405 proved that `docs/fleet/**` is an executable contract: Fleet tests and CLI projections fail when the book, north-star YAML/Markdown, example roster, or JSON schema is moved. Fred approved restoration and required the active KBN SSOT plus the eight #1187 hold-site documents to remain canonical. Scrappy supplied and will re-review the protected-path census.
|
||||
|
||||
All protected files were restored from `origin/next@216cd722`, not rewritten. The protected developer guide's Fleet-canary dependency was also restored; its sole stale upgrade-guide link was reconciled to the current administrator-guide destination. Scrappy corrected an initial provenance-pin instruction: `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` is provider-base blob `2bb6209909004b74490565d5def9956aba6d83ca`; the void `45e4…` pin belongs to a later unmerged KBN RED-branch preimage and is intentionally absent from PR #1210.
|
||||
|
||||
No documentation-only relocation of these surfaces is authorized. A future move requires explicit Fleet consumer migration or Fred/Task-18 KBN authority reconciliation.
|
||||
|
||||
## Initial findings
|
||||
|
||||
@@ -105,7 +114,7 @@ Shared indexes, navigation, audit records, integration review, and final commits
|
||||
- `docs/openapi-tess.yaml` parses as OpenAPI 3.1 with 17 paths, but remains a legacy root-level Tess-scoped contract rather than the full API SSOT.
|
||||
- The baseline `.gitignore` ignored `docs/reports/`, conflicting with the new documentation contract and lint-staged. The blanket rule is now removed so canonical evidence can be tracked normally.
|
||||
- The scaffold slice adds `USER-GUIDE/README.md`, `ADMIN-GUIDE/README.md`, `ADMIN-GUIDE/security/README.md`, `DEVELOPER-GUIDE/README.md`, `DEVELOPER-GUIDE/architecture/README.md`, and `API/README.md`; legacy pages remain unchanged.
|
||||
- `SITEMAP.md` now contains 45 resolvable current relative links and no stale legacy targets. Authority-gated Fleet, Federation, Kanban, Tess/API, and deployment groups are summarized without presenting quarantine paths as current navigation.
|
||||
- `SITEMAP.md` links the protected Fleet and KBN authority surfaces at their canonical paths. Remaining authority-gated Federation, Kanban task-state, Tess/API, and deployment groups are summarized without presenting quarantine paths as current navigation.
|
||||
- `docs/PERFORMANCE.md` had no live source/test dependency or internal links; it moved unchanged to `docs/reports/qa/p8-003-performance-optimization.md`. The admin index and current sitemap now classify it as historical evidence, not an operator runbook.
|
||||
- `PRD-TUI_Improvements.md` and `TASKS-TUI_Improvements.md` had no live source/test dependencies beyond their internal relative link; both moved unchanged to `docs/archive/tui/`, and `docs/archive/README.md` labels them historical.
|
||||
- The empty `docs/QUICKSTART.md` placeholder was replaced by `docs/USER-GUIDE/getting-started/quickstart.md`, based on verified installer, wizard, CLI, and runtime-safety behavior. The page explicitly excludes held PostgreSQL/source-checkout routes.
|
||||
@@ -130,11 +139,11 @@ Shared indexes, navigation, audit records, integration review, and final commits
|
||||
|
||||
## Risks and blockers
|
||||
|
||||
- `docs/PRD.md`, `docs/TASKS.md`, and `docs/MISSION-MANIFEST.md` retain 17 unresolved links that require maintainer/orchestrator authority. Source/tests still contain Fleet/Federation legacy paths that must move with those workstreams.
|
||||
- `docs/PRD.md`, `docs/TASKS.md`, and `docs/MISSION-MANIFEST.md` retain authority-owned links that require maintainer/orchestrator disposition. Fleet source/test consumers are satisfied by retaining the executable book at `docs/fleet/`; Federation relocation remains coupled.
|
||||
- Historical documents may contain commands or security claims that are unsafe if resurfaced as current guidance.
|
||||
- Truth audit is static unless a claim can be verified without starting held services or violating database/runtime safety rules.
|
||||
- `docs/TASKS.md` is single-writer orchestrator state and will not be edited by this task.
|
||||
- After safe archival cleanup, 125 quarantine files remain. Every remaining group is authority-, source/test-consumer-, safety-, or path-coupled; the Mos-gated compaction probes additionally hard-code their present repository-relative location and must not be moved or run independently.
|
||||
- After restoring active Fleet/KBN/#1187 surfaces and the Fleet-canary dependency, 65 quarantine files remain. Every remaining group is authority-, source/test-consumer-, safety-, or path-coupled; the Mos-gated compaction probes additionally hard-code their present repository-relative location and must not be moved or run independently.
|
||||
- The pre-existing `9a1cc63` commit removed `docs/GETTING_STARTED.md` and added the `.obsidian` ignore rule before this audit commit; that state is not attributed to this task.
|
||||
|
||||
## Verification log
|
||||
@@ -169,13 +178,14 @@ Shared indexes, navigation, audit records, integration review, and final commits
|
||||
| Lease-broker verification | PASS — safe static/test workflow is current; startup, recovery, mutation, service management, and cleanup remain held |
|
||||
| Optional egress RFC | PASS — proposal remains draft/non-operative; model and runtime-provider boundaries are separated and candidates are not integrated |
|
||||
| Web dashboard guide | PASS — current routes, views, chat persistence, and absent project/task creation controls are documented from source/tests |
|
||||
| Sitemap refresh | PASS — 45/45 relative links resolve; legacy link farm replaced by a non-linked authority-gated backlog summary |
|
||||
| Canonical link audit | BLOCKED ONLY BY CONTROL DOCS — 329 links scanned, 17 unresolved; all are in maintainer/orchestrator-owned `PRD.md`, `TASKS.md`, or `MISSION-MANIFEST.md` |
|
||||
| Sitemap refresh | PASS — 54/54 relative links resolve after PR #1210 protected-surface reconciliation |
|
||||
| Canonical link audit | BLOCKED ONLY BY CONTROL DOCS — 443 links scanned, 10 unresolved; all are in orchestrator-owned `TASKS.md` or `MISSION-MANIFEST.md` |
|
||||
| Navigation review | PASS AFTER REMEDIATION — plan/scratchpad indexes added, current quarantine links removed, lifecycle/status copy aligned |
|
||||
| Safety review | PASS AFTER REMEDIATION — Discord pages no longer claim unproven ordinary persistence or restart continuity |
|
||||
| Stop-condition review | AUTONOMOUS COMPLETE — historical mission bundle migrated; remaining groups require authority or coupled source/test work |
|
||||
| Repository pre-push checks | PASS — `pnpm preflight`, `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` with `DATABASE_URL` unset |
|
||||
| Root test suite | BLOCKED/FAILED SAFELY — Fleet tests require missing `docs/fleet/`; gateway isolation test inherited a daemon DSN and failed authentication before cleanup DML. Not retried. |
|
||||
| Root test suite | PR #1210 CI pipeline 2405 failed because the migration removed executable `docs/fleet/` contracts; provider-base restoration is the required amendment. |
|
||||
| Fleet contract restoration | PASS LOCALLY — focused north-star, Fleet documentation, and roster-schema suites pass 77/77 after exact provider-base restoration. |
|
||||
| Focused final tests | PASS — types 71, Discord 44, web 33, focused gateway 32, and lease-broker/mutator acceptance 57; `DATABASE_URL` unset, no services started |
|
||||
| Historical mission archive | PASS — 11 completed/superseded records moved under `archive/missions/`, indexed, and two broken sibling links repaired |
|
||||
| Historical planning archive | PASS — five consolidation records plus ten legacy plans/stubs moved byte-identically under `archive/planning/`; hashes and zero-consumer scans verified |
|
||||
|
||||
Reference in New Issue
Block a user