specflow-cc 1.19.0 → 1.20.1

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to SpecFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.20.1] - 2026-05-14
+
+### Fixed
+
+- **INDEX.md staleness across all TODO-mutating paths** — `1.19.0` wired the `todo reindex` helper into `/sf:todo` and `/sf:done`, but every other command that mutates `.specflow/todos/` (`/sf:plan` `rm`, `/sf:triage` create, `/sf:revise` deferred-TODO creation, `/sf:priority` priority edits, `/sf:migrate-todos`, and the `sf-spec-reviser` agent) still left INDEX.md silently out of sync. All of these now invoke `node bin/sf-tools.cjs todo reindex` after the mutation. `/sf:todos` no longer writes INDEX.md inline — it delegates to the same helper, making the reindex routine the single source of truth for INDEX layout.
+
+### Added
+
+- **`todo check-stale` CLI subcommand** in `bin/sf-tools.cjs` — compares the set of `TODO-*.md` files on disk to the set of IDs in `INDEX.md` and returns `{stale, index_exists, todo_count, index_count, missing_from_index, extra_in_index}`. Used by `/sf:status` as a safety-net freshness check: if any drift is detected (external edits, manual `rm`, a missed helper call), `/sf:status` surfaces an "INDEX.md stale" warning naming the specific divergences. No auto-fix — the user re-runs `/sf:todos` or the helper.
+- 9 new tests in `tests/todo-index.test.cjs` covering reindex idempotency, header content, drop-after-delete, and all `check-stale` scenarios (fresh, extra-in-index, missing-from-index, no-INDEX-with-files, empty-both, raw output).
+
+### Changed
+
+- **INDEX.md header text** rewritten to describe actual behaviour. Old wording ("Auto-generated from individual TODO files. Do not edit manually. Regenerate with `/sf:todos`.") implied a self-maintaining file. New wording: "Cache of individual TODO files. Refreshed when `/sf:todos` runs OR when an INDEX-mutating command explicitly invokes the regen helper (`node bin/sf-tools.cjs todo reindex`). Do not edit manually — changes will be overwritten on the next regen." Applied in both `bin/lib/todo.cjs` (the source of truth) and `templates/todo-index.md`.
+
+## [1.20.0] - 2026-05-02
+
+### Added
+
+- **Parallel specification execution** — STATE.md now supports multiple active specifications in a `## Active Specifications` table (multi-row registry), enabling concurrent work across separate Claude Code sessions
+  - Run two specs in parallel: open a second session and either `/sf:next` or `/sf:run SPEC-XXX` — each session resolves its own target
+  - Single-spec workflows are unchanged: when only one spec is active, no command requires a SPEC-ID argument
+- **Advisory file-rename lock** — new `bin/lib/lock.cjs` exposes `withStateLock(fn)` to serialize STATE.md read-modify-write across concurrent processes. Uses Node's built-in `fs.openSync(path, 'wx')` + atomic-rename pattern — no native `flock(2)`, no shell-out, no new runtime dependencies. Per-process reentrancy via module-scope `_depth` counter; cross-process exclusivity via the `wx` flag
+  - Includes EPERM-aware stale-PID detection (`isProcessAlive` treats EPERM as alive per POSIX semantics)
+- **Centralized spec resolution** — new `bin/lib/resolve.cjs` and `node bin/sf-tools.cjs state resolve [SPEC-ID]` CLI. All 15 spec-touching commands now resolve their target spec through this single helper. Returns one of four JSON shapes:
+  - `{action: "use", id: "SPEC-XXX"}` — N=1 implicit or explicit-match
+  - `{action: "ask", options: [...]}` — N>1 with no SPEC-ID provided (commands present an `AskUserQuestion` picker)
+  - `{action: "error", code: "NO_ACTIVE_SPEC"}` — N=0
+  - `{action: "error", code: "SPEC_NOT_ACTIVE"}` — explicit SPEC-ID not in active table
+- **Idempotent legacy migration** — new `bin/lib/migrate-state.cjs` upgrades old `Active Specification` / `Status` / `Next Step` triples to the new `## Active Specifications` table. Handles both heading-style and bullet-style legacy fixtures. Invoked on `/sf:health` entry; second run is zero-diff
+- **New `state` subcommands** — `state list-active`, `state add-active <id> <status> <next>`, `state remove-active <id>`, `state resolve [id?]`, `state migrate`. Legacy `state get` and `state set-active` shims preserved for backwards compatibility
+- **`/sf:autopilot` N>1 guard** — autopilot fails fast with an explicit message when more than one spec is active and no SPEC-ID is provided (no auto-pick, no `AskUserQuestion`). The `--all` flag does NOT override this guard; multi-spec autopilot iteration is intentionally out of scope
+- 38 new tests across `test/lock.test.cjs`, `test/resolve.test.cjs`, `test/migrate.test.cjs`, `test/integration.test.cjs` — covering reentrancy, concurrent-write convergence (two child processes), all 5 resolution scenarios, both legacy formats, and end-to-end CLI flows. Full suite: 43 tests pass under Node 22's default parallel runner
+
+### Changed
+
+- **All 15 spec-touching commands** now use `state resolve` instead of inline STATE.md parsing: `audit`, `autopilot`, `discuss`, `done`, `fix`, `health`, `help`, `pause`, `review`, `revise`, `run`, `show`, `split`, `status`, `verify`. STATE.md mutations route through `state add-active` / `state remove-active`
+- **`templates/state.md`** — replaced single-spec `Active Specification` / `Status` / `Next Step` block with `## Active Specifications` table (`| SPEC-ID | Status | Next Step |`)
+- **All STATE.md writes** — every mutator in `bin/lib/state.cjs` now wraps writes in `withStateLock(...)`. The grep contract `writeFile*(STATE.md, ...)` outside `bin/lib/lock.cjs` returns zero hits; this is enforced by a top-of-file comment in `lock.cjs`
+
+### Fixed
+
+- **Atomic STATE.md writes** — pre-existing torn-file risk addressed: STATE.md writes now use the temp-file + rename pattern, eliminating partial reads under concurrent access (commit `e674656`)
+
+### Migration notes
+
+Existing projects with the legacy STATE.md schema are migrated automatically on the next `/sf:health` invocation. No manual steps required. Single-spec workflows continue to work without any user-visible change.
+
 ## [1.19.0] - 2026-04-12
 
 ### Added

