ai-spector 0.4.2 → 0.4.3

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/api-detail.md

@@ -0,0 +1,27 @@
+# Graph → API Detail (per endpoint)
+
+Queries:
+```bash
+ai-spector graph query <F-xx> --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <UC-xx> --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query <entityId> --direction both --depth 2 --edges CONTEXT --json
+```
+
+| Template section | Graph source |
+|---|---|
+| **Summary / Operation ID** | UC `name`; camelCase from method + entity |
+| **Source Requirement** | F-xx id + name; UC-xx id + name |
+| **Auth** | Actor `authRequired`; UC precondition `authenticated` |
+| **Path params** | Entity field `pk: true`; UC flow step passing an id |
+| **Query params** | UC filter/search flow steps; F-xx filter requirements |
+| **Request body** | F-xx `inputData` → name, type, required, validation; UC `mainFlow` input steps |
+| **Response 2xx** | F-xx `outputData` + entity `fields` for returned object |
+| **Response 400** | F-xx `errorHandling` validation; entity field constraints |
+| **Response 401/403** | Actor auth; UC precondition violations |
+| **Response 404** | UC exception "resource not found" |
+| **Response 409** | UC exception "already exists" / "conflict" |
+| **§2 Data Model** | Entity `fields`; `relatesTo` edges for nested objects |
+| **§3 Error Codes** | All UC exception flows + F-xx error handling → HTTP codes |
+| **§4 Rate Limiting** | NFR nodes tagged `rateLimit` or `performance` |
+
+**Rule:** Every request field → F-xx `inputData` or UC flow input. Every response field → entity `fields` or F-xx `outputData`. No invented fields.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/api-list.md

@@ -0,0 +1,26 @@
+# Graph → API List
+
+Queries:
+```bash
+ai-spector graph query doc.bd.list-api --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query doc.srs.6-external-interfaces --direction both --depth 2 --edges DEPS --json
+```
+
+Derive each endpoint — **no invented endpoints**:
+
+| Endpoint rule | Graph evidence required |
+|---|---|
+| GET list | `dataEntity` + UC with list/search flow |
+| GET detail | `dataEntity` + UC with single-record read |
+| POST create | `dataEntity` + UC with create/submit flow |
+| PUT/PATCH update | `dataEntity` + UC with edit flow |
+| DELETE | `dataEntity` + UC with delete/archive flow |
+| Auth (login/logout) | Actor node + auth UC |
+
+| Column | Graph source |
+|---|---|
+| **Method** | Action type: GET/POST/PUT/DELETE |
+| **Path** | Entity name + UC slug; plural snake_case collections |
+| **Summary** | UC `name` or F-xx `name` |
+| **Auth required** | Actor `authRequired`; UC precondition `authenticated` |
+| **Source F-xx / UC-xx** | F-xx and UC-xx nodes that `satisfies` this endpoint |

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/db-design.md

@@ -0,0 +1,22 @@
+# Graph → DB Design
+
+Queries:
+```bash
+ai-spector graph query doc.bd.db-design --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <entityId> --direction both --depth 3 --edges CONTEXT --json  # per entity
+ai-spector graph query doc.srs.5-data-requirements --direction both --depth 2 --edges DEPS --json
+```
+
+| Template section | Graph source |
+|---|---|
+| **§1 DBMS** | NFR nodes tagged `infrastructure` or `database`; data-source mentions |
+| **§2 ERD entities** | All `dataEntity` nodes → table names (snake_case) |
+| **§2 ERD relationships** | `relatesTo` / `dependsOn` edges between entities → cardinality from edge `label` |
+| **§3 Table list** | All `dataEntity` nodes → `description` |
+| **§4 Fields** | Entity `fields` array → name, type, required, constraints, default |
+| **§4 Primary key** | Field with `pk: true` or id convention |
+| **§4 Foreign keys** | `relatesTo` / `dependsOn` edges → FK = `<target>_id` unless node specifies |
+| **§4 Indexes** | Entity `indexes` array; NFR performance constraints on this entity |
+| **§4 Constraints** | Field `validationRules` + NFR constraint nodes |
+
+**Rule:** Every table → `dataEntity` node. Every FK → edge. No tables without graph backing.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/screen-detail.md

