@ikunin/sprintpilot 2.0.10 → 2.1.0

package/_Sprintpilot/scripts/log-timing.js

@@ -103,7 +103,10 @@ function validatePhase(s) {
 
 function validateAction(a) {
   if (!VALID_ACTIONS.includes(a)) {
-    return { ok: false, error: `invalid action '${a}': must be one of ${VALID_ACTIONS.join(', ')}` };
+    return {
+      ok: false,
+      error: `invalid action '${a}': must be one of ${VALID_ACTIONS.join(', ')}`,
+    };
   }
   return { ok: true, value: a };
 }
@@ -430,10 +433,16 @@ function main() {
       const r = markPhase(projectRoot, story.value, phase.value, meta.value);
       // Emit a brief JSON line so callers can log the duration if useful.
       // Stdout is intentionally separate from the per-story shard.
-      process.stdout.write(`${JSON.stringify({ marked: phase.value, prev_phase: r.prev_phase, duration_ms: r.duration_ms })}\n`);
+      process.stdout.write(
+        `${JSON.stringify({ marked: phase.value, prev_phase: r.prev_phase, duration_ms: r.duration_ms })}\n`,
+      );
       return;
     }
-    appendLine(projectRoot, story.value, buildEntry(action.value, story.value, phase.value, meta.value));
+    appendLine(
+      projectRoot,
+      story.value,
+      buildEntry(action.value, story.value, phase.value, meta.value),
+    );
   } catch (e) {
     log.error(`timing write failed: ${e.message}`);
     process.exit(1);

package/_Sprintpilot/scripts/merge-shards.js

@@ -115,7 +115,9 @@ function acquireMergeLock(projectRoot) {
         try {
           const st = fs.statSync(file);
           if (Date.now() - st.mtimeMs > STALE_LOCK_AGE_MS) {
-            log.warn(`merge-shards: removing stale lock ${file} (older than ${STALE_LOCK_AGE_MS}ms)`);
+            log.warn(
+              `merge-shards: removing stale lock ${file} (older than ${STALE_LOCK_AGE_MS}ms)`,
+            );
             fs.unlinkSync(file);
             continue;
           }
@@ -201,11 +203,7 @@ function shardUnchanged(file, snapshot) {
   if (!snapshot) return false;
   try {
     const st = fs.statSync(file);
-    return (
-      st.mtimeMs === snapshot.mtime &&
-      st.size === snapshot.size &&
-      st.ino === snapshot.ino
-    );
+    return st.mtimeMs === snapshot.mtime && st.size === snapshot.size && st.ino === snapshot.ino;
   } catch {
     return false;
   }
@@ -421,7 +419,11 @@ function composeStateYaml(stateMerge) {
   if (stateMerge.corrupt.length + stateMerge.invalid.length > 0) {
     doc.shard_problems = [
       ...stateMerge.corrupt.map((c) => ({ story: c.story, kind: 'parse-error', detail: c.error })),
-      ...stateMerge.invalid.map((c) => ({ story: c.story, kind: 'invalid-shape', detail: c.reason })),
+      ...stateMerge.invalid.map((c) => ({
+        story: c.story,
+        kind: 'invalid-shape',
+        detail: c.reason,
+      })),
     ];
   }
   return `${yamlDump(doc)}\n`;
@@ -435,8 +437,16 @@ function composeDecisionYaml(decisionMerge) {
   };
   if (decisionMerge.corrupt.length + decisionMerge.invalid.length > 0) {
     doc.shard_problems = [
-      ...decisionMerge.corrupt.map((c) => ({ story: c.story, kind: 'parse-error', detail: c.error })),
-      ...decisionMerge.invalid.map((c) => ({ story: c.story, kind: 'invalid-shape', detail: c.reason })),
+      ...decisionMerge.corrupt.map((c) => ({
+        story: c.story,
+        kind: 'parse-error',
+        detail: c.error,
+      })),
+      ...decisionMerge.invalid.map((c) => ({
+        story: c.story,
+        kind: 'invalid-shape',
+        detail: c.reason,
+      })),
     ];
   }
   return `${yamlDump(doc)}\n`;
@@ -460,7 +470,13 @@ function merge(projectRoot, { layerId, archive, dryRun } = {}) {
         archivedCorrupt.push({ kind: 'state', story: c.story, ...arch });
       }
       for (const c of decisions.corrupt.concat(decisions.invalid)) {
-        const arch = archiveCorrupt(projectRoot, 'decision-log', c.story, c.file, c.error || c.reason);
+        const arch = archiveCorrupt(
+          projectRoot,
+          'decision-log',
+          c.story,
+          c.file,
+          c.error || c.reason,
+        );
         archivedCorrupt.push({ kind: 'decision-log', story: c.story, ...arch });
       }
     }
@@ -468,8 +484,12 @@ function merge(projectRoot, { layerId, archive, dryRun } = {}) {
     const stateBody = composeStateYaml(state);
     const decisionBody = composeDecisionYaml(decisions);
 
-    const stateWrite = writeAuthoritative(projectRoot, 'autopilot-state.yaml', stateBody, { dryRun });
-    const decisionWrite = writeAuthoritative(projectRoot, 'decision-log.yaml', decisionBody, { dryRun });
+    const stateWrite = writeAuthoritative(projectRoot, 'autopilot-state.yaml', stateBody, {
+      dryRun,
+    });
+    const decisionWrite = writeAuthoritative(projectRoot, 'decision-log.yaml', decisionBody, {
+      dryRun,
+    });
 
     let archiveDir = null;
     let archiveSkipped = [];

package/_Sprintpilot/scripts/post-green-gates.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+// post-green-gates.js — composed post-GREEN quality pipeline.
+//
+// Called by the orchestrator after a `bmad-dev-story` GREEN phase
+// completes verify. Runs three gates in order; first failing gate causes
+// non-zero exit with a structured JSON report.
+//
+// Gates:
+//   1. lint-changed.js       — biome/eslint on changed files only
+//   2. lint-test-pitfalls.js — LLM-test pitfalls (only on test files)
+//   3. scan.js (ci-parity)   — search for obvious CI-only failure modes
+//                              (envs hard-coded to local-only assumptions)
+//
+// Usage:
+//   post-green-gates.js [--json] [--changed-files <path>] [--project-root <path>]
+//     --changed-files: path to a newline-delimited list of changed files
+//                      (default: derive from `git diff --name-only HEAD`)
+//
+// Each gate runs in a child process via execFileSync. Argv-only — no shell.
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+function help() {
+  log.out(
+    [
+      'Usage: post-green-gates.js [--json] [--changed-files <path>] [--project-root <path>]',
+      '',
+      'Runs in order:',
+      '  1. lint-changed.js       — formatter + linter on changed files',
+      '  2. lint-test-pitfalls.js — LLM-test pitfall scan (test files only)',
+      '  3. scan.js (ci-parity)   — CI-only failure mode scan',
+    ].join('\n'),
+  );
+}
+
+function listChangedFiles(projectRoot, override) {
+  if (override) {
+    return fs
+      .readFileSync(override, 'utf8')
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+  }
+  try {
+    const out = execFileSync('git', ['diff', '--name-only', 'HEAD'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    });
+    return out
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } catch (_e) {
+    return [];
+  }
+}
+
+function runGate(name, command, args, projectRoot) {
+  const r = spawnSync(command, args, { cwd: projectRoot, encoding: 'utf8' });
+  return {
+    gate: name,
+    ok: r.status === 0,
+    exit_code: r.status === null ? -1 : r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+  };
+}
+
+function isTestFile(p) {
+  return /\.test\.(ts|tsx|js|jsx|mts)$/.test(p) || /\.spec\.(ts|tsx|js|jsx|mts)$/.test(p);
+}
+
+function isJsTsFile(p) {
+  return /\.(ts|tsx|js|jsx|mts|cjs)$/.test(p);
+}
+
+function main(argv) {
+  const { opts } = parseArgs(argv, { booleanFlags: ['json', 'help'] });
+  if (opts.help) {
+    help();
+    return 0;
+  }
+  const projectRoot = path.resolve(opts['project-root'] || process.cwd());
+  const changed = listChangedFiles(projectRoot, opts['changed-files']);
+  const jsTs = changed.filter(isJsTsFile);
+  const testFiles = changed.filter(isTestFile);
+
+  const gates = [];
+
+  // Gate 1: lint-changed.
+  const lintChangedPath = path.join(projectRoot, '_Sprintpilot', 'scripts', 'lint-changed.js');
+  if (fs.existsSync(lintChangedPath) && jsTs.length > 0) {
+    gates.push(
+      runGate(
+        'lint-changed',
+        'node',
+        [lintChangedPath, '--project-root', projectRoot],
+        projectRoot,
+      ),
+    );
+  } else {
+    gates.push({
+      gate: 'lint-changed',
+      ok: true,
+      exit_code: 0,
+      stdout: 'skipped (no JS/TS changes or script missing)',
+      stderr: '',
+    });
+  }
+
+  // Gate 2: lint-test-pitfalls — only run on test files.
+  const pitfallsPath = path.join(projectRoot, '_Sprintpilot', 'scripts', 'lint-test-pitfalls.js');
+  if (fs.existsSync(pitfallsPath) && testFiles.length > 0) {
+    gates.push(runGate('lint-test-pitfalls', 'node', [pitfallsPath, ...testFiles], projectRoot));
+  } else {
+    gates.push({
+      gate: 'lint-test-pitfalls',
+      ok: true,
+      exit_code: 0,
+      stdout: 'skipped (no test files in change set)',
+      stderr: '',
+    });
+  }
+
+  // Gate 3: ci-parity via scan.js. Pattern set is intentionally conservative
+  // — flag obvious CI-only-fail patterns: `if (!process.env.CI)` skips,
+  // hardcoded localhost ports, `xit`/`xdescribe`. scan.js does the search;
+  // we treat its non-zero exit as a block.
+  const scanPath = path.join(projectRoot, '_Sprintpilot', 'scripts', 'scan.js');
+  if (fs.existsSync(scanPath) && jsTs.length > 0) {
+    gates.push(
+      runGate(
+        'ci-parity',
+        'node',
+        [
+          scanPath,
+          '--pattern',
+          'process.env.CI',
+          '--pattern',
+          '(localhost|127\\.0\\.0\\.1):\\d{4,5}',
+          '--paths',
+          ...jsTs,
+        ],
+        projectRoot,
+      ),
+    );
+  } else {
+    gates.push({
+      gate: 'ci-parity',
+      ok: true,
+      exit_code: 0,
+      stdout: 'skipped (no JS/TS changes or script missing)',
+      stderr: '',
+    });
+  }
+
+  const firstFail = gates.find((g) => !g.ok);
+  const overallOk = !firstFail;
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: overallOk, gates, first_fail: firstFail?.gate || null }, null, 2)}\n`,
+    );
+  } else {
+    for (const g of gates) {
+      log.out(`[${g.ok ? '✓' : '✗'}] ${g.gate}: exit=${g.exit_code}`);
+      if (!g.ok) {
+        if (g.stdout) log.out(g.stdout);
+        if (g.stderr) log.err(g.stderr);
+      }
+    }
+    log.out(overallOk ? 'all gates passed' : `failed gate: ${firstFail?.gate}`);
+  }
+  return overallOk ? 0 : 1;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = { main, listChangedFiles, runGate, isTestFile, isJsTsFile };

package/_Sprintpilot/scripts/preflight-merge.js

@@ -196,7 +196,8 @@ function main() {
     process.exit(1);
   }
   const projectRoot = opts['project-root'] || process.cwd();
-  const branchPrefix = opts['branch-prefix'] !== undefined ? String(opts['branch-prefix']) : 'story/';
+  const branchPrefix =
+    opts['branch-prefix'] !== undefined ? String(opts['branch-prefix']) : 'story/';
   const timeout = opts['lock-timeout-sec']
     ? Number.parseInt(String(opts['lock-timeout-sec']), 10)
     : DEFAULT_LOCK_TIMEOUT_SEC;

package/_Sprintpilot/scripts/resolve-dag.js

@@ -568,7 +568,9 @@ function main() {
   }
 
   if (command === 'graph') {
-    process.stdout.write(`${JSON.stringify({ nodes: dag.nodes, edges: dag.edges, epic: dag.epic })}\n`);
+    process.stdout.write(
+      `${JSON.stringify({ nodes: dag.nodes, edges: dag.edges, epic: dag.epic })}\n`,
+    );
     return;
   }
   if (command === 'layers') {

package/_Sprintpilot/scripts/stack-snapshot.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+// stack-snapshot.js — capture a snapshot of the current per-story branch
+// stack so `land-this-pr.js` can land the active PR without losing the
+// rest of the in-flight stack.
+//
+// Output: JSON to stdout (or --output <path>). Shape:
+//   {
+//     base_branch: string,
+//     ts: ISO,
+//     branches: [{ name, head, story_key, status, parent? }],
+//     active_pr: { branch, number?, story_key } | null,
+//   }
+//
+// Argv-only. Uses `git -C <projectRoot>` for every git call.
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+function help() {
+  log.out(
+    [
+      'Usage: stack-snapshot.js [--project-root <path>] [--base-branch <name>]',
+      '                         [--output <file>] [--active-branch <name>]',
+      '                         [--story-key <key>] [--pr-number <n>]',
+    ].join('\n'),
+  );
+}
+
+function git(projectRoot, args) {
+  try {
+    return execFileSync('git', ['-C', projectRoot, ...args], { encoding: 'utf8' }).trim();
+  } catch (_e) {
+    return null;
+  }
+}
+
+function listLocalBranches(projectRoot, prefix) {
+  const raw = git(projectRoot, [
+    'for-each-ref',
+    '--format=%(refname:short)\t%(objectname)',
+    `refs/heads/${prefix}`,
+  ]);
+  if (!raw) return [];
+  return raw
+    .split(/\n/)
+    .filter(Boolean)
+    .map((line) => {
+      const [name, head] = line.split('\t');
+      return { name, head };
+    });
+}
+
+function readSprintStatus(projectRoot) {
+  const p = path.join(
+    projectRoot,
+    '_bmad-output',
+    'implementation-artifacts',
+    'sprint-status.yaml',
+  );
+  if (!fs.existsSync(p)) return null;
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+}
+
+function statusForStory(sprintStatusText, storyKey) {
+  if (!sprintStatusText) return 'unknown';
+  // Narrow regex — accept either "story_key: status" or block form.
+  const re = new RegExp(`^\\s*${storyKey}:\\s*(\\w+)`, 'm');
+  const m = sprintStatusText.match(re);
+  return m ? m[1] : 'unknown';
+}
+
+function snapshot(opts) {
+  const projectRoot = path.resolve(opts['project-root'] || process.cwd());
+  const baseBranch = opts['base-branch'] || 'main';
+  const branches = listLocalBranches(projectRoot, 'story/').map((b) => ({
+    ...b,
+    story_key: b.name.slice('story/'.length),
+  }));
+  const sprintStatus = readSprintStatus(projectRoot);
+  for (const b of branches) {
+    b.status = statusForStory(sprintStatus, b.story_key);
+  }
+  const active =
+    opts['active-branch'] && opts['story-key']
+      ? {
+          branch: opts['active-branch'],
+          story_key: opts['story-key'],
+          number: opts['pr-number'] ? Number(opts['pr-number']) : undefined,
+        }
+      : null;
+  return {
+    base_branch: baseBranch,
+    ts: new Date().toISOString(),
+    branches,
+    active_pr: active,
+  };
+}
+
+function main(argv) {
+  const { opts } = parseArgs(argv, { booleanFlags: ['help'] });
+  if (opts.help) {
+    help();
+    return 0;
+  }
+  const snap = snapshot(opts);
+  const out = `${JSON.stringify(snap, null, 2)}\n`;
+  if (opts.output) {
+    fs.writeFileSync(path.resolve(opts.output), out, 'utf8');
+  } else {
+    process.stdout.write(out);
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = { main, snapshot, statusForStory };

package/_Sprintpilot/scripts/state-shard.js

@@ -575,7 +575,14 @@ function deepAssign(target, source) {
   for (const k of Object.keys(source)) {
     const sv = source[k];
     const tv = out[k];
-    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+    if (
+      sv &&
+      typeof sv === 'object' &&
+      !Array.isArray(sv) &&
+      tv &&
+      typeof tv === 'object' &&
+      !Array.isArray(tv)
+    ) {
       out[k] = deepAssign(tv, sv);
     } else {
       out[k] = sv;

package/_Sprintpilot/scripts/summarize-timings.js

@@ -176,7 +176,12 @@ function pairEvents(events) {
   for (const key of Object.keys(openByStoryPhase)) {
     const [story, phase] = key.split('::');
     for (const startMs of openByStoryPhase[key]) {
-      orphans.push({ story, phase, event: 'start-without-end', ts: new Date(startMs).toISOString() });
+      orphans.push({
+        story,
+        phase,
+        event: 'start-without-end',
+        ts: new Date(startMs).toISOString(),
+      });
     }
   }
 
@@ -213,14 +218,21 @@ function aggregate(paired) {
   withPct.sort((a, b) => b.sum_ms - a.sum_ms);
   const hotspots = withPct.filter((r) => r.pct_of_total > HOTSPOT_THRESHOLD);
 
-  const stories = Object.keys(paired.stories).sort().map((key) => {
-    const s = paired.stories[key];
-    const wall_ms = s.first !== null && s.last !== null ? s.last - s.first : 0;
-    const phaseSum = Object.values(s.phases)
-      .flat()
-      .reduce((acc, v) => acc + v, 0);
-    return { story: key, wall_ms, phase_sum_ms: phaseSum, phase_count: Object.keys(s.phases).length };
-  });
+  const stories = Object.keys(paired.stories)
+    .sort()
+    .map((key) => {
+      const s = paired.stories[key];
+      const wall_ms = s.first !== null && s.last !== null ? s.last - s.first : 0;
+      const phaseSum = Object.values(s.phases)
+        .flat()
+        .reduce((acc, v) => acc + v, 0);
+      return {
+        story: key,
+        wall_ms,
+        phase_sum_ms: phaseSum,
+        phase_count: Object.keys(s.phases).length,
+      };
+    });
 
   return {
     total_paired_ms: totalPaired,
@@ -263,7 +275,9 @@ function renderText(report) {
   if (report.phases.length === 0) {
     lines.push('  (no paired start/end events)');
   } else {
-    lines.push('  phase                                    count    sum     p50     p95     max    %');
+    lines.push(
+      '  phase                                    count    sum     p50     p95     max    %',
+    );
     for (const r of report.phases) {
       lines.push(
         `  ${r.phase.padEnd(40)} ${String(r.count).padStart(5)}  ${fmtMs(r.sum_ms).padStart(6)}  ${fmtMs(r.p50_ms).padStart(6)}  ${fmtMs(r.p95_ms).padStart(6)}  ${fmtMs(r.max_ms).padStart(6)}  ${fmtPct(r.pct_of_total).padStart(6)}`,
@@ -318,7 +332,9 @@ function renderMarkdown(report) {
     lines.push('| Story | Wall | Phase sum | # phases |');
     lines.push('|---|---|---|---|');
     for (const s of report.stories) {
-      lines.push(`| ${s.story} | ${fmtMs(s.wall_ms)} | ${fmtMs(s.phase_sum_ms)} | ${s.phase_count} |`);
+      lines.push(
+        `| ${s.story} | ${fmtMs(s.wall_ms)} | ${fmtMs(s.phase_sum_ms)} | ${s.phase_count} |`,
+      );
     }
   }
   lines.push('');
@@ -360,7 +376,9 @@ function renderMarkdown(report) {
     lines.push('');
     lines.push('## Anomalies');
     lines.push('');
-    lines.push('_Excluded from p50/p95/max so a single skew/stale-marker doesn\'t poison aggregates._');
+    lines.push(
+      "_Excluded from p50/p95/max so a single skew/stale-marker doesn't poison aggregates._",
+    );
     lines.push('');
     lines.push('| Phase | clock_skew | over_threshold |');
     lines.push('|---|---:|---:|');

package/_Sprintpilot/scripts/with-retry.js

@@ -27,7 +27,8 @@ const log = require('../lib/runtime/log');
 const DEFAULT_ATTEMPTS = 3;
 const DEFAULT_MIN_MS = 500;
 const DEFAULT_MAX_MS = 2000;
-const DEFAULT_REF_LOCK_PATTERN = /cannot lock ref|Unable to create.*\.lock|Reference already exists|failed to lock|lock\.ref/i;
+const DEFAULT_REF_LOCK_PATTERN =
+  /cannot lock ref|Unable to create.*\.lock|Reference already exists|failed to lock|lock\.ref/i;
 
 function help() {
   log.out(
@@ -79,7 +80,15 @@ function runOnce(cmd, args, inherit = false) {
   };
 }
 
-function runWithRetry({ cmd, args, attempts = DEFAULT_ATTEMPTS, minMs = DEFAULT_MIN_MS, maxMs = DEFAULT_MAX_MS, pattern = DEFAULT_REF_LOCK_PATTERN, onAttempt = null }) {
+function runWithRetry({
+  cmd,
+  args,
+  attempts = DEFAULT_ATTEMPTS,
+  minMs = DEFAULT_MIN_MS,
+  maxMs = DEFAULT_MAX_MS,
+  pattern = DEFAULT_REF_LOCK_PATTERN,
+  onAttempt = null,
+}) {
   const actualAttempts = Math.max(1, attempts | 0);
   let last = null;
   for (let i = 0; i < actualAttempts; i++) {
@@ -107,9 +116,12 @@ function main() {
     help();
     process.exit(opts.help ? 0 : 1);
   }
-  const attempts = opts.attempts !== undefined ? Number.parseInt(String(opts.attempts), 10) : DEFAULT_ATTEMPTS;
-  const minMs = opts['min-ms'] !== undefined ? Number.parseInt(String(opts['min-ms']), 10) : DEFAULT_MIN_MS;
-  const maxMs = opts['max-ms'] !== undefined ? Number.parseInt(String(opts['max-ms']), 10) : DEFAULT_MAX_MS;
+  const attempts =
+    opts.attempts !== undefined ? Number.parseInt(String(opts.attempts), 10) : DEFAULT_ATTEMPTS;
+  const minMs =
+    opts['min-ms'] !== undefined ? Number.parseInt(String(opts['min-ms']), 10) : DEFAULT_MIN_MS;
+  const maxMs =
+    opts['max-ms'] !== undefined ? Number.parseInt(String(opts['max-ms']), 10) : DEFAULT_MAX_MS;
   let pattern = DEFAULT_REF_LOCK_PATTERN;
   if (opts.pattern) {
     try {

package/_Sprintpilot/skills/sprint-autopilot-on/SKILL.md

@@ -3,4 +3,26 @@ name: sprint-autopilot-on
 description: 'Engage autonomous story execution for BMad Method with git workflow integration. Implements stories end-to-end with automatic branching (git worktrees), commits, linting, and PR creation. Uses standard git worktree commands for story isolation — works with any coding agent. Falls back to stock BMad behavior when git is disabled. Use when user says "/sprint-autopilot-on" or "start autopilot".'
 ---
 
-Follow the instructions in ./workflow.md.
+## STOP — read this entire file before doing anything
+
+Sprintpilot is driven by a deterministic Node.js state machine at
+`_Sprintpilot/bin/autopilot.js`. The LLM owns in-skill execution,
+diagnosis, triage, and small-judgment decisions — not the flow.
+
+Follow **`./workflow.orchestrator.md`** verbatim. Flow control lives in
+`_Sprintpilot/bin/autopilot.js` (a Node CLI you call via `autopilot next`
+/ `autopilot record`). The orchestrator emits actions; you execute them.
+
+### Never improvise
+
+- Never decide which BMad skill runs next yourself — the state machine
+  emits an `invoke_skill` action telling you.
+- Never skip the `autopilot next` → `autopilot record` cycle. Even when
+  a step feels "obvious," route through the CLI so the ledger, verify,
+  and bookkeeping enforcement run.
+- Do not search for `workflow.md` or reconstruct it from memory; do not
+  read cached BMad legacy patterns and apply them ahead of the
+  orchestrator's state machine.
+
+`workflow.orchestrator.md` is the **sole authority** for the rest of the
+session.