nubos-pilot 0.1.0

package/lib/phase.test.cjs

@@ -0,0 +1,189 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const phase = require('./phase.cjs');
+const { NubosPilotError } = require('./core.cjs');
+
+function makeSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-phase-'));
+  fs.mkdirSync(path.join(dir, '.nubos-pilot', 'phases'), { recursive: true });
+  return dir;
+}
+
+function rmSandbox(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+}
+
+function withSandbox(fn) {
+  const dir = makeSandbox();
+  try { return fn(dir); } finally { rmSandbox(dir); }
+}
+
+test('PH-1 paddedPhase(3) === "03"', () => {
+  assert.equal(phase.paddedPhase(3), '03');
+});
+
+test('PH-2 paddedPhase("3") === "03"', () => {
+  assert.equal(phase.paddedPhase('3'), '03');
+});
+
+test('PH-3 paddedPhase(10) === "10"', () => {
+  assert.equal(phase.paddedPhase(10), '10');
+});
+
+test('PH-4 paddedPhase("2.1") === "02.1"', () => {
+  assert.equal(phase.paddedPhase('2.1'), '02.1');
+});
+
+test('PH-5 paddedPhase("12.3") === "12.3"', () => {
+  assert.equal(phase.paddedPhase('12.3'), '12.3');
+});
+
+test('PH-6 paddedPhase("abc") throws NubosPilotError(phase-not-found)', () => {
+  try {
+    phase.paddedPhase('abc');
+    assert.fail('expected throw');
+  } catch (err) {
+    assert.ok(err instanceof NubosPilotError, 'expected NubosPilotError');
+    assert.equal(err.code, 'phase-not-found');
+    assert.deepEqual(err.details, { got: 'abc' });
+  }
+});
+
+test('PH-7 paddedPhase(0) === "00"', () => {
+  assert.equal(phase.paddedPhase(0), '00');
+});
+
+test('PH-8 phaseSlug("Core Lib — Parsers & Dispatcher") === "core-lib-parsers-dispatcher"', () => {
+  assert.equal(phase.phaseSlug('Core Lib — Parsers & Dispatcher'), 'core-lib-parsers-dispatcher');
+});
+
+test('PH-9 phaseSlug("AI/ML") === "ai-ml"', () => {
+  assert.equal(phase.phaseSlug('AI/ML'), 'ai-ml');
+});
+
+test('PH-10 phaseSlug("   spaced   ") === "spaced"', () => {
+  assert.equal(phase.phaseSlug('   spaced   '), 'spaced');
+});
+
+test('PH-11 phaseSlug("123-NUMBERS") === "123-numbers"', () => {
+  assert.equal(phase.phaseSlug('123-NUMBERS'), '123-numbers');
+});
+
+test('PH-12 findPhaseDir(3, sandbox) returns absolute path ending in phases/03-core-lib', () => {
+  withSandbox((sandbox) => {
+    fs.mkdirSync(path.join(sandbox, '.nubos-pilot', 'phases', '03-core-lib'), { recursive: true });
+    const result = phase.findPhaseDir(3, sandbox);
+    assert.ok(result, 'expected non-null');
+    assert.ok(path.isAbsolute(result), 'expected absolute path');
+    assert.ok(result.endsWith(path.join('phases', '03-core-lib')), `expected suffix phases/03-core-lib, got ${result}`);
+  });
+});
+
+test('PH-13 findPhaseDir(999, sandbox) returns null (no throw)', () => {
+  withSandbox((sandbox) => {
+    assert.equal(phase.findPhaseDir(999, sandbox), null);
+  });
+});
+
+test('PH-14 findPhaseDir when phases/ dir absent returns null (not throw)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-phase-nop-'));
+  fs.mkdirSync(path.join(dir, '.nubos-pilot'), { recursive: true });
+  try {
+    assert.equal(phase.findPhaseDir(3, dir), null);
+  } finally {
+    rmSandbox(dir);
+  }
+});
+
+test('PH-15 findPhaseDir("2.1") finds 02.1-hotfix', () => {
+  withSandbox((sandbox) => {
+    fs.mkdirSync(path.join(sandbox, '.nubos-pilot', 'phases', '02.1-hotfix'), { recursive: true });
+    const result = phase.findPhaseDir('2.1', sandbox);
+    assert.ok(result);
+    assert.ok(result.endsWith(path.join('phases', '02.1-hotfix')), `got ${result}`);
+  });
+});
+
+test('PH-16 findPhaseDir prefers longer slug-bearing match over bare padded', () => {
+  withSandbox((sandbox) => {
+    const phases = path.join(sandbox, '.nubos-pilot', 'phases');
+    fs.mkdirSync(path.join(phases, '03'), { recursive: true });
+    fs.mkdirSync(path.join(phases, '03-full-slug'), { recursive: true });
+    const result = phase.findPhaseDir(3, sandbox);
+    assert.ok(result);
+    assert.ok(
+      result.endsWith(path.join('phases', '03-full-slug')),
+      `expected longer-slug winner, got ${result}`
+    );
+  });
+});
+
+test('PH-17 createPhaseDir creates phases/04-base-workflows/', () => {
+  withSandbox((sandbox) => {
+    const result = phase.createPhaseDir(4, 'base-workflows', sandbox);
+    assert.ok(path.isAbsolute(result));
+    assert.ok(result.endsWith(path.join('phases', '04-base-workflows')), `got ${result}`);
+    assert.ok(fs.statSync(result).isDirectory());
+  });
+});
+
+test('PH-18 createPhaseDir is idempotent for same (n, slug)', () => {
+  withSandbox((sandbox) => {
+    const a = phase.createPhaseDir(4, 'base-workflows', sandbox);
+    const b = phase.createPhaseDir(4, 'base-workflows', sandbox);
+    assert.equal(a, b);
+  });
+});
+
+test('PH-19 createPhaseDir throws phase-slug-mismatch on conflict', () => {
+  withSandbox((sandbox) => {
+    fs.mkdirSync(
+      path.join(sandbox, '.nubos-pilot', 'phases', '04-something-else'),
+      { recursive: true }
+    );
+    try {
+      phase.createPhaseDir(4, 'base-workflows', sandbox);
+      assert.fail('expected throw');
+    } catch (err) {
+      assert.ok(err instanceof NubosPilotError, 'expected NubosPilotError');
+      assert.equal(err.code, 'phase-slug-mismatch');
+      assert.equal(err.details.existing_slug, 'something-else');
+      assert.equal(err.details.expected_slug, 'base-workflows');
+    }
+  });
+});
+
+test('PH-20 createPhaseDir leaves no sidecar lock file behind', () => {
+  withSandbox((sandbox) => {
+    phase.createPhaseDir(4, 'base-workflows', sandbox);
+    const entries = fs.readdirSync(path.join(sandbox, '.nubos-pilot', 'phases'));
+    const locks = entries.filter((n) => n.includes('.lock') || n.startsWith('.phase-create'));
+    assert.deepEqual(locks, [], `stale lock artefacts: ${locks.join(',')}`);
+  });
+});
+
+test('PH-21 integration: repo-style phase tree resolves 03-core-lib-parsers-dispatcher-capability-layer', () => {
+
+  
+
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-phase-integ-'));
+  try {
+    fs.mkdirSync(
+      path.join(dir, '.nubos-pilot', 'phases', '03-core-lib-parsers-dispatcher-capability-layer'),
+      { recursive: true }
+    );
+    const result = phase.findPhaseDir(3, dir);
+    assert.ok(result);
+    assert.ok(
+      result.endsWith(path.join('phases', '03-core-lib-parsers-dispatcher-capability-layer')),
+      `got ${result}`
+    );
+  } finally {
+    rmSandbox(dir);
+  }
+});