@@ -0,0 +1,26 @@
+# Graph → Screen Detail (per screen)
+
+Queries:
+```bash
+ai-spector graph query doc.bd.screen-<slug> --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <UC-xx> --direction both --depth 4 --edges CONTEXT --json
+ai-spector graph query <F-xx> --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query <api-node> --direction both --depth 2 --edges DEPS --json
+```
+
+| Template section | Graph source |
+|---|---|
+| **Purpose / User Role** | UC `name` + description; actor node name(s) |
+| **§1.1 Wireframe components** | UC `mainFlow` actor actions → form/button/list; UC `postconditions` → success state |
+| **§1.2 Layout** | Input steps → form; output steps → display/table; nav steps → breadcrumb/back |
+| **§1.3 Form fields** | API request body (F-xx `inputData`) → one input per field |
+| **§1.3 Table columns** | API response body (entity `fields`) → one column per field |
+| **§1.3 Buttons** | UC `mainFlow` action verbs → button labels |
+| **§1.4 Primary actions** | UC `mainFlow` actor steps |
+| **§1.4 Navigation** | UC `postconditions` target; `list-screens.md` §2 flow |
+| **§1.5 Field validation** | F-xx `inputData.validationRules`; entity field constraints |
+| **§1.5 Defaults** | F-xx `inputData.defaultValue`; entity field `default` |
+| **Error / empty states** | UC `exceptionFlows` → one state per exception; API 404 → empty; API 400 → inline |
+| **Role sections** | Multiple actors → mark each section with actor role |
+
+**Rule:** Every form field → API request or F-xx `inputData`. Every column → API response or entity field. Every button label → UC flow verb. No invented content.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/references/bd-context/screen-list.md

@@ -0,0 +1,27 @@
+# Graph → Screen List
+
+Queries:
+```bash
+ai-spector graph query doc.bd.list-screen --direction both --depth 3 --edges CONTEXT --json
+ai-spector graph query doc.srs.3-use-cases --direction both --depth 2 --edges DEPS --json
+```
+
+Derive each screen — **no invented screens**:
+
+| Screen rule | Graph evidence |
+|---|---|
+| One screen per UC with actor-facing interaction steps | UC `mainFlow` with actor actions |
+| List/dashboard per browsable entity | `dataEntity` + UC with list/search flow |
+| Detail/form per creatable or editable entity | `dataEntity` + UC with create/edit flow |
+| Auth screens | Actor node + login/auth UC |
+| Role variants | Multiple actors on same UC → separate screens or role tabs |
+
+| Column | Graph source |
+|---|---|
+| **Screen ID** | S-xx sequentially |
+| **Screen Name** | UC name or entity name + action |
+| **Purpose** | UC one-line description |
+| **User Role** | Actor node(s) satisfying this UC |
+| **Related F-xx / UC-xx** | UC and F-xx nodes this screen satisfies |
+
+**§2 Navigation Flow:** UC `postconditions` → target screen after action completes.

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

@@ -8,6 +8,7 @@ Generate basic design markdown **from the traceability graph** and upstream SRS.
 |-----------------|----------|
 | Scope cases, waves, merge, finish, guardrails | [generate-workflow.md](../../ai-spector/references/generate-workflow.md) |
 | Graph query, ingest, perEndpoint/perScreen | [generate-graph.md](../../ai-spector/references/generate-graph.md) |
+| **Graph → template section mapping** | **[bd-context/](./bd-context/) — load the matching section file before writing each doc type** |
 
 **Upstream:** SRS on disk (minimum per `workflow.dependencies.json`). Do not invent APIs/screens not grounded in graph + SRS.
 
