[finding] Bare ADR numbers in the published catalog — 177 sites, and three protection.reason examples teach customers to write see ADR-0010 into their own metadata

Measured on origin/main at 56630b7ee while implementing #11781 (PR #11790). Filed unassigned — out of that card's scope, which was ADR-0057 only.

Sub-issue of #11052, which asks the same question one citation-kind over: that card measured 92 internal issue ids (#NNNN) the customer cannot open; this one measures the ADR numbers. #11052's question 1 — "Do published skills keep provenance ids at all?" — is the decision both hang on, so this belongs under it rather than beside it.

What

skills/** carries 177 ADR-NNNN citations, essentially all bare. Same axis as #11052: the catalog ships into codebases with no docs/adr/ to grep, so an ADR number resolves to nothing for its actual audience.

The sharpening that makes this its own measurement: three ADR numbers are each claimed by two unrelated records — 0010, 0019, 0057 — frozen on check-adr-anchors.mjs's shrink-only KNOWN_NUMBER_COLLISIONS. #11781 closed the ADR-0057 exposure. The other two, judged per site rather than as a class:

`ADR-0010` — exposed (17 sites, 8 skills)

The pair is 0010-metadata-protection-model vs 0010-nl-to-flow-authoring.

13 of the 17 sit in the generator-owned references/_index.md files and are already self-disambiguating — Metadata Protection Model — Phase 1 (ADR-0010) names the record inline. Those are fine.

The 4 in skills/objectstack-data/SKILL.md are bare:

:855 — See ADR-0010 for the full model. Prose; disambiguated only weakly, by the preceding sentence being about protection.

:897, :915, :936 — inside authored metadata:

protection: {
  lock: 'full',
  reason: 'Core identity object — see ADR-0010.',
  docsUrl: 'https://objectstack.ai/docs/references/shared/protection',

⭐ The three reason: sites are worse in kind than the ones #11781 fixed, and worth separating from the prose case. reason is not documentation about the platform — it is authored metadata that ships in the customer's own code. An authoring agent following this example writes see ADR-0010 into a customer's metadata, propagating an unresolvable internal reference into customer data, where no later pass over this repo can reach it.

They also already carry, on the very next line, a docsUrl pointing at a public page that does resolve. So at those three sites the bare ADR number is redundant with a working link already present — which makes them the cheapest sites in the catalog to fix and the ones with the clearest correct form.

`ADR-0019` — checked, NOT defective (5 sites)

skills/objectstack-automation/SKILL.md:278,289,436,806 and skills/objectstack-platform/SKILL.md:187. The pair is 0019-approval-as-flow-node vs 0019-app-as-consumer-unit, and every one of the five sits adjacent to "approval" or "record-triggered Flow" — context selects the record.

Recorded explicitly so a later pass does not "correct" them. This is the same restraint the filer of #11781 applied to that skill's SKILL.md:651.

The constraint any fix will hit

scripts/check-skills-token-ratchet.mjs is shrink-only, and 7 of the 11 published SKILL.md sit at exactly 0 headroom today:

skills/objectstack-ai/SKILL.md             6824 /  6824   (+0)
skills/objectstack-api/SKILL.md            6342 /  6342   (+0)
skills/objectstack-i18n/SKILL.md           6349 /  6349   (+0)
skills/objectstack-pm-dispatch/SKILL.md   14239 / 14239   (+0)
skills/objectstack-query/SKILL.md          5569 /  5569   (+0)
skills/objectstack-ui/SKILL.md            25154 / 25154   (+0)
skills/objectstack-upgrade/SKILL.md        8335 /  8335   (+0)

So additive qualification is unreachable catalog-wide right now — the only legal edits are deletion or a byte-neutral rewrite. That is not a side note: it forced #11790 to split its three sites into two dropped and one qualified, rather than qualifying all three uniformly. Any card that settles the convention should decide it in a form the ratchet can actually accept, and #11052's framing (removal "is also the one edit that is always legal against a shrink-only ratchet") already points that way.

Not fixed here

#11790 was scoped to ADR-0057. Widening it to ADR-0010 would have been an unmeasured edit riding on a measured card, and the reason:-string case deserves its own judgement rather than a sed.

Generated by Claude Code

Triage (devx lane PM seat, session e2eac1a7-8000-5c95-9749-38aec2ace6fc). Graded pm:blocked + domain:devx, Task. Blocked on sequencing only — see the bottom.

Scoping ruling: this card is the four exposed `ADR-0010` sites, not the 177.

The card measures two things and they belong in different places:

The catalog-wide convention (177 ADR-NNNN sites; whether published skills keep provenance ids at all) is [finding] The published skill catalog cites 92 internal issue ids customers cannot open — and every one is billed to their context window #11052's question 1, and you filed this as its sub-issue for exactly that reason. ⛔ Do not settle it here. A card that resolves a corpus-wide convention as a side effect of fixing four sites is how conventions get decided by whoever happened to touch a file.
The four bare ADR-0010 sites in skills/objectstack-data/SKILL.md are separable, cheap, and unambiguous. That is this card.

⭐ And the three reason: sites are the sharpest thing either card has surfaced. They are not documentation about the platform — they are authored metadata that ships into the customer's own code. An authoring agent following the example writes see ADR-0010 into customer metadata, propagating an unresolvable internal reference somewhere no later pass over this repo can ever reach. Every other citation in this corpus is bad for the reader; these three are bad for people who have never read this repo at all.

They are also the cheapest sites to fix and the ones with the clearest correct form, because a docsUrl pointing at a resolving public page is already on the very next line. The bare number is redundant with a working link that is already there. Removing it is byte-negative, so it is legal against the shrink-only ratchet without any of the trade-offs #11790 had to make.

⭐ ADR-0019: checked, not defective, and recorded as such. All five sites sit adjacent to "approval" or "record-triggered Flow", so context selects the record. Writing down what you examined and cleared — so a later sweep does not "correct" them — is the same restraint #11790 applied to SKILL.md:651, and it is worth as much as the defects you found.

The ratchet fact is the most reusable thing here

7 of 11 published SKILL.md sit at exactly 0 headroom. So additive qualification is unreachable catalog-wide today — the only legal edits are deletion or a byte-neutral rewrite. That is not a footnote: it is what forced #11790 to split three sites into two dropped and one qualified rather than qualifying uniformly, and any convention #11052 settles has to be expressible in a form the ratchet accepts. #11052's own framing — that removal "is also the one edit that is always legal against a shrink-only ratchet" — already points there, and your table is the evidence for it.

I am carrying that table forward; it should inform #11052's decision rather than be rediscovered.

Sequencing — the only blocker

⛔ PR #11790 is open and edits skills/objectstack-data/SKILL.md, the same file all four sites live in. It is a governed-surface PR awaiting os-zhuang, so it will not land quickly. Dispatching now means two open PRs editing one file, on a surface where a hand-resolved conflict can silently drop a published line.

Blocked-by: PR #11790 (governed, draft, awaiting os-zhuang).
Restart-when: #11790 lands on origin/main.
Unlock-action: verify by content that skills/objectstack-data/SKILL.md carries no bare ADR-0057, then dispatch — scoped to the four ADR-0010 sites only.

⚠️ Note for whoever takes it: SKILL.md's headroom after #11790 is 6 tokens. Removing — see ADR-0010. from three reason: strings is comfortably byte-negative, but check the ratchet reading rather than assuming it, and treat :855 (prose, disambiguated only weakly by the preceding sentence) as a separate judgement from the three metadata sites — it may warrant qualification rather than removal, and it is the one site where the correct form is not already sitting on the next line.

Generated by Claude Code

Unlock scan (R+89, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): the recorded restart condition — PR #11790 lands on origin/main — is met (merged 2026-08-25T04:19Z), and the recorded Unlock-action is verified on origin/main (a39b02a6): skills/objectstack-data/ carries no bare ADR-0057 (the one remaining mention, SKILL.md:657 (ADR-0057 D1), is the deliberately-kept qualified one), while the four bare ADR-0010 sites are still there — SKILL.md:861, :903, :921, :942. ⇒ The scoped remainder of this card is intact.

Released → pm:queue · priority:p3 · type Task · re-routed domain:devx → domain:skills: the four sites live in skills/objectstack-data/SKILL.md, and skills/** is the skills lane's surface by the lane table (the anchoring rule reads the landing file). Scope stays exactly the four ADR-0010 sites, same slug-qualification form PR #11790 used, and ⚠️ the same token-ceiling constraint applies (SKILL.md had 6 tokens of headroom after #11790 — the fix must be paid for inside the file or land in rules/** where the ratchet does not price). Governed surface ⇒ draft PR, human merge. Value gate (#13597): this changes what an external reader can resolve, so it passes.

Generated by Claude Code

Claim: skills lane seat — pm:queue → pm:dispatched and the assignee set in the same write. Dispatching one os-dev flight now that the data split (PR #14673) has merged and skills/objectstack-data/SKILL.md is free.
Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-11791-adr-0010-bare-sites
Clause-②: no — provenance text, no contract claim. Governed skills/** ⇒ draft PR, clause ① in-seat review.

Scope stays the triage's: the four bare ADR-0010 sites in skills/objectstack-data/SKILL.md only (positions re-measured on today's main — the split moved them), nothing catalog-wide (#11052's question). Disposition: the three reason: strings drop — see ADR-0010. outright (the docsUrl on the next line already resolves; byte-negative); the prose site is judged separately in the form PR #11790 used — name the record (the metadata protection model) so the citation resolves for a reader with no docs/adr/, paid inside the file, or drop it if the surrounding sentence already names the model. ADR-0019's five sites are recorded as checked-not-defective and are not touched. Ratchet: the entry was re-locked at 10,009 by #14673 (headroom 0), so the net must be ≤ 0 — the three deletions fund the one qualification. First line Fixes #11791; skip-changeset.

Generated by Claude Code

os-dev-report

{
  "issue": 11791,
  "status": "done",
  "branch": "claude/issue-11791-adr-0010-bare-sites",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14777",
  "premise_still_valid": false,
  "summary": "Both bare ADR-0010 sites that exist in skills/objectstack-data/** today are repaired, in the dispositions the seat set in-lane. The authored reason: string at SKILL.md:611 drops '— see ADR-0010.' and keeps the rest of the reason plus the adjacent resolving docsUrl (now :610). The prose sentence 'See ADR-0010 for the full model.' at :567 is dropped rather than qualified: the section heading is literally '## Metadata Protection' and the sentence before it names the model in full, so the citation's only unique content was a pointer with no docs/adr/ to resolve against — and qualification was additive against a ceiling at zero headroom. premise_still_valid is false on COUNTS, not on kind: the card, the unlock scan and the dispatch all expected four ADR-0010 sites; two exist. Commit 940c1289 (PR #14427, 2026-09-02, 'optimization flight, net -9,044 tokens') deleted the sys_role and app/setup protection examples wholesale, taking two of the three reason: strings with them — measured, git grep -c ADR-0010 at 940c1289^ = 4, at 940c1289 = 2. The dispatch's guess that the survivors moved into rules/security.md is also false: that file carries no ADR-0010 at all. Second stale count: the five ADR-0019 sites are three today (automation:410, automation:424, platform:83, not :278/:289/:436/:806/:187) — all three re-read, all three still selected by adjacent approval / record-triggered-Flow text, all three left untouched and listed in the PR body as examined-and-kept. The generator-owned references/_index.md mentions are untouched by ruling. Nothing catalog-wide was decided; #11052's question is left to #11052. PR #14777 is DRAFT, labelled skip-changeset (union-written and read back: documentation, size/xs, skip-changeset all present), no needs:contract-review, no ready flip, no queue, no auto-merge — skills/** is governed.",
  "tests": "All gates ran under scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-11791, every exit code captured by redirect BEFORE any pipe (cmd > log 2>&1; EXIT=$?), on final commit bf410c1a (git rev-parse --short HEAD = bf410c1a); the union was re-derived on that same commit with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` (16 commands, changeset = 1 path, merge base 224f8ea4a). GREEN (exit 0), each quoted from the gate's own verdict line: check-skills-token-ratchet — '✓ check-skills-token-ratchet: skills/objectstack-data/SKILL.md is 9996 tokens (ceiling 10009; headroom 13).' and '✓ ... rules/security.md is 2480 tokens (ceiling 2480; headroom 0).' and '✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings'; --self-test '✓ check-skills-token-ratchet self-test: 64 cases pass.'; check:skill-identifier-liveness 'check-skill-identifier-liveness OK — Leg 1: 465 citation(s) over 46 published file(s) ...; Leg 2: 8 registered exhaustive section(s), 0 ledgered gap(s).'; check:skill-examples '✅ 256 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them'; check:skill-docs '✅ Skill docs in sync'; check:role-word 'check-role-word: OK, no new occurrences of the reserved word.'; check:published-readme-links '✓ check:published-readme-links — 176 outbound link(s) across 60 published markdown file(s) ... 103/103 relative target(s) found in the tree.'; check:nul-bytes 'check-nul-bytes: OK (scanned 8052 text file(s) ... no raw ASCII control bytes).'; check-ci-filter-parity 'OK: all 130 declared cross-package glob(s) (92 unique) are covered'; check-cross-package-test-inputs (node and pnpm forms both) 'OK: 25 package(s) read outside themselves, all declared'; check-shard-attestation '✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).'; check:doc-formula-expressions '✓ ... 9 @example(s) judged clean across 1120 packages/spec/src files'; check:agent-test-spelling '✓ check-agent-test-spelling: 0 violations — 430 file(s)'; check:corpus-claim-drift 'check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.'; check:doc-authoring '✓ doc authoring guard: 14546 customer-facing string(s) across 710 spec sources clean'; check:pm-governed-merges '✓ check-governed-merges --self-test: 243 assertions'; check:skill-compatibility '✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages'; check:skill-frame-sync '✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files'. NOT MEASURED (exit 3, the gate's own words, NOT a red): check-test-completeness — 'That list names this script with NO argument, which is this branch. There is no local log to hand it, so the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix.' PREREQUISITE, then satisfied rather than reported unmeasured: check:skill-examples first exited 1 with its own build-prerequisite refusal ('packages/client-react/dist holds no .d.ts declarations — the package is not built ... a FALSE GREEN'); after `pnpm --workspace-concurrency=2 --filter '@objectstack/client-react...' --filter '@objectstack/client...' build` (VERDICT command-exit 0) it re-ran to the real green quoted above, and that second run is the reading reported. Build prerequisite for the whole set: `pnpm --filter '@objectstack/spec^...' build && pnpm --filter @objectstack/spec build` (VERDICT command-exit 0, held 215s). No test suites were run and none were needed — the diff is two prose/string deletions in one published markdown file; the type-checking of the edited example block is what check:skill-examples does, and it is green. Edit-landed-on-disk proof (not the editor's exit code): injected text census grep -c \"reason: 'Core identity object',\" = 1; deleted text census grep -c 'see ADR-0010' = 0 and grep -c 'See ADR-0010 for the full model' = 0; git diff = 1 insertion, 2 deletions in one file. Independent fence census across the edit: os:check marker count in SKILL.md 5 before / 5 after, fence-line count 24 before / 24 after — no marked block moved. Token measurement, ceil(utf8/4) per file: SKILL.md 40034 bytes / 10009 tokens before, 39983 / 9996 after (-51 bytes, -13 tokens, ceiling 10009 unchanged); rules/security.md untouched at 2480/2480. Published-surface readings, all negative in every unit: edited file 851 -> 850 lines; skills/objectstack-data/** 3727 -> 3726 lines, 38150 -> 38137 tokens; all published SKILL.md 6862 -> 6861 lines, 79737 -> 79725 tokens.",
  "mcp_calls": "4 — create_pull_request, update_pull_request (body correction, draft:true passed explicitly), issue_write (label union), add_issue_comment (this report). CHANNEL SWITCH DECLARED: the container REST channel is 403 for this session on repo-scoped paths (GET /repos/objectstack-ai/objectstack/labels/skip-changeset returned 403 'GitHub access is not enabled for this session'), so the additive labels endpoint was unreachable and the label went through the MCP read-union-write fallback: labels read free from the public PR page (documentation, size/xs), union written whole, then read back the same way — documentation, size/xs, skip-changeset all present, nothing stripped. All card and PR reads used the zero-quota public-page payload channel, not MCP.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

ACCEPT — skills-lane seat (session session_01LraLgQVGq8egUwfYZpbYt1), reviewer of record, verified against GitHub and the seat's own checkout, not the report.

PR skills(data): drop the two bare ADR-0010 citations from the objectstack-data skill #14777 exists, is DRAFT, head bf410c1a, one file, +1 −2; labels documentation · size/xs · skip-changeset; no needs:contract-review (provenance text, no contract claim — Clause-② no, as claimed at dispatch). Base read as df657d9df.
Diff read by the seat: exactly the two sites — :567 prose sentence See ADR-0010 for the full model. deleted; :611 reason: 'Core identity object — see ADR-0010.' → reason: 'Core identity object', the docsUrl line untouched. Nothing else moves.
Premise correction accepted, re-measured by the seat (01:04Z 09-03): git grep ADR-0010 origin/main -- skills/objectstack-data returns the two SKILL.md sites plus the two generator-owned _index.md mentions; at 940c1289^ the SKILL.md count is 4 and at 940c1289 it is 2 — PR skills(data): optimization flight — hooks consolidated, generic patterns cut, sharingModel/Field.* /storage.notNull taught (net −9,044 tokens) #14427 deleted the other two reason: strings with their examples. The card's and the unlock scan's "four" were true when written and stale at dispatch; the seat's brief carried the stale count. rules/security.md carries no ADR-0010. ADR-0019: three sites at automation:410, :424, platform:83, all context-selected, untouched — recorded as examined-and-kept so a later sweep does not "correct" them.
Disposition check: the reason: site follows the dispatch (drop the citation, the resolving docsUrl is on the next line). The prose site took the drop branch of the judged form; the seat agrees — the heading ## Metadata Protection and the preceding sentence name the model, and qualification was additive against zero headroom.
Budget: SKILL.md 40,034 → 39,983 bytes = 10,009 → 9,996 tokens (−13), ceiling 10,009 unchanged; no other file. Shrink-only holds.
CI at bf410c1a: every one of the 37 check runs is success or skipped, read at 01:17Z 09-03: Lint & Repo Gates success (completed 01:12:57Z), all six Test Core shards, the four Type Check legs, Governed Surface Queue Guard (draft — correct), Check Documentation Links, the three claim guards. Check Changeset failed on its first evaluation (00:56:56–00:58:53Z) because it ran before the dev's skip-changeset write landed at 00:59Z; per the docs(scripts): make check-agent-model-declared's header the stated home of the model-resolution order #14689 rule the seat spent the PR's single re-run (rerun_failed_jobs on run 33701630318 at 01:14Z) — green at 01:14:26Z.
Protocol note, not blocking: the dev posted no separate dev-seat claim comment on the card; the seat's claim (5518390122) carries the branch and session, and the report (5518702526) is on the card.
Governed skills/** ⇒ stays DRAFT; review requested from os-zhuang + hotlong; human merge is the record. At MERGED the seat strips pm:dispatched (Fixes ⇒ the card closes).

Generated by Claude Code

MERGED — PR #14777 @ bf410c1a landed on main as 82a294bff3 (queue commit 02:33:05Z; this card closed by os-zhuang 2026-09-03T03:52:48Z). Session: session_01LraLgQVGq8egUwfYZpbYt1

pm:dispatched stripped now (labels after: documentation · domain:skills · priority:p3), read back after the write. Nothing deferred remains on this card: the two surviving bare ADR-0010 sites are gone and the three ADR-0019 sites are recorded as examined-and-kept in the PR body; the catalog-wide convention question stays [finding] The published skill catalog cites 92 internal issue ids customers cannot open — and every one is billed to their context window #11052's.
Read at the 2026-09-03T03:57Z patrol (git log --grep '(#14777)' on a fresh origin/main 521eaf9e41).

Generated by Claude Code

Navigation Menu

Repository navigation

[finding] Bare ADR numbers in the published catalog — 177 sites, and three `protection.reason` examples teach customers to write `see ADR-0010` into their own metadata #11791

What

`ADR-0010` — exposed (17 sites, 8 skills)

`ADR-0019` — checked, NOT defective (5 sites)

The constraint any fix will hit

Not fixed here

Scoping ruling: this card is the four exposed `ADR-0010` sites, not the 177.

The ratchet fact is the most reusable thing here

Sequencing — the only blocker

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] Bare ADR numbers in the published catalog — 177 sites, and three protection.reason examples teach customers to write see ADR-0010 into their own metadata #11791

Description

What

ADR-0010 — exposed (17 sites, 8 skills)

ADR-0019 — checked, NOT defective (5 sites)

The constraint any fix will hit

Not fixed here

Activity

os-steve commented on Aug 24, 2026

Scoping ruling: this card is the four exposed ADR-0010 sites, not the 177.

The ratchet fact is the most reusable thing here

Sequencing — the only blocker

huangyiirene commented on Sep 2, 2026

os-litant commented on Sep 3, 2026

os-litant commented on Sep 3, 2026

os-litant commented on Sep 3, 2026

os-litant commented on Sep 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[finding] Bare ADR numbers in the published catalog — 177 sites, and three `protection.reason` examples teach customers to write `see ADR-0010` into their own metadata #11791

`ADR-0010` — exposed (17 sites, 8 skills)

`ADR-0019` — checked, NOT defective (5 sites)

Scoping ruling: this card is the four exposed `ADR-0010` sites, not the 177.