ai-spector 0.8.30 → 0.8.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spector",
-  "version": "0.8.30",
+  "version": "0.8.33",
   "description": "Cursor-first documentation workflow: traceability graph, SRS/basic/detail design templates, and ai-spector CLI",
   "type": "module",
   "license": "MIT",

package/scaffold/claude/.claude/skills/ai-spector-resolve-task/skill.md

@@ -0,0 +1,34 @@
+---
+name: ai-spector-resolve-task
+description: >-
+  FIRST CHOICE for incremental changes: add feature, add requirement, update section,
+  "I want to…", create task. Mandatory: clarify → plan → explicit yes → execute.
+  No graph_impact or edits before approval. Not for full SRS generation — use
+  ai-spector-generate-srs for DAG waves.
+---
+
+# AI Spector — Resolve Task
+
+## Plan-first mode
+
+**Forbidden before user approves the plan:** `graph_impact`, `index`, `graph_merge`, `resolve_task`, Edit/Write.
+
+**Allowed for discovery only:** `docs_search`, `graph_query_fuzzy`, `graph_query`, Read (structure).
+
+## Workflow
+
+```
+1. Acknowledge resolve-task workflow
+2. Clarify (≤3 questions) → GoalSpec
+3. Discover scope (read-only, optional)
+4. Show GoalSpec + TaskPlan → wait for yes
+5. Execute approved steps (edits + resolve_task)
+6. Report state update
+```
+
+## Routing
+
+| "I want to add login with Google" | **this skill** |
+| "generate SRS" / "write chapter 4" | `ai-spector-generate-srs` |
+
+Runbook: `.cursor/skills/ai-spector-resolve-task/references/runbook.md`

package/scaffold/claude/CLAUDE.md

@@ -90,6 +90,8 @@ Skip impact/index only when the user explicitly says it was a typo-only fix with
 | Translation status | `ai-spector-lang-status` |
 | Resolve translations | `ai-spector-resolve-translation` |
 | Resolve comments | `ai-spector-resolve-comments` |
+| Add/update feature or section ("I want to add…") | `ai-spector-resolve-task` (plan-first — no impact/edits before approval) |
+| Generate SRS / basic design (full chapter) | `ai-spector-generate-srs` / `ai-spector-generate-basic-design` |
 
 ## Quick reference
 
@@ -111,6 +113,7 @@ Skip impact/index only when the user explicitly says it was a typo-only fix with
 | `cocoindex_index({})` | Rebuild semantic embeddings |
 | `docs_search({ query })` | Semantic doc search (CocoIndex) |
 | `graph_query_fuzzy({ query })` | Natural language graph lookup (CocoIndex) |
+| `resolve_task({ intent, goalSpec, plan })` | Execute an approved task plan (index, graph_merge, etc.) |
 
 ### CLI (fallback / MCP-unavailable or no tool equivalent)
 
@@ -124,6 +127,7 @@ npx ai-spector template list        # list installed packs + active
 npx ai-spector template scan <path> # scan a template folder → scan-result.json
 npx ai-spector template install     # install pack from staging (AI writes manifest first)
 npx ai-spector template use <name>  # switch active pack (use "builtin" to revert)
+npx ai-spector resolve-task plan.json   # execute approved task plan
 
 # CocoIndex (opt-in — requires Python 3.11+)
 npx ai-spector cocoindex setup      # scaffold pipeline into project

package/scaffold/cursor/WORKFLOW.md

