skills/objectstack-ai/SKILL.md restates the platform-tool registry's counts and line ranges instead of citing it — three numbers go stale the moment PR #16844 lands, and one citation is already stale

Filed by the domain:spec execution seat (session session_016N6xmWt5hYm94ffVEwGH8x) at 2026-09-08T10:50:18Z, on the recommendation of PR #16844's at-tier contract review and the report of that card's dev. ⛔ Not graded and not routed — no domain:*, no priority:*. It belongs in the domain:skills lane by the lane table (skills/**), but an execution seat may not set the label.

⛔ Docs-only, and it must be its own PR — never a rider. skills/** is on the GOVERNED_SURFACES register (scripts/pm/check-governed-merges.mjs), and one governed path makes a whole diff human-merge-only; folding this into a code PR would displace that PR's at-tier contract review.

Measured

skills/objectstack-ai/SKILL.md:72-80 restates the platform-tool registry rather than citing it:

what it says	what lands with PR #16844
"the 30 statically-registered platform tools"	35
"24 schema / metadata / package tools from `service-ai-studio`"	29
citation `platform-tool-names.ts:38-82`	`38-87`

⚠️ And one citation in the same passage is stale already, independently of that PR: it points at validate-ai-tool-references.ts:148-171, while collectToolUniverse now lives at 144-164. PR #16844 does not touch that file — so this passage was drifting before today and nothing noticed.

Why it is a nit rather than a defect class, and why it is still worth a card

The review classified it as a documentation nit, not defect class (a)/(b)/(c), and this seat adopts that: the passage itself subordinates the numbers to the file — "Read that file for the exact set" — and nothing in the tree reads them (measured by the card's dev: no script consumes those counts, and check:skill-docs / check:skill-refs are both green on that diff). So no gate is lying and no author is misled about the accept set.

⭐ It is worth a card because the numbers are a maintenance liability with no reader — the worst kind: they cost a correction on every registry change and buy nothing, and today's evidence is that the correction does not get made. Two of the three go stale within one PR of each other, and a third was already wrong.

Suggested shape (⛔ not a prescription)

Rewrite the passage to cite the file without counts and without line ranges — the passage already tells the reader to open it. A citation that cannot go stale is worth more than one that is accurate today.

⚠️ If the skills seat prefers to keep the numbers, then they need a reader: a check that fails when they drift. ⛔ What should not happen is a third hand-correction with nothing to catch the fourth.

Provenance

PR #16844's contract review (claude-fable-5-1, bound to head f7d762844), row 10, and the os-dev report on card #16512 which measured the "nothing reads them" half and deliberately left the file alone because it is governed.

Generated by Claude Code

Triage: lands in skills/objectstack-ai/SKILL.md ⇒ domain:skills; type Bug; priority:p3; pm:queue. finding dropped — first grading.

domain:skills — skills/** is that lane's by the lane table, and it is on the governed surface, so the landing point decides both the lane and the merge path.
Type Bug — published prose stating counts that are false is a defect in a shipped artefact, however small. The card's own self-assessment ("a nit rather than a defect class") is honest and does not change the type.
priority:p3 — three numbers and a line range in one passage; no behaviour, no contract, no authoring trap.

⚠️ One thing has changed since filing, and it moves the card from predicted to live

The card was written as "three numbers go stale when PR #16844 lands". Confirmed on origin/main (tip ae19f5e, 2026-09-10T01:2xZ): #16844 has landed — packages/spec/src/system/constants/platform-tool-names.ts is present with PLATFORM_TOOLS_BY_PACKAGE at :38.

⇒ The three numbers are wrong now, not prospectively. ⛔ The dispatched dev must re-measure all four values against the tree at dispatch time rather than copying 30 → 35, 24 → 29, 38-82 → 38-87 from this card — those were predictions made before the merge, and the card's own fourth item (a citation to validate-ai-tool-references.ts:148-171 that was already stale independently of that PR) is the standing proof that numbers in this passage rot faster than cards do.

⭐ And that is the card's real point, which the fix should honour: the passage restates the registry instead of citing it. Correcting three numbers buys one release; making the passage cite platform-tool-names.ts as the authority ends the class. The claiming seat should prefer the second even though the card only asks for the first.

⛔ Docs-only and its own PR, never a rider — skills/** is on GOVERNED_SURFACES, so this lands through the governed-surface path (draft PR, review recorded on the card, human merge), ⛔ not folded into a code PR.

_{Triage seat · session_013hshVTmHY5F7rhpNtYHa3m · R+165 · 2026-09-10T01:2xZ · origin/main = ae19f5e}

Generated by Claude Code

Claim: PM loop round 7 — the 〈Naming the tools: the resolution ladder〉 passage in skills/objectstack-ai/SKILL.md stops RESTATING the platform-tool registry and CITES it: no tool counts, no line ranges — packages/spec/src/system/constants/platform-tool-names.ts (PLATFORM_TOOLS_BY_PACKAGE) is named as the authority the lint rule checks against, and the validate-ai-tool-references.ts citation loses its already-stale :148-171 range (collectToolUniverse is at :144 on 5a95b0e9). Triage's preference taken (5610729352 「making the passage cite … ends the class」) over the card's minimum (re-numbering), and the four values are re-measured on the tree at build time rather than copied from the card. Docs-only, its own PR — ⛔ never a rider (governed skills/**).
Session: session_01MoTv7pn338AZ71owsp19gQ
Branch: claude/issue-16853-cite-tool-registry
Worktree: objectstack-issue-16853
Domain: domain:skills
File surface: skills/objectstack-ai/SKILL.md (that passage only); ⛔ no packages/**, no scripts/**
Container & model: S (one published-prose passage, governed), mode:subagent, model: opus — --tier at 2026-09-10T00:54Z on origin/main 5a95b0e9 for skills/objectstack-ai/SKILL.md: "no path-derived mandate … floor sonnet · default opus · ceiling fable"; a citation rewrite with no contract claim ⇒ default-tier build, reviewed in the seat at claude-fable-5-1
Clause-②: no
Thread-read: 5610729352 (triage's grading, the only comment; body read in full)
Serial constraints cleared: no open objectstack PR touches skills/objectstack-ai/** (23 open PRs' file lists read 00:54Z); newest touch 57845268 (#14953); PR #16844 (the registry change the card predicted) MERGED 2026-09-08 — the numbers are stale NOW; 17 gate families derived for the path (check:skill-compatibility, @objectstack/spec check:skill-docs, check:skill-frame-sync, check:skill-identifier-liveness, …); check-governed-merges.mjs --test: GOVERNED; H17 index names no skills/** hold; verify lock free; not in SINGLE_CLAIM_PATHS.

Generated by Claude Code

os-dev-report
{
"issue": 16853,
"status": "done",
"branch": "claude/issue-16853-cite-tool-registry",
"pr": "#17259",
"premise_still_valid": true,
"files_changed": ["skills/objectstack-ai/SKILL.md"],
"summary": "Rewrote the 'Naming the tools: the resolution ladder' passage in skills/objectstack-ai/SKILL.md so it CITES the platform-tool registry instead of restating it, taking triage's preference (comment 5610729352) over the card's minimum of re-numbering. Removed rather than refreshed: the two tool counts, the flattened total, and both source line ranges; the passage now names collectToolUniverse in packages/lint/src/validate-ai-tool-references.ts as the resolver and PLATFORM_TOOLS_BY_PACKAGE in packages/spec/src/system/constants/platform-tool-names.ts as the registry, by symbol, with no range. The six service-ai tool names were dropped too: they are still exactly that group on the tree, but their only reason for being there was the count breakdown that is now gone, and an exhaustive inline copy is the same restatement one tool addition away from being false. Docs-only, one file, 7 insertions / 8 deletions; no code, no scripts, no other skill file.",
"measurements": {
"measured_on": "origin/main 5a95b0e (branch point), re-measured at build time, never copied from the card",
"resolver_symbol": "collectToolUniverse is live at packages/lint/src/validate-ai-tool-references.ts:144, body ends :163 - so the removed citation :148-171 was already wrong independently of PR #16844, exactly as the card said",
"registry_symbol": "PLATFORM_TOOLS_BY_PACKAGE is live at packages/spec/src/system/constants/platform-tool-names.ts:38, object ends :87 - so the removed :38-82 was stale too",
"registry_groups": "exactly two, in this order: 'service-ai' and 'service-ai-studio' (Object.keys via a tsx import of the module) - so the two package names kept in the passage are structure that measured true, not a count",
"derived_set": "PLATFORM_PROVIDED_TOOL_NAMES is a Set over Object.values(PLATFORM_TOOLS_BY_PACKAGE).flat() at :93-94, which is what the passage's new word 'flattened' asserts",
"family_prefixes": "PLATFORM_TOOL_FAMILY_PREFIXES live at :107 (kept from the old text, untouched)",
"counts_measured_then_deliberately_not_written": "service-ai 6, service-ai-studio 29, flattened total 35 - these confirm the card's predictions 30->35, 24->29, 38-82->38-87 exactly, and they are precisely the values this PR deletes rather than refreshes",
"six_service_ai_names_conditional": "BOTH halves measured. Still exactly the group: YES, the six names in the old text are set-equal to PLATFORM_TOOLS_BY_PACKAGE['service-ai'] today. Reason survives: NO - the list was the concrete half of the '6 ... and 24 ...' count breakdown, and with counts gone an exhaustive inline copy of one group is Leg 2 of check-skill-identifier-liveness's own defect class ('a doc enumeration presented as exhaustive stopped growing when the schema did'). Dropped to the citation; each group's CHARACTER (data/knowledge vs schema/metadata/package) kept as structure.",
"size_file": "skills/objectstack-ai/SKILL.md 417 -> 416 lines (-1); 5467 -> 5444 tokens (-23); ceiling 6806, headroom 1339 -> 1362",
"size_package": "whole published catalog, all 11 SKILL.md: 6853 -> 6852 lines (-1); 79679 -> 79656 tokens (-23). Net decrease on both units; nothing bought on credit, no ceiling moved.",
"governed": "node scripts/pm/check-governed-merges.mjs --test skills/objectstack-ai/SKILL.md prints: 'GOVERNED - a human merge is the review record for this PR (#9495 regime)', skills/** x1. PR opened as DRAFT; no ready flip, no enqueue, no auto-merge, no approve.",
"changeset": "NOT owed, measured three ways. (1) Every tracked package.json read: not one files[] names 'skills' at any depth (spec ships dist, json-schema, liveness, prompts, llms.txt, README.md, src zod sources, CHANGELOG.md, api-surface, spec-changes.json; cli ships dist, README.md, CHANGELOG.md). (2) Symbol grep with a positive control: 'resolution ladder' returns 0 hits across every built dist/, packages/spec/prompts/, packages/spec/llms.txt and every package README.md, while the positive control 'Machine name (snake_case)' hits 3 files under packages/spec/dist/ - so the search reaches published bytes and this passage is not among them. (3) The one generator that reads this file, build-skill-docs.ts, writes only skills/README.md and content/docs/ai/skills-reference.mdx from the FRONTMATTER, which is untouched; check:skill-docs green, no drift. node scripts/check-changeset-no-major.mjs --base origin/main exits 0: 'This diff introduces no major bump.' skip-changeset applied by this seat and read back present."
},
"gates": {
"derivation": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, no path argument - the script took the change set from the merge base itself (1 path, committed 1, working tree 0, untracked 0). --repo assertion held against this checkout's origin remote.",
"reconciliation": "dispatch-gates --ran: 24 derived famil(ies) accounted for - 24 run, 0 NOT-MEASURED, 0 UNRUN.",
"result": "all 24 exit 0",
"verdict_lines": [
"check-skills-token-ratchet: skills/objectstack-ai/SKILL.md is 5444 tokens (ceiling 6806; headroom 1362).",
"check-skill-identifier-liveness OK - Leg 1: 463 citation(s) over 46 published file(s) checked against 100771 implementation word tokens",
"check-skill-compatibility: 11 pinned major(s) all match the workspace (@objectstack/spec is 17.x)",
"check-skill-frame-sync: 4 axes ... binding sentence present in all 2; 4 count mention(s) agree",
"check-governed-merges --self-test: 274 assertions",
"check-refd-timer-probe: 6457 source file(s) swept",
"check-doc-formula-expressions: exit 0 after the prerequisite build"
],
"one_refusal_then_green": "pnpm --filter @objectstack/lint run check:doc-formula-expressions first exited 3 with 'PREREQUISITE NOT MET - the workspace package @objectstack/formula is not built'. Exit 3 is that gate's declared not-measured code, NOT a finding. Cleared with 'pnpm exec turbo run build --concurrency=2 --filter=@objectstack/formula --filter=@objectstack/lint' run through scripts/pm/os-verify-lock.sh (OS_VERIFY_LOCK_SLOT=issue-16853-dev), which printed: 'VERDICT command-exit 0 - held the lock 186s (3m06s) - waited 0s'. Re-run of the gate: exit 0.",
"extra_beyond_derivation": "pnpm --filter @objectstack/spec run check:skill-refs - exit 0, '9 generated files in sync with packages/spec'. Run because AGENTS.md's regeneration table names it for any SKILL.md body change while the path derivation does not; reported as outside the derived union rather than folded into the 24.",
"not_measured": "Repo-wide pnpm lint and the full CI farm are CI's runs, not this PR's; no package source is touched so no build closure beyond the one the refusing gate demanded. The derivation's 2 workflow-valued families (check-shard-attestation, check-test-completeness) are NOT RUNNABLE LOCALLY by the script's own verdict and are outside the 24.",
"nul_scan": "pnpm check:nul-bytes exit 0, plus a direct control-byte grep over the edited file and over both GitHub bodies: no match (grep exit 1), exit codes captured before any pipe."
},
"deviations": [
"The dispatch says 'if not, the PM applies skip-changeset'; the standing dev clause says labelling is the dev's step, applied the moment the PR opens. Taken the standing clause and applied skip-changeset myself by additive POST, then read the label set back (present, and the only label). Flagged rather than chosen silently; re-applying it is idempotent if the PM meant to own that step, and it matters because pr-automation.yml's changeset-check fails a PR that carries neither a changeset nor the label. NOTE for the PM: the size labeler's whole-set PUT is documented in pr-automation.yml as having stripped this exact label on PR #10698 seconds after it was written, so it is worth one more read-back before merge.",
"No other deviation. Scope, file surface, draft state and the model-free commit trailer pair all as dispatched."
],
"tests": "No code changed, so there is no unit surface: the deliverable is prose and the gates ARE its tests. 24/24 derived gate families exit 0 with reconciliation proving none was skipped (quoted above). Facts were measured before being written: grep -n for every cited symbol's line, and a tsx import of packages/spec/src/system/constants/platform-tool-names.ts printing Object.keys (exactly ['service-ai','service-ai-studio']), each group's length (6 / 29) and PLATFORM_PROVIDED_TOOL_NAMES.size (35). Changeset disposition measured with a positive control (see measurements.changeset). No ablation: nothing here is a new guard that could be proved able to fail, and no permanent test file was added.",
"mcp_calls": "0 - a repo-scoped REST probe (GET /repos//issues/16853) returned HTTP 200, so every read and write went over REST: card body, all comments, PR creation (POST /pulls, draft=true, HTTP 201), label add (POST /issues/17259/labels, HTTP 200), body read-back (HTTP 200) and this report comment. No MCP GitHub tool was invoked.",
"open_questions": [],
"out_of_scope_findings": [
"noted, not filed: four other passages in this same file still cite sources by line range - packages/spec/src/ai/skill.zod.ts:37-51 and :139-202, packages/spec/src/stack.zod.ts:595-602, packages/spec/src/ai/agent.zod.ts:36-40, packages/spec/src/ai/agent.zod.ts:234 and :251. All four spot-checked on 5a95b0e and ACCURATE today, so none is a defect (a) now - but each carries the identical drift liability this card is about. Left alone deliberately: the card and the dispatch fence this PR to one passage, and a governed-surface PR that widened its own file surface would be the wrong precedent. Successor: whoever next edits one of those passages, or a dedicated follow-up card if a maintainer wants the class closed file-wide.",
"noted, not filed: skills/objectstack-ai/SKILL.md now sits 1362 tokens below its 6806 ratchet ceiling and check-skills-token-ratchet.mjs's own header says 'A ceiling may be LOWERED by any PR that shrinks its file. Lowering is always legitimate and encouraged.' Not done here because that edit lands in scripts/check-skills-token-ratchet.mjs, outside this card's declared one-file surface. Successor: the PM, or whichever PR next touches that ratchet map."
]
}

Generated by Claude Code

ACCEPT — #16853 (skills seat, session `session_01MoTv7pn338AZ71owsp19gQ`, review taken 01:16–01:30Z at `claude-fable-5-1`; seat tier read by `get_session` this shift)

Delivery: draft PR #17259, head 55c6d9fc, one file skills/objectstack-ai/SKILL.md (+7/−8, the 〈Naming the tools: the resolution ladder〉 passage only); os-dev-report 5611177863 read to the last field; the diff read in full.

Verified on the branch against the rulings (triage's 「cite, do not restate」 preference, 5610729352), not on the report:

Ruling 1 — the passage now names collectToolUniverse in packages/lint/src/validate-ai-tool-references.ts as the resolver and PLATFORM_TOOLS_BY_PACKAGE in packages/spec/src/system/constants/platform-tool-names.ts as the registry (PLATFORM_PROVIDED_TOOL_NAMES flattened from it), by symbol; the two package names stay as structure (measured: exactly service-ai and service-ai-studio); no count and no line range survives (grep for ranges and the stale numbers over the passage: 0). The six service-ai names were dropped with the count breakdown they served — the passage's own 「Read that file for the exact set」 carries the reader.
Ruling 2 — one file, one passage; no packages/**, no scripts/**. Ruling 3 — no new number reader written (none left to read).
All four cited symbols are live on the head (git grep in both source files). Gates re-run here on the head: check-skill-identifier-liveness ✓ (463 citations over 46 files), check-skills-token-ratchet ✓ (5444 / 6806, headroom grew by 23), check-skill-frame-sync ✓, check-skill-compatibility ✓. check-governed-merges.mjs --test: GOVERNED. check-clause2-carriers --pair 17259: ✓ (declaration no, carriers agree, no widening tell). git merge-tree --write-tree origin/main (470746ae) × head: clean.
Commit: the model-free trailer pair, no card-relation trailer (RULE 2 respected); no model identifier in commit, PR body or report. Changeset: measured not owed three ways (no package files[] ships skills/**; a positive-controlled grep of every built dist/ finds none of the passage; the one generator reads only the frontmatter) — skip-changeset applied by the dev, read back present after the size labeler ran. CI on 55c6d9fc: 30 distinct checks green at 01:29Z.

Verdict: ACCEPT. Governed (skills/**) ⇒ four-piece placed on PR #17259: needs-user-decision, the 终稿「维护者速读」, reviews requested from os-zhuang and hotlong; this seat does not flip, queue, arm or approve. Noted, not filed (the dev's, adopted): four other passages in the same file cite by line range and are accurate today — the same liability, left to whoever next edits them or a file-wide follow-up if the maintainer wants the class closed; the token ceiling (6806) could be lowered to the landed 5444 by a later PR that touches scripts/check-skills-token-ratchet.mjs.

Generated by Claude Code

Landed — PR #17259 merged by os-zhuang at 2026-09-10T03:19:57Z (merge commit a256f1896297, head 55c6d9fc), governed path (skills/**): draft + human merge, approving review by os-zhuang 02:56Z; this seat's ACCEPT verdict 5611296946 (01:30Z) bound to that head. Verified on origin/main 2026-09-10T03:30Z: skills/objectstack-ai/SKILL.md names collectToolUniverse / PLATFORM_TOOLS_BY_PACKAGE by symbol and carries no tool counts or line ranges. Residue cleared in this same act: pm:dispatched off, assignee off; domain:skills and the type stay (ownership, not state). Skills seat, session session_01MoTv7pn338AZ71owsp19gQ.

Generated by Claude Code

docs(skills): cite `PLATFORM_CAPABILITY_TOKENS` instead of restating …

Navigation Menu

Repository navigation

skills/objectstack-ai/SKILL.md restates the platform-tool registry's counts and line ranges instead of citing it — three numbers go stale the moment PR #16844 lands, and one citation is already stale #16853

Measured

Why it is a nit rather than a defect class, and why it is still worth a card

Suggested shape (⛔ not a prescription)

Provenance

⚠️ One thing has changed since filing, and it moves the card from predicted to live

ACCEPT — #16853 (skills seat, session `session_01MoTv7pn338AZ71owsp19gQ`, review taken 01:16–01:30Z at `claude-fable-5-1`; seat tier read by `get_session` this shift)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

skills/objectstack-ai/SKILL.md restates the platform-tool registry's counts and line ranges instead of citing it — three numbers go stale the moment PR #16844 lands, and one citation is already stale #16853

Description

Measured

Why it is a nit rather than a defect class, and why it is still worth a card

Suggested shape (⛔ not a prescription)

Provenance

Activity

huangyiirene commented on Sep 10, 2026

⚠️ One thing has changed since filing, and it moves the card from predicted to live

os-justin commented on Sep 10, 2026

os-justin commented on Sep 10, 2026

os-justin commented on Sep 10, 2026

ACCEPT — #16853 (skills seat, session session_01MoTv7pn338AZ71owsp19gQ, review taken 01:16–01:30Z at claude-fable-5-1; seat tier read by get_session this shift)

os-justin commented on Sep 10, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

ACCEPT — #16853 (skills seat, session `session_01MoTv7pn338AZ71owsp19gQ`, review taken 01:16–01:30Z at `claude-fable-5-1`; seat tier read by `get_session` this shift)