@opengsd/gsd-core 1.6.0-rc.2 → 1.6.0

package/scripts/gen-plugin-skills.cjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gen-plugin-skills.cjs — generates skills/gsd-<stem>/SKILL.md from
+ * commands/gsd/*.md using convertClaudeCommandToClaudeSkill.
+ *
+ * Usage:
+ *   node scripts/gen-plugin-skills.cjs              # print summary to stdout
+ *   node scripts/gen-plugin-skills.cjs --write      # write skills/ dir
+ *   node scripts/gen-plugin-skills.cjs --check      # exit 1 if committed skills/ is stale
+ *
+ * #1596 Phase B-provide. The Claude Code plugin contract discovers skills from
+ * a skills/ directory (plugins-reference). GSD's source-of-truth commands live
+ * in commands/gsd/*.md (command frontmatter); this script converts each to
+ * skill format using the same convertClaudeCommandToClaudeSkill the file-copy
+ * installer uses, producing a build-generated skills/ dir that ships in the
+ * npm package and serves plugin-only installs.
+ *
+ * Depends on: gsd-core/bin/lib/runtime-artifact-conversion.cjs (compiled from
+ * src/runtime-artifact-conversion.cts by `npm run build:lib`). Must run AFTER
+ * build:lib in the build chain.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const COMMANDS_DIR = path.join(ROOT, 'commands', 'gsd');
+const SKILLS_DIR = path.join(ROOT, 'skills');
+const CONVERSION_MODULE = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'runtime-artifact-conversion.cjs');
+const PREFIX = 'gsd-';
+const RUNTIME = 'claude';
+
+function generateSkills(conversion) {
+  const cmdNames = conversion.readGsdCommandNames();
+  const files = fs.readdirSync(COMMANDS_DIR).filter(f => f.endsWith('.md'));
+  const results = [];
+  for (const file of files) {
+    const stem = file.slice(0, -3);
+    const skillName = PREFIX + stem;
+    const src = fs.readFileSync(path.join(COMMANDS_DIR, file), 'utf8');
+    const converted = conversion.convertClaudeCommandToClaudeSkill(src, skillName, RUNTIME, cmdNames, true);
+    results.push({ skillName, content: converted });
+  }
+  return results;
+}
+
+function main() {
+  const args = new Set(process.argv.slice(2));
+  const WRITE = args.has('--write');
+  const CHECK = args.has('--check');
+
+  if (!fs.existsSync(CONVERSION_MODULE)) {
+    throw new ExitError(
+      1,
+      `gen-plugin-skills: ${path.relative(ROOT, CONVERSION_MODULE)} not found.\n` +
+      'Run `npm run build:lib` first (this script depends on the compiled converter).'
+    );
+  }
+  const conversion = require(CONVERSION_MODULE);
+  const results = generateSkills(conversion);
+
+  if (WRITE) {
+    fs.rmSync(SKILLS_DIR, { recursive: true, force: true });
+    fs.mkdirSync(SKILLS_DIR, { recursive: true });
+    for (const { skillName, content } of results) {
+      const skillDir = path.join(SKILLS_DIR, skillName);
+      fs.mkdirSync(skillDir, { recursive: true });
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+    }
+    process.stdout.write(`gen-plugin-skills: wrote ${results.length} skills to ${path.relative(ROOT, SKILLS_DIR)}/\n`);
+    return 0;
+  }
+
+  if (CHECK) {
+    if (!fs.existsSync(SKILLS_DIR)) {
+      throw new ExitError(1, 'gen-plugin-skills: skills/ missing. Run: npm run gen:plugin-skills -- --write');
+    }
+    let stale = 0;
+    const expectedNames = new Set(results.map(r => r.skillName));
+    for (const { skillName, content } of results) {
+      const skillMd = path.join(SKILLS_DIR, skillName, 'SKILL.md');
+      if (!fs.existsSync(skillMd)) {
+        process.stderr.write(`gen-plugin-skills: missing ${path.relative(ROOT, skillMd)}\n`);
+        stale++;
+        continue;
+      }
+      if (fs.readFileSync(skillMd, 'utf8') !== content) {
+        process.stderr.write(`gen-plugin-skills: stale ${path.relative(ROOT, skillMd)}\n`);
+        stale++;
+      }
+    }
+    const existingDirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith(PREFIX));
+    for (const dir of existingDirs) {
+      if (!expectedNames.has(dir.name)) {
+        process.stderr.write(`gen-plugin-skills: stale (no source) ${path.relative(ROOT, path.join(SKILLS_DIR, dir.name))}\n`);
+        stale++;
+      }
+    }
+    if (stale > 0) {
+      throw new ExitError(1, `gen-plugin-skills: ${stale} stale skill(s). Run: npm run gen:plugin-skills -- --write`);
+    }
+    process.stdout.write(`gen-plugin-skills: ${results.length} skills up to date\n`);
+    return 0;
+  }
+
+  process.stdout.write(
+    `gen-plugin-skills: would write ${results.length} skills to ${path.relative(ROOT, SKILLS_DIR)}/\n` +
+    '  (use --write to generate, --check to verify staleness)\n'
+  );
+  return 0;
+}
+
+runMain(main);

package/scripts/lint-test-file-count.allowlist.json

@@ -21,7 +21,8 @@
         "config-get-default.test.cjs",
         "config-schema.property.test.cjs",
         "config.test.cjs",
-        "enh-1055-config-intent-descriptor-drive.test.cjs"
+        "enh-1055-config-intent-descriptor-drive.test.cjs",
+        "fix-1628-config-set-validation.test.cjs"
       ],
       "issue": "TBD"
     },

package/scripts/prompt-injection-scan.sh

@@ -77,6 +77,7 @@ ALLOWLIST=(
   'hooks/gsd-prompt-guard.js'
   'hooks/gsd-read-injection-scanner.js'
   'tests/read-injection-scanner.security.test.cjs'
+  'tests/read-injection-scanner.property.test.cjs'
   'tests/security-prompt-injection.security.test.cjs'
   'tests/list-seeds.test.cjs'
   'tests/fixtures/adversarial/security/'
@@ -85,6 +86,14 @@ ALLOWLIST=(
   # and are not attack vectors — they explain/demonstrate injection patterns.
   'TEST-EXAMPLES.md'
   'explanation/security-model.md'
+  # The untrusted-input boundary reference quotes injection phrases
+  # ("ignore previous instructions", "you are now…") as examples agents must
+  # NOT comply with — it is the defense, not an attack vector.
+  'references/untrusted-input-boundary.md'
+  # Security regression tests for input validators — fixtures must contain
+  # real injection payloads to prove the validator rejects them. See
+  # DEFECT.PROMPT-INJECTION-SCAN-COLLISION in CONTEXT.md.
+  'tests/windsurf-conversion.test.cjs'
 )
 
 is_allowlisted() {

package/scripts/release-notes/conventional-title.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Single source of truth for conventional-commit PR-title parsing.
+ *
+ * Consumed by BOTH:
+ *   - the release-notes changelog classifier
+ *     (scripts/release-notes/format-github-release-notes.cjs), and
+ *   - the PR-title CI gate (.github/workflows/pr-title-validator.yml, via
+ *     evaluatePrTitle).
+ *
+ * Keeping one matcher here is the point of #1549: a forked copy of the regex
+ * would let the gate accept a title that the changelog then mis-buckets. Both
+ * the bucket anchors and the gate must read the title the same way.
+ */
+
+// Bucket anchors. The leading `^` is load-bearing: the changelog buckets on the
+// type at the START of the title. Anything before it (e.g. a `[security] ` tag)
+// defeats the anchor and silently mis-files the entry — which is exactly the
+// drift the PR-title gate below rejects at open time.
+const FEATURE_RE = /^feat(?:ure)?\s*(?:\(|!|:)/i;
+const FIX_RE = /^fix\s*(?:\(|!|:)/i;
+
+// A well-formed conventional header at the START of the title:
+//   <type>[(<scope>)][!]:
+// e.g. `fix(#1542):`, `feat(#39)!:`, `fix:`, `enhance(verify-phase):`.
+// Anchored with `^` so a leading tag/prefix fails to match (no `bad-prefix`).
+const HEADER_RE = /^([a-z]+)(\([^)]*\))?(!)?:/i;
+
+// An issue reference inside a scope: `(#123)`, `(#123, core)`, etc.
+const ISSUE_REF_IN_SCOPE_RE = /#\d+/;
+
+/**
+ * Classify a clean conventional title into a changelog bucket.
+ * Callers that hold a full changelog bullet line (with a `* ` marker and a
+ * ` by @author` suffix) must strip those first; this operates on the title.
+ *
+ * @param {string} title
+ * @returns {'Feature'|'Fix'|'Enhancement'}
+ */
+function classifyBucket(title) {
+  const t = String(title == null ? '' : title).trim();
+  if (FEATURE_RE.test(t)) return 'Feature';
+  if (FIX_RE.test(t)) return 'Fix';
+  return 'Enhancement';
+}
+
+const REQUIRED_FORMAT_MESSAGE = [
+  'PR title must follow `type(#<issue>): summary`.',
+  'The type must come first (no leading tags like `[security]`) and the scope',
+  'must carry the linked issue ref so the release changelog links to it.',
+  'Examples: `fix(#1542): roadmap rollback`, `feat(#39)!: drop legacy flag`,',
+  '`enhance(#1549): add PR-title validator`.',
+].join(' ');
+
+/**
+ * Validate a PR title against the convention the changelog depends on (#1549).
+ *
+ * @param {{ title?: string }} input
+ * @returns {{ valid: true, reason: 'valid' }
+ *          | { valid: false, reason: 'bad-prefix'|'missing-issue-ref', message: string }}
+ */
+function evaluatePrTitle({ title } = {}) {
+  const t = String(title == null ? '' : title).trim();
+
+  const m = HEADER_RE.exec(t);
+  if (!m) {
+    // No clean `type[(scope)][!]:` at the start — covers leading tags,
+    // `Revert "..."`, empty, and freeform titles.
+    return { valid: false, reason: 'bad-prefix', message: REQUIRED_FORMAT_MESSAGE };
+  }
+
+  const scope = m[2]; // includes the parens, e.g. "(#1542)" — or undefined
+  if (!scope || !ISSUE_REF_IN_SCOPE_RE.test(scope)) {
+    return { valid: false, reason: 'missing-issue-ref', message: REQUIRED_FORMAT_MESSAGE };
+  }
+
+  return { valid: true, reason: 'valid' };
+}
+
+module.exports = {
+  FEATURE_RE,
+  FIX_RE,
+  HEADER_RE,
+  classifyBucket,
+  evaluatePrTitle,
+  REQUIRED_FORMAT_MESSAGE,
+};

package/scripts/release-notes/format-github-release-notes.cjs

@@ -5,6 +5,7 @@ const os = require('os');
 const fs = require('fs');
 const { execFileSync } = require('child_process');
 const { runMain, ExitError } = require('../lib/cli-exit.cjs');
+const { classifyBucket } = require('./conventional-title.cjs');
 
 /**
  * Classify a What's-Changed bullet line into 'Feature', 'Fix', or 'Enhancement'.
@@ -19,9 +20,9 @@ function classifyTitle(bulletLine) {
   const byIdx = withoutMarker.indexOf(' by @');
   const title = (byIdx !== -1 ? withoutMarker.slice(0, byIdx) : withoutMarker).trim();
 
-  if (/^feat(?:ure)?\s*(?:\(|!|:)/i.test(title)) return 'Feature';
-  if (/^fix\s*(?:\(|!|:)/i.test(title)) return 'Fix';
-  return 'Enhancement';
+  // Delegate to the shared matcher so the gate and the changelog can never
+  // disagree on bucketing (#1549 — single source of truth).
+  return classifyBucket(title);
 }
 
 /**

package/skills/gsd-add-tests/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: gsd-add-tests
+description: "Generate tests for a completed phase based on UAT criteria and implementation"
+argument-hint: "<phase> [additional instructions]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
+
+Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
+
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/add-tests.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
+</process>

package/skills/gsd-ai-integration-phase/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gsd-ai-integration-phase
+description: "Generate an AI-SPEC.md design contract for phases that involve building AI systems."
+argument-hint: "[phase number]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - WebFetch
+  - WebSearch
+  - AskUserQuestion
+  - mcp__context7__*
+---
+
+<objective>
+Create an AI design contract (AI-SPEC.md) for a phase involving AI system development.
+Orchestrates gsd-framework-selector → gsd-ai-researcher → gsd-domain-researcher → gsd-eval-planner.
+Flow: Select Framework → Research Docs → Research Domain → Design Eval Strategy → Done
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/ai-integration-phase.md
+@~/.claude/gsd-core/references/ai-frameworks.md
+@~/.claude/gsd-core/references/ai-evals.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates.
+</process>

package/skills/gsd-audit-fix/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: gsd-audit-fix
+description: "Autonomous audit-to-fix pipeline — find issues, classify, fix, test, commit"
+argument-hint: "--source <audit-uat> [--severity <medium|high|all>] [--max N] [--dry-run]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Run an audit, classify findings as auto-fixable vs manual-only, then autonomously fix
+auto-fixable issues with test verification and atomic commits.
+
+Flags:
+- `--max N` — maximum findings to fix (default: 5)
+- `--severity high|medium|all` — minimum severity to process (default: medium)
+- `--dry-run` — classify findings without fixing (shows classification table)
+- `--source <audit>` — which audit to run (default: audit-uat)
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/audit-fix.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/skills/gsd-audit-milestone/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gsd-audit-milestone
+description: "Audit milestone completion against original intent before archiving"
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Agent
+  - Write
+---
+
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>

package/skills/gsd-audit-uat/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: gsd-audit-uat
+description: "Cross-phase audit of all outstanding UAT and verification items"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+<objective>
+Scan all phases for pending, skipped, blocked, and human_needed UAT items. Cross-reference against codebase to detect stale documentation. Produce prioritized human test plan.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/audit-uat.md
+</execution_context>
+
+<context>
+Core planning files are loaded in-workflow via CLI.
+
+**Scope:**
+Glob: .planning/phases/*/*-UAT.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>

package/skills/gsd-autonomous/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: gsd-autonomous
+description: "Run all remaining phases autonomously — discuss→plan→execute per phase"
+argument-hint: "[--from N] [--to N] [--only N] [--interactive] [--converge]"
+effort: max
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Agent
+---
+
+<objective>
+Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests).
+
+Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup.
+
+**Creates/Updates:**
+- `.planning/STATE.md` — updated after each phase
+- `.planning/ROADMAP.md` — progress updated after each phase
+- Phase artifacts — CONTEXT.md, PLANs, SUMMARYs per phase
+
+**After:** Milestone is complete and cleaned up.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/autonomous.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--from N` — start from phase N instead of the first incomplete phase.
+- `--to N` — stop after phase N completes (halt instead of advancing to next phase).
+- `--only N` — execute only phase N (single-phase mode).
+- `--interactive` — run discuss inline with questions (not auto-answered), then dispatch plan→execute as background agents. Keeps the main context lean while preserving user input on decisions.
+- `--converge` — run each phase's planning step through `gsd-plan-review-convergence` instead of plain `gsd-plan-phase`. Requires `workflow.plan_review_convergence=true`.
+- `--cross-ai` — compatibility alias for `--converge`.
+
+When `--converge` or `--cross-ai` is set, reviewer selector flags supported by `gsd-plan-review-convergence` may be passed through: `--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`.
+
+Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools query init.milestone-op`, `gsd-tools query roadmap.analyze`). No upfront context loading needed.
+</context>
+
+<process>
+Execute end-to-end.
+Preserve all workflow gates (phase discovery, per-phase execution, blocker handling, progress display).
+</process>

