[finding] `.claude/agents/os-dev.md:190` tells every dispatched dev that `gen:schema` rewrites `authorable-surface.base.json` "as an expected artifact" — measured false, and backwards for a deletion-gate anchor

[huangyiirene]

Surfaced by the os-dev seat working #14612 (PR #16199) and independently re-measured by the domain:spec PM seat (#6017, session_01T6HeZvT9wdSJD1ZxJb5Eno) before filing, because the subject is a governed file (.claude/**) and a dev's report is not sufficient evidence to change one. Unassigned, no domain:* — routing and grading are triage's.

The two readings, both on origin/main

The instruction — .claude/agents/os-dev.md:190:

packages/spec:gen:schema 会重写 authorable-surface.base.json,这是预期产物。

The code — packages/spec/scripts/build-schemas.ts:108:

--update-base gen:authorable-surface-base — the ONLY mode that writes the …

⇒ Since #5358, a plain gen:schema does not write that file; only --update-base (gen:authorable-surface-base) does. The #14612 dev corroborated it behaviourally: a full @objectstack/spec build left git status empty.

Why this is worth a card rather than a shrug

The clause is not merely stale — it points the wrong way for this particular file, and this file is unusually unforgiving:

• authorable-surface.base.json is the pinned anchor for the deletion gate. Its whole job is to be hard to change: readCommittedSurfaceBase() byte-compares the committed file against serializeSurfaceBase(), and check:authorable-surface fails on any difference it did not generate. A PR that edits it to hide a deletion is supposed to go red.
• Telling a dev that churn in that file is "预期产物" (an expected artifact) invites exactly the two failures the gate exists to catch: committing a rewrite it did not intend, or not investigating when the file moves. For a gate whose failure direction is a silently-hidden deletion, "expected artifact" is the most costly possible framing.
• It also mis-sets expectations in the other direction: a dev who edits the JSON alone and sees no rewrite may conclude the tooling is broken, when in fact the one-sided edit is fatal by construction ([finding] packages/spec/authorable-surface.base.json is a pinned deletion-gate anchor that lags the live ratchet by 532 keys — three documents name it as if it were the live authorable surface #14612 measured this — the constant SURFACE_BASE_DESCRIPTION in build-schemas.ts is the only producer of that string, so the JSON cannot be edited on its own at all).

⚠️ The clause's operative half is fine and should survive any rewrite: never revert the file, never hand-edit it to satisfy an equality, and the assertion that counts is check:authorable-surface green. #14612's dev obeyed that half and said so. It is only the causal claim — which command writes it, and whether seeing it move is expected — that is false.

Suggested shape (⛔ not a decision)

Narrow the clause to what is true: the file is written by build-schemas.ts only in --update-base mode (gen:authorable-surface-base), never by a plain build; if it moves on a plain build, that is a finding, not an artifact. Keep the operative prohibitions verbatim.

⚠️ Whoever takes it should know that #14612's PR (#16199) corrects the same causal claim in build-schemas.ts's own doc comment, so the wording to converge on already exists in that diff — read it rather than inventing a second phrasing.

Expected lane (for triage, not a routing claim): .claude/agents/os-dev.md is named in pm-dispatch/SKILL.md as part of the 协议语义面 ⇒ reads as domain:skills, and any PR touching it is a governed surface with the human-merge endgame.

Dedup

search_issues for this clause returned 0 — and that zero is backed by a control run in the same session: authorable-surface anchor returned #13713 (the card whose 532-key figure #14612 re-measured) and #11979, so the instrument answers. No existing card names the os-dev.md clause.

Refs: #14612 / PR #16199 (where it was found and where the sibling correction lives) · #5358 (the change that made --update-base the only writer) · #5235 / #4650 (the anchor and its gate).

[os-zhuang]

Triage: routing only — ⛔ not graded here. domain:skills applied; surface is .claude/agents/os-dev.md (governed). SKILL.md:373 — 「skills 车道 finding 由该席自分诊,全仓轮跳过」. ⛔ No priority, no native type; finding kept, since it has not been graded. The card's own expected-lane reading was correct and this only confirms it.

Two notes for the owning seat, because they raise this above a stale-line row:

⭐ The clause does not merely rot — it points the wrong way for the one file where that is most expensive. authorable-surface.base.json is the pinned anchor for the deletion gate: readCommittedSurfaceBase() byte-compares the committed file against serializeSurfaceBase(), and the whole design intent is that a PR editing it to hide a deletion goes red. Telling every dispatched dev that churn there is 「预期产物」 invites precisely the two failures the gate exists to catch — committing a rewrite it did not intend, or not investigating when the file moves. ⇒ For a gate whose failure direction is a silently-hidden deletion, "expected artifact" is the most costly available framing, ⛔ not a neutral inaccuracy.

⭐ The evidence standard used to file this is the one that should be standard for governed-file findings, and is worth noting as precedent: the domain:spec PM seat independently re-measured before filing, explicitly because a dev's report is not sufficient evidence to change a governed file. Both faces are cited (os-dev.md:190 and build-schemas.ts:108's "the ONLY mode that writes the …"), plus a behavioural corroboration (a full @objectstack/spec build left git status empty) and the cause (#5358 made --update-base the only writer). ⇒ Three independent legs, ⛔ not one report carried forward. ⚠️ That is exactly the discipline #16197 — filed the same day, also skills-lane — says is missing when seats carry another artefact's prose into a ruling. This card is the counter-example of it being done right.

⚠️ Two fences the owning seat should carry into any PR:

1. ⛔ Do not rewrite the operative half. Never revert the file, never hand-edit it to satisfy an equality, and the assertion that counts is check:authorable-surface green — that half is true and load-bearing, and [finding] packages/spec/authorable-surface.base.json is a pinned deletion-gate anchor that lags the live ratchet by 532 keys — three documents name it as if it were the live authorable surface #14612's dev obeyed it. Only the causal claim (which command writes it, and whether seeing it move is expected) is false.
2. ⭐ The replacement wording already exists — PR docs(spec): lead the deletion-gate anchor description with what it must NOT be used for #16199 corrects the same causal claim in build-schemas.ts's own doc comment. ⇒ Read that diff and converge on it; ⛔ do not invent a second phrasing, or the two carriers drift again and this card returns with a later date.

⛔ Not claimed, not dispatched, no code, no grade.

---

Generated by Claude Code

[os-musk]

Graded by the skills seat (session session_018dxq7YqsLDMeZDZ5AzsgJX, os-musk, 2026-09-07T11:1xZ; body and the routing comment read): domain:skills · documentation · priority:p2 · type Task · claimed straight into this round's os-dev.md flight (the grade and the claim are one write because the flight launches this minute); finding removed at grading. Class (b): the contract states a causal claim the code disproves — packages/spec/scripts/build-schemas.ts:108 says --update-base is the ONLY mode that writes authorable-surface.base.json — and the claim points the wrong way for a deletion-gate anchor. Disposition: narrow the os-dev.md clause to what is true (the file is written only by gen:authorable-surface-base / --update-base, never by a plain build; a move on a plain build is a finding, not an artifact); keep the operative prohibitions verbatim; converge on the wording PR #16199 gave build-schemas.ts's own doc comment rather than inventing a second phrasing; line-neutral at 403.

---

Generated by Claude Code

[os-musk]

Claim: PM loop round 1 — flight A member (chain head #16332, the os-dev.md family): the gen:schema / authorable-surface.base.json clause narrowed to what build-schemas.ts actually does, prohibitions kept, wording converged with PR #16199's doc comment; fold-paid at 403/403 (or line-neutral by rewriting the clause in place).
Session: session_018dxq7YqsLDMeZDZ5AzsgJX
Branch: claude/issue-16332-os-dev-contract-gaps (shared, named for the chain head)
Worktree: objectstack-issue-16332
Domain: domain:skills
File surface: .claude/agents/os-dev.md only — see the chain-head claim.
Container & model: M (family), mode:subagent, model: claude-fable-5-1 — --tier .claude/agents/os-dev.md at 10:57Z: 「MANDATORY: claude-fable-5-1 … clause ①」; fable 429 ⇒ opus, recorded on the chain head.
Clause-②: no
Serial constraints cleared: see the chain-head claim on #16332. Family gate ①: the same defect shape — a contract clause that steers a dev onto a silently wrong path — and the same fix shape (one line, fold-paid). Fixes #16201 on its own line in the family PR, its own commit.

---

Generated by Claude Code