@xulthekl/team-flow 0.22.4

package/tests/lib/guard-tests-passing.test.mjs

@@ -0,0 +1,112 @@
+// tests/lib/guard-tests-passing.test.mjs
+// Regression for BUG-A: the `executing → closing` transition was unreachable
+// because `test_result` was never written, yet the tests-passing guard required it.
+// Now the guard also accepts `dp_6_result` starting with "pass".
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+const GUARD = join(ROOT, 'scripts', 'guard', 'guard.mjs');
+const CLI = join(ROOT, 'scripts', 'team-flow.mjs');
+
+function makeChangeDir() {
+  const dir = mkdtempSync(join(tmpdir(), 'tf-tests-passing-'));
+  mkdirSync(join(dir, 'specs'), { recursive: true });
+  writeFileSync(join(dir, 'proposal.md'), '# Test\n\n## Why\nTest.\n\n## What Changes\n- Test.\n');
+  writeFileSync(join(dir, 'design.md'), '# Design\n\n## Context\nTest.\n\n## Goals\nTest.\n\n## Decisions\n\n### Decision 1\n- Choice: Test\n- Rationale: Test\n\n## Risks And Trade-Offs\nNone.\n');
+  writeFileSync(join(dir, 'tasks.md'), '# Tasks\n\n- [x] Task 1\n- [x] Task 2\n');
+  writeFileSync(join(dir, 'specs', 'test.md'), '## ADDED Requirements\n\n### Requirement: Test\n\nThe system SHALL test.\n\n#### Scenario: Test\n- **WHEN** test\n- **THEN** test\n');
+  writeFileSync(join(dir, 'execution-contract.md'), '# Execution Contract\n\n## Intent Lock\nTest.\n');
+  initializeGitRepository(dir);
+  return dir;
+}
+
+function runGit(directory, args) {
+  return execFileSync('git', args, { cwd: directory, encoding: 'utf8' }).trim();
+}
+
+function initializeGitRepository(directory) {
+  runGit(directory, ['init', '--quiet']);
+  runGit(directory, ['config', 'user.email', 'tests@example.invalid']);
+  runGit(directory, ['config', 'user.name', 'Guard Tests Passing Test']);
+  runGit(directory, ['add', '--all']);
+  runGit(directory, ['commit', '--quiet', '--message', 'initial closing guard change']);
+  const base = runGit(directory, ['rev-parse', 'HEAD']);
+  writeFileSync(join(directory, 'git-range-marker.txt'), 'second commit\n');
+  runGit(directory, ['add', 'git-range-marker.txt']);
+  runGit(directory, ['commit', '--quiet', '--message', 'second closing guard change']);
+  return { base, head: runGit(directory, ['rev-parse', 'HEAD']) };
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+// Writes a state file in `executing` and runs the guard for executing -> closing.
+// The guard emits the structured result to stdout (--json mode), so capture both
+// stdout and stderr for assertions.
+function runClosingGuard(dir, extraState = '') {
+  try {
+    // `spec_merged: true` is in the base state so the #28 specs-merged gate
+    // passes — these tests isolate the tests-passing dimension only.
+    // (The specs-merged dimension is covered separately in
+    //  tests/lib/guard-specs-merged.test.mjs.)
+    writeFileSync(
+      join(dir, '.team-flow.yaml'),
+      `state: executing\nworkflow: full\nchange_name: test\nspec_merged: true\n${extraState}`,
+    );
+    rmSync(join(dir, '.superpowers'), { recursive: true, force: true });
+    execFileSync('node', [CLI, 'execution', 'recommend', dir,
+      '--wave', 'close:serial:1.1'], { stdio: 'pipe', timeout: 5000 });
+    execFileSync('node', [CLI, 'execution', 'plan', dir, '--mode', 'sdd',
+      '--confirm', '--acknowledge-recommendation', '--reason', 'closing guard regression fixture',
+      '--wave', 'close:serial:1.1'], { stdio: 'pipe', timeout: 5000 });
+    const report = join(dir, '.superpowers', 'sdd', 'reviews', 'close-review.md');
+    mkdirSync(join(dir, '.superpowers', 'sdd', 'reviews'), { recursive: true });
+    writeFileSync(report, 'review passed\n');
+    const base = runGit(dir, ['rev-parse', 'HEAD~1']);
+    const head = runGit(dir, ['rev-parse', 'HEAD']);
+    execFileSync('node', [CLI, 'execution', 'review', dir, '--wave', 'close',
+      '--base', base, '--head', head, '--report', report, '--verdict', 'pass'], { stdio: 'pipe', timeout: 5000 });
+    execFileSync('node', [GUARD, 'check', dir, 'executing', 'closing', '--json'], { stdio: 'pipe', timeout: 5000 });
+    return { ok: true, stderr: '' };
+  } catch (e) {
+    const out = `${e.stdout?.toString() || ''}\n${e.stderr?.toString() || ''}`;
+    return { ok: false, stderr: out || e.message };
+  }
+}
+
+describe('BUG-A: executing -> closing reachable once verification recorded', () => {
+  let dir;
+  before(() => { dir = makeChangeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('SHALL fail when no verification outcome recorded', () => {
+    const r = runClosingGuard(dir);
+    assert.equal(r.ok, false, 'closing must be blocked without a verification result');
+    assert.match(r.stderr, /verification outcome missing/i);
+  });
+
+  it('SHALL pass when dp_6_result starts with "pass" (the release-archivist signal)', () => {
+    const r = runClosingGuard(dir, 'dp_6_result: pass: all green\n');
+    assert.equal(r.ok, true, `closing should be allowed via dp_6_result, got: ${r.stderr || ''}`);
+  });
+
+  it('SHALL pass when test_result is explicitly "pass"', () => {
+    const r = runClosingGuard(dir, 'test_result: pass\n');
+    assert.equal(r.ok, true, `closing should be allowed via test_result, got: ${r.stderr || ''}`);
+  });
+
+  it('SHALL fail when dp_6_result is "fail" (not a pass signal)', () => {
+    const r = runClosingGuard(dir, 'dp_6_result: fail: broken\n');
+    assert.equal(r.ok, false, 'closing must be blocked when verification failed');
+  });
+});

package/tests/lib/guard-transitions.test.mjs

@@ -0,0 +1,262 @@
+// tests/lib/guard-transitions.test.mjs
+// Regression tests for state machine transition guard matrix
+// Covers specs/guard-transitions/spec.md requirements
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+const GUARD = join(ROOT, 'scripts', 'guard', 'guard.mjs');
+
+// All legal transitions (from docs/state-machine.md)
+const ALL_TRANSITIONS = [
+  // Mainline
+  { from: 'exploring', to: 'specifying' },
+  { from: 'specifying', to: 'bridging' },
+  { from: 'bridging', to: 'approved-for-build' },
+  { from: 'approved-for-build', to: 'executing' },
+  { from: 'executing', to: 'closing' },
+  // Fast-path
+  { from: 'exploring', to: 'bridging', workflow: 'hotfix' },
+  { from: 'exploring', to: 'approved-for-build', workflow: 'tweak' },
+  // Rewind
+  { from: 'executing', to: 'specifying' },
+  { from: 'executing', to: 'bridging' },
+  { from: 'approved-for-build', to: 'specifying' },
+  { from: 'approved-for-build', to: 'bridging' },
+  { from: 'specifying', to: 'exploring' },
+  { from: 'bridging', to: 'specifying' },
+  // Debugging round-trip
+  { from: 'executing', to: 'debugging' },
+  { from: 'debugging', to: 'executing' },
+  // Abandon
+  { from: 'exploring', to: 'abandoned' },
+  { from: 'specifying', to: 'abandoned' },
+  { from: 'bridging', to: 'abandoned' },
+  { from: 'approved-for-build', to: 'abandoned' },
+  { from: 'executing', to: 'abandoned' },
+  { from: 'debugging', to: 'abandoned' },
+];
+
+// Illegal transitions (should be rejected)
+const ILLEGAL_TRANSITIONS = [
+  { from: 'exploring', to: 'closing' },
+  { from: 'exploring', to: 'executing' },
+  { from: 'specifying', to: 'executing' },
+  { from: 'specifying', to: 'closing' },
+  { from: 'bridging', to: 'closing' },
+  { from: 'closing', to: 'abandoned' },
+  { from: 'abandoned', to: 'exploring' },
+  { from: 'abandoned', to: 'specifying' },
+];
+
+function makeChangeDir() {
+  const dir = mkdtempSync(join(tmpdir(), 'tf-guard-test-'));
+  mkdirSync(join(dir, 'specs', 'test'), { recursive: true });
+  return dir;
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+function runGuard(from, to, dir, workflow = 'full') {
+  try {
+    // Write a minimal .team-flow.yaml so guard can read state
+    const stateFile = join(dir, '.team-flow.yaml');
+    writeFileSync(stateFile, `state: ${from}\nworkflow: ${workflow}\nchange_name: test\n`);
+
+    // Also need a minimal proposal.md for artifacts-exist check
+    writeFileSync(join(dir, 'proposal.md'), '# Test\n\n## Why\n\nTest change for guard matrix audit.\n\n## What Changes\n\n- Test.\n');
+    writeFileSync(join(dir, 'design.md'), '# Design\n\n## Context\n\nTest.\n\n## Goals\n\nTest.\n\n## Decisions\n\n### Decision 1\n- Choice: Test\n- Rationale: Test\n\n## Risks And Trade-Offs\n\nNone.\n');
+    writeFileSync(join(dir, 'tasks.md'), '# Tasks\n\n- [x] Task 1\n- [x] Task 2\n');
+    writeFileSync(join(dir, 'specs', 'test', 'spec.md'), '## ADDED Requirements\n\n### Requirement: Test\n\nThe system SHALL test.\n\n#### Scenario: Test\n- **WHEN** test\n- **THEN** test\n');
+    writeFileSync(join(dir, 'execution-contract.md'), '# Execution Contract\n\n## Intent Lock\n\nTest.\n');
+
+    const cmd = `node ${GUARD} check "${dir}" ${from} ${to}`;
+    if (workflow !== 'full') {
+      execSync(`${cmd} --workflow ${workflow} --json`, { stdio: 'pipe', timeout: 5000 });
+    } else {
+      execSync(`${cmd} --json`, { stdio: 'pipe', timeout: 5000 });
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, stdout: e.stdout?.toString() || '', stderr: e.stderr?.toString() || e.message };
+  }
+}
+
+function guardOutput(result) {
+  return `${result.stdout || ''}\n${result.stderr || ''}`;
+}
+
+// ─── D1: Guard 检查矩阵完整性 ───
+// Requirement: Guard 检查矩阵完整性
+// Scenario: 主线 transition 全覆盖
+
+describe('Guard transition matrix completeness', () => {
+  let dir;
+  before(() => { dir = makeChangeDir(); });
+  after(() => { cleanup(dir); });
+
+  for (const t of ALL_TRANSITIONS) {
+    const label = `${t.from} → ${t.to}${t.workflow ? ' (' + t.workflow + ')' : ''}`;
+    it(`SHALL define checks for ${label}`, () => {
+      const result = runGuard(t.from, t.to, dir, t.workflow || 'full');
+      // The transition should be handled (either pass or fail with specific reason, but not "unknown transition")
+      if (!result.ok) {
+        const output = guardOutput(result);
+        assert.ok(
+          !output.includes('unknown transition') && !output.includes('Unknown transition'),
+          `Transition ${label} is not defined in guard matrix: ${output}`
+        );
+      }
+    });
+  }
+});
+
+// Requirement: Guard 检查矩阵完整性
+// Scenario: 非法 transition 被拦截
+describe('Illegal transition rejection', () => {
+  let dir;
+  before(() => { dir = makeChangeDir(); });
+  after(() => { cleanup(dir); });
+
+  for (const t of ILLEGAL_TRANSITIONS) {
+    it(`SHALL reject illegal transition ${t.from} → ${t.to}`, () => {
+      const result = runGuard(t.from, t.to, dir);
+      assert.equal(result.ok, false, `Illegal transition ${t.from} → ${t.to} should be rejected`);
+    });
+  }
+});
+
+// Requirement: Guard 脚本错误处理
+// Scenario: guard 脚本异常时报告给用户
+describe('Guard error handling', () => {
+  it('SHALL return non-zero exit when called without arguments', () => {
+    try {
+      execSync(`node ${GUARD} check`, { stdio: 'pipe', timeout: 5000 });
+      assert.fail('Should have thrown');
+    } catch (e) {
+      assert.ok(e.status !== 0, 'Guard should exit non-zero for missing arguments');
+    }
+  });
+
+  it('SHALL output error for nonexistent change directory', () => {
+    try {
+      execSync(`node ${GUARD} check /nonexistent/path exploring specifying`, { stdio: 'pipe', timeout: 5000 });
+      assert.fail('Should have thrown');
+    } catch (e) {
+      assert.ok(e.status !== 0, 'Guard should exit non-zero for nonexistent directory');
+    }
+  });
+});
+
+// ─── D1: Debugging 状态往返 ───
+// Requirement: Debugging 状态往返无副作用
+// Scenario: debugging 返回 executing 后进度保留
+describe('Debugging round-trip', () => {
+  let dir;
+  before(() => { dir = makeChangeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('SHALL allow executing → debugging transition', () => {
+    const result = runGuard('executing', 'debugging', dir);
+    // The transition may fail due to missing execution artifacts, but should NOT be "unknown transition"
+    if (!result.ok) {
+      const output = guardOutput(result);
+      assert.ok(!output.includes('unknown'), `Should not reject with unknown: ${output}`);
+    }
+  });
+
+  it('SHALL allow debugging → executing transition', () => {
+    const result = runGuard('debugging', 'executing', dir);
+    if (!result.ok) {
+      const output = guardOutput(result);
+      assert.ok(!output.includes('unknown'), `Should not reject with unknown: ${output}`);
+    }
+  });
+});
+
+// ─── D1: Terminal state protection ───
+// Requirement: 废弃状态转换禁止
+// Scenario: abandoned 后拒绝所有 transition
+describe('Terminal state protection — abandoned', () => {
+  let dir;
+  before(() => { dir = makeChangeDir(); });
+  after(() => { cleanup(dir); });
+
+  const allTargets = ['exploring', 'specifying', 'bridging', 'approved-for-build', 'executing', 'debugging', 'closing'];
+
+  for (const target of allTargets) {
+    it(`SHALL reject abandoned → ${target}`, () => {
+      const result = runGuard('abandoned', target, dir);
+      assert.equal(result.ok, false, `Abandoned → ${target} must be rejected (terminal state)`);
+    });
+  }
+});
+
+// Scenario: 从 closing 不能进入 abandoned
+describe('Terminal state protection — closing', () => {
+  let dir;
+  before(() => { dir = makeChangeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('SHALL reject closing → abandoned', () => {
+    const result = runGuard('closing', 'abandoned', dir);
+    assert.equal(result.ok, false, 'Closing → abandoned must be rejected (both terminal)');
+  });
+});
+
+// ─── D1: Fast-path validation ───
+// Requirement: Guard 检查矩阵完整性
+// Scenario: fast-path 有降级保护
+describe('Fast-path validation', () => {
+  let dir;
+  before(() => { dir = makeChangeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('SHALL support hotfix fast-path (exploring → bridging)', () => {
+    const result = runGuard('exploring', 'bridging', dir, 'hotfix');
+    // May fail on schema-valid or other checks, but should NOT be "unknown transition"
+    if (!result.ok) {
+      const output = guardOutput(result);
+      assert.ok(!output.includes('unknown'), `Hotfix fast-path should be defined: ${output}`);
+    }
+  });
+
+  it('SHALL support tweak fast-path (exploring → approved-for-build)', () => {
+    const result = runGuard('exploring', 'approved-for-build', dir, 'tweak');
+    if (!result.ok) {
+      const output = guardOutput(result);
+      assert.ok(!output.includes('unknown'), `Tweak fast-path should be defined: ${output}`);
+    }
+  });
+
+  it('SHALL reject hotfix fast-path when workflow is full', () => {
+    const result = runGuard('exploring', 'bridging', dir, 'full');
+    const output = guardOutput(result);
+    assert.equal(result.ok, false, 'exploring -> bridging must be rejected in full workflow');
+    assert.match(output, /workflow-mode|fast-path|hotfix|tweak/i);
+  });
+
+  it('SHALL reject tweak route to bridging', () => {
+    const result = runGuard('exploring', 'bridging', dir, 'tweak');
+    const output = guardOutput(result);
+    assert.equal(result.ok, false, 'tweak should use exploring -> approved-for-build, not bridging');
+    assert.match(output, /workflow-mode|hotfix/i);
+  });
+
+  it('SHALL reject tweak fast-path when workflow is full', () => {
+    const result = runGuard('exploring', 'approved-for-build', dir, 'full');
+    const output = guardOutput(result);
+    assert.equal(result.ok, false, 'exploring -> approved-for-build must be rejected in full workflow');
+    assert.match(output, /workflow-mode|fast-path|tweak/i);
+  });
+});