@xulthekl/team-flow 0.22.4

package/templates/spec.md

@@ -0,0 +1,31 @@
+# 能力规格
+
+## ADDED Requirements
+
+### Requirement: 需求名称
+
+The system SHALL 提供清晰且可测试的所需行为。
+
+#### Scenario: 正常路径
+
+- **WHEN** 触发动作发生
+- **THEN** 系统产生预期结果
+
+## MODIFIED Requirements
+
+### Requirement: 现有需求名称
+
+The system SHALL 按此处描述的更新行为执行。
+
+#### Scenario: 更新后的行为
+
+- **WHEN** 执行某个已知现有路径
+- **THEN** 出现新的 approved behavior
+
+## REMOVED Requirements
+
+### Requirement: 已弃用需求名称
+
+**Reason**: 为什么要移除该行为。
+
+**Migration**: 应该用什么替代它。

package/templates/tasks.md

@@ -0,0 +1,47 @@
+# 实现任务
+
+## 文件结构
+
+- `Create: path/to/new-file.ts` — 一句话说明职责
+- `Modify: path/to/existing.ts` — 改什么、为什么
+
+## 接口
+
+### Batch N → Batch M
+- **Produces**: `type/function name` — 被 Batch M 用于什么目的
+
+## 1. Batch 1: [批次目标]
+
+- [ ] **1.1 编写失败的测试**
+
+```language
+// 带精确断言的测试代码
+```
+
+**Files**: `Create/Modify: exact/path`
+
+- [ ] **1.2 运行测试并确认失败**
+
+Run: `exact command`
+Expected: FAIL with "specific error message"
+
+- [ ] **1.3 实现最小化代码**
+
+```language
+// 实现代码
+```
+
+**Files**: `Create/Modify: exact/path`
+**Interfaces**: Produces `name(type): returnType` — 被 Batch N 消费
+
+- [ ] **1.4 运行测试并确认通过**
+
+Run: `exact command`
+Expected: PASS
+
+- [ ] **1.5 提交**
+
+```bash
+git add files
+git commit -m "feat: description"
+```

package/tests/e2e.test.mjs

