veronica
12d5258e20
A - docs/README.md:149-190 rewritten. It prescribed a competing front-matter schema
(title/type/audience/status/source_of_truth) adopted by 4 of 128 live documents. Two
documented conventions in one repo is the defect this pass removes, so the README now
documents the contract and the 4 files convert in the same commit: `type` dropped
(kind replaces it), `title`/`audience`/`source_of_truth` kept.
B - source-of-truth leaves the kind enum, which is now 6 values, and returns as an orthogonal
boolean. kind was carrying two independent facts. docs/requirements/native-kanban-sot.md
is stamped `kind: spec` + `source_of_truth: true`, which is what it always was.
C - status gains `completed`. Applied to the two executed plans, on artifact evidence rather
than on their own say-so: --purpose push|merge ships in ci-queue-wait.sh, and every section
the README plan specifies exists in docs/README.md today.
D - kind follows content, never filename. docs/native-kanban-sot/TASKS.md is `kind: spec`
because its body says "a build plan, not a task tracker". The name stays wrong; that is a
rename and it is out of scope here.
E - the contract covers .md only, written into the README as a decision with vision's
YAML.parse measurement as the reason, so the omission does not read as an oversight.
F - channel-protocol.md guide -> spec. Applied, with a correction the reviewer should see: the
ruling cites "7 normative MUSTs" and there are ZERO uppercase RFC2119 terms in that file.
Control: the identical grep returns 25 lines in docs/requirements/native-kanban-sot.md. The
citation half of the finding does hold and is larger than stated. Consequence recorded in
the worklist: the file's own banner now contradicts its header.
Verified: 128 live .md under docs/ (127 baseline + this PR's worklist), 107 stamped, 0 invalid
kinds, 17 operator-held + 3 supersede-stamp deferrals + 1 generated = 21 unstamped. 107+21=128.
Control: the verifier reports valid=False when a kind is corrupted to `nonsense`, so the
0-invalid result is a real result. prettier --check clean across docs/.
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.