@ikunin/sprintpilot 2.0.4 → 2.0.6

package/README.md

@@ -197,6 +197,32 @@ Output files:
 
 ---
 
+## Adaptive Process Scaling (v2)
+
+Sprintpilot v2 introduced **complexity profiles** as a first-class config dimension. The right amount of process for a 2-story bug-fix sprint is different from a 30-story green-field rebuild — and the cost of running the heavy flow on a small change is real (more LLM turns, more context rot, more time). One knob picks the right balance:
+
+| Profile | Per-story flow | Branching | Worktrees | Parallel stories | Use it for |
+|---------|---------------|-----------|-----------|------------------|-----------|
+| `nano` | `bmad-quick-dev` (one-shot) | `epic` (one PR per epic) | off | n/a | Tiny patch sprints, hot-fix runs |
+| `small` | Full 7-step BMad cycle | `story` (one PR per story) | on | off | Single-developer projects, ≤10 stories |
+| `medium` *(default)* | Full 7-step BMad cycle | `story` | on | off | Default — balanced for most sprints |
+| `large` | Full 7-step BMad cycle | `story` | on | **on** (Claude Code) | Multi-epic sprints, 20+ stories |
+| `legacy` | Pinned to v1.0.5 behavior byte-for-byte | `story` | on | off | Existing installs that want zero behavior change |
+
+Pick the profile at install time — interactive installer asks, non-interactive flag is `--profile <nano|small|medium|large|legacy>`. Missing profile defaults to `medium` with no behavior change vs. v1.0.5.
+
+**One knob per feature** — every v2 optimization layer can be disabled in isolation without uninstalling. See [Configuration Reference](docs/CONFIGURATION.md#autopilot-configuration-modulesautopilotconfigyaml).
+
+### What v2 ships on top of the core flow
+
+- **Phase timing instrumentation** — `mark` action emits `duration` records per skill phase; auto-emitted on critical paths (no LLM bracket calls to skip). `summarize-timings.js` reports hotspots > 5% of total time.
+- **State sharding** — non-critical writes accumulate in `.pending/` shards, flushed atomically at story boundaries / session checkpoints / sprint complete. Crash-recovery keys still write straight through.
+- **Conditional boot work** — clean-repo sessions skip the slow health-check / branch-reconciliation block (saves 8–30s per session).
+- **Cached reads** — TTL + source-mtime aware file cache; any writer's mtime advance forces a miss without explicit invalidate.
+- **Auto-inferred story DAG** — autopilot infers inter-story dependencies once after `bmad-sprint-planning` and writes `_Sprintpilot/sprints/dependencies.yaml` with an `# AUTO-INFERRED` marker. Hand-authored files are detected and respected silently.
+- **Parallel story dispatch** — when `parallel_stories: true` and the host supports it, layer-aware dispatch runs N stories concurrently in their own worktrees, then merges their state shards. Claude Code today; Gemini CLI experimentally.
+- **Cross-platform** — every workflow.md call site runs under bash, zsh, Git Bash, PowerShell, and cmd. Portable Node.js helpers replace POSIX-shell idioms.
+
 ## Quick Start
 
 ```bash
@@ -215,9 +241,12 @@ npx bmad-method install
 ```
 
 ```bash
-# 2. Install Sprintpilot (interactive — select your tool when prompted)
+# 2. Install Sprintpilot (interactive — select your tool and complexity profile when prompted)
 npx @ikunin/sprintpilot@latest
 
+# 2b. Or pick the profile non-interactively
+npx @ikunin/sprintpilot@latest install --tools claude-code --profile medium --yes
+
 # 3. Start the autopilot in your IDE
 /sprint-autopilot-on
 ```
@@ -298,6 +327,19 @@ All settings live in two YAML files — edit after install to customize behavior
 | `git.lock.stale_timeout_minutes` | `30` | Auto-remove orphaned lock files |
 | `git.worktree.cleanup_on_merge` | `true` | Delete worktrees after merge |
 
+### Autopilot (`_Sprintpilot/modules/autopilot/config.yaml`)
+
+| Setting | Default (medium) | Description |
+|---------|------------------|-------------|
+| `complexity_profile` | `medium` | One of `nano`, `small`, `medium`, `large`, `legacy`. Selects the per-story flow + which v2 layers are enabled. |
+| `autopilot.session_story_limit` | `3` (nano: `5`) | Stories per session before checkpoint. `0` = unlimited. |
+| `autopilot.retrospective_mode` | `auto` | `auto` (deterministic artifact) / `stop` (pause for `/bmad-retrospective`) / `skip`. |
+| `autopilot.auto_infer_dependencies` | `true` (nano + legacy: `false`) | Infer story DAG once after `bmad-sprint-planning`. Hand-authored sidecars (no `# AUTO-INFERRED` marker) are respected silently. |
+| `autopilot.phase_timings` | `true` (legacy: `false`) | Emit phase duration records via `log-timing.js mark`. |
+| `autopilot.coalesce_state_writes` | `true` (legacy: `false`) | Buffer non-critical state in `.pending/` shards. |
+| `autopilot.conditional_boot_work` | `true` (large + legacy: `false`) | Skip health-check / branch-reconciliation on clean repos. |
+| `autopilot.cache_shared_reads` | `true` (legacy: `false`) | TTL + mtime-aware file cache for hot reads. |
+
 ### Multi-Agent (`_Sprintpilot/modules/ma/config.yaml`)
 
 | Setting | Default | Description |
@@ -305,6 +347,11 @@ All settings live in two YAML files — edit after install to customize behavior
 | `multi_agent.enabled` | `true` | Enable parallel agent skills |
 | `multi_agent.max_parallel_research` | `3` | Concurrent research agents per batch |
 | `multi_agent.max_parallel_analysis` | `5` | Concurrent codebase analysis agents |
+| `ma.state_sharding` | `auto` (large: `always`) | `auto`, `always`, `never` — shards per-story state instead of contending on root YAMLs. |
+| `ma.parallel_stories` | `false` (large: `true`) | Dispatch independent stories from a DAG layer concurrently. Requires Claude Code (or Gemini CLI w/ experimental flag). |
+| `ma.max_parallel_stories` | `2` (large: `3`) | Cap on concurrent stories per layer. |
+| `ma.experimental_parallel_on_gemini` | `false` | Opt-in parallel dispatch under Gemini CLI (worktree-scoped subagents are still upstream). |
+| `ma.parallel_epics` | `false` | EXPERIMENTAL — cross-epic parallelism with merge-conflict preflight. Off on every profile by default. |
 
 See the [Configuration Reference](docs/CONFIGURATION.md) for the full list.
 

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 2.0.4
+  version: 2.0.6
   description: Sprintpilot — autopilot and multi-agent addon for BMad Method (git workflow, parallel agents, autonomous story execution)
   bmad_compatibility: ">=6.2.0"
   modules:

package/_Sprintpilot/scripts/inject-tasks-section.js

@@ -222,6 +222,11 @@ function main() {
   const acSectionName = opts['ac-section'] || 'Acceptance Criteria';
   const projectRoot = opts['project-root'] || process.cwd();
   const storyKey = storyKeyFromFile(storyFile);
+  if (storyKey === null && timing.isEnabled(projectRoot)) {
+    log.error(
+      `inject-tasks-section: cannot derive a STORY_RE-compatible key from '${path.basename(storyFile)}' (must lower-case to /^[a-z0-9][a-z0-9-]*$/ after stripping leading 'story-' and trailing '.md'); skipping timing emit`,
+    );
+  }
 
   const body = fs.readFileSync(storyFile, 'utf8');
   const info = inspectTasksSection(body);

package/_Sprintpilot/scripts/log-timing.js

@@ -9,13 +9,16 @@
 //   start   Emit {event:"start", story, phase, ts:<iso8601>}
 //   end     Emit {event:"end",   story, phase, ts:<iso8601>}
 //   once    Emit a single-event marker (for things like health-check-run)
-//   mark    Single-call replacement for start/end pairs. Reads a tiny
-//           marker file (.timings/.mark.json), computes the duration
-//           since the previous mark, emits one duration record for the
-//           PREVIOUS phase, and writes a new marker for the current
-//           phase. Designed for LLM-driven workflows where the agent
-//           may forget to call `end` after a long skill — `mark` only
-//           needs to be called ONCE per phase transition.
+//   mark    Single-call replacement for start/end pairs. Reads a per-story
+//           marker file (.timings/.mark.<story>.json), computes the duration
+//           since the previous mark for the same story key, emits one
+//           duration record for the PREVIOUS phase, and writes a new
+//           marker for the current phase. Designed for LLM-driven
+//           workflows where the agent may forget to call `end` after a
+//           long skill — `mark` only needs to be called ONCE per phase
+//           transition. Per-story markers (added in 2.0.5) make
+//           concurrent sub-agents marking different stories race-free
+//           against the same project root.
 //
 // Output path:
 //   <project-root>/_bmad-output/implementation-artifacts/.timings/<story>.jsonl
@@ -43,7 +46,18 @@ const PHASE_RE = /^[a-z][a-z0-9-.]*$/;
 const META_MAX_BYTES = 2048;
 const LINE_MAX_BYTES = 4096; // POSIX PIPE_BUF floor — single write() is atomic
 const VALID_ACTIONS = ['start', 'end', 'once', 'mark'];
-const MARKER_FILE = '.mark.json';
+// Marker filenames are `.mark.<story>.json` — built by `markerPath()`.
+// Pre-2.0.5 used a single global `.mark.json`, which corrupted timing
+// data under parallel dispatch (concurrent sub-agents racing on one
+// rename target). The constant is gone; runtime always uses per-story
+// paths.
+//
+// Sanity ceiling for a single duration record. A wall-clock skip
+// forward of more than this many ms is treated as clock skew rather
+// than a real duration — clamped to 0 with `clock_skew: true` stamped.
+// 24h chosen because no realistic skill phase is longer than that, and
+// it's well above any plausible CI timeout.
+const MAX_PLAUSIBLE_DURATION_MS = 24 * 60 * 60 * 1000;
 
 function help() {
   log.out(
@@ -191,43 +205,81 @@ function buildEntry(action, story, phase, meta) {
 // `mark` — single-call timing
 // ---------------------------------------------------------------
 
-function markerPath(projectRoot) {
-  return path.join(timingsDir(projectRoot), MARKER_FILE);
+function markerPath(projectRoot, story) {
+  if (!story) throw new Error('markerPath requires a story key');
+  return path.join(timingsDir(projectRoot), `.mark.${story}.json`);
 }
 
-function readMarker(projectRoot) {
-  const file = markerPath(projectRoot);
-  if (!fs.existsSync(file)) return null;
+function readMarker(projectRoot, story) {
+  const file = markerPath(projectRoot, story);
+  let raw;
   try {
-    const raw = fs.readFileSync(file, 'utf8');
-    const parsed = JSON.parse(raw);
-    if (
-      parsed &&
-      typeof parsed === 'object' &&
-      typeof parsed.story === 'string' &&
-      typeof parsed.phase === 'string' &&
-      typeof parsed.ts === 'string'
-    ) {
-      return parsed;
-    }
-  } catch {
-    /* corrupt marker — treat as absent */
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    // EACCES / EISDIR / other I/O — surface to stderr so silent corruption
+    // doesn't masquerade as "first mark of session".
+    log.error(`timing marker read failed (${file}): ${e.message}`);
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    log.error(`timing marker corrupt (${file}): ${e.message} — treating as absent`);
+    return null;
+  }
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    typeof parsed.story !== 'string' ||
+    typeof parsed.phase !== 'string' ||
+    typeof parsed.ts !== 'string'
+  ) {
+    return null;
   }
-  return null;
+  // Re-validate `story` and `phase` against their regexes. CLI input is
+  // already validated, but a corrupted/hand-edited marker could carry a
+  // path-traversing story (e.g. "../../etc") — `parsed.story` flows into
+  // `appendLine(projectRoot, prev.story, ...)` which path.joins to
+  // `<timingsDir>/<story>.jsonl`. Defense-in-depth: refuse any value that
+  // doesn't match STORY_RE / PHASE_RE.
+  if (!STORY_RE.test(parsed.story)) {
+    log.error(`timing marker (${file}) has invalid story '${parsed.story}'; treating as absent`);
+    return null;
+  }
+  if (parsed.phase !== '_end' && !PHASE_RE.test(parsed.phase)) {
+    log.error(`timing marker (${file}) has invalid phase '${parsed.phase}'; treating as absent`);
+    return null;
+  }
+  return parsed;
 }
 
-function writeMarker(projectRoot, marker) {
+function writeMarker(projectRoot, story, marker) {
   const dir = timingsDir(projectRoot);
   fs.mkdirSync(dir, { recursive: true });
-  const file = markerPath(projectRoot);
+  const file = markerPath(projectRoot, story);
   // Atomic-ish: write tmp + rename. Marker is small, single-line JSON.
-  const tmp = `${file}.tmp.${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(marker));
-  fs.renameSync(tmp, file);
+  // Tmp filename includes story + pid + random suffix to avoid collisions
+  // between concurrent same-process writers (rare in normal use, common in
+  // parallel test runs) and PID-reuse.
+  const tmp = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(marker));
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    // Clean up tmp on rename failure so we don't leak orphan files.
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* ignore — tmp may not exist */
+    }
+    throw e;
+  }
 }
 
-function clearMarker(projectRoot) {
-  const file = markerPath(projectRoot);
+function clearMarker(projectRoot, story) {
+  const file = markerPath(projectRoot, story);
   try {
     fs.unlinkSync(file);
   } catch {
@@ -238,27 +290,56 @@ function clearMarker(projectRoot) {
 /**
  * mark: single-call timing API.
  *
- * Emits a duration record for the PREVIOUS phase (if any) covering the
- * interval since the previous mark, then writes a new marker for the
- * current phase. The very first mark in a session emits no duration
- * record — there's no "previous phase" yet.
+ * Emits a duration record for THIS story's PREVIOUS phase (if any),
+ * covering the interval since the previous mark for the same story key,
+ * then writes a new marker for the current phase. The very first mark
+ * for a given story emits no duration record — there's no "previous
+ * phase" yet for that story.
+ *
+ * Pre-2.0.5 used a single global marker file shared across stories,
+ * which under parallel dispatch (sub-agents marking different stories
+ * concurrently against the same project root) raced on a single file —
+ * one rename clobbered the other and durations were attributed to the
+ * wrong (story, phase). Per-story markers eliminate the race entirely:
+ * each story has its own marker file `.mark.<story>.json`.
+ *
+ * Use phase = "_end" to close THIS story's last open phase without
+ * starting a new one (e.g. at sprint-complete time, or per-story
+ * cleanup). `_end` only touches the marker for the named story; other
+ * stories' markers are untouched.
+ *
+ * Order of operations is interrupt-safe: the new marker is written
+ * BEFORE the duration record is appended. If the process is killed
+ * between the marker rename and the duration append, we lose one
+ * duration record but the next mark will read the new marker (not the
+ * stale prev) and won't double-count.
  *
- * Use phase = "_end" to close the last open phase without starting a new
- * one (e.g. at sprint-complete time).
+ * Wall-clock skew: durations are clamped to [0, MAX_PLAUSIBLE_DURATION_MS]
+ * with a `clock_skew: true` flag in the entry so aggregators don't get
+ * poisoned by NTP backsteps, DST transitions, or container clock skips
+ * forward of unrealistic magnitudes (e.g. "this skill ran for 7 hours").
  *
  * Returns { duration_ms, prev_phase } so callers can log/inspect.
  */
 function markPhase(projectRoot, story, phase, meta) {
   const now = new Date();
-  const prev = readMarker(projectRoot);
+  const prev = readMarker(projectRoot, story);
+
+  // Build the duration entry from prev (if any) before mutating marker
+  // state. We append AFTER writing the new marker, so an interrupt
+  // between the two yields one missed record (acceptable) rather than a
+  // stale marker that would double-count on the next call.
+  let durationEntry = null;
   let durationMs = null;
   let prevPhase = null;
   if (prev) {
     const prevTs = Date.parse(prev.ts);
     if (!Number.isNaN(prevTs)) {
-      durationMs = now.getTime() - prevTs;
+      const rawDelta = now.getTime() - prevTs;
+      const clamped = rawDelta < 0 || rawDelta > MAX_PLAUSIBLE_DURATION_MS;
+      durationMs = clamped ? 0 : rawDelta;
       prevPhase = prev.phase;
-      const durationEntry = {
+      durationEntry = {
         event: 'duration',
         story: prev.story,
         phase: prev.phase,
@@ -266,17 +347,26 @@ function markPhase(projectRoot, story, phase, meta) {
         ended: now.toISOString(),
         duration_ms: durationMs,
       };
+      if (clamped) durationEntry.clock_skew = true;
       if (prev.meta !== undefined) durationEntry.meta = prev.meta;
-      appendLine(projectRoot, prev.story, durationEntry);
     }
   }
+
+  // 1. Commit the marker state transition first.
   if (phase === '_end') {
-    clearMarker(projectRoot);
+    clearMarker(projectRoot, story);
   } else {
     const marker = { story, phase, ts: now.toISOString() };
     if (meta !== undefined) marker.meta = meta;
-    writeMarker(projectRoot, marker);
+    writeMarker(projectRoot, story, marker);
   }
+
+  // 2. Append the duration record after the marker is committed. If
+  //    this throws, the marker is already correct for the next mark.
+  if (durationEntry !== null) {
+    appendLine(projectRoot, prev.story, durationEntry);
+  }
+
   return { duration_ms: durationMs, prev_phase: prevPhase };
 }
 
@@ -337,7 +427,7 @@ module.exports = {
   PHASE_RE,
   META_MAX_BYTES,
   LINE_MAX_BYTES,
-  MARKER_FILE,
+  MAX_PLAUSIBLE_DURATION_MS,
   VALID_ACTIONS,
   validateStory,
   validatePhase,

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

@@ -639,7 +639,7 @@ Parse stdout as a single JSON object: `{"remaining":[...],"state":"..."}`.
     - Skill flow (full):  bmad-create-story → bmad-check-implementation-readiness → bmad-dev-story → bmad-code-review → apply patch findings → re-run tests → set status=done in {status_file}
     - Skill flow (quick): bmad-quick-dev (single skill; nano profile)
     Use {{implementation_flow}} = `{{implementation_flow}}` to pick which flow.
-    Track timing via `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story K --phase <phase>` after each skill returns.
+    Track timing via `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story K --phase <phase> --project-root {{project_root}}` after each skill returns. The explicit `--project-root` is REQUIRED — without it the script falls back to cwd (the worktree), which orphans timing data. With per-story markers (2.0.5+) concurrent sub-agents writing to the same project root no longer race.
     Return a one-line JSON summary on completion: {"story":"K", "status":"done"|"failed", "tests":"<N/M>", "notes":"<short>"}
     ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikunin/sprintpilot",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Sprintpilot — autopilot and multi-agent addon for BMad Method v6: git workflow, parallel agents, autonomous story execution",
   "license": "Apache-2.0",
   "repository": {