crenshawdev/cadence-archived

Fork 0

v3.6.0 - reading the corpus back #239

Merged

john merged 69 commits from cadence/v3.6.0 into main

2026-08-23 18:24:25 +00:00

john commented

2026-08-23 18:24:20 +00:00

Owner

Three phases, 66 commits off v3.5.9. /cad-why walks the record join, cite-count measures whether recall was read, and /cad-task leaves a record behind it. Audit PASS on both arms, 5 of 5 requirements traced, 21 of 21 acceptance criteria covered.

Closes #190, #191, #192.

john added 69 commits

2026-08-23 18:24:21 +00:00

chore: add phase 1 9809485988

/cad-why goes first because RBK-01 cannot read its own number without it. The
read-back gate counts how often a plan cites the corpus, and a near-zero count
has two readings that need opposite fixes: the planner ignored a good record, or
it correctly ignored a useless one. Nothing in the count separates them, so the
corpus gets read by hand first.

docs: capture context for phase 1 5bcf4a8c1d

docs: plan phase 1 - The corpus, read back at a file and line 40799ea72e

feat(1-1): why-query grammar and the two git invocations 8aeb289bc4

Pure module: split a positional <path>[:<line>] argument into a path and an
optional line with five distinct named refusals, build the bare-path and
line-scoped git log argv arrays (--follow/-L are mutually exclusive so they
stay separate builders, both pin -M and a fixed --format), and classify a
git result into ok/not-in-history/line-past-end/git-failed without carrying
any stderr bytes onward.

feat(1-1): why-render deterministic renderer and entry cap 683608d8aa

Pure module: sort a chain newest-first by commit date then full sha (both
descending, so a tied date and a reversed input array render identically),
carry the full sha with an 8-char abbreviation on the commit line, render a
fixed stated-absence line for each of the five join fields an entry lacks,
and cap the rendered chain at 10 entries with the untruncated total riding
the envelope and a truncation note inside the text itself.

feat(1-1): the /cad-why seam 417049d373

New top-level cadence-core/bin/why.mjs: runs the explicit not-in-history
probe before either chain query, dispatches the bare-path or line-scoped
git invocation from lib/why-query.mjs, classifies the result through the
same module, and emits one JSON object carrying the resolved path/line, the
chain entries and lib/why-render.mjs's pre-rendered text. The declared flag
door (--dir, --top) runs before the positional-query refusal so the
adoption census can prove each declared refusal by flag name with no
positional argument at all. Adds the why.mjs row to arg-contract.mjs's
CONTRACTS table, and extends why-render.mjs's renderChain to return its
sorted, capped entries alongside the rendered text.

feat(1-1): register the /cad-why command surface cbba5d59bb

The seam lands as a discoverable skill (D-14): a self-contained
skills/cad-why/SKILL.md that runs why.mjs and relays its text field
verbatim, allowed-tools Bash alone so this phase can neither write nor
dispatch. Its prescribed invocation single-quotes the caller-supplied
query, because a double-quoted $(...) or backtick in a path runs before
Node starts.

COMMANDS.md gains the Support-cluster row skills/cad-help renders, and
weight-budgets.json gains the skill's row and re-pins COMMANDS.md, which
the new row grows past its old ceiling. README's skill count moves 27 to
28, the figure prose-agreement.test.mjs counts on disk.

arg-contract.test.mjs's literal table counts move 168 to 170 and 16 to 17
to match the why.mjs CONTRACTS row.

feat(1-2): the SUMMARY commits-table reader, bound fence-aware and matched by prefix e287d3148b

feat(1-2): the storage-tier locator, one index over the live and archived phase directories 2d9ffbc517

feat(1-2): the phase and plan-task edge, read off the resolved directory 2d3f0eaa36

feat(1-2): the decision edge, cited by task or stated phase-scoped 781a178309

feat(1-2): the deviation edge names the marker the write side never emits 4c1ec3a4bc

feat(1-2): the surviving review finding edge, joined by commit range 3e0196358f

feat(1-2): the task-attributed declared-files edge, continuation lines included 6a0d5642e6

fix(1-2): contain readArtifact per file, not only per directory b5f49bad6a

phaseDirsIn contains the phase-directory walk against a symlink escaping
the planning root, and why-corpus.mjs's header says so. Every caller then
joins a NAME onto a contained directory, and statSync following that
name's own symlink put the escape back one level down: a SUMMARY.md
symlinked outside the tree passes isFile() and its bytes reach a seam
whose stdout is the place EXP-01 was about.

