mosaicstack/stack
1
0
Fork 1
Code Issues 245 Pull Requests 7 Actions Packages Projects Releases 15 Wiki Activity

docs: integrate second autonomous migration wave

Browse Source
This commit is contained in:
Jason Woltje
2026-08-10 18:33:02 -05:00
parent 6b3ebce343
commit 16920c4a6f
8 changed files with 75 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ADMIN-GUIDE/security/README.md
+4 -3
View File
@@ -1,16 +1,17 @@
# Security
> **Status:** Initial migration active. The SSO provider runbook is current; other security pages remain planned.
> **Status:** Partially migrated. The SSO provider and Discord ingress security pages are current.
This chapter will contain authentication, authorization, SSO, secrets, RBAC, and security-control guidance for administrators.
## Planned pages
- [`sso-providers.md`](sso-providers.md) — current provider configuration, discovery, callbacks, and failure modes.
- `secrets.md` — document secret handling after source/configuration verification.
- [`discord-ingress.md`](discord-ingress.md) — current Discord service authentication, allowlists, bindings, roles, replay, and failure controls.
- `secrets.md` — document general secret handling after source/configuration verification.
- `rbac.md` — document roles and permissions from the canonical implementation.
The current SSO page reflects the dynamic provider-discovery behavior. Do not revive the retired root document or add frontend feature flags that the web flow does not consume.
The current SSO page reflects dynamic provider discovery. The Discord page documents only the verified Discord compatibility boundary; it does not claim Telegram or Matrix parity. Do not revive retired root documents or add frontend feature flags that the web flow does not consume.
## Related
docs/DEVELOPER-GUIDE/README.md
+14 -10
View File
@@ -1,6 +1,6 @@
# Developer Guide
> **Status:** Partially migrated. The architecture chapter contains the promoted lease-broker security-contract pages; contributor chapters remain unmigrated.
> **Status:** Partially migrated. Architecture, lease-broker verification, and channel-adapter authoring pages are current; other contributor chapters remain unmigrated.
This book is the canonical home for architecture, package and application guides, local development, testing, contribution workflow, and integration authoring. User-facing procedures belong in [`USER-GUIDE/`](../USER-GUIDE/); operator procedures belong in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); API contracts belong in [`API/`](../API/).
@@ -13,14 +13,19 @@ This book is the canonical home for architecture, package and application guides
## Chapter map
| Chapter | Scope | Status |
| ----------------------------------------- | -------------------------------------------------------------------- | ------------------- |
| [`architecture/`](architecture/README.md) | System model, components, data flow, security model, ADRs, and RFCs. | Partially migrated. |
| `packages/` | Package- and application-level contracts and guides. | Scaffold only. |
| `local-development/` | Safe local setup and development routes. | Scaffold only. |
| `testing/` | Test strategy, verification, and quality gates. | Scaffold only. |
| `contributing/` | Contribution, review, and delivery workflow. | Scaffold only. |
| `integrations/` | Plugin, provider, and adapter authoring. | Scaffold only. |
| Chapter | Scope | Status |
| ----------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------- |
| [`architecture/`](architecture/README.md) | System model, components, data flow, security model, ADRs, and RFCs. | Partially migrated. |
| `packages/` | Package- and application-level contracts and guides. | Scaffold only. |
| `local-development/` | Safe local setup and development routes. | Scaffold only. |
| `testing/` | Test strategy, verification, and quality gates. | Lease-broker verification boundary is current. |
| `contributing/` | Contribution, review, and delivery workflow. | Scaffold only. |
| `integrations/` | Plugin, provider, and adapter authoring. | Channel-adapter authoring boundary is current. |
### Current contributor pages
- [Lease-broker operations and verification](testing/lease-broker-operations.md) — safe static/test commands plus explicitly held live operations.
- [Channel adapters](integrations/channel-adapters.md) — current shared contracts and Discord reference boundary; future adapter parity is draft.
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
@@ -31,7 +36,6 @@ These are source candidates or stale records, not verified current instructions:
- [`archived TUI PRD`](../archive/tui/PRD-TUI_Improvements.md) — contradicted/stale; it references a missing `packages/cli`, while current TUI code is under `packages/mosaic`.
- [`archived TUI task ledger`](../archive/tui/TASKS-TUI_Improvements.md) — historical task ledger; its status and worktree claims require revalidation.
- [`_old_structure/guides/dev-guide.md`](../_old_structure/guides/dev-guide.md) — historical source; verify paths and commands before promotion.
- [`_old_structure/architecture/`](../_old_structure/architecture/) — historical architecture sources; classify each page before migration.
Do not make a legacy or archived page current by linking it from a chapter as if it were already promoted.
docs/DEVELOPER-GUIDE/architecture/README.md
+12 -9
View File
@@ -17,14 +17,18 @@ These pages are current security-contract references and are consumed by the lea
## 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/`](decisions/README.md) | Approved architecture decision records. | Partially migrated. |
| `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/`](rfcs/README.md) | Proposals and protocol RFCs. | Draft egress RFC indexed. |
### Draft RFCs
- [`rfcs/optional-ai-egress-gateways.md`](rfcs/optional-ai-egress-gateways.md) — proposed model-egress boundary; not approved or integrated.
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.
@@ -33,7 +37,6 @@ Promoted pages must be linked here, from [`DEVELOPER-GUIDE/README.md`](../README
- [`docs/README.md`](../../README.md) — current documentation contract and placement rules.
- [`Documentation information architecture design`](../../plans/2026-08-10-docs-information-architecture-design.md) — approved documentation structure decision, not product architecture.
- [`Documentation catalog audit`](../../reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations, not normative architecture.
- [`_old_structure/architecture/`](../../_old_structure/architecture/) — remaining historical sources; each page requires classification and claim verification before promotion.
## Source-of-truth boundary
docs/DEVELOPER-GUIDE/architecture/rfcs/README.md
+15
View File
@@ -0,0 +1,15 @@
# Architecture RFCs
> **Status:** Current proposal index. RFCs are draft design material and have no operational or implementation authority until an approved decision and implementation evidence supersede them.
## Draft proposals
- [Optional AI egress gateways](optional-ai-egress-gateways.md) — proposed model-egress boundary; LiteLLM and Bifrost are not integrated, and Claudex remains experimental harness tooling.
A draft RFC must not be cited as a supported feature, deployment path, or approved architecture decision. Approved implemented boundaries belong under [`../decisions/`](../decisions/README.md).
## Related
- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
- [[DEVELOPER-GUIDE/architecture/decisions/README|Architecture decisions]]
- [[PRD|Product requirements]]
docs/DEVELOPER-GUIDE/operations/lease-broker-operations.md → docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md
View File
docs/SITEMAP.md
+11 -5
View File
@@ -19,6 +19,12 @@
- [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.
- [Lease-broker operations and verification](DEVELOPER-GUIDE/testing/lease-broker-operations.md) — safe static/test workflow with live procedures held.
- [Optional AI egress gateways RFC](DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md) — draft proposal; no candidate is integrated.
- [Web dashboard](USER-GUIDE/product/web-dashboard.md) — current routes, views, chat persistence, settings, and admin behavior.
- [Discord conversations](USER-GUIDE/workflows/discord-conversations.md) — current authorized Discord workflow.
- [Discord ingress security](ADMIN-GUIDE/security/discord-ingress.md) — current service authentication, allowlist, binding, role, and replay controls.
- [Channel adapter authoring](DEVELOPER-GUIDE/integrations/channel-adapters.md) — current shared contract and Discord reference boundary.
- [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.
@@ -32,7 +38,7 @@ Canonical pages added to a book must be linked from that book's README and this
## Compaction refresh lease broker
- [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.
- [Broker operations](DEVELOPER-GUIDE/testing/lease-broker-operations.md) — safe static/test workflow; live startup, recovery, mutation, and cleanup remain held.
- [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](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.
@@ -67,9 +73,9 @@ Canonical pages added to a book must be linked from that book's README and this
## Official channel plugins
- [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.
- [Discord administrator configuration](ADMIN-GUIDE/security/discord-ingress.md) — secrets, allowlists, bindings, role policy, and thread permissions.
- [Discord user workflow](USER-GUIDE/workflows/discord-conversations.md) — in-channel messages, mention-created threads, and runtime-transparent continuity.
- [Channel plugin authoring](DEVELOPER-GUIDE/integrations/channel-adapters.md) — current shared contract and requirements for future adapters.
- [Discord package guide](../plugins/discord/README.md) — package behavior, configuration shape, and development commands.
## Native Kanban and canonical task SOT
@@ -120,7 +126,7 @@ Canonical pages added to a book must be linked from that book's README and this
## Runtime-neutral Mos portability
- [Optional AI egress gateway ADR](architecture/ADR-MOS-EGRESS-GATEWAYS.md) — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies.
- [Optional AI egress gateway RFC](DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md) — draft placement and gates for LiteLLM, Bifrost, and translation proxies; no candidate is integrated.
- [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](DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md)
docs/USER-GUIDE/README.md
+7 -2
View File
@@ -1,6 +1,6 @@
# User Guide
> **Status:** Initial migration active. The quickstart is current; additional user pages remain to be migrated.
> **Status:** Partially migrated. The quickstart, web-dashboard reference, and Discord conversation workflow are current.
This book is the canonical home for end-user workflows, user-visible behavior, product concepts, and user troubleshooting. Keep installation, deployment, security controls, and recovery procedures in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); keep implementation detail in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
@@ -9,6 +9,8 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths.
- [Quickstart](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session.
- [Web dashboard](product/web-dashboard.md) — current routes, navigation, chat persistence, projects/tasks views, settings, and admin behavior.
- [Discord conversations](workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow.
## Chapter map
@@ -16,12 +18,15 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
| `getting-started/` | First-use setup, orientation, and quickstarts. | Quickstart is current; additional pages are planned. |
| `concepts/` | User-facing terminology, product concepts, and mental models. | Scaffold only. |
| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Scaffold only. |
| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Discord conversation workflow is current. |
| `product/` | Current product surfaces and visible behavior. | Web dashboard reference is current. |
| `troubleshooting/` | User-visible failures, diagnostics, and fixes. | Scaffold only. |
### Current pages
- [Quickstart](getting-started/quickstart.md) — the verified installed-CLI first-use path.
- [Web dashboard](product/web-dashboard.md) — verified current Next.js dashboard behavior and limitations.
- [Discord conversations](workflows/discord-conversations.md) — verified current Discord user workflow.
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
docs/scratchpads/DOCS-IA-002-catalog-audit.md
+12 -6
View File
@@ -46,12 +46,12 @@ Shared indexes, navigation, audit records, integration review, and final commits
### Implementation wave 2
| Lane | Branch | Owned slice | State |
| ---------------------- | --------------------------------- | ---------------------------------------------------------- | -------- |
| `docs-channel-guides` | `docs/channel-audience-guides` | Discord admin, user workflow, and adapter-authoring pages. | Running. |
| `docs-lease-ops` | `docs/lease-operations-migration` | Current/held lease-broker operational boundary. | Running. |
| `docs-egress-rfc` | `docs/egress-rfc-migration` | Explicitly draft optional egress gateway RFC. | Running. |
| `docs-dashboard-guide` | `docs/dashboard-guide-migration` | Verified current web-dashboard user page. | Running. |
| Lane | Branch | Owned slice | State |
| ---------------------- | --------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `docs-channel-guides` | `docs/channel-audience-guides` | Discord admin, user workflow, and adapter-authoring pages. | Complete; cherry-picked as `f4faa3f`. |
| `docs-lease-ops` | `docs/lease-operations-migration` | Current/held lease-broker operational boundary. | Complete; cherry-picked as `6b3ebce`, then placed under the canonical testing chapter. |
| `docs-egress-rfc` | `docs/egress-rfc-migration` | Explicitly draft optional egress gateway RFC. | Complete; cherry-picked as `0692d99`. |
| `docs-dashboard-guide` | `docs/dashboard-guide-migration` | Verified current web-dashboard user page. | Complete; cherry-picked as `7fa0f65`. |
## Progress
@@ -74,6 +74,7 @@ Shared indexes, navigation, audit records, integration review, and final commits
- [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.
- [x] Complete wave 2 audience, testing, RFC, and dashboard migrations and connect every page to its owning index and sitemap.
## Initial findings
@@ -138,3 +139,8 @@ Shared indexes, navigation, audit records, integration review, and final commits
| 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 |
| Implementation wave 2 | PASS — four isolated Luna lanes produced scoped commits; coordinator reviewed, cherry-picked, and integrated each page |
| Channel audience guides | PASS — Discord admin/user/developer pages align to shared source/tests and explicitly deny Telegram/Matrix parity claims |
| Lease-broker verification | PASS — safe static/test workflow is current; startup, recovery, mutation, service management, and cleanup remain held |
| Optional egress RFC | PASS — proposal remains draft/non-operative; model and runtime-provider boundaries are separated and candidates are not integrated |
| Web dashboard guide | PASS — current routes, views, chat persistence, and absent project/task creation controls are documented from source/tests |