package/skills/gsd-capture/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: gsd-capture
+description: "Capture ideas, tasks, notes, and seeds to their destination"
+argument-hint: "[--note | --backlog | --seed | --list | --list-seeds] [text]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+
+<objective>
+Capture ideas, tasks, notes, and seeds to their appropriate destination in the GSD system.
+
+Mode routing:
+- **default** (no flag): Capture as a structured todo for later work → add-todo workflow
+- **--note**: Zero-friction idea capture (append/list/promote) → note workflow
+- **--backlog**: Add an idea to the backlog parking lot (999.x numbering) → add-backlog workflow
+- **--seed**: Capture a forward-looking idea with trigger conditions → plant-seed workflow
+- **--list**: List pending todos and select one to work on → check-todos workflow
+- **--list-seeds**: List/audit captured seeds (optional status filter) → list-seeds workflow
+</objective>
+
+<routing>
+
+| Flag | Destination | Workflow |
+|------|-------------|----------|
+| (none) | Structured todo in .planning/todos/ | add-todo |
+| --note | Timestamped note file, list, or promote | note |
+| --backlog | ROADMAP.md backlog section (999.x) | add-backlog |
+| --seed | .planning/seeds/SEED-NNN-slug.md | plant-seed |
+| --list | Interactive todo browser + action router | check-todos |
+| --list-seeds | Read-only seed list/audit (optional status filter) | list-seeds |
+
+</routing>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/add-todo.md
+@~/.claude/gsd-core/workflows/note.md
+@~/.claude/gsd-core/workflows/add-backlog.md
+@~/.claude/gsd-core/workflows/plant-seed.md
+@~/.claude/gsd-core/workflows/check-todos.md
+@~/.claude/gsd-core/workflows/list-seeds.md
+@~/.claude/gsd-core/references/ui-brand.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse the first token of $ARGUMENTS:
+- If it is `--note`: strip the flag, pass remainder to note workflow
+- If it is `--backlog`: strip the flag, pass remainder to add-backlog workflow
+- If it is `--seed`: strip the flag, pass remainder to plant-seed workflow
+- If it is `--list-seeds`: strip the flag, pass remainder (optional status filter) to list-seeds workflow
+- If it is `--list`: pass remainder (optional area filter) to check-todos workflow
+- Otherwise: pass all of $ARGUMENTS to add-todo workflow
+</context>
+
+<process>
+1. Parse the leading flag (if any) from $ARGUMENTS.
+2. Load and execute the appropriate workflow end-to-end based on the routing table above.
+3. Preserve all workflow gates from the target workflow (directory structure, duplicate detection, commits, etc.).
+</process>

