feat(qa-checklist): resolve an area-qualified provisioning.use (#10593 gap 2)

[claude]

Fixes#10593

Gap 2: cross-area recipe reuse gets a spelling. Implements the maintainer ruling of 2026-08-22 — option A, area-qualified references — over option B (a shared areas/_fixtures.json) and option C (recipes stay area-local, cross-area consumers duplicate). The ruling is not re-litigated here.

The problem

A provisioning recipe is proved by one area and sometimes needed by a second. Until now fixtures.provisioning.use could only name a key in the item's own area, so a cross-area consumer had exactly one option left: cite the recipe by name in knownGaps prose. Prose is the one form that cannot drift-check — rename the recipe and search.json moves while the sentence in records-forms.json does not, silently and with nothing red.

What changed

use now has two spellings, and the gate resolves both:

"use": "qa-scratch-authz"// a recipe of the item's OWN area"use": "search:qa-contributor-bound-member"// "<area>:<recipe>" — one another area owns

The area half is the filename stem. Every reference already written keeps working — the qualifier is an addition, not a migration, and the self-test pins that as a regression, not as an aspiration.

Two implementation notes worth review attention:

• The area files are now walked twice. The recipe universe has to be complete before any item is judged; a single pass would test each item against a half-built map, and whether a cross-area reference resolved would depend on readdir order.
• Recipes are keyed by filename stem, deliberately not by doc.area. The two must agree, and that agreement is itself checked one line down — keying by a mismatched doc.area would let a qualified reference resolve through the very inconsistency the gate reports.

Per the dispatch, the resolver stays inside check-platform-checklist.mjs; no new module under scripts/ (that would move dispatch-gates' family universe, which #11190 is measuring across this same round).

Non-vacuity — this is the part to review

A two-level lookup has a failure mode the one-level one did not: resolving too much. No "it resolves" assertion can see that, so every limb is observed failing as well as passing. Self-test: 36 → 56 assertions.

Ablation A (the #10810 precedent): provisioningProblems() neutered to return early. Predicted 27 of the 34 provisioning assertions red — U4–U13 and Q4–Q20, every case asserting the check fires; U1/U2/U3/Q1/Q2/Q3 assert zero problems and U14 exercises areaRecipeKeys only. Observed exactly 27, exactly that set, and the full gate refused with the provisioning-resolve check's own positive control FAILED rather than going quietly green. Mutation confirmed on disk by anchor count (marker 0 → 1 at line 307) and sha256, never by the editor's exit code; restored byte-identically via an EXIT INT TERM trap (sha back to 3fa7b602…, marker count 0, clean git status).

Ablation B — the sharper one, because it tests the code/data pairing rather than the code alone. The gate was swapped back to origin/main (confirmed on disk: sha 39d95f98…, recipesByArea occurrences 10 → 0, git diff --quiet origin/main clean) while keeping this PR's data change. The base gate reds on exactly the converted item:

✗ records-forms.json · records-forms.crud-roundtrip: "fixtures.provisioning.use" names
"search:qa-contributor-bound-member" but this area file has no area-level "fixtures"
block to resolve it against — …

So the green below is produced by the new two-level lookup and by nothing else, and the data change genuinely requires the code change. Restored byte-identically.

All three failure shapes reproduced on the live corpus (each injection confirmed present on disk before the reading was taken; all reverted by trap):

injected use	what the gate said
search:qa-recipe-nobody-wrote	…not a recipe in area "search"'s area-level "fixtures" block — \search` offers `qa-contributor-bound-member``
serch:qa-contributor-bound-member	…whose area half names "serch" — there is no such area file — did you mean \search`?`
search:qa:member	…not a usable reference: it carries 2 ":" separators…
search:	…not a usable reference: its recipe half is empty…
qa-contributor-bound-member (unqualified)	…\search` defines it: write `search:qa-contributor-bound-member` … and do NOT fork a second copy into this area.`

That last row is the upgrade that makes the drift self-correcting: an author who copied an unqualified key across areas is handed the exact spelling that works.

The two prose pointers, converted where they sit

• records-forms.crud-roundtrip clause 7 now carries use: "search:qa-contributor-bound-member"; its knownGaps and clause-7 verify text stop saying the reference cannot be spelled.
• search.json's recipe knownGaps stops saying no cross-area spelling exists, and now describes a recipe with consumers in two areas, both machine-resolved.

Both consuming items take a revision bump and a history entry. For search.rls-both-personas that follows the precedent its own revision 5 set: area-level recipes carry no revision/history, so a consuming item's revision is the only pin the recipe text has. What a run does is unchanged in every particular — same recipe, same file, same clause, same object and row; no step, clause, oracle or persona changed.

⚠️ Two things this PR's green does NOT tell you

1. check:platform-checklist is not CI-wired, by maintainer decision recorded at .github/workflows/lint.yml. That decision is honoured, not changed. The local runs in this PR are the only signal this gate will ever get — a green Lint & Repo Gates on this PR says nothing whatsoever about it, and a typo'd use is caught at the next manual sweep rather than on the PR that introduces it.

2. The gate is already red on main, for a reason this PR does not touch. Measured on pristine origin/main @ 63da5867 before any edit: coverage.json · manifest: UNCLASSIFIED. packages/spec/liveness/manifest.json landed 2026-08-23 (#11338) without a matching coverage.json entry — 31 liveness kinds against 30 coverage entries. Already filed as #11421; nothing here is a fix for it, and it is the second-order cost of (1) showing up in practice. This PR's contribution to the problem list is zero: base and branch print the identical single problem.

With that one unrelated problem temporarily waived as a measurement (reverted; coverage.json sha256 unchanged), the gate goes fully green and reports the census:

check-platform-checklist: OK — 15 areas, 205 items (205 active); coverage: 30 kinds mapped,
1 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).

Gates

All on the final commit 4638ae27, exit codes captured before any pipe, each verdict quoted from the line the gate printed itself. Derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed — it takes the change set from the merge base), re-derived on the final commit, same 8 families both times.

gate	exit	verdict line
check:cross-package-test-inputs	0	OK: 14 package(s) read outside themselves, all declared…
check:doc-authoring	0	✓ doc authoring guard: 389 files clean
--filter @objectstack/lint check:doc-formula-expressions	0	✓ … 22 record-scoped formula example(s) across 420 files / 1449 TS blocks judged clean
check:entry-guard	0	✓ … 139 scripts/ file(s) — every entry guard goes through invoked-as.mjs
check:parse-guard	0	self-test + scan clean
check:pnpm-filter-targets	0	✓ … 120/148 --filter occurrence(s) … resolve
scripts/check-ci-filter-parity.mjs	0	OK: all 89 declared cross-package glob(s)…
scripts/check-cross-package-test-inputs.mjs	0	OK: 14 package(s) read outside themselves, all declared
check:nul-bytes	0	OK (scanned 6455 text file(s) … no raw ASCII control bytes)
check:platform-checklist	1	the pre-existing #11421 problem only — identical on base and branch

eslint scripts/check-platform-checklist.mjs exit 0. The repo-wide pnpm lint was narrowed deliberately, and the narrowing is a measurement: eslint --print-config on the changed file reports parserOptions.project, projectService and EXPERIMENTAL_useProjectService all undefined, so type-aware linting is not enabled and this diff cannot move the verdict of any file it does not touch; --format json judged all 4 changed files, 0 problems. CI runs the full farm regardless.

Dependency closure built under scripts/pm/os-verify-lock.sh before any gate was trusted; git status --porcelain empty afterwards, so nothing generated is in this diff.

Deliberately not in this PR

• No CI wiring for check:platform-checklist — reversing a recorded ruling.
• No unreferenced-recipe flagging. Its stated reason for being deferred has now expired — with a qualified spelling available, an unreferenced recipe is unambiguously dead text rather than "possibly consumed from prose we cannot see". Since that justification no longer holds, the gate and README no longer claim it does; the direction is filed as finding: the unreferenced-recipe direction of check:platform-checklist is now well-defined and still unchecked — the reason it was deferred has expired #11506 with the retired-item and recipe-lifecycle questions it raises.
• finding: area-level fixtures recipes carry no revision/history, so a semantic recipe edit silently re-validates every run record that depends on it #10885 (recipe revision/history) is not foreclosed, and is cited in the history entry that leans on the consuming-item-revision workaround.
• docs(qa-checklist): two items' knownGaps prose still says the validator does not resolve provisioning.use — it now does #10809 is closed (merged as docs(qa-checklist): correct two knownGaps that still deny the provisioning.use resolve #10883). Its own sequencing note assigned the second prose rewrite to whatever answered gap 2 — "Doing this correction after that decision costs one edit instead of two" — which is this PR, so the two knownGaps are corrected here rather than left inverted a second time.

No changeset: internal QA gate plus internal QA ledger, nothing published changes — same posture as #10810, which changed these same files. skip-changeset applied.

Generated by Claude Code

---

Generated by Claude Code