docs(vrs): decompose into five subsystems along the realization axis

The flat tree conflated what a Plan IS with how it is stored. Separating
them gives the hierarchy a real axis: the data model is mechanism-agnostic,
and the on-disk catalog is one realization of it. VRS.SUB-R02 asks for
exactly this ("substantial data models become child VRS nodes"), and it is
why refines: edges here carry weight rather than decorate.

  01-data-model    CMP.DM-*    lineage, identity, divergence, progress,
                               acceptance, readiness — no storage knowledge
  02-artifacts     CMP.FS-*    layout, content identity, admission,
                               integrity, repair — one realization
  03-surface       CMP.SURF-*  the sanctioned way to read and change a Plan
  04-cli           CMP.CLI-*   operator interface; adds no semantics
  05-integrations  CMP.INT-*   catalog form and replication, consumed

Root keeps what must be true of the system (CMP-R01..R09) plus the
assumptions and tradeoffs; each node refines it for one layer. Dependency
direction is one-way: the model does not know it lives in files, and the
files do not know a CLI exists.

PlanPort renamed to Plan Surface — "port" imported a pattern name into the
vocabulary without saying what the thing does. PlanReceipt shortened to
Receipt.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QzRc44KbA3wfYYKFF9UDMa
agent-session-id: cdf2c185-eeb3-4a4d-8ce0-52885f145cac
agent-tool: Claude Code
agent-tool-version: 2.1.215
agent-model: claude-opus-4-8
agent-runtime-profile: /nix/store/acr8a3l2v366jgmwiq8xdrhgz1py0db5-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/sj1v5j91h8v8d1w9lca4040302lwrd6v-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@unknown-dirty

Author: schickling-assistant

context/.decisions/0001-compass-is-an-independent-authority.md

@@ -43,7 +43,7 @@ paths, schemas, event envelopes, or storage layouts.
 
 Other systems compose with Compass through opaque references, mutations,
 queries, and receipts. They may record operational facts referencing a
-PlanReceipt, but such facts never become Compass state. Compass exposes no
+Receipt, but such facts never become Compass state. Compass exposes no
 subcommand inside another tool's CLI namespace; a facade would make the
 namespace imply authority.
 

context/01-data-model/requirements.md

@@ -0,0 +1,88 @@
+# Requirements: Data Model
+
+> **Role.** What a Plan *is*, independent of how it is stored. This node defines
+> lineage, identity, divergence, progress, acceptance, and readiness as logical
+> structure; [02-artifacts](../02-artifacts/requirements.md) realizes it as
+> files. Each requirement `refines:` a `CMP-R*`.
+
+## Requirements
+
+### Lineage
+
+- **CMP.DM-R01 A Plan is a lineage of versions.** Each version records its
+  predecessors, so the history of intent is reconstructible from the versions
+  alone. _refines: CMP-R02._
+
+- **CMP.DM-R02 Every version carries a Rationale.** The reason for the revision
+  is part of the version, not metadata about it. _refines: CMP-R03._
+
+- **CMP.DM-R03 Head is derived.** The frontier of a Plan is computed from the
+  lineage rather than recorded, so no stored value can disagree with the
+  versions. Head is a set; ordinarily it has one member.
+  _refines: CMP-R02, CMP-R04._
+
+- **CMP.DM-R04 Divergence is a state, not an error.** Versions sharing a
+  predecessor are both valid and both reported. _refines: CMP-R04._
+
+- **CMP.DM-R05 Divergence resolves by authorship.** Reconciliation is an
+  ordinary version naming every predecessor it reconciles, with its own
+  Rationale. Nothing reconciles automatically, and a reconciliation may itself
+  diverge. _refines: CMP-R03, CMP-R04._
+
+- **CMP.DM-R06 An absent predecessor is not divergence.** A version whose
+  predecessor is unknown must be distinguished from one that disagrees. The
+  first ordinarily means state is still arriving; treating it as the second
+  writes permanent intent to resolve a transient condition.
+  _refines: CMP-R04, CMP-R05._
+
+- **CMP.DM-R07 Versions are attributable.** Each version records its author and
+  a logical time ordered against other versions of the same Plan. Reconciling
+  divergence requires knowing who wrote each side and in what order.
+  _refines: CMP-R03, CMP-R04._
+
+### Identity
+
+- **CMP.DM-R08 References are minted, not derived.** A Plan reference and a Step
+  reference are minted at creation and are independent of content, so revising
+  text preserves identity and a reader can follow one unit of work across the
+  whole lineage. _refines: CMP-R02._
+
+- **CMP.DM-R09 References survive concurrent minting.** Two machines minting at
+  the same time, without a coordinator, must not produce the same reference.
+  _refines: CMP-R04._
+
+- **CMP.DM-R10 Retired references are final.** A reference is never reused after
+  retirement, and identity changes — split, merge, replacement — are stated
+  explicitly rather than inherited silently. _refines: CMP-R02._
+
+### Progress and acceptance
+
+- **CMP.DM-R11 Progress is append-only.** Progress records never alter intent
+  and never create a version. Correction is a further record, never an edit.
+  _refines: CMP-R02._
+
+- **CMP.DM-R12 Acceptance is evaluable.** A Step's acceptance criterion is
+  expressible in a form Compass can evaluate against recorded evidence. Prose
+  may accompany it but is not the criterion, because readiness cannot fold over
+  prose. _refines: CMP-R01._
+
+- **CMP.DM-R13 Only Compass judges completion.** An external record never
+  completes a Step; completion follows from the Step's own acceptance criterion.
+  _refines: CMP-R01._
+
+### Readiness
+
+- **CMP.DM-R14 Readiness is derived.** What can be worked on now follows from
+  the Step graph at head, accepted progress, and gates. It is part of the model,
+  not a projection over it. _refines: CMP-R01._
+
+- **CMP.DM-R15 Readiness explains itself.** Every answer names the unsatisfied
+  dependencies and gates. An answer that cannot say why is neither trustworthy
+  nor debuggable, and this constrains what an acceptance criterion may express.
+  _refines: CMP-R01._
+
+- **CMP.DM-R16 Readiness is defined under divergence.** With more than one head
+  member, readiness is reported per member and labelled. It never selects a side
+  and never merges graphs, which would assert intent nobody authored. The normal
+  state of the system must not be an undefined state of its primary query.
+  _refines: CMP-R04._

