docs(vrs): intent is code, a version is a module, peer code is executed

Three decisions from the plans-as-code pivot.

0012 — intent is authored as code and identity is declared. A dependency
becomes a variable, so a reference cannot be invented or mistyped; a
revision becomes a function of its predecessor, so dropping a step is
unrepresentable rather than refused; a Step's identity is the name it is
declared under. Minting, write-back, provenance checking and the minted-
reference ledger all disappear together. Load-bearing and nearly missed:
the derived identity must be part of the hashed content, or renaming a
declaration re-identifies a Step invisibly.

0013 — the evidence vocabulary stays undeclared. Declaring it would put
vocabulary inside plan identity, so widening an enum would mint a version
of every plan carrying it with no change in intent. And no declaration can
reach across versions anyway, since evidence is evaluated at the current
frontier and the recorded version is provenance, not scope. The defect is
caught better by cross-checking a write against criteria already stored —
naming the criterion that was meant rather than reporting a type error.

0014 — a version is a module, and peer code is executed. Supersedes 0009.
The import idiom requires a prior version to BE a module, and the objection
to hashing source dissolves: a committed version is never reformatted, so
identity changing under alteration is the detection mechanism, not a
fragility. The consequence is stated rather than discovered — reading a
plan evaluates everything it imports, and under replication those modules
were authored elsewhere. A generated-binding shim was considered and
rejected as buying less than it costs. What makes it acceptable is the
capability boundary, which is now protecting against a peer rather than an
accident.

Also CMP-R11: starting a plan must be trivial. Made a requirement rather
than a preference because the vision claims nothing should tempt anyone to
keep plans elsewhere, and a checklist is always cheaper — a tool heavier at
the first step loses before its guarantees can matter. Testable: an agent
given a small task either reaches for it or does not.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ini/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/0012-intent-is-authored-as-code-and-identity-is-declared.md

@@ -0,0 +1,112 @@
+# Intent is authored as code, and identity is declared
+
+Status: accepted
+
+Supersedes the authoring surface of
+[0010](./0010-intent-is-authored-as-a-document-then-committed.md) and the
+minting mechanism of [0004](./0004-stepref-is-minted-not-content-derived.md).
+
+## Context
+
+Decision 0010 moved authoring from command arguments into a document, because a
+composition assembled inside one process has nowhere durable to live. That
+diagnosis was right and its consequences held: retries became idempotent,
+reconciliation became derivable.
+
+But the document carried three problems it could not solve. A reference had to
+be minted and written back, so a value the author never chose still had to
+survive in a file the author edits. A dependency was a reference typed as a
+string, so it could be mistyped or invented — an editing experiment across
+several document formats found that where a reference sits determines whether an
+author fabricates one, and that a plausible fabrication is the worst available
+outcome. And a document restates the whole plan to change one line, so the
+authoring surface was permanently exposed to a class of silent loss that had to
+be refused at commit rather than prevented.
+
+## Evidence and Argument
+
+Expressing intent in a programming language dissolves all three, because a
+language already has the mechanisms a document was imitating.
+
+A dependency is a **variable**, so a reference is never typed and cannot be
+invented, mistyped, or omitted. A revision is a **function of its predecessor**
+that takes edits, additions, and retirements, so there is no parameter capable of
+removing a step and the silent-loss class is unrepresentable rather than
+refused. A cross-plan reference is an **import**, resolved and checked rather
+than spelled.
+
+Identity follows from the same observation. A minted reference existed because
+content addressing breaks under rewording. But a declaration already has a
+stable, author-given, tool-checked handle — its **exported name**. Rewording the
+work does not touch it; renaming it breaks every importer loudly, where a
+mistyped random value fails silently. So identity can be *declared* rather than
+minted, and the entire apparatus that existed to make a random value durable —
+minting, write-back, provenance checking, and a ledger recording what was minted
+— disappears.
+
+This was proven rather than assumed. Evaluation is deterministic across
+repetitions and across engine versions; identity survives rewording; a retired
+step is carried forward and marked rather than omitted; a plan that reads the
+clock is refused; and renaming a declaration in a committed version changes its
+hash, so re-identification is detectable.
+
+That last property is conditional and was nearly missed: it holds **only because
+the derived identity is part of the hashed content**. Before that, renaming a
+declaration silently re-identified a step while the hash stayed constant. The
+requirement is therefore load-bearing, not incidental.
+
+The cost is real and stated plainly: intent is now a program, so evaluating it
+demands determinism and a capability boundary — see
+[0011](./0011-the-javascript-runtime-is-embedded-not-invoked.md).
+
+## Options
+
+| Option | Tradeoffs |
+| --- | --- |
+| Intent as code, identity declared | References cannot be invented; dropping is unrepresentable; cross-plan references are checked; no minting apparatus at all. Intent becomes a program that must be evaluated safely and deterministically |
+| Intent as a document, references minted | No evaluation and no capability boundary; a reference must be minted and made durable, dropping must be refused rather than prevented, and every dependency is a string an author can get wrong |
+| Intent as a document, identity content-derived | No minting; identity breaks the moment work is reworded, which is the ordinary case |
+| Intent as code, references still minted | Keeps a mechanism the language makes unnecessary, and reintroduces a value the author neither chose nor can verify |
+
+## Decision
+
+Intent is authored as code, evaluated to a canonical form, and stored
+immutably.
+
+A Step's identity is the **name it is declared under**, qualified by its Plan. It
+is not minted, not random, and not derived from content. It is assigned where the
+Step is first declared and carried forward by revision, so a Step that outlives
+many versions keeps the identity it was born with.
+
+A Step declared without a name has no identity and is refused. A name is never
+reused once retired.
+
+**The derived identity is part of the hashed content.** Without this, renaming a
+declaration re-identifies a Step invisibly.
+
+A revision is expressed as a function of its predecessor. It may edit, add, and
+retire; it has no way to remove. Steps are carried forward, so omission is not
+expressible and the drop-refusal of 0010 becomes unnecessary rather than
+enforced.
+
+Dependencies and cross-plan references are ordinary language references.
+
+## Consequences
+
+- Minting, write-back, reference provenance, and the minted-reference ledger are
+  all removed. Four mechanisms and one invented concept disappear together.
+- A rejected commit leaves authored content untouched, because nothing needs to
+  be written back into it. What 0010 could only approximate becomes literally
+  true.
+- Renaming a declaration is a change of identity. For a Step carried forward
+  this cannot arise, since it descends from its original declaration rather than
+  being re-declared; for a newly declared Step before commit it is harmless. It
+  is only consequential when editing already-committed source, which is
+  detectable and is itself a violation.
+- A Step must be a named declaration. Anonymous construction is refused, which
+  is a constraint on how intent is written.
+- Intent is a program. Everything about determinism and capability in 0011
+  follows from this decision, and neither can be relaxed independently.
+- The authored form and the stored form are now different artifacts. The stored
+  form is what replicates, what is hashed, and what is read; it is never
+  authored by hand.

