ai-spector 0.3.0 → 0.3.2

package/scaffold/{.cursor → cursor}/commands/generate-basic-design.md

@@ -28,7 +28,7 @@ Arguments are **file paths** (case 2) or **free-text** (case 3). Paths are under
 | # | DAG id | Output | Query seed | Reason | Prerequisites |
 |---|--------|--------|------------|--------|---------------|
 | 1 | `bd.list-api` | `docs/basic-design/api-list.md` | `doc.srs.6-external-interfaces` | “API list” | SRS §6 if missing |
-| 2 | `bd.detail-api` | `docs/basic-design/api/…` | `F-01`, … | “APIs for feature X” | `bd.list-api`, SRS features |
+| 2 | `bd.detail-api` | `docs/basic-design/api/…` | rows in `api-list.md` §3 | “API detail for each endpoint” | `bd.list-api`, SRS §6 |
 
 3. Include **dependency closure** from `dag.basic-design.json` and missing SRS files (minimum: introduction + features per `workflow.dependencies.json`).
 4. Ask:
@@ -39,7 +39,7 @@ Reply **yes** to proceed, **no** to cancel, or edit the list.
 ```
 
 5. **Stop** without user confirmation.
-6. Clarify ambiguity early (e.g. “all API details” = every `F-xx` vs one feature; “screens” = list vs all screen detail files).
+6. Clarify ambiguity early (e.g. “all API details” = every endpoint row in `api-list.md` vs one endpoint; “screens” = list vs every row in Screen Index).
 
 ### Intent → DAG hints
 
@@ -47,10 +47,11 @@ Reply **yes** to proceed, **no** to cancel, or edit the list.
 |------------------------|------------------------|
 | database, DB, ERD, data model | `bd.db-design` → `db-design.md` |
 | API list, endpoints overview | `bd.list-api` → `api-list.md` |
-| API detail, per endpoint, REST | `bd.detail-api` → `docs/basic-design/api/` (per feature / endpoint) |
-| screen list, UI list | `bd.list-screen` → `screens/list-screens.md` |
-| screen detail, wireframe, per screen | `bd.detail-screen` → `docs/basic-design/screens/` |
-| one feature, F-01, checkout | `F-01` seeds for api/screen detail under that feature |
+| API detail, per endpoint, REST | `bd.detail-api` → `docs/basic-design/api/` (one file per endpoint row in `api-list.md` §3) |
+| screen list, UI list | `bd.list-screen` → `docs/basic-design/list-screens.md` |
+| screen detail, wireframe, per screen | `bd.detail-screen` → `docs/basic-design/screens/` (one file per Screen Index row) |
+| one endpoint, POST /checkout | that endpoint’s row in `api-list.md` → matching `api/<slug>.md` |
+| one screen, login, dashboard | that screen’s row in `list-screens.md` → matching `screens/<slug>.md` |
 | everything, full basic design | Case 1 — full DAG |
 
 ## Prerequisites
@@ -81,9 +82,10 @@ ai-spector graph validate
 2. Topological sort selected nodes + dependency ancestors (`bd.detail-api` after `bd.list-api`, etc.).
 3. Map seeds via `dag.basic-design.graph-seeds.json`:
    - Chapter artifacts → `documentNodes` id for ingest + SRS seed for **query**
-   - `perEndpoint` / `perScreen` → one target per `feature` (`F-xx`) from graph
+   - `perEndpoint` → after `api-list.md` exists, one target per **endpoint row** in §3 Endpoint Summary (not per `F-xx`); output slug from method + path (e.g. `post-checkout.md`)
+   - `perScreen` → after `list-screens.md` exists, one target per **Screen Index** row (not per feature); output slug from screen name (e.g. `login.md`)
 4. Classify disk: `good` | `missing_content` | `missing_file`.
-5. **Waves** — e.g. wave 0: `bd.db-design`, `bd.list-api`, `bd.list-screen` in parallel; wave 1: `bd.detail-api`; wave 2: `bd.detail-screen`.
+5. **Waves** — wave 0: `bd.db-design`, `bd.list-api`, `bd.list-screen` in parallel; wave 1: all `bd.detail-api` files in parallel; wave 2: all `bd.detail-screen` files in parallel. **After each wave:** merge + validate, then **`ai-spector index`** so list tables, section trees, and detail `doc.bd.*` nodes are in the graph before the next wave plans targets.
 
 ### 3. Per wave, then per target
 
@@ -97,7 +99,9 @@ ai-spector graph validate
 #### 3b. Write
 
 - Read DAG `template` files under **`.ai-spector/templates/`** (e.g. `.ai-spector/templates/basic_design/list-screen-template.md`). Missing folder → user must run `npx ai-spector init`.
-- Align API/screen names with graph `feature` titles and SRS feature detail files.
+- **List chapters first** — endpoint and screen names come from `api-list.md` and `list-screens.md` tables; detail files reference SRS/features via Source Requirement when relevant, not one file per `F-xx`.
+- **API detail** — one endpoint per file under `docs/basic-design/api/`; use `detail-api-template.md` for a single `METHOD /path` block.
+- **Screen detail** — one screen per file under `docs/basic-design/screens/`; use `detail-screen-template.md` for a single `## N. Screen:` section.
 
 #### 3c. Ingest (mandatory before next wave)
 
