ai-spector 0.8.32 → 0.8.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spector",
-  "version": "0.8.32",
+  "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

@@ -1,43 +1,34 @@
 ---
 name: ai-spector-resolve-task
 description: >-
-  Conversational task workflow (create task, resolve task): clarify intent, build
-  GoalSpec + TaskPlan, get approval, then execute via resolve_task MCP or CLI.
-  Use for create task, add/update requirements, doc edits, prototype changes, or
-  any multi-step change described in natural language.
+  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
 
-## When to use
+## Plan-first mode
 
-- "create task", "create a task", "new task", "resolve task"
-- "add requirement", "update docs", "change prototype", "I want to…", "we need to…"
-- Any open-ended doc/graph change that is not a full generate-from-scratch workflow
+**Forbidden before user approves the plan:** `graph_impact`, `index`, `graph_merge`, `resolve_task`, Edit/Write.
 
-## Workflow
-
-```
-1. Receive user intent (do not act yet)
-2. Ask ≤3 clarifying questions → build GoalSpec
-3. Show GoalSpec + TaskPlan → wait for approval
-4. Execute: direct edits + resolve_task MCP (or CLI)
-5. Report state update
-```
-
-Full runbook: `.cursor/skills/ai-spector-resolve-task/references/runbook.md` (same content after init/sync-cursor).
+**Allowed for discovery only:** `docs_search`, `graph_query_fuzzy`, `graph_query`, Read (structure).
 
-## Checklist
+## Workflow
 
 ```
-- [ ] Clarified intent → GoalSpec (domain, scope, criteria)
-- [ ] Showed plan and got user approval
-- [ ] Executed steps (edits + resolve_task for index/graph steps)
-- [ ] Reported results + state update
+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
 ```
 
-## MCP
+## Routing
 
-`resolve_task({ intent, goalSpec, plan, dryRun? })` — only after user approves the plan.
+| "I want to add login with Google" | **this skill** |
+| "generate SRS" / "write chapter 4" | `ai-spector-generate-srs` |
 
-CLI fallback: `npx ai-spector resolve-task plan.json`
+Runbook: `.cursor/skills/ai-spector-resolve-task/references/runbook.md`

package/scaffold/claude/CLAUDE.md

@@ -90,7 +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` |
-| Create task / open-ended doc change | `ai-spector-resolve-task` |
+| 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
 

package/scaffold/cursor/WORKFLOW.md

@@ -38,7 +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 |
-| Create task / change docs | “create a task”, “add requirement”, “update SRS section”, “I want to…” | `ai-spector-resolve-task` | clarify → show GoalSpec + TaskPlan → approve → `resolve_task` MCP or direct edits |
+| 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,7 +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` |
-| Create task / open-ended doc change | `ai-spector-resolve-task` |
+| 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,11 +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, add requirement, update docs, change prototype, new section, "I want to…", "we need to…" | `ai-spector-resolve-task` | `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

@@ -80,8 +80,9 @@ 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` |

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

@@ -1,11 +1,11 @@
 ---
 name: ai-spector-resolve-task
 description: >-