package/skills/gsd-cleanup/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: gsd-cleanup
+description: "Archive accumulated phase directories from completed milestones"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/cleanup.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>

package/skills/gsd-code-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: gsd-code-review
+description: "Review source files changed during a phase for bugs, security issues, and code quality problems"
+argument-hint: "<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Agent
+---
+
+<objective>
+Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems.
+
+Spawns the gsd-code-reviewer agent to analyze code at the specified depth level. Produces REVIEW.md artifact in the phase directory with severity-classified findings.
+
+Arguments:
+- Phase number (required) — which phase's changes to review (e.g., "2" or "02")
+- `--depth=quick|standard|deep` (optional) — review depth level, overrides workflow.code_review_depth config
+  - quick: Pattern-matching only (~2 min)
+  - standard: Per-file analysis with language-specific checks (~5-15 min, default)
+  - deep: Cross-file analysis including import graphs and call chains (~15-30 min)
+- `--files file1,file2,...` (optional) — explicit comma-separated file list, skips SUMMARY/git scoping (highest precedence for scoping)
+- `--fix` (optional) — after review completes (or if REVIEW.md already exists), auto-apply fixes found. Spawns gsd-code-fixer agent. Accepts sub-flags:
+  - `--all` — include Info findings in fix scope (default: Critical + Warning only)
+  - `--auto` — enable fix + re-review iteration loop, capped at 3 iterations
+
+Output: {padded_phase}-REVIEW.md in phase directory + inline summary of findings
+</objective>
+
+<execution_context>
+@~/.claude/gsd-core/workflows/code-review.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS (first positional argument is phase number)
+
+Optional flags parsed from $ARGUMENTS:
+- `--depth=VALUE` — Depth override (quick|standard|deep). If provided, overrides workflow.code_review_depth config.
+- `--files=file1,file2,...` — Explicit file list override. Has highest precedence for file scoping per D-08. When provided, workflow skips SUMMARY.md extraction and git diff fallback entirely.
+
+Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<files_to_read>` blocks.
+</context>
+
+<process>
+This command is a thin dispatch layer. It parses arguments and delegates to the workflow.
+
+Execute end-to-end.
+
+The workflow (not this command) enforces these gates:
+- Phase validation (before config gate)
+- Config gate check (workflow.code_review)
+- File scoping (--files override > SUMMARY.md > git diff fallback)
+- Empty scope check (skip if no files)
+- Agent spawning (gsd-code-reviewer)
+- Result presentation (inline summary + next steps)
+</process>