package/README.md

@@ -64,6 +64,7 @@ SpecFlow fixes this with **Fresh Context Auditing**:
 | **Quality Control** | Self-correction (biased) | Independent Auditor (unbiased) |
 | **Verification** | "Looks good to me" | Verified against contract |
 | **Execution** | Linear, single agent | Atomic waves, parallel agents |
+| **Concurrency** | One task at a time | Multiple specs in parallel sessions |
 | **Result** | Hidden bugs ship | Issues caught before code exists |
 
 > The auditor has no memory of your conversation. It only sees the spec. If the spec says "use the flux capacitor API" — the auditor asks "what is that?"
@@ -433,7 +434,7 @@ Use `max` for maximum quality everywhere, `quality` for critical features, `budg
 ```
 .specflow/
 ├── PROJECT.md      # Project context (patterns, conventions)
-├── STATE.md        # Current state and queue
+├── STATE.md        # Multi-active state and queue (parallel-safe)
 ├── config.json     # Settings
 ├── specs/          # Active specifications
 ├── research/       # Research documents
@@ -465,6 +466,13 @@ Use `max` for maximum quality everywhere, `quality` for critical features, `budg
 # Or skip manual steps — run everything autonomously
 /sf:autopilot                            # Process active spec end-to-end
 /sf:autopilot --all                      # Process entire queue
+
+# Parallel sessions (since 1.20.0)
+# Session A:
+/sf:run SPEC-042                         # Work on one spec
+# Session B (separate Claude Code window, same project):
+/sf:run SPEC-043                         # Work on a different spec concurrently
+# STATE.md is locked per-write — no torn files, both rows visible
 ```
 
 ---

package/agents/spec-reviser.md