context/01-data-model/spec.md

@@ -0,0 +1,92 @@
+# Spec: Data Model
+
+Realizes [requirements.md](./requirements.md). Storage is specified in
+[02-artifacts](../02-artifacts/spec.md) and is deliberately absent here.
+
+## Plan
+
+A Plan is a lineage of Versions plus the Progress recorded against them. It is
+named by a minted `PlanRef`.
+
+## Version
+
+| Field | Meaning |
+| --- | --- |
+| `plan` | the Plan this version belongs to |
+| `parent` | each predecessor; none for the first, several for a reconciliation |
+| `author` | who authored the revision |
+| `at` | logical time, ordered against other versions of this Plan |
+| `why` | the Rationale — required |
+| `goal` | the intent being pursued |
+| `step` | zero or more Steps |
+| `retired` | optional decommission flag |
+
+`at` is a logical counter, not wall-clock time: machines disagree about clocks
+and agree about causality, and ordering two sides of a divergence is a causal
+question.
+
+A version is identified by its content. Two versions with identical content are
+the same version; any difference makes a different one. This is what makes
+divergence observable rather than a lost write — see
+[02-artifacts](../02-artifacts/spec.md) for how identity is computed.
+
+## Step
+
+A Step carries a minted `StepRef`, the intended work, `depends_on` edges, an
+optional `supersedes` naming the Step it replaces, and an acceptance criterion.
+
+Step identity is minted rather than derived from content, because a Step's
+reference must survive rewording of the same intended work. Version identity is
+derived from content, because a version's identity *should* change whenever its
+bytes do. The two layers want opposite properties and therefore use different
+mechanisms; this asymmetry is deliberate.
+
+## Lineage, head, divergence
+
+Head is the set of versions with no successor, computed by walking the lineage.
+
+- **Divergence** — two or more versions share a predecessor. Both are valid.
+- **Reconciliation** — an ordinary version naming several predecessors.
+- **Orphan** — a version whose predecessor is unknown locally.
+
+Divergence and orphan are superficially alike and must not be conflated: the
+first is a disagreement about intent, the second is ordinarily incomplete
+replication. Reconciling an orphan writes permanent intent to paper over a
+transient gap.
+
+A reconciliation can itself diverge, because nothing serializes authorship. Two
+machines observing one divergence may each reconcile it differently, producing a
+new divergence between the reconciliations. Compass reports this; it does not
+resolve it. This is the cost of CMP-T01, and it is why convergence is a reported
+condition rather than an assumed one.
+
+## Progress
+
+A Progress record names a Plan, a Step, the version it was observed against, an
+actor, and a payload: start, update, handoff, completion, evidence.
+
+Records are additive. A record against a superseded Step is attributed forward
+through `supersedes`; a record against a retired Step is retained but does not
+contribute to readiness.
+
+## Acceptance
+
+An acceptance criterion is a predicate over recorded evidence. It answers
+whether a Step is done, from what has actually been observed, without asking a
+judge.
+
+The predicate vocabulary is unresolved (DQ03). Its shape is constrained by
+CMP.DM-R15: a predicate that cannot report which of its parts failed makes
+readiness unexplainable, so expressive power that costs explainability is not a
+good trade here.
+
+## Readiness
+
+A Step is ready when it is not retired, its acceptance criterion is not yet
+satisfied, and every Step it depends on has a satisfied criterion.
+
+Every answer carries its reasons — which dependency or gate is unsatisfied.
+
+Under divergence, readiness is computed per head member and labelled with it.
+Merging the graphs would produce a plan nobody wrote; picking a side would hide
+a disagreement the model exists to surface.

