ai-spector 0.4.2 → 0.4.4

package/package.json

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

package/scaffold/cursor/skills/README.md

@@ -14,7 +14,6 @@ Enable **every** folder under `.cursor/skills/` in Cursor (Settings → Rules
 | Analyze, index, validate graph, impact, visualize | `ai-spector-graph` |
 | SRS / requirements | `ai-spector-generate-srs` |
 | Screens, APIs, DB basic design | `ai-spector-generate-basic-design` |
-| Detail / implementation design | `ai-spector-generate-detail-design` |
 | HTML prototype | `ai-spector-generate-prototype` |
 | Review comments | `ai-spector-resolve-comments` |
 | Unsure | `ai-spector` (core) |

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

@@ -6,7 +6,7 @@ Agents use this when intent is ambiguous.
 
 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 detail vs prototype vs comments).
+3. **Still unclear** — `ai-spector` core + one question (graph vs SRS vs basic design vs prototype vs comments).
 
 ## Task → skill → runbook
 
@@ -22,8 +22,7 @@ Agents use this when intent is ambiguous.
 | doc summaries | `ai-spector-graph` | `references/summary.md` |
 | SRS, use cases, features, requirements | `ai-spector-generate-srs` | `references/runbook.md` |
 | screens, APIs, wireframes, basic design | `ai-spector-generate-basic-design` | `references/runbook.md` |
-| detail design, implementation spec | `ai-spector-generate-detail-design` | `references/runbook.md` |
-| HTML prototype | “HTML prototype”, “mockup screens”, “prototype with stripe theme” | `ai-spector-generate-prototype` | `references/runbook.md`, `references/theme-picker.md` |
+| HTML prototype | `ai-spector-generate-prototype` | `references/runbook.md` |
 | review comments, C-001, inbox | `ai-spector-resolve-comments` | `references/runbook.md` |
 | “generate docs” (no layer named) | `ai-spector-generate` | route to one skill above |
 