@@ -43,6 +44,20 @@ Templates: `.ai-spector/templates/basic_design/`
 
 **Reindex every wave (mandatory):** `graph merge` does not parse markdown bodies. Without index after wave 0, wave 1 cannot expand endpoint rows; without index after wave 1, wave 2 cannot expand Screen Index rows.
 
+## Graph context (required before writing each file)
+
+After running queries ([generate-graph.md](../../ai-spector/references/generate-graph.md) § C), load the matching file from `bd-context/` for the doc type being written:
+
+| Writing | Load |
+|---|---|
+| DB design | `bd-context/db-design.md` |
+| API list | `bd-context/api-list.md` |
+| API detail (per endpoint) | `bd-context/api-detail.md` |
+| Screen list | `bd-context/screen-list.md` |
+| Screen detail (per screen) | `bd-context/screen-detail.md` |
+
+Every endpoint, table, and screen must trace to graph nodes. No invented structure.
+
 ## Basic-design-specific write rules
 
 - **List chapters first** — names from `api-list.md` / `list-screens.md` tables; not one file per `F-xx`.

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

@@ -10,24 +10,22 @@ paths:
   - ".ai-spector/templates/detail_design/**"
 ---
 
-# AI Spector — Generate detail design
-
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
-
-## Required reading
+# Generate Detail Design
 
+## Load at start
 1. [references/runbook.md](references/runbook.md)
 2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md)
-3. [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md)
 
-## Checklist
+## Load when needed
 
-```
-- [ ] language confirmed (language-picker.md — check before first write)
-- [ ] graph validate; SRS + basic design present
-- [ ] generate-workflow waves + merge per target
-```
+| Situation | Load |
+|---|---|
+| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
+| Graph queries / merge | [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) |
+| CLI fails | [../ai-spector/references/cli-failures.md](../ai-spector/references/cli-failures.md) |
+| Run of 5+ files | [../ai-spector/references/context-management.md](../ai-spector/references/context-management.md) |
 
-## Natural language
+## On CLI failure
+Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
 
-“detail design”, “implementation spec”, “feature detail for F-03” → this skill.
+"detail design", "implementation spec", "feature detail for F-03" → this skill.

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

@@ -10,33 +10,24 @@ paths:
   - "prototype/**"
 ---
 
-# AI Spector — Generate prototype
+# Generate Prototype
 
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
+## Load at start
+1. [references/runbook.md](references/runbook.md)
 
-## Required reading
+## Load when needed
 
-- [references/runbook.md](references/runbook.md) — manifest, HTML rules, theme resolution
-- [references/auth-picker.md](references/auth-picker.md) — **when no basic auth stored**: ask username/password, create htpasswd
-- [references/theme-picker.md](references/theme-picker.md) — **when no theme stored**: recommend 3, preview, confirm
+| Situation | Load |
+|---|---|
+| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
+| No theme stored | [references/theme-picker.md](references/theme-picker.md) |
+| No basic auth stored | [references/auth-picker.md](references/auth-picker.md) |
+| Before writing each screen HTML | [references/prototype-graph-context.md](references/prototype-graph-context.md) |
+| Run of 5+ screens | [../ai-spector/references/context-management.md](../ai-spector/references/context-management.md) |
+| CLI fails | [../ai-spector/references/cli-failures.md](../ai-spector/references/cli-failures.md) |
 
-## Checklist
+## On CLI failure
+Pause. Report full output. Offer fix + retry. Details in cli-failures.md.
 
-```
-- [ ] language confirmed (language-picker.md — check before writing any screen text content)
-- [ ] list-screens + screen detail docs exist
-- [ ] basic auth resolved (config basicAuth + prototype/htpasswd → **auth picker if none**)
-- [ ] theme resolved (request → theme.json → manifest → config → **theme picker if none**)
-- [ ] if picker: 3 recommendations + previews opened + user confirmed before setup
-- [ ] prototype setup (with --theme when needed; persists when user named a theme)
-- [ ] one .html per screen; prototypeStem from manifest
-- [ ] prototype manifest && prototype validate --strict
-```
-
-## Natural language
-
-“HTML prototype”, “mockup screens”, “prototype with stripe theme” → this skill.
-
-“Help me pick a theme”, “what theme fits my app?”, “show me theme options” → [theme-picker.md](references/theme-picker.md) (even before generating).
-
-Constraints: `prototype/CLAUDE.md` in the project repo.
+"HTML prototype", "mockup screens", "prototype with stripe theme" → this skill.
+"Help me pick a theme" → load theme-picker.md directly.

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

