docs(agents): a rule's provenance cites the ADR or ruling record, then the commit sha — and runtime strings carry no tracker number

[os-steve]

Fixes #19294

Clause-②: no

AGENTS.md's register paragraph told every agent that a rule's provenance lives in the PR that landed it. Merged-PR numbers decay out of GitHub — the spec seat measured 11.7 %–15.1 % of one week's already deleted, with no 301 and an empty commit-to-PR association — so that convention pointed every reader at objects this repository does not control and has measured itself destroying. The maintainer ruled the replacement (decision batch #195 item 3 letter C+D, verbatim and untranslated: 「同意」; the director recorded it on the card this PR lands on). The sentence is REPLACED, not appended to: no second convention survives beside it.

grep -n -iE 'provenance|PR that landed|landed it' AGENTS.md on 57ceb9d returns two hits — the sentence at :14 and, at :253, the unrelated instruction that a repo-local ADR mirroring a cloud decision carries a ## Provenance section. The convention is stated once, so one sentence is replaced and nothing else in the file restates it.

Before / after — AGENTS.md :14, against 57ceb9d

Before:

(`pnpm check:pm-skill-id-lint`) — a rule's provenance lives in the PR that landed it. Where
a hook or CI gate enforces a rule mechanically, the rule is stated once here and the
script's own header is the authority on detail.

After:

(`pnpm check:pm-skill-id-lint`) — a rule's provenance cites the ADR or ruling record that
decided it, otherwise the commit sha in this repository's history; a PR number is a
convenience link, ⛔ never the citation. Runtime strings — refusal prose, prescriptions,
anything an author is shown — carry no tracker number (`pnpm check:doc-authoring`): the
lesson goes into the text. Where a hook or CI gate enforces a rule mechanically, the rule is
stated once here and the script's own header is the authority on detail.

The ruled clauses land in the ruling's own order: the ADR or ruling record first (stable, in-repo, it carries the narrative); otherwise the commit sha in this repository's history (immutable, and git reads it with no network); a PR number demoted to a convenience link and ⛔ never the citation. Letter D is the sentence after it — runtime strings carry no tracker number, under the maintainer's standing words 「处理 issue 时犯的错应该总结成经验,保留 issue id没有意义」: the lesson is written into the text instead of a number the reader must dereference.

The neighbouring clause about mechanical enforcement is kept intact, and the new text obeys itself — it carries no bare tracker number, and pnpm check:pm-skill-id-lint, which scans AGENTS.md against the pattern it names, is green on it.

Stated precisely rather than implied: the gate cited for letter D reaches packages/ minus packages/spec today, on a shrink-only baseline of 821 pinned sites across 231 files. The prose states the repo-wide rule; extending the gate's reach is the separate card already named on the issue body, not this one.

The AGENTS.md line ratchet — paid at net 0, the ceiling untouched

The ruled text is +3 physical lines and AGENTS.md sat at headroom 0 (1099 / 1099), so the first head (9f35c66) measured pnpm check:pm-skill-ratchet :: exit 1. The seat widened this card's file surface so the three lines are paid in RETIRED CONTENT — each retired fragment is a verbatim restatement of a rule whose home is another line, or a second pointer to a file already pointed at from a surviving line — ⛔ never by raising the ceiling (the CEILINGS row in scripts/pm/check-skill-line-ratchet.mjs is untouched at 1099). Head a799442: AGENTS.md 1099 → 1099, pnpm check:pm-skill-ratchet :: exit 0.

retired (pre-edit line)	what it was	the rule still lives at
:58–59 「; the script headers are the authority on detail」	restatement	:19 — the register paragraph's own clause; the two gates it qualified stay named on the line
:452–453 「The two measured mutation shapes and their triggers live in pm-dispatch references/platform-readings.md.」	second pointer	:433–434, two paragraphs above in the same section
:758–759 「(shape, sha256 vs that record, record pin == .objectui-sha)」	the gate's detail list	:19 (the script's own header is the authority on detail); scripts/check-sdui-manifest.mjs stays named; the regenerate-on-pin-bump rule at :159–161
:760–761 「— "could not run" is a failure, not a skip (Route & surface ownership §3) —」	restatement + second pointer	:851–855, Route & surface ownership rule 3

