@boyingliu01/xp-gate 0.23.0 → 0.25.0

package/lib/__tests__/issue-519-phase-transition-guard.test.js

@@ -0,0 +1,233 @@
+/**
+ * @intent #519: A real pointer-drift incident (#507) showed that a MISSED
+ *         phase transition is invisible — the state file cannot distinguish
+ *         "never ran" from "not yet advanced". Guards under test:
+ *           (1) sequence guard: `completed` on phase n is refused unless phase
+ *               n-1 is completed/skipped, with `--force` as the explicit escape;
+ *           (2) before/after echo so "command didn't run" and "ran without
+ *               effect" are distinguishable in the output;
+ *           (3) an append-only transition audit log;
+ *           (4) phase_history field normalization (`name` → `phase_name`).
+ * @covers handlePhaseTransition guard/echo, appendTransitionAudit, migrateState
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { handlePhaseTransition } from '../phase-transition.js';
+import { SprintStateManager } from '../sprint-state-manager.js';
+import { migrateState } from '../sprint-state-migrator.js';
+
+function writeState(dir, state) {
+  try {
+    fs.mkdirSync(path.join(dir, '.sprint-state'), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, '.sprint-state', 'sprint-state.json'),
+      JSON.stringify(state, null, 2),
+    );
+  } catch (err) {
+    throw new Error(`writeState failed for ${dir}: ${err.message}`);
+  }
+}
+
+function baseState(overrides = {}) {
+  return {
+    _schema_version: 1,
+    id: 'sprint-519',
+    task_description: 'test',
+    phase: 2,
+    status: 'in_progress',
+    started_at: '2026-10-14T00:00:00Z',
+    phase_history: [],
+    isolation: { worktree_path: null, branch: null },
+    ...overrides,
+  };
+}
+
+describe('#519 phase-transition sequence guard', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('refuses `completed` on phase 3 when phase 2 is not completed/skipped', async () => {
+    writeState(dir, baseState({
+      phase: 3,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'in_progress' }],
+    }));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const stderr = errSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    errSpy.mockRestore();
+    expect(code).toBe(1);
+    expect(stderr).toContain('Cannot complete phase 3');
+    expect(stderr).toContain('phase 2');
+    expect(stderr).toContain('phase history');
+  });
+
+  it('refuses the jump and names --force as the override', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await handlePhaseTransition(['5', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const stderr = errSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    errSpy.mockRestore();
+    expect(stderr).toContain('--force');
+  });
+
+  it('allows `completed` when the previous phase is completed', async () => {
+    writeState(dir, baseState({
+      phase: 2,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'completed' }],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('treats a skipped previous phase as valid', async () => {
+    writeState(dir, baseState({
+      phase: 2,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'skipped' }],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('--force overrides the guard and warns', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x', '--force']);
+    const warned = warnSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    outSpy.mockRestore();
+    warnSpy.mockRestore();
+    expect(code).toBe(0);
+    expect(warned).toContain('overridden');
+  });
+
+  it('does not guard phase 1 (no predecessor)', async () => {
+    writeState(dir, baseState({ phase: 1, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['1', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('does not guard non-completed statuses', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'in_progress', '--dir', dir]);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+});
+
+describe('#519 before/after echo', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519echo-'));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('prints before→after for the top-level phase/status and the entry', async () => {
+    // Phase 1 must be completed for the phase-2 completion to pass the
+    // sequence guard (#519) — otherwise the echo is never reached.
+    writeState(dir, baseState({
+      phase: 2,
+      status: 'in_progress',
+      phase_history: [
+        { phase: 1, name: 'PREP', status: 'completed' },
+        { phase: 2, phase_name: 'DESIGN', status: 'in_progress' },
+      ],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['2', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const output = outSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+    expect(output).toContain('before→after');
+    expect(output).toContain('in_progress → completed');
+  });
+});
+
+describe('#519 transition audit log + field normalization', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519audit-'));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('appends one JSON line per transition with from/to', () => {
+    writeState(dir, baseState({ phase: 2, phase_history: [] }));
+    const manager = new SprintStateManager(dir);
+    manager.transitionPhase(2, 'in_progress');
+    manager.transitionPhase(2, 'completed');
+    const auditFile = path.join(dir, '.sprint-state', 'transition-audit.jsonl');
+    expect(fs.existsSync(auditFile)).toBe(true);
+    const lines = fs.readFileSync(auditFile, 'utf8').trim().split('\n');
+    expect(lines.length).toBe(2);
+    const first = JSON.parse(lines[0]);
+    expect(first.phase).toBe(2);
+    expect(first.phase_name).toBe('DESIGN');
+    expect(first.to_status).toBe('in_progress');
+    expect(first.timestamp).toBeTruthy();
+    const second = JSON.parse(lines[1]);
+    expect(second.to_status).toBe('completed');
+  });
+
+  it('audit is best-effort: a write failure does not break the transition', () => {
+    writeState(dir, baseState({ phase: 2, phase_history: [] }));
+    const manager = new SprintStateManager(dir);
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // Break the real appendFileSync so appendTransitionAudit's OWN try/catch is
+    // exercised (mocking the method itself would bypass the production guard).
+    const appendSpy = vi.spyOn(fs, 'appendFileSync').mockImplementation(() => {
+      throw new Error('disk full');
+    });
+    expect(() => manager.transitionPhase(2, 'in_progress')).not.toThrow();
+    const warned = warnSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    appendSpy.mockRestore();
+    warnSpy.mockRestore();
+    expect(warned).toContain('transition audit write failed');
+  });
+
+  it('migrateState normalizes legacy `name` into `phase_name`', () => {
+    // A legacy file (no _schema_version) whose phase 1 entry carries `name`
+    // rather than `phase_name` — the exact shape #507 left behind.
+    const legacy = baseState({
+      _schema_version: undefined,
+      phase_history: [{ phase: 1, name: 'PREP', status: 'completed' }],
+    });
+    const migrated = migrateState(legacy, dir);
+    const entry = migrated.phase_history[0];
+    // The canonical field is populated (via the legacy remap and/or the
+    // name→phase_name normalization) and the legacy field is preserved.
+    expect(entry.phase_name).toBeTruthy();
+    expect(entry.name).toBe('PREP');
+  });
+
+  it('migrateState backfills `name` from `phase_name` (both directions)', () => {
+    const legacy = baseState({
+      _schema_version: undefined,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'in_progress' }],
+    });
+    const migrated = migrateState(legacy, dir);
+    const entry = migrated.phase_history[0];
+    expect(entry.phase_name).toBeTruthy();
+    // `name` is backfilled so a reader consulting either field agrees.
+    expect(entry.name).toBe(entry.phase_name);
+  });
+});

package/lib/__tests__/qoder-delphi-agents.test.js

@@ -282,4 +282,35 @@ describe('Qoder Delphi agent templates (#417)', () => {
       expect(warned()).not.toContain('templates not bundled');
     });
   });
+
+  // #429 item 5: the local-install path had direct test coverage, but the
+  // global wiring (`setupGlobal` -> `deployQoderDelphiAgents(srcDir, HOME_DIR)`)
+  // was only audited at "file exists" level — and the historical miss (#417) was
+  // exactly "local deployed, global did not". This test drives the real
+  // `setupGlobal` under a sandboxed HOME and asserts all three agents land in
+  // `~/.qoder/agents/` bound to the models this version ships. The missing-env
+  // regression it guards: someone re-pointing setupGlobal at a literal path, or
+  // dropping the call entirely, fails here instead of shipping silently.
+  it('deploys all three agents to the real HOME with this version\'s bindings after global setup', async () => {
+    // doctor.js/doctor-tui.js derive their HOME-dependent paths at module load;
+    // dropping them from the cache makes ensureTuiRegistration write inside the
+    // sandbox instead of the developer's real ~/.config/opencode/tui.json.
+    for (const name of ['../doctor.js', '../doctor-tui.js']) {
+      delete require.cache[require.resolve(name)];
+    }
+    const { setupGlobal, readQoderModelId } = require('../init');
+    // setupGlobal consumes the CLI argv array (flag checks downstream).
+    await setupGlobal([]);
+
+    const agentsDir = path.join(tmpHome, '.qoder', 'agents');
+    const shipped = path.join(repoRoot(), 'plugins', 'qoder', 'agents');
+    for (const name of ['delphi-architecture', 'delphi-technical', 'delphi-feasibility']) {
+      const deployed = path.join(agentsDir, `${name}.md`);
+      expect(fs.existsSync(deployed)).toBe(true);
+      // Identical to the bundled template's binding, not merely present: a
+      // stale global copy is the exact failure mode this audit exists for.
+      expect(readQoderModelId(deployed))
+        .toBe(readQoderModelId(path.join(shipped, `${name}.md`)));
+    }
+  });
 });

package/lib/delphi-setup.js

@@ -0,0 +1,155 @@
+'use strict';
+
+// xp-gate delphi-setup (#414 REQ-4) — the repair path for Qoder Delphi agent
+// bindings. `xp-gate init` deploys the bundled templates but deliberately
+// never overwrites an existing file, which is the right safety default for
+// installs and exactly the wrong behavior once a binding has drifted or the
+// platform retired a model id. This command exists to rebind on purpose.
+
+const fs = require('fs');
+const path = require('path');
+const { HOME_DIR, CONFIG_DIR } = require('./shared-paths.js');
+
+const DELPHI_ROLES = ['architecture', 'technical', 'feasibility'];
+// Mirrors QODER_MODEL_BINDING in init.js: the model id must survive
+// `"[DisplayName](modelId)"`, so the platform-visible charset is enforced here
+// rather than discovered as a silently-ignored binding later.
+const MODEL_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+
+function parseSetupArgs(args) {
+  const models = {};
+  let scope = 'global';
+  let projectDir;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--model') {
+      const spec = args[++i];
+      const eq = typeof spec === 'string' ? spec.indexOf('=') : -1;
+      if (eq === -1) {
+        console.error(`[delphi-setup] ERROR: --model expects <role>=<modelId>, got "${spec}".`);
+        return { error: true };
+      }
+      const role = spec.slice(0, eq).trim();
+      const modelId = spec.slice(eq + 1).trim();
+      if (!DELPHI_ROLES.includes(role)) {
+        console.error(`[delphi-setup] ERROR: unknown expert role "${role}". Must be one of: ${DELPHI_ROLES.join(', ')}.`);
+        return { error: true };
+      }
+      if (modelId === '' || !MODEL_ID_PATTERN.test(modelId)) {
+        console.error(`[delphi-setup] ERROR: model id for ${role} must match [A-Za-z0-9_.-]+ (it becomes "[id](id)" in the agent frontmatter).`);
+        return { error: true };
+      }
+      models[role] = modelId;
+    } else if (args[i] === '--local') {
+      scope = 'local';
+    } else if (args[i] === '--global') {
+      scope = 'global';
+    } else if (args[i] === '--project') {
+      projectDir = args[++i];
+      if (typeof projectDir !== 'string' || projectDir.trim() === '') {
+        console.error('[delphi-setup] ERROR: --project expects a directory path.');
+        return { error: true };
+      }
+    } else {
+      console.error(`[delphi-setup] ERROR: unknown argument "${args[i]}".`);
+      return { error: true };
+    }
+  }
+
+  const missing = DELPHI_ROLES.filter((role) => !models[role]);
+  if (missing.length > 0) {
+    console.error(`[delphi-setup] ERROR: missing --model for: ${missing.join(', ')}.`);
+    console.error('Usage: xp-gate delphi-setup --model architecture=<id> --model technical=<id> --model feasibility=<id> [--global|--local [--project <dir>]]');
+    return { error: true };
+  }
+  if (scope === 'local' && projectDir === undefined) {
+    console.error('[delphi-setup] ERROR: --local requires --project <dir> (the CLI process may not run inside the project).');
+    return { error: true };
+  }
+  const duplicates = (() => {
+    // Set-based check (#414 R1 FC-16): readable at any future role count.
+    const ids = Object.values(models);
+    return ids.length !== new Set(ids).size;
+  })();
+  if (duplicates) {
+    console.error('[delphi-setup] ERROR: the three experts must bind three DISTINCT model ids — a duplicate defeats the multi-model invariant before any review starts.');
+    return { error: true };
+  }
+  return { models, scope, projectDir };
+}
+
+// Rebind only the model line; the rest of the bundled template (persona,
+// tools, skills) stays authoritative from this version of xp-gate.
+function rebindTemplate(templateBody, modelId) {
+  // Strip a UTF-8 BOM if present: lines[0] would otherwise be "\uFEFF---" and
+  // the frontmatter would read as missing, producing a misleading error.
+  if (templateBody.charCodeAt(0) === 0xfeff) templateBody = templateBody.slice(1);
+  const bindingLine = `model: "[${modelId}](${modelId})"`;
+  const lines = templateBody.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === '---');
+  if (start !== 0) return null;
+  const end = lines.indexOf('---', 1);
+  if (end === -1) return null;
+  const bindingIndex = lines.findIndex((l, idx) => idx > start && idx < end && /^model:[ \t]/.test(l));
+  if (bindingIndex === -1) return null;
+  lines[bindingIndex] = bindingLine;
+  return lines.join('\n');
+}
+
+async function delphiSetup(args) {
+  const parsed = parseSetupArgs(args || []);
+  if (parsed.error) return 1;
+  const { models, scope, projectDir } = parsed;
+
+  const templatesDir = path.join(__dirname, '..', 'plugins', 'qoder', 'agents');
+  const targetDir = scope === 'local'
+    ? path.join(projectDir, '.qoder', 'agents')
+    : path.join(HOME_DIR, '.qoder', 'agents');
+
+  // Validate every template BEFORE writing anything: a half-rebound set would
+  // leave the registry with a mix of old and new bindings on next session load.
+  const rebound = {};
+  for (const role of DELPHI_ROLES) {
+    const templatePath = path.join(templatesDir, `delphi-${role}.md`);
+    if (!fs.existsSync(templatePath)) {
+      console.error(`[delphi-setup] ERROR: bundled template missing: ${templatePath} — reinstall xp-gate.`);
+      return 1;
+    }
+    const body = rebindTemplate(fs.readFileSync(templatePath, 'utf8'), models[role]);
+    if (body === null) {
+      console.error(`[delphi-setup] ERROR: bundled template for ${role} has no model binding line to replace.`);
+      return 1;
+    }
+    rebound[role] = body;
+  }
+
+  // Back up existing agents before the first write (#414 R1 FC-04): this is
+  // the repair path, and a repair without a rollback is just a second way to
+  // lose a working binding.
+  const backupDir = path.join(CONFIG_DIR, 'backup', `delphi-setup-${Date.now()}`);
+  const backedUp = [];
+  for (const role of DELPHI_ROLES) {
+    const targetPath = path.join(targetDir, `delphi-${role}.md`);
+    if (fs.existsSync(targetPath)) {
+      fs.mkdirSync(backupDir, { recursive: true });
+      fs.copyFileSync(targetPath, path.join(backupDir, `delphi-${role}.md`));
+      backedUp.push(role);
+    }
+  }
+  if (backedUp.length > 0) {
+    console.log(`  backed up existing agents -> ${backupDir} (${backedUp.join(', ')})`);
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const role of DELPHI_ROLES) {
+    const targetPath = path.join(targetDir, `delphi-${role}.md`);
+    fs.writeFileSync(targetPath, rebound[role]);
+    console.log(`  delphi-${role} -> ${targetPath} (model: ${models[role]})`);
+  }
+
+  console.log('');
+  console.log('✓ Delphi agents rebound. NOW RELOAD: Qoder loads agent definitions only at');
+  console.log('  session start — 重开 Qoder 会话（或重启 IDE）后新绑定才生效，否则看起来像没修好。');
+  return 0;
+}
+
+module.exports = { delphiSetup, parseSetupArgs, rebindTemplate };