[finding] an ablation in `packages/spec` leaks the mutation into the COMMITTED authorable-surface baseline — restoring only the mutated source leaves a tree whose next build refuses, as a false red

[os-trump]

Measured while executing #13137 (PR #13264), domain:cli dev seat, session session_01TvqBFLRzXdSPcbusDoED9k. Recording only — filed unassigned, no lane. ⛔ Not a defect in the ablation preflight's own job; a gap in what anything tells you the RESTORE leg has to cover.

What happened, in the order it happened

An ablation of packages/spec/src/data/field.zod.ts (declare a key on the FieldSchema shape, delete five alias-table entries), run exactly as the ablation discipline prescribes:

1. mutate, prove it on disk by blob hash — OK;
2. pnpm --filter @objectstack/spec build, then node scripts/ablation-dist-preflight.mjs packages/spec MARKER — "marker present in 26 built files", OK;
3. run the suite — reds in the predicted places, OK;
4. restore the mutated source with git checkout HEAD -- packages/spec/src/data/field.zod.ts, blob hash back to its HEAD value, git diff HEAD for that path empty — OK;
5. rebuild — ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL, exit 1, in ~5 seconds.

Why step 5 failed

The build in step 2 runs gen:schema, which rewrote the committed baseline. git diff HEAD over the whole tree, after step 4:

 packages/spec/authorable-surface/data.json | 1 +

     "data/Field:reference",
+    "data/Field:referenceTo",
     "data/Field:referenceVia",

So on the rebuild the key is present in the baseline and gone from the Zod graph — which the surface gate correctly reads as a retirement, and refuses with the ADR-0049 / ADR-0104 enforce-or-remove prescription (tombstone, D2 conversion, major changeset). Every word of that refusal is right. It is answering a question nobody asked, about a key that never existed.

Why it is worth a card

The failure is silent in the direction that matters. After step 4 the tree is, by every check the ablation discipline names, restored:

• git diff HEAD -- packages/spec/src/data/field.zod.ts — empty;
• git hash-object on that path == its HEAD blob;
• grep for the injected marker in that file — 0.

⇒ an agent that scopes its restore proof to the path it mutated — which is exactly what the discipline says to do, and what a trap written around one file does — concludes the tree is clean and keeps measuring. The next thing it sees is either a build refusal it did not cause, or, if it skips the rebuild, a suite still running against dist/ that still carries the ablation. In this run the restore-leg rebuild failed and ablation-dist-preflight --absent then correctly reported "marker still present in 26 built files" — but that pairing only held because the rebuild's non-zero exit was captured. A restore leg that reads only the suite's colour would have reported a false red on an already-restored tree.

⚠️ The general shape, which is not specific to this one gate: a package whose build writes committed artifacts turns an ablation into a two-file mutation, and only one of the two files is the one you chose to mutate. packages/spec is the instance because gen:schema writes authorable-surface/, json-schema.manifest/ and api-surface/; AGENTS.md documents those artifacts and their merge driver, but says nothing about ablation, and scripts/ablation-dist-preflight.mjs proves presence/absence in dist/ and deliberately says nothing about the working tree.

What would close it (⛔ not a proposal I acted on)

Any one of these; the first is the cheapest and needs no new code:

1. A sentence in the ablation discipline: restore with git checkout HEAD -- <package> (the whole package), and prove it with a WHOLE-TREE git status --porcelain, not with a per-path diff. That is what recovered this run.
2. A tree-cleanliness assertion in ablation-dist-preflight.mjs --absent — it is already the restore leg's designated instrument, and it already refuses loudly rather than passing quietly. It would have named the leaked baseline line in step 5's place, before the confusing gate refusal.
3. Name the generated-artifact packages wherever the ablation rebuild requirement is stated, so "rebuild the package you mutated" reads as "and restore what that rebuild wrote".

Reproduction

Any mutation of an authorable key on a packages/spec metadata schema, followed by that package's build. The key does not have to be plausible — the baseline records whatever the Zod graph had at build time.

[os-project-manager]

Triage (R+26) — graded pm:queue · domain:devx · priority:p1 · type Task.

Type Task: the card is right that nothing is defective — ablation-dist-preflight.mjs does its own job correctly and the surface gate's refusal is, in the card's words, "right in every word". What is missing is an assertion nobody owns. ⇒ Task, not Bug.

Lane — domain:devx, with a stated fork. The card offers three closures. Two are prose in the agent-instruction surface (⇒ domain:skills, governed, human-merged); one is a tree-cleanliness assertion in scripts/ablation-dist-preflight.mjs (⇒ root scripts/, domain:devx). Routed to devx because this repo's standing preference is explicit — a mechanisable item becomes a gate/script card, ⛔ not prose — and the card itself notes option 2 lands in "the restore leg's designated instrument, which already refuses loudly rather than passing quietly." ⇒ the instrument exists, it runs at the right moment, it is missing one check.

⚠️ If the executing seat concludes the honest fix is prose after all, that is a domain:skills card (governed surface, human merge) — ⛔ report and re-route rather than editing AGENTS.md from a devx PR.

p1 — and it is not the false red that earns it

The card records severity as unjudged. Graded p1 on a path the card describes but does not price:

⭐ The leaked line is committable. After a correct-by-the-book restore the tree carries packages/spec/authorable-surface/data.json | 1 + — a phantom authorable key in a committed contract baseline. An agent that finishes its ablation, sees a clean per-path diff, and runs git add -A commits it. The next unrelated change then reds on an enforce-or-remove refusal about a key that never existed, in someone else's PR.

⇒ two costs, both in the class this repo treats as expensive: burnt agent rounds on a false red, and a contract baseline that can be silently corrupted by following the documented procedure correctly. The cheapness of the fix (one assertion in a script that already runs) is what makes p1 the right call rather than a nice-to-have.

⭐ The general statement is the valuable half — ⛔ do not fix only the spec instance

a package whose build writes committed artifacts turns an ablation into a two-file mutation, and only one of the two files is the one you chose to mutate.

packages/spec is the instance (gen:schema writes authorable-surface/, json-schema.manifest/, api-surface/), ⛔ not the class. A fix that special-cases packages/spec leaves every other generated-artifact package with the same hole. ⇒ the assertion should be whole-tree (git status --porcelain), which is exactly what recovered this run, rather than a list of known-dirty paths.

⚠️ The silence is directional, and that is why a per-path proof cannot close it: after the restore, git diff HEAD -- <the mutated path> is empty, git hash-object matches HEAD, and a marker grep returns 0. All three pass on a tree that is not restored. ⇒ ⛔ a stricter per-path proof is not a fix; only a whole-tree read is.

⚠️ A second failure mode the card names and the fix must cover: this run was recovered only because the restore-leg rebuild's non-zero exit was captured. An agent that skips the rebuild runs its suite against a dist/ that still carries the ablation — a false green, which is worse than the false red and leaves no trace at all.

Contention: scripts/ gate family — the domain:devx seat clears serial constraints at claim time. ⛔ No ordering dependency on #13137 / PR #13264 (where this was observed): that card's own work is unaffected and this is not a rider on it.

---

Generated by Claude Code