@@ -0,0 +1,115 @@
+# Graph context for prototype generation
+
+Run these queries **before writing each screen's HTML**. The graph holds the authoritative spec — screen detail docs often summarize it; the graph has the full picture.
+
+Skip this document only when the graph has zero nodes for the screen (brand-new project with no graph yet). In that case, note the gap and generate from screen detail doc alone.
+
+---
+
+## Step 1 — Screen node + neighborhood
+
+```bash
+ai-spector graph query doc.bd.screen-<slug> --direction both --depth 4 --edges CONTEXT --json
+```
+
+What to extract from the result:
+
+| Field / edge | Use in HTML |
+|---|---|
+| `satisfies` → F-xx nodes | Business rules, field constraints, success/error states |
+| `satisfies` → UC-xx nodes | Actor roles, preconditions, flow steps, postconditions |
+| `dependsOn` → `doc.bd.api-*` nodes | Form fields, request params, response columns |
+| `contains` → section nodes | Section headings and subsections already defined |
+| `tracesTo` → SRS nodes | NFR constraints (e.g. required, max length, format) |
+
+If `doc.bd.screen-<slug>` is not found in the graph, try `screen-<slug>` or the screenId from `list-screens.md`.
+
+---
+
+## Step 2 — Feature detail (per linked F-xx)
+
+For each F-xx found in Step 1 `satisfies` edges:
+
+```bash
+ai-spector graph query F-<n> --direction both --depth 3 --edges CONTEXT --json
+```
+
+Extract:
+- **Functional requirements** listed under the feature → must-have UI behaviours
+- **Field definitions** (`rendersTo` → detail design docs if present)
+- **Business rules** (validation, conditional visibility, permissions)
+- **Actor** that performs / views this feature → drives role-based UI variants
+
+---
+
+## Step 3 — Use-case detail (per linked UC-xx)
+
+For each UC-xx found in Step 1 `satisfies` edges:
+
+```bash
+ai-spector graph query UC-<n> --direction both --depth 3 --edges CONTEXT --json
+```
+
+Extract:
+- **Primary actor** → who the screen is for; if multiple actors, plan role tabs or conditional sections
+- **Preconditions** → what state must be shown before the main action (e.g. "must be logged in" → redirect guard state)
+- **Main flow steps** → maps directly to the interactive sequence in the HTML (form → submit → result)
+- **Alternative / exception flows** → error states and empty states to include
+
+---
+
+## Step 4 — API endpoint detail (per linked API)
+
+For each `doc.bd.api-*` node found in Step 1 `dependsOn` edges:
+
+```bash
+ai-spector graph query doc.bd.api-<slug> --direction both --depth 2 --edges DEPS --json
+```
+
+Extract:
+- **Request body fields** → form inputs (name, type, required/optional, format hints)
+- **Response body fields** → table columns, card properties, display labels
+- **HTTP method + path** → drives the form `action` hint and confirmation copy
+- **Error codes** → error message copy and UI states (404 → empty state, 400 → inline validation, 401 → redirect)
+
+---
+
+## Step 5 — Actor / permission check
+
+If the screen serves multiple actors (e.g. Admin + End User):
+
+```bash
+ai-spector graph query <actorId> --direction both --depth 2 --edges CONTEXT --json
+```
+
+Use actor data to:
+- Render role-specific sections (admin actions gated behind a permission check visual)
+- Show the correct navigation items for each role
+- Label buttons and headings with the actor's natural language (not just "user")
+
+---
+
+## Synthesis — before writing the HTML
+
+Compile answers to these questions from the query results. Do **not** invent answers not grounded in graph data — leave a `<!-- TODO: not in spec -->` comment instead.
+
+| Question | Source |
+|---|---|
+| What fields does the form have? | API request body (Step 4) |
+| What columns / data does the list/detail show? | API response body (Step 4) |
+| What validation rules apply? | F-xx business rules (Step 2) |
+| What error states must exist? | UC exception flows (Step 3) + API error codes (Step 4) |
+| What empty state must exist? | UC preconditions + API 404 handling |
+| Which actors see what? | Actor roles (Step 3 + 5) |
+| What is the navigation target after the main action? | UC postconditions + `list-screens.md` §2 flow |
+| Any NFR constraints (length limits, formats)? | SRS `tracesTo` nodes (Step 1) |
+
+---
+
+## Accuracy rules
+
+1. **Every form field must trace to** an API request field, an F-xx field definition, or a UC data requirement. Remove any field that has no graph backing.
+2. **Every table column must trace to** an API response field or a data entity property. No invented columns.
+3. **Every button / action must trace to** a UC main flow step or F-xx functional requirement. Label it with the spec's language, not generic copy ("Save" is fine only if the spec says save; use the spec's verb if it differs).
+4. **Error and empty states are mandatory** when the UC has exception flows or the API returns error codes. A screen with only the happy-path is incomplete.
+5. **Role-based sections are mandatory** when more than one actor satisfies the screen. Use a visual separator or tab — do not silently drop one actor's view.

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

