specflow-cc 1.18.3 → 1.20.0

package/bin/lib/todo.cjs

@@ -231,8 +231,102 @@ function cmdTodoNextId(cwd, raw) {
   }, raw, nextId);
 }
 
+/**
+ * Reindex: scan TODO-*.md files, regenerate INDEX.md.
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdTodoReindex(cwd, raw) {
+  const todosDir = path.join(cwd, '.specflow', 'todos');
+
+  // Collect per-file TODOs
+  let perFiles;
+  try {
+    perFiles = fs.readdirSync(todosDir).filter(f => /^TODO-\d+\.md$/.test(f)).sort();
+  } catch (e) {
+    perFiles = [];
+  }
+
+  const todos = [];
+
+  for (const file of perFiles) {
+    const content = safeReadFile(path.join(todosDir, file));
+    if (!content) continue;
+
+    const parsed = parseFrontmatter(content);
+    const fm = parsed.frontmatter;
+
+    // Strip surrounding quotes from title (YAML may preserve them)
+    let title = fm.title || '';
+    if ((title.startsWith('"') && title.endsWith('"')) || (title.startsWith("'") && title.endsWith("'"))) {
+      title = title.slice(1, -1);
+    }
+
+    todos.push({
+      id: fm.id || file.replace('.md', ''),
+      title,
+      priority: fm.priority || '—',
+      status: fm.status || 'open',
+      created: fm.created || '',
+    });
+  }
+
+  // Sort by priority (high > medium > low > unset), then by created date
+  todos.sort((a, b) => {
+    const pa = priorityKey(a.priority);
+    const pb = priorityKey(b.priority);
+    if (pa !== pb) return pa - pb;
+    if (a.created < b.created) return -1;
+    if (a.created > b.created) return 1;
+    return 0;
+  });
+
+  // Count by priority
+  const counts = { high: 0, medium: 0, low: 0, unset: 0 };
+  for (const t of todos) {
+    if (t.priority === 'high') counts.high++;
+    else if (t.priority === 'medium') counts.medium++;
+    else if (t.priority === 'low') counts.low++;
+    else counts.unset++;
+  }
+
+  // Build INDEX.md
+  const lines = [
+    '# To-Do Index',
+    '',
+    '> Auto-generated from individual TODO files. Do not edit manually.',
+    '> Regenerate with `/sf:todos`.',
+    '',
+    '| # | ID | Title | Priority | Status | Created |',
+    '|---|-----|-------|----------|--------|---------|',
+  ];
+
+  for (let i = 0; i < todos.length; i++) {
+    const t = todos[i];
+    let title = t.title;
+    if (title.length > 50) title = title.slice(0, 50) + '...';
+    lines.push(`| ${i + 1} | ${t.id} | ${title} | ${t.priority} | ${t.status} | ${t.created} |`);
+  }
+
+  lines.push('');
+  lines.push(`**Total:** ${todos.length} items (${counts.high} high, ${counts.medium} medium, ${counts.low} low, ${counts.unset} unset)`);
+  lines.push('');
+  lines.push('---');
+  const now = new Date();
+  const timestamp = now.toISOString().replace('T', ' ').slice(0, 16);
+  lines.push(`*Last regenerated: ${timestamp}*`);
+  lines.push('');
+
+  const indexPath = path.join(todosDir, 'INDEX.md');
+  fs.writeFileSync(indexPath, lines.join('\n'), 'utf8');
+
+  output({ reindexed: todos.length, path: indexPath }, raw, `Reindexed ${todos.length} TODOs → INDEX.md`);
+}
+
 module.exports = {
   cmdTodoLoad,
   cmdTodoList,
   cmdTodoNextId,
+  cmdTodoReindex,
 };

package/bin/sf-tools.cjs

@@ -12,9 +12,15 @@
  *   todo load <id>                        Parse TODO file, return frontmatter + body
  *   todo list [--all]                     List all TODOs sorted by priority
  *   todo next-id                          Next available TODO-XXX number
+ *   todo reindex                          Regenerate INDEX.md from TODO files
  *   queue next                            First actionable spec from queue
- *   state get                             Current active spec, status, next step
- *   state set-active <id> <status> [next] Update active spec in STATE.md
+ *   state get                             Current active spec, status, next step (legacy shim)
+ *   state set-active <id> <status> [next] Update active spec in STATE.md (legacy shim)
+ *   state list-active                     List all active specs from Active Specifications table
+ *   state add-active <id> <status> <next> Append/update one row in Active Specifications table
+ *   state remove-active <id>              Remove one row from Active Specifications table
+ *   state resolve [id]                    Resolve active spec; emit JSON contract
+ *   state migrate                         One-shot idempotent migration to new schema
  *   resolve-model <agent-type>            Model for agent by current profile
  *   verify-structure                      Check .specflow/ integrity
  *   generate-slug <text>                  Text to URL-safe slug
@@ -23,9 +29,18 @@
 'use strict';
 
 const { output, error, generateSlug } = require('./lib/core.cjs');
-const { cmdStateGet, cmdStateSetActive, cmdQueueNext } = require('./lib/state.cjs');
+const {
+  cmdStateGet,
+  cmdStateSetActive,
+  cmdStateListActive,
+  cmdStateAddActive,
+  cmdStateRemoveActive,
+  cmdStateResolve,
+  cmdStateMigrate,
+  cmdQueueNext,
+} = require('./lib/state.cjs');
 const { cmdSpecLoad, cmdSpecList, cmdSpecNextId } = require('./lib/spec.cjs');
-const { cmdTodoLoad, cmdTodoList, cmdTodoNextId } = require('./lib/todo.cjs');
+const { cmdTodoLoad, cmdTodoList, cmdTodoNextId, cmdTodoReindex } = require('./lib/todo.cjs');
 const { cmdResolveModel } = require('./lib/config.cjs');
 const { cmdVerifyStructure } = require('./lib/verify.cjs');
 
@@ -59,14 +74,44 @@ const COMMANDS = {
   },
   'todo list':       () => cmdTodoList(cwd, raw, { showAll: flags.all ?? false }),
   'todo next-id':    () => cmdTodoNextId(cwd, raw),
+  'todo reindex':    () => cmdTodoReindex(cwd, raw),
   'queue next':      () => cmdQueueNext(cwd, raw),
+
+  // Legacy shims (backwards compatible)
   'state get':       () => cmdStateGet(cwd, raw),
   'state set-active': () => {
     if (!filteredArgs[2] || !filteredArgs[3]) {
       error('Missing arguments. Usage: state set-active <id> <status> [next_step]');
     }
-    cmdStateSetActive(cwd, filteredArgs[2], filteredArgs[3], filteredArgs[4], raw);
+    Promise.resolve(cmdStateSetActive(cwd, filteredArgs[2], filteredArgs[3], filteredArgs[4], raw))
+      .catch(e => error(e.message));
+  },
+
+  // New multi-spec state commands
+  'state list-active': () => cmdStateListActive(cwd, raw),
+  'state add-active':  () => {
+    if (!filteredArgs[2] || !filteredArgs[3]) {
+      error('Missing arguments. Usage: state add-active <id> <status> <next_step>');
+    }
+    Promise.resolve(cmdStateAddActive(cwd, filteredArgs[2], filteredArgs[3], filteredArgs[4] || '', raw))
+      .catch(e => error(e.message));
   },
+  'state remove-active': () => {
+    if (!filteredArgs[2]) {
+      error('Missing arguments. Usage: state remove-active <id>');
+    }
+    Promise.resolve(cmdStateRemoveActive(cwd, filteredArgs[2], raw))
+      .catch(e => error(e.message));
+  },
+  'state resolve': () => {
+    // Optional specId argument (filteredArgs[2])
+    cmdStateResolve(cwd, filteredArgs[2] || undefined, raw);
+  },
+  'state migrate': () => {
+    Promise.resolve(cmdStateMigrate(cwd, raw))
+      .catch(e => error(e.message));
+  },
+
   'resolve-model':   () => {
     if (!filteredArgs[1]) error('Missing agent type. Usage: resolve-model <agent-type>');
     cmdResolveModel(cwd, filteredArgs[1], raw);
@@ -90,9 +135,15 @@ Commands:
   todo load <id>                          Parse TODO file, return frontmatter + body
   todo list [--all]                       List TODOs sorted by priority (--all includes eliminated)
   todo next-id                            Next available TODO-XXX number
+  todo reindex                            Regenerate INDEX.md from TODO files
   queue next                              First actionable spec from queue table
-  state get                               Current active spec, status, next step
-  state set-active <id> <status> [next]   Update active spec, status, next step
+  state get                               Current active spec, status, next step (legacy shim)
+  state set-active <id> <status> [next]   Update active spec, status, next step (legacy shim)
+  state list-active                       List all rows in Active Specifications table
+  state add-active <id> <status> <next>   Append/update one row (under advisory lock)
+  state remove-active <id>               Remove one row (under advisory lock)
+  state resolve [SPEC-ID]                Resolve active spec; emit JSON contract
+  state migrate                          One-shot idempotent migration to new schema
   resolve-model <agent-type>              Resolve model for agent by current profile
   verify-structure                        Check .specflow/ directory integrity
   generate-slug <text>                    Convert text to URL-safe slug

package/commands/sf/audit.md

@@ -2,6 +2,7 @@
 name: sf:audit
 description: Audit the active specification in a fresh context
 argument-hint: "[SPEC-XXX] [--import \"feedback\"]"
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -40,17 +41,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active specification to audit.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to audit.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to audit?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -143,10 +154,11 @@ In spec frontmatter, set: `status: revision_requested`
 
 ### 4.6 Update STATE.md
 
-Update STATE.md:
-- Status → "external_review"
-- Next Step → "/sf:revise"
-- Add decision: "Imported external feedback for SPEC-XXX"
+Update STATE.md via CLI:
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX external_review /sf:revise
+```
+Add decision: "Imported external feedback for SPEC-XXX"
 
 ### 4.7 Display Import Result
 

package/commands/sf/autopilot.md

@@ -2,6 +2,7 @@
 name: sf:autopilot
 description: Run full spec lifecycle autonomously (audit -> run -> review -> done)
 argument-hint: "[SPEC-XXX] [--all]"
+# SPEC-011: Accepts optional SPEC-XXX; resolves via state resolve; FAILS when N>1 and no ID (no picker)
 allowed-tools:
   - Read
   - Write
@@ -43,25 +44,42 @@ Parse the command argument to determine execution mode:
 
 | Argument | Mode | Behavior |
 |----------|------|----------|
-| (none) | single | Process the active spec in STATE.md |
-| `SPEC-XXX` | single | Set SPEC-XXX as active, then process it |
-| `--all` | batch | Process all actionable specs in Queue order |
+| (none) | single | Resolve active spec; fail fast if N>1 (no picker) |
+| `SPEC-XXX` | single | Process this explicit spec ID |
+| `--all` | batch | Process all actionable specs in Queue order; still requires explicit SPEC-ID if N>1 |
 
-**If single mode:**
-- If SPEC-XXX argument provided: update STATE.md to set it as active spec
-- If no argument and no active spec exists: display error and exit
+**CRITICAL — N>1 guard (autopilot must be unambiguous):**
 
-**If batch mode (--all):**
-- Identify all actionable specs from Queue (any spec with status: draft, auditing, revision_requested, audited, running, review)
+Call `node bin/sf-tools.cjs state resolve $SPEC_ID_ARG` (pass SPEC-ID arg if provided; omit if not).
 
-**Error case (single mode, no active, no argument):**
-```
-No active specification to process.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to process.
 
-Provide a spec ID: `/sf:autopilot SPEC-XXX`
-Or run on all specs: `/sf:autopilot --all`
-```
-Exit.
+  Provide a spec ID: `/sf:autopilot SPEC-XXX`
+  Or run on all specs: `/sf:autopilot --all`
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → **FAIL FAST** (do NOT show picker):
+  ```
+  Autopilot requires explicit SPEC-ID when >1 active specs.
+
+  Active specs: {list SPEC-IDs from options}
+
+  Provide a spec ID: `/sf:autopilot SPEC-XXX`
+  ```
+  Exit. (This applies to both plain `/sf:autopilot` AND `/sf:autopilot --all` without a SPEC-ID. `--all` controls within-spec behavior, not multi-spec iteration.)
+
+**If single mode with explicit SPEC-ID:**
+- SPEC-ID was resolved via state resolve above (action:use)
+
+**If batch mode (--all):**
+- Identify all actionable specs from Queue (any spec with status: draft, auditing, revision_requested, audited, running, review)
 
 ## Step 3: Set Configuration Constants
 
@@ -107,8 +125,7 @@ current_spec = null
 
 ### 5.1 Load Current Spec State
 
-Read `.specflow/STATE.md` to get active specification.
-Read `.specflow/specs/SPEC-XXX.md` to get frontmatter status.
+Read `.specflow/specs/SPEC-XXX.md` to get frontmatter status (spec ID resolved in Step 2).
 
 ### 5.2 Determine Current Phase
 
@@ -255,10 +272,11 @@ mv .specflow/specs/SPEC-XXX.md .specflow/archive/
 ```
 
 5. **Update STATE.md:**
-   - Active Specification → "none"
-   - Status → "idle"
-   - Next Step → "/sf:new or /sf:next"
-   - Remove SPEC-XXX row from Queue table
+   Remove SPEC-XXX from Active Specifications table:
+   ```bash
+   node bin/sf-tools.cjs state remove-active SPEC-XXX
+   ```
+   Remove SPEC-XXX row from Queue table (using Read+Write).
 
 6. **Check STATE.md size and rotate** (same logic as 5.5 step 2)
 

package/commands/sf/discuss.md

@@ -62,9 +62,10 @@ Determine discussion mode from arguments:
 - Mode: `requirements-gathering`
 
 **Case E: No arguments**
-- Check STATE.md for active spec
-- If active spec exists: discuss that spec
-- If no active spec: ask what to discuss
+- Call `node bin/sf-tools.cjs state resolve` to resolve active spec
+- `{"action":"use","id":"SPEC-XXX"}` → discuss that spec
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → ask what to discuss
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to pick which spec to discuss
 
 ## 3. Load Context
 

package/commands/sf/done.md

@@ -1,6 +1,7 @@
 ---
 name: sf:done
 description: Finalize specification, archive, and update state
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -36,17 +37,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active specification to finalize.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to finalize.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to finalize?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -283,12 +294,16 @@ Check if the spec frontmatter contains a `source:` field (e.g., `source: TODO-00
 [ -f .specflow/todos/{source}.md ] && echo "FOUND" || echo "NOT_FOUND"
 ```
 
-2. **If FOUND:** Delete the file:
+2. **If FOUND:** Delete the file and reindex:
 
 ```bash
 rm .specflow/todos/{source}.md
 ```
 
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
+```
+
 3. **If NOT_FOUND (backward compatibility):** Also check legacy format — look in `.specflow/todos/TODO.md` for the referenced ID. If found there, remove the block using the Edit tool.
 
 No "Last updated" lines to update in per-file format.
@@ -305,11 +320,11 @@ mv .specflow/specs/SPEC-XXX.md .specflow/archive/
 
 ## Step 9: Update STATE.md
 
-### Clear Active Specification
+### Remove from Active Specifications Table
 
-- Active Specification → "none"
-- Status → "idle"
-- Next Step → "/sf:new or /sf:next"
+```bash
+node bin/sf-tools.cjs state remove-active SPEC-XXX
+```
 
 ### Remove from Queue
 

package/commands/sf/fix.md

@@ -1,6 +1,7 @@
 ---
 name: sf:fix
 description: Fix implementation based on review feedback
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -38,17 +39,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active specification to fix.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to fix.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to fix?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -164,8 +175,9 @@ Append to Review History:
 
 ## Step 8: Update STATE.md
 
-- Status → "review" (ready for re-review)
-- Next Step → "/sf:review"
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX review /sf:review
+```
 
 ## Step 9: Display Result
 

package/commands/sf/health.md

@@ -2,6 +2,7 @@
 name: sf:health
 description: Diagnose .specflow/ directory health and optionally repair issues
 argument-hint: [--repair]
+# SPEC-011: Invokes migrate-state on entry; re-stamps STATE.md header from template after migration (--repair path)
 allowed-tools:
   - Read
   - Bash
@@ -32,7 +33,19 @@ SpecFlow not initialized. Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Parse Arguments
+## Step 2: Invoke STATE.md Migration (entry point)
+
+Run migration on entry — idempotent, no-op when already migrated:
+
+```bash
+node bin/sf-tools.cjs state migrate
+```
+
+Parse the response:
+- `{"migrated":true,...}` → Migration completed. After migration, re-stamp the `## Active Specifications` header block in STATE.md from `templates/state.md` to reconcile any format drift (non-destructive: Queue, Decisions, Notes sections are preserved; only the Active Specifications block is normalized). This is the `--repair` path.
+- `{"migrated":false,...}` → Already migrated, no action needed.
+
+## Step 2.5: Parse Arguments
 
 Check if `--repair` flag is present.
 
@@ -71,9 +84,9 @@ For each check:
 Read STATE.md and validate:
 
 **E003: Active spec references non-existent file**
-- Extract active spec ID from `## Active Specification`
-- If not "—" or empty, check `.specflow/specs/{ID}.md` exists
-- If missing: error (repairable — clear active spec to "—")
+- List all active specs via `node bin/sf-tools.cjs state list-active`
+- For each SPEC-ID, check `.specflow/specs/{ID}.md` exists
+- If missing: error (repairable — remove that row via `state remove-active`)
 
 **W005: Queue references non-existent spec file**
 - Parse queue table rows

package/commands/sf/help.md

@@ -1,6 +1,7 @@
 ---
 name: sf:help
 description: Show SpecFlow help and command reference
+# SPEC-011: Uses state list-active to show active specs in overview; no state resolve needed (no single-spec operations)
 allowed-tools:
   - Read
   - Glob
@@ -203,6 +204,11 @@ Exit.
 
 ## Step 2b: Overview Help
 
+Show active specs count (uses list-active for multi-spec awareness):
+```bash
+node bin/sf-tools.cjs state list-active --raw
+```
+
 Display full command reference:
 
 ```

package/commands/sf/pause.md

@@ -1,6 +1,7 @@
 ---
 name: sf:pause
 description: Save current work context for later resumption
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -33,20 +34,26 @@ Run `/sf:init` to start.
 ```
 Exit.
 
-## Step 2: Get Current State
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract:
-- Active Specification
-- Status
-- Next Step
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active work to pause.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display info and allow general notes:
+  ```
+  No active work to pause.
 
-Current state: idle
-```
-But still allow pausing to capture general notes.
+  Current state: idle
+  ```
+  Still allow pausing to capture general notes.
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which session to pause?
+  Options: {id — title (status)} for each entry
+  ```
+
+Also call `node bin/sf-tools.cjs state list-active` to capture all active specs in the pause file.
 
 ## Step 3: Load Active Specification Details
 

package/commands/sf/review.md

@@ -1,6 +1,7 @@
 ---
 name: sf:review
 description: Review the implementation against specification
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -36,17 +37,27 @@ Run `/sf:init` first.
 ```
 Exit.
 
-## Step 2: Get Active Specification
+## Step 2: Resolve Active Specification
 
-Read `.specflow/STATE.md` and extract Active Specification.
+Call `node bin/sf-tools.cjs state resolve $ARGUMENTS` (pass the optional SPEC-XXX arg if provided).
 
-**If no active specification:**
-```
-No active specification to review.
+Parse the JSON response:
+- `{"action":"use","id":"SPEC-XXX"}` → proceed with SPEC-XXX
+- `{"action":"error","code":"NO_ACTIVE_SPEC"}` → display error and exit:
+  ```
+  No active specification to review.
 
-Run `/sf:new "task description"` to create one.
-```
-Exit.
+  Run `/sf:new "task description"` to create one.
+  ```
+- `{"action":"error","code":"SPEC_NOT_ACTIVE","id":"SPEC-XXX"}` → display error and exit:
+  ```
+  SPEC-XXX is not in the Active Specifications table.
+  ```
+- `{"action":"ask","options":[...]}` → use AskUserQuestion to show picker:
+  ```
+  Multiple active specifications. Which one to review?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -319,8 +330,12 @@ Append Review History to spec.
 
 ### Update STATE.md
 
-- If APPROVED: Status → "done", Next Step → "/sf:done"
-- If CHANGES_REQUESTED: Status → "review", Next Step → "/sf:fix"
+```bash
+# If APPROVED:
+node bin/sf-tools.cjs state add-active SPEC-XXX done /sf:done
+# If CHANGES_REQUESTED:
+node bin/sf-tools.cjs state add-active SPEC-XXX review /sf:fix
+```
 
 </fallback>