docs(skills): state the ablation-on-dist hazard as a resolution property, not a dogfood one

[os-zhuang]

Fixes#8949

What changed

Two .claude/** instruction files stated the "rebuild before you believe an ablation"
rule as a property of packages/qa/dogfood. Both now state it as a property of
resolution, which is what it actually is.

• .claude/agents/os-dev.md — the ablation clause in the standing-clauses section,
  generalized in place (no new section).
• .claude/skills/dogfood-verification/SKILL.md — the ablation bullet in section 2,
  generalized in place (no new section).

The condition, as both copies now state it

Any test whose subject resolves through the dependency's exports — which point at
that package's built dist/, not src/ — with no vitest alias redirecting the
specifier back to source. That set is enumerable and already enumerated:
KNOWN_UNALIASED_TEST_IMPORTS in scripts/check-test-source-alias.mjs.
packages/qa/dogfood is the most familiar instance, not the definition.

Two measured pairs are carried as the shortest possible provenance, as mechanism
illustration rather than as the rule body:

pair	what happened
plugin-email to platform-objects	375 passes on an ablated field; 4 went red once the dep was rebuilt
plugin-auth to core	legs meant to prove a new gate can fail ran the pre-mutation artifact and stayed green

The second pair is the one both files are written around. An un-rebuilt ablation there
does not return a null result — it returns "the gate did not fire", which in that
context reads as evidence the gate is broken rather than the harness. The expensive
outcome is a dev weakening a working gate until it fires, destroying the thing the
ablation was written to certify.

Both halves of the mechanical rule, now explicit in both copies

mutate -> rebuild -> prove the marker is IN dist/
restore -> rebuild -> prove the marker is GONE (--absent)

The restore half is the one that gets skipped: rebuilding after mutating is intuitive,
while remembering that restoring also needs a rebuild before the next measurement
is trustworthy is not. A marker left behind in dist/ keeps mutated code live for every
later suite run in that worktree, so the runs that follow measure the wrong tree.

Scope

• scripts/ablation-dist-preflight.mjs is deliberately not touched — that header is
  the authority and already carries this framing (landed via PR docs(scripts): state the ablation-on-dist hazard by its true condition, not as a dogfood property #8951); it is [finding] the ablation-on-dist false green is NOT dogfood-only — any package in KNOWN_UNALIASED_TEST_IMPORTS has it (measured in plugin-email ⇢ platform-objects) #8706's
  scope and out of bounds here. These two files were the lagging copies.
• packages/qa/dogfood/README.md step 4 is the third coupled location and is out of
  scope on purpose — it belongs to packages/qa/dogfood/README.md step 4 still prescribes the ablation without the rebuild — the third copy of the procedure, in the lane #8246 could not reach #8366 in the domain:cli lane. That card remains
  open and is not addressed here.
• Whether the preflight grows a per-symbol mode is a design question raised by [finding] the ablation-on-dist false green is NOT dogfood-only — any package in KNOWN_UNALIASED_TEST_IMPORTS has it (measured in plugin-email ⇢ platform-objects) #8706 and
  is untouched.

Merge path

⛔ Human merge only. Standing maintainer ruling, 2026-08-11:
「所有 skills 的更新和 adr 类似,需要人工审核」. This PR is a draft; no AI seat should
mark it ready, add it to the merge queue, or arm auto-merge. It is awaiting a human
merge, which on GitHub looks identical to "forgotten".

Verification

.claude/** prose only — no package source, no published surface, so no changeset
(skip-changeset).

Local gate union, all green at 2cfdd3bfb (the final commit of this branch):

gate	result
pnpm check:doc-authoring	377 files clean
pnpm --filter @objectstack/lint run check:doc-formula-expressions	24 self-test cases; 396 files / 1411 TS blocks clean
pnpm check:skill-frame-sync	4 copies structurally isomorphic across 3 files
pnpm check:pm-skill-ratchet	os-dev.md 341 lines, ceiling 399, headroom 58
pnpm check:pm-skill-id-lint	9 files clean; os-dev.md stays at zero issue-ID citations
pnpm check:agent-model-declared	os-dev.md declares opus
pnpm check:nul-bytes	6136 text files, no raw control bytes
node scripts/check-adr-merge-approval.mjs	401 Bad credentials locally (expected — needs CI credentials)

pnpm check:pm-skill-id-lint was not in the dispatched gate list; it was picked up
by re-deriving the family from the actual diff
(node scripts/pm/dispatch-gates.mjs over the two changed paths) and is green. That
re-derivation placed 8 families for this surface and matched no others.

The id-lint gate is why neither file cites an issue number: maintainer ruling
2026-08-12 keeps operative agent-protocol text free of issue-ID dereferences, so the
two measured pairs are named by package pair only.

Generated by Claude Code

---

Generated by Claude Code