diff --git a/docs/ADMIN-GUIDE/README.md b/docs/ADMIN-GUIDE/README.md index f3083d3d..0a3f33cf 100644 --- a/docs/ADMIN-GUIDE/README.md +++ b/docs/ADMIN-GUIDE/README.md @@ -1,6 +1,6 @@ # Administrator Guide -> **Status:** Scaffold only. No legacy page has been promoted into this book yet. +> **Status:** Partially migrated. Current SSO and local upgrade/recovery procedures are available; held procedures are labeled non-operative. This book is the canonical home for installation, configuration, deployment, routine operations, security controls, incident response, and recovery. User workflows belong in [`USER-GUIDE/`](../USER-GUIDE/); implementation and contributor material belongs in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/). @@ -9,17 +9,19 @@ This book is the canonical home for installation, configuration, deployment, rou - [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries. - [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths. - [Product requirements](../PRD.md) — normative requirements, currently marked draft. +- [Operations index](operations/README.md) — current local procedures and explicitly held operational outlines. +- [Security index](security/README.md) — current SSO provider configuration. ## Chapter map -| Chapter | Scope | Status | -| --------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------- | -| `installation/` | Prerequisites, installation, and first deployment. | Scaffold only. | -| `configuration/` | Environment, provider, tier, and runtime configuration. | Scaffold only. | -| `deployment/` | Topologies, rollout, migration, and upgrade procedures. | Scaffold only. | -| `operations/` | Health, observability, routine operation, and maintenance. | Scaffold only. | -| [`security/`](security/README.md) | Authentication, authorization, SSO, secrets, and security controls. | SSO provider guide is current; other pages are planned. | -| `recovery/` | Incident response, backup, rollback, and recovery. | Scaffold only. | +| Chapter | Scope | Status | +| ------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `installation/` | Prerequisites, installation, and first deployment. | Scaffold only. | +| `configuration/` | Environment, provider, tier, and runtime configuration. | Scaffold only. | +| `deployment/` | Topologies, rollout, migration, and upgrade procedures. | Scaffold only. | +| [`operations/`](operations/README.md) | Health, observability, routine operation, and maintenance. | Local upgrade/recovery is current; connector lease operations are held. | +| [`security/`](security/README.md) | Authentication, authorization, SSO, secrets, and security controls. | SSO provider guide is current; other pages are planned. | +| `recovery/` | Incident response, backup, rollback, and recovery. | Scaffold only. | Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice. diff --git a/docs/ADMIN-GUIDE/operations/README.md b/docs/ADMIN-GUIDE/operations/README.md new file mode 100644 index 00000000..c6ad5ce6 --- /dev/null +++ b/docs/ADMIN-GUIDE/operations/README.md @@ -0,0 +1,19 @@ +# Administrator Operations + +> **Status:** Partially migrated. Procedures explicitly identify whether they are current or held. + +## Current procedures + +- [Upgrade safety and recovery](upgrade-safety-and-recovery.md) — installed-CLI and local-PGlite upgrade, rollback, and framework-configuration recovery. + +## Held procedures + +- [Mos connector lease operations](mos-connector-lease-operations.md) — non-operative M1 outline while the gateway policy remains deny-all and no connector is activated. + +A held page is architecture and readiness context, not command authority. PostgreSQL, federated, bare-metal, Compose, Gateway/Web activation, and migration-runner procedures remain outside the current local route unless a later page explicitly removes the hold with verified evidence. + +## Related + +- [[ADMIN-GUIDE/README|Administrator guide]] +- [[ADMIN-GUIDE/security/README|Administrator security]] +- [[DEVELOPER-GUIDE/architecture/README|Architecture index]] diff --git a/docs/DEVELOPER-GUIDE/architecture/README.md b/docs/DEVELOPER-GUIDE/architecture/README.md index 97ece52c..153c4324 100644 --- a/docs/DEVELOPER-GUIDE/architecture/README.md +++ b/docs/DEVELOPER-GUIDE/architecture/README.md @@ -10,19 +10,21 @@ This chapter is the canonical home for Mosaic Stack's system model, component bo - [`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. +- [`channel-protocol.md`](channel-protocol.md) — current shared channel DTOs and Discord compatibility baseline, with unimplemented adapter work explicitly marked draft. +- [`decisions/mos-runtime-portability-m1.md`](decisions/mos-runtime-portability-m1.md) — current logical identity, connector lease, grant, audit, and fencing decision; connector activation remains held. 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. ## Planned pages -| Path | Purpose | Status | -| -------------------- | --------------------------------------------------------------------- | -------------- | -| `system-overview.md` | Platform boundary and major request, event, and agent-runtime flows. | Planned. | -| `component-map.md` | Apps, packages, plugins, and dependency ownership. | Planned. | -| `data-flow.md` | Data, event, and control-plane movement. | Planned. | -| `security-model.md` | Trust boundaries, authority, authentication, and authorization model. | Planned. | -| `decisions/` | Approved architecture decision records. | Scaffold only. | -| `rfcs/` | Proposals and protocol RFCs. | Scaffold only. | +| Path | Purpose | Status | +| ----------------------------------- | --------------------------------------------------------------------- | ------------------- | +| `system-overview.md` | Platform boundary and major request, event, and agent-runtime flows. | Planned. | +| `component-map.md` | Apps, packages, plugins, and dependency ownership. | Planned. | +| `data-flow.md` | Data, event, and control-plane movement. | Planned. | +| `security-model.md` | Trust boundaries, authority, authentication, and authorization model. | Planned. | +| [`decisions/`](decisions/README.md) | Approved architecture decision records. | Partially migrated. | +| `rfcs/` | Proposals and protocol RFCs. | Scaffold only. | Promoted pages must be linked here, from [`DEVELOPER-GUIDE/README.md`](../README.md), and from [`SITEMAP.md`](../../SITEMAP.md). Do not create duplicate architecture pages in `docs/mosaic-stack/` or the docs root. diff --git a/docs/DEVELOPER-GUIDE/architecture/decisions/README.md b/docs/DEVELOPER-GUIDE/architecture/decisions/README.md new file mode 100644 index 00000000..aee87b49 --- /dev/null +++ b/docs/DEVELOPER-GUIDE/architecture/decisions/README.md @@ -0,0 +1,15 @@ +# Architecture Decisions + +> **Status:** Current decision index. A decision describes an implemented and accepted boundary; draft proposals belong under `rfcs/` or `docs/plans/`. + +## Current decisions + +- [Mos runtime portability M1 — logical identity and fencing](mos-runtime-portability-m1.md) — implemented lease, grant, audit, policy, and fencing boundary; connector activation remains held. + +Decision pages do not override product requirements, API contracts, or executable behavior. Each page must identify implementation evidence, operational status, and explicit non-goals. + +## Related + +- [[DEVELOPER-GUIDE/architecture/README|Architecture index]] +- [[PRD|Product requirements]] +- [[ADMIN-GUIDE/operations/mos-connector-lease-operations|Held connector lease operations]] diff --git a/docs/SITEMAP.md b/docs/SITEMAP.md index 73a49354..479e009a 100644 --- a/docs/SITEMAP.md +++ b/docs/SITEMAP.md @@ -13,6 +13,12 @@ - [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. +- [Channel protocol architecture](DEVELOPER-GUIDE/architecture/channel-protocol.md) — shared channel DTOs and current Discord compatibility boundary; future adapters are labeled draft. +- [Architecture decisions index](DEVELOPER-GUIDE/architecture/decisions/README.md) — approved and implemented architecture decisions. +- [Mos runtime portability M1](DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md) — logical identity, connector lease, grant, audit, and fencing decision. +- [Administrator operations index](ADMIN-GUIDE/operations/README.md) — current local procedures and held operational outlines. +- [Upgrade safety and recovery](ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md) — installed-CLI/local-PGlite upgrade and framework recovery runbook. +- [Mos connector lease operations](ADMIN-GUIDE/operations/mos-connector-lease-operations.md) — held/non-operative M1 operations outline. - [API documentation index](API/README.md) — scaffold for the consolidated gateway contract. - [Reports index](reports/README.md) — review, audit, QA, security, and retained evidence. - [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations. @@ -60,7 +66,7 @@ Canonical pages added to a book must be linked from that book's README and this ## Official channel plugins -- [Channel protocol architecture](architecture/channel-protocol.md) — shared lifecycle, message, stable-route, authorization, and response-target contracts. +- [Channel protocol architecture](DEVELOPER-GUIDE/architecture/channel-protocol.md) — shared lifecycle, message, stable-route, authorization, and response-target contracts; future adapters are explicitly draft. - [Discord administrator configuration](guides/admin-guide.md#discord-ingress-security) — secrets, allowlists, bindings, role policy, and thread permissions. - [Discord user workflow](tess/USER-GUIDE.md#discord-conversations) — in-channel messages, mention-created threads, and runtime-transparent continuity. - [Channel plugin authoring](tess/PLUGIN-GUIDE.md#official-channel-adapter-contract) — requirements for future Matrix, Slack, and other official adapters. @@ -117,8 +123,8 @@ Canonical pages added to a book must be linked from that book's README and this - [Optional AI egress gateway ADR](architecture/ADR-MOS-EGRESS-GATEWAYS.md) — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies. - [Runtime-neutral Mos identity and failover mission](https://git.mosaicstack.dev/mosaicstack/stack/issues/754) - [Logical identity and connector lease/fencing implementation](https://git.mosaicstack.dev/mosaicstack/stack/issues/755) -- [M1 logical identity and fencing architecture](architecture/mos-runtime-portability-m1.md) -- [M1 connector lease operations](guides/mos-connector-lease-operations.md) +- [M1 logical identity and fencing architecture](DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md) +- [M1 connector lease operations](ADMIN-GUIDE/operations/mos-connector-lease-operations.md) — held/non-operative. ## Comms evolution — Matrix-native MACP (design, draft) diff --git a/docs/reports/README.md b/docs/reports/README.md index 7ee9c8ec..ec08c69d 100644 --- a/docs/reports/README.md +++ b/docs/reports/README.md @@ -8,10 +8,13 @@ Use the canonical guide, API contract, source, and tests to determine current be - [Documentation catalog and truth audit](documentation/2026-08-10-docs-catalog-audit.md) — migration inventory and static truth assessment. - [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 @@ -20,6 +23,7 @@ Use the canonical guide, API contract, source, and tests to determine current be ## 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. ## Retention rules diff --git a/docs/scratchpads/DOCS-IA-002-catalog-audit.md b/docs/scratchpads/DOCS-IA-002-catalog-audit.md index bf2715d5..3016d6e9 100644 --- a/docs/scratchpads/DOCS-IA-002-catalog-audit.md +++ b/docs/scratchpads/DOCS-IA-002-catalog-audit.md @@ -35,12 +35,12 @@ The four isolated worktrees were clean and removed after report collection. ### Implementation lanes -| Lane | Branch | Owned slice | State | -| ------------------- | --------------------------------- | ------------------------------------------------------ | -------- | -| `docs-channel-impl` | `docs/channel-protocol-migration` | Rewritten current channel architecture page only. | Running. | -| `docs-runtime-impl` | `docs/runtime-m1-migration` | M1 decision and held connector-lease operations guide. | Running. | -| `docs-upgrade-impl` | `docs/upgrade-recovery-migration` | Verified local upgrade/recovery administrator guide. | Running. | -| `docs-reports-impl` | `docs/report-evidence-migration` | Four byte-identical historical evidence moves. | Running. | +| Lane | Branch | Owned slice | State | +| ------------------- | --------------------------------- | ------------------------------------------------------ | ------------------------------------- | +| `docs-channel-impl` | `docs/channel-protocol-migration` | Rewritten current channel architecture page only. | Complete; cherry-picked as `00bdf8b`. | +| `docs-runtime-impl` | `docs/runtime-m1-migration` | M1 decision and held connector-lease operations guide. | Complete; cherry-picked as `631567d`. | +| `docs-upgrade-impl` | `docs/upgrade-recovery-migration` | Verified local upgrade/recovery administrator guide. | Complete; cherry-picked as `39987a5`. | +| `docs-reports-impl` | `docs/report-evidence-migration` | Four byte-identical historical evidence moves. | Complete; cherry-picked as `9f74187`. | Shared indexes, navigation, audit records, integration review, and final commits remain coordinator-owned. @@ -64,6 +64,7 @@ Shared indexes, navigation, audit records, integration review, and final commits - [x] Promote the lease-broker protocol, security, mutator-gate, and compaction-revocation contracts with their navigation and acceptance-test consumers. - [x] Remove the blanket `docs/reports/` ignore rule so canonical evidence can be staged and linted normally. - [x] Migrate the three-file #756 Discord evidence batch byte-identically and add a reports index. +- [x] Complete and integrate the four implementation-agent slices after independent scope and evidence review. ## Initial findings @@ -123,3 +124,8 @@ Shared indexes, navigation, audit records, integration review, and final commits | 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 | | #756 evidence migration | PASS — three reports moved byte-identically by SHA-256, no source/test consumers found, reports index and sitemap updated | +| Implementation agents | PASS — four isolated Luna lanes committed disjoint owned slices; coordinator reviewed and cherry-picked each commit | +| Second report batch | PASS — four historical evidence files moved byte-identically and added to the reports index | +| Channel architecture | PASS — verified DTO/Discord behavior is separated from draft Telegram, Matrix, registry, identity, and multiplexing work | +| Runtime portability M1 | PASS — current decision precision corrected; companion operations page is explicitly held/non-operative | +| Upgrade/recovery guide | PASS — installed-CLI/local-PGlite route only; PostgreSQL, Compose, migration, and Gateway/Web activation remain held |