@ikunin/sprintpilot 2.2.31 → 2.3.0

package/_Sprintpilot/lib/orchestrator/action-ledger.js

@@ -44,6 +44,40 @@ const VALID_KINDS = [
   // includes `summary` (counts) or `reason` ('disabled' / 'no_worktrees_dir'
   // / 'script_missing' / 'health_check_error' / 'worktrees_disabled').
   'worktree_health_check',
+  // v2.3.0 — sprint-plan.yaml lifecycle + queue events. Emitted from
+  // cmdStart (migration trigger, refresh, queue hydration, auto-derive
+  // gate, exhaustion) and cmdRecord (story-done sync to plan).
+  'plan_migrated',
+  'plan_migration_failed',
+  'plan_refreshed',
+  'plan_refresh_failed',
+  'plan_queue_loaded',
+  'plan_queue_failed',
+  'plan_exhausted',
+  'plan_archive_failed',
+  'auto_derive_emitted',
+  'plan_story_done',
+  'plan_story_done_failed',
+  'replan_requested_consumed',
+  // v2.3.0 — mid-flight plan mutations applied via applySideEffects.
+  'plan_reordered',
+  'plan_reorder_rejected',
+  'plan_reorder_failed',
+  'plan_stories_added',
+  'plan_add_stories_failed',
+  'plan_stories_removed',
+  'plan_remove_stories_failed',
+  // v2.3.0 — planning skill outcomes (emitted by /sprintpilot-plan-sprint
+  // via the orchestrator after the skill completes).
+  'plan_built',
+  'cross_epic_edge_rejected',
+  'issue_id_set',
+  'dag_rendered',
+  // v2.3.0 — streaming progress (Phase 4.5). Sub-step granularity within
+  // a single story so `autopilot progress` can render live status.
+  'story_step_started',
+  'story_step_progress',
+  'story_step_completed',
 ];
 
 function isPlainObject(v) {
@@ -147,11 +181,185 @@ function nextSeq(fs, filePath) {
   return 1;
 }
 
+// readSince — return entries with seq strictly greater than `afterSeq`.
+// Used by the tail iterator and one-shot consumers that want incremental
+// reads without re-parsing the whole file.
+function readSince(context, afterSeq) {
+  const entries = read(context);
+  if (typeof afterSeq !== 'number') return entries;
+  return entries.filter((e) => typeof e.seq === 'number' && e.seq > afterSeq);
+}
+
+// tail — async iterator yielding ledger entries as they're appended.
+// Polls every `pollIntervalMs` (default 250ms). Terminates when
+// `signal.aborted` is true OR when `maxIdleMs` elapses without new events
+// (default Infinity).
+//
+// Usage:
+//   const ctrl = new AbortController();
+//   for await (const event of tail({ projectRoot, signal: ctrl.signal })) {
+//     console.log(event.kind, event.seq);
+//     if (event.kind === 'halt') ctrl.abort();
+//   }
+//
+// CI-safe: no fs.watch (some filesystems don't support it; CI logs can
+// be replayed via the underlying file). Pure polling with offset tracking
+// for cheap incremental reads.
+async function* tail(context, options) {
+  if (!context || !context.projectRoot) throw new Error('tail: context.projectRoot required');
+  const opts = options || {};
+  const pollIntervalMs = typeof opts.pollIntervalMs === 'number' ? opts.pollIntervalMs : 250;
+  const maxIdleMs = typeof opts.maxIdleMs === 'number' ? opts.maxIdleMs : Number.POSITIVE_INFINITY;
+  const signal = opts.signal;
+  let lastSeq = typeof opts.afterSeq === 'number' ? opts.afterSeq : 0;
+
+  // v2.3.0 — track the ledger file's inode so we detect rotation /
+  // truncation. If `> ledger.jsonl` or `mv ledger.jsonl ledger.jsonl.1`
+  // happens, the inode changes (or stat throws) and we reset lastSeq
+  // to 0 so the next poll picks up entries from the start of the new
+  // file. Without this, tail() silently misses every event after a
+  // rotation.
+  const filePath = resolveLedgerPath(context.projectRoot);
+  let lastInode = null;
+  let lastSize = 0;
+  const captureFileIdentity = () => {
+    try {
+      const st = nodeFs.lstatSync(filePath);
+      lastInode = st.ino;
+      lastSize = st.size;
+    } catch {
+      // File doesn't exist yet — that's fine; on first poll we'll
+      // capture the identity when it appears.
+      lastInode = null;
+      lastSize = 0;
+    }
+  };
+  captureFileIdentity();
+
+  // If afterSeq isn't supplied, start from the current tail so we don't
+  // dump the whole history on every call. Pass afterSeq=0 explicitly to
+  // get everything.
+  if (typeof opts.afterSeq !== 'number') {
+    const existing = read(context);
+    if (existing.length > 0) {
+      const tailEntry = existing[existing.length - 1];
+      if (typeof tailEntry.seq === 'number') lastSeq = tailEntry.seq;
+    }
+  }
+
+  const sleep = (ms) => new Promise((resolve) => {
+    if (!signal) {
+      setTimeout(resolve, ms);
+      return;
+    }
+    const t = setTimeout(resolve, ms);
+    if (signal.aborted) {
+      clearTimeout(t);
+      resolve();
+      return;
+    }
+    signal.addEventListener('abort', () => {
+      clearTimeout(t);
+      resolve();
+    }, { once: true });
+  });
+
+  let idleAccumulatedMs = 0;
+  while (!(signal && signal.aborted)) {
+    // Rotation / truncation check before each poll. Three cases:
+    //   - File didn't exist before, now does → capture identity, treat
+    //     as fresh start; do NOT reset lastSeq (afterSeq semantics still
+    //     apply).
+    //   - File existed before, now doesn't → it was deleted; reset
+    //     identity tracking, on next iteration we'll re-capture.
+    //   - File exists with a different inode OR smaller size than last
+    //     time → rotated/truncated; reset lastSeq=0 so we yield from
+    //     the start of the new file.
+    let currentInode = null;
+    let currentSize = 0;
+    try {
+      const st = nodeFs.lstatSync(filePath);
+      currentInode = st.ino;
+      currentSize = st.size;
+    } catch {
+      // File missing — wait for it to appear.
+    }
+    if (lastInode !== null && currentInode !== null) {
+      const inodeChanged = currentInode !== lastInode;
+      const truncated = currentSize < lastSize;
+      if (inodeChanged || truncated) {
+        lastSeq = 0; // re-yield from the new file's start
+        lastInode = currentInode;
+        lastSize = currentSize;
+      }
+    } else if (currentInode !== null) {
+      // File appeared (was missing, now exists).
+      lastInode = currentInode;
+      lastSize = currentSize;
+    }
+
+    const fresh = readSince(context, lastSeq);
+    // v2.3.0 Round 2 — re-check inode AFTER readSince. The file could
+    // rotate during the read; without this we'd yield entries from the
+    // NEW file as if they were continuations of the old one (or skip
+    // them if their seq < lastSeq from the rotated file).
+    let postReadInode = null;
+    let postReadSize = 0;
+    try {
+      const st = nodeFs.lstatSync(filePath);
+      postReadInode = st.ino;
+      postReadSize = st.size;
+    } catch {
+      /* file gone — handled next iteration */
+    }
+    if (
+      lastInode !== null &&
+      postReadInode !== null &&
+      (postReadInode !== lastInode || postReadSize < lastSize)
+    ) {
+      // Rotation/truncation happened during the read. Discard the
+      // fresh batch (might be from the OLD inode), reset lastSeq to 0,
+      // and let the next iteration re-yield from the new file's start.
+      lastSeq = 0;
+      lastInode = postReadInode;
+      lastSize = postReadSize;
+      // Don't yield any of `fresh` since we can't trust which file
+      // they came from after the rotation; the next iteration's
+      // readSince(0) will pick up the new file's entries.
+      await sleep(pollIntervalMs);
+      continue;
+    }
+    if (fresh.length > 0) {
+      idleAccumulatedMs = 0;
+      for (const event of fresh) {
+        if (signal && signal.aborted) return;
+        if (typeof event.seq === 'number' && event.seq > lastSeq) {
+          lastSeq = event.seq;
+        }
+        yield event;
+      }
+      // Refresh size after yielding so the next iteration's truncation
+      // check uses the right baseline.
+      try {
+        lastSize = nodeFs.lstatSync(filePath).size;
+      } catch {
+        /* file disappeared between yield and stat — handle next loop */
+      }
+    } else {
+      idleAccumulatedMs += pollIntervalMs;
+      if (idleAccumulatedMs >= maxIdleMs) return;
+    }
+    await sleep(pollIntervalMs);
+  }
+}
+
 module.exports = {
   VALID_KINDS,
   LEDGER_FILENAME,
   append,
   read,
+  readSince,
   last,
+  tail,
   resolveLedgerPath,
 };

package/_Sprintpilot/lib/orchestrator/adapt.js

@@ -18,6 +18,34 @@ const userCommandApplier = require('./user-command-applier');
 // Threshold for `consecutive_test_failures` — workflow.md:81 says 3.
 const CONSECUTIVE_TEST_FAILURE_THRESHOLD = 3;
 
+// Threshold for the verify-loop diagnostic: when the SAME verify issues
+// repeat this many times in a row, the budget-exhausted halt prompt
+// enriches itself with a loop-detection hint (vs. a generic "rejected N
+// times" message). 3 matches verify_reject_budget for medium/large/legacy
+// profiles, so by the time the budget halts, the diagnostic is guaranteed
+// to fire if and only if the rejections were genuinely identical.
+const VERIFY_LOOP_THRESHOLD = 3;
+
+// Stable, order-independent signature of a verify issues array.
+// We compare via sorted JSON so two arrays with the same strings in
+// different order hash to the same signature (the verifier may reorder
+// internally across runs). Returns null for empty or non-array input.
+function verifyIssuesSignature(issues) {
+  if (!Array.isArray(issues) || issues.length === 0) return null;
+  // Coerce to strings, trim whitespace, then sort. The trim guards
+  // against the verifier accidentally producing trailing whitespace
+  // on one run but not another — without it, "branch required" and
+  // "branch required " would hash differently and silently break the
+  // loop detection. Trim is safe: leading/trailing whitespace in a
+  // verify-issue string is never load-bearing.
+  const strs = issues
+    .map((i) => (typeof i === 'string' ? i : JSON.stringify(i)))
+    .map((s) => s.trim())
+    .slice()
+    .sort();
+  return JSON.stringify(strs);
+}
+
 // Valid signal statuses.
 const SIGNAL_STATUSES = [
   'success',
@@ -73,28 +101,69 @@ function handleSuccess(state, signal, profile, verifyResult, sideEffects) {
   // Trust boundary: verify.js may reject what the LLM claims as success.
   if (verifyResult && verifyResult.ok === false) {
     const rejectCount = (state.verify_reject_count || 0) + 1;
+
+    // Loop detection: compare the current issues signature against the
+    // last one. Identical sets in a row → the LLM is retrying with the
+    // same broken signal. This drives the enriched halt prompt below.
+    const currentSig = verifyIssuesSignature(verifyResult.issues || []);
+    const lastSig = state.last_verify_issues_signature || null;
+    const identicalCount =
+      currentSig !== null && currentSig === lastSig
+        ? (state.consecutive_identical_rejections || 0) + 1
+        : 1;
+
     sideEffects.push({
       kind: 'log_verify_rejection',
       phase: state.phase,
       issues: verifyResult.issues || [],
       consecutive: rejectCount,
+      consecutive_identical: identicalCount,
     });
+
+    const stateWithLoopTrackers = {
+      ...state,
+      last_verify_issues_signature: currentSig,
+      consecutive_identical_rejections: identicalCount,
+    };
+
     if (rejectCount >= profile.verify_reject_budget) {
+      // Enriched diagnostic when the same issues recurred. Picks 2 as
+      // the threshold for the hint (vs. 3 for a "strong loop") because
+      // at budget exhaustion the minimum interesting case is 2 identical
+      // rejections in a row; we want the hint to fire whenever the LLM
+      // demonstrably wasn't iterating its signal between attempts.
+      const issueCount = verifyResult.issues?.length || 0;
+      const issuePlural = issueCount === 1 ? 'issue' : 'issues';
+      const timePlural = identicalCount === 1 ? 'time' : 'times';
+      const loopHint =
+        identicalCount >= 2
+          ? `\n\n⚠ Verify rejected the SAME ${issueCount} ${issuePlural} ${identicalCount} ${timePlural} in a row — this is a loop, not random noise. ` +
+            `The LLM is re-sending an identical broken signal each retry. ` +
+            `Action: read each issue text below and fix the underlying cause (e.g., if "git_steps_completed must be true — skipping git push is the most common cause", verify your git_op action actually ran \`git push\` to exit 0); don't just retry the same signal.`
+          : '';
       return {
-        newState: { ...state, verify_reject_count: 0 },
+        newState: {
+          ...stateWithLoopTrackers,
+          verify_reject_count: 0,
+          last_verify_issues_signature: null,
+          consecutive_identical_rejections: 0,
+        },
         newProfile: profile,
         nextAction: {
           type: 'user_prompt',
           phase: state.phase,
           reason: 'verify_reject_budget_exceeded',
-          prompt: `verify.js rejected ${rejectCount} consecutive success signals on ${state.phase}. Last issues: ${JSON.stringify(verifyResult.issues || [])}`,
+          prompt:
+            `verify.js rejected ${rejectCount} consecutive success signals on ${state.phase}. ` +
+            `Last issues: ${JSON.stringify(verifyResult.issues || [])}${loopHint}`,
+          consecutive_identical: identicalCount,
         },
         sideEffects,
         verdict: 'prompted',
       };
     }
     return {
-      newState: { ...state, verify_reject_count: rejectCount },
+      newState: { ...stateWithLoopTrackers, verify_reject_count: rejectCount },
       newProfile: profile,
       // Retry the same phase. adapt's caller will re-run nextAction(state, profile).
       nextAction: nextAction(state, profile),
@@ -275,9 +344,8 @@ function handleBlocked(state, signal, profile, sideEffects) {
     case 'missing_dependency':
       // Emit an abstract install action. The CLI edge (autopilot.js
       // decorateRunScript) detects the project's language(s) from
-      // manifest files and inlines the concrete `command`. Pre-2.2.19
-      // this hardcoded `npm install`, which failed on non-Node projects
-      // (Python, Rust, Go, Ruby, etc.).
+      // manifest files (package.json, pyproject.toml, Cargo.toml, etc.)
+      // and inlines the concrete `command` per language.
       return {
         newState: state,
         newProfile: profile,
@@ -413,14 +481,12 @@ function handleUserInput(state, signal, profile, sideEffects) {
   // checks all reference the wrong story.
   //
   // Phase advance: when the alternative carries `phase` and it's a
-  // valid STATES value, also advance state.phase. Pre-v2.2.6 the
-  // dispatch was one-shot — the alternative ran for ONE emission then
-  // state.phase reverted, defeating use cases like "skip dev_red /
-  // dev_green / code_review because the work is already done on the
-  // branch from a prior session." The user explicitly proposes the
-  // alternative including a target phase; they accept the consequences
-  // (e.g. verify may reject the new phase if its preconditions aren't
-  // met). Without this, accept_alternative is useless for cycle skips.
+  // valid STATES value, also advance state.phase. The user explicitly
+  // proposes the alternative including a target phase; they accept the
+  // consequences (e.g. verify may reject the new phase if its
+  // preconditions aren't met). This enables cycle skips like "jump to
+  // STORY_DONE because the work is already on the branch from a prior
+  // session."
   const dispatch = applied.sideEffects.find((e) => e && e.kind === 'dispatch_action');
   if (dispatch && dispatch.action) {
     const a = dispatch.action;
@@ -499,7 +565,17 @@ function handleVerifyOverride(state, signal, profile, verifyResult, sideEffects)
 // clears patch_findings when leaving step 6; resets per-story counters when
 // starting a new story.
 function advanceState(state, profile, newPhase, signal) {
-  const next = { ...state, phase: newPhase, retry_count_this_phase: 0, verify_reject_count: 0 };
+  const next = {
+    ...state,
+    phase: newPhase,
+    retry_count_this_phase: 0,
+    verify_reject_count: 0,
+    // v2.3.0 — phase transition clears verify-loop trackers so the next
+    // phase starts fresh. Without this a stale signature from the prior
+    // phase could artificially inflate identicalCount on the next reject.
+    last_verify_issues_signature: null,
+    consecutive_identical_rejections: 0,
+  };
   // Advancing forward clears the prior diagnosis (the LLM resolved it).
   next.prior_diagnosis = null;
 
@@ -626,5 +702,7 @@ module.exports = {
   interpretSignal,
   advanceState,
   CONSECUTIVE_TEST_FAILURE_THRESHOLD,
+  VERIFY_LOOP_THRESHOLD,
   SIGNAL_STATUSES,
+  verifyIssuesSignature,
 };

package/_Sprintpilot/lib/orchestrator/profile-rules.js

@@ -98,9 +98,6 @@ function flatToProfile(resolved, profileName) {
     // and the .timings/<story>.jsonl shards stop receiving events. Set
     // false on the `legacy` profile (no parallel coordination, no need
     // for granular timing). Default true on every other profile.
-    // Pre-2.2.26: flatToProfile didn't include this field, so
-    // `profile.phase_timings === false` was always false (undefined !==
-    // false), meaning the legacy override never took effect.
     phase_timings: coerceBool(get(resolved, 'autopilot.phase_timings'), true),
     granularity: coerceEnum(get(resolved, 'git.granularity'), VALID_GRANULARITIES, 'story'),
     worktree_enabled: coerceBool(get(resolved, 'git.worktree.enabled'), true),
@@ -180,22 +177,16 @@ function flatToProfile(resolved, profileName) {
     // --stale-minutes. 0 disables the auto-takeover entirely (locks are
     // never considered stale; manual `autopilot off` required).
     lock_stale_timeout_minutes: coerceInt(get(resolved, 'git.lock.stale_timeout_minutes'), 30),
-    // git.lint.* — documented in modules/git/config.yaml as a future
-    // post-DEV_GREEN lint phase. Currently NOT wired into the state
-    // machine (no LINT_CHECK phase emitted). v2.2.23 plumbs the config
-    // to the typed Profile so users see the shape and cmdStart emits an
-    // experimental warning when lint_enabled=true (mirroring
-    // parallel_stories handling). Full state-machine integration is
-    // tracked for v2.3.0+.
+    // git.lint.* — post-DEV_GREEN lint gate (scripts/post-green-gates.js).
+    // verifyDevGreen invokes it when lint_enabled=true; lint_blocking
+    // governs whether a failed gate rejects verify or just records.
+    // lint_output_limit caps lines of lint output per gate.
     lint_enabled: coerceBool(get(resolved, 'git.lint.enabled'), false),
     lint_blocking: coerceBool(get(resolved, 'git.lint.blocking'), false),
     lint_output_limit: coerceInt(get(resolved, 'git.lint.output_limit'), 100),
-    // git.lint.linters — per-language preference map. v2.2.28+ forwards
-    // this to lint-changed.js as --linters-json so users can reorder
-    // priorities or disable individual linters. The default-shipped
-    // priority order in lint-changed.js matches the documented config
-    // defaults, so most users see no behavior change. Setting an empty
-    // array for a language disables linting for that language entirely.
+    // git.lint.linters — per-language preference map. Forwarded to
+    // lint-changed.js as --linters-json. Empty list disables a language.
+    // javascript + typescript merge into js-ts (shared eslint/biome tooling).
     lint_linters: (() => {
       const v = get(resolved, 'git.lint.linters');
       return v && typeof v === 'object' && !Array.isArray(v) ? v : null;