docs(skills): admit hand-authored reference files under references/ in the catalog anatomy

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

[os-litant]

Fixes#14655

What this changes

One line of skills/README.md, inside the "Skill anatomy" tree: the references/ entry
now carries a comment admitting hand-authored reference files.

-├── references/+├── references/ # may also hold hand-authored reference files linked from SKILL.md

The lane decision: option 2 (amend the anatomy, do not move the files)

The card offered two honest resolutions. The skills-lane seat chose option 2 in its
claim comment on #14655, and this PR implements exactly that.

The anatomy reserved references/ for the generated _index.md and assigned every
hand-authored per-topic file to rules/. Three published packages already keep
hand-authored anchors under references/:

package	file	linked from its own SKILL.md
objectstack-data	references/data-hooks.md	SKILL.md:50, :173, :522
objectstack-platform	references/plugin-hooks.md	SKILL.md:657, :790

Both are cited by path from sibling packages as well, so option 1 (move to rules/) is a
multi-package rename carrying pointer updates, a check:skill-identifier-liveness Leg-2
binding re-check (bindings are keyed by file path plus heading) and ceiling-row renames in
scripts/check-skills-token-ratchet.mjs — for zero reader value, since the reader reaches
the same text either way. Amending the sentence that describes the catalog is the cheaper
and truer half of the pair.

Why it is one block, and one line inside it. The permission is stated where the layout
is defined, so a reader authoring a new skill sees it at the moment the question arises,
and the requirement travels with the permission: a hand-authored reference file must be
linked from SKILL.md. Everything else in the tree is byte-identical — SKILL.md,
the two _index.md comment lines (still "generated pointers", still "do not hand-edit",
still the pnpm --filter @objectstack/spec gen:skill-refs pointer), rules/ with its
per-topic role, contracts/ and evals/.

One spelling change in the two blocks below, declared. The tree's first line is a
placeholder for the skill directory, written in the file with angle brackets. GitHub's
body sanitizer deletes angle-bracket fragments from a PR body — it did exactly that on
this body's first write, leaving skills// — so the placeholder is spelled
SKILL-NAME here. That line is untouched by this PR either way; the changed line
contains no brackets and is quoted verbatim above.

Before

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

After

skills/SKILL-NAME/
├── SKILL.md # frontmatter + prose guide
├── references/ # may also hold hand-authored reference files linked from SKILL.md
│ └── _index.md # generated pointers into @objectstack/spec sources
│ # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
├── rules/ # (optional) detailed per-topic rule files linked from SKILL.md
├── contracts/ # (optional) generated machine-readable contracts (e.g. react-blocks)
└── evals/ # skill eval fixtures — used by maintainers to score the skill,
# inert (but harmless) in consumer installs

The illustrative examples the card sketched for the new comment (event lists, payload
tables, hook references) were left out deliberately: they are flavour, not contract, and
the block is under a shrink-or-neutral budget. The contract — optional, hand-authored,
linked from SKILL.md — is stated in full.

Token delta

skills/README.md, measured as ceil(utf8_bytes / 4):

	utf8 bytes	tokens
before (df657d9df)	7941	1986
after (3b9bf9435)	8018	2005
delta	+77	+19

Net positive, and stated as such rather than bought back by degrading a neighbouring
sentence. The paid-for alternative was folding the two _index.md comment lines into one,
which would have cost the reader the runnable pnpm --filter @objectstack/spec gen:skill-refs command on the catalog's front page — a worse trade than +19 tokens.
skills/README.md is outside the token-ratchet population
(scripts/check-skills-token-ratchet.mjs:133, self-test at :790), so no ceiling row
exists for it and none moved; the gate run below confirms that.

Premise correction (premise_false)

The card's closing sentence — "Either way the generator-owned skills/README.md is
regenerated, never hand-edited" — is false for this block, and the seat corrected it
at dispatch. Measured here at 3b9bf9435:

• packages/spec/scripts/build-skill-docs.ts:12-13 states the contract in its own header:
  derived listings are "rewritten between BEGIN/END GENERATED: skills markers; prose
  outside the markers is preserved".
• The generated Index table ends at the END marker on skills/README.md:44. The "Skill
  anatomy" heading is at :50 and the tree at :52-62 — after it, in preserved prose.
• So there is no generator source to amend: the block is hand-authored, and this PR edits
  it by hand. That the generated region was not touched is proved by
  check:skill-docs staying green, and by the reverse verification below showing that the
  same gate does go red for an edit inside the region.

Second, smaller correction: the seat's claim comment located the block at :44-58. At
this branch point it is the END marker that sits at :44; the anatomy heading is :50
and the tree :52-62. No effect on the decision.

Changeset

None, and the skip-changeset label is applied. This diff releases nothing from any
package — scripts/check-empty-changeset.mjs:359-361 enumerates that case by name:

* It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

The diff is exactly one file, skills/README.md, which is inside the enumerated skills/.

Gates

Head 3b9bf9435. The list is the union re-derived after the last edit with
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
(16 families, all matched via skills/README.md), plus the three the dispatch named
directly. Exit codes captured by redirect before any pipe; every run went through
scripts/pm/os-verify-lock.sh.