package/lib/plan-checker-contract.test.cjs

@@ -0,0 +1,72 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { loadAgent, FORBIDDEN } = require('./agents.cjs');
+
+const AGENT_PATH = path.join(__dirname, '..', 'agents', 'np-plan-checker.md');
+const BODY = fs.readFileSync(AGENT_PATH, 'utf-8');
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-pc-contract-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'agents', 'np-plan-checker.md'), BODY, 'utf-8');
+  return root;
+}
+
+const CATEGORIES = [
+  'missing-success-criterion',
+  'non-atomic-task',
+  'unbounded-scope',
+  'broken-dependency',
+  'cyclic-dependency',
+  'fake-promotion-trigger',
+  'missing-coverage-annotation',
+  'bare-askuser-call',
+  'hook-field-present',
+  'forbidden-agent-field',
+];
+
+const REQUIRED_H2 = [
+  '## Role',
+  '## Inputs',
+  '## Review Dimensions',
+  '## Verdict Format',
+  '## Severity Rubric',
+  '## Forbidden Outputs',
+  '## Semantic Blocks',
+];
+
+test('PC-1: loadAgent(plan-checker) returns tier=opus and name=plan-checker', () => {
+  const sb = makeSandbox();
+  try {
+    const fm = loadAgent('np-plan-checker', sb);
+    assert.equal(fm.tier, 'opus');
+    assert.equal(fm.name, 'np-plan-checker');
+  } finally {
+    fs.rmSync(sb, { recursive: true, force: true });
+  }
+});
+
+test('PC-2: body contains all 10 canonical finding-category identifiers', () => {
+  for (const c of CATEGORIES) {
+    assert.ok(BODY.includes(c), 'missing canonical category: ' + c);
+  }
+});
+
+test('PC-4: body contains all 7 required H2 section headers verbatim', () => {
+  for (const h of REQUIRED_H2) {
+    assert.ok(BODY.includes(h), 'missing required H2 header: ' + h);
+  }
+});
+
+test('PC-5: frontmatter contains no FORBIDDEN key (model/model_profile/hooks)', () => {
+  const fmBlock = BODY.split(/^---$/m)[1] || '';
+  for (const f of FORBIDDEN) {
+    const re = new RegExp('^' + f + ':', 'm');
+    assert.equal(re.test(fmBlock), false, 'frontmatter contains forbidden field: ' + f);
+  }
+});

package/lib/plan-diff.cjs

@@ -0,0 +1,173 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { NubosPilotError, findProjectRoot, projectStateDir, atomicWriteFileSync } = require('./core.cjs');
+const { TASK_ID_RE } = require('./tasks.cjs');
+const { gitShowSafe, gitDiffNoColor, checkoutFromHead } = require('./git.cjs');
+
+const SEMANTIC_HEADER = '── Semantic diff (task-level) ──────────────────────────────';
+const RAW_HEADER      = '── Raw git diff (full text) ────────────────────────────────';
+
+const PHASE_RE = /^\d+(\.\d+)?$/;
+const PLAN_ID_RE = /^\d{2}(\.\d+)?-\d{2}$/;
+
+function _scanTasks(body) {
+  const out = new Map();
+  const re = /<task\b[^>]*?tier=["']([^"']+)["'][^>]*?id=["']([^"']+)["']|<task\b[^>]*?id=["']([^"']+)["'][^>]*?tier=["']([^"']+)["']/g;
+  for (const m of String(body).matchAll(re)) {
+    const id = m[2] || m[3];
+    const tier = m[1] || m[4];
+    if (id && TASK_ID_RE.test(id)) {
+      out.set(id, { id, tier: tier || 'unknown' });
+    }
+  }
+  return out;
+}
+
+function semanticTaskDiff(priorBody, currentBody) {
+  const prior = _scanTasks(priorBody || '');
+  const cur = _scanTasks(currentBody || '');
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [id, rec] of cur) {
+    if (!prior.has(id)) {
+      added.push(rec);
+    } else {
+      const p = prior.get(id);
+      if (p.tier !== rec.tier && p.tier !== 'unknown' && rec.tier !== 'unknown') {
+        changed.push({ id, field: 'tier', from: p.tier, to: rec.tier });
+      }
+    }
+  }
+  for (const [id, rec] of prior) {
+    if (!cur.has(id)) removed.push(rec);
+  }
+  return { added, removed, changed };
+}
+
+function _renderSemantic(diff) {
+  const lines = [];
+  for (const a of diff.added) lines.push('+ ' + a.id + ': tier=' + a.tier);
+  for (const c of diff.changed) lines.push('~ ' + c.id + ': ' + c.field + '=' + c.from + '→' + c.to);
+  for (const r of diff.removed) lines.push('- ' + r.id);
+  return lines.length ? lines.join('\n') : '(no task-level changes detected)';
+}
+
+function _validatePhaseArg(phase) {
+  if (typeof phase !== 'string' || !PHASE_RE.test(phase)) {
+    throw new NubosPilotError(
+      'plan-diff-invalid-phase',
+      'Invalid phase argument: ' + String(phase),
+      { phase: String(phase) },
+    );
+  }
+}
+
+function _validatePlanId(planId) {
+  if (typeof planId !== 'string' || !PLAN_ID_RE.test(planId)) {
+    throw new NubosPilotError(
+      'plan-diff-invalid-plan-id',
+      'Invalid plan-id argument: ' + String(planId),
+      { planId: String(planId) },
+    );
+  }
+}
+
+function _planPathForIds(phase, planId, cwd) {
+  _validatePhaseArg(phase);
+  _validatePlanId(planId);
+  let root;
+  try {
+    root = findProjectRoot(cwd || process.cwd());
+  } catch {
+    root = path.resolve(cwd || process.cwd());
+  }
+  const phasesRoot = path.join(projectStateDir(root), 'phases');
+  const padded = String(phase).padStart(2, '0');
+  let phaseDirName = null;
+  try {
+    const entries = fs.readdirSync(phasesRoot, { withFileTypes: true });
+    const matches = entries
+      .filter((e) => e.isDirectory())
+      .filter((e) => e.name === padded || e.name.startsWith(padded + '-'))
+      .map((e) => e.name)
+      .sort((a, b) => b.length - a.length);
+    if (matches.length > 0) phaseDirName = matches[0];
+  } catch {
+    phaseDirName = null;
+  }
+  if (!phaseDirName) {
+    throw new NubosPilotError(
+      'plan-diff-phase-not-found',
+      'No phase directory starting with ' + padded + ' under ' + phasesRoot,
+      { phase, phasesRoot },
+    );
+  }
+  const phaseDir = path.join(phasesRoot, phaseDirName);
+  const planFile = planId + '-PLAN.md';
+  const relative = path.relative(root, path.join(phaseDir, planFile));
+  return {
+    absolute: path.join(phaseDir, planFile),
+    relative,
+    phaseDir,
+    phaseDirName,
+    root,
+    padded,
+  };
+}
+
+function renderTwoPartDiff({ phase, planId, cwd }) {
+  const resolved = _planPathForIds(phase, planId, cwd);
+  const prev = process.cwd();
+  process.chdir(resolved.root);
+  try {
+    const prior = gitShowSafe('HEAD', resolved.relative);
+    if (prior === null) return { hasPrior: false };
+    const current = fs.existsSync(resolved.absolute)
+      ? fs.readFileSync(resolved.absolute, 'utf-8')
+      : '';
+    const diff = semanticTaskDiff(prior, current);
+    const semantic = _renderSemantic(diff);
+    const raw = gitDiffNoColor('HEAD', resolved.relative);
+    const combined = [SEMANTIC_HEADER, '', semantic, '', RAW_HEADER, '', raw].join('\n');
+    return { hasPrior: true, semantic, raw, combined };
+  } finally {
+    process.chdir(prev);
+  }
+}
+
+function restoreFromHead({ phase, planId, cwd }) {
+  const resolved = _planPathForIds(phase, planId, cwd);
+  checkoutFromHead([resolved.relative], { cwd: resolved.root });
+}
+
+function archiveRejected({ phase, planId, reason, cwd }) {
+  const resolved = _planPathForIds(phase, planId, cwd);
+  const body = fs.existsSync(resolved.absolute)
+    ? fs.readFileSync(resolved.absolute, 'utf-8')
+    : '';
+  const iso = new Date().toISOString();
+  const safeIso = iso.replace(/:/g, '-');
+  const archiveName = resolved.padded + '-' + planId + '-PLAN-DIFF-' + safeIso + '.md';
+  const archivePath = path.join(resolved.phaseDir, archiveName);
+  const content = [
+    '---',
+    'rejected_at: ' + iso,
+    'reason: ' + JSON.stringify(reason == null ? '' : String(reason)),
+    '---',
+    '',
+    body,
+  ].join('\n');
+  atomicWriteFileSync(archivePath, content);
+  restoreFromHead({ phase, planId, cwd });
+  return archivePath;
+}
+
+module.exports = {
+  semanticTaskDiff,
+  renderTwoPartDiff,
+  archiveRejected,
+  restoreFromHead,
+  SEMANTIC_HEADER,
+  RAW_HEADER,
+};

