diff --git a/AGENTS.md b/AGENTS.md index de24b05e..7d70f31f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,8 @@ These are hard repo rules, not suggestions: - `ARCHITECTURE.md` is the canonical repo architecture doctrine. - `docs/BEARING.md` records the current execution gravity. - `docs/method/process.md` is the canonical cycle workflow. +- `docs/method/durable-decisions.md` owns the durable decision policy and the + canonical-owner register. - `docs/method/roadmap-planning.md` defines release-gate, roadmap, slice, and proof policy for multi-cycle planning. - `docs/design/TEMPLATE.md` is the required template for full cycle designs. @@ -68,6 +70,22 @@ These are hard repo rules, not suggestions: Keep track of our progress in the plan doc by checking off slices just before you make the commit for that slice. +## Durable Decision Discipline + +`docs/method/durable-decisions.md` owns this policy. Read it before completing +any architecture, authority, identity, causal-settlement, recovery, +compatibility, ownership, public-API, or release-boundary decision. + +Agent-specific enforcement: a change carrying such a decision is not complete +until the canonical owner named in that document is updated in the same change. +Chat transcripts, Think memories, pull-request prose, and review threads may +motivate a decision; none of them is its repository home. + +Treat missing or stale canonical decision documentation as incomplete +engineering work, not optional polish. Historical design documents remain +evidence of their cycle; when durable current architecture changes, update the +current owning doctrine rather than relying on an old retrospective. + ## Design Cycle Workflow - Start full cycles from a fetched merge target, almost always `origin/main`. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ee36e1aa..b8d9f940 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -39,31 +39,14 @@ The broader project doctrine is written down in ## Target Ownership -The final application is Jim authored in Edict and realized by Echo: - -- Jedit, Bijou, and native adapters are Jim's body. They decode terminal and - process input into canonical events, install or address verified packages, - transport opaque runtime artifacts, and render disposable projections. -- `Jim.edict` is Jim's mind. It owns editor state, modes, operators, motions, - cursor and selection policy, registers, pending actions, input-event - interpretation, observation requests, application intents, and outcome - handling. -- Jim-owned Edict lawpacks own application operations and optics such as - `ReplaceRange`, `CreateBuffer`, `DeclareCheckpoint`, and `TextWindow`, plus - their fact schemas, identities, results, and typed obstructions. -- Edict owns source checking, Core IR, authority and lawpack closure, target - lowering, package construction, and structurally separate verification. -- Echo owns only generic runtime authority: installation, admission, budgets, - scheduling, bounded program interpretation, atomic ticks, WAL, receipts, - readings, recovery, and evidence. -- Graft owns structural intelligence and projections over bounded readings. It - has no Jim text authority and does not justify application vocabulary in Echo. - -Echo production code must never branch on or implement Jim/Jedit nouns or -verbs. In particular, Echo has no `ReplaceRange` variant, rope intrinsic, -`Buffer` or `TextWindow` semantics, native Jim planner callback, -`MutationPlan`, or caller-authored graph patch. Application coordinates may be -carried opaquely in packages, fixtures, and receipts. +`docs/jim-component-ownership.md` owns the Jim/Jedit/Edict/Echo target +ownership and causal model, including each component's territory, the five +non-negotiable causal clauses, and the vocabulary Echo must never carry. + +In one line: the final application is Jim authored in Edict and realized by +Echo, with Jedit, Bijou, and the native adapters as Jim's body. Every +normative rule about who owns what lives in the document above; this file does +not restate them. ## Non-Negotiables diff --git a/docs/jim-component-ownership.md b/docs/jim-component-ownership.md index fb36ce34..300236dd 100644 --- a/docs/jim-component-ownership.md +++ b/docs/jim-component-ownership.md @@ -1144,6 +1144,17 @@ effect, and executable-identity boundaries. Any implementation that cannot demonstrate them remains a compatibility or experimental composition rather than the canonical Jim architecture. +### Vocabulary Echo must never carry + +Echo production code must never branch on or implement Jim/Jedit nouns or +verbs. In particular, Echo has no `ReplaceRange` variant, rope intrinsic, +`Buffer` or `TextWindow` semantics, native Jim planner callback, +`MutationPlan`, or caller-authored graph patch. Application coordinates may be +carried opaquely in packages, fixtures, and receipts. + +This prohibition previously lived in `ARCHITECTURE.md`. It is target-ownership +law, so it belongs to this document; `ARCHITECTURE.md` now routes here. + ## Known claims gaps and active review questions The architecture is deliberately under review because several written claims diff --git a/docs/method/durable-decisions.md b/docs/method/durable-decisions.md new file mode 100644 index 00000000..21b19ac6 --- /dev/null +++ b/docs/method/durable-decisions.md @@ -0,0 +1,46 @@ +# Durable Decision Discipline + +This document owns the workflow policy for recording durable decisions. It is +the canonical home; `AGENTS.md` links here and adds only agent-specific +enforcement. + +Important decisions are incomplete until their durable owner is current. +Architecture, authority, identity, causal-settlement, recovery, compatibility, +ownership, public-API, and release-boundary decisions MUST be recorded in the +same change in the canonical document that owns the concept. Chat transcripts, +Think memories, pull-request prose, and review threads may explain or motivate +a decision, but they are not its canonical repository home. + +## For every such decision + +1. Identify one canonical owner before completing the change. + `ARCHITECTURE.md` owns repository-wide doctrine; + `docs/jim-component-ownership.md` owns the Jim/Jedit/Edict/Echo target + ownership and causal model; a focused `docs/design/` document owns a design + cycle; `docs/method/` owns workflow policy; and `docs/BEARING.md` owns current + execution gravity. +2. Record the accepted rule, its current-versus-target posture, and explicit + refinement, supersession, dependency, and related-document edges. +3. Update the relevant documentation entrance or router when a durable page is + added, moved, or renamed. +4. Link to the canonical owner from reader-specific pages instead of copying + the same rule into several places. +5. Keep implementation checklists in their cycle owner and live review or + delivery status in GitHub. Architecture documents define durable truth; they + are not a second pull-request dashboard. +6. Revisit the same canonical owner whenever later work refines the decision. + A refinement is not complete while code, schemas, packages, runtime + evidence, or release behavior disagree with the documented rule. + +## Ownership register + +| Concept | Canonical owner | +| --- | --- | +| Repository-wide architecture doctrine | `ARCHITECTURE.md` | +| Jim/Jedit/Edict/Echo target ownership and causal model | `docs/jim-component-ownership.md` | +| A design cycle | the focused `docs/design/` document for that cycle | +| Workflow policy, including this policy | `docs/method/` | +| Current execution gravity | `docs/BEARING.md` | + +Rule 1 applies to this document too: workflow policy belongs in `docs/method/`, +which is why the policy body lives here rather than in `AGENTS.md`. diff --git a/spec/audit-docs.spec.mjs b/spec/audit-docs.spec.mjs index 7e5a245e..b43f8276 100644 --- a/spec/audit-docs.spec.mjs +++ b/spec/audit-docs.spec.mjs @@ -62,3 +62,34 @@ test('documentation audit prompt covers all stale Advanced Guide runtime referen assert.match(audit, /`src\/main-workspace\.ts`/); assert.match(audit, /`src\/main\.ts` only remains the process entrypoint/); }); +const AGENTS = 'AGENTS.md'; +const DURABLE_DECISIONS = 'docs/method/durable-decisions.md'; +const ARCHITECTURE = 'ARCHITECTURE.md'; +const OWNERSHIP = 'docs/jim-component-ownership.md'; +const POLICY_RULE = /Identify one canonical owner before completing the change/; +const OWNERSHIP_RULE = /is Jim's mind/; + +test('the durable decision policy states its rules in exactly one document', () => { + const owner = readRepoText(DURABLE_DECISIONS); + const agents = readRepoText(AGENTS); + + assert.match(owner, POLICY_RULE); + assert.doesNotMatch(agents, POLICY_RULE); + assert.match(agents, /docs\/method\/durable-decisions\.md/); +}); + +test('the documentation router lists the durable decision owner', () => { + assert.match( + readRepoText(AGENTS), + /- `docs\/method\/durable-decisions\.md` owns the durable decision policy/, + ); +}); + +test('target ownership rules are stated only by their canonical owner', () => { + const owner = readRepoText(OWNERSHIP); + const architecture = readRepoText(ARCHITECTURE); + + assert.match(owner, OWNERSHIP_RULE); + assert.doesNotMatch(architecture, OWNERSHIP_RULE); + assert.match(architecture, /docs\/jim-component-ownership\.md/); +});