@opengsd/gsd-core 1.14.0 → 1.15.0

package/scripts/command-contract-helpers.cjs

@@ -890,6 +890,7 @@ const VIOLATION_KINDS = Object.freeze({
   LEGACY_READ_TAG: 'legacy_read_tag',
   READ_TAG_GATE_MISSING: 'read_tag_gate_missing',
   UNMATCHED_CONSUMER_TOKEN: 'unmatched_consumer_token',
+  UNRESOLVED_REFERENCE_INCLUDE: 'unresolved_reference_include',
 });
 
 /**
@@ -925,6 +926,8 @@ const REMEDIES = Object.freeze({
     "add the <required_reading> MUST-Read gate clause to this agent's instructions (see docs/AGENTS.md)",
   unmatched_consumer_token:
     'declare the producing agent and marker in the registry, or remove the dispatch — nothing emits this token',
+  unresolved_reference_include:
+    'fix the gsd-core/references/ pointer so it names an existing reference file whole and ends at the name (whitespace, end of line, or closing punctuation)',
 });
 
 /**

package/scripts/docs-guard-registry.cjs

@@ -174,6 +174,7 @@ const DOCS_GUARD_TESTS = {
   // entry).
   'tests/learnings.test.cjs': ['docs/FEATURES.md'],
   'tests/analyze-dependencies.test.cjs': ['docs/COMMANDS.md'],
+  'tests/auto-select-attribute.test.cjs': ['docs/reference/plan-md.md'],
   'tests/autonomous-converge.test.cjs': [
     'docs/COMMANDS.md',
     'docs/how-to/run-phases-autonomously.md',
@@ -272,6 +273,32 @@ const DOCS_GUARD_TESTS = {
   // seeding, so a content edit to any of them (e.g. renaming a landmark
   // heading/string a hostile-input test targets) can change this test's
   // fixture assumptions.
+  // #4728: pins the retirement of Gemini CLI prose from every localized
+  // how-to/ARCHITECTURE/USER-GUIDE/CONFIGURATION/context-monitor mirror, plus
+  // the PRESERVE (Antigravity) and MODEL-AXIS (Gemini 2.5 Pro) negative-space
+  // checks in the same locales.
+  'tests/gemini-runtime-removed.test.cjs': [
+    'docs/ja-JP/how-to/install-on-your-runtime.md',
+    'docs/ko-KR/how-to/install-on-your-runtime.md',
+    'docs/pt-BR/how-to/install-on-your-runtime.md',
+    'docs/zh-CN/how-to/install-on-your-runtime.md',
+    'docs/ja-JP/ARCHITECTURE.md',
+    'docs/ko-KR/ARCHITECTURE.md',
+    'docs/pt-BR/ARCHITECTURE.md',
+    'docs/zh-CN/ARCHITECTURE.md',
+    'docs/ja-JP/USER-GUIDE.md',
+    'docs/ko-KR/USER-GUIDE.md',
+    'docs/pt-BR/USER-GUIDE.md',
+    'docs/zh-CN/USER-GUIDE.md',
+    'docs/ja-JP/CONFIGURATION.md',
+    'docs/ko-KR/CONFIGURATION.md',
+    'docs/pt-BR/CONFIGURATION.md',
+    'docs/zh-CN/CONFIGURATION.md',
+    'docs/ja-JP/context-monitor.md',
+    'docs/ko-KR/context-monitor.md',
+    'docs/pt-BR/context-monitor.md',
+    'docs/zh-CN/context-monitor.md',
+  ],
   'tests/gen-state-md-docs.test.cjs': [
     'docs/reference/state-md.md',
     'docs/ja-JP/reference/state-md.md',
@@ -376,6 +403,7 @@ const DOCS_GUARD_TESTS = {
     'docs/how-to/plan-a-phase.md',
     'docs/AGENTS.md',
   ],
+  'tests/ui-interaction-capture.test.cjs': ['docs/CONFIGURATION.md'],
   'tests/ui-spec-inventory-provenance.test.cjs': [
     'docs/FEATURES.md',
     'docs/how-to/design-a-ui-phase.md',

package/scripts/gen-loop-host-contract.cjs

@@ -78,6 +78,23 @@ const ROLE_TO_AGENT = {
   verifier:   'gsd-verifier',
 };
 
+// #4740 — Role → family mapping. Three families: orchestration, planning,
+// execution. This constrains what a workflow may DECLARE in agent-roles for
+// a given step (admissibility), a separate concern from ROLE_TO_AGENT's
+// agent-file presence check above.
+const ROLE_FAMILY = {
+  orchestrator: 'orchestration',
+  researcher: 'planning', planner: 'planning', checker: 'planning',
+  executor: 'execution', verifier: 'execution',
+};
+const EXPECTED_FAMILY_BY_STEP = {
+  discuss: 'orchestration',
+  plan: 'planning',
+  execute: 'execution',
+  verify: 'orchestration',
+  ship: 'orchestration',
+};
+
 // ─── Parser ───────────────────────────────────────────────────────────────────
 
 /**
@@ -228,6 +245,52 @@ function crossCheckRoles(content, agentRoles, fileName) {
   return errors;
 }
 
+// ─── Cross-check: declared roles vs. their permitted family (#4740) ──────────
+
+/**
+ * For a step, verify every role declared in agentRoles belongs to that step's
+ * expected family (orchestration / planning / execution).
+ *
+ * Unlike `assertPointsCoverage`'s `if (!expected) continue // caught
+ * elsewhere` guard, an unknown step here fails CLOSED: for points
+ * there is a second net (the canonical-set and duplicate checks), but nothing
+ * else in the repo validates role families, so failing open on an unknown
+ * step would make it the one input that silently bypasses this gate — the
+ * "unknown resolving to a safe known" failure mode this check exists to close.
+ *
+ * Pure: never sorts, de-dupes, or otherwise mutates `agentRoles` — the same
+ * array `buildContract` puts into the generated contract.
+ *
+ * @param {string}   step        The step named in the marker block.
+ * @param {string[]} agentRoles  Roles declared in the block.
+ * @param {string}   fileName    For error messages.
+ * @returns {string[]}           Array of error strings; empty = OK.
+ */
+function crossCheckRoleFamilies(step, agentRoles, fileName) {
+  const expectedFamily = EXPECTED_FAMILY_BY_STEP[step];
+  if (!expectedFamily) {
+    return [fileName + ': step "' + step + '" has no entry in EXPECTED_FAMILY_BY_STEP'];
+  }
+
+  const errors = [];
+  for (const role of agentRoles) {
+    const family = ROLE_FAMILY[role];
+    if (!family) {
+      errors.push(
+        fileName + ': declared agent-role "' + role + '" has no entry in ROLE_FAMILY mapping',
+      );
+      continue;
+    }
+    if (family !== expectedFamily) {
+      errors.push(
+        fileName + ': declared agent-role "' + role + '" (family "' + family +
+        '") is not permitted at step "' + step + '" (expected family "' + expectedFamily + '")',
+      );
+    }
+  }
+  return errors;
+}
+
 // ─── 12-points coverage assertion ────────────────────────────────────────────
 
 /**
@@ -331,6 +394,10 @@ function buildContract(workflowsDir) {
     const roleErrors = crossCheckRoles(content, entry.agentRoles, file);
     allErrors.push(...roleErrors);
 
+    // Cross-check role families (#4740)
+    const roleFamilyErrors = crossCheckRoleFamilies(entry.step, entry.agentRoles, file);
+    allErrors.push(...roleFamilyErrors);
+
     for (const auxiliary of auxiliaryHosts) {
       let auxiliaryContent;
       try {
@@ -667,6 +734,7 @@ function getWiredLoopPoints(repoRoot) {
 module.exports = {
   parseLoopHostBlock,
   crossCheckRoles,
+  crossCheckRoleFamilies,
   assertPointsCoverage,
   buildContract,
   serializeContract,
@@ -676,6 +744,7 @@ module.exports = {
   CANONICAL_POINTS,
   EXPECTED_POINTS_BY_STEP,
   ROLE_TO_AGENT,
+  ROLE_FAMILY,
   scanWiredPoints,
   getWiredLoopPoints,
   coveredKindsInRegion,

package/scripts/lib/macos-conformance-tier.generated.cjs

@@ -32,6 +32,7 @@ module.exports = {
   "tests/changeset-parse.test.cjs",
   "tests/check-contract-drift.test.cjs",
   "tests/check-predicate.test.cjs",
+  "tests/check-ui-plan-gate.test.cjs",
   "tests/check-ui-safety-gate.test.cjs",
   "tests/check-update-config-dir.test.cjs",
   "tests/chunked-planning-parallel.test.cjs",
@@ -52,6 +53,7 @@ module.exports = {
   "tests/config-loader.test.cjs",
   "tests/config-schema.property.test.cjs",
   "tests/config.test.cjs",
+  "tests/configured-entrypoint-validation.test.cjs",
   "tests/contributor-standards.test.cjs",
   "tests/core-utils.test.cjs",
   "tests/cursor-subagent-isolation.test.cjs",
@@ -73,6 +75,7 @@ module.exports = {
   "tests/features-index-gate.test.cjs",
   "tests/frontmatter.unit.test.cjs",
   "tests/gap-checker.property.test.cjs",
+  "tests/gemini-runtime-removed.test.cjs",
   "tests/gen-context-index.test.cjs",
   "tests/gen-section-manifest.test.cjs",
   "tests/git-base-branch.test.cjs",
@@ -83,6 +86,7 @@ module.exports = {
   "tests/gsd-statusline.test.cjs",
   "tests/gsd-tools-path-refs.test.cjs",
   "tests/gsd-validate-commit-crash-policy.test.cjs",
+  "tests/gsd-validate-commit-sigpipe.test.cjs",
   "tests/gsd-write-guard.test.cjs",
   "tests/health-diagnostic-rules/worktree-health.test.cjs",
   "tests/health-diagnostic.test.cjs",
@@ -111,6 +115,7 @@ module.exports = {
   "tests/issue-version-gate.test.cjs",
   "tests/kimi-upgrades.test.cjs",
   "tests/lint-docs-command-form.test.cjs",
+  "tests/lint-retired-runtime-name.test.cjs",
   "tests/lint-workflow-shellcheck-fetch.test.cjs",
   "tests/list-seeds.test.cjs",
   "tests/markdown-sectionizer.test.cjs",
@@ -125,6 +130,7 @@ module.exports = {
   "tests/no-posix-mode-bit-assert.rule.test.cjs",
   "tests/no-private-binary-resolution.rule.test.cjs",
   "tests/no-unguarded-nonportable-exec.rule.test.cjs",
+  "tests/nsegment-phase-grammar.test.cjs",
   "tests/observability/event.test.cjs",
   "tests/onboard-command.test.cjs",
   "tests/opencode-plugin-adapter.test.cjs",
@@ -138,6 +144,7 @@ module.exports = {
   "tests/phase-locator.test.cjs",
   "tests/phase.test.cjs",
   "tests/plan-count-single-owner.test.cjs",
+  "tests/plan-document.test.cjs",
   "tests/plan-phase-stall-detection.test.cjs",
   "tests/plan-review-convergence.test.cjs",
   "tests/planning-inspect.test.cjs",
@@ -154,6 +161,7 @@ module.exports = {
   "tests/process-seam.test.cjs",
   "tests/profile-output.test.cjs",
   "tests/profile-pipeline.test.cjs",
+  "tests/project-root.test.cjs",
   "tests/quick-batch.test.cjs",
   "tests/quick-branching.test.cjs",
   "tests/quick-research.test.cjs",
@@ -173,21 +181,27 @@ module.exports = {
   "tests/roadmap-mode-field.test.cjs",
   "tests/roadmap-parser.test.cjs",
   "tests/roadmap-phase-fallback.test.cjs",
+  "tests/roadmap-upgrade-bracket.test.cjs",
   "tests/roadmap.test.cjs",
+  "tests/run-tests-harness.test.cjs",
   "tests/runtime-artifact-layout.test.cjs",
   "tests/runtime-identity.test.cjs",
   "tests/runtime-launcher-parity.test.cjs",
+  "tests/runtime-name-policy.test.cjs",
   "tests/security.test.cjs",
   "tests/settings-jsonc.test.cjs",
   "tests/shared-hooks-dir-resolution.test.cjs",
   "tests/shell-command-projection-dispatch.test.cjs",
+  "tests/shipped-reference-cites.test.cjs",
   "tests/spawn-liveness-banner.test.cjs",
   "tests/state-document.test.cjs",
   "tests/state-transition.test.cjs",
   "tests/state.test.cjs",
   "tests/todos-workstream-scope.test.cjs",
   "tests/tracer-bullet.test.cjs",
+  "tests/uat-predicate.test.cjs",
   "tests/uat.test.cjs",
+  "tests/ui-interaction-capture.test.cjs",
   "tests/ui-safety-gate.test.cjs",
   "tests/ui-spec-inventory-provenance.test.cjs",
   "tests/unreachable-guard-drift.test.cjs",

package/scripts/lib/ndjson-reporter.cjs

@@ -16,8 +16,9 @@
 // Durability, not `--test-reporter-destination` (#3889 root cause): a
 // reporter that YIELDS strings has them piped by Node into a
 // `fs.WriteStream` targeting the destination path, and that stream buffers.
-// The parent's `execFileSync` timeout SIGKILLs the child on a hang, and
-// SIGKILL is uncatchable and gives the process zero chance to flush — so a
+// The parent's per-chunk timeout (run-tests.cjs's runChunk) kills the child
+// on a hang, and a hard kill (TerminateProcess on Windows, SIGKILL on POSIX)
+// is uncatchable and gives the process zero chance to flush — so a
 // yield-based reporter can lose every event still sitting in the stream's
 // buffer, which is exactly the case this feature exists to diagnose (proven
 // live: a chunk killed at 2006ms produced a `killed after 2006ms` line from

package/scripts/lib/platform-conformance-tier.generated.cjs

@@ -27,6 +27,7 @@ module.exports = {
   "tests/capability-source.test.cjs",
   "tests/capability-state.test.cjs",
   "tests/changeset-new.test.cjs",
+  "tests/check-contract-drift.test.cjs",
   "tests/check-env.test.cjs",
   "tests/check-gap-analysis-plan-post-e2e.test.cjs",
   "tests/check-glossary-refs.test.cjs",
@@ -42,6 +43,7 @@ module.exports = {
   "tests/claude-md.test.cjs",
   "tests/cline-install.test.cjs",
   "tests/close-phase-todos-padded-resolves.test.cjs",
+  "tests/code-review-fix-pipeline-regression.test.cjs",
   "tests/code-review-pipeline-regression.test.cjs",
   "tests/code-review-tier3-files-override-scoping.test.cjs",
   "tests/code-review.test.cjs",
@@ -62,6 +64,7 @@ module.exports = {
   "tests/config-loader.test.cjs",
   "tests/config-schema.property.test.cjs",
   "tests/config.test.cjs",
+  "tests/configured-entrypoint-validation.test.cjs",
   "tests/copilot-install.test.cjs",
   "tests/copilot-upgrades.test.cjs",
   "tests/core-utils.test.cjs",
@@ -107,6 +110,7 @@ module.exports = {
   "tests/gsd-mcp-server-bin.test.cjs",
   "tests/gsd-statusline.test.cjs",
   "tests/gsd-validate-commit-crash-policy.test.cjs",
+  "tests/gsd-validate-commit-sigpipe.test.cjs",
   "tests/gsd-write-guard.test.cjs",
   "tests/health-diagnostic-rules/config-validation.test.cjs",
   "tests/health-diagnostic-rules/worktree-health.test.cjs",
@@ -141,6 +145,7 @@ module.exports = {
   "tests/kimi-agent-converter.test.cjs",
   "tests/kimi-upgrades.test.cjs",
   "tests/kimi-variant-disambiguation.test.cjs",
+  "tests/lint-phase-arg-assignment.test.cjs",
   "tests/lint-workflow-shellcheck-fetch.test.cjs",
   "tests/live-config-guard.test.cjs",
   "tests/lockfile-cve-audit.test.cjs",
@@ -231,6 +236,7 @@ module.exports = {
   "tests/reviewer-step-dispatch.test.cjs",
   "tests/revision-remediation-binding.test.cjs",
   "tests/roadmap-parser.test.cjs",
+  "tests/roadmap-upgrade-bracket.test.cjs",
   "tests/roadmap.test.cjs",
   "tests/run-tests-harness.test.cjs",
   "tests/run-tests-temp-root.test.cjs",
@@ -248,12 +254,17 @@ module.exports = {
   "tests/shell-command-projection-dispatch.test.cjs",
   "tests/shell-command-projection-path-sep.test.cjs",
   "tests/ship-notes-wedged-pr.test.cjs",
+  "tests/shipped-reference-cites.test.cjs",
   "tests/skill-manifest.test.cjs",
   "tests/slug-derivation-drift-guard.test.cjs",
   "tests/state-todos-render.test.cjs",
   "tests/state.test.cjs",
   "tests/teams-status.test.cjs",
+  "tests/test-gate-watch-mode.test.cjs",
   "tests/todos-workstream-scope.test.cjs",
+  "tests/ui-interaction-capture.test.cjs",
+  "tests/undo-commit-selection-4465.test.cjs",
+  "tests/undo-commit-selection.test.cjs",
   "tests/unreachable-guard-drift.test.cjs",
   "tests/unreachable-shell-guard.test.cjs",
   "tests/unusable-input.test.cjs",

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

@@ -68,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',
@@ -178,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'],

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);