@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/skills/spec-diagram-review/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: spec-diagram-review
+owner: baseline
+description: Cross-consistency review of a drafted spec's diagrams. Verifies that C4 components appear in the dependency graph, class-diagram changes have matching DDL, every AC resolves to a concrete sequence, and the dependency graph is acyclic. Read-only. Run after `/spec-lint` passes and before `/approve-spec`.
+---
+
+You are auditing whether the diagrams inside `docs/specs/<slug>.md` tell a **consistent** story. The hooks and `/spec-lint` already guarantee each diagram parses and required kinds are present — your job is to catch *semantic* drift between diagrams.
+
+# Inputs
+
+- The spec: `docs/specs/<slug>.md` (caller passes the slug or path).
+- Optional: `docs/scout/<slug>.md` — reveals whether component names match actual code paths.
+
+You do not write files. Your output is an advisory report.
+
+# Method
+
+Walk the spec end-to-end, then run the five checks. Report every finding with a precise pointer (`§<section> line <n>` or `block #<N>`).
+
+## Check 1 — Container ↔ Component consistency
+
+- Every `Container(id, "Name", ...)` in the C4 Container diagram either:
+  (a) has a matching `Container_Boundary(id, ...)` with a Component diagram, or
+  (b) is annotated as "unchanged" in prose.
+- Every `Component(id, ...)` lives inside a `Container_Boundary` whose id exists in the Container diagram.
+
+## Check 2 — Components ↔ Dependency graph
+
+- Every component/container id referenced in a Component diagram's `Rel(...)` appears as a node in the dependency graph (`[id]`).
+- Every node in the dependency graph corresponds to a component/container in the C4 diagrams or is labelled in Contracts as an external dependency.
+
+## Check 3 — Dependency graph is acyclic
+
+- Parse the `' @kind dependency-graph` block. Build a directed graph from `[a] --> [b]` edges.
+- If any cycle exists, surface the cycle path as **Critical**. A cycle means the design has a deadlock — it must be resolved or explicitly justified under Open questions.
+
+## Check 4 — Class diagram ↔ Migration DDL
+
+- For each field marked `<<new>>` on a class, there must be a matching `ALTER TABLE ... ADD COLUMN` in the migration DDL block.
+- For each field marked `<<changed>>`, there must be a matching `ALTER ... ALTER COLUMN` or equivalent.
+- For each `ALTER TABLE ... ADD COLUMN`, the corresponding class must declare the field with a `<<new>>` stereotype.
+- Every forward DDL must have a paired reverse DDL in the same block.
+
+## Check 5 — ACs ↔ Sequences
+
+- Every row in the Acceptance criteria table (`AC-NNN`) must reference a sequence via `§Behavior #N`.
+- The referenced sequence block must exist and contain the promised interaction (method names in the AC should appear as arrow labels in the sequence).
+- No orphan sequences: every `title Behavior #N` block should be referenced by at least one AC row.
+
+# Output
+
+Plain markdown, no code-fence wrapper. Severity: **Critical** (blocks approval), **Major** (should fix), **Minor** (advisory).
+
+```
+# Spec Diagram Review — <slug>
+
+## Critical
+- <finding with pointer>
+
+## Major
+- <finding with pointer>
+
+## Minor
+- <finding with pointer>
+
+## Summary
+- Container ↔ Component: PASS | FAIL (<count>)
+- Components ↔ Dependency graph: PASS | FAIL (<count>)
+- Dependency graph acyclic: PASS | FAIL
+- Class ↔ Migration DDL: PASS | FAIL (<count>)
+- ACs ↔ Sequences: PASS | FAIL (<count>)
+
+Verdict: READY FOR APPROVAL | REVISIONS REQUIRED
+```
+
+# Constraints
+
+- Read-only. Do not call Edit, Write, or Bash beyond reads.
+- Do not rewrite the spec or propose new diagrams. Name the inconsistency; the author fixes it.
+- If a check cannot run (e.g., no class diagram block), say so — do not fail silently and do not guess.
+- Keep the report under ~150 lines. Long reports get skimmed; tight ones get acted on.