@@ -0,0 +1,266 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  parseDeltaSpec,
+  parseChangeMarkdown,
+  Validator,
+  tokenize,
+  detectLanguage,
+} from '../dist/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const EXAMPLES_DIR = resolve(__dirname, '../docs/examples');
+
+function readExample(...parts) {
+  return readFileSync(resolve(EXAMPLES_DIR, ...parts), 'utf-8');
+}
+
+describe('parseDeltaSpec', () => {
+  it('parses add-dark-mode spec with 3 ADDED requirements', () => {
+    const content = readExample('add-dark-mode', 'specs', 'ui-theme', 'spec.md');
+    const plan = parseDeltaSpec(content);
+
+    assert.equal(plan.added.length, 3);
+    assert.equal(plan.modified.length, 0);
+    assert.equal(plan.removed.length, 0);
+    assert.equal(plan.renamed.length, 0);
+    assert.equal(plan.sectionPresence.added, true);
+
+    const names = plan.added.map(b => b.name);
+    assert.ok(names.includes('User can use dark mode'));
+    assert.ok(names.includes('User preference persists'));
+    assert.ok(names.includes('Theme maintains readable contrast'));
+  });
+
+  it('parses refactor-auth-boundary spec with 3 MODIFIED requirements', () => {
+    const content = readExample('refactor-auth-boundary', 'specs', 'auth-boundary', 'spec.md');
+    const plan = parseDeltaSpec(content);
+
+    assert.equal(plan.added.length, 0);
+    assert.equal(plan.modified.length, 3);
+    assert.equal(plan.removed.length, 0);
+    assert.equal(plan.renamed.length, 0);
+    assert.equal(plan.sectionPresence.modified, true);
+
+    const names = plan.modified.map(b => b.name);
+    assert.ok(names.includes('Protected requests use one authentication boundary'));
+    assert.ok(names.includes('Auth failures map consistently'));
+    assert.ok(names.includes('Existing approved login behavior remains unchanged'));
+  });
+});
+
+describe('parseChangeMarkdown', () => {
+  it('parses add-dark-mode proposal with why and whatChanges', () => {
+    const content = readExample('add-dark-mode', 'proposal.md');
+    const change = parseChangeMarkdown(content, 'add-dark-mode');
+
+    assert.equal(change.name, 'add-dark-mode');
+    assert.ok(change.why.length > 50, `why section too short: ${change.why.length} chars`);
+    assert.ok(change.whatChanges.length > 0, 'whatChanges section is empty');
+
+    // proposal.md uses "## Capabilities" not "## ADDED/MODIFIED Requirements"
+    // so deltas array will be empty (no delta sections found)
+    assert.equal(change.deltas.length, 0);
+  });
+
+  it('parses refactor-auth-boundary proposal with why and whatChanges', () => {
+    const content = readExample('refactor-auth-boundary', 'proposal.md');
+    const change = parseChangeMarkdown(content, 'refactor-auth-boundary');
+
+    assert.equal(change.name, 'refactor-auth-boundary');
+    assert.ok(change.why.length > 50, `why section too short: ${change.why.length} chars`);
+    assert.ok(change.whatChanges.length > 0, 'whatChanges section is empty');
+  });
+});
+
+describe('Validator.validateDeltaSpec', () => {
+  const validator = new Validator();
+
+  it('validates add-dark-mode delta spec structure', () => {
+    const content = readExample('add-dark-mode', 'specs', 'ui-theme', 'spec.md');
+    const report = validator.validateDeltaSpec(content);
+
+    // Delta specs should have deltas (ADDED/MODIFIED/REMOVED/RENAMED)
+    // The validator checks for presence of delta sections
+    assert.equal(report.valid, true, `Expected valid but got issues: ${JSON.stringify(report.issues, null, 2)}`);
+    assert.equal(report.summary.errors, 0);
+  });
+
+  it('validates refactor-auth-boundary delta spec structure', () => {
+    const content = readExample('refactor-auth-boundary', 'specs', 'auth-boundary', 'spec.md');
+    const report = validator.validateDeltaSpec(content);
+
+    assert.equal(report.valid, true, `Expected valid but got issues: ${JSON.stringify(report.issues, null, 2)}`);
+    assert.equal(report.summary.errors, 0);
+  });
+});
+
+describe('Validator.validateChangeContent', () => {
+  const validator = new Validator();
+
+  it('validates add-dark-mode proposal as valid', () => {
+    const content = readExample('add-dark-mode', 'proposal.md');
+    const report = validator.validateChangeContent('add-dark-mode', content);
+
+    assert.equal(report.valid, true, `Expected valid but got issues: ${JSON.stringify(report.issues, null, 2)}`);
+    assert.equal(report.summary.errors, 0);
+  });
+
+  it('validates refactor-auth-boundary proposal as valid', () => {
+    const content = readExample('refactor-auth-boundary', 'proposal.md');
+    const report = validator.validateChangeContent('refactor-auth-boundary', content);
+
+    assert.equal(report.valid, true, `Expected valid but got issues: ${JSON.stringify(report.issues, null, 2)}`);
+    assert.equal(report.summary.errors, 0);
+  });
+});
+
+describe('Validator.validateImplementation', () => {
+  const validator = new Validator();
+
+  it('returns VerificationReport with three dimensions', () => {
+    const report = validator.validateImplementation(
+      'Added auth middleware in src/middleware/auth.ts',
+      '### Requirement: Auth middleware\nThe system SHALL authenticate all API requests.\n#### Scenario: Valid token\n- **WHEN** a request has a valid token\n- **THEN** the system SHALL allow access',
+      '## Decisions\n### Decision 1\n- Choice: JWT-based auth\n- Rationale: stateless'
+    );
+    assert.ok(report.dimensions);
+    assert.equal(report.dimensions.length, 3);
+    const names = report.dimensions.map(d => d.name);
+    assert.ok(names.includes('Completeness'));
+    assert.ok(names.includes('Correctness'));
+    assert.ok(names.includes('Coherence'));
+    assert.ok(['PASS', 'FAIL', 'CONDITIONAL'].includes(report.verdict));
+  });
+
+  it('detects missing requirement in diff (Completeness FAIL)', () => {
+    const report = validator.validateImplementation(
+      'Added logging to src/utils/logger.ts',
+      '### Requirement: Auth middleware\nThe system SHALL authenticate all API requests.\n\n### Requirement: Rate limiting\nThe system SHALL limit requests to 100 per minute.',
+      '## Decisions\n### Decision 1\n- Choice: JWT\n- Rationale: stateless'
+    );
+    const completeness = report.dimensions.find(d => d.name === 'Completeness');
+    assert.ok(completeness);
+    assert.equal(completeness.status, 'FAIL');
+    assert.ok(completeness.findings.some(f => f.message.includes('Rate limiting')));
+  });
+
+  it('detects placeholder markers in diff (Correctness FAIL)', () => {
+    const report = validator.validateImplementation(
+      'Added auth middleware. TODO: implement rate limiting',
+      '### Requirement: Auth middleware\nThe system SHALL authenticate all API requests.',
+      '## Decisions\n### Decision 1\n- Choice: JWT\n- Rationale: stateless'
+    );
+    const correctness = report.dimensions.find(d => d.name === 'Correctness');
+    assert.equal(correctness.status, 'FAIL');
+  });
+
+  it('passes when all requirements covered and no placeholders', () => {
+    const report = validator.validateImplementation(
+      'Added JWT auth middleware in src/middleware/auth.ts, rate limiter in src/middleware/rate-limit.ts',
+      '### Requirement: Auth middleware\nThe system SHALL authenticate all API requests.\n\n### Requirement: Rate limiting\nThe system SHALL limit requests to 100 per minute.',
+      '## Decisions\n### Decision 1\n- Choice: JWT-based auth\n- Rationale: stateless'
+    );
+    assert.equal(report.verdict, 'PASS');
+  });
+
+  it('detects coherence gaps when design decisions not in diff', () => {
+    const report = validator.validateImplementation(
+      'Added session-based auth in src/auth.ts',
+      '### Requirement: Auth middleware\nThe system SHALL authenticate all API requests.',
+      '## Decisions\n### Decision 1\n- Choice: JWT-based auth\n- Rationale: stateless'
+    );
+    const coherence = report.dimensions.find(d => d.name === 'Coherence');
+    assert.ok(coherence.findings.length > 0);
+  });
+
+  it('verifies Chinese spec content with Chinese tokenizer', () => {
+    const report = validator.validateImplementation(
+      '新增速率限制模块，使用令牌桶算法实现 src/middleware/rate-limit.ts',
+      '### Requirement: 速率限制\n系统必须实现令牌桶算法进行速率限制。\n#### Scenario: 正常请求\n- **WHEN** 请求频率在限制内\n- **THEN** 系统必须正常处理',
+      '## Decisions\n### Decision 1\n- Choice: 令牌桶算法\n- Rationale: 平滑限流'
+    );
+    const completeness = report.dimensions.find(d => d.name === 'Completeness');
+    assert.ok(completeness, 'Missing Completeness dimension');
+    assert.equal(completeness.status, 'PASS', `Expected PASS but got ${completeness.status}: ${JSON.stringify(completeness.findings)}`);
+  });
+
+  it('detects missing requirement in Chinese spec (Completeness FAIL)', () => {
+    const report = validator.validateImplementation(
+      '新增日志模块 src/utils/logger.ts',
+      '### Requirement: 速率限制\n系统必须实现令牌桶算法进行速率限制。\n\n### Requirement: 日志记录\n系统必须记录所有API请求日志。',
+      '## Decisions\n### Decision 1\n- Choice: 令牌桶算法\n- Rationale: 平滑限流'
+    );
+    const completeness = report.dimensions.find(d => d.name === 'Completeness');
+    assert.equal(completeness.status, 'FAIL');
+    assert.ok(completeness.findings.some(f => f.message.includes('速率限制')));
+  });
+});
+
+describe('tokenize', () => {
+  it('tokenizes English text with stemming', () => {
+    const tokens = tokenize('Rate limiting middleware implementation', 'en');
+    assert.ok(tokens.has('limit'), `Expected "limit" in tokens: ${[...tokens].join(', ')}`);
+    assert.ok(tokens.has('rate'), `Expected "rate" in tokens: ${[...tokens].join(', ')}`);
+    assert.ok(tokens.has('middleware'), `Expected "middleware" in tokens: ${[...tokens].join(', ')}`);
+    assert.ok(tokens.has('implement'), `Expected "implement" in tokens: ${[...tokens].join(', ')}`);
+  });
+
+  it('tokenizes Chinese text with CJK extraction', () => {
+    const tokens = tokenize('速率限制模块必须支持令牌桶算法', 'zh');
+    assert.ok(tokens.size > 0, 'Expected non-empty token set for Chinese text');
+    assert.ok(tokens.has('速率'), `Expected "速率" in tokens: ${[...tokens].join(', ')}`);
+    assert.ok(tokens.has('限制'), `Expected "限制" in tokens: ${[...tokens].join(', ')}`);
+    assert.ok(tokens.has('令牌'), `Expected "令牌" in tokens: ${[...tokens].join(', ')}`);
+  });
+
+  it('auto-detects language from text content', () => {
+    assert.equal(detectLanguage('Rate limiting middleware implementation'), 'en');
+    assert.equal(detectLanguage('速率限制模块必须支持令牌桶算法'), 'zh');
+    const mixed = detectLanguage('使用 Redis 实现速率限制模块的令牌桶算法');
+    assert.ok(['zh', 'mixed'].includes(mixed), `Expected zh or mixed, got: ${mixed}`);
+  });
+});
+
+describe('Validator.detectSyncConflicts', () => {
+  const validator = new Validator();
+
+  it('returns no conflicts when delta specs modify different requirements', () => {
+    const deltas = [
+      {
+        changeName: 'change-a',
+        content: '## MODIFIED Requirements\n### Requirement: Auth middleware\nThe system SHALL use JWT.\n#### Scenario: test\n- **WHEN** x\n- **THEN** y',
+      },
+      {
+        changeName: 'change-b',
+        content: '## MODIFIED Requirements\n### Requirement: Rate limiting\nThe system SHALL limit to 100 req/min.\n#### Scenario: test\n- **WHEN** x\n- **THEN** y',
+      },
+    ];
+    const report = validator.detectSyncConflicts(deltas);
+    assert.equal(report.hasConflicts, false);
+    assert.equal(report.conflicts.length, 0);
+  });
+
+  it('detects conflicts when two changes modify the same requirement', () => {
+    const deltas = [
+      {
+        changeName: 'change-a',
+        content: '## MODIFIED Requirements\n### Requirement: Auth middleware\nThe system SHALL use JWT tokens.\n#### Scenario: test\n- **WHEN** x\n- **THEN** y',
+      },
+      {
+        changeName: 'change-b',
+        content: '## MODIFIED Requirements\n### Requirement: Auth middleware\nThe system SHALL use session cookies.\n#### Scenario: test\n- **WHEN** x\n- **THEN** y',
+      },
+    ];
+    const report = validator.detectSyncConflicts(deltas);
+    assert.equal(report.hasConflicts, true);
+    assert.equal(report.conflicts.length, 1);
+    assert.equal(report.conflicts[0].requirement, 'Auth middleware');
+    assert.ok(report.conflicts[0].changes.includes('change-a'));
+    assert.ok(report.conflicts[0].changes.includes('change-b'));
+  });
+});

