mosaicstack/stack
21
0
Fork 1
Code Issues 338 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

chore: consolidate new foundation and archive v1 (#1495)

Browse Source
This commit is contained in:
jason.woltje
2026-09-07 12:32:57 -05:00
parent 9a5fbdbda7 5d27700026
commit 127a54fdff
3511 changed files with 727899 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
v1/docs/reports/README.md
+56
View File
@@ -0,0 +1,56 @@
---
kind: guide
status: active
---
# Documentation Reports
> **Status:** Current evidence index. Reports record reviews, tests, audits, and deferred findings; they are not requirements or operational instructions by themselves.
Use the canonical guide, API contract, source, and tests to determine current behavior. A report retains the scope and verdict of its original review unless a later report explicitly supersedes it.
## 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.
## Code-review evidence
- [Issue #756 independent code review](code-review/756-code-review.md) — historical exact-scope review of the official Discord plugin workstream.
- [Gateway security-hardening code review — 2026-03-13](code-review/gateway-security-20260313.md) — historical no-blocker review snapshot.
## Security evidence
- [Issue #756 security review](security/756-security-review.md) — historical security review of Discord ingress, authorization, routing, and residual risks.
## QA evidence
- [P8-003 performance optimization report](qa/p8-003-performance-optimization.md) — historical implementation evidence; not a current SLO or production benchmark.
- [Gateway security-hardening QA report — 2026-03-13](qa/gateway-security-20260313.md) — historical test report with its original live-smoke-test limitation.
## Native Kanban/SOT evidence
These reports preserve the review sequence for issue #751. Their GO verdicts apply only to the reviewed historical scope and do not decide current Kanban authority or authorize held KBN-101 database work.
- [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.
- [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
- Preserve report wording and verdicts when migrating historical evidence.
- Keep the reviewed commit, issue, scope, and date visible when present.
- Do not treat an old approval as approval of later code.
- Link each tracked report from this index or an explicitly scoped child index.
- Put current operator procedures in the administrator guide, not in reports.
## Related
- [[README|Documentation contract]]
- [[SITEMAP|Documentation sitemap]]
- [[archive/README|Documentation archive]]
v1/docs/reports/code-review/756-code-review.md
+32
View File
@@ -0,0 +1,32 @@
---
kind: record
status: active
---
# Independent Code Review — #756 Official Discord Channel Plugin
**Verdict: APPROVE**
## Scope reviewed
Complete current uncommitted #756 delta: multi-binding trusted agent selection, privileged ingress-route validation, attachment validation/persistence/resume, egress route lifecycle and idempotency, concurrent gateway stream state, Discord lifecycle/thread/rate behavior, compatibility ingress, and tests.
## Review result
No blocking or change-request finding remains.
- **Trusted multi-agent routing:** each binding requires a provisioned `agentConfigId`; the gateway resolves that config server-side, verifies its logical-agent name, and never accepts a Discord-controlled agent selection or applies generic routing to Discord ingress.
- **Auth and route integrity:** allowlist, pairing, role, and canonical logical-agent/channel-or-thread conversation-route validation occur before gateway processing. Privileged approval/stop paths use the same binding and route validation.
- **Attachments:** ingress rejects malformed, over-bounded, credential-bearing, fragment-bearing, or query-bearing URLs. Valid attachment metadata, including `sizeBytes`, persists and is reconstructed into resume history as explicitly untrusted context.
- **Discord reliability:** the adapter supports degraded Socket.IO reconnect, parent/thread routing semantics, bounded pre-side-effect ingress rates, and terminal response-route cleanup. Egress validates route/message alignment, sends deterministic nonces, distinguishes permanent from transient errors, and uses bounded retries.
- **Concurrent state:** per-client/conversation keys isolate listener, redaction, tool, and stream state for simultaneous threads sharing a Discord socket; disconnect cleanup covers all associated conversations.
- **Harness neutrality:** contracts retain logical-agent/channel data only; no harness/provider identity leaks into adapter routes or message boundaries.
## Verification performed
- `git diff --check` — passed.
- `pnpm --filter @mosaicstack/discord-plugin typecheck` — passed.
- `pnpm --filter @mosaicstack/discord-plugin lint` — passed.
- `pnpm --filter @mosaicstack/discord-plugin test` — passed: 44 tests; coverage 92.18% statements/lines, 86.55% branches, 100% functions (all ≥85% threshold).
- `pnpm --filter @mosaicstack/gateway typecheck` — passed.
- `cd apps/gateway && pnpm exec vitest run src/plugin/discord-ingress.security.spec.ts src/chat/chat.gateway-redaction.spec.ts src/__tests__/integration/tess-cross-surface.integration.test.ts` — passed: 32 tests.
v1/docs/reports/code-review/gateway-security-20260313.md
+28
View File
@@ -0,0 +1,28 @@
---
kind: record
status: active
---
# Code Review Report — Gateway Security Hardening
## Scope Reviewed
- `apps/gateway/src/chat/chat.gateway-auth.ts`
- `apps/gateway/src/chat/chat.gateway.ts`
- `apps/gateway/src/conversations/conversations.dto.ts`
- `apps/gateway/src/chat/__tests__/chat-security.test.ts`
## Findings
- No blocker findings in the final changed surface.
## Review Summary
- Correctness: socket auth helper now returns Better Auth session data unchanged, and gateway disconnects clients whose handshake does not narrow to a valid session payload
- Security: conversation role validation now rejects `system`; conversation content ceiling is 32k; chat request ceiling remains 10k
- Testing: targeted auth, ownership, and DTO regression tests pass
- Quality: `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` all pass after the final edits
## Residual Risk
- `chat.gateway.ts` uses local narrowing around an `unknown` session result because the requested helper contract intentionally returns `unknown`.
v1/docs/reports/compaction-refresh/830-documentation-checklist.md
+39
View File
@@ -0,0 +1,39 @@
---
kind: record
status: active
---
# #830 Documentation Completion Checklist
## Required artifacts
- [x] `docs/PRD.md` contains the M1 compaction-refresh trust-lifecycle requirements and acceptance criteria.
- [x] Operator behavior and recovery are documented in `docs/guides/lease-broker-operations.md`.
- [x] Developer architecture and protocol behavior are documented in `docs/architecture/compaction-revocation.md`, `lease-broker-protocol.md`, and `mutator-class-gate.md`.
- [x] Security boundaries and residuals are documented in `docs/architecture/lease-broker-security.md` and `compaction-revocation.md`.
- [x] `docs/SITEMAP.md` links the new architecture page.
- [x] User-guide changes are not applicable: observers are mandatory internal runtime controls with no end-user workflow.
- [x] OpenAPI/endpoint changes are not applicable: the broker remains an internal Unix-socket protocol, not a public HTTP API.
## Contract coverage
- [x] Claude and Claudex lifecycle signals, matchers, commands, and fail-closed behavior are documented.
- [x] Pi pre-/post-compaction signals and session replacement reasons are documented.
- [x] Private generation-file ownership, monotonic update, same-PID replacement, and failure fencing are documented.
- [x] `revoke_lease` input purpose, broker response state, and denial behavior are documented.
- [x] T12b/T30 explicitly names the bounded residual stale window and reports within-TTL **ALLOWED** / after-TTL **DENIED**.
- [x] Documentation explicitly disclaims a within-window mutator-action bound.
- [x] T-A, T-C, same-principal, and protected-branch boundaries are retained.
## Structure and review
- [x] New architecture content is under `docs/architecture/`.
- [x] This report is under `docs/reports/compaction-refresh/`.
- [x] Session evidence is under `docs/scratchpads/`.
- [x] Documentation changes are in the same logical change set as code and tests.
- [ ] Independent exact-head code and Opus security reviews pending coordinator sequencing after the deterministic-main rebase gate.
## Publishing
- [x] Canonical documentation remains in-repository.
- [x] No external publishing target is required for this internal M1 control.
v1/docs/reports/deferred/758-fleet-config-deferrals.md
+59
View File
@@ -0,0 +1,59 @@
---
kind: record
status: active
---
# FCM-M5-001 Fleet Documentation Deferrals and Holds
**Issue:** #758 · **Branch:** `docs/758-fleet-config-operator-docs`
These are accepted existing DAG boundaries, not omissions silently claimed as delivered.
## FCM-M3-002 hold
- Boot/reboot preservation for roster members persisted stopped or disabled.
- Current installation may enable all agent units, while the launcher projection does not yet carry
`lifecycle.enabled` or `desired_state`; documentation therefore does not claim lifecycle-safe reboot.
- Heartbeat/liveness integration into roster-v2 `status`, `doctor`, and `verify`; current observations
cover systemd active state, tmux sessions, holder ownership, and unmanaged sessions only.
## FCM-M4-002 hold
- Executable v1-to-v2 cutover, reversible canary, and rollback.
- Stale-projection/orphan migration classification and current-host managed/unmanaged fixture coverage.
- Any live migration, lifecycle, systemd/tmux/session, or rollback action.
M5 docs describe prerequisites and the preview boundary only. A ready preview is not migration or rollback evidence.
## Explicit validate-operation gap
- `FCM-REQ-03` requires a documented programmatic `mosaic fleet validate` operation.
- The current CLI does not expose that operation. Existing mutation/reconcile validation and the
documentation example test are not a replacement for the missing command.
- FCM-M5-001 documents this implementation gap without inventing syntax, JSON, exit behavior, or an
owning implementation card. Parent #758 must remain open until the requirement is implemented and
evidenced or the PRD/DAG is explicitly revised through the authoritative process.
## FCM-M5-002 hold
- Deterministic source-versus-installed asset revision detection and safe refresh implementation.
- Rolling local canary, independent validator certificate, final release evidence, merge-gate approval, and parent #758 closure.
`operations/upgrade-assets.md` is therefore a fail-closed hold, not an invented procedure.
## Compatibility interpretation
The M0 cross-cutting row requiring every retained/migrated artifact to validate through the executable contract is satisfied by each artifact's declared executable disposition, not by forcing versioned v1 fixtures through the v2 parser:
- retained examples are explicit `version: 1` fixtures validated by the production v1 parser;
- canonical profiles validate through the shared baseline plus `roles.local` resolver;
- the service preset validates through its production service-policy reader;
- migration candidates validate through the production v2 compiler and shared semantic resolver.
The executable disposition inventory rejects undeclared additions/removals and prevents silent legacy drift.
## Repository-wide documentation structure
The accepted #758 IA is the domain book under `docs/fleet/`. Creating global `USER-GUIDE`, `ADMIN-GUIDE`, or `DEVELOPER-GUIDE` books and cleaning unrelated pre-existing `docs/` root files are outside this bounded card. The repository sitemap links the fleet book. No HTTP/API/auth contract changed, so OpenAPI and endpoint-index updates are not applicable.
Canonical documentation remains in-repository; no external publishing or generated publishing output is in scope. Parent issue #758 stays open through M5.
v1/docs/reports/documentation/2026-08-10-docs-catalog-audit.md
+532
View File
@@ -0,0 +1,532 @@
---
kind: record
status: active
---
# Mosaic Stack Documentation Catalog and Truth Audit
> **Status:** First-pass static audit — 2026-08-10
> **Task:** `DOCS-IA-002` / `TASKS:DOCS-IA-002`
> **Scope:** Catalog and evidence triage only. No existing documentation was moved, deleted, or rewritten by this audit. The baseline catalog snapshot predates the DOCS-IA-002 plan, scratchpad, and report; those artifacts are listed separately and excluded from baseline counts to avoid self-referential metrics.
## Executive summary
- **283 baseline documentation artifacts** are cataloged: 11 current root files, 269 files under `docs/_old_structure/`, two prior plans, and one prior scratchpad. The three DOCS-IA-002 artifacts are listed separately.
- At the audit baseline, `.gitignore` ignored `docs/reports/`, conflicting with the documentation contract. The migration subsequently removed that blanket rule so canonical reports can be tracked normally.
- The current navigation surface contains **97 internal links, 83 legacy/unresolved links**, plus 2 intentional future blueprint wikilinks in the new `docs/README.md`.
- The historical archive contains **122 links, 12 unresolved links**. These do not represent current navigation, but they matter if pages are promoted again.
- The current broken-link problem is concentrated in `docs/SITEMAP.md` (66), `docs/MISSION-MANIFEST.md` (7), `docs/TASKS.md` (7), and `docs/PRD.md` (3).
- Static code inspection found **31 source/test/framework files** that still reference legacy documentation roots such as `docs/fleet/`, `docs/federation/`, or `docs/architecture/`. These paths cannot be removed until their consumers are migrated or deliberately updated.
- The workspace currently contains **26 package manifests**, 12 root scripts, and 110 package scripts. This is sufficient evidence to validate package/path claims statically, but not to prove deployed behavior.
### High-confidence findings
1. `docs/QUICKSTART.md` is empty and cannot serve as a quickstart.
2. `docs/SITEMAP.md` is structurally stale after the archive move; it is not a reliable current navigation map.
3. `docs/PRD-TUI_Improvements.md` and `docs/TASKS-TUI_Improvements.md` describe a missing `packages/cli` and missing historical worktree. Current TUI code is under `packages/mosaic`.
4. `docs/SSO-PROVIDERS.md` has a verified provider environment-variable core, but its `NEXT_PUBLIC_*_ENABLED` web-flow claim does not match current dynamic provider discovery through `/api/sso/providers`; Keycloak SAML fallback is also absent from the guide.
5. `docs/openapi-tess.yaml` parses as OpenAPI 3.1.0 with 17 paths and is useful as a Tess-scoped contract, but it is in a legacy root location and is not a complete gateway API contract.
6. `docs/PRD.md` is explicitly draft and normative. Its acceptance criteria must not be presented as shipped capabilities; several of its path references are broken because supporting artifacts are archived.
## Audit status model
| Status | Meaning |
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `verified` | Directly supported by current source, configuration, tests, or a reproducible static command. |
| `partially-verified` | Some claims are supported, but the page includes unverified, time-sensitive, or environment-dependent claims. |
| `contradicted` | Current repository evidence conflicts with a material claim or referenced path. |
| `stale` | Formerly meaningful, but no longer aligned with current paths or tracked state. |
| `historical` | Retained record of past state; not current operator or developer guidance. |
| `draft` | Normative proposal or requirement; not a statement of shipped behavior. |
| `unverified` | No sufficient evidence was collected in this first pass. |
| `incomplete` | Empty or structurally insufficient for its stated role. |
A document can have two labels, such as `partially-verified/contradicted`, when one section is supported and another section is materially wrong. Archived files are labeled `historical/unverified`: archival status is known, but historical claim accuracy has not been proven.
## Current-document truth triage
| Document | Preliminary status | Role | Evidence and truth notes | Candidate destination |
| -------------------------------- | ------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `docs/MISSION-MANIFEST.md` | `stale` | MVP mission rollup | Last updated 2026-07-14; seven current-path links are broken and its active-workstream claims were not revalidated. | `tasks/ or archive/missions/` |
| `docs/PERFORMANCE.md` | `partially-verified` | historical performance report | All seven named implementation files exist and key configuration/index markers are present; target metrics and production impact are not proven by this static audit. | `reports/qa/` |
| `docs/PRD-TUI_Improvements.md` | `contradicted/stale` | branch-specific TUI PRD | It names missing `packages/cli` and an absent historical worktree; current TUI code is under `packages/mosaic`. | `archive/ or plans/` |
| `docs/PRD.md` | `draft` | normative product requirements | Explicitly marked draft; three current links point to archived paths. Requirements express intent and acceptance criteria, not shipped behavior. | `PRD.md; split supporting contracts later` |
| `docs/QUICKSTART.md` | `incomplete` | quickstart placeholder | Empty file: 0 bytes and 0 lines. | `USER-GUIDE/getting-started/quickstart.md` |
| `docs/README.md` | `current/verified` | documentation structure contract | Structure, placement, source-of-truth, migration, and link rules were checked in this task; two future blueprint wikilinks are intentionally unresolved. | `README.md` |
| `docs/SITEMAP.md` | `stale/contradicted` | navigation index | 66 current links resolve only against removed pre-archive paths; it must be regenerated after the canonical scaffold and migration map are approved. | `SITEMAP.md` |
| `docs/SSO-PROVIDERS.md` | `partially-verified/contradicted` | SSO operator guide | Required provider environment names and partial-config behavior match `packages/auth`; documented `NEXT_PUBLIC_*_ENABLED` flags are not read by current web code, which discovers providers through `/api/sso/providers`. | `ADMIN-GUIDE/security/sso-providers.md` |
| `docs/TASKS-TUI_Improvements.md` | `stale/historical` | branch-specific TUI task ledger | References an absent worktree and `packages/cli`; Wave 1/2 status and commit claims were not independently reverified against current code. | `tasks/ or archive/` |
| `docs/TASKS.md` | `active/stale-links` | MVP orchestrator rollup | Active rollup with seven broken workstream links. Status is orchestrator-owned and was not changed by this audit. | `TASKS.md until orchestrator archives it` |
| `docs/openapi-tess.yaml` | `partially-verified/legacy-location` | Tess-scoped OpenAPI contract | PyYAML parses OpenAPI 3.1.0 with 17 paths. It covers Tess interaction, Mos coordination, and memory routes, but is not at `docs/API/` and is not a complete gateway contract. | `API/ (scoped Tess contract or consolidated OPENAPI.yaml)` |
### DOCS-IA-002 audit artifacts
- `docs/plans/2026-08-10-docs-catalog-audit.md` — approved audit method and evidence statuses.
- `docs/scratchpads/DOCS-IA-002-catalog-audit.md` — active audit progress and command log.
- `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` — this human-readable report; it required force-add at the audit baseline, before the blanket report ignore rule was removed.
- These artifacts are current working/evidence documentation and must not be mistaken for product requirements or shipped behavior.
## Archived catalog by category
All files below were moved unchanged by commit `cd4409a` on 2026-08-10. Category counts are definitive for this checkout; truth claims remain unverified until a page is selected for migration.
| Archived category | Files | Bytes | Preliminary destination | Default disposition |
| --------------------- | ----: | ------: | ----------------------------------------------------------------- | -------------------------------------------------- |
| `architecture/` | 7 | 84,248 | `DEVELOPER-GUIDE/architecture/` | `historical/unverified`; classify before promotion |
| `archive/` | 11 | 108,472 | `archive/` | `historical/unverified`; classify before promotion |
| `audits/` | 1 | 5,037 | `reports/documentation/ or reports/security/` | `historical/unverified`; classify before promotion |
| `briefs/` | 1 | 10,589 | `plans/ or archive/` | `historical/unverified`; classify before promotion |
| `compaction-refresh/` | 2 | 21,484 | `DEVELOPER-GUIDE/architecture/ or reports/qa/` | `historical/unverified`; classify before promotion |
| `deploy/` | 2 | 10,881 | `ADMIN-GUIDE/deployment/` | `historical/unverified`; classify before promotion |
| `design/` | 4 | 45,773 | `DEVELOPER-GUIDE/architecture/decisions/ or plans/` | `historical/unverified`; classify before promotion |
| `federation/` | 6 | 95,408 | `ADMIN-GUIDE/deployment/ and DEVELOPER-GUIDE/architecture/` | `historical/unverified`; classify before promotion |
| `fleet/` | 38 | 214,726 | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` | `historical/unverified`; classify before promotion |
| `guides/` | 9 | 94,257 | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` | `historical/unverified`; classify before promotion |
| `mission-control/` | 4 | 33,605 | `tasks/ or archive/` | `historical/unverified`; classify before promotion |
| `native-kanban-sot/` | 13 | 659,105 | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` | `historical/unverified`; classify before promotion |
| `plans/` | 12 | 298,514 | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` | `historical/unverified`; classify before promotion |
| `remediation/` | 8 | 218,485 | `reports/deferred/ or tasks/` | `historical/unverified`; classify before promotion |
| `reports/` | 12 | 79,398 | `reports/<category>/` | `historical/unverified`; classify before promotion |
| `requirements/` | 1 | 27,315 | `PRD.md or DEVELOPER-GUIDE/architecture/requirements/` | `historical/unverified`; classify before promotion |
| `reviews/` | 1 | 51,000 | `reports/code-review/` | `historical/unverified`; classify before promotion |
| `rfcs/` | 2 | 114,255 | `DEVELOPER-GUIDE/architecture/rfcs/` | `historical/unverified`; classify before promotion |
| `scratchpads/` | 111 | 638,974 | `archive/ or tasks/ after retention review` | `historical/unverified`; classify before promotion |
| `tasks/` | 4 | 20,803 | `tasks/` | `historical/unverified`; classify before promotion |
| `tess/` | 20 | 645,134 | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` | `historical/unverified`; classify before promotion |
### Category interpretation
- `architecture/`, `design/`, `requirements/`, and `rfcs/` are likely developer architecture material, but each page must be checked for supersession, normative authority, and code alignment.
- `fleet/`, `federation/`, and `tess/` are mixed audiences. They must be split across user, admin, developer, API, reports, and task destinations rather than moved as whole directories.
- `guides/` contains mixed audience material and cannot be mapped by directory name alone.
- `scratchpads/`, `remediation/`, `reports/`, `reviews/`, and `tasks/` are evidence/workflow artifacts. They should not be promoted into current guides without extracting and re-verifying the current facts.
- `archive/` is already historical by intent and should remain separate from the new migration target unless a specific page is needed for provenance.
## Baseline file-level catalog
The following table assigns every file in the baseline snapshot a preliminary status, role, evidence posture, and candidate destination. The DOCS-IA-002 plan, scratchpad, and report are listed in the audit-artifacts section above. These are triage labels, not final migration approvals.
| Path | Title | Status | Role | Evidence posture | Candidate destination |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `docs/MISSION-MANIFEST.md` | Mission Manifest — MVP | `stale` | MVP mission rollup | Last updated 2026-07-14; seven current-path links are broken and its active-workstream claims were not revalidated. | `tasks/ or archive/missions/` |
| `docs/PERFORMANCE.md` | Performance Optimization — P8-003 | `partially-verified` | historical performance report | All seven named implementation files exist and key configuration/index markers are present; target metrics and production impact are not proven by this static audit. | `reports/qa/` |
| `docs/PRD-TUI_Improvements.md` | PRD: TUI Improvements — Phase 7 | `contradicted/stale` | branch-specific TUI PRD | It names missing `packages/cli` and an absent historical worktree; current TUI code is under `packages/mosaic`. | `archive/ or plans/` |
| `docs/PRD.md` | PRD: Mosaic Stack v0.1.0 | `draft` | normative product requirements | Explicitly marked draft; three current links point to archived paths. Requirements express intent and acceptance criteria, not shipped behavior. | `PRD.md; split supporting contracts later` |
| `docs/QUICKSTART.md` | (no title) | `incomplete` | quickstart placeholder | Empty file: 0 bytes and 0 lines. | `USER-GUIDE/getting-started/quickstart.md` |
| `docs/README.md` | Mosaic Stack Documentation | `current/verified` | documentation structure contract | Structure, placement, source-of-truth, migration, and link rules were checked in this task; two future blueprint wikilinks are intentionally unresolved. | `README.md` |
| `docs/SITEMAP.md` | Documentation Sitemap | `stale/contradicted` | navigation index | 66 current links resolve only against removed pre-archive paths; it must be regenerated after the canonical scaffold and migration map are approved. | `SITEMAP.md` |
| `docs/SSO-PROVIDERS.md` | SSO Providers | `partially-verified/contradicted` | SSO operator guide | Required provider environment names and partial-config behavior match `packages/auth`; documented `NEXT_PUBLIC_*_ENABLED` flags are not read by current web code, which discovers providers through `/api/sso/providers`. | `ADMIN-GUIDE/security/sso-providers.md` |
| `docs/TASKS-TUI_Improvements.md` | Tasks: TUI Improvements | `stale/historical` | branch-specific TUI task ledger | References an absent worktree and `packages/cli`; Wave 1/2 status and commit claims were not independently reverified against current code. | `tasks/ or archive/` |
| `docs/TASKS.md` | Tasks — MVP (Top-Level Rollup) | `active/stale-links` | MVP orchestrator rollup | Active rollup with seven broken workstream links. Status is orchestrator-owned and was not changed by this audit. | `TASKS.md until orchestrator archives it` |
| `docs/_old_structure/architecture/ADR-MOS-EGRESS-GATEWAYS.md` | ADR: Optional AI egress gateways for runtime-neutral Mos | `historical/unverified` | archived architecture | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/architecture/channel-protocol.md` | Channel Protocol Architecture | `historical/unverified` | archived architecture | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/architecture/compaction-revocation.md` | Compaction observer revocation and runtime generations | `historical/unverified` | archived architecture | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/architecture/lease-broker-protocol.md` | Authenticated external lease broker protocol | `historical/unverified` | archived architecture | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/architecture/lease-broker-security.md` | WI-1 lease broker security notes | `historical/unverified` | archived architecture | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/architecture/mos-runtime-portability-m1.md` | Mos Runtime Portability M1 — Logical Identity and Fencing | `historical/unverified` | archived architecture | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/architecture/mutator-class-gate.md` | Whole mutator-class lease gate | `historical/unverified` | archived architecture | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md` | Mission Manifest — CLI Unification & E2E First-Run | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/cli-unification-20260404/TASKS.md` | Tasks — CLI Unification & E2E First-Run | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/harness-20260321/MISSION-MANIFEST.md` | Mission Manifest — Harness Foundation | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/harness-20260321/PRD.md` | PRD: Harness Foundation — Phase 9 | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md` | Mission Manifest — Install UX Hardening | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/install-ux-hardening-20260405/TASKS.md` | Tasks — Install UX Hardening | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/install-ux-v2-20260405/MISSION-MANIFEST.md` | Mission Manifest — Install UX v2 | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/install-ux-v2-20260405/TASKS.md` | Tasks — Install UX v2 | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/install-ux-v2-20260405/iuv-m03-design.md` | IUV-M03 Design: Provider-first intelligent flow + drill-down main menu | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/install-ux-v2-20260405/scratchpad.md` | Install UX v2 — Orchestrator Scratchpad | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/archive/missions/storage-abstraction/TASKS.md` | Tasks — Storage Abstraction Retrofit | `historical/unverified` | archived archive | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/` |
| `docs/_old_structure/audits/AUDIT-2026-02-17-framework-consistency.md` | Mosaic Framework Consistency Audit | `historical/unverified` | archived audits | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/documentation/ or reports/security/` |
| `docs/_old_structure/briefs/monorepo-consolidation.md` | Brief: Monorepo Consolidation — mosaic/stack → mosaic/mosaic-stack | `historical/unverified` | archived briefs | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or archive/` |
| `docs/_old_structure/compaction-refresh/probes/p5_receipt_replay.py` | #!/usr/bin/env python3 | `historical/unverified` | archived compaction-refresh | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/ or reports/qa/` |
| `docs/_old_structure/compaction-refresh/probes/p6_constrained_recovery.py` | #!/usr/bin/env python3 | `historical/unverified` | archived compaction-refresh | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/ or reports/qa/` |
| `docs/_old_structure/deploy/portainer/README.md` | deploy/portainer/ | `historical/unverified` | archived deploy | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/` |
| `docs/_old_structure/deploy/portainer/federated-test.stack.yml` | deploy/portainer/federated-test.stack.yml | `historical/unverified` | archived deploy | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/` |
| `docs/_old_structure/design/791-upgrade-config-protection.md` | Design — #791: Framework upgrades must not destroy operator-owned config under `~/.config/mosaic` | `historical/unverified` | archived design | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/decisions/ or plans/` |
| `docs/_old_structure/design/framework-constitution/ALPHA-DOD.md` | Constitution Alpha — Definition-of-Done checklist + release notes | `historical/unverified` | archived design | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/decisions/ or plans/` |
| `docs/_old_structure/design/prerelease-next-dist-tag-pipeline.md` | npm `@next` prerelease lane | `historical/unverified` | archived design | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/decisions/ or plans/` |
| `docs/_old_structure/design/storage-abstraction-middleware.md` | Storage & Queue Abstraction — Middleware Architecture | `historical/unverified` | archived design | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/decisions/ or plans/` |
| `docs/_old_structure/federation/ADMIN-CLI.md` | Mosaic Federation — Admin CLI Reference | `historical/unverified` | archived federation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/federation/MILESTONES.md` | Mosaic Stack — Federation Implementation Milestones | `historical/unverified` | archived federation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/federation/MISSION-MANIFEST.md` | Mission Manifest — Federation v1 | `historical/unverified` | archived federation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/federation/PRD.md` | Mosaic Stack — Federation PRD | `historical/unverified` | archived federation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/federation/SETUP.md` | Federated Tier Setup Guide | `historical/unverified` | archived federation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/federation/TASKS.md` | Tasks — Federation v1 | `historical/unverified` | archived federation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/deployment/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md` | Fleet Configuration Management — Documentation IA Acceptance Checklist | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/FLEET-LAUNCH.md` | Fleet Launch Runbook | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` | Fleet Configuration Management — Legacy Example, Profile, and Service Disposition Inventory | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/NORTH_STAR.md` | Mosaic Fleet — NORTH STAR | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/NORTH_STAR.yaml` | Mosaic Fleet — NORTH_STAR (machine-readable source of truth) | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/PRD-fleet-suite.md` | PRD — Mosaic Fleet Suite (init, configure, operate) | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/PRD.md` | PRD — Fleet Phase 2: Operator Observability | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/README.md` | Fleet Configuration Management | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/TASKS.md` | Tasks — W-FLEET (Fleet) Phase 2: Observability | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/backlog-conventions.md` | Fleet Backlog Conventions | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/concepts/desired-vs-observed-state.md` | Desired, Derived, and Observed Fleet State | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/concepts/generated-env-launch-chain.md` | Generated Environment Launch Chain | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/concepts/identity-class-runtime.md` | Fleet Identity, Class, and Runtime | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/concepts/role-authority-and-leases.md` | Fleet Role Authority and Leases | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/examples/roster-v2.yaml` | (no title) | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/f4-matrix-connector.md` | F4 — Orchestrator chat connector + Matrix (local homeserver) | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/how-to/configure-tess-interaction.md` | Configure an Interaction Instance | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/how-to/configure-ultron-validator.md` | Configure a Validator Instance | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/how-to/create-update-delete-agent.md` | Create, Inspect, Update, and Delete a Local Fleet Agent | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/how-to/customize-roles.md` | Customize Fleet Roles | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/how-to/start-stop-restart.md` | Safely Reconcile and Control a Local Fleet Agent | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/migration/example-profile-disposition.md` | Executable Fleet Example, Profile, and Service-Preset Dispositions | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/migration/legacy-class-aliases.md` | Legacy Fleet Class Aliases | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/migration/v1-to-v2.md` | Previewing a Fleet Roster v1-to-v2 Migration | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/north-star.md` | Mosaic Fleet — North Star | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/operations/backup-restore.md` | Fleet Configuration Backup and Restore Boundary | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/operations/env-quarantine.md` | Environment Quarantine Operations | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/operations/reconcile-and-recover.md` | Reconcile and Recover a Local Fleet | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/operations/systemd-tmux-troubleshooting.md` | Systemd and tmux Troubleshooting | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/operations/upgrade-assets.md` | Upgrade and Installed-Asset Drift | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/agent-mutations.md` | Local Fleet Agent Mutations | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/cli.md` | Fleet Control-Plane CLI | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/generated-env-boundary.md` | Fleet Generated Environment Boundary | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/lifecycle-transitions.md` | Local Fleet Lifecycle Transitions | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/role-classes.md` | Fleet Role Classes and Authority | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/roster-v2-fields.md` | Fleet Roster v2 Structural Contract | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/roster-v2.schema.json` | (no title) | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/fleet/reference/status-and-drift.md` | Local Fleet Status and Drift | `historical/unverified` | archived fleet | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `ADMIN-GUIDE/operations/ and DEVELOPER-GUIDE/architecture/` |
| `docs/_old_structure/guides/admin-guide.md` | Mosaic Stack — Admin Guide | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/deployment.md` | Deployment Guide | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/dev-guide.md` | Mosaic Stack — Developer Guide | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/fleet-local-canary.md` | Local Fleet Canary | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/lease-broker-operations.md` | Lease broker operations | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/migrate-tier.md` | Migrating to the Federated Tier | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/mos-connector-lease-operations.md` | Mos Connector Lease Operations — M1 | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/upgrade-safety-and-recovery.md` | Upgrade Safety & Recovery | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/guides/user-guide.md` | Mosaic Stack — User Guide | `historical/unverified` | archived guides | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, or DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/mission-control/BOARD.md` | Mission Control Plane — Feature Board | `historical/unverified` | archived mission-control | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/ or archive/` |
| `docs/_old_structure/mission-control/MISSION-MANIFEST.md` | Mission Manifest — Mosaic Mission Control Plane | `historical/unverified` | archived mission-control | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/ or archive/` |
| `docs/_old_structure/mission-control/PRD.md` | PRD: Mosaic Mission Control Plane | `historical/unverified` | archived mission-control | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/ or archive/` |
| `docs/_old_structure/mission-control/TASKS.md` | Tasks — Mosaic Mission Control Plane | `historical/unverified` | archived mission-control | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/ or archive/` |
| `docs/_old_structure/native-kanban-sot/DOCUMENTATION-CHECKLIST.md` | Documentation Completion Checklist — Native Kanban/SOT Canon | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/INDEX.md` | Native Kanban/SOT Canon | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` | KBN-010 — Threat, Authorization, and Constraint-Impact Gate | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` | KBN-101 — Database Runtime/Migration Role Split | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/KBN-101-ENVELOPE-A.md` | KBN-101 — B1/B2 Envelope A (v6, FINAL) — Declarative Sink-RBAC + Per-Role Credential/Connection-Selection + RLS Write-Source (INSERT tenant-bound, single-compound-or-RESTRICTIVE composition) + Sink-Resident User-Override + Read/USING Enforcement | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/MISSION-MANIFEST.md` | Mission Manifest — Mosaic Native Kanban and Canonical Task SOT P0–P3 | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/SHARED-CONTRACT.md` | Native Kanban/SOT — Remediated Shared Contract v1 | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/TASKS.md` | Native Kanban/SOT P0–P3 — Dependency-Ordered Build Slices | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/contracts/health-state.v1.ts` | (no title) | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/contracts/kanban-schema.v1.ts` | (no title) | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/contracts/mechanical-coordinator.v1.ts` | (no title) | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/contracts/recovery-posture.v1.ts` | (no title) | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/native-kanban-sot/tsconfig.json` | (no title) | `historical/unverified` | archived native-kanban-sot | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/, tasks/, and reports/` |
| `docs/_old_structure/plans/2026-03-13-gateway-security-hardening.md` | Gateway Security Hardening Implementation Plan | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/2026-03-15-agent-platform-architecture.md` | Agent Platform Architecture — Slash Commands, Workspaces, Task Orchestration & Agent Isolation | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/2026-03-15-wave2-tui-layout-navigation.md` | Wave 2 — TUI Layout & Navigation Implementation Plan | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/2026-05-06-hermes-mosaic-alignment.md` | Hermes-Mosaic Alignment Plan | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/2026-05-07-coordination-resilience.md` | Mosaic Stack ↔ Hermes Coordination Resilience | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/2026-08-09-webui-fleet-claude-bridge.md` | WebUI Fleet Claude Bridge Implementation Plan | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/agent-reflection-loop-PRD.md` | PRD — Agent Reflection Loop (durable kernel) | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/authentik-sso-setup.md` | Authentik SSO Setup | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/chroot-sandboxing.md` | Chroot Agent Sandboxing — Process Isolation for Agent Tool Execution | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/gatekeeper-service.md` | Gatekeeper Service — PR Review, Quality Gates & Merge Authority | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/gateway-token-recovery.md` | Gateway Admin Token Recovery — Implementation Plan | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/plans/task-queue-unification.md` | Task Queue Unification — @mosaicstack/queue as Unified Orchestration Layer | `historical/unverified` | archived plans | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `plans/ or DEVELOPER-GUIDE/architecture/decisions/` |
| `docs/_old_structure/remediation/BOARD-LEDGER.md` | ### **D-1 / P-ACTIVATION + hygiene — committed `.npmrc` hard-pins `store-dir=/root/.local/share/pnpm/store`.** | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/remediation/BOARD.md` | mos-remediation — LIVE BOARD (keep < 8 KB) | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/remediation/DECOMP-OPUS.md` | DECOMP-OPUS — Adversarial Task Decomposition (ROBUSTNESS SIDE) | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/remediation/DECOMP-SOL.md` | Adversarial Decomposition — Pragmatic / Shortest-Path Side | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/remediation/KICKSTART.md` | mos-remediation — Orchestrator Kickstart / Compaction-Survival Resume | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/remediation/MACP-WIRING-SCOUT.md` | MACP wiring investigation | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/remediation/MISSION.md` | Mosaic Stack Remediation — Mission Charter | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/remediation/TASKS.md` | Remediation Backlog — Reconciled Execution Plan | `historical/unverified` | archived remediation | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/deferred/ or tasks/` |
| `docs/_old_structure/reports/code-review/756-code-review.md` | Independent Code Review — #756 Official Discord Channel Plugin | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/code-review/gateway-security-20260313.md` | Code Review Report — Gateway Security Hardening | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/compaction-refresh/830-documentation-checklist.md` | #830 Documentation Completion Checklist | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/deferred/758-fleet-config-deferrals.md` | FCM-M5-001 Fleet Documentation Deferrals and Holds | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/documentation/756-discord-plugin-checklist.md` | Documentation Completion Checklist — #756 Official Discord plugin | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/documentation/758-fleet-config-ia-closure.md` | FCM-M5-001 Fleet Documentation IA Closure Evidence | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/native-kanban-sot/canon-final-rereview-go.md` | Native Kanban/SOT canon independent re-review 2 | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/native-kanban-sot/canon-initial-review-no-go.md` | Independent Review — Native Kanban/SOT Canon | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md` | KBN-101 contract independent security/architecture review | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/native-kanban-sot/ultron-final-go.md` | #751 Native Kanban/SOT canonical publication — Ultron final gate | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/qa/gateway-security-20260313.md` | QA Report — Gateway Security Hardening | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/reports/security/756-security-review.md` | Security Review — Issue #756 | `historical/unverified` | archived reports | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/<category>/` |
| `docs/_old_structure/requirements/native-kanban-sot.md` | Native Kanban and Canonical Task SOT — Canonical Requirements | `historical/unverified` | archived requirements | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `PRD.md or DEVELOPER-GUIDE/architecture/requirements/` |
| `docs/_old_structure/reviews/consolidation-board-memo.md` | Board of Directors — Monorepo Consolidation Brief | `historical/unverified` | archived reviews | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `reports/code-review/` |
| `docs/_old_structure/rfcs/RFC-001-MACP-MATRIX-NATIVE.md` | RFC-001 — MACP: A Mosaic-Native, Matrix-Native Comms Layer | `historical/unverified` | archived rfcs | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/rfcs/` |
| `docs/_old_structure/rfcs/RFC-002-INSTALL-CONFIG-TOPOLOGY.md` | RFC-002 — Install, Configuration & Topology for the Mosaic Matrix/MACP Comms System | `historical/unverified` | archived rfcs | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `DEVELOPER-GUIDE/architecture/rfcs/` |
| `docs/_old_structure/scratchpads/1000-rm-61-ci-contract-exemption.md` | RM-61 — CI contract exemption for #1000 teardown artifact | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/2026-06-20-fleet-cli-local-canary.md` | Fleet CLI Local Canary Dogfood — 2026-06-20 | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/2026-06-20-fleet-release-hardening.md` | Fleet release hardening | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/387-updater-wrapper-gitea-20260404.md` | Scratchpad — issue #387 updater simplification + Gitea wrapper repo context | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/41-plugin-host.md` | Scratchpad — P5-001 Plugin Host | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/462-fed-m3-04-scope-service.md` | Scratchpad — FED-M3-04 Scope Service | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/462-fed-m3-06-get-verb.md` | Scratchpad — FED-M3-06 get verb | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/536-wrapper-login-pin.md` | Issue 536 Wrapper Login Pin Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/544-agent-reflection-loop.md` | Scratchpad — #544 Agent Reflection Loop (durable kernel) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/559-560-wrapper-eval-login-20260620.md` | Wrapper hardening fold-in: #559 (eval removal) + #560 (host-derived login) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/561-python-is-python3.md` | Issue #561 — Bare python on agent hosts | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/631-reseed-preserves-fleet.md` | #631 — re-seed must preserve user fleet data (CRITICAL data-loss) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/633-comms-block-runbook.md` | #633 — comms-block emitter + FLEET-LAUNCH runbook | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/672-fleet-personas-timeout.md` | Scratchpad — fleet-personas spec timeout | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/703-wrapper-interactive-auth.md` | #703 Git Wrapper Interactive and Auth Resilience | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/747-wsa-dehardcode.md` | #747 — De-hardcode orchestrator and interaction agent names | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/751-native-kanban-canon.md` | Issue #751 — Native Kanban/SOT canonical publication | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/753-kbn010-threat-gate.md` | Issue #753 — KBN-010 threat, authorization, and constraint-impact gate | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/755-mos-logical-identity-fencing.md` | Issue #755 — Logical Mos identity and connector lease fencing | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/756-official-discord-plugin.md` | Scratchpad — #756 Official Discord channel plugin | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/758-fcm-m1-002-shared-role-resolution.md` | FCM-M1-002 — Shared role resolution | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/758-fcm-m1-003-example-profile-dispositions.md` | FCM-M1-003 — Executable example/profile/service-preset dispositions | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/758-fcm-m2-002-fleet-agent-crud.md` | FCM-M2-002 — Generation-Guarded Fleet Agent CRUD | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/758-fcm-m3-001-local-reconciler.md` | FCM-M3-001 — Local roster-owned reconciliation and lifecycle | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/758-fcm-m3-002-reconciler-lifecycle-gates.md` | FCM-M3-002 — Reconciler lifecycle acceptance gates | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/758-fcm-m4-001-v1-v2-migrator.md` | FCM-M4-001 — v1-to-v2 inventory, preview, and migrator | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/771-kbn101-db-role-split.md` | Scratchpad — KBN-101 DB runtime/migration role split (#771) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/791-upgrade-config-protection.md` | Scratchpad — #791 Upgrade config protection (ms-791 worker lane) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/804-install-unknown-flags.md` | Issue #804 — fail closed on unknown installer arguments | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/807-glpi-partial-content.md` | Issue #807 — GLPI list wrappers accept HTTP 206 | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/808-agent-send-sender-identity.md` | Issue #808 — agent-send sender identity | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/812-pr-review-comment.md` | Issue #812 — durable Gitea PR review comments | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/824-mosaic-skill-cli.md` | Issue #824 — Mosaic skill CLI and Claude bridge auto-sync | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/828-lease-broker.md` | WI-1 Scratchpad — Authenticated external lease broker | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/829-mutator-gate.md` | WI-2 Scratchpad — Whole mutator-class gate | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/830-compaction-revoke.md` | WI-3 Scratchpad — Compaction revocation and runtime-generation rollover | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/832-receipt-challenge-protocol.md` | #832 Receipt-challenge protocol — build scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/833-constrained-recovery-command.md` | #833 constrained recovery command — build scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/838-broker-acceptance-flake.md` | Issue #838 — Broker acceptance socket flake | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/B1-next-durable-publish-design.md` | B1 / @next Durable Publish Pipeline — Design | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/B2-skills-sync-path.md` | B2 — Fresh-install skills sync path | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/B3-wizard-gateway-health-order.md` | B3 — Wizard completion ordering | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/B4-wizard-step-dedup.md` | B4 — Wizard step deduplication | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/BUG-CLI-scratchpad.md` | BUG-CLI Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/FED-M3-05-list-verb.md` | FED-M3-05 — Federation List Verb Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/FED-M3-07-capabilities.md` | FED-M3-07 — Capabilities Verb Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/FED-M3-09-query-source.md` | FED-M3-09 — Query Source Service Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/FED-M3-10-integration-tests.md` | FED-M3-10 — Federation M3 Integration Tests | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/bug-196-admin-redirect.md` | BUG-196: Admin Page Redirect Issue | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/ci-docker-publish-20260330.md` | Scratchpad: CI Docker Publish (2026-03-30) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/cli-unification-20260404.md` | Mission Scratchpad — CLI Unification & E2E First-Run | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/f3-m3-update-reseed.md` | F3-m3 — `mosaic update` re-seeds framework + relaunches agents (R13) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/f4-matrix-connector.md` | F4 — Orchestrator chat connector + Matrix (#616) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fcm-m2-001-generated-env-boundary.md` | FCM-M2-001 — Generated Environment Boundary | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fcm-m5-001-fleet-config-operator-docs.md` | FCM-M5-001 — Fleet configuration operator documentation | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fix-ci-migrations-20260330.md` | Scratchpad — fix-ci-migrations-20260330 | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fix-turbo-env-passthrough.md` | Task Scratchpad — Turbo DATABASE_URL passthrough | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fleet-cli-local-canary-review-fixes.md` | Fleet CLI Local Canary Review Fixes | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fleet-comms-onboarding.md` | Fleet onboarding-injection — comms cheat-sheet + peer roster (#620) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fleet-enhancer-floor.md` | Fleet enhancer role + two-agent floor (#614) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fleet-observability-phase2.md` | Scratchpad — Fleet Phase 2: Observability (W-FLEET) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fleet-polish-bundle.md` | Fleet-polish bundle — boot-survival symmetry (#611) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/fleet-standup-fixes.md` | Fleet stand-up fixes — model_hint→--model + socket-default trap (#626) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/gateway-install-ux-20260404.md` | Gateway Install UX Fixes — 2026-04-04 | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/gateway-security-20260313.md` | Gateway Security Hardening Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/git-wrapper-rollup-20260526.md` | Git Wrapper Rollup — 2026-05-26 | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/h1-heartbeat-readiness.md` | H1 — heartbeat readiness detection | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/h1b-pane-idle-signal.md` | H1b — tmux pane idle signal wiring | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/h2-readiness-available.md` | H2 — readiness semantics: available, not stuck | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/harness-20260321.md` | Mission Scratchpad — Harness Foundation | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/install-ux-hardening-20260405.md` | Install UX Hardening — IUH-M01 Session Notes | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/installer-next-fast-npm-20260625.md` | Installer `--next` fast npm lane — 2026-06-25 | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/installer-next-lane-20260624.md` | Scratchpad — installer `--next` lane | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/issue-766-exact-fleet-comms.md` | Issue 766 — exact cross-harness fleet comms targeting | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/m3-001-provider-adapter.md` | M3-001 Provider Adapter Pattern — Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/macp-oc-bridge-20260330.md` | Scratchpad: MACP OC Bridge (2026-03-30) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/ms-792-fleet-enoent-installer.md` | ms-792 — Fleet roster error handling and installer heading | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/mvp-20260312.md` | Mission Scratchpad — MVP | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/north-star-doctrine.md` | north-star doctrine consolidation (#620-adjacent doc PR) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p5-003-telegram-plugin.md` | Scratchpad — P5-003 Telegram Plugin | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p5-004-authentik-sso.md` | P5-004 Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p5-overlay-composer.md` | P5 — Overlay composer + cross-harness (compose-contract) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p6-docs-compliance-alpha.md` | P6 — Docs, compliance matrix, alpha tag (constitution capstone) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p8-001-sso-providers.md` | P8-001 — WorkOS + Keycloak SSO Providers | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p8-009-tui-slash-commands.md` | P8-009: TUI Phase 1 — Slash Command Parsing | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p8-010-command-registry.md` | P8-010 Scratchpad — Gateway Phase 2: CommandRegistryService + CommandExecutorService | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p8-012-agent-provider-commands.md` | P8-012 Scratchpad — Gateway /agent, /provider, /mission, /prdy, /tools Commands | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p8-016-tool-hardening.md` | P8-016: Security — Tool Path Hardening + Sandbox Escape Prevention | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/p8-019-verify.md` | P8-019 Verification — Phase 8 Platform Architecture | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/rm-01-reproducible-checkout.md` | RM-01 — Reproducible checkout | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/rm-03-queue-guard.md` | RM-03 — CI Queue Guard Repair | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/t-a292e96f-gitea-pr-metadata.md` | t_a292e96f — Gitea PR metadata wrapper fix | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/t_301e4e3b-pr-merge-gitea-empty-uid.md` | Scratchpad: t_301e4e3b pr-merge.sh Gitea empty-uid fallback | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/t_5aab9cc8-pr-merge-eval-injection.md` | t_5aab9cc8 — pr-merge.sh eval injection remediation | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/task-mission-ownership-20260313.md` | Task Ownership Gap Fix Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-20260712.md` | Scratchpad — Tess Interaction Agent | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m1-002-provider-registry.md` | TESS-M1-002 — Provider Registry | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m1-003-fleet-provider.md` | TESS-M1-003 — Fleet/tmux Runtime Provider | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m1-obs-001.md` | TESS-M1-OBS-001 Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m1-sec-001.md` | TESS-M1-SEC-001 — Command authorization and exact-action approval | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m1-sec-004-discord-ingress.md` | Scratchpad — TESS-M1-SEC-004 Discord ingress | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m1-sec-006-session-gc-scope.md` | Scratchpad — TESS-M1-SEC-006 Session GC scope | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m2-001-pi-service.md` | TESS-M2-001 — Pi Interaction Service | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m2-002-durable-state.md` | TESS-M2-002 — Durable Tess State | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m4-001-mos-coordination.md` | TESS-M4-001 — Mos Coordination | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tess-m4-003-operator-plugins.md` | TESS-M4-003 — Operator Plugin Foundations | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/tools-md-seeding-20260411.md` | Hotfix Scratchpad — `install.sh` does not seed `TOOLS.md` | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/update-checker-package-20260404.md` | Scratchpad — updater package target fix (#382) | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/webui-fleet-bridge-plan.md` | WebUI Fleet Bridge Planning Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/webui-p2-data-auth.md` | WebUI Phase P — P2 Data + Auth Scratchpad | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/scratchpads/yolo-runtime-initial-arg-20260411.md` | Hotfix Scratchpad — `mosaic yolo <runtime>` passes runtime name as initial user message | `historical/unverified` | archived scratchpads | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `archive/ or tasks/ after retention review` |
| `docs/_old_structure/tasks/544-agent-reflection-loop.md` | 544: Agent Reflection Loop — durable kernel | `historical/unverified` | archived tasks | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/` |
| `docs/_old_structure/tasks/WP1-forge-package.md` | WP1: packages/forge — Forge Pipeline Package | `historical/unverified` | archived tasks | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/` |
| `docs/_old_structure/tasks/WP2-macp-package.md` | WP2: packages/macp — MACP Protocol Package | `historical/unverified` | archived tasks | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/` |
| `docs/_old_structure/tasks/WP3-mosaic-framework-plugin.md` | WP3: plugins/mosaic-framework — OC Rails Injection Plugin | `historical/unverified` | archived tasks | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `tasks/` |
| `docs/_old_structure/tess/ADMIN-GUIDE.md` | Tess Administration | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/ARCHITECTURE.md` | Tess Architecture | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/DEVELOPER-GUIDE.md` | Tess Developer Guide | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md` | TESS-M4-003 Operator Plugin Sketch | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/M5-003-DOCUMENTATION-CHECKLIST.md` | TESS-M5-003 Documentation Checklist | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/M5-MIGRATION-CUTOVER.md` | TESS-MIG-001 — Cutover Procedure | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/M5-MIGRATION-INVENTORY.md` | TESS-MIG-001 — Hermes → Mosaic Evidence Inventory | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/M5-MIGRATION-RETENTION-DEPRECATION.md` | TESS-MIG-001 — Retention and Legacy Deprecation Policy | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/M5-MIGRATION-ROLLBACK.md` | TESS-MIG-001 — Rollback Procedure | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/MIGRATION-INVENTORY.md` | Tess Capability Migration Inventory | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/MISSION-MANIFEST.md` | Mission Manifest — Tess Interaction Agent | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/MOS-COORDINATION.md` | Tess–Mos Coordination Contract Sketch | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/OPERATIONS-GUIDE.md` | Tess Operations and Recovery | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/PLUGIN-GUIDE.md` | Tess Plugin Authoring | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/TASKS.md` | Tasks — Tess Interaction Agent | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/THREAT-MODEL.md` | Tess Threat Model | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/USER-GUIDE.md` | Tess User Guide | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/VERIFICATION-MATRIX.md` | Tess Verification Matrix | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/hermes-runtime-adapter-design.md` | TESS-HRM-001 — Hermes runtime adapter boundary | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/_old_structure/tess/qualification/2026-07-14-option2-runtime-portability.md` | Tess / Option 2 runtime-portability qualification — 2026-07-14 | `historical/unverified` | archived tess | Moved unchanged during the 2026-08-10 archive operation; claims require evidence review before resurfacing. | `USER-GUIDE/, ADMIN-GUIDE/, and DEVELOPER-GUIDE/ by page purpose` |
| `docs/openapi-tess.yaml` | (no title) | `partially-verified/legacy-location` | Tess-scoped OpenAPI contract | PyYAML parses OpenAPI 3.1.0 with 17 paths. It covers Tess interaction, Mos coordination, and memory routes, but is not at `docs/API/` and is not a complete gateway contract. | `API/ (scoped Tess contract or consolidated OPENAPI.yaml)` |
| `docs/plans/2026-08-10-docs-information-architecture-design.md` | Documentation Information Architecture Design | `current/working` | approved plan | Task-local planning artifact; not a statement of shipped behavior. | `plans/` |
| `docs/plans/2026-08-10-docs-structure-readme.md` | Documentation Structure README Implementation Plan | `current/working` | approved plan | Task-local planning artifact; not a statement of shipped behavior. | `plans/` |
| `docs/scratchpads/DOCS-IA-001.md` | DOCS-IA-001 — Documentation Information Architecture | `current/working` | task scratchpad | Task-local working notes; not a canonical product source. | `scratchpads/` |
## Navigation and link audit
- Total scanned links: **219**.
- Current/workflow links: **97**; unresolved current links excluding the two intentional README blueprint links: **83**.
- Archive links: **122**; unresolved archive links: **12**.
### Broken-link clusters
| Target | Occurrences | Current sources |
| --------------------------------------------------------- | ----------: | ------------------------------------------- |
| `./scratchpads/mvp-20260312.md` | 3 | `docs/MISSION-MANIFEST.md` |
| `./federation/TASKS.md` | 3 | `docs/MISSION-MANIFEST.md`, `docs/TASKS.md` |
| `./federation/MISSION-MANIFEST.md` | 2 | `docs/MISSION-MANIFEST.md`, `docs/TASKS.md` |
| `./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md` | 2 | `docs/PRD.md`, `docs/TASKS.md` |
| `./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` | 2 | `docs/PRD.md`, `docs/TASKS.md` |
| `tess/USER-GUIDE.md` | 2 | `docs/SITEMAP.md` |
| `tess/PLUGIN-GUIDE.md` | 2 | `docs/SITEMAP.md` |
| `./tess/MISSION-MANIFEST.md` | 1 | `docs/MISSION-MANIFEST.md` |
| `./native-kanban-sot/MISSION-MANIFEST.md` | 1 | `docs/MISSION-MANIFEST.md` |
| `./native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md` | 1 | `docs/PRD.md` |
| `architecture/lease-broker-protocol.md` | 1 | `docs/SITEMAP.md` |
| `guides/lease-broker-operations.md` | 1 | `docs/SITEMAP.md` |
| `architecture/lease-broker-security.md` | 1 | `docs/SITEMAP.md` |
| `architecture/mutator-class-gate.md` | 1 | `docs/SITEMAP.md` |
| `architecture/compaction-revocation.md` | 1 | `docs/SITEMAP.md` |
| `guides/user-guide.md` | 1 | `docs/SITEMAP.md` |
| `guides/dev-guide.md` | 1 | `docs/SITEMAP.md` |
| `fleet/README.md` | 1 | `docs/SITEMAP.md` |
| `fleet/concepts/desired-vs-observed-state.md` | 1 | `docs/SITEMAP.md` |
| `fleet/concepts/identity-class-runtime.md` | 1 | `docs/SITEMAP.md` |
| `fleet/concepts/role-authority-and-leases.md` | 1 | `docs/SITEMAP.md` |
| `fleet/concepts/generated-env-launch-chain.md` | 1 | `docs/SITEMAP.md` |
| `fleet/reference/roster-v2-fields.md` | 1 | `docs/SITEMAP.md` |
| `fleet/reference/cli.md` | 1 | `docs/SITEMAP.md` |
| `fleet/reference/lifecycle-transitions.md` | 1 | `docs/SITEMAP.md` |
### Link-audit interpretation
- The 66 `SITEMAP.md` failures are a navigation migration blocker, not evidence that every archived page is false.
- The `PRD.md`, `TASKS.md`, and `MISSION-MANIFEST.md` failures show that current control documents still point at the pre-archive layout.
- The two unresolved wikilinks in `docs/README.md` are intentional target-tree blueprint links and should resolve when the architecture scaffold is created.
- Link repair must occur with page classification; blindly changing paths can turn a historical or draft page into an accidental current instruction.
## Repository truth dependencies
The following tracked files currently depend on documentation paths that are absent from the working tree:
| Source file | Dependency | Risk |
| -------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `README.md` | legacy docs path | Installed framework guidance may retain stale links. |
| `apps/gateway/src/federation/ca.service.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `apps/gateway/src/federation/oid.util.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `apps/gateway/src/federation/scope-schema.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/mosaic/framework/fleet/README.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/board.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/code.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/decomposition.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/documentation.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/enhancer.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/merge-gate.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/operator.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/orchestrator.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/planner.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/rebase.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/review.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/security-review.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/session-review.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/fleet/roles/site-tester.md` | `docs/fleet/` | Installed framework guidance may retain stale links. |
| `packages/mosaic/framework/systemd/user/README.md` | legacy docs path | Installed framework guidance may retain stale links. |
| `packages/mosaic/src/commands/fleet-north-star.spec.ts` | `docs/fleet/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/mosaic/src/commands/fleet.ts` | `docs/fleet/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/mosaic/src/fleet/fleet-documentation.spec.ts` | `docs/fleet/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/mosaic/src/fleet/roster-v2.spec.ts` | `docs/fleet/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/mosaic/src/lease-broker/framework_skill_portability_unittest.py` | legacy docs path | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts` | legacy docs path | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/types/src/federation/error.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/types/src/federation/request.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/types/src/federation/response.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/types/src/federation/source-tag.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
| `packages/types/src/federation/verbs.ts` | `docs/federation/` | Tests or runtime path resolution may fail if the source is not updated with the document move. |
High-risk consumers include `packages/mosaic/src/commands/fleet.ts`, fleet path-resolution tests, lease-broker portability tests, federation source comments, and root `README.md` operator links. These must be handled before deleting the archived source pages.
## Truth-audit evidence collected
| Surface | Evidence | Result |
| --------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| SSO provider environment contract | `packages/auth/src/sso.ts`, auth tests, `.env.example` | Provider core names and partial-config behavior align; web feature-flag claim does not. |
| SSO web flow | `apps/web` login/provider pages and `/api/sso/providers` calls | Dynamic provider discovery is current; `NEXT_PUBLIC_*_ENABLED` documentation is stale. |
| Performance report | Seven named implementation files exist; DB pool, upsert, indexes, GC, and Next config markers found | Static implementation alignment is partial; performance metrics and production traffic are unverified. |
| Tess OpenAPI | PyYAML parse of `docs/openapi-tess.yaml` | Valid OpenAPI 3.1 syntax with 17 paths; legacy location and incomplete full-gateway coverage remain. |
| TUI documents | `packages/cli` and old worktree absent; `packages/mosaic/src/tui` exists | TUI document paths are contradicted/stale. |
| Root navigation | Relative link resolver and repository reference scan | Current docs and code still depend on pre-archive paths. |
| Documentation root hygiene | Baseline `.gitignore` and `guides/DOCUMENTATION.md` | `docs/reports/` is required for evidence; the conflicting blanket ignore rule was identified and subsequently removed. |
## Recommended migration order
1. **Scaffold indexes without moving content:** create the required book/API `README.md` files and architecture index pages. Keep them explicit about what is not migrated yet.
2. **Repair current control-plane navigation:** classify the workstream manifests, then update `SITEMAP.md`, `MISSION-MANIFEST.md`, and `TASKS.md` through the orchestrator-owned process. Do not silently change task status.
3. **Migrate high-value operator/user material:** extract `QUICKSTART`, SSO, deployment, recovery, and user workflow pages into the appropriate books. Re-verify every command and environment variable during migration.
4. **Migrate developer architecture and API contracts:** split mixed `fleet`, `federation`, `tess`, architecture, RFC, and requirements material. Move the Tess contract into `API/` and decide whether it remains scoped or becomes part of a consolidated gateway OpenAPI contract.
5. **Resolve source/test dependencies:** update code comments, fixture paths, tests, and framework templates only alongside the corresponding documentation move. Run the relevant package tests after each dependency group.
6. **Retain evidence deliberately:** place historical reports, plans, scratchpads, task snapshots, and reviews in their artifact directories. Promote only claims with current evidence.
7. **Quarantine cleanup:** remove `_old_structure/` only after link, source-reference, and historical-retention checks pass.
## Human validation queue
The following decisions require product-owner or maintainer confirmation rather than static inference:
- Which requirements in the draft PRD remain active for the current release, versus historical or superseded workstreams.
- Whether the MVP/federation/Tess/Kanban manifests are still active control documents or should be archived.
- Which TUI work was actually merged and where its current source of truth lives.
- Whether the Tess OpenAPI document is intended to be a scoped contract or the first portion of the complete gateway contract.
- Whether `NEXT_PUBLIC_WORKOS_ENABLED` and `NEXT_PUBLIC_KEYCLOAK_ENABLED` are obsolete configuration variables or still supported by a deployment surface not present in this checkout.
- Which historical security, migration, and deployment procedures are safe to preserve as reference and which must be marked explicitly non-operative.
## Audit limitations
- This is a static repository audit. It did not start Gateway/Web, PostgreSQL, Valkey, Compose, or external identity providers.
- No external agent session was used because the existing fleet sessions were explicitly standing down; parallel discovery was performed with isolated read-only scans in this coordinating session.
- At the audit baseline, `docs/reports/` was ignored by `.gitignore` and this report required force-add. The migration subsequently removed the blanket ignore rule.
- “Historical/unverified” does not mean the original author was wrong; it means the page is not safe to treat as current without evidence.
- Claims involving production topology, external services, latency, security certification, or merged PR state need independent evidence beyond file presence.
## Reproduction commands
```bash
find docs -type f -not -path 'docs/.obsidian/*' -print | sort
rg -n --hidden --glob '!node_modules/**' --glob '!.git/**' 'docs/(fleet|federation|architecture|tess|native-kanban-sot)' apps packages plugins scripts tools README.md
pnpm exec prettier --check docs/README.md
```
## Related
- [[README|Documentation structure contract]]
- [[plans/2026-08-10-docs-information-architecture-design|Approved information architecture design]]
- [[plans/2026-08-10-docs-catalog-audit|Catalog and truth-audit plan]]
- [[scratchpads/DOCS-IA-002-catalog-audit|Catalog audit scratchpad]]
v1/docs/reports/documentation/756-discord-plugin-checklist.md
+41
View File
@@ -0,0 +1,41 @@
---
kind: record
status: active
---
# Documentation Completion Checklist — #756 Official Discord plugin
## Required artifacts
- [x] `docs/PRD.md` includes the #756 workstream, assumptions, and acceptance criteria.
- [x] User workflow updated in `docs/tess/USER-GUIDE.md`.
- [x] Administrator configuration and authorization policy updated in `docs/guides/admin-guide.md`.
- [x] Developer/plugin authoring guidance updated in `docs/tess/PLUGIN-GUIDE.md`.
- [x] Channel architecture updated in `docs/architecture/channel-protocol.md`.
- [x] Package operations/development guide added at `plugins/discord/README.md`.
- [x] `docs/SITEMAP.md` links the official channel plugin documentation.
## API coverage
- [x] No HTTP or WebSocket endpoint was added, removed, or changed.
- [x] No OpenAPI update is needed.
- [x] Shared TypeScript contracts are documented in architecture and plugin-authoring guides.
- [x] Discord authentication, authorization, thread failure, and control-command behavior are documented.
## Structural standards
- [x] Working notes remain under `docs/scratchpads/`.
- [x] Review and checklist artifacts remain under `docs/reports/`.
- [x] No generated publishing output was added.
- [x] Existing repository documentation structure was preserved; no unrelated root cleanup was attempted.
## Review gate
- [x] Independent documentation/contract review passes (shared-contract review plus final code review of the current documentation delta).
- [x] Independent code review verifies documentation matches implementation (`docs/reports/code-review/756-code-review.md`: APPROVE).
- [x] Independent security review verifies documented controls (`docs/reports/security/756-security-review.md`: APPROVE).
## Publishing
- [x] Canonical source remains in-repository.
- [x] No external publishing action is in scope for this slice.
v1/docs/reports/documentation/758-fleet-config-ia-closure.md
+49
View File
@@ -0,0 +1,49 @@
---
kind: record
status: active
---
# FCM-M5-001 Fleet Documentation IA Closure Evidence
**Issue:** #758 · **Task:** FCM-M5-001
## Artifact map
- Fleet entry point and desired/observed decision tree: `docs/fleet/README.md`.
- Concepts: `docs/fleet/concepts/` covers authority/projections, identity separation, role authority/leases, and the generated launch chain.
- Operator workflows: `docs/fleet/how-to/` covers CRUD, lifecycle, interaction and validator instances, and role overrides.
- Operations: `docs/fleet/operations/` covers reconciliation/recovery, quarantine, systemd/tmux troubleshooting, backup/restore boundaries, and upgrade-asset holds.
- References: executable schema, complete field/default/constraint reference, CLI/JSON/exit behavior, lifecycle/status/drift, role authority, and generated environment boundary under `docs/fleet/reference/`.
- Migration: preview field map, lifecycle preservation, backup/recovery prerequisites, aliases, and executable artifact dispositions under `docs/fleet/migration/`.
- Navigation: `docs/SITEMAP.md` and the fleet entry point.
## Acceptance mapping
| Checklist area | Evidence |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Roster authority and fail-closed legacy handling | Root PRD FCM-REQ-01/05/08; desired/observed and quarantine pages. |
| Classes and authority | Root PRD FCM-REQ-07; role authority concept/reference; configurable interaction/validator how-tos. |
| Lifecycle | Root PRD FCM-REQ-04; lifecycle transition table and operator lifecycle how-to. |
| Local-only generated launch boundary | Root PRD FCM-REQ-05/09; generated launch concept/reference. |
| Complete DAG and artifact inventory | `docs/TASKS.md`; M0 inventory; executable disposition tests. |
| IA pages | Every path named by the M0 checklist exists and is linked from `docs/fleet/README.md`. |
| Examples | `docs/fleet/examples/roster-v2.yaml` validates through production v2 compiler/shared resolver; shipped artifact dispositions validate through declared production readers. |
| Links | Deterministic local Markdown link test covers the entire fleet book and sitemap, including local heading-fragment resolution. |
| Sensitive/example safety | Validator scans backtick- and tilde-fenced fleet-book examples plus the canonical roster for sensitive-looking keys, common credential formats (including Anthropic, OpenAI project, and Stripe restricted keys), path-qualified privileged commands, package-manager/root commands, arbitrary command override, and hardcoded Tess/Ultron identities; findings report only file/block and violation kind, never matched values. |
| Holds | `docs/reports/deferred/758-fleet-config-deferrals.md` records M3-002, M4-002, M5-002, compatibility, and repository-structure boundaries. |
## Documentation completion checklist
- [x] Root PRD exists and remains the #758 requirements authority.
- [ ] The accepted project-specific fleet book is indexed, but it is not complete against `FCM-REQ-03`: the required explicit programmatic `mosaic fleet validate` operation is not implemented. The CLI reference and deferral report record this gap without inventing behavior.
- [x] Sitemap links the fleet entry point and operator-critical pages.
- [x] No HTTP/API/auth contract changed; OpenAPI/endpoint rows are not applicable.
- [x] Working evidence remains under `docs/scratchpads/`; closure and deferral evidence remains under `docs/reports/`.
- [x] Canonical source remains in-repository; no external publishing action is in scope.
- [ ] Independent exact-head documentation review, PR CI, and FCM-M5-002 release certificate remain post-PR gates and are not claimed here.
## Live-action boundary
No migration, canary, rollback, deployment, systemd/tmux/session operation, generated projection, or product mutation was performed. `roster.yaml` remains the sole writable desired-state authority. `mos-comms` remains temporary. Parent issue #758 remains open.
Validation command results and exact commit/tree evidence are recorded in the task scratchpad and PR body after execution.
v1/docs/reports/documentation/AUDIT-2026-02-17-framework-consistency.md
+144
View File
@@ -0,0 +1,144 @@
---
kind: record
status: active
---
# Mosaic Framework Consistency Audit
Date: 2026-02-17
Scope:
- `~/src/mosaic-bootstrap`
- `~/src/agent-skills`
- Installed runtime check: `~/.config/mosaic`
## Findings
| ID | Severity | Finding | Status |
| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| MF-001 | High | QA rails scripts referenced invalid paths (missing `/qa/` segment) for `qa-hook-handler.sh` calls. | Remediated |
| MF-002 | Medium | Conditional-loading detection was biased to legacy `agent-guides` markers and missed Mosaic `guides`/`Conditional Context` phrasing. | Remediated |
| MF-003 | Medium | Framework spec text still described detection as `agent-guides`-based only. | Remediated |
| MF-004 | Medium | Runtime Claude overlay hardcoded skill count, which drifts over time. | Remediated |
| MF-005 | High | `pr-reviewer` skill used legacy `~/.claude/scripts/git` and `~/.claude/skills` paths. | Remediated |
| MF-006 | Medium | `using-git-worktrees` prioritized `CLAUDE.md` only and ignored Mosaic-first docs (`AGENTS.md`/`SOUL.md`). | Remediated |
| MF-007 | Medium | Marketing skills used `.claude/product-marketing-context.md` instead of Mosaic repo-local path. | Remediated |
| MF-008 | Low | `agent-skills/README.md` manual install/adaptation guidance referenced legacy Claude-only paths. | Remediated |
| MF-009 | Low | Historical creation-log contained stale Claude-specific path examples. | Remediated |
## Remediation Details
### MF-001 (QA rails path correction)
Updated:
- `tools/qa/qa-hook-wrapper.sh`
- `tools/qa/qa-hook-stdin.sh`
- `tools/qa/qa-hook-handler.sh`
- `tools/qa/remediation-hook-handler.sh`
- `tools/qa/qa-queue-monitor.sh`
Change:
- Standardized handler paths to `~/.config/mosaic/tools/qa/...`.
### MF-002 + MF-003 (conditional loading/context detection)
Updated:
- `tools/bootstrap/agent-lint.sh`
- `tools/bootstrap/agent-upgrade.sh`
- `templates/agent/SPEC.md`
Change:
- Detection now recognizes both legacy and Mosaic patterns:
- `agent-guides` (legacy compatibility)
- `~/.config/mosaic/guides`
- `Conditional Loading`
- `Conditional Context`
### MF-004 (runtime overlay drift-proofing)
Updated:
- `runtime/claude/CLAUDE.md`
Change:
- Removed hardcoded skills count text.
### MF-005 (pr-reviewer skill path migration)
Updated:
- `skills/pr-reviewer/SKILL.md`
Change:
- Replaced all `~/.claude/scripts/git/...` with `~/.config/mosaic/tools/git/...`.
- Replaced `~/.claude/skills/...` with `~/.config/mosaic/skills/...`.
### MF-006 (worktree skill docs hierarchy)
Updated:
- `skills/using-git-worktrees/SKILL.md`
Change:
- Replaced CLAUDE-only checks with `AGENTS.md` / `SOUL.md` (fallback: `CLAUDE.md`).
### MF-007 (marketing context path migration)
Updated:
- `skills/product-marketing-context/SKILL.md`
- All skills referencing product-marketing-context path (bulk update)
Change:
- Standardized context path to `.mosaic/product-marketing-context.md`.
### MF-008 + MF-009 (repo guidance cleanup)
Updated:
- `README.md` (agent-skills)
- `skills/writing-skills/SKILL.md`
- `skills/writing-skills/examples/CLAUDE_MD_TESTING.md`
- `skills/systematic-debugging/CREATION-LOG.md`
Change:
- Standardized references to `~/.config/mosaic/skills`.
- Removed stale Claude-only wording.
## Residual Legacy References (Intentional)
The following legacy references remain in `mosaic-bootstrap` by design and are not inconsistencies:
- Runtime compatibility tooling for Claude home directory management:
- `bin/mosaic-link-runtime-assets`
- `bin/mosaic-clean-runtime`
- `bin/mosaic-doctor`
- `bin/mosaic-sync-skills`
- `bin/mosaic-migrate-local-skills`
- Documentation explaining Claude runtime overlays:
- `README.md`
- `profiles/README.md`
- `adapters/claude.md`
- `runtime/claude/settings-overlays/` (sample overlay; now shipped sanitized under `examples/overlays/`)
These are required to support existing Claude runtime integration while keeping Mosaic as canonical source.
## Verification
Executed checks:
- `rg -n "~/.claude|\\.claude/|agent-guides" ~/src/agent-skills -S`
- Result: no matches after remediation.
- `rg -n "~/.config/mosaic/tools/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
- Result: no invalid old-style QA rail paths remain.
- Installed runtime validation:
- `~/.config/mosaic` contains `tools/git`, `tools/portainer`, `tools/cicd`, `skills`, and `bin` tooling.
v1/docs/reports/native-kanban-sot/canon-final-rereview-go.md
+64
View File
@@ -0,0 +1,64 @@
---
kind: record
status: active
---
VERDICT: GO
# Native Kanban/SOT canon independent re-review 2
Independent read-only re-review of the complete updated staged canon. Prior proposal-audit blocker is closed; no KCR-001–016 regression or new blocker found.
## Prior blocker closure
- `contracts/kanban-schema.v1.ts:836-837` declares the required unique `task_events(workspace_id,id)` key before proposal declaration.
- `contracts/kanban-schema.v1.ts:885-894` adds both composite proposal audit FKs—submission and accepted-command event—to that exact workspace-aware key with `RESTRICT`.
- Declaration/migration order is executable and explicit in `SHARED-CONTRACT.md:79-91`: events/key first, proposal table second, both FKs third/fourth, then command enablement. This avoids forward-reference/circular-DDL ambiguity.
- Submission/acceptance semantics are frozen in `SHARED-CONTRACT.md:87-91`: preallocate proposal ID; create exact `change_proposal.submitted` event and proposal in one transaction; on acceptance lock proposal/target, execute the normal command, and bind only a same-workspace/target event with submission causation and `payload.changeProposalId` equal to the locked proposal.
- Required missing, foreign-workspace, unrelated-proposal, unrelated-target, and unrelated-command negatives are explicit in `REQUIREMENTS.md` REQ-SOT-004 and `SHARED-CONTRACT.md:121`; KBN-100/110/140 own migration, service, and integration evidence.
## KCR closure matrix
| KCR | Status |
| ------------------------------------------------------ | ------ |
| 001 health/proof | CLOSED |
| 002 error discrimination | CLOSED |
| 003 approval/assignment binding | CLOSED |
| 004 monotonic fencing/composites | CLOSED |
| 005 tenant-safe relations | CLOSED |
| 006 outage proposal persistence/commands/audit binding | CLOSED |
| 007 dependency/API freeze sequencing | CLOSED |
| 008 concrete N-1 map | CLOSED |
| 009 dependency uniqueness | CLOSED |
| 010 project congruence | CLOSED |
| 011 immutable audit retention | CLOSED |
| 012 retry/quarantine/vocabulary | CLOSED |
| 013 archive/tags target semantics | CLOSED |
| 014 recovery validator/owner slice | CLOSED |
| 015 pure Coordinator split | CLOSED |
| 016 health code/state pairing | CLOSED |
Fixed invariants remain consistent: PostgreSQL is sole writable SOT; writes require transaction-local proof and fail closed; exports never import sources; notes are attributable proposals only; Coordinator has no scope/gate/certify/merge authority; Certifier has no merge authority.
## Reproducible validation evidence
Executed read-only with current-stack config/toolchain `/src/mosaic-mono-v1`:
```text
./node_modules/.bin/prettier --config /src/mosaic-mono-v1/.prettierrc --check <all 9 publication artifacts>
PASS: All matched files use Prettier code style.
strict TypeScript --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext <four contract copies with current Drizzle node_modules resolution>
PASS
cascade/TODO/TBD/stale-hold grep plus composite-FK/semantic-marker invariant checks
PASS
```
The TypeScript check used a disposable copy under `/home/hermes/agent-work` solely to provide external-file NodeNext dependency resolution; the reviewed staging artifacts were not modified.
## Residual findings
None blocking. Implementation must execute the frozen KBN-100/KBN-110/KBN-140 proposal-event-chain tests and SecReview evidence before feature release, as already required by the canon.
No artifact source repository, branch, PR, or provider state was modified.
v1/docs/reports/native-kanban-sot/canon-initial-review-no-go.md
+362
View File
@@ -0,0 +1,362 @@
---
kind: record
status: active
---
# Independent Review — Native Kanban/SOT Canon
**Reviewer:** `enhance-sol` (independent of author `planner-sol`)
**Date:** 2026-07-13
**Review mode:** design/contract only; read-only against the staged canon
**Source plan:** `/home/hermes/agent-work/planning/mosaic-native-kanban-sot-plan.md` (`sha256:96ea4fb91436ec9a53f371d27276e27f62ecf817662599ff9152df0db55296e5`)
**Canon reviewed:** every listed artifact under `/home/hermes/agent-work/planning/kanban-canon/`, including the four TypeScript contracts; the author scratchpad was also read as validation context.
## Executive verdict
# NO-GO
The canon is not freeze-ready. I found **8 BLOCKERs**, **7 MAJORs**, and **1 MINOR**. The prose preserves the ratified authority model well, but the frozen types/schema leave concrete fail-closed, approval, fencing, tenant, outage-proposal, migration, and parallelization gaps. Those gaps would force implementation lanes either to invent contract semantics or to ship paths that violate fixed invariants.
### Blocking findings
1. Health/write authorization can be represented as contradictory, stale, or caller-asserted state.
2. Coordinator failures collapse authoritative denial, unknown transport outcome, and version conflict into one permissive shape.
3. Assignment proposals and approval proofs have no authoritative relational binding; lease acquisition accepts a forgeable proof DTO.
4. Fencing uniqueness is present, but monotonic fencing and same-task lease/checkpoint binding are not.
5. Workspace-safe accountable-owner, assignment-principal, and evidence/artifact relationships are not frozen.
6. Attributable post-recovery proposals have neither a canonical table nor command contract.
7. The slice graph starts schema/UI work before prerequisite threat and exact API/DTO freezes and contradicts coder4 lane order.
8. P0 claims a migration map while publishing only generic rules; the concrete N-1 transition from current `origin/main` is absent.
---
## Findings
### KCR-001 — BLOCKER — “Healthy” is not a proof and can be contradictory or stale
**Location**
- `contracts/health-state.v1.ts:21-31` — `KanbanHealthResponseV1` permits every combination of `state`, `readHealthProven`, and `writeHealthProven`.
- `contracts/mechanical-coordinator.v1.ts:40-49` — `CoordinatorContextV1` accepts a caller-supplied `healthState` enum only.
- `contracts/mechanical-coordinator.v1.ts:255-293` — every Coordinator operation, including mutating operations, accepts that context.
- `SHARED-CONTRACT.md:171-184` — mutations are allowed only after live PostgreSQL read/write probes.
**Violation**
Fixed invariant 2 / `REQ-SOT-002`: mutations must fail closed unless write health is positively proven. The current type permits `{ state: 'healthy', writeHealthProven: false }`, and the Coordinator mutation boundary can be invoked with a stale or fabricated `{ healthState: 'healthy' }`. A Valkey/client-derived enum could therefore be mistaken for write authorization.
**Minimal fix**
1. Make `KanbanHealthResponseV1` a discriminated union with only these legal combinations: `healthy => read=true/write=true`, `read-only-degraded => read=true/write=false`, and `write-unavailable => read=false/write=false`.
2. Do not accept write authority from a public DTO. Require Gateway/domain code to obtain and revalidate a fresh internal PostgreSQL write-health proof at mutation time (including `checkedAt`, bounded validity/policy revision, and transaction-local enforcement).
3. Split pure evaluation context from mutation context; mutation methods must accept only an unforgeable/internal healthy context or perform the probe themselves.
4. Add negative contract tests for contradictory state, expired proof, Valkey-only liveness, and caller-forged `healthy`.
### KCR-002 — BLOCKER — Coordinator error shape can conflate denial, unknown outcome, and conflict
**Location**
- `contracts/mechanical-coordinator.v1.ts:184-216` — one `CoordinatorFailureV1` allows every code to pair with arbitrary `retryable` and either `requestOutcome` value.
- `contracts/health-state.v1.ts:51-106` — the Gateway health contract correctly distinguishes deliberate denial, transport uncertainty, and version conflict.
- `SHARED-CONTRACT.md:177-216` — frozen client semantics require those cases not to be conflated.
**Violation**
Charter E and `REQ-SOT-002`. The current Coordinator result can legally encode `WRITE_HEALTH_UNPROVEN` as `retryable: true, requestOutcome: 'unknown'`, or `VERSION_CONFLICT` as retryable. That permits blind retry or a false “unknown” outcome after an authoritative fail-closed denial.
**Minimal fix**
Replace `CoordinatorFailureV1` with a discriminated union keyed by code/kind:
- deliberate health denial: `not_applied`, `retryable:false`;
- version conflict: `not_applied`, `retryable:false`, current version;
- stale fence/session/eligibility/approval failures: exact non-retry semantics;
- transport failure: a separate `retryable_transport_error`, `unknown`, same idempotency key.
Reuse or map explicitly to `KanbanMutationFailureV1`, and add exhaustive client tests proving 503 authoritative bodies, 502/504/timeouts, and 409 cannot cross-map.
### KCR-003 — BLOCKER — Approval proof is forgeable and is not linked to the persisted proposal
**Location**
- `contracts/mechanical-coordinator.v1.ts:107-137` — proposal and approval DTOs.
- `contracts/mechanical-coordinator.v1.ts:265-270` — `acquireApprovedLease` accepts the entire `ApprovalProofV1` by value.
- `contracts/kanban-schema.v1.ts:650-688` — `task_assignments` has no proposal expiry, task version, session binding, or proposal/approval FK.
- `contracts/kanban-schema.v1.ts:823-863` — `approval_decisions` can target only a task or mission and has no proposal/assignment relation.
- `SHARED-CONTRACT.md:128-137` — lease acquisition requires authoritative approval under the exact policy revision.
**Violation**
Fixed invariant 5 and `REQ-COORD-002/003`. A caller can construct an `ApprovalProofV1`; the schema cannot prove that it belongs to the proposal, workspace, task version, agent/session, unexpired policy revision, or still-current approval. The DTO state vocabulary (`awaiting_approval | policy_pre_authorized`) also does not map directly to the persisted assignment states (`proposed | approved | ...`).
**Minimal fix**
Persist one authoritative proposal/assignment identity with task version, target agent/session, expiry, state, and policy revision. Add a workspace-aware approval relation to that identity. Change lease acquisition to accept IDs, then reload and lock proposal + approval + task inside PostgreSQL and verify workspace, current version, target session, state, expiry, and policy revision before creating the lease. Freeze one state vocabulary across schema and DTOs.
### KCR-004 — BLOCKER — Fencing is unique but not monotonically increasing; relational binding is incomplete
**Location**
- `contracts/kanban-schema.v1.ts:694-743` — `task_leases` has positive/unique fencing tokens but no monotonic per-task counter.
- `contracts/kanban-schema.v1.ts:748-784` — checkpoints independently carry task, lease, and fencing token.
- `contracts/kanban-schema.v1.ts:905-910` — token equality is deferred to prose; same-task lease binding is not stated.
- `contracts/mechanical-coordinator.v1.ts:140-175` — worker commands depend on fencing safety.
**Violation**
Fixed invariant 12 / `REQ-COORD-003`. Uniqueness permits token 10 followed by token 9. A lease can reference assignment A while naming task B in the same workspace, and a checkpoint can reference lease A while naming task B. `bigint(..., { mode: 'number' })` also eventually loses integer precision in JavaScript.
**Minimal fix**
Add a durable per-task fencing counter (or equivalent PostgreSQL sequence row) incremented atomically under task lock and use the returned value for every new lease. Add workspace-aware composite constraints tying lease to its exact task+assignment and checkpoint to exact task+lease+fence. Use bigint-safe representation (`bigint`/serialized decimal), and test monotonicity, concurrent claims, stale lower tokens, and mismatched same-workspace IDs.
### KCR-005 — BLOCKER — Hard tenant boundary is not frozen for several polymorphic relationships
**Location**
- `contracts/kanban-schema.v1.ts:315-318` and `475-478` — project/task accountable owners are unvalidated `(kind, text id)` pairs.
- `contracts/kanban-schema.v1.ts:659-663` — assignment principals are unvalidated `(kind, text id)` pairs.
- `contracts/kanban-schema.v1.ts:758` and `841` — checkpoint/evidence artifact relationships are JSON arrays without workspace-aware FKs.
- `SHARED-CONTRACT.md:89-96` — only selected polymorphic checks are delegated to domain transactions; owner/principal/evidence checks are not included.
- `REQUIREMENTS.md:101-108` — every relationship must reject cross-workspace IDs.
**Violation**
Fixed invariant 7 / `REQ-TEN-001` and `REQ-ID-001`. The frozen schema can name a team or agent from another workspace as owner/assignee, and can embed foreign-workspace artifact IDs in checkpoint or approval evidence arrays. A global user ID is also insufficient without active workspace membership validation.
**Minimal fix**
Use workspace-aware owner/assignment join tables or separate nullable user/team/agent columns with exactly-one checks and composite FKs where possible. Model checkpoint/evidence artifact links as workspace-scoped join rows, or freeze explicit transaction checks for every ID. Require active workspace membership for user principals and workspace-agent/session consistency for agent principals. Add DB/repository/API/Coordinator cross-workspace negative tests without existence oracles.
### KCR-006 — BLOCKER — Post-recovery outage proposals have no canonical persistence or command surface
**Location**
- `REQUIREMENTS.md:93-99` — proposal submission and authorized accept/reject are required.
- `SHARED-CONTRACT.md:26-29` — outage notes may return only as authenticated proposals.
- `SHARED-CONTRACT.md:243-267` — the thin command/query contract contains no proposal submit/get/accept/reject operations.
- `contracts/kanban-schema.v1.ts:1-916` — no proposal table captures proposed command, target/version, attribution, lifecycle, or decision.
- `TASKS.md:99-108` — KBN-110 does not own an outage-proposal command path.
**Violation**
Fixed invariant 4 / `REQ-SOT-004`. An implementation lane would have to invent storage or misuse artifacts/approval gates. Either path risks silently applying an outage note or creating shadow state.
**Minimal fix**
Add a workspace-scoped `change_proposals`/`outage_proposals` contract with authenticated proposer, source note digest, target aggregate, expected version, proposed typed command/payload, pending/accepted/rejected state, decision actor/reason/time, idempotency key, and audit linkage. Add explicit submit/query/accept/reject Gateway commands. Acceptance must execute the normal command in a healthy transaction; a proposal itself can never claim, order, satisfy a gate, or mutate the target.
### KCR-007 — BLOCKER — Parallel slice ordering is not freeze-safe and contains a direct lane-order contradiction
**Location**
- `TASKS.md:43-60` — dependency graph makes KBN-010 and KBN-100 siblings.
- `TASKS.md:88-97` — KBN-100 nevertheless depends on KBN-010 threat findings that alter constraints.
- `SHARED-CONTRACT.md:243` and `INDEX.md:44-50` — exact route names/DTO placement remain unresolved.
- `TASKS.md:110-130` — KBN-120/130 depend on a frozen endpoint/DTO contract, while mocks may begin before KBN-110 lands.
- `TASKS.md:145-153` — KBN-200 says lane-serial after KBN-120.
- `TASKS.md:248-254` — wave table runs KBN-200 before KBN-120.
**Violation**
Charter C and the mandatory freeze-before-parallelize gate. Schema can begin before tenant/threat findings are complete; web/CLI consumers have only semantic operations, not exact DTO/endpoint contracts; coder4 has two opposite legal orders. This does not create same-file edits immediately, but it guarantees contract invention or rework across active lanes.
**Minimal fix**
1. Make KBN-010 (or an explicit constraint-impact gate from it) a completed prerequisite of KBN-100.
2. Add a small serialized KBN-105 endpoint/DTO/endpoint-registry freeze, with exact request/response/error DTOs, before KBN-120 and KBN-130 implementation.
3. Choose one coder4 lane order and use it consistently in slice text, graph, and wave table.
4. Name the exact MCP-owned files or assign their Gateway changes to coder3 before coder4 starts.
### KCR-008 — BLOCKER — Claimed P0 migration map is absent; concrete N-1 hazards remain unresolved
**Location**
- `MISSION-MANIFEST.md:153-157` — P0 says to publish a migration map and states the build hold is lifted at line 3.
- `SHARED-CONTRACT.md:101-121` — only generic expand/backfill/contract rules are supplied.
- `contracts/kanban-schema.v1.ts:1-916` — target-state declarations reuse live table names and make target fields required.
- Current foundation evidence: `origin/main:packages/db/src/schema.ts:120-301` has no workspace keys, nullable project/mission links, legacy text status vocabularies, `tasks.tags`, `tasks.assignee`, `tasks.due_date`, mission JSON milestones/config, `mission_tasks.status`, and legacy agent fields.
**Violation**
Charter D / `REQ-MIG-001` and the P0 exit claim. The generic rule is correct, but coder2 lacks the required field-by-field transition map. A direct Drizzle reconciliation could attempt type narrowing/status conversion, add required workspace/project/owner columns too early, or drop legacy columns before N-1 readers and writers are retired.
**Minimal fix**
Publish a concrete current-main delta map before lifting the hold. For each existing table/column, specify expand, backfill, compatibility read/write, switch, and contract release. At minimum cover:
- nullable-first `workspace_id`, required project/owner fields, and workspace backfill;
- legacy task/project/mission status aliases or shadow columns before v1 emission;
- `mission_tasks.status` read retirement and write-source prohibition;
- mapping/retention for tags, assignee, due date, mission description/config/milestones, and agent fields;
- current milestone circular FK ordering;
- empty, production-shape, partial-resume, and rollback/downgrade tests already named in §4.
Explicitly require legacy columns to remain in the unified Drizzle declaration during the expand/N-1 window.
### KCR-009 — MAJOR — Dependency uniqueness permits parallel duplicate edges
**Location**
- `contracts/kanban-schema.v1.ts:561-567` — unique key includes `dependencyType`.
- `SHARED-CONTRACT.md:47-49` — calls for a unique directed edge.
- `REQUIREMENTS.md:142-149` — duplicate edge attempts must fail.
**Violation**
`REQ-DEP-001`. The same predecessor/successor pair can be inserted three times, once per dependency type. That is not a unique directed edge and complicates readiness semantics.
**Minimal fix**
Make `(workspace_id, predecessor_task_id, successor_task_id)` unique independent of type, or explicitly redefine the requirement as one edge per type and freeze deterministic multi-edge completion semantics. The source plan says unique directed edge, so the former is the minimal faithful fix.
### KCR-010 — MAJOR — Same-workspace planning relationships can contradict the project hierarchy
**Location**
- `contracts/kanban-schema.v1.ts:325` — `projects.currentMilestoneId` has no FK in the declaration.
- `contracts/kanban-schema.v1.ts:427-448` — mission/milestone association checks workspace but not common project.
- `contracts/kanban-schema.v1.ts:490-516` — a task’s project, mission, milestone, and parent only need share a workspace, not a project.
- `contracts/kanban-schema.v1.ts:905-908` — only current milestone is mentioned as a deferred invariant.
**Violation**
`REQ-PLAN-001` and schema correctness. A task in project A can point to a mission/milestone/parent task from project B in the same workspace. A mission can associate a milestone from another project despite having one required project.
**Minimal fix**
Add project-congruent composite keys/FKs (or freeze mandatory transaction checks) for task→mission, task→milestone, task→parent, mission→milestone, and project→current milestone. Add same-workspace/same-project negative tests.
### KCR-011 — MAJOR — Immutable/append-only records can be erased by parent cascades
**Location**
- `contracts/kanban-schema.v1.ts:798-818` — `task_events` is described as append-only but remains under a workspace cascade.
- `contracts/kanban-schema.v1.ts:911` — only application-role UPDATE/DELETE privilege removal is stated.
- Numerous canonical relationships use `onDelete('cascade')`, including workspace roots and artifact/checkpoint/event owners.
- `REQUIREMENTS.md:41-43` and `154-170` — audit must be append-only, attributable, and reconstructable.
**Violation**
`REQ-AUD-001`. Revoking direct DELETE on `task_events` does not prevent a parent delete from cascading into the audit log. Checkpoints and immutable artifacts also lack explicit append-only privilege/retention semantics.
**Minimal fix**
Use lifecycle/archive states and `RESTRICT` for canonical parent deletion during normal operation. Freeze a separate, audited retention/break-glass purge procedure. Apply INSERT/SELECT-only or equivalent immutability controls to task events, checkpoints, and immutable artifacts, and test that parent deletion cannot silently erase them.
### KCR-012 — MAJOR — Coordinator persistence lacks durable quarantine/retry state and DTO/schema alignment
**Location**
- `contracts/mechanical-coordinator.v1.ts:239-244` — expiry returns `quarantined` IDs.
- `contracts/kanban-schema.v1.ts:457-490` — task has only untyped `retryPolicy` metadata and no quarantine/execution disposition.
- `contracts/mechanical-coordinator.v1.ts:173` — `evidenceIds` has no corresponding evidence table/type; schema has artifacts.
- `contracts/kanban-schema.v1.ts:479`, `663`, and agent role JSON — specialist roles are free text despite the frozen role vocabulary in `mechanical-coordinator.v1.ts:19-29`.
**Violation**
`REQ-COORD-004` and internal consistency. PostgreSQL cannot deterministically reconstruct why/when a task was quarantined, its bounded retry state, or which typed evidence was submitted. Free-text roles allow the schema and engine to disagree.
**Minimal fix**
Freeze a durable execution/retry/quarantine record (attempt count, next eligibility, terminal reason, actor/policy, timestamps, version) or typed task columns with events. Align `evidenceIds` to artifact IDs or add a real evidence entity. Use one specialist-role enum/check across tasks, assignments, agents/sessions, DTOs, and Coordinator.
### KCR-013 — MAJOR — Thin MVP promises task archive and tag filtering without target-state semantics
**Location**
- `REQUIREMENTS.md:182-193` — users must archive tasks and filter by tags.
- `SHARED-CONTRACT.md:252-267` — mutations include cancel but not archive task.
- `contracts/kanban-schema.v1.ts:457-490` — no task archive field and no typed tags field/table.
- Current `origin/main` already has `tasks.tags`, making omission from the target declaration a migration-loss hazard.
**Violation**
`REQ-UI-001/002` and internal acceptance consistency. “Archive” cannot be implemented without inventing whether it means cancelled, hidden, or soft-deleted; tag filtering has no frozen storage/query contract.
**Minimal fix**
Either remove task archive/tag acceptance from P1, or add explicit non-lifecycle archival semantics (`archived_at/by/reason`) and a workspace-safe tags model/query contract. Preserve/migrate the current tags column until the selected model is live.
### KCR-014 — MAJOR — Recovery contract states critical rules only in comments and has no owning implementation slice
**Location**
- `contracts/recovery-posture.v1.ts:97-147` — exported JSON Schema validates only local field shapes.
- `contracts/recovery-posture.v1.ts:150-156` — PITR/WAL, effective RPO, off-cluster, high-assurance minima, and audit rules are comments only.
- `REQUIREMENTS.md:270-277` — parser rejection of impossible combinations is acceptance-critical.
- `TASKS.md:75-244` — no bounded slice owns recovery config parsing, override audit, backup/WAL setup, or restore/break-glass evidence.
**Violation**
`REQ-REC-001`. A consumer using the advertised JSON Schema can accept weakened high-assurance values, PITR without WAL, or an impossible RPO. The task plan has no lane accountable for closing that acceptance criterion.
**Minimal fix**
Export a normative `validateRecoveryPostureV1`/schema refinement with machine-testable cross-field checks and add a bounded Infra/recovery slice (serialized if it touches shared config) owning config parsing, override audit, mechanism verification, restore test, and break-glass evidence. Recovery config must continue to expose no authority/gate knobs.
### KCR-015 — MAJOR — Pure Coordinator slice cannot implement two frozen methods without persistence access
**Location**
- `contracts/mechanical-coordinator.v1.ts:259-263` — `explainEligibility` receives only `taskId`, not a structured snapshot.
- `contracts/mechanical-coordinator.v1.ts:289-293` — `recoverFromPostgres` explicitly reads PostgreSQL.
- `TASKS.md:145-153` — KBN-200 is a pure engine with no SQL, Drizzle, Gateway, or Valkey.
- `TASKS.md:157-164` — persistence belongs to coder3/KBN-210.
**Violation**
Charter C and internal consistency. coder4 cannot implement the frozen port in a pure package without crossing coder3’s persistence boundary. If coder3 implements the port instead, KBN-200’s acceptance and ownership are misassigned.
**Minimal fix**
Split the contract into a pure decision engine that receives complete immutable snapshots and a persistence/orchestration service port implemented by KBN-210. Move `recoverFromPostgres` and ID-based loading to the adapter/service; make pure explanation accept a snapshot.
### KCR-016 — MINOR — Health denial code/state pairs are not correlated by type
**Location**
- `contracts/health-state.v1.ts:35-61` — either denial code can pair with either degraded state.
- `SHARED-CONTRACT.md:188-190` — prose defines `KANBAN_WRITE_UNAVAILABLE` specifically for `write-unavailable`.
**Violation**
Health contract precision. A client can receive a semantically inconsistent authoritative body even after KCR-001’s broader state fix.
**Minimal fix**
Make deliberate denial a two-variant union with exact code/state pairing.
---
## Clean checks / invariants that do hold
The review did **not** find a gap in these areas:
- The canon consistently selects current `mosaicstack/stack` + Drizzle/PostgreSQL and rejects greenfield/Prisma revival.
- Every artifact states PostgreSQL is the sole writable SOT and Valkey/files are non-authoritative.
- Generated `TASKS.md`, `mission.json`, and exports are consistently declared read-only and never import sources. KBN-300’s importer is scoped to immutable legacy JSON/Vikunja snapshots, not generated projections.
- Recovery config exposes recovery fields only; it contains no direct fail-open, SOT, Coordinator-authority, or gate-waiver knob.
- The Coordinator interface contains no `createTask`, acceptance-edit, gate-waive, certify, merge, release, or provider-close method. `submitForReview` is type-limited to `in_review`, not `done` or `certified`.
- Certifier is consistently final independent gate with no merge authority.
- The seven canonical task status values match across requirements, shared prose, schema, and Coordinator’s ready/in-review surfaces.
- One-active-lease partial uniqueness, no-self-edge, outbox aggregate-revision/event-type uniqueness, optimistic task/project/mission/milestone versions, and N-1 test categories are explicitly present.
- The file-tree partition is mostly well separated once the ordering/freeze defects in KCR-007 are corrected.
## Required re-review scope
After remediation, re-review at minimum:
1. health/coordinator discriminated unions and mutation-time health proof;
2. proposal/approval/assignment/lease relational model;
3. monotonic fencing and composite bindings;
4. tenant-safe polymorphic relationships;
5. outage-proposal persistence and commands;
6. concrete current-main migration map;
7. corrected dependency graph and exact API/DTO freeze;
8. recovery validator/owner slice;
9. all schema and DTO vocabulary alignment.
## Overall verdict
**NO-GO — 8 BLOCKERs must be resolved before the v1 contract is frozen or parallel implementation begins.**
v1/docs/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md
+114
View File
@@ -0,0 +1,114 @@
---
kind: record
status: active
---
# KBN-101 contract independent security/architecture review
**Verdict: REQUEST CHANGES**
## Review identity and scope
- **Exact reviewed head:** `da742ca2da4a2ff466916c818fe275c4f7ffd384` (`docs(#771): record role-split review evidence`)
- **Required comparison:** `origin/main...da742ca2da4a2ff466916c818fe275c4f7ffd384`
- **Range:** `82ce3252df38a687c50485f8d048b53ca8db5989` is an ancestor of the reviewed head; the final head adds the scratchpad evidence commit and was reviewed.
- **Changed docs:** `docs/PRD.md`, `docs/SITEMAP.md`, `docs/native-kanban-sot/{INDEX.md,KBN-101-DB-ROLE-SPLIT.md,SHARED-CONTRACT.md,TASKS.md}`, and `docs/scratchpads/771-kbn101-db-role-split.md` (300 additions / 25 deletions).
- **Reviewed inputs:** issue #771; current DB/Gateway/storage/config/wizard/installer/compose/Portainer/CI sources; all current migration/DDL references; KBN-010, rc.4/rc.5 shared contract, requirements/canon, KBN-100 #769 branch context, and the final scratchpad.
- **Repository/provider state:** not modified. The pre-existing `.mosaic/orchestrator/*` dirt was not touched.
The role graph itself is sound in principle: a NOLOGIN platform database owner, separate NOLOGIN schema owner, NOINHERIT migrator which explicitly `SET ROLE`s, and runtime membership only in a capability role with `SET FALSE` does not create circular privilege or application-created login roles. The split of foundation certification before KBN-100 and immutable-operation certification after KBN-100 is also correctly ordered.
## Findings
### HIGH — DDL/migration control plane is not closed at every current entrypoint
The contract requires an explicit, locked migration phase and forbids Gateway/runtime DDL (`KBN-101-DB-ROLE-SPLIT.md:34-39`), but its KBN-101-02 result merely says migration-capable commands use the migration DTO (`:109`). It does not prohibit or route every existing bypass through that one command.
Current bypasses include:
- `runMigrations()` falls back from an argument to `DATABASE_URL` and a hard-coded URL (`packages/db/src/migrate.ts:24-35`), while `drizzle.config.ts` likewise uses `DATABASE_URL` plus a default (`packages/db/drizzle.config.ts:3-9`).
- Package scripts expose direct `drizzle-kit migrate` **and** `drizzle-kit push` (`packages/db/package.json:23-26`); `db:push` bypasses the planned journal/fingerprint/lock entirely.
- `mosaic storage migrate --run` shells out to the direct `db:migrate` script (`packages/storage/src/cli.ts:413-452`).
- The federated integration test can create types, tables, and indexes directly against `DATABASE_URL` and intentionally operates without a Drizzle ledger (`packages/db/src/federation.integration.test.ts:28-30,46-134`).
**Failure mode:** a runtime or CI environment with only `DATABASE_URL`, or an operator invoking an existing command, can apply unverified DDL outside the lock, `SET ROLE` preflight, exact-ledger gate, and deployment sequencing. This breaks the requested fail-closed split even if Gateway startup is repaired.
**Required remediation:** amend KBN-101-02/03/06 to enumerate these entrypoints and make the dedicated migrator runner the only PostgreSQL DDL path. Production-like `db:push` must be removed/blocked; `db:migrate`, `storage migrate --run`, and migration tests must invoke the same migration runner with `DATABASE_MIGRATION_URL`, lock, identity preflight, and ledger verification. Tests needing schema must consume a pre-migrated disposable database, or be explicitly run only by that migration phase. Add negative tests showing each command refuses `DATABASE_URL`-only execution and cannot reach DDL.
### HIGH — TLS requirement has no deployable server/bootstrap contract
The contract correctly requires a mounted CA and hostname-verified TLS (`KBN-101-DB-ROLE-SPLIT.md:25,28,93-95`). However KBN-101-05 promises only a “migration phase and secret binding boundary” (`:112`), not PostgreSQL server TLS, certificate issuance/SANs, CA distribution, startup ordering, or the fresh/existing-database bootstrap trust path.
Current standalone and federated compose expose plain PostgreSQL with no server TLS configuration or CA mount (`docker-compose.yml:2-14`; `docker-compose.federated.yml:27-44`). The Portainer test stack passes a single plaintext in-network URL and uses the same database login for Gateway and database bootstrap (`deploy/portainer/federated-test.stack.yml:51-60,110-117`).
**Failure mode:** enforcing the mandatory CA makes current local standalone/federated topologies unable to start; relaxing it to make bootstrap work silently violates K101-REQ-03. A first database cannot be safely migrated until the server certificate, its SAN for the actual service/DNS name, and trusted CA are provisioned, but this lifecycle is not owned or tested.
**Required remediation:** add a concrete KBN-101-00/05 TLS bootstrap sub-contract: issuer/CA owner; server key/cert and SAN inputs; secure storage/mount permissions; `postgresql.conf`/container TLS enablement; migration and runtime CA mounts; hostname used by each compose/Swarm service; readiness only after TLS authentication; CA overlap rotation; and an existing-database transition. Require a disposable standalone and federated/Swarm test to prove verified TLS succeeds and missing CA, wrong CA, wrong SAN, and `sslmode` downgrade fail before readiness. Do not merge KBN-101-05 with an implicit plaintext exception.
### HIGH — exact ledger fingerprint and historical 0009 repair are underspecified for existing databases
The contract requires an “ordered complete set” and rejection of out-of-order rows (`KBN-101-DB-ROLE-SPLIT.md:36-38`), but does not define the canonical serialized tuple, ledger ordering source, or safe upgrade rule for a historical ledger. The current ledger stores only `id`, `hash`, and `created_at` (`packages/db/src/migrate.ts:70-82,105-107`). Its journal is demonstrably non-monotonic: `0008` has `when=1776822435828`, followed by `0009` at `1745280000000` (`packages/db/drizzle/meta/_journal.json:62-79`); the existing PostgreSQL runner documents that this causes skipping (`packages/db/src/migrate.ts:29-35`).
**Failure mode:** an implementation can either reject a legitimate historical database after correcting 0009, or accept a reordered/duplicated ledger because no precise comparison rule exists. A count/hash-set implementation would fail to detect the condition that this contract explicitly calls unsafe; physical `id` order is not an adequate substitute after historical repair.
**Required remediation:** freeze a versioned manifest algorithm before implementation: canonical record fields (at least journal index/tag, corrected logical order, migration content hash, and an explicit migration-manifest version), canonical byte serialization, SHA-256 input, and exact observed-ledger mapping. State whether physical ledger insertion order is normative; if not, compare hash-to-manifest tuples rather than timestamps. Add an idempotent migrator-only 0009 existing-database remediation/reconciliation procedure with backup/rollback evidence. Require clean, pre-0009, 0009-skipped, 0009-applied-late, duplicate, unknown, missing, corrupt-pair, and stale-replica cases. No manual ledger insertion is an acceptable production recovery path.
### MEDIUM — advisory-lock namespace is collision-prone and lacks a fixed identifier contract
The specified lock is `pg_try_advisory_lock(hashtext('mosaic-schema-migration-v1'))` (`KBN-101-DB-ROLE-SPLIT.md:34`). `hashtext` produces a 32-bit key. Session ownership/crash behavior is otherwise correctly stated (one session, same-session release, connection-close release), but an unrelated database user can accidentally collide or deliberately hold the key and force `DATABASE_MIGRATION_LOCKED`.
**Failure mode:** avoidable migration denial of service in a shared PostgreSQL database. The current repository already uses separate `hashtext` advisory-lock names for migrate-tier, demonstrating the need for a documented namespace rather than a collision-prone implicit one.
**Required remediation:** freeze a two-int advisory-lock namespace (fixed documented class/object values) or a documented 64-bit `hashtextextended` key with fixed seed; keep acquisition, migration, verification, and release on the single `max:1` migrator session. Add tests for concurrent migration, connection loss/crash release, readiness while the lock holder is active, and an unrelated lock-key non-interference case.
### MEDIUM — identifier safety and `search_path` verification need executable constraints
The contract rightly requires `pg_catalog, <mosaic_application_schema>` and rejects writable paths (`KBN-101-DB-ROLE-SPLIT.md:54,70-77`), but uses dynamic placeholders for database/schema and does not state how migration/bootstrap SQL will avoid identifier interpolation. Existing code has raw-SQL facilities (`packages/storage/src/migrate-tier.ts` uses `.unsafe`), so this is not merely theoretical.
**Failure mode:** a future operator-configured database/schema value that reaches bootstrap or `SET search_path` through raw string construction can inject DDL, or a pooled connection can retain a mutable search path.
**Required remediation:** require fixed allowlisted identifiers or server-side identifier quoting (`format('%I', ...)`) only; never interpolate URL/config values into SQL. Set and verify the trusted path per connection/session before any query (`SET LOCAL` inside transactions where applicable), forbid `public`/`$user` additions, and add injection-shaped identifier and pooled-connection reset negatives. Include this in KBN-101-00/01 tests.
## Acceptance and threat traceability
| Requirement / threat | Review result | Evidence or blocking finding |
| ----------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| K101-REQ-01 / AC-K101-01 split runtime/migration URLs | Partial | Role/DTO boundary is coherent; HIGH DDL-path finding requires all current commands to be closed. |
| K101-REQ-02 / AC-K101-02 explicit migration/readiness | Blocked | HIGH ledger definition and HIGH DDL-bypass findings. |
| K101-REQ-03 / AC-K101-03 least privilege, TLS, grants | Partial | Role model, default privileges, ledger read-only, TEMP/function checks are well specified (`KBN-101...:47-56,70-79`); HIGH TLS bootstrap and MEDIUM identifier constraints remain. |
| K101-REQ-04 / AC-K101-04 immutable relations | Correctly deferred | KBN-101-09 after KBN-100 is the correct serial gate (`KBN-101...:58-66,115-118`); no synthetic-only certification claim found. |
| K101-REQ-05 / AC-K101-05 N-1, secrets, rollback | Partial | No owner-runtime exception and rollback keeps migration URL out of Gateway (`:83-95`); deployable TLS and full command inventory are missing. |
| K101-REQ-06 / AC-K101-07 KBN gates and DAG | Structurally sound | DAG is acyclic: 00→01/{03}; 02→06; 00/01/03→05; 00/04/05/06→07→08→KBN-100→09→KBN-105. KBN-100’s current branch contains docs-only baseline tracking, not schema implementation. |
| T: runtime DDL / migration fallback | Blocked | HIGH finding 1. Current Gateway/storage, CLI, direct Drizzle scripts, and integration DDL require explicit closure. |
| T: race/crash/readiness | Partial | Same-session nonblocking lock and replica-unready rules are present (`:34-38`); lock namespace remediation required. |
| T: immutable evidence rewrite | Correctly staged | Explicit INSERT/SELECT-only matrix and RESTRICT retention are retained; proof is properly after table creation. |
| T: secret leakage / TLS downgrade | Partial | Redaction and distinct Vault paths are specified (`:93-97`), but no server TLS/bootstrap implementation contract exists. |
## Unresolved assumptions
1. `standalone` and `federated` are the complete PostgreSQL production-like set (K101-A1).
2. Each eligible deployment can execute a dedicated migration Job/one-shot phase (K101-A2).
3. Vault path names are targets, not verified existing paths; deployment ownership remains to be established.
4. PostgreSQL 17 is available for the selected membership and advisory-lock implementation.
5. The required server-side TLS issuer/certificate lifecycle and Swarm/compose secret transport have not been decided; this is blocking, not a permissible implicit plaintext bootstrap.
6. Historical databases containing the 0009 journal/ledger anomaly have no frozen reconciliation procedure.
## Independent test and consistency evidence
Read-only checks run in this review:
| Check | Result |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `git diff --check origin/main...da742ca2...` | PASS |
| `pnpm exec prettier --check` on all seven changed docs | PASS |
| `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` | PASS |
| `docker compose -f docker-compose.yml config --quiet` (isolated test ports) | PASS |
| `docker compose -f docker-compose.federated.yml --profile federated config --quiet` (isolated test ports) | PASS |
| Static journal inspection | FAILS the required monotonic ordering premise: 0008 → 0009 `when` decreases; current runner documents skipping behavior. |
| Static DDL-entrypoint inventory | Found direct Drizzle scripts, storage CLI shell-out, runtime extension/migration calls, fleet backlog migration, tier probe extension creation, and a direct-DLL federated integration test. |
No live database, Vault, CI, deployment, issue, PR, or repository mutation was performed. The pass results validate documentation syntax/contract compilation and compose syntax only; they do **not** certify the proposed security behavior.
## Conclusion
Do not merge this frozen contract as implementation-ready until the HIGH findings are corrected and independently re-reviewed. The central role ownership/default-privilege design, immutable-table staging, and KBN-100/KBN-105 serial gating should be retained; they are not the reason for this REQUEST CHANGES verdict.
v1/docs/reports/native-kanban-sot/ultron-final-go.md
+43
View File
@@ -0,0 +1,43 @@
---
kind: record
status: active
---
# #751 Native Kanban/SOT canonical publication — Ultron final gate
**Verdict: GO** — zero BLOCKER/HIGH findings.
## Scope / integrity
- Reviewed `/home/hermes/agent-work/stack-kanban-canon` staged delta only: exactly 16 documentation/contract artifacts; no unstaged delta; `git diff --cached --check` passes.
- This is a publication canon, not a runtime implementation. The explicit implementation hold prevents feature work until canon merge and prerequisite release (`docs/requirements/native-kanban-sot.md:8-9`; `docs/native-kanban-sot/TASKS.md:45-67`).
## Acceptance mapping and findings
| Requirement area | Final evidence / result |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sole PostgreSQL SOT, generated projections, outage proposals | Requirements D3/D4 and fixed invariants prohibit alternate writers and import (`docs/requirements/native-kanban-sot.md:22-23,32-44`). Health contract keeps public observation separate from branded transaction-local proof (`contracts/health-state.v1.ts:44-84`) and freezes 503/409/502/504 mappings (`:91-184`). Proposal table uses workspace-aware event FKs (`contracts/kanban-schema.v1.ts:847-908`); exact submission/acceptance transaction semantics are specified (`SHARED-CONTRACT.md:81-89`). PASS. |
| Workspace tenancy, planning, assignments, evidence | Workspace-composite task and proposal relations plus active-member rules are explicit (`SHARED-CONTRACT.md:40-48`; `kanban-schema.v1.ts:587-637,875-908`). Lease/checkpoint relations bind workspace/task/assignment/session/fence, with one active lease and bigint fencing (`:1062-1114`). PASS. |
| Coordinator, gates, concurrency/recovery | Pure Coordinator has snapshot-only decision methods (`mechanical-coordinator.v1.ts:186-198`); persistence port owns locked ID validation and recovery (`:371-407`). Requirements forbid Coordinator scope/gate/certification/merge authority and Certifier merge authority (`requirements:39-40`; `MISSION-MANIFEST.md` authority table). Recovery validator rejects unknown fields, PITR/WAL/RPO/storage/high-assurance violations (`recovery-posture.v1.ts:193-369`). PASS. |
| Migration/N-1/API/task decomposition | N-1 expand/backfill/compatibility/switch/contract order and proposal DDL sequence are concrete (`SHARED-CONTRACT.md:69-115`). Frozen exact Gateway/DTO registry and non-overlapping lane ownership/prerequisites are present (`SHARED-CONTRACT.md:244-282`; `TASKS.md:45-67,81-259`). PASS. |
| Documentation / seven owner decisions / evidence | D1–D7 are all explicitly ratified (`requirements:20-26`); all 26 REQ sections contain acceptance criteria. Index/manifest/task graph link requirements, frozen contracts, ownership, and evidence. Relative-link audit passes. PASS. |
## Independent verification performed
```text
git diff --cached --check PASS
./node_modules/.bin/prettier --check <all publication paths> PASS
./node_modules/.bin/tsc --noEmit --strict <health/coordinator/recovery> PASS
Python relative Markdown link audit PASS (0 errors)
Python requirement acceptance audit PASS (26 requirements; 0 missing acceptance sections)
Static staged scope/status check PASS (16 staged docs-only; no unstaged delta)
```
The full schema-contract strict type check cannot resolve `drizzle-orm` from this docs-only worktree; this is an environment dependency-resolution limitation, not a contract diagnostic. Independent external publication validation and final re-review record the strict all-four-contract check against the current Stack Drizzle toolchain as PASS.
## Residual items
- **LOW:** implementation must deliver the declared KBN-100/KBN-110/KBN-140 proposal-event-chain, tenant, failure-mapping, and SecReview evidence before P0/P1 release. This is a forward implementation obligation already frozen in the canon, not a publication defect.
- **LOW:** selected infrastructure backup provider/recovery tier and migration/cutover thresholds remain owner-controlled implementation decisions, bounded by the normative recovery contract and change control.
No source, staging, commit, provider, CI, or deployment state was mutated.
v1/docs/reports/qa/gateway-security-20260313.md
+44
View File
@@ -0,0 +1,44 @@
---
kind: record
status: active
---
# QA Report — Gateway Security Hardening
## Scope
- Chat HTTP auth guard hardening
- Chat WebSocket session validation
- DTO validation rules for chat and conversation payloads
- Ownership regression coverage for by-id routes
## TDD
- Required: yes
- Applied: yes
- Red step: targeted tests failed on socket session reshaping and DTO role/length mismatches
- Green step: targeted tests passed after runtime and DTO alignment
## Baseline Verification
| Command | Result | Evidence |
| ------------------------------------------------------------------------------------------------------------------------------ | ------ | --------------------------------------------- |
| `pnpm --filter @mosaicstack/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts` | pass | 3 test files passed, 20 tests passed |
| `pnpm typecheck` | pass | turbo completed 18/18 package typecheck tasks |
| `pnpm lint` | pass | turbo completed 18/18 package lint tasks |
| `pnpm format:check` | pass | `All matched files use Prettier code style!` |
## Situational Verification
| Acceptance Criterion | Verification Method | Evidence |
| ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Chat controller requires auth and current-user context | source assertion test | `chat-security.test.ts` checks `@UseGuards(AuthGuard)` and `@CurrentUser() user: { id: string }` |
| WebSocket handshake requires Better Auth session | unit tests for `validateSocketSession()` | null handshake returns `null`; valid handshake returns original session object |
| Conversation messages reject non-user/assistant roles | class-validator test | `system` role fails validation |
| Conversation messages enforce a 32k max length | class-validator test | `32_001` chars fail validation |
| Chat request payload enforces a 10k max length | class-validator test | `10_001` chars fail validation |
| By-id routes reject cross-user access | ownership regression tests | conversations, projects, missions, tasks each raise `ForbiddenException` for non-owner access |
## Residual Risk
- No live HTTP or WebSocket smoke test against a running gateway process was executed in this session.
v1/docs/reports/qa/p8-003-performance-optimization.md
+163
View File
@@ -0,0 +1,163 @@
---
kind: record
status: active
---
# Performance Optimization — P8-003
**Branch:** `feat/p8-003-performance`
**Target metrics:** <200 ms TTFB, <2 s page loads
---
## What Was Profiled
The following areas were reviewed through static analysis and code-path tracing
(no production traffic available; findings are based on measurable code-level patterns):
| Area | Findings |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `packages/db` | Connection pool unbounded (default 10, no idle/connect timeout) |
| `apps/gateway/src/preferences` | N+1 round-trip on every pref upsert (SELECT + INSERT/UPDATE) |
| `packages/brain/src/conversations` | Unbounded list queries — no `LIMIT` or `ORDER BY` |
| `packages/db/src/schema` | Missing hot-path indexes: auth session lookup, OAuth callback, conversation list, agent-log tier queries |
| `apps/gateway/src/gc` | Cold-start GC blocked NestJS bootstrap (synchronous `await` in `onModuleInit`) |
| `apps/web/next.config.ts` | Missing `compress: true`, no `productionBrowserSourceMaps: false`, no image format config |
---
## Changes Made
### 1. DB Connection Pool — `packages/db/src/client.ts`
**Problem:** `postgres()` was called with no pool config. The default max of 10 connections
and no idle/connect timeouts meant the pool could hang indefinitely on a stale TCP connection.
**Fix:**
- `max`: 20 connections (configurable via `DB_POOL_MAX`)
- `idle_timeout`: 30 s (configurable via `DB_IDLE_TIMEOUT`) — recycle stale connections
- `connect_timeout`: 5 s (configurable via `DB_CONNECT_TIMEOUT`) — fail fast on unreachable DB
**Expected impact:** Eliminates pool exhaustion under moderate concurrency; removes indefinite
hangs when the DB is temporarily unreachable.
---
### 2. Preferences Upsert — `apps/gateway/src/preferences/preferences.service.ts`
**Problem:** `upsertPref` executed two serial DB round-trips on every preference write:
```
1. SELECT id FROM preferences WHERE user_id = ? AND key = ? (→ check exists)
2a. UPDATE preferences SET value = ? … (→ if found)
2b. INSERT INTO preferences … (→ if not found)
```
Under concurrency this also had a TOCTOU race window.
**Fix:** Replaced with single-statement `INSERT … ON CONFLICT DO UPDATE`:
```sql
INSERT INTO preferences (user_id, key, value, mutable)
VALUES (?, ?, ?, true)
ON CONFLICT (user_id, key) DO UPDATE SET value = excluded.value, updated_at = now();
```
This required promoting `preferences_user_key_idx` from a plain index to a `UNIQUE INDEX`
(see migration `0003_p8003_perf_indexes.sql`).
**Expected impact:** ~50% reduction in DB round-trips for preference writes; eliminates
the race window.
---
### 3. Missing DB Indexes — `packages/db/src/schema.ts` + migration
The following indexes were added or replaced to cover common query patterns:
| Table | Old indexes | New / changed |
| --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `sessions` | _(none)_ | `sessions_user_id_idx(user_id)`, `sessions_expires_at_idx(expires_at)` |
| `accounts` | _(none)_ | `accounts_provider_account_idx(provider_id, account_id)`, `accounts_user_id_idx(user_id)` |
| `conversations` | `(user_id)`, `(archived)` separate | `conversations_user_archived_idx(user_id, archived)` compound |
| `agent_logs` | `(session_id)`, `(tier)`, `(created_at)` separate | `agent_logs_session_tier_idx(session_id, tier)`, `agent_logs_tier_created_at_idx(tier, created_at)` |
| `preferences` | non-unique `(user_id, key)` | **unique** `(user_id, key)` — required for `ON CONFLICT` |
**Expected impact:**
- Auth session validation (hot path on every request): from seq scan → index scan
- OAuth callback account lookup: from seq scan → index scan
- Conversation list (dashboard load): compound index covers `WHERE user_id = ? ORDER BY updated_at`
- Log summarisation cron: `(tier, created_at)` index enables efficient hot→warm promotion query
All changes are in `packages/db/drizzle/0003_p8003_perf_indexes.sql`.
---
### 4. Conversation Queries — `packages/brain/src/conversations.ts`
**Problem:** `findAll(userId)` and `findMessages(conversationId)` were unbounded — no `LIMIT`
and `findAll` had no `ORDER BY`, so the DB planner may not use the index efficiently.
**Fix:**
- `findAll`: `ORDER BY updated_at DESC LIMIT 200` — returns most-recent conversations first
- `findMessages`: `ORDER BY created_at ASC LIMIT 500` — chronological message history
**Expected impact:** Prevents accidental full-table scans on large datasets; ensures the
frontend receives a usable, ordered result set regardless of table growth.
---
### 5. Cold-Start GC — `apps/gateway/src/gc/session-gc.service.ts`
**Problem:** `onModuleInit()` was `async` and `await`-ed `fullCollect()`, which blocked the
NestJS module initialization chain. Full GC — which calls `redis.keys('mosaic:session:*')` and
a DB query — typically takes 100–500 ms. This directly added to startup TTFB.
**Fix:** Made `onModuleInit()` synchronous and used `.then().catch()` to run GC in the
background. The first HTTP request is no longer delayed by GC work.
**Expected impact:** Removes 100–500 ms from cold-start TTFB.
---
### 6. Next.js Config — `apps/web/next.config.ts`
**Problem:** `compress: true` was not set, so response payloads were uncompressed. No image
format optimization or source-map suppression was configured.
**Fix:**
- `compress: true` — enables gzip/brotli for all Next.js responses
- `productionBrowserSourceMaps: false` — reduces build output size
- `images.formats: ['image/avif', 'image/webp']` — Next.js Image component will serve modern
formats to browsers that support them (typically 40–60% smaller than JPEG/PNG)
**Expected impact:** Typical HTML/JSON gzip savings of 60–80%; image serving cost reduced
for any `<Image>` components added in the future.
---
## What Was Not Changed (Intentionally)
- **Caching layer (Valkey/Redis):** The `SystemOverrideService` and GC already use Redis
pipelines. `PreferencesService.getEffective()` reads all user prefs in one query — this
is appropriate for the data size and doesn't warrant an additional cache layer yet.
- **WebSocket backpressure:** The `ChatGateway` already drops events for disconnected clients
(`client.connected` check) and cleans up listeners on disconnect. No memory leak was found.
- **Plugin/skill loader startup:** `SkillLoaderService.loadForSession()` is called on first
session creation, not on startup. Already non-blocking.
- **Frontend React memoization:** No specific hot components were identified as causing
excessive re-renders without profiling data. No speculative `memo()` calls added.
---
## Held future procedure
This report is non-operative evidence, not a current runbook. Until **KBN-101-00, KBN-101-03, and KBN-101-05** land, do not execute a PostgreSQL runner from this checkout. The approved future procedure is exactly: external bootstrap → TLS/roles → `mosaic-db-migrator --run` → `mosaic-db-migrator --verify` → Gateway/Compose readiness. Deployment will supply the reviewed runner, migration-only credentials, and TLS material; Gateway startup only verifies readiness.
---
_Generated by P8-003 performance optimization task — 2026-03-18_
v1/docs/reports/quality/1099-pipefail-sweep.md
+88
View File
@@ -0,0 +1,88 @@
---
kind: record
status: active
---
# #1099 pipefail + early-exit sweep
Baseline: `df4c591ab42aa1ae62c12935fdc0e772684864a0`
This is a site inventory, not a risk count. `FIXED` means the early-exiting consumer no longer has a piped upstream process whose SIGPIPE can become the result under `pipefail`. `NOT-LOAD-BEARING` means the pipeline status is explicitly discarded. `UNREACHABLE-AND-WHY` describes designed input, not a payload-size safety claim.
## Tranche 1 — runtime and general scripts
| Baseline site | Verdict | Construction / reason |
| ------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `tools/matrix-presence-harness/run.sh:38` | FIXED | nullglob array selects the first path; no pipeline |
| `tools/e2e-install-test.sh:139` | FIXED | capture help completely, then grep via redirection |
| `tools/install.sh:312` | FIXED | NUL `mapfile` reads all roots; count != 1 reaches the named malformed-archive diagnostic |
| `scripts/analysis/reflect-board-history.sh:76` | FIXED | capture Git history completely, then grep via redirection |
| `scripts/analysis/reflect-git-history.sh:67` | FIXED | grep reads from a here-string |
| `scripts/analysis/reflect-git-history.sh:69` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/authentik/user-create.sh:72` | FIXED | jq `first(...)` reads the response directly |
| `packages/mosaic/framework/tools/git/mutate-push-guard.sh:87` | FIXED | grep `-m1` reads the file directly; downstream `cut` consumes its complete scalar output |
| `packages/mosaic/framework/tools/orchestrator/session-resume.sh:94` | FIXED | `mapfile` plus bounded indexed loop replaces `head` pipeline |
| `packages/mosaic/framework/tools/prdy/prdy-status.sh:69` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:172` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:173` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:174` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:175` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:176` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:177` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:178` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/qa/typecheck-hook.sh:16` | FIXED | Bash regex extracts the first field without a pipeline |
| `packages/mosaic/framework/tools/qa/typecheck-hook.sh:56` | FIXED | grep and bounded sed each read from a here-string |
| `packages/mosaic/framework/tools/tmux/send-message.sh:113` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/tmux/send-message.sh:124` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/wake/detector.sh:126` | FIXED | one awk reads the manifest directly and exits after the first exact key |
| `packages/mosaic/framework/tools/wake/detector.sh:270` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/wake/detector.sh:278` | FIXED | grep reads from a here-string |
| `packages/mosaic/framework/tools/wake/digest.sh:647` | FIXED | capture complete locator output, then select first line by parameter expansion |
| `packages/mosaic/framework/tools/wake/reconcile.sh:149` | FIXED | one awk reads the manifest directly and exits after the first exact key |
## Explicit withdrawn / non-load-bearing sites
| Baseline site | Verdict | Reason |
| ---------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------- | --- | --------------------------------------- |
| `tools/install.sh:182` | NOT-LOAD-BEARING | ` | | true` explicitly discards lookup status |
| `tools/install.sh:356` | UNREACHABLE-AND-WHY | `pnpm pack` writes one matching CLI tarball into a fresh directory immediately before lookup; citation withdrawn in #1099 |
| `tools/install.sh:357` | UNREACHABLE-AND-WHY | same fresh-directory invariant for gateway tarball; citation withdrawn in #1099 |
| `tools/install.sh:627` | NOT-LOAD-BEARING | ` | | true` explicitly discards lookup status |
| `scripts/agent/session-start.sh:70` | NOT-LOAD-BEARING | optional scratchpad lookup has ` | | true` |
| `packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh:58` | NOT-LOAD-BEARING | optional scratchpad lookup has ` | | true` |
| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:25` | UNREACHABLE-AND-WHY | withdrawn in #1099 after designed-input reachability measurement; preserved without re-litigation |
| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:27` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:30` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:32` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
| `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:34` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
## Tranche 2 — non-wake test harnesses
All 22 baseline sites below are `FIXED`; the checked-in tranche fixture is passed through the same scanner and asserts all 22 occurrences and 21 normalized identities (the same response-split line occurs twice).
| Baseline site(s) | Verdict | Construction |
| ------------------------------------------------------ | ------- | ------------------------------------------------------------- |
| `systemd/user/test-fleet-units.sh:148` | FIXED | capture tmux output, then grep via redirection |
| `git/test-issue-comment-readback.sh:283,302` | FIXED | parameter expansion splits status/body without `head` |
| `git/test-pr-review-gitea-comment.sh:228` | FIXED | parameter expansion splits status/body |
| `git/test-lane-brief-pr-linkage.sh:72` | FIXED | grep reads from a here-string |
| `git/test-pr-review-repo-host-override.sh:225-226` | FIXED | grep reads from a here-string |
| `orchestrator/smoke-test.sh:67,72` | FIXED | parameter expansion selects first line |
| `orchestrator/test-board-roll.sh:99-100` | FIXED | grep reads from a here-string |
| `quality/scripts/test-upgrade-durable-snapshot.sh:180` | FIXED | complete sorted output is read with `mapfile`, then indexed |
| `quality/scripts/test-upgrade-rollback.sh:339,356` | FIXED | direct `grep -m1` file reads; cleanup captures before testing |
| `tmux/test-send-message-socket.sh:37,38,44-46,68,72` | FIXED | capture commands complete before redirected grep assertions |
| `tmux/test-send-message-verdict.sh:34` | FIXED | grep reads from a here-string |
## Tranche 3 — wake validation harnesses
All 26 baseline occurrences (25 normalized identities; one preimage selector occurs twice) are `FIXED` and mechanically bound through the wake fixture and shared scanner.
| Baseline site(s) | Verdict | Construction |
| -------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `wake/test-wake-digest-quarantine.sh:567` | FIXED | complete match populations are captured, then first line selected by parameter expansion |
| `wake/test-wake-preimage.sh:182-183,346-347` | FIXED | jq `first(...)` reads each JSONL file directly |
| `wake/validate-973/microtest-wake-assert.sh:153,170-171,176,204-209,233-234,251-252,286-287` | FIXED | scalar assertions use here-strings; diagnostics use non-early sed ranges; source line captured before matching |
| `wake/validate-973/validate-973.sh:110,119,180,182,187` | FIXED | scalar assertions use here-strings; diagnostic truncation uses consuming sed ranges |
The scoped inventory is complete: 26 runtime/general + 22 non-wake tests + 26 wake tests fixed; 11 explicitly withdrawn or non-load-bearing sites retain their documented verdicts.
v1/docs/reports/security/756-security-review.md
+42
View File
@@ -0,0 +1,42 @@
---
kind: record
status: active
---
# Security Review — Issue #756
**Scope:** final current uncommitted Discord plugin, shared channel contract, gateway ingress, AgentService, and plugin registration delta
**Snapshot:** `plugins/discord/src/index.ts` SHA-256 `5ee6b6aa4e2ff349f137f76b918d02c1254e12066cb48b136048e57bef36fdb2`
**Verdict:** **APPROVE**
## Final remediation verification
| Area | Current evidence | Result |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Attachment confidentiality and integrity | Ingress accepts bounded attachment metadata only when URL is HTTPS, query-free, fragment-free, and credential-free. Count, aggregate size, field length, MIME, and finite non-negative size validation apply before dispatch; `sizeBytes` is signed and retained. | Pass |
| Trusted agent selection | Each binding names a required trusted `agentConfigId`; gateway resolves that config server-side and requires its configured name to equal the binding logical-agent ID. Client/provider input cannot select the agent for Discord ingress. | Pass |
| Privileged operation routing | Gateway revalidates the binding and requires the signed conversation identity to match the configured logical agent before approve/stop actions. Paired admin identity and one-time approval checks remain enforced. | Pass |
| Egress containment and delivery | Egress requires an aligned message/route, configured parent or exact observed thread target, and cleans response routes after completion, errors, typed-ingress failure, or bounded-map pressure. | Pass |
| Side-effect limits | Per guild/authorized-parent/user rolling message and thread limits execute before thread creation or dispatch. | Pass |
## Security controls reviewed
- Default-deny guild, parent-channel, user, configured pairing, and role checks precede rate consumption and all side effects.
- Gateway independently enforces Discord service authentication, HMAC integrity, allowlists, binding/role checks, attachment validation, and replay-ID rejection.
- Thread authorization uses only the Discord thread parent; category parents cannot authorize ingress.
- Agent-visible attachment references are explicitly labeled untrusted; binary content is not embedded. Persisted attachment name/URL values are redacted.
- Egress uses deterministic nonces, bounded transient retry, typed terminal errors, and does not send to forged targets.
- No secrets or message content were added to plugin logs.
## Verification evidence
| Command | Result |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `pnpm --filter @mosaicstack/discord-plugin test` | PASS — 44 tests; v8 coverage: 92.18% statements/lines, 86.55% branches, 100% functions |
| `pnpm --filter @mosaicstack/discord-plugin typecheck` | PASS |
| `pnpm --filter @mosaicstack/types typecheck` | PASS |
| `pnpm --filter @mosaicstack/gateway typecheck` | PASS |
| `pnpm --filter @mosaicstack/gateway exec vitest run src/plugin/discord-ingress.security.spec.ts src/agent/__tests__/agent-service-ownership.test.ts` | PASS — 29 tests |
| `git diff --check` | PASS |
No unresolved critical, high, medium, or low security findings were identified in the reviewed final delta.