diff --git a/docs/DEVELOPER-GUIDE/architecture/README.md b/docs/DEVELOPER-GUIDE/architecture/README.md index b2c4830b..97ece52c 100644 --- a/docs/DEVELOPER-GUIDE/architecture/README.md +++ b/docs/DEVELOPER-GUIDE/architecture/README.md @@ -7,6 +7,8 @@ This chapter is the canonical home for Mosaic Stack's system model, component bo ## Promoted pages - [`lease-broker-protocol.md`](lease-broker-protocol.md) — authenticated Unix-socket protocol, identity binding, framing, persistence, and lease transitions. +- [`lease-broker-security.md`](lease-broker-security.md) — identity, ancestry, filesystem, whole-class, observer, and named residual security boundaries. +- [`mutator-class-gate.md`](mutator-class-gate.md) — default-deny tool authorization, runtime adapters, launch choke point, and parser assurance boundary. - [`compaction-revocation.md`](compaction-revocation.md) — Claude/Pi observer lifecycle, runtime generations, revocation, and the bounded residual stale window. These pages are current security-contract references and are consumed by the lease-broker acceptance suites. Their live deployment gaps remain explicitly labeled in the pages; this migration does not change runtime behavior. diff --git a/docs/_old_structure/architecture/lease-broker-security.md b/docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md similarity index 96% rename from docs/_old_structure/architecture/lease-broker-security.md rename to docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md index 183f94b2..0209165a 100644 --- a/docs/_old_structure/architecture/lease-broker-security.md +++ b/docs/DEVELOPER-GUIDE/architecture/lease-broker-security.md @@ -1,5 +1,9 @@ # WI-1 lease broker security notes +> **Status:** Current contract reference. +> **Audience:** Developer and security reviewer. +> **Evidence:** The lease-broker implementation and acceptance material cross-check this boundary; deployment-review requirements remain explicitly labeled below. + - Trusted identity comes only from Linux `SO_PEERCRED` plus `/proc` starttime, never request identity fields. - Descendant authorization is anchored to `(pid,starttime)` and uses a complete second starttime pass to fail closed on disappearance or PID-reuse races. - Runtime generations are monotonic per anchor; a bump revokes prior-incarnation tokens before persistence commits. WI-3 stores the live generation in an owner-only locked file so same-PID Pi reload/new/resume/fork and Claude resume/clear transitions cannot inherit a VERIFIED lease. diff --git a/docs/_old_structure/architecture/mutator-class-gate.md b/docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md similarity index 96% rename from docs/_old_structure/architecture/mutator-class-gate.md rename to docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md index 522b5833..66f321e6 100644 --- a/docs/_old_structure/architecture/mutator-class-gate.md +++ b/docs/DEVELOPER-GUIDE/architecture/mutator-class-gate.md @@ -1,5 +1,9 @@ # Whole mutator-class lease gate +> **Status:** Current contract reference. +> **Audience:** Developer and security reviewer. +> **Evidence:** Runtime launch-guard and mutator-gate tests cross-check this boundary; parser residuals and deployment gaps remain explicitly labeled below. + WI-2 adds the framework-native authorization boundary for Claude (including the supported Claudex overlay) and Pi. Every runtime-reported tool name reaches the lease broker before execution. The gate classifies capabilities by the whole tool class; it never parses a Bash command to decide whether that particular string looks read-only. ## Default-deny policy diff --git a/docs/SITEMAP.md b/docs/SITEMAP.md index 544b188c..72f83cad 100644 --- a/docs/SITEMAP.md +++ b/docs/SITEMAP.md @@ -10,6 +10,8 @@ - [Developer guide index](DEVELOPER-GUIDE/README.md) — partially migrated contributor and architecture documentation. - [Architecture index](DEVELOPER-GUIDE/architecture/README.md) — system design, security contracts, decisions, and RFCs. - [Lease-broker protocol](DEVELOPER-GUIDE/architecture/lease-broker-protocol.md) — authenticated runtime lease-broker protocol and persistence boundary. +- [Lease-broker security notes](DEVELOPER-GUIDE/architecture/lease-broker-security.md) — identity, ancestry, filesystem, and residual security boundaries. +- [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny tool authorization and launch choke point. - [Compaction revocation lifecycle](DEVELOPER-GUIDE/architecture/compaction-revocation.md) — Claude/Pi lifecycle observers, generation fencing, and residual boundary. - [API documentation index](API/README.md) — scaffold for the consolidated gateway contract. - [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations. @@ -25,8 +27,8 @@ Canonical pages added to a book must be linked from that book's README and this - [Internal broker protocol](DEVELOPER-GUIDE/architecture/lease-broker-protocol.md) — kernel identity, ancestry and generation invariants, framed requests, responses, and persisted cycle bindings. - [Broker operations](guides/lease-broker-operations.md) — protected paths, startup, constrained recovery, fail-closed posture, distinct-principal deployment, and residual risk. - [Constrained recovery skill](../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md) — source-resident thin wrapper, receipt scope, C4 replay boundary, and T-C middle-drop disclosure. -- [Lease-broker security notes](architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements. -- [Whole mutator-class gate](architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary. +- [Lease-broker security notes](DEVELOPER-GUIDE/architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements. +- [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary. - [Compaction revocation lifecycle](DEVELOPER-GUIDE/architecture/compaction-revocation.md) — Claude/Pi observer matrix, same-PID generation rollover, failure fencing, and the named bounded residual stale window. ## CLI and skill management diff --git a/docs/scratchpads/DOCS-IA-002-catalog-audit.md b/docs/scratchpads/DOCS-IA-002-catalog-audit.md index 18dddcde..6bd1bf31 100644 --- a/docs/scratchpads/DOCS-IA-002-catalog-audit.md +++ b/docs/scratchpads/DOCS-IA-002-catalog-audit.md @@ -36,7 +36,7 @@ The four isolated worktrees were clean and removed after report collection. - [x] Archive the contradicted TUI PRD/task pair with unchanged content and an explicit archive index. - [x] Create and promote the verified user quickstart from the empty root placeholder. - [x] Rewrite and promote the SSO administrator runbook from current auth/web source evidence. -- [x] Promote the lease-broker protocol and compaction-revocation contracts with their acceptance-test path consumers. +- [x] Promote the lease-broker protocol, security, mutator-gate, and compaction-revocation contracts with their navigation and acceptance-test consumers. ## Initial findings @@ -55,7 +55,7 @@ The four isolated worktrees were clean and removed after report collection. - `PRD-TUI_Improvements.md` and `TASKS-TUI_Improvements.md` had no live source/test dependencies beyond their internal relative link; both moved unchanged to `docs/archive/tui/`, and `docs/archive/README.md` labels them historical. - The empty `docs/QUICKSTART.md` placeholder was replaced by `docs/USER-GUIDE/getting-started/quickstart.md`, based on verified installer, wizard, CLI, and runtime-safety behavior. The page explicitly excludes held PostgreSQL/source-checkout routes. - The SSO guide now documents Authentik/WorkOS/Keycloak discovery, OIDC callbacks, Keycloak SAML fallback, partial-config failures, and the absence of frontend feature flags. The root guide and stale `.env.example` flags were removed. -- The lease-broker acceptance suites directly consumed two quarantined `docs/architecture/` paths; promoting the protocol and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract paths without changing runtime behavior. +- The lease-broker acceptance suites directly consumed two quarantined `docs/architecture/` paths; promoting the protocol, security, mutator-gate, and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract family without changing runtime behavior. ## Method @@ -75,22 +75,22 @@ The four isolated worktrees were clean and removed after report collection. ## Verification log -| Check | Result | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| File inventory | PASS — 11 root files, 269 archived files, plus task artifacts | -| Initial link audit | FINDING — 219 links, 98 unresolved | -| Code-surface audit | PASS — corrected manifest/script and legacy-reference scans; first attempt was discarded due to a `require()` path bug | -| Truth probes | PASS — root docs, SSO, performance, TUI, OpenAPI, and source-path evidence triaged | -| Final report | Written — `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` | -| Scoped commit | PASS — audit plan, report, and scratchpad committed together; `.mosaic/orchestrator/*` remains outside the commit | -| Report formatting and scope | PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; ignored report path identified and force-add is required | -| Commit hook behavior | FINDING — lint-staged emitted an ignored `docs/reports` path error during commit even though the report was force-staged; remediation remains open | -| Index scaffold | PASS — six indexes formatted, all new Markdown/wikilinks resolve, and target directories exist; legacy pages were not changed | -| Sitemap scaffold | PASS — additive current section is formatted, all seven links resolve, and legacy sections are unchanged | -| First migration selection | PASS — P8-003 report selected as a no-rewrite evidence migration; live references identified before move | -| P8-003 migration | PASS — destination is byte-identical, live references were updated, formatting and navigation checks pass, and only the scoped migration files are pending commit | -| TUI archive migration | PASS — both pages are byte-identical, internal links and archive navigation resolve, formatting passes, and only the scoped archive files are pending commit | -| Quickstart migration | PASS — current page content is source-checked, held routes are labeled, navigation resolves, root placeholder is removed, and formatting passes | -| SSO migration | PASS — auth/gateway/web SSO tests pass (15+2+2), source claims and navigation resolve, obsolete env flags are removed, and the root guide is retired | -| Parallel Pi audits | PASS — four requested `openai-codex/gpt-5.6-luna:max` read-only lanes completed in clean isolated worktrees; no agent changes were imported | -| Lease-broker architecture | PASS — two contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed | +| Check | Result | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| File inventory | PASS — 11 root files, 269 archived files, plus task artifacts | +| Initial link audit | FINDING — 219 links, 98 unresolved | +| Code-surface audit | PASS — corrected manifest/script and legacy-reference scans; first attempt was discarded due to a `require()` path bug | +| Truth probes | PASS — root docs, SSO, performance, TUI, OpenAPI, and source-path evidence triaged | +| Final report | Written — `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` | +| Scoped commit | PASS — audit plan, report, and scratchpad committed together; `.mosaic/orchestrator/*` remains outside the commit | +| Report formatting and scope | PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; ignored report path identified and force-add is required | +| Commit hook behavior | FINDING — lint-staged emitted an ignored `docs/reports` path error during commit even though the report was force-staged; remediation remains open | +| Index scaffold | PASS — six indexes formatted, all new Markdown/wikilinks resolve, and target directories exist; legacy pages were not changed | +| Sitemap scaffold | PASS — additive current section is formatted, all seven links resolve, and legacy sections are unchanged | +| First migration selection | PASS — P8-003 report selected as a no-rewrite evidence migration; live references identified before move | +| P8-003 migration | PASS — destination is byte-identical, live references were updated, formatting and navigation checks pass, and only the scoped migration files are pending commit | +| TUI archive migration | PASS — both pages are byte-identical, internal links and archive navigation resolve, formatting passes, and only the scoped archive files are pending commit | +| Quickstart migration | PASS — current page content is source-checked, held routes are labeled, navigation resolves, root placeholder is removed, and formatting passes | +| SSO migration | PASS — auth/gateway/web SSO tests pass (15+2+2), source claims and navigation resolve, obsolete env flags are removed, and the root guide is retired | +| Parallel Pi audits | PASS — four requested `openai-codex/gpt-5.6-luna:max` read-only lanes completed in clean isolated worktrees; no agent changes were imported | +| Lease-broker architecture | PASS — four contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed |