@xulthekl/team-flow 0.22.4

package/tests/lib/execution-plan.test.mjs

@@ -0,0 +1,474 @@
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  createPlan as createRawPlan, readPlan, recordReview, validatePlan, writePlan,
+} from '../../scripts/lib/execution-plan.mjs';
+import { createRecommendationReceipt, recommendExecutionModes } from '../../scripts/lib/execution-recommendation.mjs';
+import { readState } from '../../scripts/lib/state-loader.mjs';
+
+let changeDir;
+let gitRefs;
+
+beforeEach(() => {
+  changeDir = mkdtempSync(join(tmpdir(), 'execution-plan-'));
+  writeFileSync(join(changeDir, 'tasks.md'), '# Tasks\n\n- [ ] 1.1 First task\n- [ ] 1.2 Second task\n');
+  writeFileSync(join(changeDir, 'execution-contract.md'), '# Execution Contract\n\nCurrent contract.\n');
+  writeFileSync(join(changeDir, '.team-flow.yaml'), 'state: approved-for-build\nworkflow: full\nrevision: 2\n');
+  gitRefs = initializeGitRepository(changeDir);
+});
+
+afterEach(() => {
+  rmSync(changeDir, { recursive: true, force: true });
+});
+
+function writeReviewReport(name, content = 'Review completed without blocking findings.\n') {
+  const reportsDir = join(changeDir, '.superpowers', 'sdd', 'reviews');
+  mkdirSync(reportsDir, { recursive: true });
+  const reportPath = join(reportsDir, name);
+  writeFileSync(reportPath, content);
+  return reportPath;
+}
+
+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', 'Execution Plan Test']);
+  runGit(directory, ['add', '--all']);
+  runGit(directory, ['commit', '--quiet', '--message', 'initial execution plan 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 execution plan change']);
+  return { base, head: runGit(directory, ['rev-parse', 'HEAD']) };
+}
+
+function createPlan(directory, input) {
+  const receipt = input.recommendationReceipt ?? createRecommendationReceipt(directory, input.waves);
+  const recommendation = input.recommendation ?? receipt.recommendation;
+  const followedRecommendation = input.mode === recommendation.recommendation.mode;
+  return createRawPlan(directory, {
+    ...input,
+    source: input.source === 'default' ? 'user-confirmed' : input.source,
+    recommendation,
+    recommendationReceipt: receipt,
+    selection: input.selection ?? {
+      confirmed: true,
+      followed_recommendation: followedRecommendation,
+      acknowledged_non_recommendation: !followedRecommendation,
+    },
+  });
+}
+
+describe('execution plan data contract', () => {
+  it('recommends inline for one small sequential task', () => {
+    const result = recommendExecutionModes({
+      workflow: 'full',
+      taskCount: 1,
+      inlineThreshold: 3,
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+
+    assert.deepEqual(result.available_modes, ['inline', 'batch-inline', 'sdd']);
+    assert.equal(result.recommendation.mode, 'inline');
+    assert.match(result.recommendation.reasons.join('\n'), /single sequential task/i);
+  });
+
+  it('recommends batch-inline for a bounded sequential batch', () => {
+    const result = recommendExecutionModes({
+      workflow: 'hotfix',
+      taskCount: 3,
+      inlineThreshold: 3,
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1', '1.2', '1.3'], depends_on: [] }],
+    });
+
+    assert.equal(result.recommendation.mode, 'batch-inline');
+    assert.match(result.recommendation.reasons.join('\n'), /within.*threshold/i);
+  });
+
+  it('recommends SDD for independent parallel work', () => {
+    const result = recommendExecutionModes({
+      workflow: 'full',
+      taskCount: 2,
+      inlineThreshold: 3,
+      waves: [{ id: 'foundation', strategy: 'parallel', tasks: ['1.1', '1.2'], depends_on: [] }],
+    });
+
+    assert.equal(result.recommendation.mode, 'sdd');
+    assert.match(result.recommendation.reasons.join('\n'), /parallel/i);
+  });
+
+  it('limits tweak recommendations to direct inline execution', () => {
+    const result = recommendExecutionModes({ workflow: 'tweak', taskCount: 2, inlineThreshold: 3, waves: [] });
+
+    assert.deepEqual(result.available_modes, ['inline']);
+    assert.equal(result.recommendation.mode, 'inline');
+  });
+
+  it('creates a current SDD plan with an auditable parallel wave', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd',
+      source: 'default',
+      rationale: 'full workflow default',
+      waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1', '1.2'], depends_on: [] }],
+    });
+
+    writePlan(changeDir, plan);
+    const result = validatePlan(changeDir, readPlan(changeDir));
+
+    assert.equal(result.valid, true, result.failures.join('\n'));
+    assert.equal(result.plan.mode, 'sdd');
+    assert.equal(readState(changeDir).execution_plan_hash, plan.hash);
+  });
+
+  it('preserves a user-confirmed non-recommended selection in the plan hash', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'inline',
+      source: 'user-confirmed',
+      rationale: 'operator accepts the serial execution risk',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1', '1.2'], depends_on: [] }],
+      recommendation: {
+        available_modes: ['inline', 'batch-inline', 'sdd'],
+        recommendation: { mode: 'batch-inline', reasons: ['Two tasks are within the threshold.'] },
+        facts: { workflow: 'full' },
+      },
+      selection: {
+        confirmed: true,
+        followed_recommendation: false,
+        acknowledged_non_recommendation: true,
+      },
+    });
+
+    assert.equal(plan.selection.acknowledged_non_recommendation, true);
+    assert.equal(plan.recommendation.recommendation.mode, 'batch-inline');
+  });
+
+  it('invalidates a legacy full plan without recommendation and confirmation evidence', () => {
+    const plan = createRawPlan(changeDir, {
+      mode: 'sdd',
+      source: 'legacy',
+      rationale: 'legacy execution plan',
+      waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1', '1.2'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+
+    const result = validatePlan(changeDir, readPlan(changeDir));
+
+    assert.equal(result.valid, false);
+    assert.match(result.failures.join('\n'), /recommendation.*required|selection.*required/i);
+  });
+
+  it('invalidates a revision whose recommendation skips the immediately prior plan', () => {
+    const first = createPlan(changeDir, {
+      mode: 'sdd',
+      source: 'user-confirmed',
+      rationale: 'initial execution plan',
+      waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1', '1.2'], depends_on: [] }],
+    });
+    writePlan(changeDir, first);
+    writeFileSync(join(changeDir, '.team-flow.yaml'), readFileSync(join(changeDir, '.team-flow.yaml'), 'utf8')
+      .replace(/^revision:.*$/m, 'revision: 4'));
+    const receipt = createRecommendationReceipt(changeDir, first.waves);
+    const revised = createRawPlan(changeDir, {
+      mode: 'sdd',
+      source: 'user-confirmed-revision',
+      rationale: 'skips an execution plan revision',
+      waves: first.waves,
+      revision: 4,
+      recommendation: receipt.recommendation,
+      recommendationReceipt: receipt,
+      selection: {
+        confirmed: true,
+        followed_recommendation: true,
+        acknowledged_non_recommendation: false,
+      },
+    });
+    writePlan(changeDir, revised);
+
+    const result = validatePlan(changeDir, readPlan(changeDir));
+
+    assert.equal(result.valid, false);
+    assert.match(result.failures.join('\n'), /recommendation receipt.*prior|recommendation.*revision/i);
+  });
+
+  it('rejects parallel waves with self and unknown dependencies', () => {
+    assert.throws(() => createPlan(changeDir, {
+      mode: 'sdd',
+      source: 'default',
+      rationale: 'invalid dependencies',
+      waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1'], depends_on: ['wave-1'] }],
+    }), /cannot depend on itself/);
+
+    assert.throws(() => createPlan(changeDir, {
+      mode: 'sdd',
+      source: 'default',
+      rationale: 'invalid dependencies',
+      waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1'], depends_on: ['missing'] }],
+    }), /unknown wave/);
+  });
+
+  it('rejects dependency cycles and duplicate task IDs in any wave', () => {
+    assert.throws(() => createPlan(changeDir, {
+      mode: 'sdd',
+      source: 'default',
+      rationale: 'cyclic dependencies',
+      waves: [
+        { id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: ['wave-2'] },
+        { id: 'wave-2', strategy: 'serial', tasks: ['1.2'], depends_on: ['wave-1'] },
+      ],
+    }), /dependency cycle/);
+
+    assert.throws(() => createPlan(changeDir, {
+      mode: 'sdd',
+      source: 'default',
+      rationale: 'duplicate parallel task',
+      waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1', '1.1'], depends_on: [] }],
+    }), /duplicate tasks/);
+
+    assert.throws(() => createPlan(changeDir, {
+      mode: 'sdd',
+      source: 'default',
+      rationale: 'duplicate task across waves',
+      waves: [
+        { id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] },
+        { id: 'wave-2', strategy: 'parallel', tasks: ['1.1', '1.2'], depends_on: [] },
+      ],
+    }), /duplicate task.*1\.1/i);
+  });
+
+  it('changes the plan hash when plan content changes', () => {
+    const first = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'first rationale',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+    const second = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'second rationale',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+
+    assert.notEqual(first.hash, second.hash);
+  });
+
+  it('marks a plan stale after its frozen artifacts change', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'freeze current artifacts',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+    writeFileSync(join(changeDir, 'tasks.md'), '# Tasks\n\n- [ ] 1.1 Changed task\n');
+
+    const result = validatePlan(changeDir, readPlan(changeDir));
+
+    assert.equal(result.valid, false);
+    assert.ok(result.failures.includes('execution plan is stale: artifacts hash mismatch'));
+  });
+
+  it('marks a plan stale after its frozen contract changes', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'freeze current contract',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+    writeFileSync(join(changeDir, 'execution-contract.md'), '# Execution Contract\n\nChanged contract.\n');
+
+    const result = validatePlan(changeDir, readPlan(changeDir));
+
+    assert.equal(result.valid, false);
+    assert.ok(result.failures.includes('execution plan is stale: contract hash mismatch'));
+  });
+
+  it('marks a plan stale when the state revision changes', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'freeze current revision',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+    writeFileSync(join(changeDir, '.team-flow.yaml'), [
+      'state: approved-for-build',
+      'workflow: full',
+      'revision: 3',
+      `execution_plan_hash: ${plan.hash}`,
+      '',
+    ].join('\n'));
+
+    const result = validatePlan(changeDir, readPlan(changeDir));
+
+    assert.equal(result.valid, false);
+    assert.ok(result.failures.includes('execution plan revision does not match state'));
+  });
+
+  it('rejects a persisted plan when its state plan revision is deleted or differs', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'freeze persisted plan revision',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+
+    const stateVariants = [
+      [
+        'state: approved-for-build',
+        'workflow: full',
+        'revision: 2',
+        `execution_plan_hash: ${plan.hash}`,
+      ],
+      [
+        'state: approved-for-build',
+        'workflow: full',
+        'revision: 2',
+        `execution_plan_hash: ${plan.hash}`,
+        'execution_plan_revision: null',
+      ],
+      [
+        'state: approved-for-build',
+        'workflow: full',
+        'revision: 2',
+        `execution_plan_hash: ${plan.hash}`,
+        'execution_plan_revision:',
+      ],
+      [
+        'state: approved-for-build',
+        'workflow: full',
+        'revision: 2',
+        `execution_plan_hash: ${plan.hash}`,
+        'execution_plan_revision: 3',
+      ],
+    ];
+
+    for (const state of stateVariants) {
+      writeFileSync(join(changeDir, '.team-flow.yaml'), `${state.join('\n')}\n`);
+      const result = validatePlan(changeDir, readPlan(changeDir));
+      assert.equal(result.valid, false);
+      assert.ok(result.failures.includes('execution plan revision does not match state'));
+    }
+  });
+
+  it('records review receipts only for known waves', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'review gate',
+      waves: [{ id: 'wave-1', strategy: 'parallel', tasks: ['1.1', '1.2'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+
+    const reportPath = writeReviewReport('wave-1.md');
+    const receipt = recordReview(changeDir, 'wave-1', {
+      status: 'pass', base: gitRefs.base, head: gitRefs.head, report: reportPath,
+    });
+
+    assert.equal(receipt.status, 'pass');
+    assert.ok(receipt.recorded_at);
+    const reviewsDir = join(changeDir, '.superpowers', 'sdd', 'reviews');
+    const receiptFiles = readdirSync(reviewsDir).filter(fileName => fileName.endsWith('.json'));
+    assert.equal(receiptFiles.length, 1);
+    assert.deepEqual(
+      JSON.parse(readFileSync(join(reviewsDir, receiptFiles[0]), 'utf8')),
+      receipt,
+    );
+    assert.throws(
+      () => recordReview(changeDir, 'unknown-wave', {
+        status: 'pass', base: gitRefs.base, head: gitRefs.head, report: reportPath,
+      }),
+      /unknown wave/,
+    );
+  });
+
+  it('persists receipts independently for wave IDs with encoded-name collisions', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'review receipt naming',
+      waves: [
+        { id: 'a%', strategy: 'serial', tasks: ['1.1'], depends_on: [] },
+        { id: 'a_25', strategy: 'serial', tasks: ['1.2'], depends_on: ['a%'] },
+      ],
+    });
+    writePlan(changeDir, plan);
+
+    const percentReport = writeReviewReport('percent.md', 'Percent wave passed.\n');
+    const underscoreReport = writeReviewReport('underscore.md', 'Underscore wave failed.\n');
+    recordReview(changeDir, 'a%', {
+      status: 'pass', base: gitRefs.base, head: gitRefs.head, report: percentReport,
+    });
+    recordReview(changeDir, 'a_25', {
+      status: 'fail', base: gitRefs.base, head: gitRefs.head, report: underscoreReport,
+    });
+
+    const reviewsDir = join(changeDir, '.superpowers', 'sdd', 'reviews');
+    const receipts = readdirSync(reviewsDir)
+      .filter(fileName => fileName.endsWith('.json'))
+      .sort()
+      .map(fileName => JSON.parse(readFileSync(join(reviewsDir, fileName), 'utf8')));
+    assert.equal(receipts.length, 2);
+    assert.ok(receipts.some(receipt => receipt.report === join('.superpowers', 'sdd', 'reviews', 'percent.md')));
+    assert.ok(receipts.some(receipt => receipt.report === join('.superpowers', 'sdd', 'reviews', 'underscore.md')));
+  });
+
+  it('rejects missing, non-file, empty, and symbolic-link report evidence before writing a receipt', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'review evidence must be durable',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+
+    const reportsDir = join(changeDir, '.superpowers', 'sdd', 'reviews');
+    mkdirSync(reportsDir, { recursive: true });
+    const emptyReport = join(reportsDir, 'empty.md');
+    const directoryReport = join(reportsDir, 'directory');
+    const validReport = writeReviewReport('valid.md');
+    const symlinkReport = join(reportsDir, 'symlink.md');
+    writeFileSync(emptyReport, '');
+    mkdirSync(directoryReport);
+    symlinkSync(validReport, symlinkReport);
+
+    for (const report of [
+      join(reportsDir, 'missing.md'),
+      directoryReport,
+      emptyReport,
+      symlinkReport,
+    ]) {
+      assert.throws(() => recordReview(changeDir, 'wave-1', {
+        status: 'pass', base: gitRefs.base, head: gitRefs.head, report,
+      }), /report evidence|review report/i);
+      assert.equal(lstatSync(join(reportsDir, 'valid.md')).isFile(), true);
+      assert.equal(readdirSync(reportsDir).filter(fileName => fileName.endsWith('.json')).length, 0);
+    }
+  });
+
+  it('preserves a legitimate review report path in the receipt', () => {
+    const plan = createPlan(changeDir, {
+      mode: 'sdd', source: 'default', rationale: 'retain report path for audit',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: [] }],
+    });
+    writePlan(changeDir, plan);
+    const reportPath = writeReviewReport('audit.md');
+
+    const receipt = recordReview(changeDir, 'wave-1', {
+      status: 'pass', base: gitRefs.base, head: gitRefs.head, report: reportPath,
+    });
+
+    assert.equal(receipt.report, join('.superpowers', 'sdd', 'reviews', 'audit.md'));
+  });
+
+  it('returns validation failures instead of throwing for malformed plans', () => {
+    const result = validatePlan(changeDir, { mode: 'sdd', waves: 'not-an-array' });
+
+    assert.equal(result.valid, false);
+    assert.ok(result.failures.length > 0);
+  });
+
+  it('returns validation failures for malformed dependency data', () => {
+    const result = validatePlan(changeDir, {
+      mode: 'sdd',
+      source: 'default',
+      rationale: 'malformed dependency input',
+      waves: [{ id: 'wave-1', strategy: 'serial', tasks: ['1.1'], depends_on: {} }],
+    });
+
+    assert.equal(result.valid, false);
+    assert.ok(result.failures.includes('wave 1 depends_on must be an array'));
+  });
+});

