9 Commits

2 changed files with 39 additions and 3 deletions
+27 -3
View File
@@ -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
@@ -331,7 +332,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.
@@ -380,6 +383,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.
+12
View File
@@ -3,6 +3,18 @@
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: nothing.
3. `git fetch origin` and branch off `origin/main`, not the worktree left behind: `main` moved
under 4c mid-chunk and the branch needed a rebase before it could merge.
4. 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,