The resolved path must now stay inside the resolved directory it was
joined onto. A non-symlink resolves to itself and passes trivially; a
symlink pointing out is refused EESCAPE before it is opened, which also
closes the check-to-use race on the same line, since a path a symlink
names cannot be swapped for one outside the directory after a check it
never passed.

feat(1-3): the prune-commit search and its milestone label binding aa806a6c02

feat(1-3): the reverse commit-to-phase map, recovered out of git history e0ef35bf5b

feat(1-3): the recovered map reaches the chain, labelled by its milestone dcc411addc

feat(1-3): the remaining edges read their artifacts out of the prune parent 228990389b

feat(1-3): the named gap, and the phase number that is never guessed 2382a9a70f

docs(1): phase 1 summary cae92d7e04

Seventeen plan commits plus one orchestrator fix deliver /cad-why: a
queried path's commits joined to six record edges across the live
phases/ tier, the _archive-v<ver>/ tier and pruned milestones recovered
out of git history, with the gap named in words where no tier answers.

risk_surface fired once per plan on each committed range and passed all
three: plan 1 raised 2 and kept none, plan 2 raised 3 and its one
survivor is fixed in b5f49bad, plan 3 raised 1 and kept none. CONTEXT
D-10 and D-13 are corrected in place where plan deviations refuted them.
PLAN-1.md carries the lease widening approved at plan 1's structural
checkpoint.

docs: phase 1 UAT - 12 passed, 0 failed 93228fb4de

docs: point the cursor at /cad-phase add - v3.6.0 stays open 8c6d487ea8

chore: add phase 2 (the read-back gate) and phase 3 (the fast path leaves a record) 526b6792e9

docs: capture context for phase 2 5a0a87bf2c

docs: plan phase 2 - the read-back gate 6829a2c640

feat(2-1): the surfaced set, own-phase scoped and kinded 75269066da

feat(2-1): the cited mentions, bare and phase-qualified ee6738e02e

feat(2-1): the cite-count subcommand and its envelope bfd2180a41

One `planning.mjs` subcommand joins the two readers per item: the surfaced
set (bounded `results`, own-phase rows dropped, four kinds) against the
plan's D-NN mentions, scoped by phase. It REPORTS and never gates.

`cited_by_kind` carries all four arms always, with capture, deviation and
uat marked `unjoinable` rather than `cited: 0` - those artifacts carry no
identifier to join on, and absence and silence are different answers.

The `cite-count` row in CONTRACTS is one word, `--point` is refused against
its two values in the seam's own `bad-args` vocabulary, and the flag-entry
census moves 170 -> 173 for the three new rows.

feat(2-1): the memory.backend third state on cite-count 67288e9853

The handler reads the effective backend across the config layers, the same
read `cmdRecall` makes with the same `builtin` schema default. On `none`
the envelope carries `backend: 'none'` and `--payload` is neither required
nor read - there is no envelope to hand over, because the workflow skips
the call that would have produced one, and `cmdRecall` ignores its query on
the same arm.

That is what makes three runs separable by their recorded fields alone:
`backend: 'none'`, a `surfaced.count` of 0 without it, and a non-empty
`surfaced` with `cited.count` 0. No fourth field restates any of it, and
the envelope shape is identical on both paths.

A torn config layer reads the key as absent and would default a deliberate
`none` back to `builtin`, so `warnings[]` rides the envelope when non-empty.

refactor(2-1): one reader for memory.backend, not one per command 696fd59f31

`cmdCiteCount` inlined its own `mergeLayers` + `?? 'builtin'` pair beside
`cmdRecall`'s, which is exactly how the off switch comes to mean one thing
at the seam that produces the surfaced set and another at the seam that
counts it. Both now read `memoryBackend(dir)`.

It also keeps the check-12 census at fifteen callsites over nine files.
That census exists so a new callsite cannot be added without choosing an
arm; the arm chosen here is to add no callsite.

`warnings` is returned rather than surfaced - the reader has no envelope -
and both callers keep putting it on theirs unchanged.

test(2-1): the seam's stated behavior at the CLI c96796bb99

Five cases over scratch fixtures, spawning the real binary: the envelope's
two sides per item with the three unjoinable arms asserted as unjoinable
rather than as zero; the own-phase exclusion proved in BOTH directions on
one payload, so a rule that dropped both rows or kept both fails; two runs
byte-compared on raw stdout; the fixture's trace.jsonl read back and proved
to hold no lifecycle/dispatch, seeded with an anchor so an empty file
cannot pass it vacuously; and the three memory.backend states separated by
their recorded fields alone.