package/lib/plan-diff.test.cjs

@@ -0,0 +1,217 @@
+const { test, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+
+const pd = require('./plan-diff.cjs');
+
+const _repos = [];
+
+function makeRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-plan-diff-'));
+  execFileSync('git', ['init', '-q', '-b', 'main', root], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos-pilot.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'chore: init'], { stdio: 'pipe' });
+  _repos.push(root);
+  return root;
+}
+
+function seedPlanCommit(root, phase, phaseSlug, planId, body) {
+  const padded = String(phase).padStart(2, '0');
+  const phaseDir = path.join(root, '.nubos-pilot', 'phases', padded + '-' + phaseSlug);
+  fs.mkdirSync(phaseDir, { recursive: true });
+  const rel = path.join('.nubos-pilot', 'phases', padded + '-' + phaseSlug, planId + '-PLAN.md');
+  const abs = path.join(root, rel);
+  fs.writeFileSync(abs, body, 'utf-8');
+  execFileSync('git', ['-C', root, 'add', '--', rel], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'commit', '-q', '-m', 'docs(' + planId + '): seed PLAN.md'], { stdio: 'pipe' });
+  return { abs, rel, phaseDir };
+}
+
+function planBody(tasks) {
+  const lines = ['---', 'plan: 1', 'phase: 9', 'requirements: [R-05]', '---', '', '## Tasks', ''];
+  for (const t of tasks) {
+    lines.push('<task type="auto" tier="' + t.tier + '" id="' + t.id + '">');
+    lines.push('body');
+    lines.push('</task>');
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function inRepo(root, fn) {
+  const prev = process.cwd();
+  process.chdir(root);
+  try { return fn(); } finally { process.chdir(prev); }
+}
+
+after(() => {
+  while (_repos.length) {
+    const r = _repos.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('PD-1: added task (new id in current, not in prior) is reported', () => {
+  const prior = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const current = planBody([
+    { id: '09-01-T01', tier: 'opus' },
+    { id: '09-01-T04', tier: 'haiku' },
+  ]);
+  const diff = pd.semanticTaskDiff(prior, current);
+  assert.deepEqual(diff.added, [{ id: '09-01-T04', tier: 'haiku' }]);
+  assert.deepEqual(diff.removed, []);
+  assert.deepEqual(diff.changed, []);
+});
+
+test('PD-2: removed task (id in prior but not current) is reported', () => {
+  const prior = planBody([
+    { id: '09-01-T01', tier: 'opus' },
+    { id: '09-01-T03', tier: 'haiku' },
+  ]);
+  const current = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const diff = pd.semanticTaskDiff(prior, current);
+  assert.deepEqual(diff.added, []);
+  assert.equal(diff.removed.length, 1);
+  assert.equal(diff.removed[0].id, '09-01-T03');
+  assert.deepEqual(diff.changed, []);
+});
+
+test('PD-3: tier change on same id is reported as changed', () => {
+  const prior = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const current = planBody([{ id: '09-01-T01', tier: 'sonnet' }]);
+  const diff = pd.semanticTaskDiff(prior, current);
+  assert.deepEqual(diff.added, []);
+  assert.deepEqual(diff.removed, []);
+  assert.deepEqual(diff.changed, [{ id: '09-01-T01', field: 'tier', from: 'opus', to: 'sonnet' }]);
+});
+
+test('PD-4: non-canonical task-id formats are ignored (Pitfall 4)', () => {
+  const prior = '<task tier="opus" id="T-09-01-04">x</task>\n<task tier="opus" id="T01">y</task>\n';
+  const current = '<task tier="opus" id="T-09-01-04">x</task>\n<task tier="haiku" id="09-01-T05">z</task>\n';
+  const diff = pd.semanticTaskDiff(prior, current);
+  assert.deepEqual(diff.added, [{ id: '09-01-T05', tier: 'haiku' }]);
+  assert.deepEqual(diff.removed, []);
+  assert.deepEqual(diff.changed, []);
+});
+
+test('PD-5: renderTwoPartDiff returns hasPrior=true with combined Semantic + Raw sections', () => {
+  const root = makeRepo();
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', planBody([
+    { id: '09-01-T01', tier: 'opus' },
+  ]));
+  const modified = planBody([
+    { id: '09-01-T01', tier: 'opus' },
+    { id: '09-01-T02', tier: 'sonnet' },
+  ]);
+  fs.writeFileSync(abs, modified, 'utf-8');
+  const r = pd.renderTwoPartDiff({ phase: '09', planId: '09-01', cwd: root });
+  assert.equal(r.hasPrior, true);
+  assert.ok(r.semantic.includes('09-01-T02'));
+  assert.ok(r.raw.startsWith('diff --git'));
+  assert.ok(r.combined.includes('Semantic diff'));
+  assert.ok(r.combined.includes('Raw git diff'));
+});
+
+test('PD-6: renderTwoPartDiff returns {hasPrior:false} when HEAD has no prior PLAN.md', () => {
+  const root = makeRepo();
+  const padded = '09';
+  const phaseDir = path.join(root, '.nubos-pilot', 'phases', padded + '-feature-set');
+  fs.mkdirSync(phaseDir, { recursive: true });
+  fs.writeFileSync(path.join(phaseDir, '09-01-PLAN.md'), planBody([{ id: '09-01-T01', tier: 'opus' }]), 'utf-8');
+  const r = pd.renderTwoPartDiff({ phase: '09', planId: '09-01', cwd: root });
+  assert.equal(r.hasPrior, false);
+  assert.equal(r.semantic, undefined);
+});
+
+test('PD-7: archiveRejected writes PLAN-DIFF-{ISO}.md with frontmatter + restores HEAD', () => {
+  const root = makeRepo();
+  const priorBody = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const { abs, phaseDir } = seedPlanCommit(root, '09', 'feature-set', '09-01', priorBody);
+  const newBody = planBody([
+    { id: '09-01-T01', tier: 'opus' },
+    { id: '09-01-T02', tier: 'sonnet' },
+  ]);
+  fs.writeFileSync(abs, newBody, 'utf-8');
+  const archivePath = pd.archiveRejected({ phase: '09', planId: '09-01', reason: 'design flaw', cwd: root });
+  assert.ok(fs.existsSync(archivePath));
+  const name = path.basename(archivePath);
+  assert.match(name, /^09-09-01-PLAN-DIFF-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}\.\d{3}Z\.md$/);
+  const archived = fs.readFileSync(archivePath, 'utf-8');
+  assert.match(archived, /^---\n/);
+  assert.ok(archived.includes('rejected_at:'));
+  assert.ok(archived.includes('reason: "design flaw"'));
+  assert.ok(archived.includes('09-01-T02'), 'archive must include rejected body');
+  const restored = fs.readFileSync(abs, 'utf-8');
+  assert.equal(restored, priorBody, 'working-tree PLAN.md must be reset to HEAD body');
+  assert.ok(phaseDir);
+});
+
+test('PD-8: back-to-back archiveRejected produces distinct filenames (millisecond ISO, Pitfall 9)', () => {
+  const root = makeRepo();
+  const priorBody = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', priorBody);
+  fs.writeFileSync(abs, planBody([{ id: '09-01-T02', tier: 'haiku' }]), 'utf-8');
+  const a1 = pd.archiveRejected({ phase: '09', planId: '09-01', reason: 'first', cwd: root });
+  fs.writeFileSync(abs, planBody([{ id: '09-01-T03', tier: 'haiku' }]), 'utf-8');
+  const a2 = pd.archiveRejected({ phase: '09', planId: '09-01', reason: 'second', cwd: root });
+  assert.notEqual(a1, a2);
+  assert.ok(fs.existsSync(a1));
+  assert.ok(fs.existsSync(a2));
+});
+
+test('PD-9: archiveRejected with empty reason → frontmatter reason: ""', () => {
+  const root = makeRepo();
+  const priorBody = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', priorBody);
+  fs.writeFileSync(abs, planBody([{ id: '09-01-T02', tier: 'haiku' }]), 'utf-8');
+  const archivePath = pd.archiveRejected({ phase: '09', planId: '09-01', reason: '', cwd: root });
+  const body = fs.readFileSync(archivePath, 'utf-8');
+  assert.ok(body.includes('reason: ""'));
+});
+
+test('PD-10: restoreFromHead is idempotent', () => {
+  const root = makeRepo();
+  const priorBody = planBody([{ id: '09-01-T01', tier: 'opus' }]);
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', priorBody);
+  fs.writeFileSync(abs, 'mutated', 'utf-8');
+  pd.restoreFromHead({ phase: '09', planId: '09-01', cwd: root });
+  assert.equal(fs.readFileSync(abs, 'utf-8'), priorBody);
+  pd.restoreFromHead({ phase: '09', planId: '09-01', cwd: root });
+  assert.equal(fs.readFileSync(abs, 'utf-8'), priorBody);
+});
+
+test('PD-11: semantic diff line format uses +/~/- prefixes with expected fields', () => {
+  const root = makeRepo();
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', planBody([
+    { id: '09-01-T01', tier: 'opus' },
+    { id: '09-01-T03', tier: 'haiku' },
+  ]));
+  fs.writeFileSync(abs, planBody([
+    { id: '09-01-T01', tier: 'sonnet' },
+    { id: '09-01-T04', tier: 'haiku' },
+  ]), 'utf-8');
+  const r = pd.renderTwoPartDiff({ phase: '09', planId: '09-01', cwd: root });
+  assert.ok(r.combined.includes('+ 09-01-T04: tier=haiku'));
+  assert.ok(r.combined.includes('~ 09-01-T01: tier=opus→sonnet'));
+  assert.ok(r.combined.includes('- 09-01-T03'));
+});
+
+test('PD-12: rendered combined output contains no ANSI escape bytes (Pitfall 6)', () => {
+  const root = makeRepo();
+  const { abs } = seedPlanCommit(root, '09', 'feature-set', '09-01', planBody([
+    { id: '09-01-T01', tier: 'opus' },
+  ]));
+  execFileSync('git', ['-C', root, 'config', '--local', 'color.ui', 'always'], { stdio: 'pipe' });
+  fs.writeFileSync(abs, planBody([
+    { id: '09-01-T01', tier: 'opus' },
+    { id: '09-01-T02', tier: 'sonnet' },
+  ]), 'utf-8');
+  const r = pd.renderTwoPartDiff({ phase: '09', planId: '09-01', cwd: root });
+  assert.equal(r.combined.indexOf('\x1b'), -1);
+  inRepo(root, () => {  });
+});