package/obj/template/.claude/skills/spec-lint/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: spec-lint
+owner: baseline
+description: Preflight a spec draft without saving. Runs the same three checks as the write-boundary hooks — PlantUML syntax, required diagram presence, and AC-to-sequence traceability — and prints a compact pass/fail table. Use while iterating so the hooks don't bite on save.
+---
+
+# spec-lint — preflight a spec draft
+
+Invocable by both user (`/spec-lint <slug>`) and Claude (when iterating on a spec and wanting to check status before writing).
+
+## What it checks
+
+Three checks, same logic as the hooks, but advisory (no writes are blocked):
+
+| # | Check | Hook it mirrors |
+|---|---|---|
+| 1 | Every ```plantuml``` fence parses under `plantuml -checkonly` | `plantuml_syntax_guard` |
+| 2 | Required diagram kinds present (config: `project.json → artifacts.required_diagrams.spec`) | `spec_diagram_presence_guard` |
+| 3 | Every `AC-NNN` row in the Acceptance criteria table references a `§Behavior #N` section that exists | (no hook — unique to the lint) |
+
+## Invocation
+
+`/spec-lint <slug>` — where `<slug>` corresponds to `docs/specs/<slug>.md`.
+
+## Steps
+
+1. Validate the slug: `docs/specs/<slug>.md` must exist.
+2. Run:
+   ```
+   .claude/skills/spec-lint/lint.sh <slug>
+   ```
+3. Print the script's output verbatim to the user. It is a table with one row per check and a final summary line.
+
+## Output format
+
+```
+check                              status
+---------------------------------- ------
+plantuml_syntax                    PASS
+diagram_presence                   FAIL  (missing: c4_component, dependency_graph)
+ac_traceability                    FAIL  (AC-002 → §Behavior #2 not found)
+---------------------------------- ------
+overall                            FAIL
+```
+
+Exit 0 on overall PASS, 1 on overall FAIL. Intended for use in CI or a pre-commit loop as well as interactively.
+
+## Prerequisites
+
+- `plantuml` CLI on PATH for check #1 (if absent, #1 is reported as `SKIP (no plantuml)`; #2 and #3 still run).
+
+## Notes
+
+- Unlike the hooks, `spec-lint` runs against the on-disk file, not proposed content. Save or use the hooks to validate an unsaved draft.
+- `spec-lint` does not render. Use `/spec-render <slug>` for that.

