finding: the unreferenced-recipe direction of check:platform-checklist is now well-defined and still unchecked — the reason it was deferred has expired

[os-steve]

Observation from the #10593 gap-2 work (the area-qualified use). Filed unassigned; recording that a deferral's stated reason has expired, not claiming the work.

The deferral, and why it was made

scripts/check-platform-checklist.mjs resolves fixtures.provisioning.use to a real recipe, but deliberately does not check the reverse direction — a recipe that no item references. Unlike the trap vocabulary beside it, which is bidirectional (every trap used is documented, every trap documented is used), the recipe check is one-way.

The reason was recorded in the gate and in docs/qa/platform-checklist/README.md, and it was a good one at the time:

Cross-area reuse has no spelling yet, so a recipe whose only consumer lives in another area is referenced from that item's knownGaps prose — invisible to the check. Redding the unreferenced direction would answer the cross-area question by accident, in the direction of "recipes are area-local", and that is a convention decision rather than a mechanical one.

In other words: flagging an unreferenced recipe could not distinguish dead text from a recipe whose only consumer sat in another area and could not say so.

What changed

The maintainer ruled option A on 2026-08-22 (#10593 gap 2): provisioning.use accepts <area>:<recipe>, and a cross-area consumer opts in by key like any other. records-forms.crud-roundtrip is the worked instance and now carries search:qa-contributor-bound-member.

That removes the ambiguity the deferral rested on. Every legitimate consumer of a recipe can now express itself as a use, in any area. So a recipe with no use pointing at it is no longer "possibly referenced from prose we cannot see" — it is dead text, unambiguously, and the check could say so.

Why this is filed rather than done

Deliberately not folded into the gap-2 PR, on the dispatch's explicit instruction ("do not add unreferenced-recipe flagging in this PR, either way"). It is also a genuinely separate change:

• It is the first direction of this gate that can red on a file nobody edited — a recipe goes unreferenced when its last consumer is retired, which is an edit in a different area file.
• It needs a decision on retired items: an item with status: "retired" still carries its fixtures.provisioning, so "referenced" has to mean referenced-by-an-active-item or referenced-at-all, and those differ the moment a recipe's only consumer is retired.
• It wants a spelling for a deliberately-kept recipe (a $-annotation, a waiver field, or "retire the recipe with the item").

Interaction worth noting

#10885 (recipes carry no revision/history) is the third axis of the same convention and is pm:on-hold. If recipes gain a lifecycle of their own there, "unreferenced" probably wants to be expressed through it — a retired recipe rather than a flagged one — so sequencing this after #10885 may be cheaper than deciding a bespoke answer here.

Current state

All four recipes are referenced today, so this direction would land green: qa-scratch-authz (3 items), qa-media-constraints (1), qa-flow-status-doors (1), qa-contributor-bound-member (2, one of them cross-area). Nothing is broken. The cost is that the gate's own comment now documents a deferral whose reason no longer holds, which is how a deliberate gap turns into an unexamined one.

⚠️ Note for whoever picks this up: check:platform-checklist is not CI-wired (maintainer decision, .github/workflows/lint.yml), and it is currently red on main for an unrelated reason (#11421). Neither is caused by this; both shape how you would verify a change here.

[os-steve]

Claim: devx lane PM seat, session e2eac1a7-8000-5c95-9749-38aec2ace6fc, branch claude/issue-11506-unreferenced-recipe-direction.

Graded finding → pm:dispatched, domain:devx.

⚠️ Collision check done: your surface is scripts/check-platform-checklist.mjs, which does not appear in the file set the in-flight #11511 will touch, and none of my open governed PRs reach it. ⛔ Verify it yourself before your first edit — and use git merge-base <head> origin/main, never a PR's base.sha, which is the base at PR creation and never updates.

⚠️ Worth knowing before you scope: #11730 is in the maintainer's decision box — check:platform-checklist is deliberately not CI-wired, so its red is visible to nobody until a runner reads it. That does not block this card (the direction you are closing is real either way), but it does mean ⛔ do not wire it into CI as a side effect; that is the maintainer's open decision, not yours.

If you are a different session and you see this comment before starting work, this card is taken — pick another.

---

Generated by Claude Code

[claude]

{
 "issue": 11506,
 "status": "done",
 "branch": "claude/issue-11506-unreferenced-recipe-direction",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11847",
 "premise_still_valid": true,
 "summary": "PREMISE VERIFIED FIRST, and it holds. The deferral's stated reason was that cross-area reuse had no spelling, so a recipe whose only consumer lived in another area was referenced from knownGaps prose the gate could not see -- flagging an unreferenced recipe would then have settled that open convention by accident, toward 'recipes are area-local'. It was discharged by the maintainer's option-A ruling of 2026-08-22 (#10593 gap 2, landed by PR #11508, merged to main as d10e2146). Three confirmations in the tree rather than recollection: parseUse/two-level lookup implemented in scripts/check-platform-checklist.mjs; areas/records-forms.json:23 carries the worked instance \"use\": \"search:qa-contributor-bound-member\"; areas/search.json:52 records the ruling and both machine-resolved consumers. The ruling comment on #10593 is verbatim 'Ruled: Option A -- area-qualified references', accepted in the 2026-08-22 decision-inbox batch the maintainer took as 「接受所有」. So every legitimate consumer can now express itself as a use, and an unreferenced recipe is unambiguously dead text. IMPLEMENTED: check-platform-checklist now runs the resolve in both directions -- every area-level recipe must be named by some item's use, reported against the file that owns it. Three definitional edges decided in the gate's comment rather than left to the reader: (1) only a resolved fixtures.provisioning.use counts, never a prose mention (two area files open with 'Shape copied from qa-scratch-authz', which is provenance, not consumption); (2) a reference from a RETIRED item still counts -- mechanical, not a convention call, because provisioningProblems runs on every item regardless of status, so a retired item's use must resolve and its recipe must exist; an active-only reading would make the two directions mutually unsatisfiable the moment a recipe's last consumer retired, escapable only by editing a retired item, which the append-only lifecycle forbids; (3) the direction is SUPPRESSED while any use dangles, so one typo cannot also accuse the correct recipe it was aiming at. NO waiver spelling was invented (population needing one: zero) -- the failure names the two remedies that exist, and #10885 may answer the keep-it-anyway case as a retired recipe rather than a waived one. check:platform-checklist was NOT CI-wired (lint.yml untouched, #11730 left to the maintainer). Note the card's warning that the gate is red on main for #11421 has EXPIRED too: #11421 closed via PR #11524, and the gate is green on my base e47d5ef61 (exit 0, recorded before any edit).",
 "tests": "All at final head ee7ade76d, in worktree /home/user/objectstack-issue-11506. Exit codes captured by redirect-then-capture (cmd > file 2>&1; EXIT=$?), never after a pipe; every verdict below is the gate's own printed line.\n\nPOPULATION (the zero, with its positive control). 4 recipes / 7 referencing items / 0 unreferenced, enumerated from the area files: attachments-storage:qa-scratch-authz (3 items), attachments-storage:qa-media-constraints (1), automation:qa-flow-status-doors (1), search:qa-contributor-bound-member (2, one cross-area). Status census: 207 items, ALL active -- 0 retired, and 0 retired items carry a provisioning block, so the card's retired-vs-active question also has an empty subject today and both readings agree on this tree. Reference-surface sweep: grepping all four recipe names across the whole repo (excluding node_modules/.git) returns ONLY scripts/check-platform-checklist.mjs, docs/qa/platform-checklist/README.md and four area JSON files -- no run records, no skills, no coverage.json. So 'unreferenced' needs no exception list: measured size ZERO. Because the subject population is zero and stays zero on a healthy ledger, a check alone would have a permanently empty output whose green cannot distinguish 'working' from 'deleted' -- so this ships BOTH the direction and a 19-assertion inline positive control, matching the file's existing trap-vocabulary (22) and provisioning-resolve (34) controls.\n\nNON-VACUITY -- three ablations, each under trap '<restore>' EXIT INT TERM, each asserting the anchor match count IN-PROCESS (a zero-hit edit aborts loudly rather than reading as a clean ablation), each proving the mutation landed by sha256 change, each proving the restore byte-identical.\nA (does it fire?): injected one genuinely unreferenced recipe into areas/automation.json. sha256 ce5f1eda->71f39dfe, inject-marker count 0->1, JSON still parses. GATE_EXIT=1, exactly 1 problem: 'automation.json: area-level recipe \"qa-ablation-orphan-recipe\" is referenced by no item -- dead text.' Restore: sha256 back to ce5f1eda, BYTE-IDENTICAL, GATE_EXIT=0.\nB (Zone 1 guard -- must not redden a CORRECT recipe): misspelt a real use, qa-media-constraints -> qa-media-constraint. GATE_EXIT=1 with problem count = 1, and that one problem is the dangling reference ('did you mean `qa-media-constraints`?'). The correct recipe was NOT accused -- suppression held on real data, which is exactly the double-report that would have invited deleting live text. Restore byte-identical.\nC (cross-area accounting on REAL data, the card's motivating scenario): qa-contributor-bound-member has two consumers, one in another area. C1 repointed the cross-area consumer records-forms.crud-roundtrip elsewhere -> GATE_EXIT=0, still green because search.rls-both-personas still references it. C2 repointed that one too -> GATE_EXIT=1 reported against search.json, the area that OWNS the recipe, though the triggering edits were in other files -- i.e. a recipe going unreferenced by an edit in a different area file, reproduced end to end. All three files restored byte-identical; gate green again.\nHONEST NOTE on the ablation harness: one echo BANNER line in ablation-bc.sh had a shell-quoting bug (backticks inside double quotes), printing 'line 43: use: command not found'. It touched no mutation -- every mutation is proven independently by the in-process 1-match assertion and a visible sha256 change -- but recording it because a silent no-op from exactly this class of error was the trap flagged at dispatch.\n\nEXISTING DIRECTION UNCHANGED, proven by the gate's own verdict line, not by inspection. Baseline captured on this same tree at e47d5ef61 BEFORE any edit: 'OK -- 15 areas, 207 items (207 active); coverage: 31 kinds mapped, 0 waived; traps: 19 documented, 19 in use; provisioning: 4 area recipes, 7 item references resolved (1 area-qualified) (self-checks: 22 trap-vocabulary + 34 provisioning-resolve assertions).' Branch: 'OK -- 15 areas, 207 items (207 active); coverage: 31 kinds mapped, 0 waived; traps: 19 documented, 19 in use; provisioning: 4 area recipes, 7 item references resolved (1 area-qualified), 4/4 recipes referenced; (self-checks: 22 trap-vocabulary + 34 provisioning-resolve + 19 unreferenced-recipe assertions).' Field-by-field: areas/items/active, coverage kinds+waived, traps documented+in use, area recipes, item references resolved, area-qualified refs, and BOTH pre-existing self-check counts are all UNCHANGED; the only deltas are additions (19 unreferenced assertions, 4/4 recipes referenced). The 4/4 is counted from the reference map, not restated from recipeTotal. Self-test alias: 'check-platform-checklist --self-test: 75 assertions' (was 56), exit 0.\nMETHOD CORRECTION worth recording: my first attempt to compare directions ran origin/main's gate from a copied file in the scratchpad; it died with ERR_MODULE_NOT_FOUND on its sibling js-comment-mask.mjs, and my parser would have reported the pre-existing fields as 'CHANGED'. Caught by reading the real output rather than the summary table, and redone against the recorded baseline.\n\nGATES. Family re-derived from the COMMITTED diff with 'node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack' (it reads its own change set from the merge base; no hand-built path list passed) -- 8 families, unchanged between the working-tree and committed derivations, no additions. Union re-run at final head ee7ade76d through scripts/pm/os-verify-lock.sh (VERDICT command-exit 0, held 20s, waited 0s): EXIT=0 for all ten of check:nul-bytes, check:platform-checklist, check:agent-test-spelling, check:cross-package-test-inputs, check:doc-authoring, --filter @objectstack/lint check:doc-formula-expressions, check:entry-guard, check:parse-guard, check:pnpm-filter-targets, node scripts/check-cross-package-test-inputs.mjs. check:doc-formula-expressions first printed 'PREREQUISITE NOT MET' for @objectstack/formula and then for @objectstack/lint; both built as the message instructs and re-run green -- per #11824 that is a prerequisite, not a finding and not a verdict.\nREPO-WIDE LINT NARROWED, declared as a narrowing with all three measurements: (1) population read from eslint's OWN config -- isPathIgnored reports docs/qa/platform-checklist/README.md IGNORED ('File ignored because no matching configuration was supplied') and scripts/check-platform-checklist.mjs in scope, so one of my two files is eslint's entire population here; (2) file count from --format json: 2 entries, 0 errors, 1 warning (that ignore notice); (3) config invariance -- eslint.config.mjs states in its own words that this repo 'never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file', measured there with its own positive control, so this diff cannot move the verdict on any untouched file. CI runs the full farm regardless.\n\nCOLLISION CHECK done myself, not taken from the dispatch: enumerated all open PRs and their file lists. Only #11780 also touches docs/qa/platform-checklist/, and its area-file edits contain NO added or removed line matching provisioning, \"use\", \"fixtures\" or a retire -- so it can neither create an unreferenced recipe nor remove a recipe's last consumer, and it does not touch scripts/check-platform-checklist.mjs. No textual and no semantic collision.",
 "open_questions": [
 {
 "question": "NON-BLOCKING, for ratification only -- the card asked for 'a spelling for a deliberately-kept recipe' (a $-annotation, a waiver field, or 'retire the recipe with the item'). I deliberately built none. Does the maintainer want that ratified, or a waiver mechanism added now?",
 "options": [
 "A. Ship with no waiver (what this PR does). Population needing one is measured at zero -- all 4 recipes referenced by 7 items. The failure names the two remedies that exist (give it a consumer from any area, or delete it), and the gate's comment says a genuine keep-it-anyway case is the moment to decide the spelling, on that case's evidence.",
 "B. Add a waiver field now (e.g. a $keep annotation or a waiver key with a reason), matching the blocked.by/blocked.ref waive-with-a-reference idiom used elsewhere in this ledger.",
 "C. Defer the whole direction until #10885 gives recipes their own revision/history, then express 'unreferenced' as a RETIRED recipe rather than a flagged one."
 ],
 "recommendation": "A, on all four axes. Real business need: zero -- no recipe today wants keeping without a consumer, so B is a guess at what the first real case will want, written before that case exists to constrain it. Long-term soundness: B invents a second, weaker way to be 'referenced' and creates precisely the accommodation surface contract-first discipline warns about; A keeps one rule with two honest answers. Hard-to-get-wrong: A is strictly stricter -- a waiver is the field an AI author reaches for to silence a gate, and a waiver with no real case has no reviewable standard to judge it against. Startup scope discipline: A adds no declared surface; B is declared-but-unconsumed capability from day one, the exact shape ADR-0049 enforce-or-remove exists to retire. C is not chosen because it leaves the gate's own comment documenting an expired deferral for an indefinite period, which is how this card was created in the first place -- and nothing in this PR forecloses #10885 relocating the concept later."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code