Declare the populations four under-matching gates really read, and refuse a dead declaration

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);

.github/workflows/lint.yml

@@ -688,6 +688,24 @@ jobs:
  - name: ROOT_DIR_WATCH_HINTS declarations are literals
  run: pnpm check:watch-hint-literal
 
+ # The other half of the same failure (#13519). The step above holds that a
+ # declaration is still READABLE BY A TEXT SCANNER; this one holds that
+ # what it reads still names something. A family whose declared literals
+ # all reach zero tracked files prints as an ORDINARY SILENCE — byte for
+ # byte the output of a gate that declared nothing — so the derivation and
+ # the gate disagree about whether a population was declared and neither
+ # says so. Measured on the tree this landed against: two families, one of
+ # them a gate that sweeps every workflow file and appeared on no card that
+ # edited one. The rule is per-FAMILY, not per-literal: a gate may spell a
+ # slug or a sentinel path beside a live declaration, and only a whole
+ # declaration that reaches nothing is refused. No allowlist and no gate
+ # names — the stronger rule ("a gate that enumerates a directory must
+ # declare one") was implemented, measured at 86 findings over 114
+ # enumerating gate files, and refused as an allowlist with a verdict
+ # attached. Reads the derivation once over the tracked corpus; ~5s.
+ - name: A declared gate population reaches the tree
+ run: pnpm check:declared-population-live
+
  # PM bare-root worklist self-test (#10840). The step above proves the
  # dispatch derivation still WORKS; this one proves the recorded triage of
  # the gates that derivation structurally cannot see is still true of the

package.json

@@ -70,6 +70,7 @@
  "check:pm-label-desc-cap": "node scripts/pm/check-label-desc-cap.mjs --self-test && node scripts/pm/check-label-desc-cap.mjs",
  "check:pm-dispatch-gates": "node scripts/pm/check-dispatch-gates.mjs",
  "check:watch-hint-literal": "node scripts/check-watch-hint-literal.mjs --self-test && node scripts/check-watch-hint-literal.mjs",
+ "check:declared-population-live": "node scripts/check-declared-population-live.mjs --self-test && node scripts/check-declared-population-live.mjs",
  "check:pm-half-states": "node scripts/pm/check-half-states.mjs --self-test",
  "check:pm-clause2-carriers": "node scripts/pm/check-clause2-carriers.mjs --self-test",
  "check:pm-governed-merges": "node scripts/pm/check-governed-merges.mjs --self-test",

packages/spec/scripts/build-skill-docs.ts

@@ -26,9 +26,73 @@ import path from 'path';
 
 const REPO_ROOT = path.resolve(__dirname, '../../..');
 const SKILLS_DIR = path.resolve(REPO_ROOT, 'skills');
+/** The file a child of the skills root must CARRY to be a skill (`:main` admits on it). */
+const ENTRYPOINT_FILE = 'SKILL.md';
 const README = path.resolve(SKILLS_DIR, 'README.md');
 const GUIDE = path.resolve(REPO_ROOT, 'content/docs/ai/skills-reference.mdx');
 