package/obj/template/.claude/skills/spec-lint/lint.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# spec-lint — run the three diagram-spec checks against a saved spec.
+# Usage: .claude/skills/spec-lint/lint.sh <slug>
+
+set -u
+
+if [ "${1:-}" = "" ]; then
+  echo "usage: lint.sh <slug>" >&2
+  exit 2
+fi
+SLUG="$1"
+
+ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SPEC="$ROOT/docs/specs/$SLUG.md"
+PROJECT_JSON="$ROOT/.claude/project.json"
+
+if [ ! -f "$SPEC" ]; then
+  echo "spec-lint: spec not found at $SPEC" >&2
+  exit 2
+fi
+
+HAS_PLANTUML=0
+command -v plantuml >/dev/null 2>&1 && HAS_PLANTUML=1
+
+SPEC="$SPEC" PROJECT_JSON="$PROJECT_JSON" HAS_PLANTUML="$HAS_PLANTUML" SLUG="$SLUG" python3 <<'PY'
+import json, os, re, subprocess, sys
+
+spec_path = os.environ["SPEC"]
+pj_path   = os.environ["PROJECT_JSON"]
+has_puml  = os.environ.get("HAS_PLANTUML") == "1"
+spec = open(spec_path, encoding="utf-8").read()
+
+fence_re = re.compile(r'^[ \t]*```[ \t]*plantuml[ \t]*$(.*?)^[ \t]*```[ \t]*$',
+                      re.DOTALL | re.IGNORECASE | re.MULTILINE)
+blocks = [m.group(1) for m in fence_re.finditer(spec)]
+
+def check_syntax():
+    if not has_puml:
+        return "SKIP", "plantuml CLI not on PATH"
+    if not blocks:
+        return "PASS", "no blocks"
+    bad = []
+    for i, body in enumerate(blocks, start=1):
+        src = body.strip("\n")
+        if "@startuml" not in src:
+            src = "@startuml\n" + src + "\n@enduml\n"
+        try:
+            r = subprocess.run(["plantuml", "-checkonly", "-pipe"],
+                               input=src.encode(), capture_output=True, timeout=15)
+        except Exception as e:
+            bad.append(f"block #{i}: {e}")
+            continue
+        if r.returncode != 0:
+            err = (r.stderr or r.stdout or b"").decode(errors="replace").strip().splitlines()
+            bad.append(f"block #{i}: {' | '.join(err[-2:]) if err else 'exit ' + str(r.returncode)}")
+    return ("PASS", "all blocks parse") if not bad else ("FAIL", "; ".join(bad))
+
+def check_presence():
+    try:
+        pj = json.load(open(pj_path))
+        required = pj["artifacts"]["required_diagrams"]["spec"]
+    except Exception:
+        return "SKIP", "required_diagrams.spec not configured"
+    missing = []
+    for kind, rule in required.items():
+        need = int(rule.get("min", 1))
+        marker = rule.get("marker")
+        any_of = rule.get("any_of") or []
+        found = 0
+        for b in blocks:
+            if marker and marker in b:
+                found += 1; continue
+            for pat in any_of:
+                try:
+                    if re.search(pat, b, re.MULTILINE):
+                        found += 1; break
+                except re.error:
+                    continue
+        if found < need:
+            missing.append(f"{kind} (need {need}, found {found})")
+    return ("PASS", "all kinds present") if not missing else ("FAIL", "missing: " + ", ".join(missing))
+
+def check_traceability():
+    # Find AC rows: table cells starting with AC-NNN in the Acceptance criteria section.
+    ac_section_re = re.compile(r'##\s+Acceptance criteria(.*?)(?=^##\s|\Z)', re.DOTALL | re.MULTILINE)
+    m = ac_section_re.search(spec)
+    if not m:
+        return "FAIL", "no '## Acceptance criteria' section"
+    section = m.group(1)
+    # Rows like: | AC-001 | ... | ... | §Behavior #1 |
+    row_re = re.compile(r'\|\s*(AC-\d+)\s*\|.*?\|\s*(§?Behavior\s*#?\s*\d+|§Behavior\s*#\d+|—|-)\s*\|', re.IGNORECASE)
+    rows = row_re.findall(section)
+    if not rows:
+        return "FAIL", "no AC-NNN rows with a sequence reference"
+    problems = []
+    # Extract which Behavior #N sequences actually exist: look for '### Behavior ...' or 'Behavior #N' titles and fenced sequence blocks.
+    behavior_titles = set()
+    # Accept anchors stamped inside sequence titles like `title Behavior #1 — ...`
+    for i, b in enumerate(blocks, start=1):
+        tm = re.search(r'(?im)^\s*title\s+Behavior\s*#(\d+)\b', b)
+        if tm:
+            behavior_titles.add(int(tm.group(1)))
+    # Also consider explicit ### headings like "### Behavior #N" (optional extra convention).
+    for hm in re.finditer(r'(?im)^###\s+Behavior\s*#(\d+)\b', spec):
+        behavior_titles.add(int(hm.group(1)))
+
+    for ac_id, ref in rows:
+        if ref.strip() in ("—", "-"):
+            problems.append(f"{ac_id}: no sequence reference")
+            continue
+        num_m = re.search(r'#\s*(\d+)', ref)
+        if not num_m:
+            problems.append(f"{ac_id}: unparsable ref '{ref.strip()}'")
+            continue
+        n = int(num_m.group(1))
+        if n not in behavior_titles:
+            problems.append(f"{ac_id}: §Behavior #{n} not found")
+    return ("PASS", f"{len(rows)} AC rows all traced") if not problems else ("FAIL", "; ".join(problems))
+
+def _expand_brace_globs(globs):
+    # Expand {a,b,c} alternations into multiple flat globs so fnmatch can handle them.
+    out = []
+    for g in globs:
+        if "{" not in g:
+            out.append(g); continue
+        # one level of brace expansion is enough for our patterns
+        i = g.index("{"); j = g.index("}", i)
+        prefix, alts, suffix = g[:i], g[i+1:j].split(","), g[j+1:]
+        for a in alts:
+            out.append(prefix + a.strip() + suffix)
+    return out
+
+def _glob_to_regex(g):
+    # Convert a shell-style glob to a regex anchored at full-string match.
+    # Handles `**` (any path segments incl. /), `*` (any chars except /),
+    # and `?` (one char). Everything else is escaped.
+    out = []
+    i = 0
+    while i < len(g):
+        c = g[i]
+        if c == "*":
+            if i + 1 < len(g) and g[i+1] == "*":
+                out.append(".*"); i += 2
+            else:
+                out.append("[^/]*"); i += 1
+        elif c == "?":
+            out.append("[^/]"); i += 1
+        elif c in ".+()|^$\\[]{}":
+            out.append(re.escape(c)); i += 1
+        else:
+            out.append(c); i += 1
+    return "^" + "".join(out) + "$"
+
+def _matches_any_glob(path, globs):
+    for g in _expand_brace_globs(globs):
+        if re.fullmatch(_glob_to_regex(g), path):
+            return True
+    return False
+
+def check_design_calls():
+    try:
+        pj = json.load(open(pj_path))
+        ui_globs = pj.get("tdd", {}).get("ui_globs", []) or []
+    except Exception:
+        return "SKIP", "tdd.ui_globs not configured"
+    if not ui_globs:
+        return "SKIP", "tdd.ui_globs is empty"
+
+    # Extract write_set paths from the spec body. Accept either a leading
+    # `write_set:` line (markdown body) or paths inside a Design calls table.
+    write_set_paths = set()
+    for line in spec.splitlines():
+        m = re.search(r'write[_\s]set\s*:\s*(.+)$', line, re.IGNORECASE)
+        if m:
+            for tok in re.split(r'[`,\s|]+', m.group(1)):
+                tok = tok.strip().strip("*").strip()
+                if tok and "/" in tok and not tok.startswith("#"):
+                    write_set_paths.add(tok)
+
+    # Compute intersection of write_set with ui_globs.
+    ui_hits = [p for p in write_set_paths if _matches_any_glob(p, ui_globs)]
+    if not ui_hits:
+        return "SKIP", f"no UI files in write_set ({len(write_set_paths)} paths checked)"
+
+    # Conditional fires — design_calls section must be present AND non-empty.
+    dc_section = re.search(
+        r'^##\s+Design\s+calls\s*$([\s\S]*?)(?=^##\s|\Z)',
+        spec, re.MULTILINE | re.IGNORECASE,
+    )
+    if not dc_section:
+        return "FAIL", f"write_set has UI files ({', '.join(sorted(ui_hits))}) but no `## Design calls` section"
+    body = dc_section.group(1).strip()
+    # Empty conventions: `*(none)*`, dash placeholders, or no table rows.
+    has_table_row = bool(re.search(r'^\|[^|\n]+\|[^|\n]+\|', body, re.MULTILINE))
+    is_none_marker = bool(re.search(r'^\s*-?\s*\*?\(?none\)?\*?\s*$', body, re.MULTILINE | re.IGNORECASE))
+    if not has_table_row or is_none_marker:
+        return "FAIL", f"write_set has UI files ({', '.join(sorted(ui_hits))}) but Design calls section is empty / `*(none)*`"
+    return "PASS", f"{len(ui_hits)} UI path(s) match design_calls rows"
+
+results = [
+    ("plantuml_syntax",   *check_syntax()),
+    ("diagram_presence",  *check_presence()),
+    ("ac_traceability",   *check_traceability()),
+    ("design_calls",      *check_design_calls()),
+]
+
+name_w = max(len(n) for n, _, _ in results)
+print(f"{'check'.ljust(name_w)}  {'status':<6}  detail")
+print(f"{'-'*name_w}  {'-'*6}  {'-'*50}")
+overall_fail = False
+for name, status, detail in results:
+    if status == "FAIL":
+        overall_fail = True
+    print(f"{name.ljust(name_w)}  {status:<6}  {detail}")
+print(f"{'-'*name_w}  {'-'*6}")
+print(f"{'overall'.ljust(name_w)}  {'FAIL' if overall_fail else 'PASS'}")
+sys.exit(1 if overall_fail else 0)
+PY