package/tests/lib/cmd-audit.test.mjs

@@ -0,0 +1,202 @@
+// tests/lib/cmd-audit.test.mjs
+// Tests for scripts/lib/cmd-audit.mjs
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+let tempDir;
+
+describe('cmd-audit: generateReport()', () => {
+  let generateReport, DP_NAMES;
+
+  before(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), 'tf-audit-test-'));
+    const modulePath = join(process.cwd(), 'scripts/lib/cmd-audit.mjs');
+    const mod = await import(modulePath);
+    generateReport = mod.generateReport;
+    DP_NAMES = mod.DP_NAMES;
+  });
+
+  after(() => {
+    if (tempDir) rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('generates report with all 8 DP rows (DP-0 through DP-7)', () => {
+    const state = {
+      change_name: 'test-change',
+      state: 'closing',
+      dp_0_result: 'confirmed',
+      dp_1_result: 'confirmed: csv export',
+      dp_2_result: 'approved: artifacts ok',
+      dp_3_result: 'contract signed',
+      dp_4_result: null,
+      dp_5_result: null,
+      dp_6_result: null,
+      dp_7_result: null,
+    };
+
+    const report = generateReport(tempDir, state);
+
+    // Should contain all 8 DPs in the summary table
+    for (let i = 0; i <= 7; i++) {
+      assert.ok(report.includes(`DP-${i}`), `Report should include DP-${i}`);
+    }
+  });
+
+  it('includes change name and state in header', () => {
+    const state = { change_name: 'export-csv', state: 'executing' };
+    const report = generateReport(tempDir, state);
+
+    assert.ok(report.includes('export-csv'));
+    assert.ok(report.includes('executing'));
+    assert.ok(report.includes('# Decision-Point Audit Report'));
+  });
+
+  it('reports correct recorded/missing counts', () => {
+    const state = {
+      change_name: 'test',
+      state: 'specifying',
+      dp_0_result: 'confirmed',
+      dp_1_result: 'confirmed: ok',
+      // dp_2 through dp_7 are all null (not recorded)
+    };
+
+    const report = generateReport(tempDir, state);
+
+    assert.ok(report.includes('2/8 已记录'), `Expected 2/8 recorded but got: ${report}`);
+    assert.ok(report.includes('6/8 未记录'), `Expected 6/8 missing but got: ${report}`);
+  });
+
+  it('treats confirmed DP-0 state as recorded without dp_0_result', () => {
+    const state = {
+      change_name: 'test',
+      state: 'specifying',
+      dp_0_decisions: 'scope confirmed',
+      dp_0_confirmed: 'true',
+      dp_0_timestamp: '2026-07-06T10:50:00Z',
+    };
+
+    const report = generateReport(tempDir, state);
+
+    assert.ok(
+      report.includes('| DP-0 | 用户确认门禁 | confirmed | 2026-07-06T10:50:00Z |'),
+      `Expected DP-0 to be recorded from dp_0_confirmed but got: ${report}`,
+    );
+    assert.ok(report.includes('1/8 已记录'), `Expected 1/8 recorded but got: ${report}`);
+  });
+
+  it('marks unrecorded DPs with interpretation hint', () => {
+    const state = {
+      change_name: 'test',
+      state: 'exploring',
+      // No DPs recorded at all
+    };
+
+    const report = generateReport(tempDir, state);
+
+    // Should have 'not recorded' for all DPs
+    const notRecordedCount = (report.match(/not recorded/g) || []).length;
+    assert.ok(notRecordedCount >= 8, `Expected at least 8 'not recorded' but got ${notRecordedCount}`);
+
+    // Unrecorded DPs should have the interpretation hint
+    assert.ok(report.includes('尚未记录结果'), 'Should include hint for unrecorded DPs');
+  });
+
+  it('includes all DP names from DP_NAMES constant', () => {
+    const state = {
+      change_name: 'test',
+      state: 'closing',
+      dp_0_result: 'ok',
+      dp_0_timestamp: '2026-07-01T00:00:00Z',
+      dp_1_result: 'ok',
+      dp_1_timestamp: '2026-07-01T00:00:00Z',
+      dp_2_result: 'ok',
+      dp_2_timestamp: '2026-07-01T00:00:00Z',
+      dp_3_result: 'ok',
+      dp_3_timestamp: '2026-07-01T00:00:00Z',
+      dp_4_result: 'ok',
+      dp_4_timestamp: '2026-07-01T00:00:00Z',
+      dp_5_result: 'ok',
+      dp_5_timestamp: '2026-07-01T00:00:00Z',
+      dp_6_result: 'ok',
+      dp_6_timestamp: '2026-07-01T00:00:00Z',
+      dp_7_result: 'ok',
+      dp_7_timestamp: '2026-07-01T00:00:00Z',
+    };
+
+    const report = generateReport(tempDir, state);
+
+    for (const [dpNum, name] of Object.entries(DP_NAMES)) {
+      assert.ok(report.includes(name), `Report should include DP-${dpNum} name: ${name}`);
+    }
+
+    assert.ok(report.includes('8/8 已记录'));
+  });
+
+  it('formats timestamps correctly', () => {
+    const state = {
+      change_name: 'test',
+      state: 'closing',
+      dp_0_result: 'confirmed',
+      dp_0_timestamp: '2026-07-01T08:30:00Z',
+    };
+
+    const report = generateReport(tempDir, state);
+    assert.ok(report.includes('2026-07-01T08:30:00Z'));
+  });
+
+  it('handles empty string as not recorded', () => {
+    const state = {
+      change_name: 'test',
+      state: 'exploring',
+      dp_0_result: '',
+      dp_0_timestamp: '',
+    };
+
+    const report = generateReport(tempDir, state);
+    assert.ok(report.includes('not recorded'), 'Empty strings should be treated as not recorded');
+  });
+
+  it('uses directory basename when change_name is null', () => {
+    const state = { state: 'exploring' };
+    const report = generateReport(tempDir, state);
+
+    // tempDir basename should appear
+    const dirName = tempDir.split('/').filter(Boolean).pop();
+    assert.ok(report.includes(dirName), `Report should include directory name "${dirName}" as fallback`);
+  });
+
+  it('generates per-DP interpretation section for each DP', () => {
+    const state = {
+      change_name: 'test',
+      state: 'bridging',
+      dp_0_result: 'confirmed: scope ok',
+    };
+
+    const report = generateReport(tempDir, state);
+
+    // Should have per-DP sections
+    for (let i = 0; i <= 7; i++) {
+      assert.ok(report.includes(`### DP-${i}`), `Report should have section for DP-${i}`);
+    }
+
+    // Recorded DP should have the recorded interpretation
+    assert.ok(report.includes('已记录为'));
+  });
+
+  it('generates a valid markdown table', () => {
+    const state = {
+      change_name: 'test',
+      state: 'specifying',
+      dp_0_result: 'confirmed',
+    };
+
+    const report = generateReport(tempDir, state);
+
+    // Verify table structure
+    assert.ok(report.includes('| DP | 名称 | 结果 | 时间戳 |'), 'Should have table header');
+    assert.ok(report.includes('|----|------|------|--------|'), 'Should have table separator');
+  });
+});

