@warren-dean/code-kit 0.9.1 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "code-kit",
       "source": "./",
       "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
-      "version": "0.9.1",
+      "version": "0.10.0",
       "category": "development",
       "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
       "license": "MIT"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-kit",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
   "author": {
     "name": "Warren Langeveldt"

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
 
+## 0.10.0 (2026-10-12)
+
+An older setup is brought up to date before new work starts, and a security reviewer checks the changes that need one.
+
+- **The gaps stop new work until init fills them.** For a project set up by an older init, `code-kit next` names what it's missing: a design gate for the lanes that build screens, design stories before the screen stories not yet started, a QA lane, and a security reviewer. Work already started goes on through review and merge; nothing new starts. Once nothing is in flight, `next` gives `update`, and the loop has the lead re-run `/code-kit:init`, which shows you the difference first.
+- **An adversarial security reviewer.** spec-design writes a short threat model for each spec (what's sensitive, who might attack it, the trust boundaries) and security requirements stories can cite. init writes a read-only `security-reviewer` agent. `code-kit security` says whether a branch touches sign-in, permissions, outside input, personal data, encryption, payments, secrets or dependencies, and where; when it does, the review runs the security reviewer, which reports only findings with a concrete attack path. A blocker sends the branch back like a failing test.
+- **Setup version 3.** Re-running init records `"setup": 3`.
+
 ## 0.9.1 (2026-10-12)
 
 Team mode, run against a real GitHub repository. It's still a preview.

package/README.md

@@ -184,7 +184,7 @@ spec-design works an idea into a specification with you before any code exists.
 1. **Frame:** the problem, the users, the outcome, the constraints and the non-goals.
 2. **Explore:** two or three different shapes of solution, the main user journeys, and the riskiest assumptions. You choose.
 3. **Scope:** capability areas, and what the first release has to deliver end to end.
-4. **Specify:** one spec per area, with numbered, testable requirements covering data, states, rules, permissions, errors and acceptance criteria.
+4. **Specify:** one spec per area, with numbered, testable requirements covering data, states, rules, permissions, errors and acceptance criteria, and a short threat model with the security requirements that answer it.
 5. **Architecture, principles and plan:** the layers, contracts, recipes for each layer's common additions (they become the lane agents' skills), definition of done, and stories split into lanes, with a design story before the screens of each area that has any.
 6. **Check:** every journey maps to requirements and every requirement to a story, with no gaps left as "TBD".
 
@@ -200,7 +200,7 @@ Requirements are headings (`### BOOK-4 Cancel a booking`). Stories are `### ST-1
 
 - **A new build:** init reads the docs in full: the architecture and layer map, the plan or work split, and the principles. It drafts the rules from them.
 - **An existing codebase (brownfield):** the docs can be thin or missing. Init works the layers out from the code: which folders import which, and who works where according to the git history. It also runs each check once and flags any that already fail, so you decide what to do with them.
-- **Either way:** you get a draft (`.claude/code-kit.draft.json`), one agent per lane with its project skills (one per recipe, in the same approval), the design gate for lanes that own screens, a CLAUDE.md section and a list of questions (see [The agents and skills it creates](#the-agents-and-skills-it-creates)). Nothing is enforced until you approve and the draft becomes `.claude/code-kit.json`.
+- **Either way:** you get a draft (`.claude/code-kit.draft.json`), one agent per lane with its project skills (one per recipe, in the same approval), a read-only security reviewer, the design gate for lanes that own screens, a CLAUDE.md section and a list of questions (see [The agents and skills it creates](#the-agents-and-skills-it-creates)). Nothing is enforced until you approve and the draft becomes `.claude/code-kit.json`.
 
 **Existing violations.** Brownfield code usually breaks some layer rules already. On approval, `baseline --write` records them in `.claude/code-kit.baseline.json`:
 
@@ -220,7 +220,8 @@ code-kit ships no fixed team. Init writes one for each project, from its docs or
 ├── agents/
 │   ├── web-engineer.md    # one lane agent per lane
 │   ├── api-engineer.md
-│   └── db-engineer.md
+│   ├── db-engineer.md
+│   └── security-reviewer.md  # reads every sensitive change as an attacker would; owns nothing
 └── skills/
     └── new-migration/     # project recipes, only the ones you approve
         └── SKILL.md
@@ -266,6 +267,8 @@ Editing an agent file can't loosen a rule. And the agent files are kit files (`.
 5. The stop hook runs the checks before the agent can finish.
 6. Review compares the branch with the requirements and the report, and `verify` checks the rules again in CI.
 
+**The security reviewer** (`.claude/agents/security-reviewer.md`, from `templates/security-reviewer.md`) is a reviewer, not a lane: it owns no paths and checks everyone's work. Init writes it whenever the product handles sign-in, personal data, payments, input from outside or secrets, which is nearly always. It only reads (Read, Grep, Glob, and Bash for `git diff` and the project's audit commands), and the hooks hold it to that like any subagent outside the lanes. spec-design gives each spec a short threat model (what's sensitive, who might attack it, the trust boundaries) and security requirements stories cite. When `code-kit security` says a story's change touches something sensitive, the review runs the agent on the diff against those threat models: it attacks authentication and authorisation, injection (prompt injection too), data exposure, secrets, cryptography, SSRF and redirects, deserialisation, new dependencies and the privacy targets, and grades each finding blocker, concern or nit, with where, the attack and the fix. A blocker sends the branch back like a failing test.
+
 **Project skills** (`.claude/skills/<recipe>/SKILL.md`) are the step-by-step recipes your docs describe, like "add a migration" or "add an endpoint". Init lists the ones it finds and writes them only if you say yes, never as empty stubs. Each is listed in the owning lane agent's "Skills to use". Like the agents, they're kit files: the lead maintains them, and changes are logged.
 
 **Kept in step.** When the project changes (a new app, a new lane, moved folders), re-run `/code-kit:init`. It drafts new agents for new lanes and updates the paths of existing ones, keeping anything written by hand. You see the difference and approve it before anything changes.
@@ -349,6 +352,7 @@ code-kit diff --config .claude/code-kit.draft.json  # what a draft changes
 code-kit baseline [--write] # layer violations in the code as it is
 code-kit graph [--depth N]  # which folders import which
 code-kit verify [--base ref] [--branch name] [--no-checks] [--json]  # a branch's changes, for CI and review
+code-kit security [--base ref] [--branch name] [--json]  # whether a branch needs the security review, and why: sign-in, permissions, outside input, personal data, payments, secrets, dependencies
 code-kit status [--base ref] [--json]  # stories and requirements against the spec
 code-kit next [--base ref] [--json]    # the step to take now, from the project's state
 code-kit trace <path>... [--json]      # what a file is for: requirements, lane, layer rules
@@ -410,7 +414,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pan
 | `adapters`                     | no                | `{ "<adapter>": false }` switches off an adapter that would otherwise be detected; `true` says the project wants that tool, so until it's set up here `next` gives its setup before any code. See [Adapters](#adapters).                                                                                                                                                                                                                                                                                                                                                                                    |
 | `approvals.lead`               | no                | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals).                                                                                                                                                                                                                                                                                                                                                |
 | `approvals.delegate`           | no                | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: approvals the lead may grant on its own, with `code-kit approve --delegated`, and with `merge`, merges into a protected branch with `code-kit merge --delegated`. Dependencies are checked against the npm registry; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals).                                                  |