@@ -38,6 +38,7 @@ Then: add files under `docs/data-source/`, enable **all** skills under `.cursor/
 | Translation status | “what’s stale in JP”, “pending translations” | `ai-spector-lang-status` | `lang_queue({})` MCP |
 | Sync translations | “resolve translations”, “update JP from EN” | `ai-spector-resolve-translation` | read queue → translate → `index({ cocoindexSync: true })` |
 | Review comments | “resolve comments”, “fix C-001” | `ai-spector-resolve-comments` | inbox → plan → edit → commit |
+| Add/update one feature or section | “I want to add login with Google”, “add requirement”, “update auth section” | `ai-spector-resolve-task` | clarify → plan → **explicit yes** → then edit + impact + index (never impact before approval) |
 | Explore graph | “show the graph” | `ai-spector-graph` | `npx ai-spector graph visualize --open` (no MCP equivalent) |
 
 Unsure? The agent uses [skills/_skill-router.md](./skills/_skill-router.md) or asks one clarifying question.

package/scaffold/cursor/rules/ai-spector-after-doc-edit.mdc

@@ -6,6 +6,8 @@ alwaysApply: false
 
 # After doc edits — impact + queue
 
+When following **ai-spector-resolve-task**, run impact and index only **after plan approval**, as steps in the approved TaskPlan — not during planning.
+
 When you **finish editing** any file under `docs/srs/`, `docs/basic-design/`, or `docs/detail-design/`:
 
 ## 1. Check traceability impact

package/scaffold/cursor/rules/ai-spector-resolve-task.mdc

@@ -0,0 +1,29 @@
+---
+description: >-
+  Incremental doc changes (add feature, update section, I want to…) must use
+  resolve-task workflow: clarify → plan → explicit approval → then edit/impact/index.
+  Never run graph_impact or edit docs before the user approves the plan.
+alwaysApply: true
+---
+
+# Resolve-task gate for incremental changes
+
+When the user asks to **add**, **update**, or **change** a feature, requirement, section, or prototype element (e.g. "I want to add login with Google"):
+
+1. **Activate** `ai-spector-resolve-task` — not `ai-spector-generate-srs` or `ai-spector-generate-basic-design`.
+2. **Read** `.cursor/skills/ai-spector-resolve-task/references/runbook.md`.
+3. **Clarify** → **show GoalSpec + TaskPlan** → **wait for explicit yes**.
+4. **Only then** edit files and run `graph_impact` / `index` / `resolve_task`.
+
+## Forbidden before plan approval
+
+- `graph_impact`, `index`, `graph_merge`, `resolve_task`
+- Edit / Write under `docs/` or `prototype/`
+- "Quick check" impact or draft edits
+
+## Full generate vs incremental
+
+| Request | Skill |
+|---------|-------|
+| "generate SRS", "write chapter 4", DAG wave | `ai-spector-generate-srs` |
+| "add login with Google", "update auth section" | `ai-spector-resolve-task` |

package/scaffold/cursor/skills/README.md

@@ -17,6 +17,7 @@ Enable **every** folder under `.cursor/skills/` in Cursor (Settings → Rules
 | Screens, APIs, DB basic design | `ai-spector-generate-basic-design` |
 | HTML prototype | `ai-spector-generate-prototype` |
 | Review comments | `ai-spector-resolve-comments` |
+| Add/update feature or section (“I want to add…”) | `ai-spector-resolve-task` (plan-first) |
 | Translation status (read-only) | `ai-spector-lang-status` |
 | Resolve / sync translations | `ai-spector-resolve-translation` |
 | Unsure | `ai-spector` (core) |

package/scaffold/cursor/skills/_skill-router.md

@@ -4,9 +4,11 @@ Agents use this when intent is ambiguous.
 
 ## Priority
 
-1. **File context** — `paths` in skill frontmatter (e.g. `prototype/**` → prototype skill).
-2. **Natural language** — match skill `description`; then read that skill’s `references/` runbook.
-3. **Still unclear** — `ai-spector` core + one question (graph vs SRS vs basic design vs prototype vs comments).
+1. **Incremental change (plan-first)** — verbs *add*, *update*, *change*, *modify*, *extend*, or phrases *"I want to"*, *"we need to"*, *create task* → **`ai-spector-resolve-task`** before any generate-* skill. Example: "add login with Google" → resolve-task, **not** generate-srs.
+2. **Full generation** — *generate*, *write chapter*, *DAG wave*, *from graph* → `ai-spector-generate` or layer skill.
+3. **File context** — `paths` in skill frontmatter (e.g. `prototype/**` → prototype skill) when intent is still ambiguous.
+4. **Natural language** — match skill `description`; then read that skill’s `references/` runbook.
+5. **Still unclear** — `ai-spector` core + one question (incremental change vs full generate vs graph vs comments).
 
 ## Task → skill → runbook
 
@@ -24,10 +26,12 @@ Agents use this when intent is ambiguous.
 | link graph, semantic edges | `ai-spector-graph` | `references/link-graph.md` |
 | sync graph | `ai-spector-graph` | `references/sync-graph.md` |
 | doc summaries | `ai-spector-graph` | `references/summary.md` |
-| generate docs, write SRS, requirements, use cases, features | `ai-spector-generate` | `SKILL.md` (checks `packs.srs`, then routes) |
+| generate docs, write SRS (full chapter/DAG), generate use cases from graph | `ai-spector-generate` | `SKILL.md` (checks `packs.srs`, then routes) |
+| add feature, add requirement, update section, "I want to add…", "we need…" | `ai-spector-resolve-task` | `references/runbook.md` |
 | screens, APIs, wireframes, basic design | `ai-spector-generate` | `SKILL.md` (checks `packs.basicDesign`, then routes) |
 | HTML prototype | `ai-spector-generate-prototype` | `references/runbook.md` |
 | set up template pack, import template, custom template, install template | `ai-spector-template-import` | `references/runbook.md` |
+| create task, new task, resolve task, change prototype | `ai-spector-resolve-task` | `references/runbook.md` |
 | review comments, C-001, inbox | `ai-spector-resolve-comments` | `references/runbook.md` |
 | translation status, stale langs | `ai-spector-lang-status` | `SKILL.md` |
 | resolve translations, sync JP/VI | `ai-spector-resolve-translation` | `references/runbook.md` |

package/scaffold/cursor/skills/ai-spector/SKILL.md

@@ -5,7 +5,8 @@ description: >-
   and routing to task skills. Use when the user mentions ai-spector, docflow, or .npx ai-spector but the
   task is unclear, or for init and project layout. Do not use when the user clearly wants SRS,
   basic design, HTML prototype, graph operations, or comment resolution — use the
-  matching task skill instead.
+  matching task skill instead. For open-ended doc/graph changes or "create task",
+  use ai-spector-resolve-task.
 ---
 
 # AI Spector (core)
@@ -33,6 +34,7 @@ When the `ai-spector` MCP server is enabled (`.cursor/mcp.json` or `.mcp.json` l
 | Rebuild semantic embeddings | `cocoindex_index({})` | `npx ai-spector cocoindex index` |
 | Semantic doc search | `docs_search({ query })` | `npx ai-spector cocoindex search --query …` |
 | Natural language graph lookup | `graph_query_fuzzy({ query })` | *(no CLI equivalent)* |
+| Execute approved task plan | `resolve_task({ intent, goalSpec, plan })` | `npx ai-spector resolve-task plan.json` |
 | **Visualize graph** | *(no MCP tool)* | `npx ai-spector graph visualize --open` |
 
 Use CLI **only** when: MCP server is not configured, the tool errors, or no MCP equivalent exists (visualize, `lang add`, template mutations).
@@ -78,12 +80,14 @@ When `npx ai-spector` exits non-zero, required `--json` is invalid, or a require
 |--------|-------|
 | Setup / bootstrap project | `ai-spector-setup` |
 | Analyze, index, validate, impact, visualize | `ai-spector-graph` |
-| SRS | `ai-spector-generate-srs` |
-| Basic design | `ai-spector-generate-basic-design` |
+| Add/update one feature or section ("I want to add…") | `ai-spector-resolve-task` |
+| Generate SRS (full chapter / DAG) | `ai-spector-generate-srs` |
+| Generate basic design (full wave) | `ai-spector-generate-basic-design` |
 | Prototype | `ai-spector-generate-prototype` |
 | Comments | `ai-spector-resolve-comments` |
 | Translation status / stale languages | `ai-spector-lang-status` |
 | Resolve / sync translations | `ai-spector-resolve-translation` |
+| Create task, open-ended doc/graph change | `ai-spector-resolve-task` |
 | “Generate docs” (vague) | `ai-spector-generate` |
 
 When a task skill applies, read its `references/` runbook fully before acting.

package/scaffold/cursor/skills/ai-spector-generate/SKILL.md

@@ -1,14 +1,22 @@
 ---
 name: ai-spector-generate
 description: >-
-  Routes document-generation requests to the correct skill based on the active template packs.
-  Use when the user says "generate docs", "generate requirements", "write SRS", or names a
-  document type without specifying a layer. Always checks packs.srs and packs.basicDesign before routing.
+  Routes full document-generation requests to the correct skill based on active template packs.
+  Use for "generate docs", "generate SRS", "write chapter N" (DAG waves from graph). If the user
+  wants to add/update a single feature or section ("I want to add…"), route to ai-spector-resolve-task
+  instead. Always checks packs.srs and packs.basicDesign before routing.
 ---
 
 # AI Spector — Generate (router)
 
-## Step 0 — Check active packs (always first)
+## Step 0 — Incremental vs full generate
+
+| User intent | Route to |
+|-------------|----------|
+| add / update / change one feature, section, API, screen | `ai-spector-resolve-task` |
+| generate SRS / basic design / full chapter from graph | continue below |
+
+## Step 1 — Check active packs (always first)
 
 Read `.ai-spector/docflow.config.json`. Check `packs.srs` and `packs.basicDesign` independently.
 

package/scaffold/cursor/skills/ai-spector-generate-basic-design/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: ai-spector-generate-basic-design
 description: >-
-  Generates or updates basic design documents from the traceability graph and SRS: screen list and
-  screen details, API list and endpoint details, database design under docs/basic-design/. Use when
-  the user asks for basic design, wireframes, screen map, API design, ERD, or list-screens.md. Do not
-  use for SRS-only work, HTML prototype, or graph analyze/index without doc generation.
+  Generates basic design chapters from the traceability graph in DAG order (screen list, API list,
+  wireframes wave). Do NOT use for incremental adds like "add an API endpoint" or "update screen X"
+  — use ai-spector-resolve-task instead. Do not use for SRS-only work, HTML prototype, or graph-only
+  analyze/index tasks.
 paths:
   - "docs/basic-design/**"
   - ".ai-spector/templates/basic_design/**"

package/scaffold/cursor/skills/ai-spector-generate-srs/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: ai-spector-generate-srs
 description: >-
-  Generates or updates the System Requirements Specification from the traceability graph and
-  docs/data-source context. Use when the user asks to generate or update SRS, requirements, use cases
-  (UC-xx), features (F-xx), or files under docs/srs/. Do not use for basic design screens/APIs,
+  Generates SRS chapters from the traceability graph in DAG order (full waves, "generate SRS",
+  "write chapter 4", use case list from graph). Do NOT use for incremental adds like "add a feature",
+  "I want to add login" — use ai-spector-resolve-task instead. Do not use for basic design,
   HTML prototype, or graph-only analyze/index tasks.
 paths:
   - "docs/srs/**"
@@ -35,4 +35,6 @@ paths:
 ## On CLI failure
 Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
 
-"generate SRS", "write requirements", "use case chapter", "feature list" → this skill.
+"generate SRS", "write chapter 3", "feature list from graph", "all UC details" → this skill.
+
+"add feature", "I want to add …", "update auth section" → **ai-spector-resolve-task** (plan-first).

package/scaffold/cursor/skills/ai-spector-resolve-task/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ai-spector-resolve-task
+description: >-
+  FIRST CHOICE for incremental doc/graph changes: add feature, add requirement, update
+  section, change prototype, "I want to…", "we need to…", create task. Mandatory
+  workflow: clarify → show GoalSpec + TaskPlan → wait for explicit yes → then execute.
+  Do NOT jump to edits or graph_impact before approval. Do NOT use generate-srs or
+  generate-basic-design for single-feature additions — use this skill instead.
+paths:
+  - "docs/**"
+  - "prototype/**"
+  - ".ai-spector/**"
+---
+
+# AI Spector — Resolve Task
+
+**Read first:** [references/runbook.md](references/runbook.md) — follow every phase in order.
+
+## You are in plan-first mode
+
+The user described a **change**, not a full generate-from-scratch run. Your job is to **plan and get approval before any write or impact tool**.
+
+### Forbidden until the user replies **yes** to the plan
+
+| Do NOT call | Do NOT do |
+|-------------|-----------|
+| `graph_impact` | Edit or Write any file |
+| `index`, `graph_merge`, `resolve_task` | Generate SRS/basic-design chapters |
+| `graph_validate`, `graph_report` | "Quick preview" edits |
+| Bulk reads of `docs/**` for writing | Run impact "to check scope" |
+
+### Allowed before approval (discover only)
+
+`docs_search`, `graph_query_fuzzy`, `graph_query` — to find **where** a change belongs. No impact, no edits.
+
+## Workflow (strict)
+
+```
+Phase 1  Receive intent          → acknowledge, no tools
+Phase 2  Clarify (≤3 questions) → fill GoalSpec fields
+Phase 3  Discover (optional)    → read-only lookup for scope
+Phase 4  Show plan              → GoalSpec + TaskPlan table
+Phase 5  Wait for approval      → user must say yes / approve / go ahead
+Phase 6  Execute                → edits + resolve_task for index/graph steps
+Phase 7  Report                 → state update summary
+```
+
+**Never skip Phase 2–5.** "Add login with Google" is not specific enough — you still clarify domain, target file/section, and done criteria.
+
+## First response template
+
+When this skill activates, start like this (adapt to the user's message):
+
+> I'll handle this through the **resolve-task** workflow — plan first, execute after you approve.
+>
+> To build the right plan:
+> 1. …
+> 2. …
+> 3. …
+
+Do not run tools in this first message unless the user already named exact file paths.
+
+## Triggers → this skill (not generate-*)
+
+| User says | Route here |
+|-----------|------------|
+| "I want to add login with Google" | **this skill** |
+| "add a requirement for …" | **this skill** |
+| "update the SRS section on …" | **this skill** |
+| "change prototype theme" | **this skill** |
+| "generate SRS" / "write chapter 4" | `ai-spector-generate-srs` |
+| "generate basic design" / "screen list" | `ai-spector-generate-basic-design` |
+
+## Checklist
+
+```
+- [ ] Announced resolve-task workflow (plan-first)
+- [ ] Asked clarifying questions → GoalSpec complete
+- [ ] Showed GoalSpec + TaskPlan → got explicit yes
+- [ ] Executed approved steps only
+- [ ] Reported state update
+```

package/scaffold/cursor/skills/ai-spector-resolve-task/references/runbook.md

@@ -0,0 +1,214 @@
+# Resolve Task — conversational runbook
+
+Plan-first workflow for incremental doc/graph changes. The agent **never edits or runs impact** until the user approves a written plan.
+
+---
+
+## Routing — when this runbook applies
+
+| User intent | Skill |
+|-------------|-------|
+| Add / update / change one feature, section, or requirement | **resolve-task** (this runbook) |
+| "I want to…", "we need to…", "create a task" | **resolve-task** |
+| Generate full SRS chapter or DAG wave from graph | `ai-spector-generate-srs` |
+| Generate screen list, API list, basic design wave | `ai-spector-generate-basic-design` |
+
+**Example:** "I want to add login with Google feature" → **resolve-task**, not generate-srs.
+
+---
+
+## Phase 1 — Receive intent
+
+User sends a free-form message.
+
+**Actions:** Read the message. Acknowledge you will use the resolve-task workflow.
+
+**Forbidden:** Every tool — no `graph_impact`, no `index`, no file edits, no bulk `docs/**` reads.
+
+**Then:** Go to Phase 2. Do not skip.
+
+---
+
+## Phase 2 — Clarify (mandatory)
+
+Ask what you need to fill **all four** `GoalSpec` fields. Batch ≤3 questions in one message.
+
+| Field | What to clarify |
+|-------|----------------|
+| `domain` | docs / prototype / graph / template / lang / comments? |
+| `scope` | Which file(s) or section(s)? |
+| `criteria` | What does "done" look like? |
+| `notes` | Constraints, related features, languages? |
+
+**Rules:**
+- **Always ask at least one question** unless the user already gave domain + exact file path(s) + acceptance criteria in the same message.
+- "Add login with Google" is **not** enough — clarify SRS vs prototype, which section, and done criteria.
+- Do not propose file content yet. Do not run impact.
+
+**Example (login with Google):**
+
+> I'll handle this through the **resolve-task** workflow — plan first, execute after you approve.
+>
+> To build the right plan:
+> 1. Should this go in **SRS** (e.g. features / external interfaces) or also **basic design / prototype**?
+> 2. Is there an existing auth section to extend, or a new feature id (e.g. F-xx)?
+> 3. What does done look like — e.g. requirements written + graph reindexed?
+
+---
+
+## Phase 3 — Discover (optional, read-only)
+
+Use **only** when you need to find where content belongs.
+
+| Allowed | Forbidden |
+|---------|-----------|
+| `docs_search({ query })` | `graph_impact` |
+| `graph_query_fuzzy({ query })` | `index`, `graph_merge` |
+| `graph_query({ seedId })` | Edit, Write |
+| `Read` a single file for structure (headings) | Bulk-read docs for drafting |
+
+Stop when you can name concrete `scope` paths. Go to Phase 4.
+
+---
+
+## Phase 4 — Build and show the plan
+
+Construct `GoalSpec` + `TaskPlan`. **Show both in chat.** Do not execute.
+
+### GoalSpec (show this)
+
+```
+Domain : docs
+Scope  : docs/srs/en/04-features/f-12-google-login.md  (example)
+Criteria:
+  - Google OAuth login requirements documented
+  - Linked to existing auth use case if applicable
+  - graph reindexed after edit
+Notes  : match style of existing F-xx feature files
+```
+
+### TaskPlan (show this)
+
+| # | Step | Tool |
+|---|------|------|
+| s1 | Add F-xx Google login feature doc (or extend existing section) | direct edit |
+| s2 | Check traceability impact | `graph_impact` |
+| s3 | Re-index project | `index` |
+| s4 | Merge knowledge → graph | `graph_merge` |
+
+**Risk:** show `low` / `medium` / `high` as an **estimate** from scope size, or write "computed at step s2 after approval". Do **not** call `graph_impact` during planning.
+
+### Approval gate
+
+End with:
+
+> **Approve this plan?** Reply **yes** to execute, or tell me what to change.
+
+**Forbidden:** Any step in the table until the user confirms.
+
+---
+
+## Phase 5 — Wait for approval
+
+Proceed only on explicit approval: "yes", "approve", "go ahead", "looks good", "execute".
+
+If the user changes the plan → update GoalSpec/TaskPlan → show again → wait again.
+
+---
+
+## Phase 6 — Execute
+
+Run **only** approved steps, in order.
+
+### Direct edit steps
+Use Edit / Write. Report each file changed.
+
+### MCP / CLI steps
+Use `resolve_task` for batched index/graph steps, or call MCP tools individually per the plan:
+
+```json
+{
+  "intent": "I want to add login with Google feature",
+  "goalSpec": {
+    "trigger": "I want to add login with Google feature",
+    "domain": "docs",
+    "scope": ["docs/srs/en/04-features/f-12-google-login.md"],
+    "criteria": ["Google OAuth requirements documented", "graph reindexed"]
+  },
+  "plan": {
+    "goal": {
+      "trigger": "I want to add login with Google feature",
+      "domain": "docs",
+      "scope": ["docs/srs/en/04-features/f-12-google-login.md"],
+      "criteria": ["Google OAuth requirements documented", "graph reindexed"]
+    },
+    "steps": [
+      { "id": "s2", "description": "Check traceability impact", "tool": "graph_impact", "args": { "change": "content_change" } },
+      { "id": "s3", "description": "Re-index project", "tool": "index", "args": {} },
+      { "id": "s4", "description": "Merge knowledge", "tool": "graph_merge", "args": {} }
+    ]
+  }
+}
+```
+
+CLI fallback: `npx ai-spector resolve-task plan.json`
+
+**Note:** Edit steps (s1) are done outside `resolve_task` — the tool only runs registered executors (`index`, `graph_merge`, `graph_impact`, `graph_report`).
+
+### If a step is blocked
+Report the blocker. Ask: skip, retry, or stop?
+
+---
+
+## Phase 7 — Report state update
+
+```
+✓ Task task-abc123 — COMPLETE
+  domain: docs  risk: low
+
+Steps:
+  ✓ [s1] Added docs/srs/en/04-features/f-12-google-login.md
+  ✓ [s2] graph_impact — 2 review, 0 regenerate
+  ✓ [s3] Re-index project
+  ✓ [s4] Merge knowledge
+
+State update:
+  1 file(s) changed
+  graph reindexed
+```
+
+Ask if anything else needs adjustment.
+
+---
+
+## Guardrails (non-negotiable)
+
+1. **No edits before approval** — including "let me draft it for you to review".
+2. **No `graph_impact` before approval** — impact is an execute-step, not a planning shortcut.
+3. **No `index` / `graph_merge` / `resolve_task` before approval**.
+4. **Do not route to generate-srs** for single-feature adds — stay in this workflow.
+5. **One approval gate** — clear yes, then execute all steps.
+
+---
+
+## CLI reference
+
+| Command | Purpose |
+|---------|---------|
+| `npx ai-spector resolve-task plan.json` | Execute approved plan JSON |
+| `npx ai-spector resolve-task plan.json --dry-run` | Validate without writing |
+| `npx ai-spector resolve-task plan.json --json` | Machine-readable output |
+
+MCP: `resolve_task` (schema: `ResolveTaskSchema`)
+
+---
+
+## If blocked
+
+See [cli-failures.md](../../ai-spector/references/cli-failures.md).
+
+| Issue | Fix |
+|-------|-----|
+| `No executor registered for tool "X"` | Use: `index`, `graph_merge`, `graph_report`, `graph_impact` |
+| Plan JSON parse error | Validate JSON before running |
+| Reindex fails | `npx ai-spector setup --check` |