package/obj/template/.claude/skills/spec-render/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: spec-render
+owner: baseline
+description: Extract every PlantUML block from docs/specs/<slug>.md and render each to SVG under docs/specs/_rendered/<slug>/, with an index.md listing them in order. Run this before /approve-spec so the reviewer sees pictures instead of raw PlantUML.
+disable-model-invocation: true
+---
+
+# spec-render — render a spec's diagrams for review
+
+User-invokable only. This skill has side effects (writes SVGs and an index). Claude does not invoke it autonomously.
+
+## Invocation
+
+`/spec-render <slug>` — where `<slug>` corresponds to `docs/specs/<slug>.md`.
+
+## Prerequisites
+
+- `plantuml` CLI on PATH (`brew install plantuml` / `apt-get install plantuml`).
+- The spec at `docs/specs/<slug>.md` exists and passes `spec_diagram_presence_guard` + `plantuml_syntax_guard` — otherwise rendering will surface the same errors.
+
+## Steps
+
+1. Validate the slug: `docs/specs/<slug>.md` must exist.
+2. Run the render script:
+   ```
+   .claude/skills/spec-render/render.sh <slug>
+   ```
+   The script:
+   - Reads `docs/specs/<slug>.md`.
+   - Extracts every ```plantuml``` fenced block in source order.
+   - For each block: classifies it by marker (c4_context / c4_container / c4_component / sequence / class / dependency_graph / state / other), writes `docs/specs/_rendered/<slug>/<NN>_<kind>.puml`, then renders to `<NN>_<kind>.svg`.
+   - Writes `docs/specs/_rendered/<slug>/index.md` with section titles and image links in order.
+3. Report the output path and a short per-kind count to the user.
+4. If any block fails to render, surface the offending index + first line + stderr tail, and exit non-zero. Do **not** silently skip broken blocks.
+
+## Output
+
+- `docs/specs/_rendered/<slug>/<NN>_<kind>.svg` — one per diagram block.
+- `docs/specs/_rendered/<slug>/<NN>_<kind>.puml` — source kept next to the SVG for easier diffs.
+- `docs/specs/_rendered/<slug>/index.md` — markdown index with embedded images.
+
+## Notes
+
+- The render directory is a build output. Add `docs/specs/_rendered/` to `.gitignore` if you don't want the SVGs in the repo; the PlantUML sources in the spec are the source of truth.
+- For offline review without installing PlantUML, use the `plantuml` MCP server from `.mcp.json` — it talks to a PlantUML renderer over HTTP. This skill prefers the local CLI because it's faster and keeps renders self-contained.