@@ -176,7 +176,13 @@ For each deferred item:
 - TODO-{XXX} — {item description}
 ```
 
-**Important:** This step is mandatory. Every deferred item MUST produce a TODO. If TODO creation fails, report the failure — do not silently skip.
+4. After the loop completes (at least one TODO created), refresh the INDEX.md cache so it reflects the newly-created files:
+
+```bash
+node bin/sf-tools.cjs todo reindex
+```
+
+**Important:** Both substeps are mandatory. Every deferred item MUST produce a TODO, and if any TODO is created the reindex helper MUST run before reporting completion. Skipping the reindex leaves `.specflow/todos/INDEX.md` missing the just-created entries, which the `/sf:status` freshness check will then flag. If TODO creation fails, report the failure — do not silently skip.
 
 ## Step 6: Update Frontmatter
 
@@ -245,6 +251,7 @@ Tip: `/clear` recommended — auditor needs fresh context
 - [ ] Revision Response recorded in Audit History
 - [ ] Deferred items (if any) created as individual `.specflow/todos/TODO-XXX.md` files
 - [ ] TODOs Created subsection appended to Response (if deferred items exist)
+- [ ] INDEX.md refreshed via `node bin/sf-tools.cjs todo reindex` (if any TODO was created)
 - [ ] Frontmatter status updated
 - [ ] STATE.md updated
 - [ ] Clear summary of changes provided

package/bin/lib/core.cjs

@@ -94,6 +94,31 @@ function parseFrontmatter(content) {
   return { frontmatter, body };
 }
 
+/**
+ * Atomically write a file via tmp + rename. Prevents torn writes if the
+ * process is interrupted mid-write, and prevents readers (e.g. the statusline
+ * hook) from observing a half-written file when a command writes concurrently.
+ *
+ * Note: this does NOT prevent the read-modify-write race between two writers
+ * (both read old state, both write, second wins). For SpecFlow's interactive
+ * single-session model that race is rare; preventing torn files is the goal.
+ *
+ * @param {string} filePath - Absolute path to write
+ * @param {string} content - File contents (utf8)
+ */
+function atomicWrite(filePath, content) {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const tmpPath = path.join(dir, '.' + base + '.tmp.' + process.pid + '.' + Date.now());
+  try {
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, filePath);
+  } catch (e) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    throw e;
+  }
+}
+
 /**
  * Generate a URL-safe slug from text.
  * Lowercase, replace spaces/special chars with hyphens, collapse multiples, trim edges.
@@ -115,6 +140,7 @@ module.exports = {
   output,
   error,
   safeReadFile,
+  atomicWrite,
   parseFrontmatter,
   generateSlug,
 };

package/bin/lib/lock.cjs

@@ -0,0 +1,213 @@
+/**
+ * bin/lib/lock.cjs — Advisory file-rename lock for STATE.md mutations
+ *
+ * IMPORTANT: AC 14 grep contract
+ * All fs.writeFileSync / fs.writeFile calls targeting .specflow/STATE.md MUST go
+ * through withStateLock() in THIS file. Verified by:
+ *   grep -rn 'writeFileSync.*STATE\.md\|writeFile.*STATE\.md' \
+ *     $(find bin -name '*.cjs') | grep -v lock.cjs
+ * must return zero hits. If this file is renamed, update that grep pattern everywhere
+ * it is referenced (CI checks, SPEC-011 acceptance criteria).
+ *
+ * Exports: withStateLock(asyncFn) → Promise<*>
+ *
+ * Lock mechanics:
+ *   - Lock file: .specflow/.state.lock
+ *   - Acquisition: fs.openSync(lockPath, 'wx') — exclusive create (atomic on POSIX + macOS + WSL)
+ *   - On EEXIST: read lock file PID, send signal 0 to check liveness, clear stale lock if dead
+ *   - Retry with exponential backoff, max 5 seconds total
+ *   - Release: fs.unlinkSync(lockPath)
+ *
+ * Reentrancy (within one Node process):
+ *   - Module-scope _depth counter tracks nest level
+ *   - Outer call acquires OS lock and increments _depth to 1
+ *   - Inner (reentrant) calls from the same process increment _depth and skip OS re-acquire
+ *   - On release, decrement _depth; OS lock released only when _depth reaches 0
+ *   - This is single-Node-process only — no worker_threads support
+ *   - Cross-process exclusion is provided by the OS exclusive-create
+ *
+ * No new runtime dependencies — uses only built-in `fs` and `process`.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Module-scope reentrancy counter (single-process only)
+let _depth = 0;
+let _lockFd = null;
+
+const LOCK_TIMEOUT_MS = 5000;
+const RETRY_BASE_MS = 10;
+const RETRY_MAX_MS = 200;
+
+/**
+ * Resolve the lock file path relative to cwd.
+ * @returns {string}
+ */
+function getLockPath() {
+  return path.join(process.cwd(), '.specflow', '.state.lock');
+}
+
+/**
+ * Write PID to the lock file descriptor.
+ * @param {number} fd - Open file descriptor
+ */
+function writePid(fd) {
+  const pidStr = String(process.pid);
+  fs.writeSync(fd, pidStr);
+}
+
+/**
+ * Read the PID from an existing lock file.
+ * Returns null if file cannot be read or doesn't contain a valid PID.
+ * @param {string} lockPath
+ * @returns {number|null}
+ */
+function readLockPid(lockPath) {
+  try {
+    const content = fs.readFileSync(lockPath, 'utf8').trim();
+    const pid = parseInt(content, 10);
+    return isNaN(pid) ? null : pid;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Check if a process with the given PID is alive using signal 0.
+ * Returns true if alive, false if dead or inaccessible.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM = process exists but is owned by another user — still alive
+    if (e.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+/**
+ * Attempt to clear a stale lock file.
+ * Safe to call even if the file no longer exists.
+ * @param {string} lockPath
+ */
+function clearStaleLock(lockPath) {
+  try {
+    fs.unlinkSync(lockPath);
+  } catch (_) {
+    // Ignore — another process may have cleared it already
+  }
+}
+
+/**
+ * Acquire the advisory file-rename lock.
+ * Blocks (via async polling) until acquired or timeout exceeded.
+ * @param {string} lockPath
+ * @returns {Promise<number>} Resolved file descriptor
+ * @throws {Error} If lock cannot be acquired within timeout
+ */
+async function acquireLock(lockPath) {
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let retryMs = RETRY_BASE_MS;
+
+  while (true) {
+    try {
+      // Exclusive create — atomic on POSIX, macOS, and WSL
+      const fd = fs.openSync(lockPath, 'wx');
+      writePid(fd);
+      return fd;
+    } catch (e) {
+      if (e.code !== 'EEXIST') {
+        throw e;
+      }
+
+      // Lock file exists — check for stale lock
+      const ownerPid = readLockPid(lockPath);
+      if (ownerPid !== null && !isProcessAlive(ownerPid)) {
+        // Owner is dead — clear stale lock and retry immediately
+        clearStaleLock(lockPath);
+        continue;
+      }
+
+      // Lock is held by a live process — check timeout
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `withStateLock: could not acquire .state.lock within ${LOCK_TIMEOUT_MS}ms ` +
+          `(held by PID ${ownerPid ?? 'unknown'})`
+        );
+      }
+
+      // Exponential backoff
+      await sleep(retryMs);
+      retryMs = Math.min(retryMs * 2, RETRY_MAX_MS);
+    }
+  }
+}
+
+/**
+ * Release the advisory lock.
+ * @param {string} lockPath
+ * @param {number} fd - File descriptor to close
+ */
+function releaseLock(lockPath, fd) {
+  try {
+    fs.closeSync(fd);
+  } catch (_) {}
+  try {
+    fs.unlinkSync(lockPath);
+  } catch (_) {}
+}
+
+/**
+ * Simple promise-based sleep.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Execute asyncFn inside the advisory STATE.md lock.
+ *
+ * Reentrant within one Node process: if this process already holds the lock
+ * (_depth > 0), the inner call simply executes without re-acquiring.
+ *
+ * @param {Function} asyncFn - Async function to execute under lock
+ * @returns {Promise<*>} Result of asyncFn
+ */
+async function withStateLock(asyncFn) {
+  const lockPath = getLockPath();
+
+  if (_depth > 0) {
+    // Already holding the lock in this process — reentrant call
+    _depth++;
+    try {
+      return await asyncFn();
+    } finally {
+      _depth--;
+    }
+  }
+
+  // Outer call — acquire OS lock
+  _lockFd = await acquireLock(lockPath);
+  _depth = 1;
+
+  try {
+    return await asyncFn();
+  } finally {
+    _depth--;
+    if (_depth === 0) {
+      releaseLock(lockPath, _lockFd);
+      _lockFd = null;
+    }
+  }
+}
+
+module.exports = { withStateLock };

package/bin/lib/migrate-state.cjs

@@ -0,0 +1,242 @@
+/**
+ * bin/lib/migrate-state.cjs — One-shot idempotent STATE.md schema migration
+ *
+ * Exports: migrateStateMd(content) → string
+ *
+ * Transforms legacy STATE.md formats to the new `## Active Specifications` table schema.
+ *
+ * Handles TWO known legacy formats:
+ *
+ *   Format A (real STATE.md — heading-style):
+ *     ## Active Specification
+ *
+ *     SPEC-XXX
+ *
+ *     **Status:** running
+ *     **Next Step:** /sf:review
+ *
+ *   Format B (templates/state.md — bullet-style):
+ *     - **Active Specification:** [none | SPEC-XXX]
+ *     - **Status:** ...
+ *     - **Next Step:** ...
+ *
+ * Idempotent: if `## Active Specifications` (plural, table) already present,
+ * returns content unchanged.
+ *
+ * The caller is responsible for writing the result back to disk (under withStateLock).
+ * Invoked from:
+ *   - `node bin/sf-tools.cjs state migrate`  (explicit)
+ *   - `/sf:health` on entry (implicit)
+ *   - `node bin/sf-tools.cjs state list-active` (lazy safety net on first read)
+ */
+
+'use strict';
+
+/**
+ * Build the new Active Specifications table section, optionally seeded with
+ * one row if we detected a non-"none" spec ID.
+ *
+ * @param {string|null} specId - Detected legacy spec ID, or null/empty/"none"
+ * @param {string|null} status - Legacy status value
+ * @param {string|null} nextStep - Legacy next step value
+ * @returns {string} New section text (no trailing newline)
+ */
+function buildNewSection(specId, status, nextStep) {
+  const hasSpec = specId && specId.toLowerCase() !== 'none' && specId !== '—' && specId !== '-';
+
+  let table =
+    '## Active Specifications\n' +
+    '\n' +
+    '| SPEC-ID | Status | Next Step |\n' +
+    '|---------|--------|-----------|';
+
+  if (hasSpec) {
+    const rowStatus = status || 'running';
+    const rowNext = nextStep || '/sf:review';
+    table += '\n| ' + specId + ' | ' + rowStatus + ' | ' + rowNext + ' |';
+  }
+
+  return table;
+}
+
+/**
+ * Migrate a STATE.md from legacy format to the new Active Specifications table.
+ *
+ * Pure function — does NOT read or write files.
+ *
+ * @param {string} content - Current STATE.md file content
+ * @returns {string} Migrated content (unchanged if already new format)
+ */
+function migrateStateMd(content) {
+  if (!content || typeof content !== 'string') {
+    return content || '';
+  }
+
+  // Idempotency check: if new schema already present, return unchanged
+  if (content.includes('## Active Specifications')) {
+    return content;
+  }
+
+  const lines = content.split('\n');
+
+  // ─── Format A detection: "## Active Specification" heading-style ──────────
+  // Pattern:
+  //   ## Active Specification
+  //   <blank>
+  //   SPEC-XXX           (or "—" / empty)
+  //   <blank>
+  //   **Status:** ...
+  //   **Next Step:** ...
+
+  const formatAIdx = lines.findIndex(l => l.trim() === '## Active Specification');
+
+  if (formatAIdx !== -1) {
+    return migrateFormatA(lines, formatAIdx);
+  }
+
+  // ─── Format B detection: bullet-style "## Current Position" or inline bullets ─
+  // Pattern:
+  //   - **Active Specification:** [none | SPEC-XXX]
+  //   - **Status:** ...
+  //   - **Next Step:** ...
+
+  const bulletIdx = lines.findIndex(l => /^\s*-\s+\*\*Active Specification:\*\*/.test(l));
+
+  if (bulletIdx !== -1) {
+    return migrateFormatB(lines, bulletIdx);
+  }
+
+  // Unknown format — return unchanged (safe fallback)
+  return content;
+}
+
+/**
+ * Migrate Format A (heading-style) STATE.md.
+ *
+ * @param {string[]} lines
+ * @param {number} headingIdx - Line index of "## Active Specification"
+ * @returns {string}
+ */
+function migrateFormatA(lines, headingIdx) {
+  let specId = null;
+  let status = null;
+  let nextStep = null;
+
+  // Scan forward from heading to collect values (stop at next ## or end)
+  let sectionEnd = lines.length;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+
+    if (trimmed.startsWith('## ') && i !== headingIdx) {
+      sectionEnd = i;
+      break;
+    }
+
+    // Spec ID line: non-empty, not a bold field, not a comment
+    if (trimmed && !trimmed.startsWith('**') && !trimmed.startsWith('#') && !trimmed.startsWith('<!--')) {
+      if (!specId) specId = trimmed;
+    }
+
+    // Bold field: **Status:** value
+    const statusMatch = trimmed.match(/^\*\*Status:\*\*\s*(.+)$/);
+    if (statusMatch) status = statusMatch[1].trim();
+
+    const nextMatch = trimmed.match(/^\*\*Next Step:\*\*\s*(.+)$/);
+    if (nextMatch) nextStep = nextMatch[1].trim();
+  }
+
+  const newSection = buildNewSection(specId, status, nextStep);
+
+  // Replace lines from headingIdx to sectionEnd-1 with new section
+  const before = lines.slice(0, headingIdx);
+  const after = lines.slice(sectionEnd);
+
+  // Preserve a blank line before the next section if it exists
+  const combined = [...before, ...newSection.split('\n'), '', ...after];
+
+  return combined.join('\n');
+}
+
+/**
+ * Migrate Format B (bullet-style) STATE.md.
+ *
+ * @param {string[]} lines
+ * @param {number} bulletIdx - Line index of the "- **Active Specification:**" bullet
+ * @returns {string}
+ */
+function migrateFormatB(lines, bulletIdx) {
+  let specId = null;
+  let status = null;
+  let nextStep = null;
+
+  // Extract spec ID from the same line: - **Active Specification:** SPEC-XXX
+  const activeLine = lines[bulletIdx];
+  const activeMatch = activeLine.match(/\*\*Active Specification:\*\*\s*(.+)$/);
+  if (activeMatch) specId = activeMatch[1].trim().replace(/^\[|\]$/g, ''); // strip [...] if present
+
+  // Look ahead for Status and Next Step bullets (within the same section)
+  // Also locate all three bullet lines so we can remove them
+  const bulletLines = [bulletIdx];
+
+  for (let i = bulletIdx + 1; i < Math.min(bulletIdx + 6, lines.length); i++) {
+    const trimmed = lines[i].trim();
+
+    if (trimmed.startsWith('## ')) break; // next section
+
+    const statusMatch = trimmed.match(/^-\s+\*\*Status:\*\*\s*(.+)$/);
+    if (statusMatch) {
+      status = statusMatch[1].trim().replace(/^\[|\]$/g, '');
+      bulletLines.push(i);
+    }
+
+    const nextMatch = trimmed.match(/^-\s+\*\*Next Step:\*\*\s*(.+)$/);
+    if (nextMatch) {
+      nextStep = nextMatch[1].trim().replace(/^\[|\]$/g, '');
+      bulletLines.push(i);
+    }
+  }
+
+  const newSection = buildNewSection(specId, status, nextStep);
+
+  // Check if there's a parent heading like "## Current Position" immediately before
+  // the bullet lines that we should also replace/remove
+  let sectionStart = bulletIdx;
+  let headingToRemove = null;
+
+  for (let i = bulletIdx - 1; i >= 0 && i >= bulletIdx - 3; i--) {
+    const trimmed = lines[i].trim();
+    if (trimmed === '## Current Position') {
+      headingToRemove = i;
+      sectionStart = i;
+      break;
+    }
+  }
+
+  // Remove: [parent heading if any] + blank lines + bullet lines
+  const linesToRemove = new Set(bulletLines);
+  if (headingToRemove !== null) linesToRemove.add(headingToRemove);
+
+  // Also remove blank lines immediately surrounding the heading
+  if (headingToRemove !== null) {
+    if (headingToRemove > 0 && lines[headingToRemove - 1].trim() === '') {
+      linesToRemove.add(headingToRemove - 1);
+    }
+    if (headingToRemove + 1 < lines.length && lines[headingToRemove + 1].trim() === '') {
+      linesToRemove.add(headingToRemove + 1);
+    }
+  }
+
+  // Insert new section at sectionStart position
+  const before = lines.slice(0, sectionStart).filter((_, idx) => !linesToRemove.has(idx));
+  const removedBefore = lines.slice(0, sectionStart);
+  const keptBefore = removedBefore.filter((_, idx) => !linesToRemove.has(idx));
+
+  const maxBullet = Math.max(...bulletLines);
+  const after = lines.slice(maxBullet + 1);
+
+  const combined = [...keptBefore, ...newSection.split('\n'), '', ...after];
+
+  return combined.join('\n');
+}
+
+module.exports = { migrateStateMd };