docs: integrate autonomous migration slices
This commit is contained in:
Jason Woltje
@@ -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.
|
||||
|
||||
|
||||
@@ -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]]
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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]]
|
||||
+9
-3
@@ -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)
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user