AGENTS.md

@@ -117,8 +117,9 @@ A message names the violation, not the rule alone — a rule by itself states a
 must invert before it reads as a failure — and where the flavour's claim refuses ordinary prose it
 names the escape that unclaims the form claimed: `\!adf:` for a directive, block line and inline
 alike, `\|` for every pipe row.
-Adding, removing or renaming a code is breaking, so a milestone meeting a new failure cause
-reuses a code where one fits; the list is complete at `0.1.0`. A code names the
+Adding, removing or renaming a code is breaking, so a new cause takes an existing code whose
+name reads true of it in both directions; where none does and a plain name exists, a new code — in
+any 0.x minor, and after 1.0 only in a MAJOR (the maintainer, 2026-09-18). A code names the
 cause; where one cause recurs across node types, across one mark's attributes or across
 directions, one code covers them all and
 `path` and `message` say which — `unsupported-nesting-depth` is the 500-level guard whichever
@@ -324,7 +325,9 @@ someone spells it or pins it.
   number is the markdown flavour's choice, not ADF's.
 - Explicit over implicit; descriptive names; no catch-all files (`utils`, `helpers`, `misc`); a
   file does not repeat its directory in its name — `adf/document.ts`, never
-  `adf/adf-document.ts`.
+  `adf/adf-document.ts`. A name is the noun `spec/flavour.md` or ADF's schema uses for the
+  thing; a directory follows a split the spec draws; a placement these rules leave open goes
+  beside its only reader, or in what both read where there are two (the maintainer, 2026-09-18).
 - Reuse before adding; the smallest sufficient diff is the benchmark; no speculative generality —
   a second consumer, or it goes.
 
@@ -373,6 +376,27 @@ Ask, don't guess: any choice where what the maintainer would pick is not near-ce
 and the answer lands as a decision in this file. The confidence bar is very high — asking too
 often is the accepted cost, guessing wrong is not.
 
+An ask is a gap in this file, and its answer is the rule that closes the gap, never the instance
+alone. Before asking, name the class the question belongs to and the earlier `(the maintainer, …)`
+entries of that class; where a rule already decides it, apply it without asking, and where the rule
+reads two ways on this input, that reading is the ask. Never ask "A or B?": state the gap, the
+earlier asks of its class, the nearest text here, a candidate rule in this file's voice and section,
+and the instance it yields, and ask for the rule. The maintainer answers the rule, the rule lands
+here, and the instance follows from it in the chunk. A rule that keeps collecting instances is
+wrong: rewrite it rather than append to it. `version` and `NPM_TOKEN` stay the maintainer's
+whatever any rule says.
+
+Rules the loop has settled (the maintainer, 2026-09-18):
+
+- A finding inside the chunk's item is fixed in the chunk. Outside it, a new `todo.md` item, always
+  in a release, weighed against every item on that release by the personas and §1–§3 — an item it
+  outweighs moves later. A weighing no rule decides is asked as a gap.
+- A stated number — 500 levels, the gate's seconds, the branch floor — is kept; a chunk that cannot
+  keep it asks, naming the number it can reach. A number the code needs and no rule states is a gap.
+- Where the shipping order names no release for the next unchecked item, the chunk is planning that
+  release: every unscheduled item weighed as above, the order written in `todo.md`, and the
+  maintainer's approval taken before any code.
+
 Reserved for the maintainer, never the agent: changing `version` in `package.json` (a bump on
 `main` publishes, §9 — every release is the maintainer's) and the `NPM_TOKEN` secret.
 

todo.md

@@ -3,6 +3,17 @@
 The plan. Design questions are settled in `AGENTS.md`; remaining spec detail is settled at its own
 milestone. A done item shrinks to its title here; its full text moves to `todo-history.md`.
 
+## Next session
+
+Start a session with: `Read AGENTS.md and todo.md, then do what todo.md's "Next session" says.`
+
+1. The first unchecked item in shipping order, per AGENTS.md §15 — or, where that item has no
+   release, the planning chunk §15 describes.
+2. In flight: 4c has uncommitted work in `.claude/worktrees/scanning-rule-sites` (branch
+   `4c-scanning-rule-sites`) and a stray `bench-4c.ts` that does not ship; continue from the diff.
+3. Before stopping, rewrite this section: the in-flight line, and the prompt itself wherever the
+   session found it wrong or short.
+
 ## Milestones
 
 Shipping order: 3h, 3i, 3j, 5a, 5b, 5c, 5d, 5 → `0.1.0` (shipped 2026-09-05); 3k, 11, 4, 12, 13, 4b, 4c, 14, 15, 16, 10, 5g → `0.2.0`;