package/obj/template/.claude/skills/spec-render/render.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# spec-render — extract every ```plantuml``` block from docs/specs/<slug>.md,
+# classify it, render to SVG, and write an index.md.
+#
+# Usage: .claude/skills/spec-render/render.sh <slug>
+
+set -eu
+
+if [ "${1:-}" = "" ]; then
+  echo "usage: render.sh <slug>" >&2
+  exit 2
+fi
+SLUG="$1"
+
+ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SPEC="$ROOT/docs/specs/$SLUG.md"
+OUT="$ROOT/docs/specs/_rendered/$SLUG"
+
+if [ ! -f "$SPEC" ]; then
+  echo "spec-render: spec not found at $SPEC" >&2
+  exit 2
+fi
+
+if ! command -v plantuml >/dev/null 2>&1; then
+  echo "spec-render: \`plantuml\` CLI not on PATH. Install: brew install plantuml (macOS) / apt-get install plantuml (Debian/Ubuntu)." >&2
+  exit 2
+fi
+
+mkdir -p "$OUT"
+rm -f "$OUT"/*.puml "$OUT"/*.svg "$OUT"/index.md 2>/dev/null || true
+
+# Extract + classify + write .puml files.
+SPEC="$SPEC" OUT="$OUT" SLUG="$SLUG" python3 <<'PY'
+import os, re, sys
+
+spec = open(os.environ["SPEC"], encoding="utf-8").read()
+out  = os.environ["OUT"]
+slug = os.environ["SLUG"]
+
+fence_re = re.compile(r'^[ \t]*```[ \t]*plantuml[ \t]*$(.*?)^[ \t]*```[ \t]*$',
+                      re.DOTALL | re.IGNORECASE | re.MULTILINE)
+
+def classify(body):
+    lowered = body.lower()
+    if "!include <c4/c4_context>"   in lowered: return "c4_context"
+    if "!include <c4/c4_container>" in lowered: return "c4_container"
+    if "!include <c4/c4_component>" in lowered: return "c4_component"
+    if re.search(r"'\s*@kind\s+dependency-graph", body): return "dependency_graph"
+    if re.search(r"^\s*(participant|actor)\b", body, re.MULTILINE): return "sequence"
+    if re.search(r"^\s*\[\*\]\s*-->", body, re.MULTILINE): return "state"
+    if re.search(r"^\s*class\s+\w", body, re.MULTILINE): return "class"
+    return "other"
+
+# Section title from the last preceding ### heading (for the index).
+heading_re = re.compile(r'^\s{0,3}#{2,4}\s+(.+?)\s*$', re.MULTILINE)
+
+blocks = []
+for m in fence_re.finditer(spec):
+    before = spec[:m.start()]
+    headings = heading_re.findall(before)
+    section = headings[-1].strip() if headings else "(untitled)"
+    body = m.group(1).strip("\n")
+    if "@startuml" not in body:
+        body = "@startuml\n" + body + "\n@enduml\n"
+    kind = classify(body)
+    blocks.append((section, kind, body))
+
+if not blocks:
+    print("spec-render: no ```plantuml``` blocks found", file=sys.stderr)
+    sys.exit(1)
+
+index_lines = [f"# Rendered diagrams — {slug}", ""]
+for i, (section, kind, body) in enumerate(blocks, start=1):
+    stem = f"{i:02d}_{kind}"
+    puml_path = os.path.join(out, stem + ".puml")
+    with open(puml_path, "w", encoding="utf-8") as f:
+        f.write(body if body.endswith("\n") else body + "\n")
+    index_lines.append(f"## {i:02d}. {section} — `{kind}`")
+    index_lines.append("")
+    index_lines.append(f"![{kind}]({stem}.svg)")
+    index_lines.append("")
+    index_lines.append(f"Source: [`{stem}.puml`]({stem}.puml)")
+    index_lines.append("")
+
+with open(os.path.join(out, "index.md"), "w", encoding="utf-8") as f:
+    f.write("\n".join(index_lines))
+print(f"spec-render: extracted {len(blocks)} block(s)")
+PY
+
+# Render each .puml to SVG. Fail loud on any error.
+fail=0
+for puml in "$OUT"/*.puml; do
+  [ -f "$puml" ] || continue
+  if ! plantuml -tsvg -o "$OUT" "$puml" 2>"$OUT/.render.err"; then
+    echo "spec-render: FAILED to render ${puml##*/}" >&2
+    sed -n '1,10p' "$OUT/.render.err" >&2
+    fail=1
+  fi
+done
+rm -f "$OUT/.render.err"
+
+if [ "$fail" -ne 0 ]; then
+  echo "spec-render: one or more blocks failed to render. See errors above." >&2
+  exit 1
+fi
+
+# Count per kind for the user summary.
+echo "spec-render: wrote $OUT/index.md"
+ls "$OUT" | awk -F_ '/\.svg$/ { sub(/\.svg$/, "", $0); sub(/^[0-9]+_/, "", $0); kinds[$0]++ } END { for (k in kinds) printf "  %s: %d\n", k, kinds[k] }'