-  Conversational task workflow (create task, resolve task): agent clarifies user
-  intent, builds a GoalSpec + TaskPlan, shows it for approval, then executes via
-  the resolve_task MCP tool or CLI. Use when the user wants to create a task,
-  add/update a requirement, change a prototype, update docs, regenerate
-  sections, or any multi-step doc/graph change described in natural language.
+  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/**"
@@ -14,25 +14,69 @@ paths:
 
 # AI Spector — Resolve Task
 
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
+**Read first:** [references/runbook.md](references/runbook.md) — follow every phase in order.
 
-## Required reading
+## You are in plan-first mode
 
-[references/runbook.md](references/runbook.md) — follow phases in order.
+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**.
 
-## Checklist
+### 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)
 
 ```
-- [ ] Receive user intent (free-form)
-- [ ] Ask ≤3 clarifying questions → build GoalSpec
-- [ ] Show GoalSpec + TaskPlan → wait for approval
-- [ ] Execute via resolve_task MCP tool (or CLI)
-- [ ] Report results + state update
+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
 ```
 
-## Natural language triggers → this skill
+**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. …
 
-"create task", "create a task", "new task", "resolve task", "run a task",
-"add requirement", "update docs", "change prototype", "new feature section",
-"update SRS", "regenerate screens", "I want to…", "we need to…",
-any open-ended change request that is not a full generate-from-scratch workflow.
+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

@@ -1,156 +1,193 @@
 # Resolve Task — conversational runbook
 
-Chat-first workflow for any multi-step doc/graph change. User describes intent in plain language; agent clarifies, plans, gets approval, then executes.
+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. **Do not act yet.** Just read and move to Phase 2.
+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.
 
-Examples:
-- "create a task to add authentication to the SRS"
-- "add an authentication requirement to the SRS"
-- "change the prototype theme to dark"
-- "we need a new API section in basic design"
+**Then:** Go to Phase 2. Do not skip.
 
 ---
 
-## Phase 2 — Clarify (≤ 3 questions)
+## Phase 2 — Clarify (mandatory)
 
-Ask only what is needed to fill `GoalSpec`. Stop when you can answer all four fields.
+Ask what you need to fill **all four** `GoalSpec` fields. Batch ≤3 questions in one message.
 
 | Field | What to clarify |
 |-------|----------------|
-| `domain` | Which area: docs / prototype / graph / template / lang? |
-| `scope` | Which specific files or sections change? |
+| `domain` | docs / prototype / graph / template / lang / comments? |
+| `scope` | Which file(s) or section(s)? |
 | `criteria` | What does "done" look like? |
-| `notes` | Any constraints, tone, related nodes? |
+| `notes` | Constraints, related features, languages? |
 
 **Rules:**
-- Ask at most 3 questions per round; batch them in one message.
-- If the intent is already specific enough, skip to Phase 3.
-- Do not propose edits or generate content yet.
+- **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 |
 
-**Example clarification message:**
-> To make sure I plan this correctly:
-> 1. Should this go in the main SRS (`docs/srs/`) or a language variant?
-> 2. Is there an existing section to extend, or does this need a new one?
-> 3. What does "done" look like — e.g. the section exists + graph reindexed?
+Stop when you can name concrete `scope` paths. Go to Phase 4.
 
 ---
 
-## Phase 3 — Build and show the plan
+## Phase 4 — Build and show the plan
 
-Once you have enough to fill `GoalSpec`, construct the plan and **show it in chat** before doing anything.
+Construct `GoalSpec` + `TaskPlan`. **Show both in chat.** Do not execute.
 
-### GoalSpec format (show this)
+### GoalSpec (show this)
 
 ```
 Domain : docs
-Scope  : docs/srs/02-features.md
+Scope  : docs/srs/en/04-features/f-12-google-login.md  (example)
 Criteria:
-  - FR-AUTH section present with at least 3 requirements
-  - graph reindexed successfully
-Notes  : keep consistent with existing FR-PAY section style
+  - 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 format (show this)
+### TaskPlan (show this)
 
 | # | Step | Tool |
 |---|------|------|
-| s1 | Edit docs/srs/02-features.md — add FR-AUTH section | (direct edit) |
-| s2 | Re-index project | `index` |
-| s3 | Merge knowledge | `graph_merge` |
+| 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 level:** low / medium / high / critical (from impact analysis)
+**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.
 
-**Then ask:** "Does this plan look right? Reply **yes** to execute, or tell me what to change."
+### Approval gate
 
-Do not proceed until the user confirms.
+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 4 — Execute
+## Phase 6 — Execute
 
-After approval, run each step in order.
+Run **only** approved steps, in order.
 
-### Steps that are direct edits
-Use the Edit / Write tools directly. Report each file changed.
+### Direct edit steps
+Use Edit / Write. Report each file changed.
 
-### Steps that call MCP tools
-Use the `resolve_task` MCP tool with the approved plan:
+### MCP / CLI steps
+Use `resolve_task` for batched index/graph steps, or call MCP tools individually per the plan:
 
 ```json
 {
-  "intent": "<original user message>",
+  "intent": "I want to add login with Google feature",
   "goalSpec": {
-    "trigger": "<original user message>",
+    "trigger": "I want to add login with Google feature",
     "domain": "docs",
-    "scope": ["docs/srs/02-features.md"],
-    "criteria": ["FR-AUTH section present", "graph reindexed"]
+    "scope": ["docs/srs/en/04-features/f-12-google-login.md"],
+    "criteria": ["Google OAuth requirements documented", "graph reindexed"]
   },
   "plan": {
-    "goal": { "...same as goalSpec..." },
+    "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": "Re-index project", "tool": "index", "args": {} },
-      { "id": "s3", "description": "Merge knowledge",  "tool": "graph_merge", "args": {} }
+      { "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": {} }
     ]
   }
 }
 ```
 
-Or via CLI if MCP is unavailable:
+CLI fallback: `npx ai-spector resolve-task plan.json`
 
-```bash
-# write plan.json, then:
-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 in chat. Ask the user: "Step **sN** is blocked: `<reason>`. Should I skip it, retry, or stop?"
+Report the blocker. Ask: skip, retry, or stop?
 
 ---
 
-## Phase 5 — Report state update
-
-After execution, show a summary:
+## Phase 7 — Report state update
 
 ```
 ✓ Task task-abc123 — COMPLETE
   domain: docs  risk: low
 
 Steps:
-  ✓ [s1] Edit docs/srs/02-features.md
-  ✓ [s2] Re-index project
-  ✓ [s3] Merge knowledge
+  ✓ [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:
-  reindexed: 1 file(s)
-  graph diff: +2 -0 ~1
-  3 file(s) changed across 3 steps
+  1 file(s) changed
+  graph reindexed
 ```
 
-Then ask if there is anything else to adjust.
-
----
-
-## Replanning
-
-If the user changes their mind after seeing the plan (Phase 3), go back to Phase 2 — update `GoalSpec` + `TaskPlan` and show the revised plan again.
-
-If a step fails mid-execution, either:
-- Replan without that step and continue, or
-- Stop and report the full blocker to the user
+Ask if anything else needs adjustment.
 
 ---
 
-## Guardrails
+## Guardrails (non-negotiable)
 
-- **Never start editing** before the user approves the plan.
-- **Never skip the clarify phase** — even one ambiguous word can target the wrong file.
-- **Never run `resolve_task` with an unapproved plan.**
-- Ask for approval once, clearly. Don't loop approval prompts.
+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.
 
 ---
 
@@ -158,11 +195,11 @@ If a step fails mid-execution, either:
 
 | Command | Purpose |
 |---------|---------|
-| `npx ai-spector resolve-task plan.json` | Execute a pre-built plan JSON |
+| `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 tool: `resolve_task` (schema: `ResolveTaskSchema`)
+MCP: `resolve_task` (schema: `ResolveTaskSchema`)
 
 ---
 
@@ -172,6 +209,6 @@ See [cli-failures.md](../../ai-spector/references/cli-failures.md).
 
 | Issue | Fix |
 |-------|-----|
-| `No executor registered for tool "X"` | Use a supported tool: `index`, `graph_merge`, `graph_report`, `graph_impact` |
-| Plan JSON parse error | Validate JSON with `node -e "JSON.parse(require('fs').readFileSync('plan.json','utf8'))"` |
-| Reindex fails | Check `npx ai-spector setup --check` first |
+| `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` |