-| `setup`                        | no                | The version of init's setup the project has (2 now). Without it, or lower, `next` names what re-running init adds: project skills with the lane agents, the design gate, a QA lane, and companions set up first                                                                                                                                                                                                                                                                                                                                                                                             |
+| `setup`                        | no                | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it                                                                                                                                                                                                                                                                                                                                                  |
 | `team`                         | no                | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default) or `{ command }` for another team provider. See docs/specs/16-teams.md. |
 | `branches.protected`           | no                | Default `["main", "master"]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `harness`                      | no                | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 10; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (default the session's), and `background.pauseAtPercent` (default 80). Change them with `/harness` or `code-kit settings set`.                                                                                              |

package/bin/code-kit.mjs

@@ -8,6 +8,8 @@
 //   graph [--depth N]     which folders import which (to find the layers in existing code)
 //   verify [--base ref] [--branch name] [--no-checks]
 //                         the rules for everything this branch changed since base (for CI and review)
+//   security [--base ref] [--branch name] [--json]
+//                         whether a branch's changes need the security reviewer, and why (ONB-7)
 //   status [--base ref] [--json]
 //                         each story and requirement in the plan: built, in review, ready, blocked, tested
 //   adapters              other tools detected in the project, what each adds to the rules, and its setup
@@ -52,6 +54,12 @@ import { nextStep } from '../hooks/lib/next.mjs';
 import { traceFile } from '../hooks/lib/trace.mjs';
 import { buildStatus, specCheckRows } from '../hooks/lib/plan.mjs';
 import { recordSentBack } from '../hooks/lib/reviews.mjs';
+import {
+  SECURITY_AGENT,
+  SECURITY_AGENT_FILE,
+  reasonsInWords,
+  securityReview,
+} from '../hooks/lib/security.mjs';
 import { storyTimes } from '../hooks/lib/timeline.mjs';
 import { PROJECT, projectMap, storyMap, trail } from '../hooks/lib/storymap.mjs';
 import { journal } from '../hooks/lib/journal.mjs';
@@ -1063,6 +1071,39 @@ function verify() {
   out('No problems.');
 }
 
+/**
+ * ONB-7: whether a branch's changes need the security reviewer, and why: sign-in, permissions, outside
+ * input, personal data, encryption, payments, secrets, commands built from strings, new dependencies,
+ * or a security requirement the story cites.
+ */
+function security() {
+  const { config } = load();
+  const from = base(config, false);
+  let branch = branchName;
+  if (!branch) {
+    try {
+      branch = currentBranch('.');
+    } catch {
+      die('This checkout has no branch; pass --branch <name>.');
+    }
+  }
+  if (!refExists(branch)) die(`--branch ${branch} is not a known branch.`);
+  const found = securityReview(resolve('.'), { base: from, branch, config });
+  if (flag('--json')) return out(JSON.stringify({ base: from, ...found }, null, 2));
+  const what = found.story ? `${found.story} on ${branch}` : branch;
+  if (!found.needed)
+    return out(
+      `${what} needs no security review: against ${from}, it touches no sign-in, permissions, outside input, personal data, encryption, payments or secrets, adds no dependencies and cites no security requirement.`,
+    );
+  out(`${what} needs the security review. Against ${from}, it touches:`);
+  for (const r of found.reasons) out(`  ${reasonsInWords([r])}`);
+  out(
+    found.agent
+      ? `\nRun the ${SECURITY_AGENT} agent on the diff (git diff ${from}...${branch}) with the story's specs and their threat models. A blocker it finds sends the branch back, like a failing test.`
+      : `\nThis project has no ${SECURITY_AGENT} agent (${SECURITY_AGENT_FILE}). Re-run /code-kit:init to add it; until then, review the diff as an attacker would yourself, against the specs' threat models.`,
+  );
+}
+
 const pad = (s, n) => String(s).padEnd(n);
 
 function status() {
@@ -1521,6 +1562,7 @@ const commands = {
   adapters,
   next,
   verify,
+  security,
   status,
   unowned,
   diff,
@@ -1532,6 +1574,7 @@ function usage() {
   die(
     'Usage: code-kit check | who <path>... | unowned | diff | baseline [--write] | graph [--depth N]\n' +
       '              | verify [--base ref] [--branch name] [--no-checks] | status [--base ref] [--json]\n' +
+      '              | security [--base ref] [--branch name] [--json]\n' +
       '              | next [--base ref] [--json] | adapters | trace <path>... [--json]\n' +
       '              | approve <name>... --reason "…" [--lane name]   [--config file]\n' +
       '              | merge <branch> --delegated|--person [--into branch] | requests [--json]\n' +

package/hooks/lib/config.mjs

@@ -143,10 +143,11 @@ const isRegExp = (v) => {
 
 /**
  * ONB-5: the version of init's setup. 2 adds project skills with the lane agents, the design gate for
- * lanes with screens, a QA lane for end-to-end tests, and companions set up before coding (spec 17). A
- * project set up before (no `setup`, or a lower one) is told what re-running init adds.
+ * lanes with screens, a QA lane for end-to-end tests, and companions set up before coding; 3 adds the
+ * security reviewer (ONB-7, spec 17). A project set up before (no `setup`, or a lower one) is told what
+ * re-running init adds.
  */
-export const SETUP_VERSION = 2;
+export const SETUP_VERSION = 3;
 
 /** Every problem with a parsed config, as readable sentences; empty when it is valid. */
 export function validate(c) {

package/hooks/lib/next.mjs

@@ -9,6 +9,8 @@ import { buildStatus, readStories, DESIGN, LEAD } from './plan.mjs';
 import { pendingSetup } from './adapters/index.mjs';
 import { CONFIG_FILE, SETUP_VERSION } from './config.mjs';
 import { readQueue, waiting } from './queue.mjs';
+import { laneOf } from './rules.mjs';
+import { SECURITY_AGENT_FILE } from './security.mjs';
 
 export const DRAFT_FILE = '.claude/code-kit.draft.json';
 export const BRIEF_STATES = ['framed', 'explored', 'scoped', 'specified', 'planned', 'ready'];
@@ -149,11 +151,17 @@ export function nextStep(root, base) {
   }
   const [setup] = pendingSetup(raw, root);
   if (setup) return result('setup', setup.why, { args: setup.skill });
-  // ONB-5: a project set up before setup did all of this is told what re-running init adds.
-  if ((raw?.setup ?? 1) < SETUP_VERSION)
+  // ONB-5: a project set up before setup did all of this is told what re-running init adds; when
+  // ONB-6 finds what it's missing, no new story starts until init has added it.
+  const older = (raw?.setup ?? 1) < SETUP_VERSION;
+  const gaps = older ? setupGaps(config, readStories(root, plan), files) : [];
+  if (older && !gaps.length)
     attention.push(
-      "This project's code-kit setup predates what init now sets up: project skills with each lane agent, designs approved before screens are built, a QA lane for end-to-end tests, and companion tools set up before coding. Re-run /code-kit:init to add what's missing; it keeps everything that's still right and shows you the difference first.",
+      "This project's code-kit setup predates what init now sets up: project skills with each lane agent, designs approved before screens are built, a QA lane for end-to-end tests, a security reviewer that checks each sensitive change as an attacker would, and companion tools set up before coding. Re-run /code-kit:init to add what's missing; it keeps everything that's still right and shows you the difference first.",
     );
+  const missingWords = gaps.length
+    ? `This project's setup is missing what init now sets up: ${gaps.join('; ')}.`
+    : '';
   // ONB-1: a lane agent naming a skill that doesn't exist works without the recipe it was given.
   for (const missing of missingSkills(root)) attention.push(missing);
 
@@ -194,6 +202,16 @@ export function nextStep(root, base) {
   // ONB-2: design stories, designed with the person before any screen that depends on them is built.
   const forDesign = readyStories.filter((s) => buildable(s) && s.lane === DESIGN).map((s) => s.id);
   const unbuildable = readyStories.filter((s) => !buildable(s)).map((s) => s.id);
+  // ONB-6: work already started finishes; nothing new starts until init has filled the gaps.
+  const held = gaps.length
+    ? [...ready, ...forDesign, ...forLead].sort((a, b) => a.slice(3) - b.slice(3))
+    : [];
+  if (held.length) {
+    ready.length = forDesign.length = forLead.length = 0;
+    attention.push(
+      `${missingWords} ${held.join(', ')} ${held.length === 1 ? 'waits' : 'wait'} until /code-kit:init has added it.`,
+    );
+  }
   if (unbuildable.length)
     attention.push(
       `${unbuildable.join(', ')} can't be dispatched until the plan's gaps are fixed.`,
@@ -262,6 +280,12 @@ export function nextStep(root, base) {
       `${forLead.join(', ')} ${forLead.length === 1 ? 'is' : 'are'} the lead's own: build ${forLead.length === 1 ? 'it' : 'them'} on ${forLead.map((id) => `lead/${id.toLowerCase()}`).join(', ')}, then review like any branch.`,
       { args: forLead.join(' ') },
     );
+  // ONB-6: with nothing in flight, the setup is brought up to date before the next story.
+  if (gaps.length && !building.length && !queued.length)
+    return result(
+      'update',
+      `${missingWords} Re-run /code-kit:init before the next story: it shows the person the difference before anything changes.`,
+    );
   if (building.length)
     return result(
       'wait',
@@ -294,6 +318,66 @@ export function nextStep(root, base) {
   );
 }
 
+const SCREEN_LANE = /(^|-)(web|mobile|frontend|front-end|ui|desktop|ios|android|admin|portal)(-|$)/;
+const SCREEN_FILE = /\.(tsx|jsx|vue|svelte|swift|dart)$/;
+const TEST_FILE = /(^|\/)(__tests__|e2e|tests?)\/|\.(test|spec|stories)\.\w+$/;
+const QA_LANE = /(^|-)(qa|e2e|tests?)(-|$)/;
+
+/**
+ * ONB-6: what a setup older than init's is missing, in words, from the config, the plan and the code.
+ * A lane owns screens when its name or agent says so (web, mobile, desktop…) or it holds screen
+ * files. It's missing the design gate, design stories before the screen stories not yet started, and a
+ * QA lane for the end-to-end suites; and, with or without screens, the security reviewer (ONB-7), when
+ * its agent file isn't among the tracked files.
+ */
+export function setupGaps(config, stories, files = []) {
+  const gaps = screenGaps(config, stories, files);
+  if (!files.includes(SECURITY_AGENT_FILE))
+    gaps.push(
+      `a security reviewer (${SECURITY_AGENT_FILE}) that checks each change touching sign-in, permissions, personal data, payments, secrets or dependencies as an attacker would`,
+    );
+  return gaps;
+}
+
+/** ONB-6: the gaps of a setup whose lanes own screens: the design gate, design stories, a QA lane. */
+function screenGaps(config, stories, files) {
+  const lanes = Object.entries(config.lanes);
+  const holdsScreens = new Set(
+    files.filter((f) => SCREEN_FILE.test(f) && !TEST_FILE.test(f)).map((f) => laneOf(f, config)),
+  );
+  const screens = lanes
+    .filter(
+      ([name, l]) => SCREEN_LANE.test(name) || SCREEN_LANE.test(l.agent) || holdsScreens.has(name),
+    )
+    .map(([name]) => name);
+  if (!screens.length) return [];
+  const gaps = [];
+  const list = (names) => names.join(', ').replace(/, ([^,]*)$/, ' and $1');
+  if (!config.designGate)
+    gaps.push(
+      `a design gate for ${list(screens)}, so screens are built only from approved designs`,
+    );
+  // A screen story not yet started, with no design story among everything it depends on.
+  const byId = new Map(stories.map((s) => [s.id, s]));
+  const designed = (s, seen = new Set()) =>
+    s.dependsOn.some((d) => {
+      if (seen.has(d)) return false;
+      seen.add(d);
+      const dep = byId.get(d);
+      return dep && (dep.lane === DESIGN || designed(dep, seen));
+    });
+  const undesigned = stories
+    .filter((s) => screens.includes(s.lane) && ['todo', 'ready'].includes(s.status) && !designed(s))
+    .map((s) => s.id);
+  if (undesigned.length)
+    gaps.push(
+      `design stories before the screens: ${list(undesigned)} ${undesigned.length === 1 ? 'is' : 'are'} planned with no design to build from`,
+    );
+  if (!lanes.some(([name, l]) => QA_LANE.test(name) || QA_LANE.test(l.agent)))
+    gaps.push('a QA lane with a test-engineer for the end-to-end tests of the journeys');
+  return gaps;
+}
+
 /** The code-kit skills every agent may name without a project copy. */
 const KIT_SKILLS = (() => {
   try {

package/hooks/lib/plan.mjs

@@ -20,7 +20,8 @@ export const DESIGN = 'design';
 const TEST =
   /(^|\/)(tests?|__tests__|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
 
-const markdownFiles = (root, path) => {
+/** The markdown files at `path`: the file itself, or every one under the folder, sorted. */
+export const markdownFiles = (root, path) => {
   const full = join(root, path);
   if (!existsSync(full)) return [];
   if (statSync(full).isFile()) return path.endsWith('.md') ? [path] : [];

package/hooks/lib/security.mjs

@@ -0,0 +1,180 @@
+// ONB-7: which branches the security reviewer looks at. Security is a reviewer, not a lane: it owns no
+// paths and checks everyone's work. A story's change gets the security review when it touches sign-in,
+// permissions, outside input, personal data, encryption, payments, secrets or commands built from
+// strings, adds dependencies, or cites a requirement from a spec's `## Security requirements`. Read
+// from git (base...branch): the files changed and the lines added, tests and docs left out.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDependencyFile } from './dependencies.mjs';
+import { markdownFiles, readStories } from './plan.mjs';
+import { storyOfBranch } from './teamfacts.mjs';
+
+export const SECURITY_AGENT = 'security-reviewer';
+export const SECURITY_AGENT_FILE = `.claude/agents/${SECURITY_AGENT}.md`;
+
+// Tests, docs and design files describe the change; the review looks at the code that ships.
+const NOT_SHIPPED =
+  /(^|\/)(tests?|__tests__|e2e|docs?|design)\/|\.(test|spec|stories)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$|\.(md|mdx|txt|png|jpe?g|gif|svg|webp)$/i;
+
+/**
+ * What makes a change sensitive, by kind: `path` matches a changed file's path, `code` (one pattern or
+ * several) an added line.
+ * Each kind reads as the reason a person is given.
+ */
+export const SENSITIVE = [
+  {
+    kind: 'sign-in',
+    why: 'sign-in or sessions',
+    path: /(^|[/_.-])(auth\w*|login|logout|sign-?in|sign-?up|sessions?|oauth|sso|jwt|passwords?|mfa|otp)([/_.-]|$)/i,
+    code: /\b(signIn|signOut|login|logout|getSession|setSession|jwt\.(sign|verify)|jsonwebtoken|passport\.|bcrypt|argon2|verifyPassword|hashPassword|Set-Cookie|cookies\(\)|httpOnly)\b/,
+  },
+  {
+    kind: 'permissions',
+    why: 'permissions',
+    path: /(^|[/_.-])(permissions?|roles?|rbac|acl|polic(y|ies)|guards?|middleware|authori[sz]\w*)([/_.-]|$)/i,
+    code: [
+      /\b(isAdmin|hasRole|hasPermission|can[A-Z]\w*|[Aa]uthori[sz]e\w*|requireRole)\b/,
+      /\b(enable row level security|create policy|grant\s+\w+\s+on)\b/i,
+    ],
+  },
+  {
+    kind: 'input',
+    why: 'input from outside (requests, forms, uploads, webhooks)',
+    path: /(^|[/_.-])(webhooks?|uploads?|handlers?)([/_.-]|$)|(^|\/)(api|routes?)\/|(^|\/)route\.[jt]s$/i,
+    code: /\b(req\.(body|query|params|files?)|request\.(json|form|args|body)\(?|formData\(\)|searchParams|FormData|multer|busboy|ctx\.request\.body|@Body\(|@Query\(|@Param\()/,
+  },
+  {
+    kind: 'personal data',
+    why: 'personal data',
+    path: /(^|[/_.-])(users?|profiles?|accounts?|customers?|patients?|members?|children|students?|contacts?)([/_.-]|$)/i,
+    code: /\b(email|phone(_?number)?|date_?of_?birth|dob|home_?address|street_?address|passport|tax_?file|national_?id|medicare|ssn|first_?name|last_?name|full_?name)\b/i,
+  },
+  {
+    kind: 'encryption',
+    why: 'encryption, hashing or random values',
+    path: /(^|[/_.-])(crypto|encrypt\w*|decrypt\w*|ciphers?|hash(ing)?|keys?|kms|signing)([/_.-]|$)/i,
+    code: /\b(createCipheriv|createDecipheriv|createHash|createHmac|randomBytes|Math\.random|crypto\.subtle|md5|sha1|AES|RSA|hashlib|Fernet)\b/,
+  },
+  {
+    kind: 'payments',
+    why: 'payments',
+    path: /(^|[/_.-])(payments?|billing|checkout|invoices?|stripe|subscriptions?|refunds?|payouts?|wallet)([/_.-]|$)/i,
+    code: /\b(stripe|paymentIntent|checkout\.sessions|charge|refund|payout|amount_?cents)\b/i,
+  },
+  {
+    kind: 'secrets',
+    why: 'secrets or credentials',
+    path: /(^|\/)\.env(\.|$)|(^|[/_.-])(secrets?|credentials?|tokens?)([/_.-]|$)/i,
+    code: /\b(api_?key|secret_?key|client_?secret|private_?key|access_?token|refresh_?token|password\s*[:=])/i,
+  },
+  {
+    kind: 'injection',
+    why: 'queries, commands, templates or redirects built from strings',
+    code: /(\$queryRawUnsafe|\$executeRawUnsafe|\.raw\(|sql\.unsafe|execute\(\s*[`'"]?\s*(select|insert|update|delete)\b.*(\$\{|\+)|child_process|\bexec(Sync)?\(|\bspawn(Sync)?\(|subprocess\.|os\.system|\beval\(|new Function\(|dangerouslySetInnerHTML|\.innerHTML\s*=|v-html|\{\{\{|pickle\.loads|yaml\.load\(|unserialize\(|res\.redirect\(|redirect\(\s*(req|request|params|searchParams)|fetch\(\s*(req|request|params|body|url)\b)/i,
+  },
+];
+
+/**
+ * The requirement IDs of each spec's `## Security requirements` section (spec-design writes a spec's
+ * security requirements there, as `### AREA-n` headings like any other requirement).
+ */
+export function securityRequirementIds(texts) {
+  const ids = new Set();
+  for (const text of texts) {
+    let inSecurity = false;
+    for (const line of text.split('\n')) {
+      if (/^##\s/.test(line)) inSecurity = /^##\s+Security requirements\b/i.test(line);
+      const m = inSecurity && line.match(/^###\s+((?!ST-)[A-Z][A-Z0-9]*-\d+)\b/);
+      if (m) ids.add(m[1]);
+    }
+  }
+  return ids;
+}
+
+/** Added lines of a unified diff (`git diff -U0`): [{ file, line, text }]. */
+export function addedLines(diff) {
+  const added = [];
+  let file = null;
+  let line = 0;
+  for (const l of diff.split('\n')) {
+    if (l.startsWith('+++ ')) {
+      file = l === '+++ /dev/null' ? null : l.slice(4).replace(/^b\//, '');
+      continue;
+    }
+    const hunk = l.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunk) {
+      line = Number(hunk[1]);
+      continue;
+    }
+    if (!file) continue;
+    if (l.startsWith('+')) added.push({ file, line: line++, text: l.slice(1) });
+    else if (l.startsWith(' ')) line++;
+  }
+  return added;
+}
+
+const examples = (list) =>
+  `${list.slice(0, 3).join(', ')}${list.length > 3 ? ` and ${list.length - 3} more` : ''}`;
+
+/**
+ * Why a change needs the security review, in words, one per kind: [{ kind, why, where: [...] }].
+ * Empty when it touches nothing sensitive. `files` are the changed files, `added` the added lines,
+ * `cites` the story's requirements and `security` the IDs of the specs' security requirements.
+ */
+export function securityReasons({ files = [], added = [], cites = [], security = new Set() }) {
+  const reasons = [];
+  const shipped = files.filter((f) => !NOT_SHIPPED.test(f));
+  const lines = added.filter((a) => !NOT_SHIPPED.test(a.file));
+  for (const s of SENSITIVE) {
+    const code = [s.code].flat();
+    const where = [
+      ...(s.path ? shipped.filter((f) => s.path.test(f)) : []),
+      ...lines.filter((a) => code.some((c) => c.test(a.text))).map((a) => `${a.file}:${a.line}`),
+    ];
+    if (where.length) reasons.push({ kind: s.kind, why: s.why, where: [...new Set(where)] });
+  }
+  const deps = files.filter(isDependencyFile);
+  if (deps.length) reasons.push({ kind: 'dependencies', why: 'dependencies', where: deps });
+  const cited = cites.filter((id) => security.has(id));
+  if (cited.length)
+    reasons.push({ kind: 'requirements', why: 'security requirements it cites', where: cited });
+  return reasons;
+}
+
+/** The reasons as one sentence: "sign-in or sessions (src/auth/login.ts), dependencies (package.json)". */
+export const reasonsInWords = (reasons) =>
+  reasons.map((r) => `${r.why} (${examples(r.where)})`).join('; ');
+
+const git = (root, ...args) =>
+  execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+/**
+ * Whether `branch` needs the security review against `base`, read from git:
+ * { branch, story, needed, reasons, agent } where `agent` says whether the project has the
+ * security-reviewer agent.
+ */
+export function securityReview(root, { base, branch, config }) {
+  const range = `${base}...${branch}`;
+  const files = git(root, 'diff', '--name-only', '--no-renames', range).split('\n').filter(Boolean);
+  const added = addedLines(git(root, 'diff', '-U0', '--no-renames', '--no-color', range));
+  const story = storyOfBranch(branch);
+  const { specs, plan } = config.docs ?? {};
+  const cites =
+    (plan ? readStories(root, plan) : []).find((s) => s.id === story)?.requirements ?? [];
+  const texts = specs
+    ? markdownFiles(root, specs).map((f) => readFileSync(join(root, f), 'utf8'))
+    : [];
+  const reasons = securityReasons({ files, added, cites, security: securityRequirementIds(texts) });
+  return {
+    branch,
+    story,
+    needed: reasons.length > 0,
+    reasons,
+    agent: existsSync(join(root, SECURITY_AGENT_FILE)),
+  };
+}

package/hooks/mod/loop.mjs

@@ -3,7 +3,16 @@
 // existing skills, and the hooks judge every call as before.
 
 /** The steps the loop hands the lead; the rest (spec-design, init, check) wait for the person. */
-const LEAD_STEPS = new Set(['dispatch', 'review', 'lead', 'merge', 'rules', 'design', 'setup']);
+const LEAD_STEPS = new Set([
+  'dispatch',
+  'review',
+  'lead',
+  'merge',
+  'rules',
+  'design',
+  'setup',
+  'update',
+]);
 
 /**
  * The prompt for a step from `code-kit next --json` (LOOP-1), or null when it isn't the lead's to
@@ -27,6 +36,9 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
     return ids.length
       ? `Before any code is written, set up ${ids[0].split(':')[0]}: run /${ids[0]}. ${step.why ?? ''}`.trim()
       : null;
+  // ONB-6: an older setup brought up to date before the next story; init shows the person the diff.
+  if (step.step === 'update')
+    return `Before the next story, bring code-kit's setup up to date: run /code-kit:init. ${step.why ?? ''}`.trim();
   // ONB-2: the screens designed, and approved by the person, before they're built.
   if (step.step === 'design')
     return ids.length
@@ -61,6 +73,7 @@ export function stepLabel(step) {
       rules: 'Rules onto',
       design: 'Design',
       setup: 'Set up',
+      update: 'Update the setup',
     }[step.step] ?? step.step;
   return ids ? `${verb} ${ids}` : verb;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",

package/skills/init/SKILL.md

@@ -60,7 +60,7 @@ Write `.claude/code-kit.draft.json`. Follow `${CLAUDE_PLUGIN_ROOT}/README.md`
   - `agent`: a kebab-case agent name, for example `api-engineer`;
   - `paths` and `exclude`: every path must have exactly one owner.
 - **A QA lane:** when lanes own screens, or the plan's journeys cross lanes, a `qa` lane with a `test-engineer` agent owning the end-to-end suites (the plan's work split names them; brownfield: the folders the existing end-to-end tests live in), even if the docs forgot it. Its agent's proving command runs the suites. Add a `checks` entry for them scoped by `files` to the suites, so verify runs them when they change. Unit tests stay with each lane.
-- **`setup`:** `2`, the version of this setup, so `code-kit next` can tell an older project what re-running init adds.
+- **`setup`:** `3`, the version of this setup, so `code-kit next` can tell an older project what re-running init adds.
 - **`lead.paths`:** contracts, specs, design, root config, and anything the docs reserve for the lead.
 - **`anyActor`:** lockfiles, if lanes may update them.
 - **`protected`:** registers and contracts that need a person's sign-off, each with an `approval` name and a `why`.
@@ -102,6 +102,12 @@ Draft, alongside the config:
   - its lane rules.
   - If an agent already exists, keep its content and add only what's missing.
   - Drop the spec-check lines if the config has no `docs.specs`.
+- **A security reviewer:** write `.claude/agents/security-reviewer.md` from `${CLAUDE_PLUGIN_ROOT}/templates/security-reviewer.md`, in the same approval as the lane agents, whenever the product handles sign-in, personal data, payments, input from outside (forms, APIs, webhooks, uploads) or secrets. That's almost every product; leave it out only for one with none of these, such as a static site or a local tool with no accounts, and say why. It is a reviewer, not a lane: no entry in `lanes`, no paths, and only read-only tools (Read, Grep, Glob, and Bash for commands that change nothing), so the hooks treat it as read-only too. Fill it in from the docs (or the code, for brownfield):
+  - what's sensitive, who might attack it and the trust boundaries, from the specs' `## Threat model` sections (brownfield, or specs without one: from the data the code stores and the routes it exposes, as a question to the person);
+  - the spec files it reads;
+  - the privacy and data residency targets in the principles;
+  - the project's audit commands (for example `npm audit --omit=dev`, `pip-audit`), each run once now; leave out one that isn't installed, and say so.
+  - If the agent already exists, keep its content and add only what's missing.
 - **CLAUDE.md:** add the section from `${CLAUDE_PLUGIN_ROOT}/templates/claude-md.md`.
 - **Project skills, with the agents** (recipes like "new screen", "new migration" or "new endpoint"): one per recipe in the architecture's `## Recipes`, or any other doc that describes one step by step. Draft them now, alongside the agents, and show them in the same approval; the agents and their skills are one piece of work. Brownfield code without recipes in its docs: propose recipes from the patterns the code already follows (how its existing screens, endpoints or migrations are built), as drafts the person approves. Never write an empty one.
   - Write each as `.claude/skills/<name>/SKILL.md`, saying in its description which recipe in which doc it comes from, so an update can find it again.
@@ -110,7 +116,7 @@ Draft, alongside the config:
 Show the person:
 
 1. the layers and what each may depend on, and for brownfield the existing violations the baseline will record;
-2. the lanes, their agents and their paths;
+2. the lanes, their agents and their paths, and the security reviewer (or why it's left out);
 3. protected paths, blocked and restricted commands, and checks (including any left out because they fail today);
    and whether the lead may record approvals given in chat (`approvals.lead`), and how hands-off the build is (`harness.autonomy`);
 4. the project skills, and which lane agents use each;
@@ -144,10 +150,11 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
 
 1. **Re-read** the docs and the repository as in section 1, including the brownfield steps if the code has grown past the docs.
 2. **Draft** the whole config again into `.claude/code-kit.draft.json`, starting from the live one. Keep everything that's still right, so the diff shows only real changes. If the live config has no `harness.autonomy`, ask the person about it as in section 2.
-   A config without `"setup": 2` predates what setup now includes; add whichever of these the project is missing, as section 2 and 3 describe, and set `"setup": 2`:
+   A config without `"setup": 3` predates what setup now includes; add whichever of these the project is missing, as section 2 and 3 describe, and set `"setup": 3`:
    - project skills for the recipes in the docs (or, without recipes, the patterns the code follows), listed on the lane agents;
    - the design gate for every lane that owns screens, with its register; and design stories in the plan for screens not yet built (ask the person before adding stories);
    - the QA lane, its agent and its checks, when there are screens or journeys across lanes;
+   - the security reviewer (`.claude/agents/security-reviewer.md`), unless the product handles no sign-in, personal data, payments, outside input or secrets; and, as a proposal for the person, a threat model and security requirements for each spec that lacks them (spec-design's section 4);
    - `"adapters": { "<name>": true }` for a companion that's installed but not set up, which is then set up before any code.
 3. **Show the difference:**
 
@@ -159,7 +166,7 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
    `diff` lists lanes, layers, checks and rules that were added (`+`), removed (`-`) or changed (`~`), and how many files change owner, route by route. Explain each change in a sentence, with where it came from: the doc section, or the folder in the repository.
 
 4. **Also propose:**
-   - agent files for new lanes, and updates to agents whose paths changed;
+   - agent files for new lanes, and updates to agents whose paths changed, and to the security reviewer when the specs' threat models changed;
    - **project skills**, by reading the recipes in the docs again and comparing them with `.claude/skills/`:
      - a new skill for each recipe the docs now describe that has none;
      - an update to each skill whose recipe changed, showing what changed;

package/skills/next/SKILL.md

@@ -15,23 +15,24 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" next --json
 
 It returns `step`, `why`, `args`, `then` (steps that can follow straight after) and `attention` (things the person should know). The order it applies:
 
-| State                                                      | Step                                                      |
-| ---------------------------------------------------------- | --------------------------------------------------------- |
-| Invalid config                                             | `check`, then fix the config                              |
-| No config, a draft waiting                                 | `init`, to show it for approval                           |
-| No config, a spec still being shaped (brief not `ready`)   | `spec-design`, resuming                                   |
-| No config, a ready spec                                    | `init <docs folder>`                                      |
-| No config, existing code or docs                           | `init`                                                    |
-| Nothing at all                                             | `spec-design`                                             |
-| Config, but no specs, plan or stories                      | `spec-design`                                             |
-| A companion the config wants, not set up yet               | `setup`: run that tool's init skill (`args`), before code |
-| Stories finished on their branches                         | `review`, then `dispatch` what's ready                    |
-| Design stories ready (`**Lane:** design`)                  | `design`, then `dispatch` what needs no design            |
-| Stories ready                                              | `dispatch`                                                |
-| The lead's own stories ready (`**Lane:** lead`)            | `lead`: the lead builds them itself                       |
-| Stories being built, nothing else can start                | wait                                                      |
-| Ready stories with gaps in the plan, or a dependency cycle | `spec-design`, to fix the plan                            |
-| Every story done                                           | done: `status`, then `spec-design` for the next milestone |
+| State                                                        | Step                                                      |
+| ------------------------------------------------------------ | --------------------------------------------------------- |
+| Invalid config                                               | `check`, then fix the config                              |
+| No config, a draft waiting                                   | `init`, to show it for approval                           |
+| No config, a spec still being shaped (brief not `ready`)     | `spec-design`, resuming                                   |
+| No config, a ready spec                                      | `init <docs folder>`                                      |
+| No config, existing code or docs                             | `init`                                                    |
+| Nothing at all                                               | `spec-design`                                             |
+| Config, but no specs, plan or stories                        | `spec-design`                                             |
+| A companion the config wants, not set up yet                 | `setup`: run that tool's init skill (`args`), before code |
+| An older setup missing what init now adds, nothing in flight | `update`: re-run init, before any new story               |
+| Stories finished on their branches                           | `review`, then `dispatch` what's ready                    |
+| Design stories ready (`**Lane:** design`)                    | `design`, then `dispatch` what needs no design            |
+| Stories ready                                                | `dispatch`                                                |
+| The lead's own stories ready (`**Lane:** lead`)              | `lead`: the lead builds them itself                       |
+| Stories being built, nothing else can start                  | wait                                                      |
+| Ready stories with gaps in the plan, or a dependency cycle   | `spec-design`, to fix the plan                            |
+| Every story done                                             | done: `status`, then `spec-design` for the next milestone |
 
 Tell the person in one or two lines what you found and what you're about to run, with anything under `attention`. If `attention` says the folder isn't a git repository, run `git init` before init (spec-design doesn't need one).
 
@@ -40,6 +41,7 @@ Tell the person in one or two lines what you found and what you're about to run,
 Run the named skill with the Skill tool: `code-kit:<step>`, with `args` (and the person's argument, if they gave one). Follow that skill in full. This skill only chooses; it never does a step's work itself.
 
 - **`setup`:** run the skill named in `args` (for example `context-graph:init`); it's another plugin's, so call it by that full name.
+- **`update`:** run `code-kit:init`. `why` names what the setup is missing (the design gate, design stories, a QA lane, a security reviewer); init adds those, shows the person the difference, and sets `"setup": 3`. Until then no new story starts; work already started goes on to review and merge.
 - **`lead`:** there's no skill to run. Build each story yourself, on the branch `lead/st-<n>`: spec-check it first if it cites requirements, do the work, commit, then run `code-kit:review` on the branch like any other. A spike's result goes in the docs it names.
 - **`wait`:** say which stories are being built and on which branches, then stop. When a lane agent finishes, its notification arrives in this session; run this skill again then. If a story has been in progress with no agent running (the session ended, or the agent stopped without committing), dispatch it again.
 - **`done`:** give the `status` summary in a few lines, then offer to run spec-design for the next milestone or feature.

package/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: The lead's review of a lane's finished branch before it merges. Runs code-kit verify on the branch, checks the work against its story's requirements and acceptance criteria, the spec-check report, the approval log and the tests, and ends with merge or send back. Use when a lane agent or person finishes a story, when the person asks to review a branch or pull request, or runs /code-kit:review [branch, story ID or PR number].
+description: The lead's review of a lane's finished branch before it merges. Runs code-kit verify on the branch, checks the work against its story's requirements and acceptance criteria, the spec-check report, the approval log and the tests, runs the security reviewer on sensitive changes, and ends with merge or send back. Use when a lane agent or person finishes a story, when the person asks to review a branch or pull request, or runs /code-kit:review [branch, story ID or PR number].
 ---
 
 # Review a lane's branch
@@ -47,12 +47,27 @@ Read the story, every requirement it cites, and the full diff (`git diff <base>.
 - **Only the story:** changes beyond the story (refactors elsewhere, other stories' requirements, new dependencies) are called out. They may be fine, but they're the person's call.
 - **Contracts respected:** the code uses the contracts as written. A lane that needed a contract change should have asked, not worked around it.
 
-## 4. Verdict
+## 4. The security review
 
-Report the table, `verify`'s result and one of:
+Ask whether the change needs it:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" security --base <base> --branch <branch>
+```
+
+It does when the diff touches sign-in, permissions, input from outside, personal data, encryption, payments, secrets, or queries and commands built from strings, adds dependencies, or the story cites a security requirement; it says which, and where. When it does:
+
+- Run the `security-reviewer` agent (Agent tool, `subagent_type` `security-reviewer`) with the branch, the base, the story, its requirements, the spec files it touches (their `## Threat model` and `## Security requirements`) and the reasons `security` gave. It reads only, and ends with the same findings block as code-kit's reviewer: each finding graded blocker, concern or nit, with where, the attack and the fix.
+- **A blocker fails the review**, like a failing test: the branch goes back to its lane with the finding (where, the attack, the fix). Concerns are yours to weigh: send back the ones the threat model says matter, and put the rest in the report. Nits go in the report.
+- No `security-reviewer` agent in the project: `security` says so. Review the diff yourself against the same list in `${CLAUDE_PLUGIN_ROOT}/templates/security-reviewer.md`, and tell the person that re-running `/code-kit:init` adds the agent.
+- A background reviewer can't start agents: it lists the security review as due, as a concern with the reasons, and the lead runs it.
+
+## 5. Verdict
+
+Report the table, `verify`'s result, the security review's findings (or that none was needed) and one of:
 
 - **Files any agent may write** (`anyActor`, such as a lockfile or recorded decisions) have no owning lane, but they have a reviewer: `trace <file>` names it (the lead unless the config names a lane). Review those changes as that reviewer would, or ask that lane's agent.
-- **Merge.** Everything passes. Put the branch in the merge queue, set the story's `**Status:**` to `done` in the plan, and commit:
+- **Merge.** Everything passes, and the security review found no blocker. Put the branch in the merge queue, set the story's `**Status:**` to `done` in the plan, and commit:
 
   ```bash
   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" queue add <branch>

package/skills/spec-design/SKILL.md

@@ -85,6 +85,8 @@ Each requirement gets an ID (`<AREA>-<n>`, for example `BOOK-4`) and its own hea
 - **Errors and edge cases:** invalid input, duplicates, concurrency, partial failure, timeouts, an external service being down, empty and very large data.
 - **Events and integrations:** what other parts of the system or external services are told, and what they send back.
 - **Acceptance criteria:** Given / When / Then for the main path and for each important error.
+- **Threat model:** a short `## Threat model` per area: what in it is sensitive (personal data, children's data, credentials, money), who might attack it (a signed-out visitor, another customer, a staff member with the wrong role), and its trust boundaries (where outside input enters). A few concrete lines, not a compliance checklist; leave it out for an area that holds nothing sensitive and takes no outside input.
+- **Security requirements:** under `## Security requirements`, the rules that stop the attacks the threat model names, each with an ID and heading like any other requirement (`### BOOK-9 A customer sees only their own bookings`) and acceptance criteria written from the attacker's side. Stories cite them like any other requirement; a story that cites one always gets the security review.
 - **Screens** (any area a person uses through a web, mobile or desktop interface): a `## Screens` section listing each screen, what it shows, what the person can do on it and which requirements it serves, with its empty, loading and error states. These are what gets designed before anything is built.
 
 A spec answers what and why, not how: no framework, file or function names unless the person requires them. Anything still undecided goes in the spec's open questions and the brief's, never into a requirement. `Status: specified`.
@@ -103,10 +105,11 @@ These are what `/code-kit:init` turns into enforced rules, so be concrete.
   - **recipes**: under `## Recipes`, a `### <recipe-name>` for each layer's common addition (a new screen, endpoint, migration, domain service, job): the steps in order, the files each step creates or changes, and how it's tested. Each becomes a project skill when init sets up the lanes, so every lane agent builds the same thing the same way;
   - the **design tool** for screens, when there are any: the one the person uses (Paper, Figma, Pencil), or design files under `design/` when they have none.
     Propose the architecture from the specs and constraints, explain the choices, and ask about the ones that matter. Record each in the decision log.
-- **`docs/principles.md`:** the engineering rules; what counts as a contract; the definition of done (tests, checks, reviews, end-to-end working features); the test, lint, typecheck and database commands once they're known; and which commands only CI or a person may run, such as deploys.
+- **`docs/principles.md`:** the engineering rules; the privacy and data residency targets from the brief (where data may be stored and processed, what is never logged), which the security reviewer checks against; what counts as a contract; the definition of done (tests, checks, reviews, end-to-end working features); the test, lint, typecheck and database commands once they're known; and which commands only CI or a person may run, such as deploys.
 - **`docs/plan.md`**, from `${CLAUDE_PLUGIN_ROOT}/templates/plan.md`:
   - the **work split**: lanes (for example web, api, data), the paths each will own, the agent name for it and the command that proves its work, so work can run in parallel without overlap. Each lane writes and runs the unit tests for its own code;
   - a **QA lane** (`qa`, agent `test-engineer`) whenever the product has screens or journeys that cross lanes: it owns the end-to-end suites (for example `e2e/**` or `apps/*/e2e/**`), in the runner that suits each surface (Playwright for web, Maestro or Detox for mobile), and its command runs them. Nobody else owns these tests, so without it nothing proves a journey works across the lanes;
+  - no lane for security: it owns no paths. init adds a read-only security reviewer that checks every story touching the threat models' sensitive parts, so security requirements are delivered by the lanes whose code they constrain;
   - milestones, each a usable increment;
   - stories, each small enough for one lane to finish on one branch. Each story is a `### ST-<n> Title` heading with `**Lane:**`, `**Requirements:**` (the IDs it delivers, or `none` for a spike or a foundation that delivers none), `**Depends on:**` and `**Status:** todo` lines. `code-kit status` and the dispatch skill read them. A story that needs two lanes is two stories, with a dependency between them;
   - sequencing: contracts and shared foundations first, as the lead's own stories (`**Lane:** lead`, built by the lead rather than dispatched), then work that can run in parallel;
@@ -121,7 +124,7 @@ Before handing over, review everything once, as a sceptical engineer about to bu
 
 - every journey step maps to a requirement, and every requirement to a story;
 - every requirement is testable and has acceptance criteria where it matters;
-- data, states, permissions and errors are covered for every area;
+- data, states, permissions and errors are covered for every area, and every area holding something sensitive or taking outside input has a threat model and security requirements;
 - no requirement contradicts another, the constraints or a non-goal;
 - nothing is left as "TBD" outside the open-questions lists.
 

package/templates/security-reviewer.md

@@ -0,0 +1,57 @@
+---
+name: security-reviewer
+description: Read-only adversarial review of one story's change, against its specs' threat models. Use when code-kit security says a branch needs the security review, or the lead asks for one.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the security reviewer for this repository. You attack a change the way someone trying to break this product would, and report what you find. You have no lane and own no paths: you never edit or write files, install anything, commit, approve, merge or record a send-back (code-kit's hooks refuse those for you). The lead decides; you report.
+
+**What's sensitive here:** {{from the brief and specs: personal data, children's data, credentials, money, and where each is stored}}
+**Who might attack it:** {{the attackers the threat models name: signed-out visitors, other customers, a staff member with the wrong role, automated scrapers}}
+**Trust boundaries:** {{where outside input enters: the routes, webhooks, uploads, queues and third-party callbacks}}
+**Specs:** {{the spec files, each with its ## Threat model and ## Security requirements}}
+**Privacy and residency:** {{the principles' data residency and privacy targets, or "none set"}}
+**Audit commands:** `{{the project's dependency and code audit commands, e.g. npm audit --omit=dev}}`
+
+Use Bash only for commands that change nothing: `git diff`, `git log`, `git show`, the audit commands above, and `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" security --branch <branch>` to see why the branch was sent to you.
+
+For the branch and story you are given:
+
+1. Read the story, every requirement it cites, and the threat model and security requirements of each spec it touches.
+2. Read the full diff (`git diff <base>...<branch>`), then each changed file in full, and the callers and callees of every changed handler, query and permission check.
+3. Attack it. For each kind below, ask what an attacker on the far side of a trust boundary could do with this change:
+   - **Authentication and authorisation:** every new or changed route, handler, server action, job and query checks who is asking and what they may touch. Look for a missing check, a check on the wrong object (one customer's ID in another's request), a role read from the client, and data scoped in the screen but not in the query.
+   - **Injection:** SQL, shell, file paths, templates and HTML built from input; for features that call a language model, prompt injection through content the model reads, and model output trusted as a command or as markup.
+   - **Data exposure:** personal data or secrets in logs, error messages, responses, analytics and caches; selects that return more columns or rows than the screen needs.
+   - **Secrets:** keys, tokens or passwords in code, config, tests or history; secrets sent to the client.
+   - **Cryptography:** home-made crypto, weak hashes for passwords, `Math.random` for tokens, fixed IVs or keys, missing signature or expiry checks.
+   - **Requests and redirects:** server-side requests to URLs the user controls (SSRF), and open redirects.
+   - **Unsafe deserialisation:** `eval`, `pickle`, unsafe YAML, and objects merged from input without a schema.
+   - **Dependencies:** each new package's maintainers, age, weekly downloads and install scripts; known advisories from the audit command.
+   - **Privacy and residency:** data leaving the region or the purposes the principles allow.
+4. Report only findings with a concrete attack path: who the attacker is, the request or input they send, and what they get. A worry without a path isn't a finding.
+
+Grade each finding:
+
+- **blocker:** exploitable as it is, or a security requirement the story cites isn't met. The branch must not merge.
+- **concern:** should be fixed: exploitable only with something else going wrong, or a defence missing where the threat model expects one. The lead decides.
+- **nit:** a note: hardening worth doing later.
+
+For each, say where (`path:line`), the attack, and the fix, and cite the requirement or threat it bears on.
+
+End your report with one fenced json block, exactly this shape (the same as code-kit's reviewer, so the lead reads both the same way):
+
+```json
+{
+  "findings": [
+    {
+      "severity": "blocker",
+      "where": "src/api/orders.ts:42",
+      "text": "Attack: … Fix: …",
+      "rule": "ORD-7"
+    }
+  ]
+}
+```
+
+With nothing to report, say what you attacked and why each held, and end with `{"findings": []}` in the block.

package/templates/spec.md

@@ -42,6 +42,24 @@
 
 …
 
+## Threat model
+
+{{Short and concrete, for this area only. Leave it out if the area holds nothing sensitive and takes no outside input.}}
+
+- **Sensitive:** {{what here is worth stealing or breaking: personal data, children's data, credentials, money; and where it's kept}}
+- **Attackers:** {{who might try: a signed-out visitor, another customer, a staff member with the wrong role, a compromised integration}}
+- **Trust boundaries:** {{where outside input enters and who is trusted on each side: the routes, webhooks, uploads, third-party callbacks}}
+
+## Security requirements
+
+### {{AREA}}-{{n}} {{what must hold, for example "A customer sees only their own bookings"}}
+
+{{The rule, stated so a review can check it, and the attack it stops.}}
+
+**Acceptance**
+
+- Given {{an attacker and what they hold}}, when {{the attack}}, then {{what they get instead}}.
+
 ## Quality targets
 
 {{Only the ones that change how this area is built: scale, response times, privacy, accessibility, audit.}}