@@ -4,6 +4,13 @@ Generate **static HTML** prototypes from basic-design screen specs. All setup an
 
 **User runs this command;** the agent runs CLI. On CLI failure: [cli-failures.md](../../ai-spector/references/cli-failures.md).
 
+## Context hygiene
+
+For runs of 5+ screens, follow [context-management.md](../../ai-spector/references/context-management.md):
+- **Sub-agent per screen** — delegate graph queries + screen doc reads for each screen; receive a ≤400-word summary (fields, flows, roles, errors); main agent writes from the summary.
+- **Compact every 5 screens** — after writing and validating a batch of 5, `/compact` with the plan summary (remaining screens, written paths) before continuing.
+- After writing a screen HTML file, discard its content from context — record only the path.
+
 ## Philosophy
 
 - **Screen design is source of truth** — `docs/basic-design/list-screens.md` + `docs/basic-design/screens/<slug>.md`
@@ -87,11 +94,25 @@ ai-spector prototype manifest --dry-run
 
 Read each target’s `docs/basic-design/screens/<slug>.md` — wireframe (§1.1), layout (§1.2), interactions. Read `prototype/DESIGN.md` for colors, type, spacing.
 
+### 2b. Load graph context per screen
+
+**Required before writing each screen’s HTML.** Run the queries in [prototype-graph-context.md](./prototype-graph-context.md) for the screen being generated.
+
+This step pulls:
+- The F-xx / UC-xx the screen satisfies → business rules, required fields, flow steps, error states
+- The API endpoints the screen depends on → exact form fields, response columns, error codes
+- Actor roles → role-based UI sections
+
+Do not skip this step. Screen detail docs summarize the spec; the graph has the authoritative detail. Any form field, table column, button, or error state **must be traceable to graph data** before you write it into the HTML.
+
 ### 3. Generate HTML
 
 For each screen in scope:
 
 - Write `prototype/src/<prototypeStem>.html` (self-contained or with sibling `.css`/`.js` in `prototype/src/`)
+- All content derived from graph context (step 2b) + screen detail doc — no invented fields or labels
+- Include error states and empty states for every exception flow found in the graph
+- Render role-specific sections when multiple actors satisfy the screen
 - Link navigation using relative paths between screens when `list-screens.md` §2 defines flow
 - Do **not** edit `docs/**`
 