context/.decisions/0013-the-evidence-vocabulary-stays-undeclared.md

@@ -0,0 +1,102 @@
+# The evidence vocabulary stays undeclared
+
+Status: accepted
+
+## Context
+
+Compass fixes the structure of a Plan and rejects unknown fields in it. It fixes
+nothing about the words used inside an acceptance criterion — the kinds of
+evidence and their attributes are supplied entirely by whoever writes the plan,
+and are validated by nobody.
+
+That produces a specific, silent defect. A criterion naming one spelling and an
+evidence record naming another leaves the criterion *valid* and permanently
+unsatisfied. Readiness reports the step as waiting, forever, in a way
+indistinguishable from work that simply is not done.
+
+The obvious remedy is to make the vocabulary declared, so criterion and evidence
+are checked against one definition.
+
+## Evidence and Argument
+
+Two findings, each sufficient on its own, argue against declaring it.
+
+**A declaration would put the vocabulary inside plan identity.** Identity is a
+hash of the whole body, so a vocabulary carried in a version means widening an
+enum or adding an attribute mints a substantive new version of *every plan that
+uses it* — with no change to intent whatsoever. A system whose central claim is
+that a version means intent changed would then manufacture versions nobody
+authored. Keeping the declaration outside the version instead makes it a
+dangling reference under replication, since the catalog replicates as files with
+no resolution root.
+
+**No declaration can reach across versions anyway.** Evidence is evaluated
+against the criterion at the current frontier, not against the version it was
+recorded under; the recorded version is provenance, not evaluation scope.
+Validation is therefore only ever possible at write time, and a narrowing
+revision leaves previously-valid evidence inert under every later criterion — the
+original symptom, now with a declaration certifying the evidence as fine.
+
+Against that, the defect is fully catchable without any declaration. The
+criteria are already in the version being written against, so a record can be
+checked against them at write time using only what is in memory. The domain of
+each attribute is derivable from the values the plan's own criteria bind — the
+plan supplies its own enumeration without declaring one. The resulting
+diagnostic is *better* than a declaration would give: not that a value is
+ill-typed, but which criterion was meant and how it differs.
+
+Two subtleties were found by prototyping the naive form and breaking it.
+Negation is idiomatic — "no known failure" — so a record matching the inner term
+of a negated criterion is not a mistake to correct but an outcome to report; only
+positively-stated criteria may suggest a correction. And a near-match is not
+evidence of a mistake, because a genuine alternative outcome differs from the
+expected one by exactly as much as a misspelling does. Both are handled by
+scoping to polarity and deriving the domain from the plan's own corpus, and the
+residual — a legitimate value no criterion happens to mention — is irreducible
+and is why this reports rather than refuses.
+
+## Options
+
+| Option | Tradeoffs |
+| --- | --- |
+| Undeclared, with a write-time cross-check | Catches the defect with a better diagnostic, no dependency, no schema, no effect on identity; cannot see values no criterion mentions, so it warns rather than refuses |
+| Declared, carried inside the version | Exact validation and static detection of unsatisfiable criteria; puts vocabulary inside identity, so a vocabulary change mints versions nobody authored |
+| Declared, carried outside the version | Identity untouched; becomes a dangling reference under replication, and a fix cannot reach what is already committed |
+| Undeclared, no checking at all | Nothing to build; the defect stays silent and indistinguishable from unfinished work |
+
+## Decision
+
+The evidence vocabulary remains undeclared. Compass does not define, validate, or
+adjudicate what evidence means.
+
+When a record is written, it is cross-checked against the acceptance criteria it
+could contribute to. A value outside the domain those criteria establish is
+reported, naming the criterion it most likely intended. This reports; it never
+refuses, because the derivable domain is necessarily incomplete.
+
+A record matching a negated criterion is reported as consequential rather than
+mistaken: it will withdraw acceptance rather than grant it.
+
+An attribute no criterion mentions remains accepted in silence. Matching is a
+subset relation by design, and evidence may legitimately carry more context than
+any criterion demands.
+
+Separately, a criterion that **contradicts itself** is detected when it is
+written. This is a strictly smaller claim than deciding whether a criterion can
+be satisfied — which is undecidable here, since satisfaction may depend on
+whether a named actor ever acts — and being smaller, it is a claim that can
+always be kept.
+
+## Consequences
+
+- Compass stays domain-neutral. Nothing in it names a kind of work, which is why
+  a plan for writing or research is expressible on the same terms as one for
+  software.
+- The defect is caught where it is made, with a diagnostic that names the
+  criterion rather than the type.
+- Some misspellings are missed — those whose value is plausible for a criterion
+  that does not exist. This is the accepted ceiling.
+- Compass records claims and does not certify their meaning, consistent with
+  evidence being a claim whose author is recorded rather than adjudicated.
+- A narrowing revision can strand previously-recorded evidence. Nothing here
+  prevents that, and reporting it is a separate concern from validating a write.