gate	exit	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, …
node scripts/check-cross-package-test-inputs.mjs	0	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-shard-attestation.mjs	0	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED — PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named. The gate's own text: "the local reading for this gate is NOT MEASURED. ⛔ It is not a red, and there is nothing here to fix."
pnpm --filter @objectstack/lint run check:doc-formula-expressions	0	✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 426 files / 1365 TS blocks judged clean by @objectstack/formula. (first run exited 3 on unbuilt prerequisites; measured after building @objectstack/formula then @objectstack/lint)
pnpm --filter @objectstack/spec run check:skill-docs	0	✓ skills/README.md · ✓ content/docs/ai/skills-reference.mdx · ✅ Skill docs in sync
pnpm check:agent-test-spelling	0	✓ check-agent-test-spelling: 0 violations — 430 file(s) · 5698 bare -- token(s) · …
pnpm check:corpus-claim-drift	0	check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.
pnpm check:cross-package-test-inputs	0	All 117 self-test cases passed. · OK: 25 package(s) read outside themselves, all declared…
pnpm check:doc-authoring	0	✓ doc authoring guard: 46 published skill files clean — no internal issue-id references.
pnpm check:merge-driver	0	✓ check-regen-pending self-test passed.
pnpm check:pm-governed-merges	0	✓ check-governed-merges --self-test: 243 assertions …
pnpm check:role-word	0	check-role-word: OK, no new occurrences of the reserved word.
pnpm check:skill-compatibility	0	✓ check-skill-compatibility-version: 11 SKILL.md file(s) reconciled against 79 workspace packages
pnpm check:skill-frame-sync	0	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:skill-identifier-liveness	0	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).
node scripts/check-skills-token-ratchet.mjs	0	✓ check-skills-token-ratchet: 36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
node scripts/check-skills-token-ratchet.mjs --self-test	0	✓ check-skills-token-ratchet self-test: 64 cases pass.
node scripts/check-nul-bytes.mjs	0	check-nul-bytes: OK (scanned 8053 text file(s) … no raw ASCII control bytes).

18 measured green, 1 recorded NOT MEASURED (CI-only input), 0 red.

Reverse verification of check:skill-docs

The gate that proves the generated region was left alone is only worth quoting if it can
fail. Run from the committed state, under the verify lock, by a script with a trap on
EXIT, INT and TERM that re-checks the file out, and absolute paths throughout. No rebuild
leg is owed: the gate is tsx scripts/build-skill-docs.ts --check, which reads the
markdown sources from disk — no compiled artifact sits between the mutation and the
measurement.

leg	on-disk proof	gate exit	verdict line
mutated (one character inserted inside the generated region: the Formula row's expression domain cell)	anchor count before 1 / after 0, injected count before 0 / after 1; blob 2940ce52… → e023126d…	1	✗ skills/README.md is out of date — run pnpm --filter @objectstack/spec gen:skill-docs
restored (git checkout HEAD -- skills/README.md)	blob back to 2940ce52… = the HEAD blob; git diff HEAD 0 bytes; git status --porcelain 0 lines	0	✅ Skill docs in sync

The predicted direction was red naming skills/README.md, and that is what it did.

ESLint

Narrowed to the changed file, and the narrowing is a measurement rather than a skip:

1. Population, read from eslint.config.mjs itself: the base block at :971 is
   files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'], and every later block (:1015,
   :1054, :1103, :1172, :1212, :1238) narrows within those extensions. No block
   admits .md.
2. Count, from --format json: one entry for skills/README.md, 0 errors, 1 warning,
   and the warning is File ignored because no matching configuration was supplied.
   ESLint exited 0.
3. Invariance for untouched files: the config declares no parserOptions.project and
   no projectService anywhere (its own comment at :328 says so — "no
   parserOptions.project, no typed @typescript-eslint rules"), so no verdict on any
   file is a function of another file's contents. A markdown-only diff cannot move a lint
   result anywhere in the tree.

Follow-up, not this PR

• The card's "require the link" half is stated here as text, not enforced by a gate.
  Adding one was explicitly out of scope. A gate is plausible — the shape would be "every
  non-_index.md file under a published skills/*/references/ is referenced by that
  skill's SKILL.md" — but it needs the lane's decision, and there is a third file to
  triage first (below).
• skills/objectstack-ui/references/react-blocks.md is a generated file (its own
  header: "GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not
  edit") living under references/ beside _index.md, and grep finds no link to it from
  objectstack-ui/SKILL.md. It is neither the generated _index.md the anatomy names nor
  the hand-authored, linked material this PR admits, so the amended sentence does not cover
  it either. Reported to the lane seat for dedup against Seam (spec lane, ruled): gen:react-blocks stops emitting skills/objectstack-ui/contracts/react-blocks.contract.json — the markdown rendering becomes the single AI-facing output (#14296 item 3 = A) #14559 rather than filed from
  here.

Merge

Draft, and it stays draft — governed skills/** surface (Prime Directive #14): the
maintainer's human merge is the review record. No reviewers requested, no auto-merge, no
ready flip.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1