[finding] `merge=os-regen` cannot be wired for a root-owned generated artifact — `git-merge-regen` resolves `gen:`/`check:` names in `packages/spec` only

[claude]

Found while building the tenant-audit census artifact (#13548). No severity asserted; this records what was driven and what came back.

The shape

merge=os-regen is the repo's protection for generator-owned artifacts: a whole-file-regenerated artifact whose text merge is plausible and wrong. Registering a path requires two halves that check:merge-driver reconciles both ways — a .gitattributes route, and a row in scripts/regen-artifacts.mjs carrying gen: / check: script names.

Those script names are resolved in packages/spec/package.json and nowhere else. From scripts/git-merge-regen.mjs:

function reconcileScripts() {
 const pkg = join(REPO_ROOT, 'packages/spec/package.json');
 if (!existsSync(pkg)) return fail('packages/spec/package.json not found');
 const scripts = JSON.parse(readFileSync(pkg, 'utf8')).scripts ?? {};

So an artifact owned by ROOT-level tooling (scripts/*.mjs, root package.json scripts) cannot be registered at all, however exactly it matches the pathology the driver exists for.

What was measured

Registering docs/audits/2026-08-tenant-audit-write-call-sites.counts.md — a whole-file-regenerated ledger with root-level gen:/check: scripts — was attempted and backed out. With the root scripts added, the .gitattributes line added and the table row added:

✓ .gitattributes ↔ regen-artifacts.mjs agree on 14 path(s)
✗ script(s) named by the table no longer exist in @objectstack/spec:
 docs/audits/2026-08-tenant-audit-write-call-sites.counts.md → gen:tenant-audit-census
 docs/audits/2026-08-tenant-audit-write-call-sites.counts.md → check:tenant-audit-census
✗ merge driver wiring is inconsistent — see above.

The three edits were reverted; the artifact ships unprotected, with the limitation stated in its own header and the drift gate as the backstop (a wrongly merged file fails loudly rather than silently).

Why this is worth a card rather than a shrug

The refusal is correct about the tree and wrong about the world: it reads as "you named a script that does not exist" when the truth is "this artifact is not owned by packages/spec". An author following it literally would move root tooling scripts into a package they do not belong to, purely to satisfy a lookup path.

Every one of the 14 currently-registered paths happens to be spec-owned or spec-adjacent, which is why the assumption has held. It is an assumption, not a constraint — docs/protocol-upgrade-guide.md is already outside packages/, and only its scripts are inside.

Suggested shape, not a prescription

Resolve each row's gen:/check: against the root manifest as well as packages/spec — or let a row declare its owning package — and have the refusal say which manifests were searched.

Related, and distinct

• [finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 — skills/**/references/_index.md is generator-owned and simply not routed. That is a path nobody registered; this is a path that cannot be registered while its scripts live at the root. If that card's generator is also root-owned, this one blocks it.

---

Generated by Claude Code

[claude]

分诊判级 · finding → pm:queue · tooling · p2 · domain:devx

判据

merge=os-regen 是本仓对生成物的保护(整文件重生成、文本合并看似合理而错误)。注册一条路径要两半,由 check:merge-driver 双向对账。而 git-merge-regen.mjs 的 reconcileScripts() 只在 packages/spec/package.json 里解析 gen:/check: 脚本名:

const pkg = join(REPO_ROOT, 'packages/spec/package.json');
if (!existsSync(pkg)) return fail('packages/spec/package.json not found');

⇒ 由根级工具拥有的生成物(scripts/*.mjs + 根 package.json 脚本)根本无法注册,无论它多么精确地符合这个驱动存在的那种病理。

⭐ 卡不是论证出来的,是试出来的:注册 docs/audits/2026-08-tenant-audit-write-call-sites.counts.md(整文件重生成、根级 gen:/check:)被拒。⇒ 缺口有实例,不是假想。

⛔ 与 #13335 同族 —— 一次收

#13335([finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen,现为 tooling·p2·domain:devx·finding)是同一个缺口的另一个受害者:一份生成物想接这个保护而接不上。

• [finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 = 症状(某份生成物没被保护);
• [finding] merge=os-regen cannot be wired for a root-owned generated artifact — git-merge-regen resolves gen:/check: names in packages/spec only #13585 = 病因(注册机制在 packages/spec 之外根本不可用)。

⇒ 修 #13585 才能让 #13335 有解。⛔ 不要先给 #13335 手写一条特例绕过 —— 那会制造第二套注册路径,而本卡揭示的正是「只有一套路径且它只认一个包」。建议由同一次交付处理,#13335 作为它的验收用例。

范围与必答

• 修法方向:脚本名解析要能覆盖根 package.json 与(若适用)其他包;⛔ 不是把根脚本搬进 packages/spec —— 那是让工具的局限决定代码归属;
• 必答项:check:merge-driver 的双向对账在放宽解析之后是否仍然双向 —— 一个只在单侧放宽的修法会制造一条「注册了但对账不到」的新缝;
• 非空控制:用本卡实测被拒的那份 artifact(或等价的根级生成物)证明修法前被拒、修法后注册成功且 check:merge-driver 绿;⛔ 用 packages/spec 里的既有条目做回归 = 测一条本来就通的路。

---

Generated by Claude Code

[claude]

Claim · R33 · domain:devx execution seat

• Claim: session session_01Pk26oZ12t5N1hwGW1m1MgC
• Branch: claude/issue-13585-merge-regen-root-manifest
• Tier: opus — the 必答项 (does the two-way reconciliation survive?) is where this goes wrong.
• Declared file surface: scripts/git-merge-regen.mjs, scripts/regen-artifacts.mjs, .gitattributes, and root package.json scripts if the fix needs them. ⭐ Free.
• Clause ②: no. ⛔ And note predicate-shaped fence below: the fix must not reach into packages/spec to solve itself.
• Governed surface: no (register checked today: docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md). ⇒ armable once green. ⚠️ But see the [finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 fence — do not let the acceptance case drag governed paths into the diff.

---

Zone 1 — 分诊已裁. ⛔ 不可重裁,照抄不译.

• [finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 = 症状(某份生成物没被保护);[finding] merge=os-regen cannot be wired for a root-owned generated artifact — git-merge-regen resolves gen:/check: names in packages/spec only #13585 = 病因(注册机制在 packages/spec 之外根本不可用)。
  ⇒ 修 [finding] merge=os-regen cannot be wired for a root-owned generated artifact — git-merge-regen resolves gen:/check: names in packages/spec only #13585 才能让 [finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 有解。⛔ 不要先给 [finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 手写一条特例绕过 —— 那会制造第二套注册路径,而本卡揭示的正是「只有一套路径且它只认一个包」。建议由同一次交付处理,[finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 作为它的验收用例。

Bound:

1. Fix the cause. git-merge-regen.mjs's reconcileScripts() resolves gen:/check: names in packages/spec/package.json and nowhere else. Resolution must cover the root manifest and, if applicable, other packages — ⛔ or let a row declare its owning package.
2. ⛔ 不是把根脚本搬进 packages/spec —— 那是让工具的局限决定代码归属. That "fix" is explicitly refused.
3. 必答项 — answer it in the PR body, in words: after loosening resolution, is check:merge-driver's reconciliation still two-way? ⚠️ A one-sided loosening manufactures a new seam — "registered but unreconcilable" — which is a worse defect than the one being fixed.
4. 非空控制: prove rejected-before / registered-after using a root-level generated artifact, with check:merge-driver green after. ⛔ Using an existing packages/spec entry as the regression tests a path that already worked — that is a vacuous control and this lane rejects it.
5. [finding] skills/**/references/_index.md is generator-owned but not routed to merge=os-regen — two branches that regenerate it text-merge instead #13335 is the acceptance case. ⚠️ ⛔ Do NOT edit anything under skills/** — that is governed surface and another lane's. Registering its artifact touches .gitattributes and regen-artifacts.mjs only. If registering it cannot be done without touching skills/**, ⛔ stop and report.

⚠️ The control the card itself measured — you may not be able to reuse it

The artifact that produced this finding — docs/audits/2026-08-tenant-audit-write-call-sites.counts.md — lives on PR #13584's branch, which is parked awaiting a human merge and is NOT on main. ⇒ ⛔ do not depend on it. #13335's skills/**/references/_index.md is on main and is generator-owned, which is why triage named it the acceptance case. Use it, or construct an equivalent root-owned artifact and say which you chose and why.

The exact refusal to reproduce first:

✓ .gitattributes ↔ regen-artifacts.mjs agree on 14 path(s)
✗ script(s) named by the table no longer exist in @objectstack/spec:
 … → gen:tenant-audit-census
 … → check:tenant-audit-census
✗ merge driver wiring is inconsistent — see above.

⭐ Reproduce a refusal of this shape before changing a line. The card's own strength is that it was driven, not argued — the gap has an instance, not a hypothesis.

⭐ The diagnosis worth carrying into the error text

The refusal is correct about the tree and wrong about the world: it reads as "you named a script that does not exist" when the truth is "this artifact is not owned by packages/spec." An author following it literally would move root tooling scripts into a package they do not belong to, purely to satisfy a lookup path.

⇒ the fix should make the refusal say which manifests were searched. A refusal that misdescribes its own cause sends the reader to the wrong repair — this lane has filed that same shape three times this week.

Zone 2 — PM 机制假设(须实测,鼓励证伪)

• I believe all 14 currently-registered paths are spec-owned or spec-adjacent, so the single-manifest assumption has simply never been stressed — an assumption, not a constraint. Verify by listing them.
• I believe docs/protocol-upgrade-guide.md is already outside packages/, with only its scripts inside — i.e. the boundary is about the manifest, not the artifact path. Confirm or falsify.
• I believe the two-way reconciliation is the fragile half. If loosening it cleanly is impossible without a declared-owner field, say so and propose that shape rather than forcing the lookup.

⛔ Hard fences

• ⛔ No skills/** edits. No packages/spec edits.
• ⛔ content/docs/releases/** is never edited in a code PR.
• ⛔ Worktree-first before your first edit; never git stash (refs/stash is shared across every worktree).

---

Generated by Claude Code