Falsifier run: deleting the own-phase exclusion from lib/cite-surfaced.mjs
fails exactly one of the five, the own-phase case.

feat(2-2): the count records itself in the run record a234348ea4

feat(2-2): the surfaced set reaches disk as this run's payload 22eede3669

feat(2-2): both count points, advisory at each b0eaab6b29

feat(2-2): the under-threshold path counts too 2eea242c46

feat(2-2): the report names the zero case, and does nothing about it b419b39968

chore(2-2): re-pin the weight budget and the seam-call census ba076f306d

fix(2-2): the carried scratch path refuses what it cannot survive 054fa9a03d

Every site that echoes a `mktemp -d` directory for a later Bash invocation to
paste back as a literal now refuses the path at creation unless it is drawn
from `[A-Za-z0-9._/-]`. The path is built from `$TMPDIR`, which the operator
does not always own - a cloned repo's `.envrc`, a devcontainer, a CI runner -
and a single `"` in it closes the argument at the use site and runs the rest of
the directory name as commands.

Refused at creation rather than quoted defensively at each use, because the
carried literal is unquoted by construction: the workflow prose tells the model
to paste the echoed value, so there is no single place a quoting rule could
hold. The class is deliberately narrow and a `TMPDIR` holding a space is
refused too, which is one `export` away from fixed, where a path that executes
is not.

All three sites, not just the one the gate fired on: `plan.md` had inherited
the pattern from `review-triggers.md`, and `triage-gate.md` carries a third
copy.

test(2-3): three runs, told apart by their records alone 86ad92c422

docs(2-3): the subcommand block names the write it makes 1341e1117d

docs(2): phase 2 summary e327bca838

docs: phase 2 UAT - 6 passed, 0 failed 3a7c72d4fe

docs: the UAT walk asks in plain words, and does not assume the check already ran cb3bd5d6a1

docs: capture context for phase 3 e4359f42cc

docs: plan phase 3 - The fast path leaves a record 0613d832fc

docs(3): the record lister contains the record file, not only its directory a5714cbfda

feat(3-1): one home for where a task record lives and what it looks like 9d52efd581

A new lib/task-record.mjs owns four facts the writer, the recall walk and
/cad-why's task tier would otherwise each hold their own version of: the
tasks/ directory and RECORD.md names, the slug predicate, the guarded lister
and the pure renderer.

The slug predicate REFUSES rather than sanitises - the VAL-01 lesson from
milestone-prune --label, which was only trimmed before being joined onto a
directory path. The lister contains its walk the way phaseDirsIn does and one
level further in: RECORD.md itself is resolved and required to land inside the
planning root, because the recall tier reads snippets straight out of the path
it returns.

The renderer's sections are the corpus's own grammar - ## What shipped for the
recall tier, a three-column ## Commits table parseCommitRows reads back, and a
last ## Files section taskDeclaredFiles reads back - so the record joins to
shipped readers instead of needing new ones.

feat(3-1): task-record, the subcommand that writes a task's record acbd00fe40

One-word `task-record` on planning.mjs, with a declared CONTRACTS row for its
five flags and the pinned entry count moved 173 -> 178 in the same commit, since
that assertion is what makes the contract walk non-vacuous.

Every figure is DERIVED from the range: one `git log` for the commits table and
one `git diff --name-only` for the declared-files line, both over the ids
resolveRange resolved. Nothing is retyped onto a flag, which is the
transcription surface D-07 names, and it is why a re-run over an unchanged range
rewrites byte-identical bytes.

A slug that is not one path segment is refused with nothing written. A tree with
no planning root gets neither one nor a tasks/ directory - written:false with a
reason, ok:true - and the outcome event lands before the envelope on every path
past argument validation, so a refusal still says a record was attempted.

The redactUrl census in planning.test.mjs answered the classification: the git
catch is wrapped, the mkdir/atomicWrite catch is not, because that detail is an
fs error over the path --dir just named.

feat(3-1): the recall corpus reaches the tasks tier 20884d6314

parseTaskRecordSnippets is its OWN reader beside parseSummarySnippets, not a
call to it: that one indexes ## Deviations and ## Open items alone, which is the
measured reason a task record was invisible to recall even in a SUMMARY shape -
a query naming exactly what a shipped task did returned five hits over 59 and
none from .planning/tasks/.

cmdRecall's walk gains the tier LAST, on the identical argument the ARCHIVE.md
walk makes for its own position: search() orders by score then corpus position,
so appending leaves every existing index where it was and a tree with no tasks/
emits the bytes it emitted before this walk existed - asserted against an empty
tasks/ directory rather than assumed.

