@boyingliu01/xp-gate 0.23.0 → 0.25.0

package/lib/doctor.js

@@ -2643,8 +2643,276 @@ function formatDoctorJson(checks, issues) {
   };
 }
 
+// ── doctor delphi (#414 REQ-3/REQ-6) ───────────────────────────────────
+// Diagnoses the Delphi review chain end to end. Each check exists because a
+// real failure was silent: drifted agent bindings looked like a working setup
+// (B2), a stale skill copy made reinstall = downgrade (B4), and a missing
+// runner script surfaced only as a failed review (B3).
+async function doctorDelphi(options = {}) {
+  const { configPath, npmLatest } = options;
+  const checks = [];
+  const add = (name, status, detail) => checks.push({ name, status, detail });
+
+  // 1. Node >= 18: the runner gates on it and exits 1 mid-review otherwise.
+  const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+  add('Node.js >= 18', nodeMajor >= 18 ? 'PASS' : 'FAIL',
+    `current: ${process.versions.node}`);
+
+  // 2. Qoder agent bindings: present, parseable, three distinct ids, matching
+  // what this version ships. A stale binding is a repair, not an error to
+  // retype: the detail names delphi-setup. Project-level agents (from
+  // `delphi-setup --local --project`) take precedence when a complete set
+  // exists there, so the doctor agrees with the repair command (#414 R1 FC-09).
+  const { readQoderModelId } = require('./init.js');
+  const roles = ['architecture', 'technical', 'feasibility'];
+  const homeAgentsDir = path.join(HOME_DIR, '.qoder', 'agents');
+  // Injectable for tests; defaults to the cwd the doctor runs from.
+  const projectAgentsDir = path.join(options.projectDir || process.cwd(), '.qoder', 'agents');
+  const homeComplete = roles.every((r) => fs.existsSync(path.join(homeAgentsDir, `delphi-${r}.md`)));
+  const projectComplete = roles.every((r) => fs.existsSync(path.join(projectAgentsDir, `delphi-${r}.md`)));
+  const agentsDir = projectComplete ? projectAgentsDir : homeAgentsDir;
+  const agentsSource = projectComplete
+    ? `project-level ${agentsDir}`
+    : `user-level ${agentsDir}`;
+  const agentIds = [];
+  let agentsStatus = 'PASS';
+  const agentDetails = [agentsSource];
+  for (const role of roles) {
+    const agentPath = path.join(agentsDir, `delphi-${role}.md`);
+    if (!fs.existsSync(agentPath)) {
+      agentsStatus = 'FAIL';
+      agentDetails.push(`delphi-${role}.md missing (run: xp-gate init --global, or delphi-setup --local --project for project scope)`);
+      continue;
+    }
+    const id = readQoderModelId(agentPath);
+    if (id === null) {
+      agentsStatus = 'FAIL';
+      agentDetails.push(`delphi-${role}.md has no quoted model binding (repair: xp-gate delphi-setup)`);
+      continue;
+    }
+    const bundledId = readQoderModelId(path.join(PKG_DIR, 'plugins', 'qoder', 'agents', `delphi-${role}.md`));
+    if (bundledId === null) {
+      // A bundle without a parseable template is install corruption: skipping
+      // the comparison would hide it behind a healthy-looking id (#414 R1 FC-08).
+      agentsStatus = 'FAIL';
+      agentDetails.push(`delphi-${role}: bundled template missing/unreadable — reinstall xp-gate`);
+      continue;
+    }
+    if (bundledId !== id) {
+      agentDetails.push(`delphi-${role}: ${id} (this version ships ${bundledId} — repair: xp-gate delphi-setup)`);
+    } else {
+      agentDetails.push(`delphi-${role}: ${id}`);
+    }
+    agentIds.push(id);
+  }
+  // Report every problem class independently: missing files, unparseable
+  // bindings and duplicates can coexist, and each has a different remedy
+  // (#414 R1 MI-02).
+  if (agentIds.length !== roles.length) agentsStatus = 'FAIL';
+  if (new Set(agentIds).size !== agentIds.length) {
+    agentsStatus = 'FAIL';
+    agentDetails.push('duplicate model binding across experts — three DISTINCT ids are required');
+  }
+  add('Qoder Delphi agent bindings', agentsStatus, agentDetails.join('; ') || 'all three bound');
+
+  // 3. Skill install parity: a drifted installed copy is how "reinstall from
+  // an old local repo" became a downgrade (#414 B4). Every bundled file is
+  // compared, not just SKILL.md — the install script copies *.json and
+  // references/ too, and B4-style drift hits those equally (#414 R1 MI-03).
+  const platform = detectPlatform();
+  const installedSkillDir = platform === 'qoder'
+    ? path.join(HOME_DIR, '.qoder', 'skills', 'delphi-review')
+    : platform === 'claude-code'
+      ? path.join(HOME_DIR, '.claude', 'skills', 'delphi-review')
+      : path.join(HOME_DIR, '.config', 'opencode', 'skills', 'delphi-review');
+  // Injectable for tests (#414 R3 FC-01/FC-02): the empty-bundle branch is a
+  // real failure mode and must be drivable without mutating the package.
+  const bundledSkillDir = options.bundledSkillDir || path.join(PKG_DIR, 'skills', 'delphi-review');
+  const sha256 = (p) => require('crypto').createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+  const listBundledSkillFiles = (dir, base = dir, out = []) => {
+    if (!fs.existsSync(dir)) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) listBundledSkillFiles(p, base, out);
+      else out.push(path.relative(base, p));
+    }
+    return out;
+  };
+  if (!fs.existsSync(path.join(installedSkillDir, 'SKILL.md'))) {
+    add('Delphi skill install parity', 'FAIL',
+      `not installed at ${installedSkillDir} (install: xp-gate install-skill delphi-review)`);
+  } else {
+    const bundledFiles = listBundledSkillFiles(bundledSkillDir);
+    if (bundledFiles.length === 0) {
+      // An installed copy next to an empty bundle is install corruption —
+      // "0 files match" must never read as healthy (#414 R2 MN-R2-01). The
+      // bundled dir ships inside the installed package itself, so an
+      // unreachable one is a broken install, not a transient condition
+      // (#414 R3 FC-05): FAILing is the doctor's job here.
+      add('Delphi skill install parity', 'FAIL',
+        `bundled skill directory missing or empty: ${bundledSkillDir} — reinstall xp-gate`);
+    } else {
+      const drifted = [];
+      for (const rel of bundledFiles) {
+        const installedPath = path.join(installedSkillDir, rel);
+        const bundledPath = path.join(bundledSkillDir, rel);
+        if (!fs.existsSync(installedPath)) {
+          drifted.push(`${rel}: missing`);
+        } else if (sha256(installedPath) !== sha256(bundledPath)) {
+          drifted.push(`${rel}: differs from bundle`);
+        }
+      }
+      if (drifted.length > 0) {
+        add('Delphi skill install parity', 'FAIL',
+          `${drifted.length} file(s) differ from the ${getCliVersionSafe()} bundle: `
+          + `${drifted.slice(0, 5).join('; ')}${drifted.length > 5 ? '; ...' : ''} `
+          + '(reinstall: xp-gate install-skill delphi-review --force)');
+      } else {
+        add('Delphi skill install parity', 'PASS',
+          `${bundledFiles.length} file(s) match the bundle`);
+      }
+    }
+  }
+
+  // 4. Runner script locate: the runner must be findable from the places a
+  // review actually starts.
+  const runnerCandidates = [
+    ['package bundle', path.join(PKG_DIR, 'scripts', 'delphi-external-review.cjs')],
+    ['project', path.join(process.cwd(), 'scripts', 'delphi-external-review.cjs')],
+    ['installed skill', path.join(installedSkillDir, 'scripts', 'delphi-external-review.cjs')],
+  ];
+  const foundRunner = runnerCandidates.filter(([, p]) => fs.existsSync(p));
+  add('delphi-external-review runner', foundRunner.length > 0 ? 'PASS' : 'FAIL',
+    foundRunner.length > 0
+      ? foundRunner.map(([label, p]) => `${label}: ${p}`).join('; ')
+      : 'not found in package bundle, project, or installed skill');
+
+  // 5. Config ping: parseable, three distinct callable models. A duplicate
+  // model here is a review that will BLOCK later — say so now.
+  const cfgPath = configPath || path.join(process.cwd(), '.delphi-config.json');
+  if (!fs.existsSync(cfgPath)) {
+    add('Delphi config (.delphi-config.json)', 'FAIL',
+      `${cfgPath} not found (copy .delphi-config.json.example from the skill directory)`);
+  } else {
+    try {
+      const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+      const profileName = raw.active_profile || 'default';
+      const profile = raw.profiles && raw.profiles[profileName];
+      if (!profile) {
+        add('Delphi config (.delphi-config.json)', 'FAIL', `profile "${profileName}" not found`);
+      } else {
+        const experts = profile.experts || {};
+        const models = roles.map((r) => experts[r] && experts[r].model);
+        const providers = profile.providers || {};
+        const missingRoles = roles.filter((r, i) => !models[i]);
+        const duplicates = models.filter((m, i) => m && models.indexOf(m) !== i);
+        const badProviders = roles.filter((r) => {
+          const e = experts[r];
+          return !e || !providers[e.provider]
+            || !providers[e.provider].base_url
+            || String(providers[e.provider].base_url).indexOf('http') !== 0;
+        });
+        if (missingRoles.length > 0 || duplicates.length > 0 || badProviders.length > 0) {
+          const problems = [];
+          if (missingRoles.length > 0) problems.push(`missing experts: ${missingRoles.join(', ')}`);
+          if (duplicates.length > 0) problems.push(`duplicate models: ${[...new Set(duplicates)].join(', ')}`);
+          if (badProviders.length > 0) problems.push(`unusable provider binding: ${badProviders.join(', ')}`);
+          add('Delphi config (.delphi-config.json)', 'FAIL', problems.join('; '));
+        } else {
+          add('Delphi config (.delphi-config.json)', 'PASS',
+            `profile "${profileName}": ${models.join(' / ')}`);
+        }
+      }
+    } catch (err) {
+      add('Delphi config (.delphi-config.json)', 'FAIL', `unparseable: ${err.message}`);
+    }
+  }
+
+  // 6. Version consistency (#414 REQ-6): local files first. The npm-latest
+  // probe is opt-in (options.probeNpmLatest) or pre-supplied
+  // (options.npmLatest) — the doctor never blocks on the network, which is
+  // what an offline CI or restricted shell would otherwise hit (#414 R1 FC-03).
+  const localVersion = getCliVersionSafe();
+  let versionStatus = 'PASS';
+  let versionDetail = `xp-gate ${localVersion}`;
+  if (npmLatest === undefined && options.probeNpmLatest === true) {
+    try {
+      versionDetail += `; npm latest probe: ${execWithTimeout('npm view @boyingliu01/xp-gate version', 8000).trim()}`;
+    } catch {
+      versionStatus = 'SKIP';
+      versionDetail += '; npm latest probe unavailable (offline?) — skipped';
+    }
+  } else if (typeof npmLatest === 'string' && npmLatest !== localVersion) {
+    versionStatus = 'FAIL';
+    versionDetail += `; npm latest ${npmLatest} differs from local ${localVersion} — update (npm install -g @boyingliu01/xp-gate@latest) or verify which side is stale`;
+  } else if (npmLatest === null || options.probeNpmLatest !== true) {
+    versionDetail += '; npm latest probe skipped (pass --npm-check or options.probeNpmLatest to run it)';
+  }
+  add('Delphi version consistency', versionStatus, versionDetail);
+
+  // 7. DSH native-channel readiness (#443 REQ-6): only meaningful when a DSH
+  // home exists. The two-layer switch (preset capability + host setting)
+  // defaults to disabled, and a review that assumes native will silently run
+  // three same-model seats.
+  const dshHome = path.join(HOME_DIR, '.dsh');
+  if (!fs.existsSync(dshHome)) {
+    add('DSH subagent model selection', 'SKIP', `no ${dshHome} — not a DSH environment`);
+  } else {
+    const settingsCandidates = [
+      path.join(dshHome, 'settings.json'),
+      path.join(dshHome, 'settings', 'settings.json'),
+      path.join(dshHome, 'config.json'),
+    ];
+    const settingsFile = settingsCandidates.find((p) => fs.existsSync(p));
+    if (!settingsFile) {
+      add('DSH subagent model selection', 'FAIL',
+        `${dshHome} exists but no settings file found — subagent model selection defaults to disabled (#443)`);
+    } else {
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+        const selection = settings.subagentModelSelection;
+        const allowed = selection && Array.isArray(selection.allowedModels) ? selection.allowedModels : [];
+        const ids = allowed.map((m) => (typeof m === 'string' ? m : m && m.id)).filter(Boolean);
+        if (selection && selection.enabled === true && new Set(ids).size >= 3) {
+          add('DSH subagent model selection', 'PASS', `${settingsFile}: enabled, ${new Set(ids).size} distinct allowed models`);
+        } else if (selection && selection.enabled === true) {
+          add('DSH subagent model selection', 'FAIL',
+            `${settingsFile}: enabled but only ${new Set(ids).size} distinct allowedModels (need ≥3) — native channel unusable`);
+        } else {
+          // The switch shipping off is the platform default, not a defect:
+          // only an operator who explicitly enables it and under-provisions
+          // allowedModels has a real misconfiguration (#414 R1 FC-07).
+          add('DSH subagent model selection', 'SKIP',
+            `${settingsFile}: native model selection disabled (platform default) — the external channel is the contract path (#443)`);
+        }
+      } catch (err) {
+        add('DSH subagent model selection', 'SKIP', `${settingsFile} unparseable: ${err.message}`);
+      }
+    }
+  }
+
+  for (const check of checks) {
+    const mark = check.status === 'PASS' ? '✓' : check.status === 'SKIP' ? '○' : '✗';
+    console.log(`  ${mark} ${check.name}: ${check.detail || check.status}`);
+  }
+  const failed = checks.filter((c) => c.status === 'FAIL').length;
+  console.log('');
+  console.log(failed === 0
+    ? '  Delphi review chain: healthy.'
+    : `  Delphi review chain: ${failed} check(s) FAILED.`);
+  return failed === 0 ? 0 : 1;
+}
+
+function getCliVersionSafe() {
+  try {
+    return require('../package.json').version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
 module.exports = {
-  doctor, isXpGateFile, SIGNATURES,
+  doctor, doctorDelphi, isXpGateFile, SIGNATURES,
   fixVersionMismatch,
   fixTemplateDirMismatch,
   fixMissingHooks,

package/lib/init.js

@@ -271,6 +271,46 @@ function printCliToolStatus() {
   }
 }
 
+/**
+ * Probe for gitleaks and warn when it is missing (#511).
+ *
+ * Gate 8 became fail-closed in #499: a missing gitleaks BLOCKs the commit
+ * outright (it does NOT skip, unlike the tools reported by
+ * printCliToolStatus). The user-facing installers never provisioned it, so an
+ * existing user upgrading into #499 hits a hard BLOCK on their next commit with
+ * no prior signal — this is the missing migration notice.
+ *
+ * Probe-and-prompt only: nothing is installed here (installing is the user's
+ * explicit choice, via the printed command). The fail-closed semantics of
+ * #499 are untouched.
+ *
+ * @param {(name: string) => {available: boolean, version?: string}} checkTool
+ * @param {(line: string) => void} [log]
+ * @returns {{available: boolean}} the probe result, for callers that branch on it
+ */
+function probeGitleaksNotice(checkTool, log = console.log) {
+  const result = checkTool('gitleaks');
+  if (result.available) {
+    log(`✓ gitleaks present${result.version ? `: ${result.version}` : ''}`);
+    return { available: true };
+  }
+
+  log('');
+  log('⚠  gitleaks is NOT installed.');
+  log('   Gate 8 (secret scanning) is FAIL-CLOSED since #499: your next commit');
+  log('   will be BLOCKED until gitleaks is available.');
+  log('');
+  log('   Install it now:');
+  log('     bash scripts/install-gitleaks.sh');
+  log('');
+  log('   Per-OS alternatives:');
+  log('     macOS:    brew install gitleaks');
+  log('     Linux:    https://github.com/gitleaks/gitleaks/releases');
+  log('     Windows:  winget install gitleaks  (or: scoop install gitleaks)');
+  log('');
+  return { available: false };
+}
+
 /**
  * Ask the user for confirmation via stdin.
  * @param {string} question - The yes/no question to display
@@ -352,6 +392,11 @@ async function init(args) {
   console.log('Checking CLI tools...');
   printCliToolStatus();
 
+  // #511: gitleaks is the one tool whose absence BLOCKS rather than SKIPs
+  // (Gate 8 fail-closed, #499) — surface it separately so an upgrading user
+  // has a migration path before the first blocked commit.
+  probeGitleaksNotice(checkCliTool);
+
   console.log('Checking platform dependencies...');
   // Detect platform and check/auto-install dependencies
   const platform = detectPlatform();
@@ -922,4 +967,7 @@ function injectKarpathyPrinciples(projectRoot) {
   }
 }
 
-module.exports = { init, promptBootstrap, installModuleRuntimeDeps, deployQoderDelphiAgents, configureQoderDelphiAgents, readQoderModelId };
+// setupGlobal is exported so the global-install wiring (agents deployed to the
+// real HOME) can be audited under a sandboxed HOME, not just asserted to exist
+// — the historical miss was "local deployed, global did not" (#417, #429).
+module.exports = { init, promptBootstrap, installModuleRuntimeDeps, deployQoderDelphiAgents, configureQoderDelphiAgents, readQoderModelId, setupGlobal, probeGitleaksNotice };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-14T05:31:48.350Z",
+  "checked_at": "2026-10-15T07:13:54.700Z",
   "source": "network"
 }

package/lib/phase-transition.js

@@ -532,12 +532,14 @@ async function handlePhaseTransition(args = []) {
     console.log('  --render           Render ASCII dashboard after transition');
     console.log('  --dir <path>       Project directory (default: cwd)');
     console.log('  --skip-evidence <reason>  Skip evidence validation (requires reason)');
+    console.log('  --force            Override the phase sequence guard (#519)');
     console.log('');
     console.log('Examples:');
     console.log('  xp-gate phase-transition 1 completed');
     console.log('  xp-gate phase-transition 3 completed --render');
     console.log('  xp-gate phase-transition 2 in_progress --outputs \'{"spec":"path.yaml"}\'');
     console.log('  xp-gate phase-transition 4 completed --skip-evidence "Emergency hotfix"');
+    console.log('  xp-gate phase-transition 3 completed --force   # skip-order override');
     return 0;
   }
 
@@ -576,6 +578,9 @@ async function handlePhaseTransition(args = []) {
     }
   }
 
+  // #519: explicit override for the sequence guard below.
+  const forceTransition = args.includes('--force');
+
   // Validate inputs
   if (phase < 1 || phase > 6) {
     console.error(`Error: Phase must be 1-6, got ${phase}`);
@@ -592,6 +597,37 @@ async function handlePhaseTransition(args = []) {
   try {
     const manager = new SprintStateManager(projectDir);
 
+    // ── #519 Layer 0: Sequence guard ──
+    // `completed` on phase n requires phase n-1 to be completed/skipped first.
+    // #507 proved that a missed transition is invisible in the state file (the
+    // pointer just looks "not yet advanced"), so out-of-order completion —
+    // skipping a phase, or completing from a stale pointer — must be refused
+    // loudly rather than written silently. `--force` overrides for the rare
+    // legitimate case (e.g. retroactively recording a skipped phase).
+    if (status === 'completed' && phase >= 2) {
+      const seqState = manager.read();
+      if (seqState && Array.isArray(seqState.phase_history)) {
+        const prevPhase = phase - 1;
+        const prevEntry = seqState.phase_history.find(e => e.phase === prevPhase);
+        const prevOk = prevEntry && (prevEntry.status === 'completed' || prevEntry.status === 'skipped');
+        if (!prevOk && !forceTransition) {
+          const summary = seqState.phase_history
+            .map(e => `  ${e.phase}:${e.phase_name || PHASE_NAMES[e.phase] || '?'} = ${e.status}`)
+            .join('\n');
+          console.error(`❌ [sprint-audit] Cannot complete phase ${phase} (${PHASE_NAMES[phase]}):`);
+          console.error(`   phase ${prevPhase} (${PHASE_NAMES[prevPhase]}) is not completed/skipped.`);
+          console.error('   Current phase history:');
+          console.error(summary || '  (empty)');
+          console.error(`   Advance it first: xp-gate phase-transition ${prevPhase} completed`);
+          console.error('   Or override explicitly: --force');
+          return 1;
+        }
+        if (!prevOk && forceTransition) {
+          console.warn(`⚠️  [sprint-audit] Sequence guard overridden (--force): phase ${prevPhase} is not completed/skipped.`);
+        }
+      }
+    }
+
     // ── Layer 1: Pre-transition gate check ──
     // Check BEFORE transitionPhase() to validate previous phase completion.
     // Runs when status === 'in_progress' and phase >= 2.
@@ -640,9 +676,34 @@ async function handlePhaseTransition(args = []) {
       }
     }
 
+    // Capture the before-image for the echo below (#519). Read once here so a
+    // concurrent writer cannot make before/after disagree about their baseline.
+    const beforeSnapshot = (() => {
+      try {
+        const s = manager.read();
+        if (!s) return { phase: undefined, status: undefined, entryStatus: undefined };
+        const e = Array.isArray(s.phase_history) ? s.phase_history.find(x => x.phase === phase) : undefined;
+        return { phase: s.phase, status: s.status, entryStatus: e ? e.status : undefined };
+      } catch {
+        return { phase: undefined, status: undefined, entryStatus: undefined };
+      }
+    })();
+
     const newState = manager.transitionPhase(phase, status, { outputs });
 
+    // #519: before/after echo. The #507 failure mode was "the command either
+    // never ran or ran without effect" — both look identical in a terminal that
+    // prints only a success line. Printing the observed state on both sides
+    // makes those two cases distinguishable in the output itself.
+    const afterEntry = Array.isArray(newState.phase_history)
+      ? newState.phase_history.find(e => e.phase === phase)
+      : undefined;
+    const oldTop = `${beforeSnapshot.phase ?? '-'}/${beforeSnapshot.status ?? '-'}`;
+    const newTop = `${newState.phase ?? '-'}/${newState.status ?? '-'}`;
+    const oldEntry = beforeSnapshot.entryStatus ?? '(none)';
+    const newEntryStatus = afterEntry ? afterEntry.status : '(none)';
     console.log(`✅ Phase ${phase} transitioned to '${status}'`);
+    console.log(`   before→after  phase/status: ${oldTop} → ${newTop}  |  phase ${phase} entry: ${oldEntry} → ${newEntryStatus}`);
 
     // ── Layer 1.5: Auto-trigger Layer 2 reminder on Phase 6 completed ──
     if (phase === 6 && status === 'completed') {

package/lib/sprint-state-manager.js

@@ -12,6 +12,38 @@ const fs = require('fs');
 const path = require('path');
 const { migrateState, createInitialState, rollbackState, LEGACY_PHASE_MAP } = require('./sprint-state-migrator');
 
+/** Canonical phase order; index = phase - 1. */
+const PHASE_NAMES = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
+
+/**
+ * Apply a status change to the phase_history entry for `phase`, creating it on
+ * first sight, and stamp started_at/completed_at/duration_seconds.
+ *
+ * Module-level and pure (it only mutates the passed-in state), extracted from
+ * transitionPhase (#519) so that method stays within the long-function budget.
+ */
+function applyHistoryEntry(state, phase, phaseName, status) {
+  let entry = state.phase_history.find(e => e.phase === phase);
+  if (!entry) {
+    entry = { phase, phase_name: phaseName, status };
+    state.phase_history.push(entry);
+  }
+
+  entry.status = status;
+  if (status === 'in_progress' && !entry.started_at) {
+    entry.started_at = new Date().toISOString();
+  }
+  if (status === 'completed' || status === 'skipped') {
+    entry.completed_at = new Date().toISOString();
+    if (entry.started_at) {
+      const startMs = new Date(entry.started_at).getTime();
+      const endMs = new Date(entry.completed_at).getTime();
+      entry.duration_seconds = Math.round((endMs - startMs) / 1000);
+    }
+  }
+  return entry;
+}
+
 class SprintStateManager {
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
@@ -48,59 +80,57 @@ class SprintStateManager {
   }
 
   write(state) {
-    // Ensure state directory exists
-    if (!fs.existsSync(this.stateDir)) {
-      fs.mkdirSync(this.stateDir, { recursive: true });
+    try {
+      if (!fs.existsSync(this.stateDir)) {
+        fs.mkdirSync(this.stateDir, { recursive: true });
+      }
+      // Atomic write: write to tmp, then rename
+      const tmpFile = this.stateFile + '.tmp';
+      fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
+      fs.renameSync(tmpFile, this.stateFile);
+    } catch (err) {
+      throw new Error(`Failed to write sprint state: ${err.message}`);
     }
-
-    // Atomic write: write to tmp, then rename
-    const tmpFile = this.stateFile + '.tmp';
-    fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
-    fs.renameSync(tmpFile, this.stateFile);
   }
 
   transitionPhase(phase, status, options = {}) {
     const state = this.read() || createInitialState(this.projectRoot);
 
-    // Update current phase
-    state.phase = phase;
-
-    // Find or create phase_history entry
-    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
-    const phaseName = phaseNames[phase - 1];
-
-    let entry = state.phase_history.find(e => e.phase === phase);
-    if (!entry) {
-      entry = {
-        phase,
-        phase_name: phaseName,
-        status,
-      };
-      state.phase_history.push(entry);
-    }
+    // Capture the before-image so the caller can echo a before/after
+    // comparison. #519: the same values feed the append-only audit log.
+    const beforePhase = state.phase;
+    const beforeEntry = Array.isArray(state.phase_history)
+      ? state.phase_history.find(e => e.phase === phase)
+      : undefined;
+    const beforeStatus = beforeEntry ? beforeEntry.status : undefined;
 
-    // Update entry
-    entry.status = status;
-    if (status === 'in_progress' && !entry.started_at) {
-      entry.started_at = new Date().toISOString();
-    }
-    if (status === 'completed' || status === 'skipped') {
-      entry.completed_at = new Date().toISOString();
-      if (entry.started_at) {
-        const startMs = new Date(entry.started_at).getTime();
-        const endMs = new Date(entry.completed_at).getTime();
-        entry.duration_seconds = Math.round((endMs - startMs) / 1000);
-      }
-    }
+    state.phase = phase;
+    const phaseName = PHASE_NAMES[phase - 1];
+    applyHistoryEntry(state, phase, phaseName, status);
 
-    // Update outputs if provided
     if (options.outputs) {
       state.outputs = { ...state.outputs, ...options.outputs };
     }
 
-    // Write state atomically
     this.write(state);
 
+    // #519: append-only transition audit. The #507 incident proved that a
+    // MISSED transition is invisible in the state file — the pointer drift
+    // looked identical to a legitimately-not-yet-run phase. A per-transition
+    // record — from/to plus statuses — lets post-mortems distinguish "never
+    // ran" from "ran and was overwritten". Best-effort: a logging failure must
+    // never break the transition, same contract as the onTransition callback.
+    this.appendTransitionAudit({
+      phase,
+      phase_name: phaseName,
+      from_phase: beforePhase,
+      // from_status === undefined together with a defined to_status is exactly
+      // what proves the phase was reached from nothing — i.e. never ran.
+      from_status: beforeStatus,
+      to_status: status,
+      timestamp: new Date().toISOString(),
+    });
+
     // Trigger onTransition callback (for auto-render)
     if (typeof options.onTransition === 'function') {
       try {
@@ -114,6 +144,23 @@ class SprintStateManager {
     return state;
   }
 
+  /**
+   * Append one JSON line to .sprint-state/transition-audit.jsonl (#519).
+   * Never throws — audit is evidence, not a gate.
+   * @param {object} record
+   */
+  appendTransitionAudit(record) {
+    try {
+      if (!fs.existsSync(this.stateDir)) {
+        fs.mkdirSync(this.stateDir, { recursive: true });
+      }
+      const auditFile = path.join(this.stateDir, 'transition-audit.jsonl');
+      fs.appendFileSync(auditFile, JSON.stringify(record) + '\n', 'utf8');
+    } catch (err) {
+      console.warn(`[WARN] transition audit write failed: ${err.message}`);
+    }
+  }
+
   rollback() {
     return rollbackState(this.stateFile, this.backupFile);
   }