+/**
+ * The population this script READS, declared for `scripts/pm/dispatch-gates.mjs`
+ * — spelled as a LITERAL array because the hint extractor reads source TEXT (a
+ * declaration computed from `SKILLS_DIR` would build no hint at all;
+ * `scripts/check-watch-hint-literal.mjs` holds that spelling for every declarer
+ * in the tree).
+ *
+ * ## What was declared before, and why it under-matched
+ *
+ * The only path literal this module body spelled was the GUIDE path,
+ * `content/docs/ai/skills-reference.mdx` — an OUTPUT. So `check:skill-docs`
+ * declared its generated artifact and not one of its inputs: a card editing a
+ * skill entrypoint — the file whose frontmatter is the entire catalog — was
+ * never told that this gate reads it, and `--check` reds in CI on drift the
+ * derivation could have predicted.
+ *
+ * The inputs were not forgotten, they were unspellable AS ONE HINT: `SKILLS_DIR`
+ * is built with `path.resolve(REPO_ROOT, 'skills')`, and a single-segment
+ * literal is refused by the extractor as too generic to be a path population.
+ *
+ * ## Why NOT the subtree spelling, which is the idiom's usual escape
+ *
+ * `scripts/pm/bare-root-worklist.mjs` carries the measured triage for exactly
+ * this root and refuses the wholesale hint: this script's population is 12 of
+ * the 50 files tracked under it (24%), so `skills/**` would name this gate for
+ * 38 files it never opens. That is the REFUSE-WIDE trade, and the worklist
+ * prices a false wholesale hint as the costlier error.
+ *
+ * What the recorded refusal turned on is that no SINGLE spelling reaches both
+ * halves: `:221` readdirs the root and admits a child only if it carries a
+ * SKILL.md, while the twelfth file is the root README this script WRITES, which
+ * sits outside every skill directory. Two literals reach both, and reach
+ * nothing else — 12 of 12, precise AND complete — which is the declaration
+ * below and why the row's verdict is withdrawn rather than the declaration.
+ */
+const DECLARED_WATCH_HINTS = ['skills/*/SKILL.md', 'skills/README.md'];
+
+/**
+ * The declaration above, held against the constants this script really reads
+ * from. A hand-written path that agreed with the read only on the day it was
+ * typed is the drift this idiom replaces, so the check derives what it compares
+ * against from `SKILLS_DIR` and `README` — move either and this throws here, in
+ * this file, instead of going quiet in a dispatch brief.
+ */
+function assertWatchHintsDeclareTheReadSurface(): void {
+ const rel = (abs: string) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+ const expected = [`${rel(SKILLS_DIR)}/*/${ENTRYPOINT_FILE}`, rel(README)];
+ if (DECLARED_WATCH_HINTS.join('|') !== expected.join('|')) {
+ throw new Error(
+ `build-skill-docs: the declared watch-hint population ${JSON.stringify(DECLARED_WATCH_HINTS)} no longer ` +
+ `names what this script reads (${JSON.stringify(expected)}) — update the declaration, as a LITERAL array.`,
+ );
+ }
+ // …and it stays NARROW. A hint that reached the bare root would be the
+ // wholesale claim the worklist refused, arriving through a reword.
+ if (DECLARED_WATCH_HINTS.some((h) => h.endsWith('/**'))) {
+ throw new Error(
+ `build-skill-docs: the declaration must stay narrower than the root: ${JSON.stringify(DECLARED_WATCH_HINTS)}`,
+ );
+ }
+}
+
 // Marker comments delimit the generated region. MDX does not support HTML
 // comments (`<!-- -->`) — it needs `{/* */}` — so the syntax is per file type.
 type CommentStyle = 'html' | 'mdx';
@@ -78,7 +142,7 @@ interface Skill {
 }
 
 function parseFrontmatter(name: string, label: string): Skill {
- const file = path.resolve(SKILLS_DIR, name, 'SKILL.md');
+ const file = path.resolve(SKILLS_DIR, name, ENTRYPOINT_FILE);
  const raw = fs.readFileSync(file, 'utf-8');
  const parts = raw.split(/^---\s*$/m);
  if (parts.length < 3) throw new Error(`${name}: no YAML frontmatter`);
@@ -216,10 +280,12 @@ function spliceBlock(file: string, block: string, style: CommentStyle): string {
 function main() {
  const check = process.argv.includes('--check');
 
+ assertWatchHintsDeclareTheReadSurface();
+
  // Catalog ⇄ DISPLAY must be in lockstep.
  const onDisk = fs
  .readdirSync(SKILLS_DIR)
- .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, 'SKILL.md')));
+ .filter((d) => d.startsWith('objectstack-') && fs.existsSync(path.resolve(SKILLS_DIR, d, ENTRYPOINT_FILE)));
  const configured = new Set(DISPLAY.map((d) => d.name));
  const missing = onDisk.filter((d) => !configured.has(d));
  const extra = DISPLAY.filter((d) => !onDisk.includes(d.name)).map((d) => d.name);