context/.decisions/0014-a-version-is-a-module-and-peer-code-is-executed.md

@@ -0,0 +1,94 @@
+# A version is a module, and peer code is executed
+
+Status: accepted
+
+Supersedes [0009](./0009-kdl-is-parsed-upstream-and-rendered-canonically-here.md).
+
+## Context
+
+Decision 0012 makes intent a program, so that a dependency is a variable and a
+prior Step is referenced by importing it. That idiom only works if a prior
+version **is a module** — a reference cannot be imported from a document.
+
+An earlier design kept a separate stored form and treated the authored source as
+transient. That is incoherent with the import idiom and was carried for one
+reason: the belief that hashing source makes formatting identity-bearing, and
+therefore fragile.
+
+## Evidence and Argument
+
+The objection dissolves on inspection. A committed version is immutable — nobody
+reformats one, because doing so is not an edit but a forgery. Identity changing
+under reformatting is not a fragility; it is the detection mechanism. A content
+hash carried in the filename makes any alteration of committed source visible,
+which is precisely the guarantee wanted.
+
+So a version is a module, stored as authored, named by the hash of its bytes.
+There is no second artifact, no canonical renderer to own, and no divergence
+possible between what was written and what was stored.
+
+The consequence has to be stated rather than discovered: **reading a plan
+evaluates it, and evaluating a version evaluates every version and plan it
+imports.** Under replication those modules were authored elsewhere. Compass
+therefore executes code that arrived from another machine.
+
+This was considered against two alternatives. Storing an evaluated form
+alongside the source only half-helps, since a successor importing a predecessor
+still evaluates the original. Generating data-only binding modules and importing
+those would avoid executing foreign authored logic entirely, at the cost of a
+generated artifact per version, a generator to keep honest, and an import that no
+longer refers to the module actually written.
+
+The direct form is chosen. A plan is code; running a peer's plan is running a
+peer's code, and pretending otherwise by interposing a generated shim buys less
+than it costs — the shim is still executed, and the honesty is worse.
+
+What makes this acceptable is not trust but the evaluation environment. A plan
+runs against an explicitly constructed global with no clock, no filesystem, no
+network, no dynamic code construction, and no capability the host did not name.
+A hostile plan can compute; it cannot reach anything.
+
+## Options
+
+| Option | Tradeoffs |
+| --- | --- |
+| A version is a module, imported directly | The import idiom works as written; one artifact; alteration detectable by hash. Reading executes code authored elsewhere |
+| A version is a module plus a stored evaluated form | Reads avoid evaluation; a successor still evaluates its predecessor, so foreign execution is only reduced, and two artifacts can disagree |
+| Imports resolve to generated data-only bindings | Foreign authored logic never runs; adds a generated artifact and a generator per version, and an import stops referring to the module written |
+| A version is a document; references are spelled | No execution at all; loses the import idiom, and returns every reference to a string that can be mistyped or invented |
+
+## Decision
+
+A committed version is the authored module, stored unchanged and named by the
+hash of its bytes.
+
+Altering committed source changes its hash and is detected. Committed source is
+never rewritten, reformatted, or migrated in place.
+
+Reading a plan evaluates it and everything it imports. **Compass executes modules
+authored on other machines.** This is a deliberate consequence of intent being
+code, not an oversight, and it is the reason the evaluation environment in 0011
+is a correctness boundary rather than a convenience.
+
+Evaluation is bounded. A plan that does not terminate, or that allocates without
+limit, is stopped and reported — executing foreign code makes resource
+exhaustion a reachable state rather than a theoretical one.
+
+## Consequences
+
+- One artifact per version. The authored form and the stored form are the same
+  thing, so they cannot drift.
+- Identity is the hash of source bytes. Whitespace is therefore significant, and
+  that is deliberate: it is what makes tampering visible.
+- Reads are expensive, because they evaluate. A derived, rebuildable index is
+  no longer an optimisation but a requirement for reading at scale.
+- The capability boundary carries far more weight than when only local drafts
+  were evaluated. Every exclusion in 0011 is now protecting against a peer rather
+  than against an accident, and relaxing any of them is a change to this
+  decision.
+- Execution must be bounded in time and memory. A denial of service is now the
+  most plausible hostile act, and it is the one the capability list does not
+  address.
+- A plan cannot be read on a machine that lacks its imports. An unreplicated
+  import is worse than a missing predecessor: the plan cannot be evaluated at
+  all, rather than merely showing an incomplete lineage.

