@ikunin/sprintpilot 2.1.1 → 2.1.2

package/_Sprintpilot/bin/autopilot.js

@@ -128,6 +128,13 @@ function composeRuntimeState(persisted, profile) {
     user_branch: persisted.user_branch || null,
     // Land-as-you-go: pending land state survives rebase-conflict halts.
     land_pending: persisted.land_pending || null,
+    // Pending alternative (propose_alternative → user_prompt) survives
+    // across halts so the next session re-emits the prompt rather than
+    // silently dropping the LLM's proposal.
+    pending_alternative: persisted.pending_alternative || null,
+    // halt_requested is intentionally NOT carried forward here: cmdStart
+    // clears it on each new session (a `pause` cleanly halts THIS session
+    // and the next /sprint-autopilot-on resumes normally).
   };
 }
 
@@ -151,6 +158,7 @@ function persistRuntimeState(runtime, profile, projectRoot) {
     consecutive_test_failures: runtime.consecutive_test_failures,
     user_branch: runtime.user_branch,
     land_pending: runtime.land_pending,
+    pending_alternative: runtime.pending_alternative || null,
   };
   return persistState(updates, profile, projectRoot, runtime.story_key || 'sprint');
 }
@@ -272,10 +280,12 @@ function applySideEffects(sideEffects, runtime, profile, projectRoot) {
           },
           { projectRoot },
         );
-        // We log the commands; the CLI caller is responsible for actually
-        // applying them to the runtime state on the next `next` invocation.
-        // (e.g. skip_story would update sprint-status; this CLI doesn't
-        // touch sprint-status directly — that's BMad's domain.)
+        // adapt.handleUserInput now applies these commands itself (so
+        // pause halts on the same turn, accept_alternative dispatches the
+        // stored alternative, etc.). This branch is kept purely for the
+        // ledger entry — re-applying here would double-mutate state.
+        // BMad-owned mutations (e.g. skip_story → sprint-status) still
+        // live elsewhere; this CLI never touches sprint-status directly.
         break;
       }
       case 'profile_escalated':

package/_Sprintpilot/lib/orchestrator/adapt.js

@@ -13,6 +13,7 @@
 const { STATES, nextAction, nextStateAfterSuccess, nextStoryStart } = require('./state-machine');
 const { classifyImpact } = require('./impact-classifier');
 const { escalateOnFailure } = require('./profile-rules');
+const userCommandApplier = require('./user-command-applier');
 
 // Threshold for `consecutive_test_failures` — workflow.md:81 says 3.
 const CONSECUTIVE_TEST_FAILURE_THRESHOLD = 3;
@@ -328,8 +329,20 @@ function handleProposeAlternative(state, signal, profile, sideEffects) {
     };
   }
 
