gsd-remix 1.0.0

package/sdk/src/query/check-ship-ready.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Unit tests for `check.ship-ready` (decision-routing audit §3.9).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { checkShipReady } from './check-ship-ready.js';
+
+describe('checkShipReady', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = join(tmpdir(), `gsd-check-ship-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(projectDir, '.planning', 'phases'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('throws when phase arg is missing', async () => {
+    await expect(checkShipReady([], projectDir)).rejects.toThrow();
+  });
+
+  it('returns all expected shape keys', async () => {
+    await mkdir(join(projectDir, '.planning', 'phases', '01-foundation'), { recursive: true });
+
+    const { data } = await checkShipReady(['1'], projectDir);
+    const d = data as Record<string, unknown>;
+
+    expect(typeof d.ready).toBe('boolean');
+    expect(typeof d.verification_passed).toBe('boolean');
+    expect(typeof d.clean_tree).toBe('boolean');
+    expect(typeof d.on_feature_branch).toBe('boolean');
+    expect(typeof d.remote_configured).toBe('boolean');
+    expect(typeof d.gh_available).toBe('boolean');
+    expect(typeof d.gh_authenticated).toBe('boolean');
+    expect(Array.isArray(d.blockers)).toBe(true);
+  });
+
+  it('returns current_branch and base_branch fields', async () => {
+    await mkdir(join(projectDir, '.planning', 'phases', '01-foundation'), { recursive: true });
+
+    const { data } = await checkShipReady(['1'], projectDir);
+    const d = data as Record<string, unknown>;
+
+    // current_branch is either a string (when in a git repo) or null (temp dir not a repo)
+    expect(d.current_branch === null || typeof d.current_branch === 'string').toBe(true);
+    expect(d.base_branch === null || typeof d.base_branch === 'string').toBe(true);
+  });
+
+  it('never throws — returns false fields on git errors', async () => {
+    // Use a directory that is not a git repo
+    const nonGitDir = join(tmpdir(), `gsd-non-git-${Date.now()}`);
+    await mkdir(join(nonGitDir, '.planning', 'phases', '01-test'), { recursive: true });
+
+    try {
+      const { data } = await checkShipReady(['1'], nonGitDir);
+      const d = data as Record<string, unknown>;
+      // All git-based fields should be false/null when not a git repo
+      expect(d.ready).toBe(false);
+    } finally {
+      await rm(nonGitDir, { recursive: true, force: true });
+    }
+  });
+
+  it('gh_authenticated is always false (advisory — no network call)', async () => {
+    await mkdir(join(projectDir, '.planning', 'phases', '01-foundation'), { recursive: true });
+
+    const { data } = await checkShipReady(['1'], projectDir);
+    const d = data as Record<string, unknown>;
+    // Per spec: gh_authenticated is advisory — skip actual auth check to avoid slow network call
+    expect(d.gh_authenticated).toBe(false);
+  });
+});

package/sdk/src/query/check-ship-ready.ts

@@ -0,0 +1,103 @@
+/**
+ * Ship preflight checks (`check.ship-ready`).
+ *
+ * Consolidates git/gh checks from `ship.md` into a single structured query.
+ * All subprocess calls are wrapped in try/catch — never throws on git/gh failures.
+ * See `.planning/research/decision-routing-audit.md` §3.9.
+ */
+
+import { execSync } from 'node:child_process';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { normalizePhaseName } from './helpers.js';
+import { checkVerificationStatus } from './check-verification-status.js';
+import type { QueryHandler } from './utils.js';
+
+function runSyncSafe(cmd: string, cwd: string): string | null {
+  try {
+    return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function boolSyncSafe(cmd: string, cwd: string): boolean {
+  return runSyncSafe(cmd, cwd) !== null;
+}
+
+export const checkShipReady: QueryHandler = async (args, projectDir) => {
+  const raw = args[0];
+  if (!raw) {
+    throw new GSDError('phase number required for check ship-ready', ErrorClassification.Validation);
+  }
+
+  normalizePhaseName(raw); // validate format
+
+  const blockers: string[] = [];
+
+  // git checks — all wrapped in try/catch via helpers
+  const porcelain = runSyncSafe('git status --porcelain', projectDir);
+  const clean_tree = porcelain !== null && porcelain === '';
+
+  const current_branch = runSyncSafe('git rev-parse --abbrev-ref HEAD', projectDir);
+  const on_feature_branch =
+    current_branch !== null &&
+    current_branch !== 'main' &&
+    current_branch !== 'master';
+
+  // Determine base branch
+  let base_branch: string | null = null;
+  if (current_branch) {
+    const mergeRef = runSyncSafe(`git config --get branch.${current_branch}.merge`, projectDir);
+    if (mergeRef) {
+      base_branch = mergeRef.replace('refs/heads/', '');
+    } else {
+      // Fallback: check if 'main' branch exists, else 'master'
+      const mainExists = boolSyncSafe('git rev-parse --verify main', projectDir);
+      base_branch = mainExists ? 'main' : 'master';
+    }
+  }
+
+  const remoteOut = runSyncSafe('git remote', projectDir);
+  const remote_configured = remoteOut !== null && remoteOut.trim().length > 0;
+
+  // gh availability
+  const gh_available =
+    boolSyncSafe('gh --version', projectDir) ||
+    boolSyncSafe('which gh', projectDir);
+
+  // gh_authenticated: advisory — skip actual auth check to avoid slow network call
+  const gh_authenticated = false;
+
+  // Verification status
+  let verification_passed = false;
+  try {
+    const verRes = await checkVerificationStatus([raw], projectDir);
+    const vdata = verRes.data as Record<string, unknown>;
+    verification_passed = vdata.status !== 'fail';
+  } catch {
+    verification_passed = false;
+  }
+
+  // Collect blockers
+  if (!verification_passed) blockers.push('verification status is fail or missing');
+  if (!clean_tree) blockers.push('working tree is not clean (uncommitted changes)');
+  if (!on_feature_branch) blockers.push('not on a feature branch (currently on main/master or unknown)');
+  if (!remote_configured) blockers.push('no git remote configured');
+
+  const ready = verification_passed && clean_tree && on_feature_branch && remote_configured;
+
+  return {
+    data: {
+      ready,
+      verification_passed,
+      clean_tree,
+      on_feature_branch,
+      current_branch,
+      base_branch,
+      remote_configured,
+      gh_available,
+      gh_authenticated,
+      blockers,
+    },
+  };
+};

package/sdk/src/query/check-verification-status.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Unit tests for `check.verification-status` (decision-routing audit §3.8).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { checkVerificationStatus } from './check-verification-status.js';
+
+describe('checkVerificationStatus', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = join(tmpdir(), `gsd-check-ver-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(projectDir, '.planning', 'phases'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('throws when phase arg is missing', async () => {
+    await expect(checkVerificationStatus([], projectDir)).rejects.toThrow();
+  });
+
+  it('returns status missing when VERIFICATION.md does not exist', async () => {
+    await mkdir(join(projectDir, '.planning', 'phases', '01-foundation'), { recursive: true });
+
+    const { data } = await checkVerificationStatus(['1'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.status).toBe('missing');
+    expect(d.score).toBeNull();
+    expect(d.gaps).toEqual([]);
+    expect(d.human_items).toEqual([]);
+    expect(d.deferred).toEqual([]);
+  });
+
+  it('returns status pass when all rows are PASS', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '02-core');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(
+      join(phaseDir, 'VERIFICATION.md'),
+      [
+        '---',
+        'status: passed',
+        '---',
+        '',
+        '| ID | Description | Status | Notes |',
+        '|---|---|---|---|',
+        '| T-01 | Auth works | PASS | |',
+        '| T-02 | User model | PASS | |',
+        '| T-03 | API endpoint | PASS | |',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    const { data } = await checkVerificationStatus(['2'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.status).toBe('pass');
+    expect(d.gaps).toEqual([]);
+  });
+
+  it('returns status fail with gaps when FAIL rows present', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '03-api');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(
+      join(phaseDir, 'VERIFICATION.md'),
+      [
+        '| ID | Description | Status | Notes |',
+        '|---|---|---|---|',
+        '| T-01 | Auth works | PASS | |',
+        '| T-02 | Error handling | FAIL | Missing 500 handler |',
+        '| T-03 | API endpoint | PASS | |',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    const { data } = await checkVerificationStatus(['3'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.status).toBe('fail');
+    expect((d.gaps as string[]).length).toBeGreaterThan(0);
+  });
+
+  it('returns score as fraction string', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '04-ui');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(
+      join(phaseDir, 'VERIFICATION.md'),
+      [
+        '| ID | Description | Status | Notes |',
+        '|---|---|---|---|',
+        '| T-01 | Feature A | PASS | |',
+        '| T-02 | Feature B | PASS | |',
+        '| T-03 | Feature C | FAIL | |',
+        '| T-04 | Feature D | PASS | |',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    const { data } = await checkVerificationStatus(['4'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.score).toBe('3/4');
+  });
+
+  it('collects human_items when type column contains human', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '05-test');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(
+      join(phaseDir, 'VERIFICATION.md'),
+      [
+        '| ID | Description | Type | Status | Notes |',
+        '|---|---|---|---|---|',
+        '| T-01 | API returns 200 | truth | PASS | |',
+        '| T-02 | UI looks correct | human | PASS | Manual check |',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    const { data } = await checkVerificationStatus(['5'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect((d.human_items as string[]).length).toBeGreaterThan(0);
+  });
+
+  it('collects deferred items when notes column contains deferred', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '06-misc');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(
+      join(phaseDir, 'VERIFICATION.md'),
+      [
+        '| ID | Description | Status | Notes |',
+        '|---|---|---|---|',
+        '| T-01 | Feature A | PASS | |',
+        '| T-02 | Perf test | PASS | deferred to phase 8 |',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    const { data } = await checkVerificationStatus(['6'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect((d.deferred as string[]).length).toBeGreaterThan(0);
+  });
+});

package/sdk/src/query/check-verification-status.ts

@@ -0,0 +1,160 @@
+/**
+ * VERIFICATION.md parser (`check.verification-status`).
+ *
+ * Replaces VERIFICATION.md grep/parse branches in `execute-phase.md`,
+ * `autonomous.md`, `progress.md` with a structured query.
+ * See `.planning/research/decision-routing-audit.md` §3.8.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { normalizePhaseName } from './helpers.js';
+import { findPhase } from './phase.js';
+import type { QueryHandler } from './utils.js';
+
+const NOT_FOUND_RESULT = {
+  status: 'missing' as const,
+  score: null,
+  gaps: [] as string[],
+  human_items: [] as string[],
+  deferred: [] as string[],
+};
+
+// ─── Markdown table parser ─────────────────────────────────────────────────
+
+interface TableRow {
+  cells: string[];
+  raw: string;
+}
+
+function parseTableRows(content: string): TableRow[] {
+  return content
+    .split('\n')
+    .filter(line => {
+      const trimmed = line.trim();
+      return trimmed.startsWith('|') && trimmed.endsWith('|') && !/^\|[-: |]+\|$/.test(trimmed);
+    })
+    .map(line => ({
+      cells: line
+        .split('|')
+        .slice(1, -1)
+        .map(c => c.trim()),
+      raw: line.trim(),
+    }));
+}
+
+/**
+ * Find the column index that matches a header predicate, falling back to -1.
+ */
+function findColIndex(headerRow: TableRow, predicate: (cell: string) => boolean): number {
+  return headerRow.cells.findIndex(c => predicate(c));
+}
+
+export const checkVerificationStatus: QueryHandler = async (args, projectDir) => {
+  const raw = args[0];
+  if (!raw) {
+    throw new GSDError('phase number required for check verification-status', ErrorClassification.Validation);
+  }
+
+  normalizePhaseName(raw); // validate format
+
+  const phaseRes = await findPhase([raw], projectDir);
+  const pdata = phaseRes.data as Record<string, unknown>;
+
+  if (!pdata.found || !pdata.directory) {
+    return { data: NOT_FOUND_RESULT };
+  }
+
+  const phaseDirFull = join(projectDir, pdata.directory as string);
+
+  // Locate VERIFICATION.md — may be prefixed
+  let verPath: string | null = null;
+  if (existsSync(phaseDirFull)) {
+    try {
+      const files = readdirSync(phaseDirFull) as string[];
+      const verFile = files.find(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md');
+      if (verFile) verPath = join(phaseDirFull, verFile);
+    } catch {
+      return { data: NOT_FOUND_RESULT };
+    }
+  }
+
+  if (!verPath) return { data: NOT_FOUND_RESULT };
+
+  let content: string;
+  try {
+    content = await readFile(verPath, 'utf-8');
+  } catch {
+    return { data: NOT_FOUND_RESULT };
+  }
+
+  const rows = parseTableRows(content);
+  if (rows.length === 0) {
+    // No table rows — check frontmatter status field only
+    const statusMatch = content.match(/^status:\s*(\S+)/im);
+    const status = statusMatch ? statusMatch[1].toLowerCase() : 'missing';
+    return { data: { ...NOT_FOUND_RESULT, status: status === 'missing' ? 'missing' : status } };
+  }
+
+  // Detect header row — heuristic: first row typically has column names
+  const firstRow = rows[0];
+  const isHeader = firstRow.cells.some(c =>
+    /^(id|status|description|type|notes)$/i.test(c),
+  );
+  const dataRows = isHeader ? rows.slice(1) : rows;
+  const headerRow = isHeader ? firstRow : null;
+
+  // Determine column indices
+  let statusCol = headerRow ? findColIndex(headerRow, c => /^status$/i.test(c)) : -1;
+  let typeCol = headerRow ? findColIndex(headerRow, c => /^type$/i.test(c)) : -1;
+  let notesCol = headerRow ? findColIndex(headerRow, c => /^notes$/i.test(c)) : -1;
+  let descCol = headerRow ? findColIndex(headerRow, c => /^description$/i.test(c)) : -1;
+
+  // Fallbacks for tables without headers or unusual column orders
+  if (statusCol === -1) statusCol = 2; // typical: | ID | Description | Status |
+  if (descCol === -1) descCol = 1;
+
+  let passCount = 0;
+  let totalCount = 0;
+  const gaps: string[] = [];
+  const human_items: string[] = [];
+  const deferred: string[] = [];
+
+  for (const row of dataRows) {
+    const statusVal = (row.cells[statusCol] ?? '').toUpperCase();
+    const typeVal = typeCol >= 0 ? (row.cells[typeCol] ?? '').toLowerCase() : '';
+    const notesVal = notesCol >= 0 ? (row.cells[notesCol] ?? '').toLowerCase() : '';
+    const descVal = row.cells[descCol] ?? row.cells[0] ?? row.raw;
+
+    if (statusVal === 'PASS' || statusVal === 'FAIL') totalCount++;
+    if (statusVal === 'PASS') passCount++;
+    if (statusVal === 'FAIL') gaps.push(descVal);
+    if (typeVal.includes('human')) human_items.push(descVal);
+    if (notesVal.includes('deferred')) deferred.push(descVal);
+  }
+
+  const score = totalCount > 0 ? `${passCount}/${totalCount}` : null;
+
+  let status: string;
+  if (gaps.length > 0) {
+    status = 'fail';
+  } else if (passCount === totalCount && totalCount > 0) {
+    status = 'pass';
+  } else {
+    // Check frontmatter status as tiebreaker
+    const statusMatch = content.match(/^status:\s*(\S+)/im);
+    status = statusMatch ? statusMatch[1].toLowerCase() : 'partial';
+  }
+
+  return {
+    data: {
+      status,
+      score,
+      gaps,
+      human_items,
+      deferred,
+    },
+  };
+};

package/sdk/src/query/commit.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Unit tests for git commit and check-commit query handlers.
+ *
+ * Tests: execGit, sanitizeCommitMessage, commit, checkCommit.
+ * Uses real git repos in temp directories.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+// ─── Test setup ─────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-commit-'));
+  // Initialize a git repo
+  execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+  execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+  execSync('git config user.name "Test User"', { cwd: tmpDir, stdio: 'pipe' });
+  // Create .planning directory
+  await mkdir(join(tmpDir, '.planning'), { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ─── execGit ───────────────────────────────────────────────────────────────
+
+describe('execGit', () => {
+  it('returns exitCode 0 for successful command', async () => {
+    const { execGit } = await import('./commit.js');
+    const result = execGit(tmpDir, ['status']);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it('returns non-zero exitCode for failed command', async () => {
+    const { execGit } = await import('./commit.js');
+    const result = execGit(tmpDir, ['log', '--oneline']);
+    // git log fails in empty repo with no commits
+    expect(result.exitCode).not.toBe(0);
+  });
+
+  it('captures stdout from git command', async () => {
+    const { execGit } = await import('./commit.js');
+    const result = execGit(tmpDir, ['rev-parse', '--git-dir']);
+    expect(result.stdout).toBe('.git');
+  });
+});
+
+// ─── sanitizeCommitMessage ─────────────────────────────────────────────────
+
+describe('sanitizeCommitMessage', () => {
+  it('strips null bytes and zero-width characters', async () => {
+    const { sanitizeCommitMessage } = await import('./commit.js');
+    const result = sanitizeCommitMessage('hello\u0000\u200Bworld');
+    expect(result).toBe('helloworld');
+  });
+
+  it('neutralizes injection markers', async () => {
+    const { sanitizeCommitMessage } = await import('./commit.js');
+    const result = sanitizeCommitMessage('fix: update <system> prompt [SYSTEM] test');
+    expect(result).not.toContain('<system>');
+    expect(result).not.toContain('[SYSTEM]');
+  });
+
+  it('preserves normal commit messages', async () => {
+    const { sanitizeCommitMessage } = await import('./commit.js');
+    const result = sanitizeCommitMessage('feat(auth): add login endpoint');
+    expect(result).toBe('feat(auth): add login endpoint');
+  });
+
+  it('returns input unchanged for non-string', async () => {
+    const { sanitizeCommitMessage } = await import('./commit.js');
+    expect(sanitizeCommitMessage('')).toBe('');
+  });
+});
+
+// ─── commit ────────────────────────────────────────────────────────────────
+
+describe('commit', () => {
+  it('returns committed:false when commit_docs is false and no --force', async () => {
+    const { commit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: false }),
+    );
+    const result = await commit(['test commit message'], tmpDir);
+    expect((result.data as { committed: boolean }).committed).toBe(false);
+    expect((result.data as { reason: string }).reason).toContain('commit_docs');
+  });
+
+  it('creates commit with --force even when commit_docs is false', async () => {
+    const { commit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: false }),
+    );
+    await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\n');
+    const result = await commit(['test commit', '--force'], tmpDir);
+    expect((result.data as { committed: boolean }).committed).toBe(true);
+    expect((result.data as { hash: string }).hash).toBeTruthy();
+  });
+
+  it('stages files and creates commit with correct message', async () => {
+    const { commit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: true }),
+    );
+    await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\n');
+    const result = await commit(['docs: update state'], tmpDir);
+    expect((result.data as { committed: boolean }).committed).toBe(true);
+    expect((result.data as { hash: string }).hash).toBeTruthy();
+
+    // Verify commit message in git log
+    const log = execSync('git log -1 --format=%s', { cwd: tmpDir, encoding: 'utf-8' }).trim();
+    expect(log).toBe('docs: update state');
+  });
+
+  it('returns nothing staged when no files match', async () => {
+    const { commit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: true }),
+    );
+    // Stage config.json first then commit it so .planning/ has no unstaged changes
+    execSync('git add .planning/config.json', { cwd: tmpDir, stdio: 'pipe' });
+    execSync('git commit -m "init"', { cwd: tmpDir, stdio: 'pipe' });
+    // Now commit with specific nonexistent file (--files separates message from paths, matching CJS argv)
+    const result = await commit(['test msg', '--files', 'nonexistent-file.txt'], tmpDir);
+    expect((result.data as { committed: boolean }).committed).toBe(false);
+    expect((result.data as { reason: string }).reason).toContain('nonexistent-file.txt');
+  });
+
+  it('commits specific files when provided', async () => {
+    const { commit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: true }),
+    );
+    await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\n');
+    await writeFile(join(tmpDir, '.planning', 'ROADMAP.md'), '# Roadmap\n');
+    const result = await commit(['docs: state only', '--files', '.planning/STATE.md'], tmpDir);
+    expect((result.data as { committed: boolean }).committed).toBe(true);
+
+    // Verify only STATE.md was committed
+    const files = execSync('git show --name-only --format=', { cwd: tmpDir, encoding: 'utf-8' }).trim();
+    expect(files).toContain('STATE.md');
+    expect(files).not.toContain('ROADMAP.md');
+  });
+});
+
+// ─── checkCommit ───────────────────────────────────────────────────────────
+
+describe('checkCommit', () => {
+  it('returns can_commit:true when commit_docs is enabled', async () => {
+    const { checkCommit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: true }),
+    );
+    const result = await checkCommit([], tmpDir);
+    expect((result.data as { can_commit: boolean }).can_commit).toBe(true);
+  });
+
+  it('returns can_commit:true when commit_docs is not set', async () => {
+    const { checkCommit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({}),
+    );
+    const result = await checkCommit([], tmpDir);
+    expect((result.data as { can_commit: boolean }).can_commit).toBe(true);
+  });
+
+  it('returns can_commit:false when commit_docs is false and planning files staged', async () => {
+    const { checkCommit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: false }),
+    );
+    await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\n');
+    execSync('git add .planning/STATE.md', { cwd: tmpDir, stdio: 'pipe' });
+    const result = await checkCommit([], tmpDir);
+    expect((result.data as { can_commit: boolean }).can_commit).toBe(false);
+  });
+
+  it('returns can_commit:true when commit_docs is false but no planning files staged', async () => {
+    const { checkCommit } = await import('./commit.js');
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ commit_docs: false }),
+    );
+    const result = await checkCommit([], tmpDir);
+    expect((result.data as { can_commit: boolean }).can_commit).toBe(true);
+  });
+});