@@ -34,7 +33,6 @@ Shared: [ai-spector/references/cli-failures.md](./ai-spector/references/cli-fail
 ```text
 analyze → validate graph → generate SRS → index
   → generate basic design → index
-  → generate detail design
   → prototype setup → generate HTML screens
 ```
 

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

@@ -4,7 +4,7 @@ description: >-
   Provides shared rules for AI Spector docflow projects: CLI failure handling, traceability graph path,
   and routing to task skills. Use when the user mentions ai-spector, docflow, or .ai-spector but the
   task is unclear, or for init and project layout. Do not use when the user clearly wants SRS,
-  basic design, detail design, HTML prototype, graph operations, or comment resolution — use the
+  basic design, HTML prototype, graph operations, or comment resolution — use the
   matching task skill instead.
 ---
 
@@ -36,7 +36,6 @@ When `ai-spector` exits non-zero, required `--json` is invalid, or a required MC
 | Analyze, index, validate, impact, visualize | `ai-spector-graph` |
 | SRS | `ai-spector-generate-srs` |
 | Basic design | `ai-spector-generate-basic-design` |
-| Detail design | `ai-spector-generate-detail-design` |
 | Prototype | `ai-spector-generate-prototype` |
 | Comments | `ai-spector-resolve-comments` |
 | “Generate docs” (vague) | `ai-spector-generate` |

package/scaffold/cursor/skills/ai-spector/references/cli-failures.md

@@ -1,185 +1,61 @@
-# CLI and tool failures (mandatory agent behavior)
+# CLI failures
 
-When any `ai-spector` command **fails** (non-zero exit, throws, or empty/invalid JSON when `--json` was required), or a **required tool** fails unexpectedly (MCP, terminal, network):
+**Load this file only when a CLI command fails.** Do not pre-load.
 
-1. **Pause** the current step — no templates, no subagents, no writing `docs/srs/**`, no silent fallbacks.
-2. **Report** using the response format below (verbatim CLI/tool output).
-3. **Offer recovery** — always present **fix and retry** (recommended) and, when safe, a **bounded workaround** the agent can execute if the user approves.
-4. **Wait for the user** (or apply [auto-fix without asking](#agent-may-fix-without-asking-small-local) only for trivial local fixes).
-5. After fix or approved workaround, **continue the same task** from the failed step (re-run the same CLI when possible).
+When any `ai-spector` command exits non-zero or returns invalid JSON:
 
-**Default:** fix and retry. **Workarounds** are allowed only with explicit user approval and the guardrails in [Workaround catalog](#workaround-catalog-user-approval-required).
+1. **Pause** — no writing, no silent fallbacks.
+2. **Report** with the format below.
+3. **Offer recovery** — fix + retry (default), or bounded workaround if approved.
+4. **Wait** — then continue the same task from the failed step.
 
----
-
-## Recovery flow
-
-```text
-Tool/CLI fails
-  → pause + report (Blocked format)
-  → propose Option 1 (fix & retry) + Option 2 (workaround, if any) + Option 3 (pause)
-  → user picks (or auto-fix for trivial cases)
-  → execute choice → re-run same CLI at next checkpoint when possible
-```
-
-| User says | Agent does |
-|-----------|------------|
-| **1**, “fix”, “retry”, “yes fix” | Apply fix steps (or ask for one missing input), re-run **the same** failed command/step |
-| **2**, “workaround”, “continue anyway” | Follow [Workaround catalog](#workaround-catalog-user-approval-required); state trade-offs; merge/validate when writing docs |
-| **3**, “pause”, “stop”, no reply yet | Stop; do not generate or bulk-read docs; user re-runs the task later |
-| “you figure it out” / “use your judgment” | Prefer **fix and retry** first; if blocked after one retry, propose the **smallest** approved workaround and ask once |
-
-Do **not** leave the user stuck with only “run `/analyze` again” when you can propose a concrete fix **or** a bounded workaround.
+Auto-fix without asking: typo in seed id, missing parent dir, wrong cwd — fix and retry once.
+Must ask user: deleting graph files, large manual edits, any workaround not listed below.
 
 ---
 
-## Forbidden (unless user explicitly approves a workaround)
-
-| Do not | Why |
-|--------|-----|
-| Hand-edit `traceability.graph.json` at scale | Bypasses merge/validate; drifts from `knowledge.json` |
-| Implement graph BFS/search in the agent | Duplicates `graph query` / `graph impact` |
-| Glob or read all of `docs/srs/**` because query failed | Hides missing graph or bad seed id |
-| Use `.ai-spector/index/*.md` as **primary** context when validate/query failed | Index is fallback only after **successful** CLI with thin graph |
-| Skip `graph merge` and “fill SRS from memory” | Breaks traceability |
-| Silently continue after `graph validate` errors | Generation will be wrong or inconsistent |
-| Tell the user “run this CLI yourself” without offering to run it | Agent owns CLI in this workflow |
-| Continue generation after CLI failure **without** user choosing fix, workaround, or pause | User must not be blocked silently or bypassed silently |
-
-**Allowed after successful CLI:** If `graph query --json` succeeds but `nodes` has no domain entries, say so and suggest **analyze** — still do not bulk-read `docs/srs/**`.
-
----
-
-## Response format (copy this structure)
-
-```markdown
-## Blocked: <task or slash-command> — <CLI | tool> failed
-
-**Command / tool:** `ai-spector <subcommand> …` or `<MCP tool name>`
-**Exit code:** <n> (if applicable)
+## Report format
 
-**Output:**
-\`\`\`
-<paste full stdout/stderr or tool error>
-\`\`\`
-
-**What this means:** <one or two sentences>
-
-**How to fix (recommended):**
-1. <step agent or user can take>
-2. <step>
-3. Re-run the same step: `<exact command>` or **/<slash-command>**
-
-**Workaround (optional):** <only if bounded and useful — e.g. “read these 2 projection paths and draft section X; merge after index recovers”>
-**Trade-off if workaround:** <traceability / staleness risk in plain language>
-
-**What would you like to do?**
-1. **Fix and retry** (recommended) — <one-line summary of fix path>
-2. **Workaround** — <one-line summary; skip only if none applies>
-3. **Pause** — stop here; you fix environment and say “retry” or re-run the task
-
-Reply with **1**, **2**, **3**, or tell me your preference.
 ```
-
-For **optional** steps (e.g. `graph visualize --open`), you may use a shorter **Interrupted** header but still offer fix vs skip.
-
----
-
-## Workaround catalog (user approval required)
-
-Use only when the user chooses **2** or explicitly accepts the trade-off. Prefer the **smallest** scope that unblocks the task; return to CLI as soon as it works.
-
-| Situation | Workaround | Guardrails | Restore traceability |
-|-----------|------------|------------|----------------------|
-| `graph query` fails once (cwd, typo) | Fix cwd/seed id; one retry | No doc writes until query succeeds | Re-run query before write |
-| `graph query` OK but thin `nodes` | Read only `projectionPaths` + cited `docs/data-source/**` | Named paths only; no `docs/srs/**` glob | `graph merge` + `validate` after draft |
-| `graph validate` — one bad id/edge | Patch **single** node/edge; re-validate | No mass graph surgery | `validate` must pass before next wave |
-| `graph merge` — one bad `listedInSection` | Fix id in `knowledge.json`; re-merge | No hand-merge of full graph | Same |
-| `index` fails on one path | Skip that path if command allows; fix path and re-index | Do not skip required wave index without user OK | Re-run **index** for skipped paths |
-| Optional visualize fails | Skip open; continue pipeline | User chose workaround | None |
-| Terminal/env (not git, missing `uv`) | Agent runs install/init steps user approves | No destructive deletes without ask | Re-run failed CLI |
-| Generation blocked only by **upstream** missing SRS | User approves generating prerequisite layer first | Run prerequisite wave with normal merge/validate | Full pipeline order |
-
-After any workaround that wrote docs or graph patches: **`graph validate`** (and **`index`** when the command doc requires) before the next wave.
+## Blocked: <command> failed
+**Command:** `ai-spector <subcommand>`  **Exit:** <n>
+**Output:** <paste stdout/stderr>
+**Means:** <one sentence>
+**Fix:** <steps> then re-run `<same command>`
+**Workaround (if any):** <bounded scope + trade-off>
+
+Reply: 1 Fix & retry  2 Workaround  3 Pause
+```
 
 ---
 
-## Common failures → fixes
-
-### `ai-spector: command not found`
-
-- **Means:** Package not installed or not on PATH.
-- **Fix:** `npm install ai-spector` in the project; agent uses `npx ai-spector …` from project root.
-
-### `Could not find project root` / missing `docflow.config.json`
-
-- **Means:** `init` not run or wrong working directory.
-- **Fix:** Run `npx ai-spector init` from project root; agent `cd`s to workspace root before CLI.
-
-### `ai-spector analyze` fails
-
-- **Means:** Registry/templates or graph bootstrap broke.
-- **Fix:** Show full error; check `.ai-spector/registry/section-registry.json` exists; re-run `init` if config is corrupt; do not proceed to merge.
-
-### `graph merge` — `No domain entries in knowledge.json`
-
-- **Means:** Analyze extract did not populate staging.
-- **Fix:** Re-run `/analyze`; ensure `docs/data-source/` has real markdown files with UC/F/actor content; fill `knowledge.json` with at least one `useCase` or `feature`.
-- **Workaround (user OK):** Manually add minimal entries to `knowledge.json` then re-merge.
-
-### `graph merge` — `Merge edge missing target node` / section id
-
-- **Means:** `listedInSection` points to a section id not in the graph.
-- **Fix:** Use a section id from `section-registry.json` (e.g. `sec.srs.3-use-cases.l3.3.32-list-use-case`) or omit `listedInSection` for defaults; re-run merge.
-
-### `graph validate` — `DOC-SECTION-COVERAGE` on `doc.bd.list-api` / `doc.bd.list-screen` / `doc.bd.db-design`
-
-- **Means:** Basic-design **list chapter** documents exist in the graph without child `section` nodes (common after a projection-only `graph merge` before bootstrap/index).
-- **Fix:** From project root run **`npx ai-spector index`** (or ask to **refresh index**). Ensure `.ai-spector/templates/basic_design/` exists (`npx ai-spector init`). Then re-run **`graph merge`** for your patch and **`graph validate`**.
-
-### `graph validate` — `DOMAIN-ANCHORED` / `SECTION-TREE` / `SCHEMA`
-
-- **Means:** Graph inconsistent with rules.
-- **Fix:** Paste each `[ERROR]` line; prefer re-run **analyze** (merge) over manual JSON surgery; for one bad id, agent may patch **only** that node/edge then re-validate.
-
-### `graph query <id>` — seed missing or empty subgraph
-
-- **Means:** Wrong id, or domain not merged.
-- **Fix:** Run **visualize-graph** or `graph query` with a known id from `knowledge.json`; run **analyze** if no `useCase`/`feature` nodes.
-
-### `graph query` — invalid JSON / parse error
-
-- **Means:** CLI crashed or wrong cwd.
-- **Fix:** Re-run from project root; if repeat, report as tool bug with full stderr.
-
-### `graph impact --git` — not a git repository / no changes
-
-- **Means:** `--git` needs a git working tree with staged or unstaged diffs.
-- **Fix:** Initialize git (`git init`) and make edits, or use **impact** with a short description, editor selection, or `--file` / `--heading` instead of `--git`.
-
-### `graph impact --git` — could not map diff to graph seeds
-
-- **Means:** Changed paths are not linked to `document` / `section` nodes (e.g. only `README.md` or `src/`).
-- **Fix:** Run impact on doc paths under `docs/` or `.ai-spector/`; or **impact** with a short description of the traceability change.
-
-### Stale graph or indexes after manual edits or generate SRS
-
-- **Means:** User changed `docs/data-source/`, SRS outputs, or templates without re-running ingest; graph still shows template-only domain nodes.
-- **Fix:** Run **`ai-spector index`**. For fully stale domain detail, re-run **`/analyze`** → fresh `knowledge.json`.
+## Common fixes
+
+| Error | Fix |
+|---|---|
+| `command not found` | `npm install ai-spector`; use `npx ai-spector` |
+| `Could not find project root` | Run `npx ai-spector init`; check cwd |
+| `analyze` fails | Show full error; check registry exists; re-run init if corrupt |
+| `merge` — no domain entries | Re-run `/analyze`; ensure data-source has UC/F/actor content |
+| `merge` — missing target node | Fix section id from `section-registry.json`; re-merge |
+| `validate` — DOC-SECTION-COVERAGE | Run `ai-spector index` then re-merge and re-validate |
+| `validate` — DOMAIN-ANCHORED / SCHEMA | Re-run analyze; patch only the single bad node/edge |
+| `graph query` — empty subgraph | Wrong id or domain not merged; run analyze first |
+| `graph query` — invalid JSON | Re-run from project root; report as bug if repeats |
+| `index` fails on one path | Fix the path; re-index; do not skip required wave index without user OK |
+| Stale graph after manual edits | `ai-spector index`; re-run `/analyze` for fully stale domain |
 
 ---
 
-## Agent may fix without asking (small, local)
+## Workarounds (user approval required)
 
-- Create missing parent dirs under `.ai-spector/` if `init` was incomplete.
-- Correct a **single** typo in `knowledge.json` id or `listedInSection` then re-run `graph merge`.
-- Re-run the **same** failed command once after an obvious fix (e.g. `cd` to project root).
-- Wrong CLI flags the agent introduced — fix and retry immediately.
+| Situation | Workaround | Restore |
+|---|---|---|
+| `graph query` thin nodes | Read `projectionPaths` + cited data-source files only (no `docs/srs/**` glob) | `graph merge` + validate after draft |
+| `validate` — one bad id/edge | Patch single node/edge; re-validate | Must pass before next wave |
+| `index` fails one path | Skip that path if allowed; re-index after fix | Re-run index |
+| Upstream SRS missing | Generate SRS prerequisite first (user approves) | Full pipeline order |
 
-## Agent must ask user before
+After any workaround that wrote docs: `graph validate` (+ `index` if required) before next wave.
 
-- Deleting `traceability.graph.json` or re-running `init --force`.
-- Large manual edits to graph or generated SRS.
-- Changing bundled templates or `workflow.dependencies.json`.
-- Any [workaround](#workaround-catalog-user-approval-required) not listed above or that skips **validate** before the next generation wave.
-- Bulk reads under `docs/srs/**` or `docs/basic-design/**` as primary context.
+**Forbidden without user approval:** hand-edit graph at scale · glob `docs/srs/**` as primary context · skip `graph merge` · continue generation after validate errors.

package/scaffold/cursor/skills/ai-spector/references/context-management.md

@@ -0,0 +1,157 @@
+# Context management during generation
+
+Long generation runs (full SRS, full basic design) accumulate raw graph JSON, template content, data-source files, and previous wave outputs in the context window. Past a certain size, this degrades accuracy — the model starts blending data from earlier targets into the current one.
+
+Two tools prevent this: **compaction checkpoints** and **sub-agent delegation**.
+
+---
+
+## Rule 1 — Compact at wave boundaries (mandatory)
+
+After every wave completes (merge + validate pass), compact the context **before starting the next wave**:
+
+```
+/compact
+```
+
+What to retain across the compaction (summarise into the compact prompt if the tool asks):
+- The generation plan: wave table, remaining targets, current wave number
+- Completed outputs: list of written file paths + validate OK (not their content)
+- Language setting and theme (if prototype)
+- Any open blockers or deferred items
+
+What to discard (do not try to retain):
+- Raw graph query JSON from completed targets
+- File content of already-written docs
+- Template content (re-read from `.ai-spector/templates/` when needed)
+- Data-source file content read in earlier waves
+
+**Trigger compact also when:**
+- Writing more than 5 per-domain files in a single wave (compact after every 5th file)
+- Switching document types mid-wave (e.g., UC files → feature files)
+- Context feels noisy — re-reads of the same data, earlier target data bleeding in
+
+---
+
+## Rule 2 — Sub-agent for graph context gathering
+
+Do **not** run graph queries + file reads + synthesis all inline in the main agent turn. This fills the context with raw data that is only useful for 30 seconds.
+
+Instead, delegate context gathering to a sub-task and receive only the distilled result.
+
+### Sub-agent pattern
+
+**Delegate:** "Gather context for `<target>`"
+
+**Prompt to sub-agent (adapt per target type):**
+
+```
+Query the graph and read relevant files for <target id / type>.
+Return ONLY a structured summary — do not return raw JSON or full file content.
+
+Required output shape:
+- Target: <id>, <name>
+- Actors: list of actor names and roles
+- Flow steps: numbered main flow (max 10 steps); exception flows (list conditions only)
+- Data fields: input fields (name, type, required, validation); output fields (name, type)
+- Related nodes: UC/F/API/screen ids that this target depends on or satisfies
+- Gaps: any required graph node that is missing or empty
+
+Queries to run:
+  ai-spector graph query <seedId> --direction both --depth 4 --edges CONTEXT --json
+  ai-spector graph query <depId> --direction both --depth 2 --edges DEPS --json
+  [read projectionPaths files listed in query result]
+
+Max summary length: 400 words. No raw JSON in the response.
+```
+
+**Main agent receives:** The 400-word summary — not the raw query output.
+
+**Main agent writes:** The document file using the summary + template.
+
+### When to use sub-agents
+
+| Task | Use sub-agent? |
+|---|---|
+| Graph query + extraction for a single UC/F/screen | **Yes** |
+| Reading multiple data-source files to find relevant domain info | **Yes** |
+| Impact analysis before regenerating a file | **Yes** |
+| Checking whether a UC node exists | No — simple CLI call inline |
+| Writing the file itself | No — main agent writes |
+| Running `graph validate` / `graph merge` | No — CLI inline |
+
+---
+
+## Rule 3 — Read discipline (no speculative reads)
+
+Only read a file if the graph query result references it in `projectionPaths` or the DAG explicitly lists it as a dependency. Never read:
+
+- `docs/**` as a glob
+- The entire `docs/data-source/` directory upfront
+- Previously generated docs "for context" unless they are a direct DAG dependency of the current target
+
+After a file is read and its relevant data extracted, treat it as consumed. Do not re-read it for a later target unless that target also has it in `projectionPaths`.
+
+---
+
+## Rule 4 — Context budget per target
+
+Before writing each target, the context should hold **only**:
+
+| Item | Max size |
+|---|---|
+| Generation plan (wave table, remaining targets) | ~200 tokens |
+| Extracted context for current target (from sub-agent or compact summary) | ~400 tokens |
+| Template structure (section headings only, not full template) | ~200 tokens |
+| Language setting | 1 line |
+| Current target output (while writing) | as needed |
+
+If the active context clearly exceeds this (raw JSON visible, previous target data visible, multiple template files loaded), compact before writing.
+
+---
+
+## Rule 5 — After writing, let it go
+
+Once a file is written and `rendersTo` is logged for the wave-end merge:
+- Do not re-read the file
+- Do not summarise its content into memory
+- Record only: path + validate status
+
+The graph is the persistent record. The context window is scratch space per target.
+
+---
+
+## Compaction prompt template
+
+When compacting mid-run, include this summary so the next turn has enough to continue:
+
+```
+Continuing generation of <layer> (e.g., SRS / basic design).
+
+Plan:
+- Wave <N> of <total> — COMPLETED
+- Wave <N+1> targets: <list of DAG ids and output paths>
+- Remaining waves: <list>
+
+Completed files:
+<path> — validate OK
+<path> — validate OK
+
+Settings:
+- Language: <language>
+- Graph validated: YES
+
+Resume at: wave <N+1>, target <first target id>.
+```
+
+---
+
+## Summary
+
+| Checkpoint | Action |
+|---|---|
+| End of every wave | `/compact` with plan summary |
+| Every 5 per-domain files | `/compact` with plan summary |
+| Before each target | Delegate graph query + extraction to sub-agent |
+| After reading data-source files | Extract what's needed; discard the raw read |
+| After writing a file | Record path + status only; discard file content |

package/scaffold/cursor/skills/ai-spector/references/generate-graph.md

@@ -1,6 +1,6 @@
 # Graph-first generation (shared)
 
-Used by **SRS**, **basic design**, and **detail design** generation skills.
+Used by **SRS** and **basic design** generation skills.
 
 | Orchestration (scope, confirm, wave checklist, finish) | [generate-workflow.md](./generate-workflow.md) |
 | Per-command DAG + intent tables | each skill's `references/runbook.md` |
@@ -71,9 +71,14 @@ ai-spector graph impact <targetSeedId> --change content_change --json
 ### D. Write
 
 - Read template from `.ai-spector/templates/` (DAG `template` field). If missing → stop and ask user to run `npx ai-spector init`.
+- **Before filling the template**, load the matching context section for this doc type:
+  - SRS targets → `srs-context/<section>.md` (see SRS runbook for the table)
+  - Basic design targets → `bd-context/<doc-type>.md` (see BD runbook for the table)
+  - Prototype screens → [prototype-graph-context.md](../../ai-spector-generate-prototype/references/prototype-graph-context.md)
 - Fill for this target only; keep all required headings; replace placeholders with graph-backed content.
 - Cross-check every UC/F reference against `nodes` from query JSON.
 - Add section anchors `<!-- section:sec.... -->` where templates expect them.
+- **Never invent** field names, endpoint paths, table names, actor roles, or business rules not present in the query results.
 
 ### E. Ingest (once per wave — not per file)