context/06-evals/spec.md

@@ -105,7 +105,16 @@ asserted:
 | evidence contradicts | acceptance is a current reading, not a latch — CMP.DM-R12 |
 | a claim without standing | predicates bind recorded fields — decision 0008 |
 | a plan that is not code | the model is domain-neutral |
-
-The last one is deliberate. Nothing in the model mentions code, and a suite
-composed only of engineering scenarios would quietly make that claim false by
-never testing it.
+| an agent given a small task | starting is trivial — CMP-R11 |
+
+The domain-neutral scenario is deliberate. Nothing in the model mentions code,
+and a suite composed only of engineering scenarios would quietly make that claim
+false by never testing it.
+
+The last scenario is of a different kind and is the only one that cannot be
+asserted mechanically. CMP-R11 claims starting a plan is trivial enough that
+nobody reaches for a checklist instead — which is a claim about behaviour under
+choice, not about output. It is measured by giving an agent a small planning task
+with Compass available and observing whether it uses it, and it fails when the
+agent writes its own list. A scenario that merely drives the commands would prove
+the commands work while leaving the claim untested.

context/requirements.md

@@ -88,3 +88,16 @@ for one layer:
   store a wrong value is permanent. This constrains identity, ordering, and
   deduplication in particular: none of them may rest on something an actor
   chooses.
+
+- **CMP-R11 Starting a plan must be trivial.** Beginning a plan must cost one
+  command and produce something immediately workable, with nothing to import,
+  configure, or look up. Ceremony must scale with a plan's size, never with the
+  act of starting one.
+
+  This is a requirement rather than an ergonomic preference because the vision
+  claims nothing about the tool should tempt anyone to keep plans elsewhere, and
+  a hand-written checklist is always available and always cheap. A tool that is
+  heavier at the first step loses to the checklist before any of its guarantees
+  can matter. Whether it holds is observable — an agent given a small planning
+  task either reaches for Compass or does not — so it is testable rather than
+  asserted.