package/tests/lib/cmd-checkpoint.test.mjs

@@ -0,0 +1,98 @@
+// tests/lib/cmd-checkpoint.test.mjs
+// Dispatcher-level tests for tf checkpoint.
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const CLI = join(process.cwd(), 'scripts/team-flow.mjs');
+let changeDir;
+
+function runSsf(args) {
+  try {
+    const stdout = execFileSync(process.execPath, [CLI, ...args], {
+      encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { exitCode: 0, stdout, stderr: '' };
+  } catch (error) {
+    return {
+      exitCode: error.status || 1,
+      stdout: error.stdout?.toString() || '',
+      stderr: error.stderr?.toString() || error.message,
+    };
+  }
+}
+
+beforeEach(() => {
+  changeDir = mkdtempSync(join(tmpdir(), 'tf-checkpoint-'));
+  writeFileSync(join(changeDir, 'tasks.md'), '# Tasks\n\n- [ ] 1.1 Original task text\n');
+});
+
+afterEach(() => {
+  rmSync(changeDir, { recursive: true, force: true });
+});
+
+describe('tf checkpoint', () => {
+  it('advertises checkpoint and handoff syntax in --help', () => {
+    const result = runSsf(['--help']);
+    assert.equal(result.exitCode, 0, result.stderr);
+    assert.match(result.stdout, /checkpoint save <change-dir>/);
+    assert.match(result.stdout, /handoff create <change-dir>/);
+  });
+
+  it('saves and shows a task checkpoint', () => {
+    const result = runSsf([
+      'checkpoint', 'save', changeDir, '--task', '1.1', '--next', 'Run focused tests',
+      '--completed', 'Added parser tests', '--verification', 'tests/lib/sdd-overlay.test.mjs',
+      '--review', 'review.md', '--risk', 'None', '--commit-start', 'aaaaaaa', '--commit-end', 'bbbbbbb',
+    ]);
+    assert.equal(result.exitCode, 0, result.stderr);
+    const show = runSsf(['checkpoint', 'show', changeDir, '1.1', '--json']);
+    assert.equal(show.exitCode, 0, show.stderr);
+    const shown = JSON.parse(show.stdout).checkpoint;
+    assert.equal(shown.next, 'Run focused tests');
+    assert.equal(shown.completed, 'Added parser tests');
+    assert.equal(shown.evidence, 'tests/lib/sdd-overlay.test.mjs');
+    assert.equal(shown.review, 'review.md');
+    assert.equal(shown.risk, 'None');
+    assert.equal(shown.commit_start, 'aaaaaaa');
+    assert.equal(shown.commit_end, 'bbbbbbb');
+
+    const listed = runSsf(['checkpoint', 'list', changeDir, '--json']);
+    assert.equal(listed.exitCode, 0, listed.stderr);
+    const listedCheckpoint = JSON.parse(listed.stdout).checkpoints[0];
+    assert.equal(listedCheckpoint.completed, 'Added parser tests');
+    assert.equal(listedCheckpoint.evidence, 'tests/lib/sdd-overlay.test.mjs');
+    assert.equal(listedCheckpoint.review, 'review.md');
+    assert.equal(listedCheckpoint.risk, 'None');
+    assert.equal(listedCheckpoint.commit_start, 'aaaaaaa');
+    assert.equal(listedCheckpoint.commit_end, 'bbbbbbb');
+  });
+
+  it('rejects save without --next before creating a checkpoint file', () => {
+    const result = runSsf(['checkpoint', 'save', changeDir, '--task', '1.1']);
+    assert.equal(result.exitCode, 2);
+    assert.equal(existsSync(join(changeDir, '.superpowers', 'sdd', 'checkpoints', '1.1.md')), false);
+  });
+
+  it('lists a stale checkpoint as JSON', () => {
+    const save = runSsf(['checkpoint', 'save', changeDir, '--task', '1.1', '--next', 'Run focused tests']);
+    assert.equal(save.exitCode, 0, save.stderr);
+    writeFileSync(join(changeDir, 'tasks.md'), '# Tasks\n\n- [ ] 1.1 Changed task text\n');
+
+    const result = runSsf(['checkpoint', 'list', changeDir, '--json']);
+    assert.equal(result.exitCode, 0, result.stderr);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.ok, true);
+    assert.equal(payload.checkpoints.length, 1);
+    assert.equal(payload.checkpoints[0].task_id, '1.1');
+    assert.equal(payload.checkpoints[0].stale, true);
+  });
+
+  it('rejects an unknown task ID when showing a checkpoint', () => {
+    const result = runSsf(['checkpoint', 'show', changeDir, '9.9']);
+    assert.equal(result.exitCode, 1);
+  });
+});