+  // Store the proposed alternative on state so a later `accept_alternative`
+  // user command can dispatch it. Without this, the alternative would
+  // evaporate the moment the prompt is emitted.
+  const newState = {
+    ...state,
+    pending_alternative: {
+      action: alternative,
+      impact,
+      reason: signal.reason || null,
+      prompted_at: new Date().toISOString(),
+    },
+  };
   return {
-    newState: state,
+    newState,
     newProfile: profile,
     nextAction: {
       type: 'user_prompt',
@@ -346,19 +359,59 @@ function handleProposeAlternative(state, signal, profile, sideEffects) {
 }
 
 function handleUserInput(state, signal, profile, sideEffects) {
-  // Adapt does not validate commands (that's user-commands.js' job at the CLI
-  // edge) but it does decide the structural response: a user_input signal
-  // always triggers a re-emission of nextAction under the new state. The
-  // CLI edge applies the commands first, then calls adapt with the new state.
+  // Apply the user's commands directly so the resulting state changes
+  // (halt_requested, cleared pending_alternative, dispatch_action effect)
+  // take effect on this same turn. Prior versions only emitted an
+  // apply_user_commands side-effect and the CLI never re-dispatched —
+  // pause never halted, accept_alternative had nowhere to land.
+  const commands = signal.commands || [];
+  const applied = userCommandApplier.apply(state, profile, commands);
+
+  // Mirror the legacy apply_user_commands side-effect so the ledger trail
+  // stays human-readable (kind: user_commands_applied).
   sideEffects.push({
     kind: 'apply_user_commands',
-    commands: signal.commands || [],
+    commands,
     phase: state.phase,
   });
+  for (const e of applied.sideEffects) sideEffects.push(e);
+
+  const newState = applied.newState;
+  const newProfile = applied.newProfile;
+
+  // Halt requested? Emit a halt action and let cmdRecord write the
+  // resume fingerprint.
+  if (newState.halt_requested) {
+    return {
+      newState,
+      newProfile,
+      nextAction: {
+        type: 'halt',
+        phase: newState.phase,
+        reason: newState.halt_requested.reason || 'user_pause',
+      },
+      sideEffects,
+      verdict: 'halt',
+    };
+  }
+
+  // One-shot dispatch (e.g. accept_alternative resolved a pending alt)?
+  // Return the dispatched action in place of the state-machine's default.
+  const dispatch = applied.sideEffects.find((e) => e && e.kind === 'dispatch_action');
+  if (dispatch && dispatch.action) {
+    return {
+      newState,
+      newProfile,
+      nextAction: { ...dispatch.action, _dispatched_via: dispatch.reason || 'user_input' },
+      sideEffects,
+      verdict: 'advanced',
+    };
+  }
+
   return {
-    newState: state,
-    newProfile: profile,
-    nextAction: nextAction(state, profile),
+    newState,
+    newProfile,
+    nextAction: nextAction(newState, newProfile),
     sideEffects,
     verdict: 'advanced',
   };

package/_Sprintpilot/lib/orchestrator/user-command-applier.js

@@ -61,12 +61,15 @@ function applyOne(state, profile, cmd) {
 
     case 'force_continue':
       // Clears verify-reject + retry counters so the orchestrator stops
-      // looping on a stuck transition. Phase is unchanged.
+      // looping on a stuck transition. Phase is unchanged. Also clears
+      // any pending_alternative — `force_continue` is the explicit "no,
+      // keep the planned action" answer to a propose_alternative prompt.
       newState = {
         ...state,
         retry_count_this_phase: 0,
         verify_reject_count: 0,
         consecutive_test_failures: 0,
+        pending_alternative: undefined,
       };
       effects.push({
         kind: 'state_transition',
@@ -74,6 +77,7 @@ function applyOne(state, profile, cmd) {
         to: state.phase,
         reason: 'user_force_continue',
         details: cmd.reason || null,
+        cleared_pending_alternative: !!state.pending_alternative,
       });
       break;
 
@@ -100,8 +104,19 @@ function applyOne(state, profile, cmd) {
       break;
 
     case 'pause':
-      // No state change. The CLI is expected to halt the loop and wait
-      // for the user to /sprint-autopilot-on again. Recorded for audit.
+      // Set `halt_requested` so adapt.nextAction returns a halt action
+      // on this same turn. Without this flag, prior versions of the
+      // applier only logged the halt side-effect and the orchestrator
+      // kept emitting the next planned action — the loop never stopped.
+      // `halt_requested` is cleared by `start` on the next session
+      // (same path that clears stale fingerprints on resume).
+      newState = {
+        ...state,
+        halt_requested: {
+          reason: cmd.reason || null,
+          requested_at: new Date().toISOString(),
+        },
+      };
       effects.push({
         kind: 'halt',
         reason: 'user_pause',
@@ -109,6 +124,38 @@ function applyOne(state, profile, cmd) {
       });
       break;
 
+    case 'accept_alternative': {
+      // Dispatches the orchestrator's stored `pending_alternative` (set
+      // when handleProposeAlternative escalated to a user_prompt at
+      // medium/high impact). The CLI edge / adapt's handleUserInput
+      // looks for this side-effect and uses `action` as the one-shot
+      // nextAction in place of the state-machine default.
+      const pending = state.pending_alternative;
+      if (!pending || !pending.action) {
+        effects.push({
+          kind: 'validation_error',
+          reason: 'accept_alternative: no pending alternative to accept',
+          phase: state.phase,
+          details: cmd.reason || null,
+        });
+        break;
+      }
+      newState = {
+        ...state,
+        pending_alternative: undefined,
+        retry_count_this_phase: 0,
+        verify_reject_count: 0,
+      };
+      effects.push({
+        kind: 'dispatch_action',
+        action: pending.action,
+        impact: pending.impact || null,
+        reason: 'user_accept_alternative',
+        details: cmd.reason || null,
+      });
+      break;
+    }
+
     case 'override_decision':
       // We don't apply a state mutation. The CLI records this so a
       // subsequent verify_override can reference DEC-id.

package/_Sprintpilot/lib/orchestrator/user-commands.js

@@ -7,12 +7,18 @@
 // Pure module. No I/O.
 //
 // Command kinds (initial set; new kinds added via additive PR):
-//   skip_story        { story_key: string, reason?: string }
-//   abort_sprint      { reason?: string }
-//   force_continue    { reason?: string }
-//   override_decision { decision_id: string, new_value: string }
-//   change_profile    { profile: 'nano'|'small'|'medium'|'large'|'legacy' }
-//   pause             { reason?: string }
+//   skip_story         { story_key: string, reason?: string }
+//   abort_sprint       { reason?: string }
+//   force_continue     { reason?: string }
+//   override_decision  { decision_id: string, new_value: string }
+//   change_profile     { profile: 'nano'|'small'|'medium'|'large'|'legacy' }
+//   pause              { reason?: string }
+//   accept_alternative { reason?: string }
+//     Accepts the orchestrator's most recent `propose_alternative` that
+//     was escalated to a user_prompt at medium/high impact. Dispatches
+//     the stored alternative as the next action and clears the pending
+//     entry. Validation rejects this kind when no alternative is pending
+//     in state — see user-command-applier.js for the runtime check.
 //
 // Validation returns { ok: true, command } | { ok: false, errors: string[] }.
 
@@ -27,6 +33,7 @@ const COMMAND_KINDS = [
   'override_decision',
   'change_profile',
   'pause',
+  'accept_alternative',
 ];
 
 const STORY_KEY_RE = /^[A-Za-z0-9._-]{1,64}$/;
@@ -65,7 +72,8 @@ function validateOne(cmd) {
     }
     case 'abort_sprint':
     case 'force_continue':
-    case 'pause': {
+    case 'pause':
+    case 'accept_alternative': {
       if ('reason' in cmd && cmd.reason !== undefined && typeof cmd.reason !== 'string')
         errors.push(`${cmd.kind}.reason must be string when present`);
       break;

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 2.1.1
+  version: 2.1.2
   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/skills/sprint-autopilot-on/workflow.orchestrator.md

@@ -49,8 +49,8 @@ Wrap everything in `{ "status": "...", ... }` and pass to
 | `success`             | `output?: object` (for `bmad-code-review` MUST include `findings[]` with `action: 'block'\|'patch'\|'defer'`); `next_skill_hint?` |
 | `failure`             | `reason`, `diagnosis` (first-class — fed back into next retry), `recoverable: boolean`           |
 | `blocked`             | `blocker_kind` (one of the 5 TRUE BLOCKERS or recoverable kinds), `details`, `user_input_needed`, `consecutive_count?` |
-| `propose_alternative` | `reason`, `alternative` (full Action object), `urgency_hint?` (raises impact only)               |
-| `user_input`          | `commands: UserCommand[]` (validated server-side; see user-commands.js)                          |
+| `propose_alternative` | `reason`, `alternative` (full Action object), `urgency_hint?` (raises impact only). Low impact → auto-accepted; medium / high → orchestrator stores the alternative in `state.pending_alternative` and emits `user_prompt`. The user accepts via `user_input` `{ kind: 'accept_alternative' }` or rejects via `force_continue` (both clear `pending_alternative`). |
+| `user_input`          | `commands: UserCommand[]` (validated server-side; see user-commands.js). Kinds: `skip_story`, `abort_sprint`, `force_continue`, `override_decision`, `change_profile`, `pause` (cleanly halts THIS session; next `/sprint-autopilot-on` resumes), `accept_alternative` (dispatches the stored `pending_alternative`). |
 | `verify_override`     | `evidence: { decision_log_ref?, explanation, expected_paths? }` — used when verify.js is wrong   |
 
 ## TRUE BLOCKER kinds (per AGENTS.md)

package/lib/commands/install.js

@@ -31,6 +31,8 @@ const {
 } = require('../core/markers');
 const { renderString, buildContext, isTextFile } = require('../substitute');
 const { fetchLatestVersion, compareVersions } = require('../core/update-check');
+const { mergeYamlConfig, mergeTemplateFile } = require('../core/config-merger');
+const { scanForLeftoverSnapshots } = require('../core/v2-upgrade-recovery');
 const prompts = require('../prompts');
 
 const execFileAsync = promisify(execFile);
@@ -79,6 +81,37 @@ const RUNTIME_RESOURCES = [
   'scripts',
   'templates',
 ];
+
+// Files under _Sprintpilot/ that users edit. Step 6 nukes these along
+// with everything else when copying the bundled tree; we snapshot them
+// BEFORE step 6 and restore them AFTER, using a per-file strategy:
+//
+//   strategy: 'yaml'     — line-aware merge (config-merger.mergeYamlConfig).
+//                          User scalars patched into the freshly-copied
+//                          bundled file. Bundled comments + new keys
+//                          preserved. Orphan user keys land in a footer
+//                          `# Preserved from prior install` block.
+//
+//   strategy: 'template' — skip-if-exists. If the user file differs from
+//                          bundled, keep the user version verbatim and
+//                          write bundled next door as <file>.bundled.
+const USER_OWNED_FILES = [
+  { path: 'modules/git/config.yaml', strategy: 'yaml' },
+  { path: 'modules/ma/config.yaml', strategy: 'yaml' },
+  { path: 'modules/autopilot/config.yaml', strategy: 'yaml' },
+  { path: 'modules/git/templates/pr-body.md', strategy: 'template' },
+  { path: 'modules/git/templates/commit-story.txt', strategy: 'template' },
+  { path: 'modules/git/templates/commit-patch.txt', strategy: 'template' },
+  { path: '.secrets-allowlist', strategy: 'template' },
+];
+
+// Explicit dot-path renames the installer maps when reading old user
+// configs. Empty for the 2.1.x baseline; add entries when a future
+// release renames a key so user customizations land at the new path.
+const KEY_RENAMES = Object.freeze({
+  // 'old.dotted.path': 'new.dotted.path'
+});
+
 const V1_MODULE_NAMES = ['git', 'ma', 'autopilot'];
 
 // Sentinel thrown by evictV1Installation when the user declines migration.
@@ -275,6 +308,99 @@ async function applyV1ModuleConfigs(projectRoot, snapshot) {
   return applied;
 }
 
+// Snapshot user-owned files BEFORE the destructive step-6 copy. For each
+// path in USER_OWNED_FILES that exists under targetAddonDir today, capture
+// its current content along with the strategy. Returns an array; entries
+// for files that don't exist yet (fresh installs) are simply absent.
+async function snapshotUserOwnedFiles(targetAddonDir) {
+  const out = [];
+  for (const entry of USER_OWNED_FILES) {
+    const abs = path.join(targetAddonDir, entry.path);
+    if (!(await fs.pathExists(abs))) continue;
+    try {
+      const buffer = await fs.readFile(abs);
+      out.push({ path: entry.path, strategy: entry.strategy, buffer });
+    } catch {
+      // Unreadable user file — skip; the bundled default will land.
+    }
+  }
+  return out;
+}
+
+// Apply the user-owned snapshot back over the freshly-copied bundled files,
+// using the per-file strategy. Writes are atomic via writeAtomic. Returns
+// an array of `{ path, strategy, preserved, orphans, sidecar }` describing
+// what happened for each file — the caller pretty-prints this to the user.
+async function applyUserOwnedFiles(targetAddonDir, snapshot, keyRenames = {}) {
+  const results = [];
+  for (const entry of snapshot) {
+    const abs = path.join(targetAddonDir, entry.path);
+    const userText = entry.buffer.toString('utf8');
+    let bundledText = '';
+    try {
+      bundledText = await fs.readFile(abs, 'utf8');
+    } catch {
+      // Bundled file no longer ships at this path — treat user file as
+      // an orphan: keep it as-is, no sidecar (nothing to compare against).
+      await writeAtomic(abs, entry.buffer);
+      results.push({
+        path: entry.path,
+        strategy: entry.strategy,
+        preserved: [],
+        orphans: [],
+        sidecar: false,
+        note: 'bundled file no longer ships; user copy preserved',
+      });
+      continue;
+    }
+
+    if (entry.strategy === 'yaml') {
+      const r = mergeYamlConfig(bundledText, userText, keyRenames);
+      if (r.fallback) {
+        // Merge couldn't parse — fall back to template strategy so the
+        // user doesn't lose their file. Sidecar the bundled version.
+        const t = mergeTemplateFile(bundledText, userText);
+        await writeAtomic(abs, t.text);
+        if (t.sidecar !== null) {
+          await writeAtomic(`${abs}.bundled`, t.sidecar);
+        }
+        results.push({
+          path: entry.path,
+          strategy: 'template-fallback',
+          preserved: [],
+          orphans: [],
+          sidecar: t.sidecar !== null,
+          note: 'YAML merge fell back to skip-if-exists',
+        });
+        continue;
+      }
+      await writeAtomic(abs, r.text);
+      results.push({
+        path: entry.path,
+        strategy: 'yaml',
+        preserved: r.preserved,
+        orphans: r.orphans,
+        sidecar: false,
+      });
+    } else {
+      // template strategy
+      const t = mergeTemplateFile(bundledText, userText);
+      await writeAtomic(abs, t.text);
+      if (t.sidecar !== null) {
+        await writeAtomic(`${abs}.bundled`, t.sidecar);
+      }
+      results.push({
+        path: entry.path,
+        strategy: 'template',
+        preserved: t.kept === 'user' ? ['(verbatim)'] : [],
+        orphans: [],
+        sidecar: t.sidecar !== null,
+      });
+    }
+  }
+  return results;
+}
+
 // Emergency fallback when applyV1ModuleConfigs throws: the in-memory
 // snapshot is stringified to a recovery file so the user can re-apply
 // manually after fixing whatever blocked the write. Without this the
@@ -976,6 +1102,31 @@ async function runInstall(options = {}) {
   process.stdout.write(pc.cyan(renderBanner(addonVersion)));
   console.log('');
 
+  // 0a. Recovery banner: surface any leftover backups/snapshots from a
+  //     prior installer run that may have silently clobbered user configs
+  //     before v2.1.2's preservation logic landed. Read-only; nothing is
+  //     deleted — the user decides.
+  try {
+    const leftovers = await scanForLeftoverSnapshots(projectRoot);
+    if (leftovers.length > 0) {
+      console.log(
+        pc.yellow('NOTE: detected leftover config snapshots from a prior install:'),
+      );
+      for (const f of leftovers) {
+        console.log(pc.yellow(`  - ${path.relative(projectRoot, f)}`));
+      }
+      console.log(
+        pc.yellow(
+          '  These may contain config you customized but lost during a prior upgrade.',
+        ),
+      );
+      console.log(pc.yellow('  Review before deleting.'));
+      console.log('');
+    }
+  } catch {
+    // Non-fatal — banner is purely informational.
+  }
+
   // 1. Verify BMad Method installed
   const bmadManifest = await verifyBmadInstalled(projectRoot);
   if (!bmadManifest) {
@@ -1216,6 +1367,12 @@ async function runInstall(options = {}) {
   if (dryRun) {
     console.log(pc.dim(`[DRY RUN] Would copy runtime resources to ${targetAddonDir}`));
   } else {
+    // 6-pre. Snapshot user-owned files BEFORE the destructive copy. On a
+    //        fresh install the snapshot is empty; on upgrade it captures
+    //        config.yaml edits, template customizations, and the secrets
+    //        allowlist so they can be re-applied after step 6.
+    const userOwnedSnapshot = await snapshotUserOwnedFiles(targetAddonDir);
+
     await fs.ensureDir(targetAddonDir);
     for (const item of RUNTIME_RESOURCES) {
       const src = path.join(ADDON_DIR, item);
@@ -1279,6 +1436,42 @@ async function runInstall(options = {}) {
     //     so the existing upgrade test coverage (readExistingAutopilotConfig /
     //     patchAutopilotConfig) is unaffected by the new key.
     await patchComplexityProfile(projectRoot, complexityProfile);
+
+    // 6d. Re-apply the user-owned snapshot taken before step 6. YAML configs
+    //     get a line-aware merge (user scalars patched into the freshly
+    //     copied bundled file, comments preserved, new bundled keys land).
+    //     Templates fall back to skip-if-exists with a .bundled sidecar.
+    //     Runs AFTER 6a (v1 reapply) and AFTER 6b / 6c so prompt-resolved
+    //     autopilot values are not overwritten by a stale snapshot.
+    if (userOwnedSnapshot.length > 0) {
+      const merged = await applyUserOwnedFiles(targetAddonDir, userOwnedSnapshot, KEY_RENAMES);
+      let anySidecar = false;
+      for (const r of merged) {
+        const detail =
+          r.strategy === 'yaml' && r.preserved.length > 0
+            ? ` (preserved ${r.preserved.length} setting${r.preserved.length === 1 ? '' : 's'})`
+            : r.strategy === 'template' && r.preserved.length > 0
+              ? ' (kept user version)'
+              : '';
+        console.log(`  Preserved ${r.path}${detail}`);
+        if (r.note) console.log(pc.dim(`    note: ${r.note}`));
+        if (r.orphans && r.orphans.length > 0) {
+          console.log(
+            pc.dim(`    orphan keys appended to file footer: ${r.orphans.join(', ')}`),
+          );
+        }
+        if (r.sidecar) anySidecar = true;
+      }
+      if (anySidecar) {
+        console.log('');
+        console.log(
+          pc.yellow(
+            '  Some bundled defaults were written next to user files as .bundled sidecars.',
+          ),
+        );
+        console.log(pc.yellow('  Diff them by hand to pick up new options.'));
+      }
+    }
   }
 
   // 7. Verify git check-ignore
@@ -1380,5 +1573,9 @@ module.exports = {
     COMPLEXITY_PROFILES,
     DEFAULT_COMPLEXITY_PROFILE,
     RUNTIME_RESOURCES,
+    USER_OWNED_FILES,
+    KEY_RENAMES,
+    snapshotUserOwnedFiles,
+    applyUserOwnedFiles,
   },
 };

package/lib/core/config-merger.js

@@ -0,0 +1,238 @@
+// config-merger.js — preserve user edits when the installer rewrites
+// _Sprintpilot/ on upgrade.
+//
+// Two strategies, picked per-file in `lib/commands/install.js`:
+//
+//   mergeYamlConfig(bundledText, userText, keyRenames)
+//     For modules/*/config.yaml. Bundled file is freshly copied. We
+//     parse both files into flat dot-path → scalar maps, compute the
+//     user-customized set (paths whose user value differs from bundled
+//     default OR doesn't exist in bundled), and patch each customization
+//     back into the bundled text by line-substitution. Bundled inline
+//     comments and section structure are preserved verbatim.
+//
+//   mergeTemplateFile(bundledText, userText)
+//     For free-form templates (.md / .txt / .secrets-allowlist) where
+//     line-based YAML merging doesn't apply. If user file exists and
+//     differs from bundled, keep the user file; the caller writes the
+//     bundled version next door as a .bundled sidecar so the user can
+//     diff and merge by hand.
+//
+// Both functions are pure. They never read or write disk; the caller
+// (applyUserOwnedFiles in install.js) owns I/O via writeAtomic.
+
+// -----------------------------------------------------------------------------
+// YAML scalar/path parsing
+// -----------------------------------------------------------------------------
+
+// One non-empty, non-comment line of the form:
+//   <indent><key>: [value][ # trailing-comment]
+// Captures: indent, key, value-with-optional-trailing-comment.
+const KV_RE = /^(?<indent>\s*)(?<key>[A-Za-z_][\w-]*):\s*(?<rest>.*)$/;
+const COMMENT_ONLY_RE = /^\s*#/;
+const BLANK_RE = /^\s*$/;
+
+function isBlank(line) {
+  return BLANK_RE.test(line);
+}
+
+function isCommentOnly(line) {
+  return COMMENT_ONLY_RE.test(line);
+}
+
+// Split a value-and-maybe-trailing-comment chunk (the `rest` capture above)
+// into { value, trailing } where `trailing` is everything from the first
+// unquoted `#` onward (with its leading whitespace). YAML inline comments
+// require whitespace before the `#`, which `KV_RE` already enforces by
+// matching the colon-then-whitespace before `rest`.
+function splitInlineComment(rest) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < rest.length; i++) {
+    const ch = rest[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === '#' && !inSingle && !inDouble) {
+      // YAML requires whitespace before `#` for an inline comment.
+      if (i === 0 || /\s/.test(rest[i - 1])) {
+        return { value: rest.slice(0, i).trimEnd(), trailing: rest.slice(i) };
+      }
+    }
+  }
+  return { value: rest.trimEnd(), trailing: '' };
+}
+
+// Parse a YAML-ish file into a flat map of dot-paths → string values.
+// Lines that don't match `KV_RE` are ignored. Container lines (`key:`
+// with empty value followed by deeper-indented children) are tracked
+// via an indent stack so dot-paths nest correctly. Throws on malformed
+// indentation; the caller catches and falls back to template strategy.
+function parseFlat(text) {
+  const lines = text.split(/\r?\n/);
+  const stack = []; // [{ indent: number, key: string }]
+  const out = Object.create(null);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isBlank(line) || isCommentOnly(line)) continue;
+    const m = line.match(KV_RE);
+    if (!m) continue; // list items, multi-line strings, etc. — not in our scope
+    const indent = m.groups.indent.length;
+    const key = m.groups.key;
+    const { value } = splitInlineComment(m.groups.rest);
+    // Pop deeper-or-equal scopes off the stack.
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    const path = [...stack.map((s) => s.key), key].join('.');
+    if (value.length === 0) {
+      // Container — push and continue. Don't record an empty scalar.
+      stack.push({ indent, key });
+    } else {
+      out[path] = value;
+    }
+  }
+  return out;
+}
+
+// Patch a single scalar value at the given dot-path into the bundled
+// text. Returns the new text. If the path can't be found, returns the
+// text unchanged (the caller decides whether to append the orphan).
+function patchScalarInPlace(text, dotPath, newValue) {
+  const targetSegments = dotPath.split('.');
+  const lines = text.split(/\r?\n/);
+  const stack = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isBlank(line) || isCommentOnly(line)) continue;
+    const m = line.match(KV_RE);
+    if (!m) continue;
+    const indent = m.groups.indent.length;
+    const key = m.groups.key;
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    const currentPath = [...stack.map((s) => s.key), key];
+    const isContainer = m.groups.rest.length === 0;
+    if (isContainer) {
+      stack.push({ indent, key });
+      continue;
+    }
+    if (
+      currentPath.length === targetSegments.length &&
+      currentPath.every((seg, idx) => seg === targetSegments[idx])
+    ) {
+      const { trailing } = splitInlineComment(m.groups.rest);
+      const sep = trailing ? ' ' : '';
+      lines[i] = `${m.groups.indent}${key}: ${newValue}${sep}${trailing}`;
+      return lines.join('\n');
+    }
+  }
+  return text; // not found — caller may append as orphan
+}
+
+// -----------------------------------------------------------------------------
+// Public: mergeYamlConfig
+// -----------------------------------------------------------------------------
+
+/**
+ * Merge user YAML into freshly-copied bundled YAML, preserving the
+ * bundled file's structure and inline comments.
+ *
+ * @param {string} bundledText - the freshly-copied bundled file contents
+ * @param {string} userText - the user's pre-upgrade contents
+ * @param {Object<string, string>} keyRenames - { 'old.path': 'new.path' }
+ * @returns {{ text: string, preserved: string[], orphans: string[], fallback: boolean }}
+ *   text: merged file text to write
+ *   preserved: dot-paths whose user value was patched into the bundled text
+ *   orphans: dot-paths present only in user (appended as a footer block)
+ *   fallback: true if parse failed and we returned bundledText unchanged
+ */
+function mergeYamlConfig(bundledText, userText, keyRenames = {}) {
+  if (typeof bundledText !== 'string' || typeof userText !== 'string') {
+    return { text: bundledText || '', preserved: [], orphans: [], fallback: true };
+  }
+  let bundledMap;
+  let userMap;
+  try {
+    bundledMap = parseFlat(bundledText);
+    userMap = parseFlat(userText);
+  } catch {
+    return { text: bundledText, preserved: [], orphans: [], fallback: true };
+  }
+
+  // Apply renames before computing the diff: a user key at `old.path`
+  // is treated as if it sat at `new.path`.
+  const renamed = Object.create(null);
+  for (const [k, v] of Object.entries(userMap)) {
+    const remapped = Object.hasOwn(keyRenames, k) ? keyRenames[k] : k;
+    renamed[remapped] = v;
+  }
+
+  let text = bundledText;
+  const preserved = [];
+  const orphans = [];
+
+  for (const [path, userValue] of Object.entries(renamed)) {
+    const bundledValue = bundledMap[path];
+    if (bundledValue === userValue) continue; // no customization
+    if (bundledValue === undefined) {
+      orphans.push(path);
+      continue;
+    }
+    const next = patchScalarInPlace(text, path, userValue);
+    if (next === text) {
+      // Path exists in bundled map but couldn't be re-located — treat as
+      // orphan rather than silently dropping the user value.
+      orphans.push(path);
+    } else {
+      text = next;
+      preserved.push(path);
+    }
+  }
+
+  if (orphans.length > 0) {
+    // Append as a clearly-labeled footer block so the user notices and
+    // can re-integrate or delete by hand. Use a `# Preserved` header
+    // followed by literal `key: value` lines — these will round-trip
+    // through `parseFlat` on the next upgrade.
+    const footer = [
+      '',
+      '# Preserved from prior install — verify these still apply:',
+      ...orphans.map((p) => `# ${p}: ${renamed[p]}`),
+      '',
+    ].join('\n');
+    text = text.endsWith('\n') ? text + footer : text + '\n' + footer;
+  }
+
+  return { text, preserved, orphans, fallback: false };
+}
+
+// -----------------------------------------------------------------------------
+// Public: mergeTemplateFile
+// -----------------------------------------------------------------------------
+
+/**
+ * For free-form template files (.md / .txt / .secrets-allowlist).
+ *
+ * @param {string} bundledText - freshly-copied bundled contents
+ * @param {string|null} userText - user's pre-upgrade contents, or null/undefined if absent
+ * @returns {{ kept: 'user' | 'bundled', text: string, sidecar: string | null }}
+ *   When kept === 'user', `text` is the user contents and `sidecar` is the
+ *   bundled contents (caller writes it as <file>.bundled). When kept ===
+ *   'bundled', `text` is the bundled contents and `sidecar` is null.
+ */
+function mergeTemplateFile(bundledText, userText) {
+  const bundled = typeof bundledText === 'string' ? bundledText : '';
+  const user = typeof userText === 'string' ? userText : '';
+  if (user.length === 0 || user === bundled) {
+    return { kept: 'bundled', text: bundled, sidecar: null };
+  }
+  return { kept: 'user', text: user, sidecar: bundled };
+}
+
+module.exports = {
+  mergeYamlConfig,
+  mergeTemplateFile,
+  // Exported for tests only.
+  _internals: { parseFlat, patchScalarInPlace, splitInlineComment },
+};

package/lib/core/v2-upgrade-recovery.js

@@ -0,0 +1,47 @@
+// v2-upgrade-recovery.js — detect leftover snapshot/backup files from
+// prior installer runs that may have silently clobbered user configs.
+//
+// Used at the top of `runInstall` to print a banner pointing the user
+// at recoverable data. Returns paths only; the installer never deletes
+// these — the user decides when they've been restored or are safe to
+// discard.
+
+const path = require('node:path');
+const fs = require('fs-extra');
+
+// Patterns we scan for, relative to projectRoot:
+//   - *.bak-sprintpilot-migration*       (legacy marker strip backups)
+//   - .sprintpilot-v1-snapshot*.json     (v1 module-config recovery dumps)
+//
+// Both are written today by the v1→v2 migration path (lib/commands/install.js
+// pickBackupPath + persistSnapshotForRecovery). The same pattern could end
+// up triggered if a future installer hits a write failure mid-merge.
+
+const BACKUP_GLOB = /\.bak-sprintpilot-migration/;
+const SNAPSHOT_GLOB = /^\.sprintpilot-v1-snapshot.*\.json$/;
+
+async function scanForLeftoverSnapshots(projectRoot) {
+  const out = [];
+  // Top-level scan only (non-recursive). The two patterns are always
+  // written at the project root or alongside the file they backed up.
+  try {
+    const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (SNAPSHOT_GLOB.test(entry.name) || BACKUP_GLOB.test(entry.name)) {
+        out.push(path.join(projectRoot, entry.name));
+      }
+    }
+  } catch {
+    // projectRoot unreadable — caller can't act on the banner anyway.
+    return out;
+  }
+
+  // Also scan a couple of well-known directories where backup files
+  // accumulate (AGENTS.md.bak-sprintpilot-migration is at root, but
+  // .clinerules.bak-... could live wherever the rules file lives).
+  // For now, root-only is enough — extend if real reports surface.
+  return out;
+}
+
+module.exports = { scanForLeftoverSnapshots };

package/package.json

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