No phase key on a task row. references/recall.md states phase is optional and
that a reader must never substitute an inferred one, and phase: 0 would be
exactly that.

docs(3-1): this repository's first real task record, written by the seam a2f7f63348

Produced by RUNNING task-record over the bound-plan-size run's own committed
range (093408c9^..6ed57a7a), never hand-written: a hand-written file proves
nothing about the writer and is the model-holding-Write shape D-07 rejects.

The indexed text is the record's own words, drawn from that task's ## Outcome
section, so the corpus carries what shipped rather than a fresh claim about it.
recall "plan size ceiling max_plan_tasks task count" now returns
tasks/bound-plan-size/RECORD.md, which makes AC1's check a statement about the
corpus rather than about a fixture.

fix(3-1): the record writer is contained the way the record reader is 7123438559

`isTaskSlug` refuses a slug that traverses; it cannot see a
`tasks/<slug>` that already IS a symlink, and git carries symlinks, so a
cloned planning tree ships one. `mkdirSync(recursive)` follows it and
`atomicWrite` does not catch it: it lstats its own temp path, which
refuses a symlinked destination file and says nothing about a symlinked
parent directory. The record landed in a tree `taskRecordsIn` would then
refuse to read it back from.

The lister's containment rule becomes `insideRoot` and the writer answers
it too, so reader and writer agree about where a record may live.

feat(3-2): index a /cad-task record's commits as a tier of its own b680a37211

feat(3-2): ask the tasks tier after the phase spine and before recovery 335a590ef2

fix(3-2): close the unterminated assertion message in why-corpus.test.mjs b6c6ebf540

feat(3-2): render a resolved task as a task, never as a phase b871829cc3

feat(3-2): read a task's RECORD.md as its declaration source 72aeb59c96

test(3-3): pin --phase 0 on task.md's risk-check invocation 4ede090734

feat(3-3): bracket a /cad-task run under a per-run phase-0 correlation anchor 7c071320f8

feat(3-3): /cad-task writes its record and reports where it landed 82135d761f

docs(3): phase 3 summary f9e486d15c

fix: a task entry name the writer would refuse is not listed back 8f43985442

taskRecordsIn contained every path it walked but judged no NAME, so a
tasks/ entry called `a\n## Commits` or one carrying a terminal escape
resolved inside the planning root and reached /cad-why's rendered output
and the recall index verbatim. The lister now applies isTaskSlug - the
same predicate the writer is held to - before joining the name onto
anything.

docs: task record task-record-slug-filter c3a054d77a

docs(3): AC3 and AC5 amended to what phase 3 delivered b5a642482a

PLAN-3.md's Notes recorded both re-readings at plan time and nothing
carried them back: AC3's third clause contradicted its own first, and
AC5's grep already failed against a file this phase never touched on
those lines. CONTEXT.md now states what was contracted and SUMMARY.md
records the two as deviations.

docs: phase 3 UAT - 9 passed, 0 failed b95bbd2c19

docs: correct the claims that had drifted from the tree ed7a2a3377

Twelve stale claims found by a docs-verify sweep of the root docs and
docs/, each re-checked against the code before the edit:

- command and skill counts (README, MANIFESTO, LINEAGE) - 28 commands,
  34 skill dirs of which 6 are contracts, 6 agent roles across 19 rungs
- config.mjs's subcommand list gained get and lost the pruned mode key,
  and the schema is 78 leaves rather than ~50 (DESIGN)
- git-segments.mjs is eighty-five lines, as README and INTERNALS
  already said (DESIGN)
- the install URL is the self-hosted origin (DESIGN)
- the canonical .planning/ set now names what actually ships, including
  v3.6.0's tasks/<slug>/RECORD.md (DESIGN)
- risk_surface fires once per plan only in /cad-execute, once per run
  elsewhere, and the ephemeral-target drop needs an empty git ls-files
  only for a DIRECTORY target (docs/WORKFLOW)
- route-table's own note said five triggers where the schema defines four
- suite timings, which had roughly doubled (CONTRIBUTING)

chore: bump manifest to v3.6.0 + changelog a40f7fcf03

chore: prune v3.6.0 completed phases d8173830d8

docs: close v3.6.0, open v3.6.1 over the gaps it named

test / node-test (git, 22) (pull_request) Successful in 30s

Details

test / node-test (git, 24) (pull_request) Successful in 34s

Details

test / node-test (other, 22) (pull_request) Failing after 1m17s

Details

test / node-test (other, 24) (pull_request) Failing after 1m11s

Details

test / node-test (planning, 22) (pull_request) Successful in 1m40s