@benjaminthomas/spec-driven-dev 1.8.0 → 1.11.0

package/bin/risk.mjs

@@ -0,0 +1,137 @@
+// GitRisk: per-file historical risk from git alone (no model, no tokens).
+//   Risk = 0.30·Churn + 0.35·BugDensity + 0.20·FanOut + 0.15·Security   (each factor 0–100)
+// The weights are a hypothesis to calibrate by backtest, so .spec-driven.yml `risk.weights` overrides them.
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+export const DEFAULT_WEIGHTS = { churn: 0.3, bug_density: 0.35, fan_out: 0.2, security: 0.15 };
+export const TIERS = [[75, "critical"], [50, "high"], [25, "medium"], [0, "low"]];
+const MIN_COMMITS = 3; // shortcut: a file with 1 commit that was a fix would score 100% bug density; divide by at least 3. Replace with Bayesian smoothing if calibration shows it matters.
+
+// Classification uses the conventional-commit type when the repo uses one, and message keywords otherwise.
+const BUG = /^(fix|hotfix|bugfix|revert)(\(.+\))?!?:|\b(fix(e[sd]|ing)?|bug|hotfix|regression|broken|crash(es|ed)?|patch(ed)?|defect)\b/i;
+const SECURITY = /\b(security|cve-\d+|xss|csrf|ssrf|sqli|injection|vuln(erability)?|exploit|sanitiz(e|ation)|escap(e|ing) (html|input|output)|auth(entication|orization)? (bypass|fix)|privilege|secret(s)? (leak|exposed)|leak(ed|s)? (token|key|secret|credential)|rate.?limit|helmet|csp)\b/i;
+const SKIP = /(^|\/)(node_modules|dist|build|out|vendor|coverage|\.next|graphify-out|specs)\/|\.(md|mdx|txt|lock|log|png|jpe?g|gif|svg|ico|webp|pdf|zip|map|snap|csv)$|(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|go\.sum|poetry\.lock|composer\.lock)$/i;
+const CODE = /\.(m?[jt]sx?|cjs|py|rb|go|rs|java|kt|php|cs|swift|scala|vue|svelte)$/i;
+
+const git = (cwd, args) => {
+  try { return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 512 * 1024 * 1024 }).toString(); } catch { return ""; }
+};
+export const classify = (subject) => ({ bug: BUG.test(subject), security: SECURITY.test(subject) });
+export const tierOf = (score) => TIERS.find(([min]) => score >= min)[1];
+
+// Value at the 90th percentile; "expected" in min(100, actual / expected × 100), so one outlier can't flatten everyone else.
+function p90(values) {
+  const v = values.filter((x) => x > 0).sort((a, b) => a - b);
+  return v.length ? v[Math.min(v.length - 1, Math.floor(v.length * 0.9))] : 1;
+}
+
+// Within-repo dependents: how many other files import this one. Relative JS/TS imports and Python module paths.
+// shortcut: no tsconfig path aliases or cross-repo consumers (GitRisk open question U7); add when a repo needs them.
+function fanOut(repo, files) {
+  const set = new Set(files), dependents = new Map(files.map((f) => [f, new Set()]));
+  const exts = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", "/index.ts", "/index.tsx", "/index.js", "/index.jsx", ".py", "/__init__.py"];
+  const pyIndex = new Map(files.filter((f) => f.endsWith(".py")).map((f) => [f.replace(/\/__init__\.py$|\.py$/, "").split("/").join("."), f]));
+  for (const f of files) {
+    if (!CODE.test(f)) continue;
+    let text = "";
+    try { text = fs.readFileSync(path.join(repo, f), "utf8"); } catch { continue; }
+    if (text.length > 2e6) continue;
+    const targets = new Set();
+    for (const m of text.matchAll(/(?:from\s+|require\(\s*|import\(\s*|import\s+)["'](\.{1,2}\/[^"']+)["']/g)) {
+      const base = path.posix.normalize(path.posix.join(path.posix.dirname(f), m[1]));
+      const hit = exts.map((e) => base + e).find((c) => set.has(c));
+      if (hit) targets.add(hit);
+    }
+    if (f.endsWith(".py")) for (const m of text.matchAll(/^\s*(?:from\s+([\w.]+)\s+import|import\s+([\w.]+))/gm)) {
+      const hit = pyIndex.get(m[1] || m[2]);
+      if (hit) targets.add(hit);
+    }
+    for (const t of targets) if (t !== f) dependents.get(t).add(f);
+  }
+  return new Map([...dependents].map(([f, s]) => [f, s.size]));
+}
+
+// Score every tracked code file in one repo. `prefix` labels files in multi-repo workspaces.
+export function scoreRepo(repo, { since = "2 years ago", weights = DEFAULT_WEIGHTS, prefix = "" } = {}) {
+  const files = git(repo, ["ls-files"]).split("\n").filter((f) => f && !SKIP.test(f));
+  const tracked = new Set(files);
+  const stats = new Map(files.map((f) => [f, { commits: 0, bug: 0, security: 0 }]));
+  let commits = 0;
+  // \x1e starts each commit; the subject follows, then the changed file names.
+  for (const block of git(repo, ["log", "--no-merges", `--since=${since}`, "--name-only", "--format=%x1e%s"]).split("\x1e").slice(1)) {
+    const [subject, ...changed] = block.split("\n");
+    const c = classify(subject);
+    commits++;
+    for (const f of changed) {
+      const s = tracked.has(f) && stats.get(f);
+      if (!s) continue;
+      s.commits++;
+      if (c.bug) s.bug++;
+      if (c.security) s.security++;
+    }
+  }
+  const fan = fanOut(repo, files);
+  const expChurn = p90([...stats.values()].map((s) => s.commits)), expFan = p90([...fan.values()]);
+  const rows = files.map((f) => {
+    const s = stats.get(f), denom = Math.max(s.commits, MIN_COMMITS);
+    const factors = {
+      churn: Math.min(100, (s.commits / expChurn) * 100),
+      bug_density: s.commits ? (s.bug / denom) * 100 : 0,
+      fan_out: Math.min(100, ((fan.get(f) || 0) / expFan) * 100),
+      security: s.commits ? (s.security / denom) * 100 : 0,
+    };
+    const score = Object.keys(DEFAULT_WEIGHTS).reduce((t, k) => t + (Number(weights[k]) || 0) * factors[k], 0);
+    const r = (x) => Math.round(x * 10) / 10;
+    return { file: prefix ? `${prefix}/${f}` : f, score: r(score), tier: tierOf(score), commits: s.commits, bug_fixes: s.bug, security_fixes: s.security, dependents: fan.get(f) || 0,
+      factors: { churn: r(factors.churn), bug_density: r(factors.bug_density), fan_out: r(factors.fan_out), security: r(factors.security) } };
+  });
+  return { commits, head: git(repo, ["rev-parse", "--short", "HEAD"]).trim(), rows };
+}
+
+export function normWeights(w) {
+  const out = { ...DEFAULT_WEIGHTS };
+  for (const k of Object.keys(DEFAULT_WEIGHTS)) if (w && w[k] !== undefined && w[k] !== "") out[k] = Number(w[k]);
+  return out;
+}
+export function weightProblems(w) {
+  const p = [];
+  for (const [k, v] of Object.entries(w || {})) {
+    if (!(k in DEFAULT_WEIGHTS)) p.push(`risk.weights.${k}: unknown factor (use ${Object.keys(DEFAULT_WEIGHTS).join(", ")})`);
+    else if (!(Number(v) >= 0)) p.push(`risk.weights.${k} "${v}" must be a number ≥ 0`);
+  }
+  const sum = Object.values(normWeights(w)).reduce((a, b) => a + b, 0);
+  if (Math.abs(sum - 1) > 0.001) p.push(`risk.weights add up to ${Math.round(sum * 1000) / 1000}, not 1`);
+  return p;
+}
+
+// The area file skills read: top N files, within the 150-line area-file limit.
+export function riskMarkdown({ rows, repos, weights, since, top }) {
+  const pct = (x) => `${Math.round(x * 100)}%`;
+  const w = weights;
+  const shown = rows.filter((r) => r.score > 0).slice(0, Math.min(top, 120));
+  const lines = [
+    "# Risk",
+    "<!-- Generated by `spec-driven-dev risk`. Don't edit by hand: re-run it. Skills read this only when risk.enabled is on. -->",
+    `Scored ${repos.map((r) => `${r.name} at ${r.head} (${r.commits} commits)`).join(", ")} · since ${since} · ${new Date().toISOString().slice(0, 10)}`,
+    "",
+    `Risk = ${w.churn} × Churn + ${w.bug_density} × Bug Density + ${w.fan_out} × Fan-out + ${w.security} × Security (each 0–100; weights ${pct(w.churn)} / ${pct(w.bug_density)} / ${pct(w.fan_out)} / ${pct(w.security)}).`,
+    "Tiers: critical ≥ 75 · high ≥ 50 · medium ≥ 25. A historical signal, not proof of a bug.",
+    "",
+    "| File | Score | Tier | Churn | Bug density | Fan-out | Security | Commits (fixes / security) |",
+    "|---|---|---|---|---|---|---|---|",
+    ...shown.map((r) => `| \`${r.file}\` | ${r.score} | ${r.tier} | ${r.factors.churn} | ${r.factors.bug_density} | ${r.factors.fan_out} | ${r.factors.security} | ${r.commits} (${r.bug_fixes} / ${r.security_fixes}) |`),
+  ];
+  if (rows.length > shown.length) lines.push("", `${rows.length - shown.length} more files not shown. \`spec-driven-dev risk --files=a,b\` prints any file's score.`);
+  return lines.join("\n") + "\n";
+}
+
+// Change one `block: key: value` line in .spec-driven.yml text, keeping every comment and other line as is.
+export function setConfigValue(text, blockName, key, value) {
+  const block = text.match(new RegExp(`^${blockName}:.*\\n(?:(?:[ \\t]+.*|[ \\t]*)\\n)*`, "m"));
+  const line = new RegExp(`^([ \\t]+${key}:[ \\t]*)[^\\s#]+`, "m");
+  if (!block) return `${text.replace(/\n*$/, "\n")}${blockName}:\n  ${key}: ${value}\n`;
+  const body = line.test(block[0]) ? block[0].replace(line, `$1${value}`) : block[0].replace(new RegExp(`^${blockName}:.*\\n`), `$&  ${key}: ${value}\n`);
+  return text.replace(block[0], body);
+}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.8.0",
-  "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
+  "version": "1.11.0",
+  "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → review → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
   "type": "module",
   "bin": {
     "spec-driven-dev": "bin/spec-driven-dev.cjs"
   },
   "files": [
     "bin",
-    "skills"
+    "plugin/skills",
+    "plugin/.claude-plugin"
   ],
   "scripts": {
     "test": "python3 scripts/check.py && node scripts/test-cli.mjs"

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "ticket-to-pr",
+  "version": "1.11.0",
+  "description": "Parallel-batch spec-driven feature workflow (spec-setup, spec-investigate, spec-create, spec-implement, spec-verify, spec-review, spec-checkpoint, spec-ship) plus a portable SEO/GEO operations skill (generative-seo) for any codebase.",
+  "author": {
+    "name": "Benjamin Thomas",
+    "url": "https://github.com/benjaminthomas"
+  },
+  "keywords": [
+    "spec-driven-development",
+    "feature-workflow",
+    "parallel-agents",
+    "seo",
+    "geo",
+    "productivity"
+  ],
+  "homepage": "https://github.com/benjaminthomas/spec-driven-dev",
+  "repository": "https://github.com/benjaminthomas/spec-driven-dev",
+  "icon": ".claude-plugin/icon.png"
+}

package/{skills → plugin/skills}/spec-checkpoint/SKILL.md

@@ -49,6 +49,28 @@ issues before proceeding — do not skip or ignore failures.
 
 Iterate until every check passes cleanly. Only then move to the next step.
 
+### Step 2b: Update project context (spec work only)
+
+Skip this step unless the changes belong to a spec (`{specs_dir}/{feature}/` exists for this work).
+
+1. Overwrite the README's **Resume here** (`Stage: committed`, `Next: spec-ship`). Write
+   `Last commit: this checkpoint (git log -1)`, because the commit's hash doesn't exist yet and
+   amending afterwards would change it again.
+2. **When the feature is done** (every task checked) and `{specs_dir}/CONTEXT.md` exists, distil
+   the lasting lessons. Use the light model tier for this where the host lets you pick a subagent
+   model.
+   - Read the feature's `log.md`. This is the one time it's read in full.
+   - Keep only what a future feature in the same area needs: decisions and why, conventions found,
+     pitfalls. Drop routine progress.
+   - Add them to the end of the right `context/<area>.md` (create it if the area has none), and add
+     one line to CONTEXT.md's **Specs** list. Follow the rules in
+     references/context-template.md inside the installed `spec-setup` skill folder (not this repo): dated, with a source, added at the end, within the size
+     limits, superseded lines moved to `context/archive.md`.
+   - Show the context changes in the report so the user can correct them.
+3. If `risk.enabled` is on and the CLI is available, re-run `spec-driven-dev risk` so the scores
+   include this work. It's git-only, so it costs no tokens.
+4. No CONTEXT.md? Skip the distilling and suggest running `spec-setup` to create one.
+
 ### Step 3: Stage Everything
 
 Stage all changes — tracked modifications, deletions, and new untracked files:
@@ -65,6 +87,9 @@ anything you don't recognize; skim its diff if you're unsure.
 
 ### Step 4: Craft the Commit Message
 
+Check `{specs_dir}/CONTEXT.md`'s **Conventions** first, if it exists. A recorded rule about commits
+(authorship, trailers, format) beats the defaults below.
+
 Write a commit message in the config's `git.commit_style` (`conventional` → `feat: …`, `ticket` → `STP-123: …` using the ticket ID from the branch name, `freeform`). Without config, follow the project's existing conventions (observed from `git log`). Structure:
 
 - **First line**: clear, concise summary in imperative mood (50-72 chars)

package/{skills → plugin/skills}/spec-create/SKILL.md

@@ -32,6 +32,31 @@ isn't, detect what this skill needs from the repo, ask about anything ambiguous,
 the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
 `specs_dir`).
 
+## Project context
+
+- **Take context from the investigation.** Use `investigation.md`'s **Relevant Context**. Without an
+  investigation, read `{specs_dir}/CONTEXT.md` (or `spec-driven-dev context`) and only the
+  `context/<area>.md` files this feature touches. Never load the archive.
+- **Copy, don't link.** Put only the 3–5 lines each task needs into that task's **Project Context**.
+  Coders never read the context files, which keeps parallel coders from each loading them.
+- **Trace requirements.** Number them R1, R2… (keep the investigation's numbers), fill **Covers** in
+  every task and the **Coverage** table in requirements.md. Don't finish while a requirement has no
+  task.
+- **Start the memory.** Create or extend `log.md` (`references/log-template.md`) and fill the
+  README's **Resume here** block.
+
+## Risk signal (GitRisk)
+
+Same rule as `spec-investigate`: use it only when `risk.enabled` is on (or absent) and
+`{specs_dir}/context/risk.md` exists, and ignore risk completely when it's `off`. For each task that
+creates or modifies a **high** or **critical** file (from the investigation's **Risk Hotspots**, or
+`spec-driven-dev risk --files=…`):
+
+- **Raise its tier by one** (light → standard → deep), and say why in Complexity's Signals.
+- Fill the task's **Risk** section: the file, its score, and the past failure pattern.
+- Its **Tests** must include at least one test aimed at that past failure pattern, not just the new
+  behaviour.
+
 ## When to Use
 
 - After a planning conversation where requirements and technical details have been discussed
@@ -92,6 +117,7 @@ specs/{feature-name}/
 ├── README.md
 ├── requirements.md
 ├── action-required.md
+├── log.md
 └── tasks/
     ├── task-01-{name}.md
     ├── task-02-{name}.md
@@ -103,6 +129,7 @@ Read the templates in `references/` before writing each file:
 - `references/task-template.md` — for each task file (self-contained with all context)
 - `references/requirements-template.md` — for the requirements document
 - `references/action-required-template.md` — for manual human steps
+- `references/log-template.md` — for the append-only log
 
 Task files are numbered with zero-padded two-digit prefixes in topological order: Batch 1 tasks first, then Batch 2, etc. Within a batch, order is arbitrary but stable.
 
@@ -135,6 +162,7 @@ Files created:
 - action-required.md
 - tasks/ ({T} task files)
 
+Coverage: R1–R{n} all mapped to tasks
 Model plan: {n} light · {n} standard · {n} deep
   (models from .spec-driven.yml → light: {model}, standard: {model}, deep: {model})
   Deep tasks: {task-nn — main reason}
@@ -149,7 +177,7 @@ Next steps:
 2. Review the requirements and task files
 3. When you're happy with it, either:
    - say "implement" to build it and stop for review, or
-   - say "approved, run it through" to build, verify and commit in one go (stops at any failure,
+   - say "approved, run it through" to build, verify, review and commit in one go (stops at any failure,
      never pushes without asking)
 ```
 
@@ -163,4 +191,5 @@ by default after approval. Never start implementing from this skill.
 - Tasks within the same batch must not modify overlapping files. Parallel agents on the same branch cannot safely touch the same files.
 - Keep tasks atomic — one concern per task. If a task has more than 5-7 files to modify, consider splitting it.
 - Put tests in each task's Tests section, not in separate testing tasks (unless the user asks, or it's a cross-cutting suite).
+- Every requirement (R1…) maps to at least one task, and every task lists what it **Covers**.
 - Number task files in topological order (batch 1 first, then batch 2, etc.) for easy scanning.

package/plugin/skills/spec-create/references/log-template.md

@@ -0,0 +1,27 @@
+# Log Template
+
+`specs/{feature}/log.md` keeps what would otherwise live only in the chat: decisions, deviations,
+answers from the user, review findings, and dead ends. Without it, those are lost when the session
+ends or the conversation is compacted.
+
+**Rules**
+- **Append only.** Add entries at the bottom. Never rewrite or reorder.
+- **Never read it in full.** A new session reads the README's **Resume here** block. Read the log's
+  last ~20 lines only when Resume here isn't enough.
+- **One to three lines per entry.** Point to files as `path:line`. Don't paste code.
+- **Log what's worth keeping:** a decision and its reason, a change from the spec, the user's answer
+  to a question, a review finding and its fix, an approach that failed and why. Skip routine
+  progress, which the checkboxes already show.
+
+## Template
+
+```markdown
+# Log: {Feature Name}
+
+- 2026-11-10 spec-create · Created spec: {N} tasks in {B} batches. Covers R1–R{n}.
+- 2026-11-10 spec-implement · Decision: reuse `retryWithBackoff` (`src/lib/retry.ts:12`) instead of a new helper. The user asked for it.
+- 2026-11-10 spec-implement · Deviation: task-03 also touches `src/api/routes.ts`, because the route table lives there.
+- 2026-11-11 spec-verify · R3 failed: webhook retried 5 times, not 3. Fixed in task-04 and re-verified.
+```
+
+Each entry has the date, the skill that wrote it, then what happened and why.

package/{skills → plugin/skills}/spec-create/references/readme-template.md

@@ -7,6 +7,15 @@ Use this structure for the README.md at the root of each spec folder. The README
 ```markdown
 # {Feature Name}
 
+## Resume here
+
+<!-- Overwritten by each spec-* skill when it finishes. A new session reads this first. Keep it ~10 lines. -->
+- **Stage:** spec created, awaiting approval
+- **Next:** review the spec, then say "implement" (or "approved, run it through")
+- **Open questions:** {none, or one line each}
+- **Last commit:** {short sha, or "none yet"}
+- **Areas:** {context areas this feature touches, e.g. billing, api}
+
 ## Overview
 
 {One paragraph summary of what the feature does and why it exists.}
@@ -15,6 +24,7 @@ Use this structure for the README.md at the root of each spec folder. The README
 
 - [Requirements](./requirements.md) — full requirements and acceptance criteria
 - [Action Required](./action-required.md) — manual steps needing human action
+- [Log](./log.md) — decisions, deviations and review findings (append-only)
 
 ## Dependency Graph
 
@@ -48,6 +58,8 @@ graph TD
 
 ## Key Points
 
+- **Resume here** is the cheap way back in. Every `spec-*` skill overwrites it when it finishes (stage, next action, open questions, last commit), so a new or compacted session reads ~10 lines instead of the whole history. `spec-driven-dev status` prints each spec's **Next** line.
+
 - The **Dependency Graph** uses Mermaid syntax (widely rendered in GitHub, VS Code, etc.). Each node shows the task number and title for quick reference.
 - The **Batches** table provides a scannable overview of what runs in parallel.
 - The **Task Status** section uses markdown checkboxes that the `spec-implement` skill updates as tasks complete. The orchestrator parses these to determine which batch to resume from.

package/{skills → plugin/skills}/spec-create/references/requirements-template.md

@@ -26,11 +26,18 @@ Use this structure for the requirements.md at the root of each spec folder.
 
 ## Acceptance Criteria
 
-{High-level criteria for the entire feature. Individual task files have their own granular criteria.}
+{High-level criteria for the entire feature, numbered R1, R2… so tasks and verification can point to them. Keep the numbers from investigation.md if it has them. Individual task files have their own granular criteria.}
 
-- [ ] {Criterion 1}
-- [ ] {Criterion 2}
-- [ ] {Criterion 3}
+- [ ] R1: {Criterion 1}
+- [ ] R2: {Criterion 2}
+- [ ] R3: {Criterion 3}
+
+## Coverage
+
+| Requirement | Tasks |
+|---|---|
+| R1 | task-01, task-03 |
+| R2 | task-02 |
 
 ## Assumptions
 
@@ -51,4 +58,5 @@ Use this structure for the requirements.md at the root of each spec folder.
 
 - The requirements doc provides **overall feature context** that each coder agent receives alongside its task file. Keep it focused on the "what" and "why" — individual task files handle the "how."
 - Non-goals are important: they prevent agents from over-building. If search functionality is out of scope, say so — otherwise a well-meaning agent might add it.
+- **Every requirement must map to at least one task.** `spec-create` doesn't finish while the Coverage table has a requirement with no task, and `spec-verify` reports pass/fail per requirement number.
 - Acceptance criteria here are feature-level (the whole thing works end-to-end). Task-level criteria live in each task file.

package/{skills → plugin/skills}/spec-create/references/task-template.md

@@ -15,6 +15,10 @@ pending
 
 {N}
 
+## Covers
+
+{Requirement numbers from requirements.md this task delivers, e.g. R1, R3.}
+
 ## Complexity
 
 **Tier:** {light | standard | deep}
@@ -31,6 +35,18 @@ pending
 
 **Context from dependencies:** {Prose summary of what the dependency tasks produce that this task needs. For example: "task-01-setup-database.md creates the PostgreSQL schema with users and sessions tables. This task builds the API routes that query those tables." This is what makes each file self-contained — the agent does not need to read other task files to understand its inputs.}
 
+## Risk
+
+{Only when the task touches a high/critical file and risk.enabled is on; otherwise write "None".}
+
+- `path/to/file.ts`: {score} {tier}. Past failures: {what the fix commits show keeps breaking}. Test: {the test in Tests aimed at it}
+
+## Project Context
+
+{Only the 3–5 lines from the project context (CONTEXT.md / context/<area>.md, via the investigation's Relevant Context) that apply to THIS task: conventions, pitfalls, off-limits areas. The coder never reads the context files itself. Write "None" if nothing applies.}
+
+- {e.g. Errors go through `AppError` (`src/lib/errors.ts:8`); never throw raw strings.}
+
 ## Files to Create
 
 - `path/to/new-file.ts` — {Brief purpose}
@@ -87,6 +103,8 @@ pending
 - The **Dependencies** section includes prose context (not just filenames) so the agent understands its inputs without reading other files. This is the most important part of making task files self-contained.
 - **Files to Create** and **Files to Modify** make the task's scope explicit. Tasks in the same batch should not overlap on these lists.
 - **Technical Details** captures everything from the planning conversation — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. If it was discussed during planning and is relevant to this task, it belongs here.
+- **Covers** links the task to requirement numbers, so nothing in requirements.md is left without a task.
+- **Project Context** carries just the conventions this task needs. Copy lines; don't link to CONTEXT.md, because parallel coders reading the whole context would multiply the token cost.
 - **Complexity** comes from `complexity-rubric.md`. `spec-implement` picks the coder's model from this tier, so rate honestly: under-rating a risky task is the expensive mistake.
 - **Tests** names the tests the coder writes alongside the code. A behavioural acceptance criterion without a matching test is a gap — add the test or explain why it can only be checked by `spec-verify`.
 - **Acceptance Criteria** should be specific enough that completion can be verified objectively (by a code review agent or a human).

package/{skills → plugin/skills}/spec-implement/SKILL.md

@@ -38,6 +38,20 @@ isn't, detect what this skill needs from the repo, ask about anything ambiguous,
 the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
 `specs_dir`).
 
+## Project context and memory
+
+- **Start cheap.** Read the README's **Resume here** block first. Read the last ~20 lines of
+  `log.md` only if that isn't enough. You, the orchestrator, read `{specs_dir}/CONTEXT.md` once,
+  because its **Conventions** and **Off-limits** apply to your own work too: commit messages and
+  trailers, branches, files nobody may touch. Coders don't read it. Each task file's **Project
+  Context** already carries what its coder needs. Open one `context/<area>.md` only when a review
+  finding depends on a convention the task file doesn't state.
+- **Log as you go.** Append 1–3 lines to `log.md` for each decision, deviation from the spec, user
+  answer, review finding and fix, or failed approach. Skip routine progress.
+- **Before stopping for any reason** (batch done, failure, user stop, run-through gate), overwrite
+  **Resume here** with the stage, next action, open questions, and last commit. A new or compacted
+  session must be able to continue from that block alone.
+
 ## Orchestration Model
 
 This skill's parallelism assumes your host can run multiple independent agents at once —
@@ -209,12 +223,14 @@ After the batch passes review (or the user chooses to proceed):
 
 1. **Update task files**: for each completed task, change the Status field from `pending` to `complete`
 2. **Update README.md**: change `- [ ]` to `- [x]` for each completed task
-3. **Commit the batch**:
+3. **Update memory**: append a log entry (what this batch decided or changed from the spec) and
+   overwrite the README's **Resume here** (`Stage: batch {N}/{total} done`, `Next: …`).
+4. **Commit the batch**:
    ```
    git add -A
    git commit -m "feat({feature}): complete batch {N} — {brief summary}"   # or the config's git.commit_style
    ```
-4. **Report batch completion**:
+5. **Report batch completion**:
    ```
    Batch {N} of {total} complete.
 
@@ -254,7 +270,7 @@ Next steps:
 
 ## Run-through mode (after approval)
 
-Run-through applies when the user asks for it ("approved, run it through", "build, verify and
+Run-through applies when the user asks for it ("approved, run it through", "build, verify, review and
 commit it") or when `.spec-driven.yml` has `pipeline.after_approval: run-through` and the user has
 approved the spec. In that case, don't stop after Step 9. Continue:
 
@@ -262,16 +278,18 @@ approved the spec. In that case, don't stop after Step 9. Continue:
 Run-through progress:
 - [ ] Implement all batches (Steps 1–9) — every review gate passed
 - [ ] Verify — follow the spec-verify skill; every acceptance criterion PASS
+- [ ] Review — follow the spec-review skill; no blockers (should-fix items are listed, not blocking)
 - [ ] Checkpoint — follow the spec-checkpoint skill; every check passes, commit made
 - [ ] Stop and hand off to spec-ship
 ```
 
 1. **Gate on each stage.** Move on only if the previous stage fully passed. On any failure (a review
-   gate exhausted its 3 cycles, a criterion FAILed or was SKIPPED, a check failed), stop the
+   gate exhausted its 3 cycles, a criterion FAILed or was SKIPPED, spec-review found a blocker, a
+   check failed), stop the
    run-through and report where it stopped, why, and the command to resume (e.g. "fix X, then say
    'continue the run-through'").
-2. **Verify, then checkpoint.** Follow those skills' own instructions in full, including the
-   verification report. Don't shortcut them because you're running them in sequence.
+2. **Verify, review, then checkpoint.** Follow those skills' own instructions in full, including
+   the verification report and review.md. Review fixes still need the user's yes. Don't shortcut them because you're running them in sequence.
 3. **Never push.** The run-through ends at a local commit. Finish with the summary below and ask
    whether to run `spec-ship`. `spec-ship` still shows exactly what will be pushed and waits for a
    yes.
@@ -282,6 +300,7 @@ Run-through progress:
 Run-through complete for "{feature}":
 - Implement: {N} batches, all review gates PASS
 - Verify: {P}/{P} criteria PASS (specs/{feature}/verification-report.md)
+- Review: 0 blockers · {S} should-fix · {N} nits (specs/{feature}/review.md)
 - Checkpoint: {commit hash} — {subject}
 
 Ready to push and open a PR. Run spec-ship? (it will show exactly what gets pushed first)

package/{skills → plugin/skills}/spec-implement/references/review-prompt-template.md

@@ -25,7 +25,8 @@ You are reviewing the combined output of Batch {batch_number} of a feature imple
    - No duplicate or conflicting definitions
    - Shared state (env vars, config) is consistent
 4. **Code Quality**: Check for security issues, performance problems, and adherence to project conventions.
-5. **Scope**: Verify each task stayed within its defined scope (Files to Create/Modify). Flag any unexpected file changes.
+5. **Risk**: for every task with a filled **Risk** section, check the code handles the past failure pattern it names, and that the test aimed at it exists and would fail without the fix.
+6. **Scope**: Verify each task stayed within its defined scope (Files to Create/Modify). Flag any unexpected file changes.
 
 ## Verdict
 

package/{skills → plugin/skills}/spec-investigate/SKILL.md

@@ -8,9 +8,9 @@ description: >
   plan it", or hands over any of those inputs and wants the
   system understood (current behaviour, root cause, affected repos/files, risks, open
   questions) rather than fixed or built yet. This is the first stage of the
-  investigate → create → (human approval) → implement → verify → ship pipeline — it hands off
+  investigate → create → (human approval) → implement → verify → review → ship pipeline — it hands off
   to the existing spec-create skill and does not replace, duplicate, or invoke spec-create,
-  spec-implement, spec-verify, or spec-ship itself. Ticket-agnostic: works for bugs, features,
+  spec-implement, spec-verify, spec-review, or spec-ship itself. Ticket-agnostic: works for bugs, features,
   refactors, security, performance, infra, or cross-repository tickets in any repo.
 license: MIT
 ---
@@ -22,11 +22,11 @@ Discover and record the facts. Do not design the fix and do not write any code.
 This skill is stage 1 of:
 
 ```
-spec-investigate → spec-create → human approval → spec-implement → spec-verify → spec-ship
+spec-investigate → spec-create → human approval → spec-implement → spec-verify → spec-review → spec-checkpoint → spec-ship
 ```
 
-`spec-create`, `spec-implement`, `spec-verify`, and `spec-ship` already exist elsewhere (e.g. the
-`spec-driven-dev` plugin, or whatever equivalent this host provides). **Never create, redesign,
+`spec-create`, `spec-implement`, `spec-verify`, `spec-review`, and `spec-ship` already exist elsewhere (e.g. the
+`ticket-to-pr` plugin, or whatever equivalent this host provides). **Never create, redesign,
 duplicate, or invoke those skills from here.** Your only output is an investigation report plus a
 ready-to-use work branch; a human decides when to run `spec-create` next.
 
@@ -45,6 +45,42 @@ isn't, detect what this skill needs from the repo, ask about anything ambiguous,
 the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
 `specs_dir`).
 
+## Project context (read before investigating)
+
+Cheap sources first, code second:
+
+1. Read `{specs_dir}/CONTEXT.md`, the index of 60 lines or fewer, or run
+   `spec-driven-dev context`. Pick the areas this work touches and read only those
+   `context/<area>.md` files (`spec-driven-dev context --areas=billing,api`). Never load
+   `context/archive.md`.
+2. **Optional graph.** If `context.graph` isn't `off` and graphify is available
+   (`graphify-out/graph.json` exists or `graphify` is on the PATH), map the system with
+   `graphify query "<topic>" --budget 1500` and `graphify path "<A>" "<B>"` before grepping. Treat
+   INFERRED or AMBIGUOUS edges as hints. Never install it.
+3. **Context is a lead, not evidence.** Verify it against the code like any other source. Where the
+   code contradicts it, record that under **Relevant Context → Context corrections**. Don't edit
+   CONTEXT.md from here.
+4. Copy the 10–20 lines that apply into the report's **Relevant Context** section. That digest is
+   what later stages use, so they don't reload the context files.
+
+No CONTEXT.md? Investigate as usual, and suggest running `spec-setup` afterwards to create one.
+
+## Risk signal (GitRisk)
+
+Use it only when `.spec-driven.yml` has `risk.enabled: on`, or has no `risk:` block, **and**
+`{specs_dir}/context/risk.md` exists. If `risk.enabled: off`, ignore risk entirely: don't read the
+file, compute scores, or mention risk. That keeps on/off comparisons (`spec-driven-dev risk-eval`)
+clean.
+
+1. Once you know the change surface, look up its files: `spec-driven-dev risk --files=a,b` (or
+   `npx -y @benjaminthomas/spec-driven-dev risk --files=…`), or find them in `risk.md`. Without the
+   CLI, approximate a file's history with `git log --since="2 years ago" --format=%s -- <file>`.
+2. For each **high** or **critical** file in the surface, look harder: read its last ~10 commit
+   subjects and the diffs of its last 1–2 fix commits, and check its dependents. Write what keeps
+   breaking there in the report's **Risk Hotspots** section.
+3. A score is a reason to look harder, never evidence. Hotspot findings still need their
+   VERIFIED / INFERRED labels.
+
 ## Invocation
 
 ```
@@ -285,6 +321,10 @@ needed — this mirrors where `spec-create` already keeps its own output, so the
 naturally from the same place; don't commit this folder if the repo's convention already
 gitignores `specs/`, matching whatever this repo already does there). Use the structure in `references/report-template.md`.
 
+Number the **Potential Requirements** R1, R2… so `spec-create` and `spec-verify` can trace
+each one. Start `{specs_dir}/{feature-slug}/log.md` (append-only; template: references/log-template.md inside the installed
+`spec-create` skill folder, next to its SKILL.md, not in this repo) with one entry: the date, `spec-investigate`, and the headline finding.
+
 Every section should be specific and evidence-backed, or explicitly say "None found" /
 "Not applicable to this ticket" rather than being left looking like an oversight.
 

package/{skills → plugin/skills}/spec-investigate/references/report-template.md

@@ -16,6 +16,17 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 - Base Branch:
 - Base Commit:
 
+## Relevant Context
+<!-- 10–20 lines max: only what applies to this work, copied from specs/CONTEXT.md and context/<area>.md. spec-create passes these on to task files. -->
+- Areas: (e.g. billing, api)
+- Conventions / decisions / pitfalls that apply: (one line each, with the source)
+- Context corrections: (where the code contradicts CONTEXT.md, with evidence; or "none")
+
+## Risk Hotspots
+<!-- Only when risk.enabled is on. One row per high/critical file in the change surface; else "none" or omit. -->
+| File | Score / tier | What has broken here before (from fix commits) | What to watch in this change |
+|---|---|---|---|
+
 ## Business Context
 ## Problem Statement
 ## Expected Behaviour
@@ -45,6 +56,7 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 ### Business Decisions
 ### Technical Decisions
 ### Potential Requirements
+(Number them R1, R2… so spec-create and spec-verify can trace each one.)
 ### Proposed Solutions Discussed
 ### Open Questions
 ### Conflicts / Discrepancies