context/01-integrations/requirements.md

@@ -0,0 +1,74 @@
+# Requirements: Artifacts
+
+> **Role.** One realization of the [data model](../01-data-model/requirements.md)
+> as files on disk: layout, identity, admission, integrity, and repair. The
+> model does not depend on this realization; this node depends on the model.
+> Each requirement `refines:` a `CMP-R*` or a `CMP.DM-R*`.
+
+## Requirements
+
+### Layout and identity
+
+- **CMP.FS-R01 The catalog root is configuration.** No storage location is
+  compiled in. _refines: CMP-R06._
+
+- **CMP.FS-R02 Version identity is the content.** A version's stored identity is
+  a hash of its content, so identical content is one version and any difference
+  is another. This is what makes divergence survive replication instead of
+  becoming a lost write. _refines: CMP.DM-R03, CMP.DM-R04._
+
+- **CMP.FS-R03 Content hashes never address Steps.** Step references are minted
+  values carried in the document, never derived from it.
+  _refines: CMP.DM-R08._
+
+- **CMP.FS-R04 Nothing records head.** No file names the current version. A
+  stored head is a cell two writers can contend on, and union replication cannot
+  merge one. _refines: CMP.DM-R03._
+
+- **CMP.FS-R05 Paths are machine-agnostic.** Authored content refers to
+  locations by variable rather than absolute path, so one catalog is valid on
+  machines with different layouts. An unresolvable reference fails loudly;
+  resolving it to an empty or plausible path is worse than failing.
+  _refines: CMP-R06._
+
+### Admission
+
+- **CMP.FS-R06 Admission is deliberate.** A file becomes state only in an
+  expected location and only when its content matches its recorded identity.
+  Parsing successfully is not sufficient. Under no-delete replication a wrongly
+  admitted file is permanent. _refines: CMP-R07._
+
+- **CMP.FS-R07 Identity mismatch is rejection.** A file whose content does not
+  match its identity is refused with a clear error, not accepted with a warning.
+  The mismatch is precisely the corruption signal.
+  _refines: CMP-R07, CMP.FS-R02._
+
+- **CMP.FS-R08 Received files are untrusted.** Files arriving by replication are
+  admitted on the same terms as local ones. No property conferred by the local
+  filesystem may be assumed to have survived the wire.
+  _refines: CMP-R07._
+
+### Integrity and repair
+
+- **CMP.FS-R09 Intent resists accidental edit.** Written intent is stored so
+  that an in-place edit fails visibly rather than succeeding silently. This
+  guards against error, not against a determined writer.
+  _refines: CMP-R02, CMP-T02._
+
+- **CMP.FS-R10 The lineage is checkable.** Compass verifies that every version
+  matches its identity and that every recorded predecessor is present, and
+  reports what is broken and where. _refines: CMP-R07._
+
+- **CMP.FS-R11 Repair never rewrites history.** Recovery from damage proceeds by
+  authoring new content that records the damage and continues from the last
+  intact predecessor. Editing or deleting a damaged version cascades through
+  every descendant, and deletion returns on the next sync.
+  _refines: CMP-R07, CMP-R02._
+
+- **CMP.FS-R12 Retirement is content.** Decommissioning is an authored flag.
+  Deletion is never the mechanism. _refines: CMP-R02._
+
+- **CMP.FS-R13 Unwritable content stays written.** Content that should never
+  have been recorded cannot be recalled from replicas. Compass can mark it inert
+  and flag it; it cannot make it absent. This is a property to design around,
+  not a gap to close. _refines: CMP-T03._