From 64f65307bb4604401616201d86639197c33e40ed Mon Sep 17 00:00:00 2001 From: James Ross Date: Mon, 24 Aug 2026 08:51:34 -0700 Subject: [PATCH 1/3] Document durable decision policy --- AGENTS.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index de24b05e..cc3555a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,6 +68,41 @@ 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 + +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. + +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`. From ccb0f34b2a7327d2b48a86e7c8003f74f6e49e54 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 6 Sep 2026 22:52:42 -0700 Subject: [PATCH 2/3] Fix: give the durable decision policy one canonical owner The policy assigns workflow policy to `docs/method/` and requires linking to a canonical owner instead of copying a rule into several places. It then stated itself, in full, in AGENTS.md -- violating both of its own rules in the act of declaring them. Moves the policy body to docs/method/durable-decisions.md, which the policy names as the owner of workflow policy, and leaves AGENTS.md with a link plus the agent-specific enforcement clause. Adds the new document to the AGENTS.md router, as rule 3 requires. Records the canonical-owner assignments as a table in the owning document. Regression coverage in spec/audit-docs.spec.mjs asserts the policy rules appear in exactly one document and that the router names the owner. Both assertions fail at 64f65307. Addresses review threads PRRT_kwDOSCKBn86bwuw6 and PRRT_kwDOSCKBn86bwvLA. --- AGENTS.md | 37 +++++++------------------ docs/method/durable-decisions.md | 46 ++++++++++++++++++++++++++++++++ spec/audit-docs.spec.mjs | 32 ++++++++++++++++++++++ 3 files changed, 88 insertions(+), 27 deletions(-) create mode 100644 docs/method/durable-decisions.md diff --git a/AGENTS.md b/AGENTS.md index cc3555a8..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. @@ -70,33 +72,14 @@ you make the commit for that slice. ## Durable Decision Discipline -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. +`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 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 14c534f5..66901e4b 100644 --- a/spec/audit-docs.spec.mjs +++ b/spec/audit-docs.spec.mjs @@ -71,3 +71,35 @@ test('Jim logo is original project artwork with explicit metadata', () => { assert.match(logo, /Original Jim project logo/); assert.match(logo, /Apache-2\.0/); }); + +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/); +}); From 4b0f1e66e99bcbf09f68ad4f8a38ceab24275f57 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 6 Sep 2026 22:52:52 -0700 Subject: [PATCH 3/3] Fix: route target ownership to its declared owner The policy names `docs/jim-component-ownership.md` as the owner of the Jim/Jedit/Edict/Echo target ownership and causal model, while ARCHITECTURE.md carried a competing normative "Target Ownership" section restating the same component responsibilities in fewer words. The two had already diverged, which is the concrete cost the policy exists to prevent: ARCHITECTURE.md called `Jim.edict` "Jim's mind" while the owning document calls `jim.core` "Jim's mind". Two documents, two names for one component. One rule in that section existed nowhere else -- the prohibition on Echo carrying Jim vocabulary (`ReplaceRange` variant, rope intrinsic, `Buffer` or `TextWindow` semantics, native Jim planner callback, `MutationPlan`, caller-authored graph patch). It is target-ownership law, so it moves into the owning document rather than being deleted with the duplicated prose. ARCHITECTURE.md now routes to the owner and states no ownership rule of its own. Regression coverage asserts the component rule appears only in the owning document and that ARCHITECTURE.md links to it; the assertion fails at 64f65307. Addresses review thread PRRT_kwDOSCKBn86bwvLF. --- ARCHITECTURE.md | 33 ++++++++------------------------- docs/jim-component-ownership.md | 11 +++++++++++ 2 files changed, 19 insertions(+), 25 deletions(-) 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