specflow-cc 1.19.0 → 1.20.1

package/bin/lib/todo.cjs

@@ -295,8 +295,10 @@ function cmdTodoReindex(cwd, raw) {
   const lines = [
     '# To-Do Index',
     '',
-    '> Auto-generated from individual TODO files. Do not edit manually.',
-    '> Regenerate with `/sf:todos`.',
+    '> 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.',
     '',
     '| # | ID | Title | Priority | Status | Created |',
     '|---|-----|-------|----------|--------|---------|',
@@ -324,9 +326,79 @@ function cmdTodoReindex(cwd, raw) {
   output({ reindexed: todos.length, path: indexPath }, raw, `Reindexed ${todos.length} TODOs → INDEX.md`);
 }
 
+/**
+ * Check whether INDEX.md is stale relative to TODO-*.md files.
+ *
+ * Stale = the set of TODO-XXX IDs on disk diverges from the set of TODO-XXX IDs
+ * listed in INDEX.md (file deleted but still in INDEX, or file present but missing).
+ *
+ * NOTE: Eliminated TODOs (`status: eliminated`) still appear in `/sf:todos --all`
+ * regenerated INDEX.md output, so they are NOT filtered here — both sides see them.
+ *
+ * Output JSON: { stale, missing_from_index, extra_in_index, index_exists }
+ *  - missing_from_index: file exists on disk but not in INDEX.md
+ *  - extra_in_index: ID listed in INDEX.md but no file on disk
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output mode
+ */
+function cmdTodoCheckStale(cwd, raw) {
+  const todosDir = path.join(cwd, '.specflow', 'todos');
+  const indexPath = path.join(todosDir, 'INDEX.md');
+
+  // Collect IDs from disk
+  const diskIds = new Set();
+  try {
+    for (const f of fs.readdirSync(todosDir)) {
+      const m = f.match(/^(TODO-\d+)\.md$/);
+      if (m) diskIds.add(m[1]);
+    }
+  } catch (e) {
+    // todos dir missing — treat as empty
+  }
+
+  // Collect IDs referenced in INDEX.md (parse only the table rows)
+  const indexIds = new Set();
+  const indexContent = safeReadFile(indexPath);
+  const indexExists = indexContent !== null;
+
+  if (indexContent) {
+    // Match TODO-XXX in pipe-table cells: "| N | TODO-001 | ..."
+    const regex = /\|\s*\d+\s*\|\s*(TODO-\d+)\s*\|/g;
+    let m;
+    while ((m = regex.exec(indexContent)) !== null) {
+      indexIds.add(m[1]);
+    }
+  }
+
+  const missingFromIndex = [...diskIds].filter(id => !indexIds.has(id)).sort();
+  const extraInIndex = [...indexIds].filter(id => !diskIds.has(id)).sort();
+
+  // If INDEX.md does not exist but there are TODO files, INDEX is stale.
+  // If INDEX.md does not exist and no TODO files, not stale (nothing to track).
+  const stale =
+    missingFromIndex.length > 0 ||
+    extraInIndex.length > 0 ||
+    (!indexExists && diskIds.size > 0);
+
+  output(
+    {
+      stale,
+      index_exists: indexExists,
+      todo_count: diskIds.size,
+      index_count: indexIds.size,
+      missing_from_index: missingFromIndex,
+      extra_in_index: extraInIndex,
+    },
+    raw,
+    stale ? 'STALE' : 'FRESH'
+  );
+}
+
 module.exports = {
   cmdTodoLoad,
   cmdTodoList,
   cmdTodoNextId,
   cmdTodoReindex,
+  cmdTodoCheckStale,
 };

package/bin/sf-tools.cjs

@@ -13,9 +13,15 @@
  *   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
+ *   todo check-stale                      Report drift between TODO-*.md and INDEX.md
  *   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,9 +30,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, cmdTodoReindex } = require('./lib/todo.cjs');
+const { cmdTodoLoad, cmdTodoList, cmdTodoNextId, cmdTodoReindex, cmdTodoCheckStale } = require('./lib/todo.cjs');
 const { cmdResolveModel } = require('./lib/config.cjs');
 const { cmdVerifyStructure } = require('./lib/verify.cjs');
 
@@ -61,14 +76,44 @@ const COMMANDS = {
   'todo list':       () => cmdTodoList(cwd, raw, { showAll: flags.all ?? false }),
   'todo next-id':    () => cmdTodoNextId(cwd, raw),
   'todo reindex':    () => cmdTodoReindex(cwd, raw),
+  'todo check-stale': () => cmdTodoCheckStale(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);
@@ -93,9 +138,15 @@ Commands:
   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
+  todo check-stale                        Report drift between TODO-*.md and INDEX.md
   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/migrate-todos.md

@@ -13,7 +13,7 @@ Migrate an existing monolithic `.specflow/todos/TODO.md` to the new per-file for
 This is a one-time migration command. After migration:
 - `TODO.md` is renamed to `TODO.md.bak` (NOT deleted — safety net)
 - Each TODO becomes its own `TODO-XXX.md` file
-- `INDEX.md` is generated from the new files
+- `INDEX.md` is regenerated from the new files via the shared `todo reindex` helper
 - All other commands will use the new per-file format automatically
 
 Use `--dry-run` to preview the migration without writing any files.
@@ -173,24 +173,14 @@ created: {YYYY-MM-DD}
 
 ## Step 7: Generate INDEX.md
 
-Write `.specflow/todos/INDEX.md` with all migrated TODOs, sorted by priority then date:
+Invoke the shared regen helper to build `.specflow/todos/INDEX.md` from the migrated files:
 
-```markdown
-# To-Do Index
-
-> Auto-generated from individual TODO files. Do not edit manually.
-> Regenerate with `/sf:todos`.
-
-| # | ID | Title | Priority | Status | Created |
-|---|-----|-------|----------|--------|---------|
-{one row per TODO, sorted by priority then created date}
-
-**Total:** {N} items ({high} high, {medium} medium, {low} low, {unset} unset)
-
----
-*Last regenerated: {YYYY-MM-DD HH:MM}*
+```bash
+node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex
 ```
 
+Do NOT write INDEX.md inline — the helper is the single source of truth for its layout (see `templates/todo-index.md`).
+
 ## Step 8: Rename Legacy TODO.md
 
 ```bash
@@ -245,7 +235,7 @@ Migrated {N} TODOs from TODO.md to per-file format.
 - [ ] Individual TODO-XXX.md files created for each block
 - [ ] Each file has valid YAML frontmatter (id, title, priority, status, created)
 - [ ] Title derived from description (first sentence, ~80 chars)
-- [ ] INDEX.md generated from migrated files
+- [ ] INDEX.md regenerated via `node ~/.claude/specflow-cc/bin/sf-tools.cjs todo reindex`
 - [ ] TODO.md renamed to TODO.md.bak (NOT deleted)
 - [ ] Clear migration summary shown
 - [ ] Cleanup instructions provided

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