@@ -121,9 +125,14 @@ Merge patch (include `documentNodes` from `dag.basic-design.graph-seeds.json` wh
 ```bash
 ai-spector graph merge .ai-spector/.docflow/extract/projection-patch.json
 ai-spector graph validate
+ai-spector index
 ```
 
-Per-domain file: `rendersTo` from `F-xx` or `doc.bd.*` to actual path; `tracesTo` / `references` to SRS or API list as appropriate.
+**Reindex every wave (mandatory):** run `ai-spector index` after merge + validate for that wave — not only at the end. Wave 0 index parses list-chapter sections (`doc.bd.list-api`, `doc.bd.list-screen`, `doc.bd.db-design`) from disk; wave 1+ index adds per-endpoint / per-screen `doc.bd.api-*` / `doc.bd.screen-*` nodes and `contains` edges from list chapters. Without reindex, wave 1 cannot reliably expand endpoint rows from `api-list.md` §3, and wave 2 cannot expand Screen Index rows from `list-screens.md`.
+
+Use `ai-spector index --skip-graphify` when only markdown under `docs/basic-design/` changed (typical). Use `--force-graphify` only when `docs/data-source/` code paths must rebuild.
+
+Per-endpoint / per-screen file: `rendersTo` from `doc.bd.api-*` or `doc.bd.screen-*` to actual path; `contains` from `doc.bd.list-api` / `doc.bd.list-screen`; optional `tracesTo` from related `F-xx` when Source Requirement cites a feature.
 
 #### 3d. Log
 
@@ -131,20 +140,21 @@ Append `.ai-spector/.docflow/logs/generate-basic-design.log`.
 
 ### 4. Finish
 
-- Final `graph validate`.
+- If the last wave already ran `graph validate` + `ai-spector index`, a final validate is enough; otherwise run both again.
 - Suggest **`/summary basic-design`** (required by workflow before detail design).
 
 ## Waves (reference)
 
-| Wave | DAG nodes (parallel within wave) |
-|------|----------------------------------|
-| 0 | `bd.db-design`, `bd.list-api`, `bd.list-screen` |
-| 1 | `bd.detail-api` (+ per-feature API files) |
-| 2 | `bd.detail-screen` (+ per-feature screen files) |
+| Wave | DAG nodes (parallel within wave) | After wave |
+|------|----------------------------------|------------|
+| 0 | `bd.db-design`, `bd.list-api`, `bd.list-screen` | merge → validate → **`ai-spector index`** |
+| 1 | `bd.detail-api` (+ one file per api-list endpoint row) | merge → validate → **`ai-spector index`** |
+| 2 | `bd.detail-screen` (+ one file per Screen Index row) | merge → validate → **`ai-spector index`** |
 
 ## Guardrails
 
-- **Parallel only within a wave** — never `bd.detail-api` before `bd.list-api` is ingested.
+- **Parallel only within a wave** — never `bd.detail-api` before `bd.list-api` is ingested and **indexed**.
+- **Reindex after every wave** — `graph merge` alone does not parse markdown bodies; `ai-spector index` is required before the next wave.
 - **Every target** gets `graph query` + dependency queries.
 - **Case 3** requires explicit user **yes** before writes.
 - Do not overwrite `good` without user intent.

package/scaffold/cursor/commands/resolve-comments.md

@@ -0,0 +1,145 @@
+# /resolve-comments
+
+IDE-first workflow (Cursor) for **git-backed review comments** under `comments/`. Web reviewers create threads; you resolve locally: inbox in chat → pick thread → impact → propose edit → apply → commit (doc + resolve meta) → push.
+
+No Writer API — storage is git-only (`meta_data.json` + `events.jsonl`).
+
+## Usage
+
+| You say | Agent does |
+|---------|------------|
+| `/resolve-comments` | Inbox table in chat → wait for your pick |
+| `/resolve-comments C-001` | Plan + impact for pick **C-001** |
+| `/resolve-comments srs/01-overview` | Inbox filtered to that file |
+
+## IDE workflow (agent — follow in order)
+
+### Phase 0 — Sync
+
+```bash
+git pull
+```
+
+### Phase 1 — Show thread pick list in chat (user selects)
+
+```bash
+ai-spector comments inbox --json
+```
+
+**IDE presentation (required):**
+
+1. Read `idePresentation.markdown` from JSON — render **only that markdown table** in chat.
+2. Follow `idePresentation.rules`: **one row per open thread**, not per reply; **no raw JSON**; **no thread uuids** in user-facing text.
+3. Use **pick ids** (`C-001`, `C-002`, …) for selection.
+
+Example table (from CLI):
+
+| Pick | Document | Lines | Lang | Reviewer ask |
+|------|----------|-------|------|--------------|
+| **C-001** | `docs/srs/01-overview.md` | 12-14 | EN | Please clarify… |
+
+**Stop and ask:** “Which thread should we resolve? Reply with **C-00N**.”
+
+Do not start editing until the user picks (unless they already passed `C-001` in the slash command).
+
+**Do not use** `comments list` for user selection — use **`comments inbox`** only.
+
+### Phase 2 — Plan + impact (after pick)
+
+```bash
+ai-spector comments plan C-001 --json
+```
+
+**Show in chat:** full thread comments, anchored doc text, impact summary, regen targets.
+
+### Phase 3 — Propose edit (user approval required)
+
+1. Quote anchored lines + reviewer ask
+2. Propose concrete markdown change
+3. Ask: **“Apply this edit?”** — wait for explicit approval
+
+### Phase 4 — Apply edit
+
+Edit `anchor.docPath` at lines `startLine`–`endLine`. Show diff summary in chat.
+
+### Phase 5 — Resolve status + single git commit (doc + comment meta)
+
+Each resolve must land in git with **both** the **document fix** and **comment thread metadata** — never commit only `comments/` without the changed doc file.
+
+**Steps:**
+
+```bash
+# 1) Stage and commit doc fix first (establishes resolvedInCommitSha target)
+git add docs/srs/....md
+git commit -m "fix(docs): address comment C-001 on srs/01-overview lines 12-14"
+
+# 2) Write resolve meta pointing at that doc commit
+ai-spector comments resolve <threadId> --file srs/01-overview \
+  --expected-version <v from plan> --json
+
+# 3) Stage comment meta AND re-include doc in the same final commit
+git add comments/srs/01-overview/<threadId>/ docs/srs/....md
+git commit --amend -m "fix(docs): address comment C-001 on srs/01-overview lines 12-14
+
+Resolved thread <threadId>. Pick C-001."
+
+git push
+```
+
+**Why amend:** `comments resolve` needs HEAD after the doc commit for `resolvedInCommitSha`. Amending folds `meta_data.json` + `events.jsonl` into the **same commit** as the doc change so one push contains the full resolve.
+
+**Commit must include:**
+
+| Path | Content |
+|------|---------|
+| `docs/…` | Edited document (the fix) |
+| `comments/…/{thread_id}/meta_data.json` | `status: resolved`, `resolvedInCommitSha`, … |
+| `comments/…/{thread_id}/events.jsonl` | append `resolved` event |
+
+**Never:** `git add` only `comments/` while doc changes stay unstaged or uncommitted.
+
+If HEAD moved before resolve, pass `--commit-sha <doc-fix-sha>` explicitly.
+
+### Phase 6 — Optional follow-up
+
+```bash
+ai-spector index
+```
+
+Or targeted `/generate-srs` / `/generate-basic-design` when plan lists regen targets.
+
+## Multi-thread session
+
+Re-run `comments inbox --json` → show `idePresentation.markdown` → ask for next pick.
+
+## Chat presentation rules
+
+- Inbox: **`idePresentation.markdown` table only** (threads, not replies)
+- Plan/impact: full detail after pick
+- Commits: **doc file + comment meta together** (amend pattern above)
+- Pick ids in chat; thread ids only in CLI args
+
+## CLI reference
+
+| Command | Purpose |
+|---------|---------|
+| `comments inbox [--json]` | Thread pick list + `idePresentation` for chat |
+| `comments plan C-001 [--json]` | Anchor excerpt + graph impact |
+| `comments resolve <threadId> --file <path> [--expected-version]` | Update meta before final amend commit |
+
+## Guardrails
+
+- No Writer API
+- No resolve before doc edit is applied
+- No commit with only metadata — **always include changed doc file**
+- No push until amend commit contains doc + `comments/…/thread/`
+
+## If blocked
+
+See [_cli-failures.md](./_cli-failures.md).
+
+| Issue | Fix |
+|-------|-----|
+| Unknown C-00N | Re-run `comments inbox --json` |
+| Stale version | Re-run `comments plan`, refresh `--expected-version` |
+| Doc missing from commit | `git status` — stage `docs/…` before amend |

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

@@ -0,0 +1,22 @@
+# AI Spector skill router
+
+Cursor loads skills by **description** when the user does not use a slash command. Enable **all** skills under `.cursor/skills/` after `init`.
+
+## Skills
+
+| Skill folder | When Cursor should use it |
+|--------------|---------------------------|
+| `ai-spector` | Any ai-spector / docflow / `.ai-spector` project work; shared CLI rules |
+| `ai-spector-graph` | Analyze, index, validate, impact, visualize, Graphify, knowledge.json, regen scope |
+| `ai-spector-generate` | Generate or update SRS, basic design, detail design under `docs/` |
+| `ai-spector-resolve-comments` | Review comments in `comments/`, resolve threads, C-001 pick list |
+
+## Slash commands (explicit)
+
+When the user runs `/analyze`, `/generate-srs`, `/resolve-comments`, etc., read the matching file in `.cursor/commands/` — skills and commands share the same rules.
+
+## Priority
+
+1. Explicit slash command → `commands/<name>.md`
+2. Natural language → task skill above + same command doc when one exists
+3. Ambiguous → `ai-spector` core + ask which task (graph vs generate vs comments)

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

@@ -0,0 +1,47 @@
+---
+name: ai-spector
+description: >-
+  AI Spector docflow core — traceability graph, .ai-spector project, CLI failure rules, templates.
+  Use when working in an ai-spector project but task is unclear; read _skill-router.md to pick a task skill.
+---
+
+# AI Spector (core)
+
+Shared rules for **all** ai-spector work. For a specific task, also load the matching task skill (see router below).
+
+**Workflow index:** `.cursor/commands/_workflow.md`
+**Skill router:** `.cursor/skills/_skill-router.md`
+
+## CLI failure rule (non-negotiable)
+
+When `ai-spector` exits non-zero or required `--json` is missing/invalid:
+
+1. **Stop** — no generate, no bulk `docs/srs/**` reads, no hand-editing the whole graph.
+2. **Report** per `.cursor/commands/_cli-failures.md` (verbatim CLI output + fix steps).
+3. **Fix**, then **re-run the same CLI**.
+
+Never bypass CLI with manual graph edits or invented content.
+
+## Graphify MCP
+
+`init` writes `.cursor/mcp.json` → graph at `.ai-spector/.docflow/graph/graphify-out/graph.json`.
+
+## Heart of the system
+
+`.ai-spector/graph/traceability.graph.json` — context via `ai-spector graph query <id> --json`.
+
+Run CLI from project root; prefer `npx ai-spector` if not on PATH.
+
+## Task skills (auto-routing)
+
+| User intent | Skill | Command doc |
+|-------------|-------|---------------|
+| Analyze, index, validate, impact, visualize graph | `ai-spector-graph` | `commands/analyze.md`, `index.md`, `impact.md`, … |
+| Generate SRS / basic design / detail design | `ai-spector-generate` | `commands/generate-*.md` |
+| Resolve review comments under `comments/` | `ai-spector-resolve-comments` | `commands/resolve-comments.md` |
+
+When the user uses a **slash command** (`/analyze`, `/generate-srs`, `/resolve-comments`), follow that command file directly — skills reinforce the same rules.
+
+## Templates
+
+Read from `.ai-spector/templates/` before any generation. Missing templates → `npx ai-spector init --force`.

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

@@ -0,0 +1,41 @@
+---
+name: ai-spector-generate
+description: >-
+  AI Spector document generation — SRS, basic design, detail design from traceability graph.
+  Use for /generate-srs, /generate-basic-design, /generate-detail-design, or when user asks to
+  generate, write, or update requirements specs, SRS chapters, basic design, detail design, or docs under docs/srs docs/basic-design.
+---
+
+# AI Spector — Generate
+
+**Core rules:** `.cursor/skills/ai-spector/SKILL.md`
+**Graph context:** `.cursor/commands/_generate-graph.md`, `_graph.md`
+
+## Route to command doc
+
+| Trigger | Read first | Notes |
+|---------|------------|-------|
+| `/generate-srs`, SRS, requirements spec | `commands/generate-srs.md` | DAG waves, `graph query`, templates in `.ai-spector/templates/srs/` |
+| `/generate-basic-design`, screens, APIs, DB design | `commands/generate-basic-design.md` | `templates/basic_design/` |
+| `/generate-detail-design` | `commands/generate-detail-design.md` | `templates/detail_design/` |
+
+## Before generating
+
+1. **`ai-spector graph validate`** should pass (or run `/validate-graph` first).
+2. **Read the template** from `.ai-spector/templates/` — never guess structure.
+3. After each wave: **`graph merge`** projection patch with `rendersTo` + `dependsOn`.
+4. After SRS generation: recommend **`/index`**.
+
+## Natural language → command
+
+| User says | Action |
+|-----------|--------|
+| "generate SRS", "write requirements", "create use case docs" | `generate-srs.md` |
+| "basic design", "screen list", "API design doc" | `generate-basic-design.md` |
+| "detail design", "feature detail doc" | `generate-detail-design.md` |
+
+Confirm scope when user describes generation in natural language (not explicit paths).
+
+## Generate discipline
+
+Accuracy over speed — batch only same-wave independent targets; merge + validate after each wave.

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

@@ -0,0 +1,39 @@
+---
+name: ai-spector-graph
+description: >-
+  AI Spector graph operations — analyze docs/data-source, index refresh, validate traceability graph,
+  impact/regen scope, visualize graph, link semantic edges. Use for /analyze, /index, /validate-graph,
+  /impact, /visualize-graph, or when user asks about traceability graph, knowledge.json, Graphify, or what to regenerate.
+---
+
+# AI Spector — Graph
+
+**Core rules:** `.cursor/skills/ai-spector/SKILL.md` (CLI failure, graph path).
+
+## Route to command doc
+
+| Trigger | Read first | CLI |
+|---------|------------|-----|
+| `/analyze`, ingest data-source, extract knowledge | `commands/analyze.md` | `ai-spector analyze` → graphify → merge → validate |
+| `/index`, refresh graph after edits | `commands/index.md` | `ai-spector index` |
+| `/validate-graph`, graph errors | `commands/validate-graph.md` | `ai-spector graph validate` |
+| `/impact`, what breaks, regen scope, git diff impact | `commands/impact.md` | `ai-spector graph impact … --json` |
+| `/visualize-graph`, explore graph in browser | `commands/visualize-graph.md` | `ai-spector graph visualize --open` |
+| `/link-graph`, semantic relatesTo edges | `commands/link-graph.md` | `graph merge --semantic` |
+| `/sync-graph` | `commands/sync-graph.md` | per command |
+| `/summary` (index summaries only) | `commands/summary.md` | index build under `.ai-spector/index/` |
+
+## Natural language → command
+
+| User says | Action |
+|-----------|--------|
+| "analyze my data source", "run analyze" | `/analyze` flow → `analyze.md` |
+| "refresh the graph", "re-index" | `/index` → `index.md` |
+| "validate graph", "graph has errors" | `/validate-graph` |
+| "what's the impact", "what do I need to regenerate" | `/impact` → `impact.md` |
+| "show the graph", "visualize traceability" | `/visualize-graph` |
+
+## References
+
+- Graph CLI details: `commands/_graph.md`
+- Generate graph patches: `commands/_generate-graph.md`

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

@@ -0,0 +1,42 @@
+---
+name: ai-spector-resolve-comments
+description: >-
+  AI Spector git-backed review comment resolve — list open threads, pick C-001, plan with impact,
+  propose doc fix, commit doc + comment meta. Use for /resolve-comments, comments/ folder,
+  meta_data.json, reviewer comments on SRS/basic design, or "resolve this comment thread".
+---
+
+# AI Spector — Resolve comments
+
+**Core rules:** `.cursor/skills/ai-spector/SKILL.md`
+**Full workflow:** `.cursor/commands/resolve-comments.md` (follow step-by-step)
+
+## Quick flow
+
+1. `git pull`
+2. `ai-spector comments inbox --json` → show **`idePresentation.markdown`** only (thread table, pick ids)
+3. User picks **C-00N** → `ai-spector comments plan C-00N --json` (impact + anchor)
+4. Propose edit → user approves → apply to `docs/…`
+5. Commit doc → `comments resolve` → amend commit with **doc + `comments/…/thread/`** → push
+
+## CLI
+
+| Step | Command |
+|------|---------|
+| Inbox | `ai-spector comments inbox --json` |
+| Plan | `ai-spector comments plan C-001 --json` |
+| Resolve meta | `ai-spector comments resolve <threadId> --file <logical_path> --expected-version <v>` |
+
+## Natural language → this skill
+
+| User says | Action |
+|-----------|--------|
+| "resolve comments", "fix review comments", "open comment threads" | Start inbox flow |
+| "address C-001", "resolve thread on srs/…" | `plan` then edit + commit |
+| "comments under comments/" | Git-only F-05 flow — no Writer API |
+
+## Guardrails
+
+- Inbox: thread table only — no raw JSON or thread uuids in chat
+- Commit must include **changed doc file** and comment meta (amend pattern in `resolve-comments.md`)
+- No resolve before doc fix is applied

package/templates/basic_design/detail-api-template.md

@@ -1,6 +1,6 @@
-# API Detail: <Project Name>
+# API Detail: <METHOD /path>
 
-> This document specifies detailed request/response schemas, path/query parameters, and error handling for each API endpoint. For the endpoint list and overview, see the API List document.
+> **One endpoint per file** under `docs/basic-design/api/<slug>.md` (slug from method + path, e.g. `post-checkout.md`). For the endpoint list and overview, see `docs/basic-design/api-list.md`.
 
 **Source Requirements:** SRS Section 4 (System Features), Section 6.2 (Software Interfaces)
 

package/templates/basic_design/detail-screen-template.md

@@ -1,6 +1,6 @@
-# Screen Detail:
+# Screen Detail: <Screen Name>
 
-> This document provides detailed layout, component, and interaction specifications for each screen. For the screen map and design system, see the Screen Map (List Screen) document. Use one section per screen; duplicate the structure below for each screen in the Screen Index.
+> **One screen per file** under `docs/basic-design/screens/<slug>.md`. For the screen map and design system, see `docs/basic-design/list-screens.md`. Use a single `## 1. Screen:` section in this file.
 
 **Source Requirements:** SRS Section 6.1 (User Interfaces)
 

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

@@ -1,62 +0,0 @@
----
-name: ai-spector
-description: "Cursor-first docs: user runs slash commands; agent runs CLI; on CLI failure stop and help fix — no manual bypass."
----
-
-# AI Spector Skill
-
-**Workflow:** `.cursor/commands/_workflow.md` — user only runs `npx ai-spector init` once, then slash commands.
-
-**Graphify MCP:** `init` configures `.cursor/mcp.json` → graph file at `.ai-spector/.docflow/graph/graphify-out/graph.json` (not `docs/data-source/graphify-out/`).
-
-## CLI failure rule (non-negotiable)
-
-When `ai-spector` exits non-zero or required `--json` is missing/invalid:
-
-1. **Stop** — no generate, no bulk `docs/srs/**` reads, no hand-editing the whole graph.
-2. **Report** using the format in `.cursor/commands/_cli-failures.md` (verbatim CLI output + plain fix steps).
-3. **Fix** the root cause, then **re-run the same CLI** and continue the slash command.
-
-Never ignore CLI errors and “work around” with index files, manual BFS, or inventing graph content. See `_cli-failures.md` for forbidden fallbacks.
-
-## Slash commands (user)
-
-| Command | Agent runs CLI |
-|---------|----------------|
-| `/analyze` | `analyze` → `graphify update` → Graphify MCP extract → `graph merge` → `graph validate` |
-| `/index` | `ai-spector index` — rebuild graph structure, re-merge knowledge, Graphify storage, doc indexes |
-| `/summary` | Build `.ai-spector/index/*.md` summaries (optional; graph is primary for generation) |
-| `/validate-graph` | `graph validate` |
-| `/visualize-graph` | `graph visualize --open` |
-| `/generate-srs` | All DAG, explicit paths, or natural-language scope (confirm before gen) → waves → query → write → merge |
-| `/impact` | Empty args → git diff + seeds; else resolve → `graph impact <id> --json` (optional `--git` / `--file` / `--heading`) |
-| `/generate-basic-design` | Same as SRS: all / paths / request (**confirm**) → waves → query → merge (`dag.basic-design.*`) |
-| `/generate-detail-design` | `graph query` per target |
-
-Run CLI from **project workspace root**; prefer `npx ai-spector` if the binary is not on PATH.
-
-## Heart of the system
-
-`.ai-spector/graph/traceability.graph.json`
-
-Context: **`ai-spector graph query <seedId> --json`** — depth 4 for targets, depth 2 for DAG deps; use `projectionPaths`. After each generated file: **`graph merge`** projection patch with `rendersTo` + `dependsOn`. Details: `_generate-graph.md`, `_graph.md`.
-
-**Generate:** accuracy over speed — batch only same-wave independent targets; merge + validate after each wave.
-
-## Templates (mandatory path)
-
-`npx ai-spector init` copies bundled templates to **`.ai-spector/templates/`** (see `docflow.config.json` → `paths.templates`).
-
-Before `/generate-srs`, `/generate-basic-design`, or `/generate-detail-design`:
-
-1. **Read** the template file from `.ai-spector/templates/` (DAG `template` field is relative to that root, e.g. `srs/1-introduction.md`, `basic_design/list-screen-template.md`).
-2. **Preserve** the template’s headings and section order in the output under `docs/`.
-3. If `.ai-spector/templates/` is missing, tell the user to run **`npx ai-spector init`** (or `init --force` to refresh) — do not guess structure from memory or search `node_modules`.
-
-| Kind | Directory |
-|------|-----------|
-| SRS | `.ai-spector/templates/srs/` |
-| Basic design | `.ai-spector/templates/basic_design/` |
-| Detail design | `.ai-spector/templates/detail_design/` |
-
-Optional index: `.ai-spector/templates/README.md`.