veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
kind, status
| kind | status |
|---|---|
| guide | active |
Architecture
Status: Partially migrated. The lease-broker security-contract pages below are current references; the remaining architecture pages are still being classified.
This chapter is the canonical home for Mosaic Stack's system model, component boundaries, data and control flow, security model, architecture decisions, and RFCs. It explains why the system has its shape; it does not replace PRD.md, TASKS.md, or the API contract.
Promoted pages
lease-broker-protocol.md— authenticated Unix-socket protocol, identity binding, framing, persistence, and lease transitions.lease-broker-security.md— identity, ancestry, filesystem, whole-class, observer, and named residual security boundaries.mutator-class-gate.md— default-deny tool authorization, runtime adapters, launch choke point, and parser assurance boundary.compaction-revocation.md— Claude/Pi observer lifecycle, runtime generations, revocation, and the bounded residual stale window.channel-protocol.md— current shared channel DTOs and Discord compatibility baseline, with unimplemented adapter work explicitly marked draft.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. | Partially migrated. |
rfcs/ |
Proposals and protocol RFCs. | Draft egress RFC indexed. |
Draft RFCs
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, and from SITEMAP.md. Do not create duplicate architecture pages in docs/mosaic-stack/ or the docs root.
Migration backlog — not current architecture
docs/README.md— current documentation contract and placement rules.Documentation information architecture design— approved documentation structure decision, not product architecture.Documentation catalog audit— evidence and migration recommendations, not normative architecture.
Source-of-truth boundary
Architecture pages explain approved design and current system boundaries. Requirements remain in PRD.md; active work remains in TASKS.md; executable behavior remains authoritative in source and tests. Draft proposals belong in rfcs/ or docs/plans/, with status clearly labeled.