@@ -125,6 +146,12 @@ git commit -m "chore(prototype): add HTML screens (<theme>)"
 - [ ] If no stored basic auth: [auth picker](auth-picker.md) run — username/password collected, `prototype auth` executed, `prototype/htpasswd` present
 - [ ] If no stored theme: [theme picker](theme-picker.md) run — 3 recommendations, previews opened, user confirmed
 - [ ] `prototype setup` run with resolved theme
+- [ ] Graph context queries run per screen ([prototype-graph-context.md](./prototype-graph-context.md)) before writing HTML
+- [ ] Every form field traces to an API request field or F-xx/UC-xx field definition
+- [ ] Every table column traces to an API response field or data entity
+- [ ] Every button/action label matches the spec's verb (not generic copy)
+- [ ] Error states and empty states included for all UC exception flows + API error codes
+- [ ] Role-based sections rendered when multiple actors satisfy the screen
 - [ ] Every generated file name matches `prototypeStem` in manifest
 - [ ] Wireframe/layout from screen detail doc reflected in HTML
 - [ ] Tokens from `prototype/DESIGN.md` only (no random CDN)

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

@@ -10,27 +10,29 @@ paths:
   - ".ai-spector/templates/srs/**"
 ---
 
-# AI Spector — Generate SRS
-
-**Core:** [../ai-spector/SKILL.md](../ai-spector/SKILL.md)
-
-## Required reading
-
-1. [references/runbook.md](references/runbook.md) — SRS-specific DAG, waves, finish
-2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md) — scope, confirm, per-wave checklist
-3. [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) — query, merge, ingest
-
-## Checklist
-
-```
-- [ ] language confirmed (language-picker.md — check before first write)
-- [ ] graph validate
-- [ ] runbook + generate-workflow followed
-- [ ] templates from .ai-spector/templates/srs/
-- [ ] merge + validate each wave
-- [ ] ai-spector index when runbook says so
-```
-
-## Natural language
-
-“generate SRS”, “write requirements”, “use case chapter”, “feature list” → this skill.
+# Generate SRS
+
+## Load at start
+1. [references/runbook.md](references/runbook.md)
+2. [../ai-spector/references/generate-workflow.md](../ai-spector/references/generate-workflow.md)
+
+## Load when needed
+
+| Situation | Load |
+|---|---|
+| Language not set | [../ai-spector/references/language-picker.md](../ai-spector/references/language-picker.md) |
+| Writing §1 Introduction | [references/srs-context/introduction.md](references/srs-context/introduction.md) |
+| Writing §2 Overall Description | [references/srs-context/overall-description.md](references/srs-context/overall-description.md) |
+| Writing §3 UC list or UC-xx detail | [references/srs-context/use-case-detail.md](references/srs-context/use-case-detail.md) |
+| Writing §4 feature list or F-xx detail | [references/srs-context/feature-detail.md](references/srs-context/feature-detail.md) |
+| Writing §5 Data Requirements | [references/srs-context/data-requirements.md](references/srs-context/data-requirements.md) |
+| Writing §6 External Interfaces | [references/srs-context/external-interfaces.md](references/srs-context/external-interfaces.md) |
+| Writing §7 Quality Attributes | [references/srs-context/quality-attributes.md](references/srs-context/quality-attributes.md) |
+| Graph queries / merge | [../ai-spector/references/generate-graph.md](../ai-spector/references/generate-graph.md) |
+| CLI fails | [../ai-spector/references/cli-failures.md](../ai-spector/references/cli-failures.md) |
+| Run of 5+ files | [../ai-spector/references/context-management.md](../ai-spector/references/context-management.md) |
+
+## 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.

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

@@ -8,6 +8,7 @@ Generate SRS markdown **from the traceability graph** in DAG order.
 |-----------------|----------|
 | Scope cases, waves, merge, finish, guardrails | [generate-workflow.md](../../ai-spector/references/generate-workflow.md) |
 | Graph query, ingest patch, parallelism | [generate-graph.md](../../ai-spector/references/generate-graph.md) |
+| **Graph → template section mapping** | **[srs-context/](./srs-context/) — load the matching section file before writing each doc type** |
 
 ## Intent → DAG hints
 
