@opengsd/gsd-core 1.13.0 → 1.15.0

package/scripts/lint-allowed-tools-parity.cjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-allowed-tools-parity.cjs — catch `allowed-tools` frontmatter that
+ * declares `Bash` but omits `Grep` (#4394, follow-up to #3085).
+ *
+ * ## Why
+ *
+ * `gen-plugin-skills.cjs --check` already guarantees `skills/*` /SKILL.md`
+ * matches byte-for-byte what `commands/gsd/*.md` generates, so the two trees
+ * cannot silently diverge FROM EACH OTHER. Nothing guarded the shape #3085
+ * actually found: a command shipping `Bash` without `Grep` purely by
+ * omission, identical in both trees and therefore invisible to a parity
+ * check that only compares them to each other.
+ *
+ * That drift ran long enough for 29 of 71 skills to lack a tool most of
+ * their siblings already declared, and it surfaced through a manual audit
+ * rather than any gate. A command that can shell out but cannot Grep does
+ * not fail loudly — it quietly reaches for `Bash` + `grep` instead, which is
+ * slower, less structured, and (per `lint-portable-grep.cjs`) a portability
+ * hazard of its own on hosts without GNU grep.
+ *
+ * ## The rule
+ *
+ * A command whose `allowed-tools` includes `Bash` must also include `Grep`,
+ * unless it is on the exemption list below.
+ *
+ * Detection only. This lint never edits a command's `allowed-tools`.
+ *
+ * ## Why an exemption list rather than a heuristic
+ *
+ * The alternative — inferring from a command's body whether it "really"
+ * needs Grep — would make the rule's verdict depend on prose that changes
+ * constantly, and produce a lint whose failures nobody can predict. A short
+ * literal list keeps every exemption a reviewable one-line diff, and the
+ * staleness check below stops it becoming a dumping ground: an entry that no
+ * longer needs to be there fails just as loudly as a missing tool.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const DEFAULT_ROOT = 'commands/gsd';
+
+/**
+ * Commands allowed to declare `Bash` without `Grep`.
+ *
+ * Keyed by command stem (the filename without `.md`), with the reason inline
+ * so changing the set is a one-line, reviewable diff.
+ *
+ * #4394 named eight candidates from the #3085 review: the six `gsd-ns-*`
+ * namespace dispatchers, `gsd-help`, and `gsd-surface`. Seven of those turn
+ * out not to need an entry at all — they do not declare `Bash` in the first
+ * place, so the rule never reaches them:
+ *
+ *   ns-context/ns-ideate/ns-manage/ns-project/ns-review/ns-workflow  Read + Skill
+ *   help                                                             Read
+ *
+ * Listing them anyway would be seven pre-forgiven commands: the day one of
+ * them gained `Bash`, the omission it was granted an exemption for would
+ * pass silently. The staleness check in `scan()` below is what surfaced
+ * this, and it is why the list stays minimal — an exemption is a real
+ * suppression, not documentation.
+ */
+const EXEMPT = new Map([
+  // Toggles which skills are surfaced. Mutates the install tree through the
+  // installer's own seams rather than by searching project files, so `Bash`
+  // here is not standing in for a search it cannot perform.
+  ['surface', 'mutates the install surface via installer seams, not by searching the project'],
+]);
+
+/**
+ * Parse an `allowed-tools` frontmatter value.
+ *
+ * Handles both shapes the corpus uses: a YAML block sequence
+ *
+ *     allowed-tools:
+ *       - Read
+ *       - Bash
+ *
+ * and an inline scalar or flow sequence (`allowed-tools: Read, Bash` /
+ * `allowed-tools: [Read, Bash]`). Returns `null` when the key is absent,
+ * which is NOT a violation — a command with no `allowed-tools` at all
+ * declares no `Bash` either, so this rule has nothing to say about it.
+ *
+ * Deliberately not a YAML parser: the frontmatter here is a fixed, shallow
+ * shape, and pulling in a parser to read one list would be a dependency
+ * bought for a single key.
+ *
+ * @param {string} text  full file contents
+ * @returns {string[] | null}  declared tool names, or null when the key is absent
+ */
+function parseAllowedTools(text) {
+  const lines = String(text).split(/\r?\n/);
+  const keyIndex = lines.findIndex((l) => /^allowed-tools:/.test(l));
+  if (keyIndex === -1) return null;
+
+  const inline = lines[keyIndex].replace(/^allowed-tools:/, '').trim();
+  if (inline) {
+    return inline
+      .replace(/^\[/, '')
+      .replace(/\]$/, '')
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+  }
+
+  const tools = [];
+  for (let i = keyIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    const item = line.match(/^\s*-\s+(.+?)\s*$/);
+    if (item) {
+      tools.push(item[1].replace(/^['"]|['"]$/g, ''));
+      continue;
+    }
+    // The first line that is neither a list item nor blank ends the block —
+    // the next frontmatter key, or the closing `---`.
+    if (line.trim() === '') continue;
+    break;
+  }
+  return tools;
+}
+
+/**
+ * List command stems under `dir`, sorted.
+ *
+ * @param {string} dir  absolute path to the commands directory
+ * @returns {{ stem: string, file: string }[]}
+ */
+function listCommands(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => ({ stem: e.name.replace(/\.md$/, ''), file: path.join(dir, e.name) }))
+    .sort((a, b) => a.stem.localeCompare(b.stem));
+}
+
+/**
+ * Evaluate the corpus.
+ *
+ * Reports two independent failure classes, because an exemption list that
+ * can only ever grow rots into a list of things nobody re-examined:
+ *
+ *   - `violations`: declares Bash, omits Grep, not exempt.
+ *   - `staleExemptions`: on the list but no longer needs to be — either the
+ *     command is gone, or it no longer declares Bash without Grep. Removing
+ *     the entry is then a one-line diff, and the next omission in that
+ *     command is caught rather than silently pre-forgiven.
+ *
+ * @param {string} [root]  repo-relative commands directory
+ * @returns {{ scanned: number, violations: {stem: string, tools: string[]}[], staleExemptions: {stem: string, reason: string}[] }}
+ */
+function scan(root = DEFAULT_ROOT) {
+  const abs = path.isAbsolute(root) ? root : path.join(ROOT, root);
+  const commands = listCommands(abs);
+  const violations = [];
+  const seen = new Set();
+
+  for (const { stem, file } of commands) {
+    const tools = parseAllowedTools(fs.readFileSync(file, 'utf8'));
+    if (!tools) continue;
+    if (!tools.includes('Bash') || tools.includes('Grep')) continue;
+    seen.add(stem);
+    if (EXEMPT.has(stem)) continue;
+    violations.push({ stem, tools });
+  }
+
+  const present = new Set(commands.map((c) => c.stem));
+  const staleExemptions = [];
+  for (const [stem, reason] of EXEMPT) {
+    if (!present.has(stem)) {
+      staleExemptions.push({ stem, reason: `no such command (${reason})` });
+    } else if (!seen.has(stem)) {
+      staleExemptions.push({ stem, reason: `no longer declares Bash without Grep (${reason})` });
+    }
+  }
+
+  return { scanned: commands.length, violations, staleExemptions };
+}
+
+function main() {
+  const root = process.env.GSD_LINT_ALLOWED_TOOLS_ROOT || DEFAULT_ROOT;
+  const { scanned, violations, staleExemptions } = scan(root);
+
+  if (violations.length > 0 || staleExemptions.length > 0) {
+    const parts = [];
+    if (violations.length > 0) {
+      parts.push(
+        'lint-allowed-tools-parity: these commands declare `Bash` but not `Grep` (#4394).\n' +
+          'A command that can shell out but cannot Grep reaches for `Bash` + `grep` instead —\n' +
+          'slower, unstructured, and a portability hazard on hosts without GNU grep. Add `Grep`\n' +
+          'to the frontmatter, or add the command to EXEMPT in this script with a reason:\n' +
+          violations.map((v) => `  ${root}/${v.stem}.md  [${v.tools.join(', ')}]`).join('\n'),
+      );
+    }
+    if (staleExemptions.length > 0) {
+      parts.push(
+        'lint-allowed-tools-parity: these EXEMPT entries are stale — delete them so the next\n' +
+          'omission in those commands is caught rather than silently pre-forgiven:\n' +
+          staleExemptions.map((s) => `  ${s.stem}: ${s.reason}`).join('\n'),
+      );
+    }
+    throw new ExitError(1, parts.join('\n\n'));
+  }
+
+  console.log(
+    `ok lint-allowed-tools-parity: ${scanned} command(s) checked, ${EXEMPT.size} exemption(s) all still needed`,
+  );
+}
+
+module.exports = { parseAllowedTools, scan, EXEMPT, DEFAULT_ROOT };
+
+if (require.main === module) runMain(main);

package/scripts/lint-docs-guard-registration.exempt-baseline.cjs

@@ -46,6 +46,7 @@ const DOCS_GUARD_EXEMPT_BASELINE = [
   'codebuddy-upgrades.test.cjs',
   'commands.test.cjs',
   'commit-docs-bypass.test.cjs',
+  'compact-content-partition-guard.test.cjs',
   'complexity-trigger.test.cjs',
   'concurrency-safety.test.cjs',
   'cursor-imperative-reference.test.cjs',
@@ -67,6 +68,7 @@ const DOCS_GUARD_EXEMPT_BASELINE = [
   'lint-allow-test-rule-refs.test.cjs',
   'lint-docs-command-form.test.cjs',
   'lint-docs-required.test.cjs',
+  'lint-retired-runtime-name.test.cjs',
   'manifest-version-sync.test.cjs',
   'milestone-archive.test.cjs',
   'model-resolver.test.cjs',
@@ -80,6 +82,7 @@ const DOCS_GUARD_EXEMPT_BASELINE = [
   'repo-invariants.test.cjs',
   'require-issue-link-policy.test.cjs',
   'reviewer-manifest-body.test.cjs',
+  'reviewer-step-dispatch.test.cjs',
   'run-tests-harness.test.cjs',
   'runtime-name-policy.test.cjs',
   'security-prompt-injection.security.test.cjs',
@@ -123,8 +126,12 @@ const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
     'docs/how-to/some-unrelated-guide.md', 'docs/how-to/x.md', 'docs/some-unrelated-file.md',
     'docs/totally-unrelated.md',
   ],
+  // #4641: cites docs/adr/4641-windows-selector-consolidation.md in an
+  // explanatory comment describing why the retired `windows` scope must not
+  // be restored; the file never reads that (or any) docs/ file.
   'ci-test-scope.test.cjs': [
-    'docs/a.md', 'docs/adr', 'docs/adr/22-plan-drift-guard.md', 'docs/how-to/configure-model-profiles.md',
+    'docs/a.md', 'docs/adr', 'docs/adr/22-plan-drift-guard.md',
+    'docs/adr/4641-windows-selector-consolidation.md', 'docs/how-to/configure-model-profiles.md',
     'docs/installer-migrations.md', 'docs/ja-JP', 'docs/ja-JP/USAGE.md', 'docs/usage.md', 'docs/x.md',
   ],
   'cline-install.test.cjs': ['docs/guide.md'],
@@ -135,6 +142,10 @@ const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
   'commit-docs-bypass.test.cjs': [
     'docs/40-design.md', 'docs/CONFIGURATION.md', 'docs/readme.md', 'docs/tracked-var-mentioning',
   ],
+  // #4403: cites docs/PARTITION-RULES.md as a "see" pointer in the module docstring
+  // describing the operational spec this guard implements; the file never reads that
+  // (or any) docs/ file.
+  'compact-content-partition-guard.test.cjs': ['docs/PARTITION-RULES.md'],
   'complexity-trigger.test.cjs': ['docs/readme.md'],
   // #3884: cites docs/CLI-TOOLS.md:736 in an explanatory comment describing
   // the real `frontmatter get <file> [--field key]` CLI shape; the file
@@ -168,13 +179,39 @@ const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
     'docs/COMMANDS.md', 'docs/USER-GUIDE.md', 'docs/adr', 'docs/adr/0001-foo.md', 'docs/adr/0099-new.md',
     'docs/agents', 'docs/agents/triage-labels.md',
   ],
+  // #4729: `writeFile('docs/...', ...)` calls WRITE fabricated fixture
+  // content into a throwaway mkdtemp repo; the file never reads real shipped
+  // docs/ content — every path here is fixture data for the guard under
+  // test.
+  // Re-confirmed: every path below is WRITTEN as fabricated fixture content
+  // into a throwaway mkdtemp repo; none reads real shipped docs. The a*/b*/c*/
+  // d* entries are the adversarial-regression fixtures (dialect-plus-runtime-
+  // word, adjacency laundering, version laundering, bare-marker abuse).
+  'lint-retired-runtime-name.test.cjs': [
+    'docs/adr', 'docs/adr/999-retired-runtime-record.md', 'docs/filler/note-',
+    'docs/guides/a1.md', 'docs/guides/a2.md', 'docs/guides/b1.md',
+    'docs/guides/b2.md', 'docs/guides/b3.md', 'docs/guides/c3.md',
+    'docs/guides/c4.md', 'docs/guides/config-homes.md', 'docs/guides/d1.md',
+    'docs/guides/hooks.md', 'docs/guides/one.md', 'docs/guides/runtime-claim.md',
+    'docs/guides/setup.md', 'docs/history/migration-note.md',
+    'docs/ja-JP/guides/runtimes.md', 'docs/pt-BR/guides/a3.md',
+    'docs/pt-BR/guides/hooks.md', 'docs/pt-BR/guides/policy.md',
+    'docs/reference/client-models.md', 'docs/reference/models.md',
+    'docs/zh-CN/guides/a4.md', 'docs/zh-CN/reference/models.md',
+  ],
   'manifest-version-sync.test.cjs': [],
   // #3884: re-confirmed — the added docs/CLI-TOOLS.md:458 reference is the
   // same class as the existing docs/TESTING-SUITES.md one (a placement-note
   // / explanatory comment citing documented CLI behavior for context, never
   // a read target); the exemption's premise still holds for both.
   'milestone-archive.test.cjs': ['docs/CLI-TOOLS.md', 'docs/TESTING-SUITES.md'],
-  'model-resolver.test.cjs': ['docs/TESTING-SUITES.md'],
+  // #4505: additionally cites docs/features/dynamic-routing-with-failure-tier-escalation.md
+  // in explanatory comments, quoting the documented first-spawn contract the new rows
+  // assert against; the file never reads that (or any) docs/ file — every read it makes
+  // targets a tmpdir .planning fixture.
+  'model-resolver.test.cjs': [
+    'docs/TESTING-SUITES.md', 'docs/features/dynamic-routing-with-failure-tier-escalation.md',
+  ],
   'new-project-mvp-prompt.test.cjs': ['docs/CONFIGURATION.md'],
   'onboard-command.test.cjs': ['docs/adr/0001-runtime.md'],
   'opencode-command-dir-plural.test.cjs': ['docs/commands'],
@@ -187,11 +224,18 @@ const DOCS_GUARD_EXEMPT_DOCS_PATHS = {
   'repo-invariants.test.cjs': ['docs/FEATURES.md', 'docs/workflows/README'],
   'require-issue-link-policy.test.cjs': ['docs/-prefixed', 'docs/CONFIGURATION.md', 'docs/a.md', 'docs/b.md', 'docs/guide.md'],
   'reviewer-manifest-body.test.cjs': ['docs/how-to/ship-a-reviewer-lane.md'],
+  // #4209: 'docs/spec.md' is a synthetic, never-read fake path proving dispatchReviewerLanes
+  // has no code-review-specific special-casing; 'docs/adr/456-test-rigor-architecture.md' is a
+  // prose citation in a code comment justifying the fast-check property tests below (#4209
+  // review). Neither is a real filesystem read — the file never reads any docs/ file.
+  'reviewer-step-dispatch.test.cjs': ['docs/adr/456-test-rigor-architecture.md', 'docs/spec.md'],
   'run-tests-harness.test.cjs': ['docs/TESTING-SUITES.md'],
   'runtime-name-policy.test.cjs': ['docs/customize/skills'],
   'security-prompt-injection.security.test.cjs': ['docs/notes.md'],
   'shipped-reference-cites.test.cjs': [],
-  'state.test.cjs': ['docs/CONFIGURATION.md', 'docs/reference/state-md.md'],
+  // #4186: the record-session usage-contract test cites the documented
+  // signature in docs/CLI-TOOLS.md in its explanatory comment.
+  'state.test.cjs': ['docs/CLI-TOOLS.md', 'docs/CONFIGURATION.md', 'docs/reference/state-md.md'],
   'worktree-safety.test.cjs': ['docs/SUMMARY.md'],
 };
 

package/scripts/lint-phase-arg-assignment.cjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lint-phase-arg-assignment.cjs — a workflow that READS `${PHASE_ARG}` must
+ * also SAY where it comes from (#4777).
+ *
+ * ## Why
+ *
+ * Seven workflows shipped an `init.phase-op "${PHASE_ARG}"` call with no
+ * assignment anywhere in the file and no instruction to derive one. The
+ * variable expanded to the empty string on every run, `init.phase-op ""`
+ * resolved `phase_found: false` unconditionally, and each workflow fell
+ * through to its own "phase not executed" exit with a blank phase number —
+ * so `/gsd:secure-phase 4` reported that phase *nothing* was not executed.
+ * Two of them had carried the defect since the files were created in March.
+ *
+ * Nothing caught it because the working pattern lived in a *different* file:
+ * `verify-work.md` derives the value correctly, and a copy of an init block
+ * that leaves the derivation line behind is indistinguishable, on review,
+ * from one that never needed it.
+ *
+ * ## The rule
+ *
+ * A workflow whose bash blocks read `$PHASE_ARG` must carry one of:
+ *
+ *   1. a **shell assignment** matching one of the frozen `CANONICAL_FORMS`
+ *      below, textually before the first read; or
+ *   2. a **prose derivation step** — a line outside the bash blocks that
+ *      tells the model to parse `$ARGUMENTS` into `$PHASE_ARG`
+ *      (`execute-phase.md`: "First positional token → `PHASE_ARG`"); or
+ *   3. an entry in `EXEMPT`, with a reason.
+ *
+ * ## Why the forms are frozen
+ *
+ * Requiring *an* assignment would be satisfied by a seventh hand-rolled sed
+ * pipeline, which is how the two grammars in this tree already drifted apart.
+ * The rule therefore pins the exact text. There are three legitimate ways a
+ * workflow learns its phase — `$ARGUMENTS` positional, `--phase N`, and a
+ * positional `$1` passed by a skill dispatch — and each has exactly one
+ * spelling. A new grammar is a deliberate one-line addition here, reviewed
+ * once, rather than a copy that diverges silently.
+ *
+ * Detection only: this lint never edits a workflow.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const DEFAULT_ROOT = path.join(ROOT, 'gsd-core', 'workflows');
+const SECTIONIZER_PATH = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'markdown-sectionizer.cjs');
+
+/**
+ * Fenced-block extraction goes through the Markdown Sectionizer seam
+ * (ADR-1372) rather than a local fence regex — `local/no-adhoc-markdown-parsing`
+ * enforces that, and it is right to: a `~~~` block, an indented fence, or a
+ * nested fence inside another would each be misread by a hand-rolled pattern,
+ * and this rule's whole job is to know which lines are shell.
+ */
+function loadSectionizer() {
+  try {
+    return require(SECTIONIZER_PATH);
+  } catch (e) {
+    throw new ExitError(
+      1,
+      'lint-phase-arg-assignment: cannot load the markdown-sectionizer seam at ' +
+        `${path.relative(ROOT, SECTIONIZER_PATH)} — run 'npm run build:lib' first (${e.message})`,
+    );
+  }
+}
+
+const SHELL_INFO_STRINGS = new Set(['bash', 'sh', 'shell']);
+
+/**
+ * The only accepted spellings of a PHASE_ARG assignment, keyed by grammar.
+ * Compared after collapsing runs of whitespace, so indentation inside a
+ * block is free but the pipeline itself is not.
+ *
+ * Known limitation (#4777 review): neither `positional` nor `phaseFlag`
+ * strips a surrounding quote — `positional('4 --ws "my team"')` leaves
+ * `--ws`/`my`/`team` tokens in PHASE_ARG instead of stripping the flag, and
+ * `phaseFlag('--phase "4"')` yields an empty PHASE_ARG, reproducing this
+ * issue's own defect for that input shape. Every `argument-hint` in the
+ * repo documents unquoted usage as primary, and `positional` is copied
+ * verbatim from verify-work.md's pre-existing shipped form rather than
+ * "improved" here — hardening the regex would mean changing production
+ * bash text in all 7 shipped workflows this exact-match check compares
+ * against. See tests/lint-phase-arg-assignment.test.cjs's dedicated
+ * describe block for a live repro.
+ */
+const CANONICAL_FORMS = Object.freeze({
+  /** `/gsd:secure-phase 4` — the phase is the whole argument string, minus a `--ws <name>` pair. */
+  positional:
+    'PHASE_ARG=$(echo "$ARGUMENTS" | sed -E \'s/--ws[[:space:]]+[A-Za-z0-9._-]+//g\' | xargs)',
+  /** `/gsd:review --phase 4 --codex` — the phase is the value of a named flag. */
+  phaseFlag:
+    'PHASE_ARG=$(echo "$ARGUMENTS" | sed -nE \'s/.*--phase[[:space:]]+([A-Za-z0-9._-]+).*/\\1/p\')',
+  /** Skill dispatch passes the phase as `$1` (`Skill(skill="gsd-code-review", args="4")`). */
+  firstPositional: 'PHASE_ARG="${1}"',
+});
+
+/**
+ * Files that read `$PHASE_ARG` and legitimately do not assign it. Each entry
+ * is checked for staleness: one whose file stopped reading the variable, or
+ * started assigning it, fails just as loudly as a missing assignment — an
+ * exemption nobody can remove is how a list like this becomes a place to
+ * hide the next defect.
+ */
+const EXEMPT = new Map([
+  [
+    'code-review/steps/dispatch-fix.md',
+    'step fragment of code-review.md, which assigns PHASE_ARG="${1}" before dispatching it',
+  ],
+]);
+
+const READ_RE = /\$\{?PHASE_ARG\b/;
+const ASSIGN_RE = /^[ \t]*PHASE_ARG=(?!=).*$/gm;
+/**
+ * A prose derivation step: a non-bash line that routes `$ARGUMENTS` into
+ * `PHASE_ARG`. Matches both shapes in the tree — an arrow ("First positional
+ * token → `PHASE_ARG`") and a "store as `$PHASE_ARG`" instruction.
+ */
+const PROSE_ASSIGN_RE = /(?:→|->|store as)\s*`?\$?\{?PHASE_ARG/;
+
+/** Collapse whitespace runs so indentation does not decide the verdict. */
+function normalize(line) {
+  return line.trim().replace(/\s+/g, ' ');
+}
+
+const CANONICAL_SET = new Set(Object.values(CANONICAL_FORMS).map(normalize));
+
+/** Every `*.md` under `dir`, recursively, as paths relative to `dir`. */
+function collectWorkflows(dir) {
+  const out = [];
+  const walk = (current, prefix) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const abs = path.join(current, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(abs, rel);
+      else if (entry.isFile() && entry.name.endsWith('.md')) out.push(rel);
+    }
+  };
+  walk(dir, '');
+  return out.sort();
+}
+
+/**
+ * Classify one workflow's PHASE_ARG handling.
+ *
+ * `reads` counts bash-block reads only: `${PHASE_ARG}` inside prose is a
+ * mention (an error message being described, an example invocation), not a
+ * consumption, and requiring an assignment for those would make the rule fire
+ * on documentation.
+ */
+function inspect(text, sectionizer = loadSectionizer()) {
+  const lines = text.split('\n');
+  const shell = sectionizer
+    .scanFencedBlocks(lines)
+    .filter((b) => SHELL_INFO_STRINGS.has(b.infoString.trim().split(/\s+/)[0]))
+    // closeLineIdx === -1 marks an unterminated fence: take the rest of the
+    // file rather than dropping the block, so a workflow whose last fence is
+    // missing its closer is still scanned instead of silently exempted.
+    .map((b) => lines.slice(b.openLineIdx + 1, b.closeLineIdx === -1 ? lines.length : b.closeLineIdx).join('\n'))
+    .join('\n');
+
+  const assignments = [...shell.matchAll(ASSIGN_RE)].map((m) => m[0]);
+  const firstAssignIdx = shell.search(/^[ \t]*PHASE_ARG=(?!=)/m);
+  const firstReadIdx = shell.search(READ_RE);
+
+  // The prose search deliberately runs over the WHOLE file rather than the
+  // non-bash remainder: a derivation step is a prose line, and stripping
+  // blocks first would only add a way for the two to disagree.
+  const hasProse = text.split('\n').some((line) => PROSE_ASSIGN_RE.test(line));
+
+  return {
+    reads: firstReadIdx !== -1,
+    assignments,
+    nonCanonical: assignments.filter((a) => !CANONICAL_SET.has(normalize(a))),
+    // An assignment that lands after the first read is the same defect with
+    // extra steps — the read still expands to nothing.
+    assignsBeforeRead: firstAssignIdx !== -1 && firstReadIdx !== -1 && firstAssignIdx <= firstReadIdx,
+    hasProse,
+  };
+}
+
+/** Scan a workflows directory. Returns `{ scanned, violations, staleExemptions }`. */
+function scan(rootDir = DEFAULT_ROOT, exempt = EXEMPT) {
+  const violations = [];
+  const seenExempt = new Set();
+  const sectionizer = loadSectionizer();
+  let scanned = 0;
+
+  for (const rel of collectWorkflows(rootDir)) {
+    const report = inspect(fs.readFileSync(path.join(rootDir, rel), 'utf8'), sectionizer);
+    if (!report.reads && report.assignments.length === 0) continue;
+    scanned += 1;
+
+    // Decide the verdict FIRST, then consult the exemption list. Marking an
+    // entry used before knowing whether the file would actually fail lets an
+    // exemption outlive its reason: the file gets fixed, the entry stays, and
+    // it silently pre-forgives the NEXT unassigned read in that same file.
+    let violation = null;
+    if (report.nonCanonical.length > 0) {
+      violation = { file: rel, kind: 'non-canonical', detail: normalize(report.nonCanonical[0]) };
+    } else if (!report.reads) {
+      violation = null;
+    } else if (report.assignments.length === 0 && !report.hasProse) {
+      violation = { file: rel, kind: 'unassigned', detail: 'reads ${PHASE_ARG} with no assignment and no derivation step' };
+    } else if (report.assignments.length > 0 && !report.assignsBeforeRead) {
+      violation = { file: rel, kind: 'late-assignment', detail: 'PHASE_ARG is assigned after its first use' };
+    }
+
+    if (!violation) continue;
+    if (exempt.has(rel)) { seenExempt.add(rel); continue; }
+    violations.push(violation);
+  }
+
+  const staleExemptions = [...exempt.keys()]
+    .filter((rel) => !seenExempt.has(rel))
+    .map((rel) => ({ file: rel, reason: exempt.get(rel) }));
+
+  return { scanned, violations, staleExemptions };
+}
+
+function main() {
+  const { scanned, violations, staleExemptions } = scan();
+  const parts = [];
+
+  if (violations.length > 0) {
+    parts.push(
+      'lint-phase-arg-assignment: these workflows do not say where ${PHASE_ARG} comes from (#4777).\n' +
+        'An unassigned PHASE_ARG expands to the empty string, init.phase-op resolves\n' +
+        'phase_found:false for every invocation, and the workflow exits reporting that a blank\n' +
+        'phase was not executed. Add one of the canonical forms in this script — or, for a model-\n' +
+        'derived value, a prose derivation step — before the first read:\n' +
+        violations.map((v) => `  gsd-core/workflows/${v.file}  [${v.kind}] ${v.detail}`).join('\n'),
+    );
+  }
+  if (staleExemptions.length > 0) {
+    parts.push(
+      'lint-phase-arg-assignment: these EXEMPT entries are stale — delete them so the next\n' +
+        'unassigned read in those files is caught rather than silently pre-forgiven:\n' +
+        staleExemptions.map((s) => `  ${s.file}: ${s.reason}`).join('\n'),
+    );
+  }
+  if (parts.length > 0) throw new ExitError(1, parts.join('\n\n'));
+
+  console.log(
+    `ok lint-phase-arg-assignment: ${scanned} workflow(s) checked, ${EXEMPT.size} exemption(s) all still needed`,
+  );
+}
+
+module.exports = { CANONICAL_FORMS, EXEMPT, DEFAULT_ROOT, inspect, scan };
+
+if (require.main === module) runMain(main);