package/tests/lib/guard-specs-merged.test.mjs

@@ -0,0 +1,108 @@
+// tests/lib/guard-specs-merged.test.mjs
+// Regression for #28: `executing → closing` must be blocked while delta specs
+// exist but spec-merger has not run (spec_merged not recorded).
+
+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(withDelta) {
+  const dir = mkdtempSync(join(tmpdir(), 'tf-specs-merged-'));
+  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, 'execution-contract.md'), '# Execution Contract\n\n## Intent Lock\nTest.\n');
+  const specsContent = withDelta
+    ? '## ADDED Requirements\n\n### Requirement: New\n\nThe system SHALL do new.\n\n#### Scenario: New\n- **WHEN** x\n- **THEN** y\n'
+    : '## Requirements\n\n### Requirement: Existing\n\nThe system SHALL exist.\n\n#### Scenario: Existing\n- **WHEN** a\n- **THEN** b\n';
+  writeFileSync(join(dir, 'specs', 'test.md'), specsContent);
+  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 Specs Merged 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 });
+}
+
+function runClosingGuard(dir, extraState = '') {
+  try {
+    rmSync(join(dir, '.superpowers'), { recursive: true, force: true });
+    writeFileSync(
+      join(dir, '.team-flow.yaml'),
+      `state: executing\nworkflow: full\nchange_name: test\ndp_6_result: pass: ok\n${extraState}`,
+    );
+    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 = execFileSync('git', ['rev-parse', 'HEAD~1'], { cwd: dir, encoding: 'utf8' }).trim();
+    const head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf8' }).trim();
+    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, out: '' };
+  } catch (e) {
+    const out = `${e.stdout?.toString() || ''}\n${e.stderr?.toString() || ''}`;
+    return { ok: false, out: out || e.message };
+  }
+}
+
+describe('BUG/#28: spec-merger gate before closing', () => {
+  let noDeltaDir, deltaDir;
+  before(() => {
+    noDeltaDir = makeChangeDir(false);
+    deltaDir = makeChangeDir(true);
+  });
+  after(() => {
+    cleanup(noDeltaDir);
+    cleanup(deltaDir);
+  });
+
+  it('SHALL allow closing when there are no delta specs', () => {
+    const r = runClosingGuard(noDeltaDir);
+    assert.equal(r.ok, true, `closing should be allowed without delta specs, got: ${r.out}`);
+  });
+
+  it('SHALL block closing when delta specs exist but spec-merger has not run', () => {
+    const r = runClosingGuard(deltaDir);
+    assert.equal(r.ok, false, 'closing must be blocked until delta specs are merged');
+    assert.match(r.out, /spec-merger|spec_merged|delta specs/i);
+  });
+
+  it('SHALL allow closing when spec_merged is recorded', () => {
+    const r = runClosingGuard(deltaDir, 'spec_merged: true\n');
+    assert.equal(r.ok, true, `closing should be allowed once spec_merged=true, got: ${r.out}`);
+  });
+});