@@ -46,6 +47,22 @@ Templates: `.ai-spector/templates/srs/`
 
 Follow [generate-workflow.md](../../ai-spector/references/generate-workflow.md) for planning and per-wave execution.
 
+## Graph context (required before writing each file)
+
+After running queries ([generate-graph.md](../../ai-spector/references/generate-graph.md) § C), load the matching file from `srs-context/` for the doc type being written:
+
+| Writing | Load |
+|---|---|
+| §1 Introduction | `srs-context/introduction.md` |
+| §2 Overall Description | `srs-context/overall-description.md` |
+| §3 UC list or UC-xx detail | `srs-context/use-case-detail.md` |
+| §4 feature list or F-xx detail | `srs-context/feature-detail.md` |
+| §5 Data Requirements | `srs-context/data-requirements.md` |
+| §6 External Interfaces | `srs-context/external-interfaces.md` |
+| §7 Quality Attributes | `srs-context/quality-attributes.md` |
+
+Every UC-xx, F-xx, and actor in output must exist as a graph node. No invented identifiers.
+
 ## SRS-specific ingest notes
 
 - List chapters need `rendersTo` from template `doc.srs.*` nodes.

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/data-requirements.md

@@ -0,0 +1,10 @@
+# Graph → §5 Data Requirements
+
+Query: `doc.srs.5-data-requirements` DEPS depth 2, then each `dataEntity` node CONTEXT depth 3.
+
+| Template section | Graph source |
+|---|---|
+| **Entity list** | All `dataEntity` nodes → name, description, linked F-xx via `satisfies` / `partOf` |
+| **Entity fields** | `dataEntity.fields` array → name, type, required, constraints |
+| **Relationships** | `relatesTo` / `dependsOn` edges between entities → cardinality from edge properties |
+| **Retention rules** | Entity `retention` property or NFR nodes referencing entities |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/external-interfaces.md

@@ -0,0 +1,10 @@
+# Graph → §6 External Interfaces
+
+Query: `doc.srs.6-external-interfaces` DEPS depth 2, then each `api` / `externalSystem` node.
+
+| Template section | Graph source |
+|---|---|
+| **6.1 User Interfaces** | Screen nodes → names, purposes; actor nodes → which screens they use |
+| **6.2 Software Interfaces** | API / `externalSystem` nodes → name, protocol, purpose; `dependsOn` from F-xx |
+| **6.3 Hardware Interfaces** | NFR nodes tagged `hardware` |
+| **6.4 Communication Interfaces** | Protocol / integration nodes; NFR nodes tagged `communication` |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/feature-detail.md

@@ -0,0 +1,20 @@
+# Graph → §4 Feature detail (per F-xx)
+
+Query: `F-xx` CONTEXT depth 4.
+
+| Template section | Graph source |
+|---|---|
+| **Name / Priority / Description** | F-xx node `name`, `priority`, `description` |
+| **User Story** | F-xx `userStory`; or derive from actor + description |
+| **In / Out of Scope** | F-xx `scope.in`, `scope.out` arrays |
+| **Related Use Cases** | UC nodes via `satisfies` inbound → UC-xx ids and names |
+| **§2 Stimulus/Response** | UC `mainFlow` steps for linked UCs; actor name from actor node |
+| **§2 Error Handling** | UC `exceptionFlows` + F-xx `errorHandling` array |
+| **§3 Functional Requirements** | F-xx `requirements` → FR-xx-nn ids, descriptions, priority, acceptance criteria |
+| **§3 Input Data** | F-xx `inputData` or entity nodes via `dependsOn` |
+| **§3 Output Data** | F-xx `outputData` or entity response fields |
+| **§3 UI — Screens** | Screen nodes linked via `satisfies` |
+| **§3 Dependencies** | `dependsOn` edges → other F-xx or external system nodes |
+| **§3 Assumptions** | F-xx `assumptions` array |
+
+For the **§4 list chapter**: query `doc.srs.4-system-features-list` CONTEXT depth 2 → extract all `feature` nodes sorted by id; include linked UC ids.

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/introduction.md

