specflow-cc 1.19.0 → 1.20.0

package/bin/sf-tools.cjs

@@ -14,8 +14,13 @@
  *   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
@@ -24,7 +29,16 @@
 '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, cmdTodoReindex } = require('./lib/todo.cjs');
 const { cmdResolveModel } = require('./lib/config.cjs');
@@ -62,13 +76,42 @@ const COMMANDS = {
   '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);
@@ -94,8 +137,13 @@ Commands:
   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
 
@@ -309,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>
 

package/commands/sf/revise.md

@@ -1,6 +1,7 @@
 ---
 name: sf:revise
 description: Revise specification based on audit feedback
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -37,17 +38,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; strip non-SPEC-ID args first).
 
-**If no active specification:**
-```
-No active specification to revise.
+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 revise.
 
-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 revise?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -508,8 +519,9 @@ After recording the Response, if any items were marked "Deferred":
 In spec frontmatter: `status: auditing`
 
 In STATE.md:
-- Status → "auditing"
-- Next Step → "/sf:audit"
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX auditing /sf:audit
+```
 
 </fallback>
 

package/commands/sf/run.md

@@ -1,6 +1,7 @@
 ---
 name: sf:run
 description: Execute the specification (implement the code)
+# SPEC-011: Accepts optional SPEC-XXX as first positional arg; resolves via state resolve
 allowed-tools:
   - Read
   - Write
@@ -39,17 +40,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 execute.
+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 execute.
 
-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 run?
+  Options: {id — title (status)} for each entry
+  ```
 
 ## Step 3: Load Specification
 
@@ -182,9 +193,9 @@ Use model for `spec-executor` or `spec-executor-orchestrator` from selected prof
 
 ## Step 7: Update Status
 
-Update STATE.md:
-- Status → "running"
-- Next Step → "(in progress)"
+```bash
+node bin/sf-tools.cjs state add-active SPEC-XXX running "(in progress)"
+```
 
 Update spec frontmatter:
 - status → "running"