ai-spector 0.2.4 → 0.2.6

package/scaffold/.cursor/commands/link-graph.md

@@ -0,0 +1,43 @@
+# /link-graph — semantic meaning edges (agent + CLI)
+
+Add **meaning (agent)** edges (`relatesTo`) that CLI/index cannot infer. Do **not** edit `traceability.graph.json` by hand.
+
+## Prerequisites
+
+- `ai-spector index` completed (spec sections + `derivedFrom` when possible)
+- Seed id (e.g. `UC-03`) or `--file` + heading
+
+## Steps
+
+1. **Query graph (CLI)**
+
+   ```bash
+   npx ai-spector graph query <SEED> --direction both --depth 3 --json
+   npx ai-spector graph report --json
+   ```
+
+2. **Read sources** — Only open paths from `derivedFrom` / `sourceRef` on the seed; read matching `docs/data-source/**` excerpts and relevant SRS `###` sections.
+
+3. **Write patch** — Save edges to:
+
+   `.ai-spector/.docflow/extract/semantic-links.patch.json`
+
+   Use the example format in `semantic-links.patch.example.json`. Rules:
+
+   - **Edges only** by default (`nodes: []`)
+   - Allowed type: `relatesTo` (optional `role`: `evidence`, `usesEntity`, …)
+   - Use **existing** node ids from query output only
+   - Do **not** create new `document` or `section` nodes
+
+4. **Merge + validate (CLI)**
+
+   ```bash
+   npx ai-spector graph merge --semantic
+   npx ai-spector graph validate
+   ```
+
+5. Show the user a short summary: edges added, seed, and whether `graph report` still lists domains needing links.
+
+## Failures
+
+See `.cursor/commands/_cli-failures.md`. If merge rejects an edge, fix the patch ids/types and re-run merge.

package/schemas/schema.graph.json

@@ -20,6 +20,8 @@
     "nodeType": {
       "type": "string",
       "enum": [
+        "bundle",
+        "sourceFile",
         "document",
         "section",
         "table",
@@ -46,7 +48,8 @@
         "requires",
         "tracesTo",
         "derivedFrom",
-        "rendersTo"
+        "rendersTo",
+        "relatesTo"
       ]
     },
     "node": {
@@ -59,13 +62,18 @@
         "template": { "type": "string" },
         "output": { "type": "string" },
         "outputPattern": { "type": "string" },
-        "perDomain": { "type": "string", "enum": ["useCase", "feature"] },
+        "perDomain": {
+          "type": "string",
+          "enum": ["useCase", "feature", "apiDetail", "screenDetail"]
+        },
         "documentId": { "type": "string" },
         "heading": { "type": "string" },
         "level": { "type": "integer", "minimum": 2, "maximum": 6 },
         "order": { "type": "integer", "minimum": 0 },
         "title": { "type": "string" },
-        "slug": { "type": "string" }
+        "slug": { "type": "string" },
+        "role": { "type": "string", "enum": ["source", "business", "spec"] },
+        "path": { "type": "string" }
       }
     },
     "edge": {