@@ -0,0 +1,12 @@
+# Graph → §1 Introduction
+
+Query: `doc.srs.1-introduction` CONTEXT depth 2 + system root node.
+
+| Template section | Graph source |
+|---|---|
+| **1.1 Product Name** | System node `name` |
+| **1.1 Intended Audience** | All `actor` nodes → roles |
+| **1.3 Major Features** | All `feature` nodes → F-xx names (graph only, no invented) |
+| **1.3 Scope / Purpose** | System node `description` or data-source summary |
+| **1.3 Out of Scope** | Nodes marked `outOfScope: true`; explicit exclusions in data-source |
+| **1.4 References** | `rendersTo` / `definedIn` edges → data-source files |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/overall-description.md

@@ -0,0 +1,11 @@
+# Graph → §2 Overall Description
+
+Query: `doc.srs.2-overall-description` CONTEXT depth 3.
+
+| Template section | Graph source |
+|---|---|
+| **Product perspective** | System node; `relatesTo` external systems |
+| **User classes / actors** | All `actor` nodes → name, role, permissions |
+| **Operating environment** | NFR nodes tagged `environment` or `infrastructure` |
+| **Constraints** | NFR nodes tagged `constraint` |
+| **Assumptions** | Nodes or edges tagged `assumption` |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/quality-attributes.md

@@ -0,0 +1,11 @@
+# Graph → §7 Quality Attributes / NFR
+
+Query: `ai-spector graph query nfr --direction both --depth 2 --json` (or NFR bundle node).
+
+| Template section | Graph source |
+|---|---|
+| **Performance** | NFR `category: performance` → thresholds, response time, throughput |
+| **Security** | NFR `category: security` |
+| **Reliability / Availability** | NFR `category: reliability` or `availability` |
+| **Scalability** | NFR `category: scalability` |
+| **Maintainability** | NFR `category: maintainability` |

package/scaffold/cursor/skills/ai-spector-generate-srs/references/srs-context/use-case-detail.md

@@ -0,0 +1,26 @@
+# Graph → §3 Use Case detail (per UC-xx)
+
+Query: `UC-xx` CONTEXT depth 4.
+
+| Template section | Graph source |
+|---|---|
+| **Name / Description** | UC node `name`, `description` |
+| **Primary Actor** | Actor linked via `satisfies` or `partOf` inbound |
+| **Secondary Actors** | Additional actor nodes in neighbourhood |
+| **Priority** | UC node `priority` |
+| **Preconditions** | UC `preconditions` array; or `dependsOn` UCs that must complete first |
+| **Postconditions** | UC `postconditions` array |
+| **Trigger** | UC `trigger` property |
+| **§2 Main Flow** | UC `mainFlow` steps → one numbered row per step |
+| **§3 Alternative Flows** | UC `alternativeFlows` → one subsection per entry |
+| **§4 Exception Flows** | UC `exceptionFlows` / `errorFlows` + F-xx `errorHandling` for linked features |
+| **§5 Business Rules** | F-xx `businessRules` via `satisfies` outbound → BR-xx-nn ids |
+| **§6 Functional Requirements** | F-xx FR list via `satisfies` → FR-xx-nn ids |
+| **§7 Input Data** | F-xx `inputData` + `dataEntity` nodes via `dependsOn` |
+| **§7 Output Data** | F-xx `outputData` + `dataEntity` nodes reachable from UC |
+| **§8 UI Requirements** | Screen nodes linked via `satisfies` → screen names and ids |
+| **§9 Related Use Cases** | UC nodes via `relatesTo`, `includes`, `extends` edges |
+
+For the **§3 list chapter** (not per-file): query `doc.srs.3-use-cases` CONTEXT depth 2 → extract all `useCase` nodes, sorted by id.
+
+**Rule:** Every UC and F-xx in output must exist as a graph node. Missing node → `<!-- TODO: node missing in graph -->`.