All three lines are bought by deleted content, none by re-wrap: each untouched paragraph greedy-wraps to exactly the line count it already had. Candidates rejected and why (an only pointer; PR #19214's reserved region :931–:956; fragments that buy no line; a loosely wrapped paragraph whose lines would be re-wrap currency; gate-pinned governed-surface enumerations) are on the card's second os-dev-report.

Verification

Derived union on a799442 (re-run after the retirements and one merge of origin/main), node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack with no paths, reconciled with --ran: 15 derived, 15 run, 0 NOT-MEASURED, 0 UNRUN, every exit captured before any pipe.

Green (15): check-closing-keyword-parity (gate and --self-test), check-comment-mask-corpus, check:agent-test-spelling, check:docs-audit-scope, check:driver-memory-census, check:gitlink-declared, check:nul-bytes, check:pm-governed-merges, check:pm-governed-prose, check:pm-skill-id-lint, check:refd-timer-probe, check:required-contexts, check:watch-hint-literal, check:pm-skill-ratchet (AGENTS.md 1099 lines, ceiling 1099, headroom 0).

Run beyond the union because the new text names it: pnpm check:doc-authoring :: exit 0 — 403 files clean, 44 published skill files clean, 15881 customer-facing strings across 1013 spec sources clean, sibling-package prose ids holding the baseline.

No package is touched, so there is no dependency closure to build and no package test suite in scope; the repo-wide pnpm lint scan is CI's run, not this PR's. skip-changeset: AGENTS.md is a repo-root instruction file and ships in no package's files[].

Acceptance notes

• Noted, not filed: the gate cited for letter D excludes packages/spec from its prose-id leg and runs on a shrink-only baseline, so the mechanical reach is narrower than the prose rule. Carrier: the reach card already named on the issue body — no new card.
• Noted, not filed: the CEILINGS row for AGENTS.md now carries four stacked per-card narratives in a gate script whose own header prescribes moving narrative out of operational text. Carrier: the next ceiling raise on that row, PR docs(agents): say how a return-delivered durability seam is declared #19214, already in flight.

维护者速读(草稿)

改了什么 — AGENTS.md 开头「规则登记册」那一段里的一句:规则的出处从「落地它的 PR」改成「先引 ADR / 裁决记录,没有就引本仓的 commit sha,PR 号只能当顺手链接」;并补上一句「运行时字符串(拒绝文案、处方、任何打给作者看的文字)不带任何 issue 号,把教训写进正文」。这三行的增量由退掉文件里四处重复陈述 / 重复指针付账(上表),文件净 0 行,行数棘轮上限没动。

为什么改 — 旧写法把读者指向 GitHub 上的 PR 号,而实测一周内已合并 PR 号有 11.7%–15.1% 已经被删除(没有 301,commit 到 PR 的关联是空的)。也就是说,规则的出处指向了一个本仓库不拥有、而且已经被测到正在消失的对象。ADR / 裁决记录和 commit sha 都在仓库里,不会消失。这是您在裁决批次 #195 第 3 项 C+D 上批的「同意」。

风险与代价(含回滚) — 风险很低:改的是一句给 AI 和人看的约定,没有代码、没有发布面、没有 changeset。代价是退掉的四处重复文字,每一处的规则仍住在上表点名的行;若您认为哪一处不该退,恢复它是一行 revert,但要同时退别的一行才能过棘轮。回滚就是 revert 这一个 commit,没有任何下游依赖。

席位意见 — (留空,席位复审时定稿)

你要做的 — 一件事:确认正文措辞后点合并(Tier H,这个 PR 一直是 draft,席位已做 ACCEPT;棘轮已绿,不需要您裁行预算)。

---

Generated by Claude Code

[os-steve]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: a799442150f5db0beb19b71741c3f59ae53d43b9

① Derived judgments

• Published accept set / public surface: none moves — the repo-root instruction file (AGENTS.md, +25 / −25, net 0: 1099 → 1099 against a ceiling of 1099, the CEILINGS row untouched), three commits (the ruled sentence; the retirements that pay for it; one merge of origin/main, no rebase). check-governed-merges --pr 19453: GOVERNED — Tier H, 50 changed lines under the human-merge line — the maintainer's click lands it; the PR stays draft. Judged correct.
• The fix, read line by line: :14 REPLACED, not appended — 「a rule's provenance cites the ADR or ruling record that decided it, otherwise the commit sha in this repository's history; a PR number is a convenience link, ⛔ never the citation. Runtime strings — refusal prose, prescriptions, anything an author is shown — carry no tracker number (pnpm check:doc-authoring): the lesson goes into the text.」 — the three clauses of batch chore(deps)(deps-dev): bump @types/node from 20.19.30 to 25.0.10 #195 item 3 letter C+D in the ruling's own order, the neighbouring mechanical-enforcement clause kept intact, no second convention surviving (the only other provenance in the file, :253's ## Provenance section rule, is unrelated); the new text obeys itself (no bare tracker number; the id-lint that scans this file is green). The +3 lines paid by four retirements the seat re-read in the diff: :58–59 「the script headers are the authority on detail」 (the register paragraph's own clause at :19), :452–453 a second pointer to references/platform-readings.md (:433–434 two paragraphs above), :758–759 the check-sdui-manifest detail list (:19; the script stays named; the pin-bump rule at :159–161), :760–761 the 「could not run is a failure」 restatement and its §3 pointer (Route & surface ownership rule 3 at :851–855). Each rule still lives where the table says; nothing retired is an only pointer, nothing sits in PR docs(agents): say how a return-delivered durability seam is declared #19214's region, nothing is gate-pinned prose. Judged correct.
• Evidence, seat-run on this head in a detached worktree: check-skill-line-ratchet.mjs exit 0 (AGENTS.md 1099 lines, headroom 0; widest table row 768 / 768), check-skill-id-lint.mjs exit 0, check-governed-prose.mjs exit 0; merge-tree vs origin/main 8e368dc: 0 conflicts; CI on a799442: 26 check runs, 1 still running, 0 red. The dev's union 15 / 15 exit 0 with --ran reconciled on this head (the STALE TREE warning cleared by the merge), check:doc-authoring exit 0 (403 files clean), check:pm-dispatch-gates exit 0 in round 1 with no dispatch-gates source changed since (measured).

② Semver level

None — nothing published (AGENTS.md ships in no package's files[]); skip-changeset on the PR is the correct declaration. Judged correct.

③ Boundary flags

open_questions empty after the rework — the round-1 blocker (a +3 line-budget ruling) is dissolved by paying the ratchet in retired content, the route the ratchet's own header names beside the raise. The PR body was stale after the rework by the seat's own instruction; the seat rewrote its ratchet section, the verification line and the 维护者速读's 风险 / 你要做的 items on this head (PATCH /pulls/19453 with the payload's footer stripped, read back: exactly one footer, content byte-identical) — the maintainer now reads one act: the merge click. All four mechanism assumptions confirmed (:14 as it stood; PR #19214 at :931–:956 region-parallel and untouched; GOVERNED Tier H; the id-lint and doc-authoring gates green — the latter run as a declared extra since AGENTS.md is outside its scan roots). Deviations read and accepted (the merge of origin/main touching no AGENTS.md line; the round-1 commit message's overstated gate reach, precise in the body; the PR relabelled by another actor — size/s, documentation). Three noted, not filed items carry their carriers (the gate's narrower reach — the reach card on the issue body; the stacked CEILINGS narratives — PR #19214; two more retirable restatements at :720 / :865 — the next PR that needs lines in this file).

Implemented-by: claude/issue-19294-provenance-cites-record-then-sha
Reviewed-by: session_017ETYWqMQD4qMtZzAGovWNi

VERDICT: PASS

---

Generated by Claude Code