package/obj/template/.claude/skills/spec-traceability-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: spec-traceability-review
+owner: baseline
+description: Traceability review — every spec AC must trace to a resolvable upstream AC in the intake (and BRD if present), and no upstream AC is silently dropped. Read-only. Run alongside `spec-diagram-review` before `/approve-spec`.
+---
+
+You answer one question: **can every acceptance criterion in the spec be traced to an upstream requirement, and is every upstream requirement accounted for?**
+
+# Inputs
+
+- Spec: `docs/specs/<slug>.md`
+- Intake: `docs/intake/<slug>.md` (required)
+- BRD: `docs/brd/<slug>.md` (optional — include if present)
+
+If the intake is missing, stop and report: "Cannot trace: intake not found at docs/intake/<slug>.md". Do not infer.
+
+# Method
+
+1. Extract AC IDs from the intake's Acceptance criteria section. IDs may be numbered (1, 2, 3) or prefixed (AC-001, AC1). Record both forms.
+2. Extract business requirements from the BRD if present. IDs are typically `BR-NNN`.
+3. Extract AC rows from the spec's Acceptance criteria table. Record each row's `AC-NNN` id and its `Upstream AC` reference.
+4. Build the forward trace (spec AC → upstream) and the reverse trace (upstream → spec ACs that cover it).
+
+# Severity matrix
+
+| Severity | Condition |
+|---|---|
+| Critical | A spec `AC-NNN` row has no `Upstream AC` cell, or the cell does not resolve to a real intake/BRD AC. |
+| Critical | An intake AC has no corresponding spec AC (silent drop). |
+| Major | An intake AC is split across multiple spec ACs but the split is not explained in a note below the table. |
+| Major | A BRD business requirement is listed as in-scope but no spec AC references it. |
+| Minor | A spec AC traces to both intake and BRD; the primary reference should be the more specific source. |
+
+# Output
+
+Plain markdown. One section per severity. End with a two-table summary.
+
+```
+# Spec Traceability Review — <slug>
+
+## Critical
+- <finding>
+
+## Major
+- <finding>
+
+## Minor
+- <finding>
+
+## Forward trace (spec → upstream)
+| Spec AC | Upstream | Resolves? |
+|---|---|---|
+| AC-001 | intake AC 1 | YES |
+| AC-002 | BR-001 | YES |
+| AC-003 | (missing) | NO |
+
+## Reverse trace (upstream → spec)
+| Upstream | Covered by | Complete? |
+|---|---|---|
+| intake AC 1 | AC-001 | YES |
+| intake AC 2 | — | NO (silent drop) |
+| BR-001 | AC-002 | YES |
+
+Verdict: READY FOR APPROVAL | REVISIONS REQUIRED
+```
+
+# Constraints
+
+- Read-only. Do not call Edit, Write, or Bash beyond reads.
+- Do not judge the *quality* of ACs themselves (that's the diagram-review's and human reviewer's concern). Only check that the linkage is intact.
+- If the intake's AC format is ambiguous (mixed ID styles, un-numbered bullets), flag under **Minor** and proceed with your best mapping — do not fail the review on formatting alone.
+- Keep the report under ~120 lines.