@cloverleaf/reference-impl 0.7.5 → 0.8.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cloverleaf",
   "description": "Cloverleaf reference implementation — Claude Code skills for task scaffolding and the Delivery pipeline (implementer, documenter, reviewer, UI reviewer with multi-viewport visual diff, QA, merge, release).",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "author": {
     "name": "Renato D'Arrigo",
     "email": "renato.darrigo@gmail.com"

package/README.md

@@ -43,6 +43,7 @@ v0.2 implements both paths of the Delivery track:
 - `/cloverleaf-ui-review` — run UI Reviewer *(new in v0.2)*
 - `/cloverleaf-approve-baselines` — human baseline-approval gate; clears `baselines_pending` and advances `ui-review → qa` *(new in CLV-19)*
 - `/cloverleaf-qa` — run QA *(new in v0.2)*
+- `/cloverleaf-security-review` — Security Reviewer: deterministic secret scan + LLM vulnerability judgment; runs when `security_class` is `high`
 - `/cloverleaf-merge` — human gate (branches on state)
 - `/cloverleaf-run` — orchestrator (dispatches by `risk_class`)
 - `/cloverleaf-release` — publish a new `@cloverleaf/reference-impl` release; runs pre-flight checks then executes `git tag -a` / `git push origin main` / `git push origin <tag>` / `npm publish` / `gh release create`; accepts `[--dry-run] [--yes]` *(new in CLV-63)*
@@ -198,6 +199,20 @@ Returns the RFC's status, all sibling Plans (with their child tasks), all standa
 
 Skipping the Plan = skipping `task_batch_gate`. That's the right tradeoff for hotfixes (one task; no decomposition to review) and for one-task-at-a-time incremental work. It's the wrong tradeoff for a large multi-task scope where the human's review of the decomposition is the load-bearing checkpoint. Plans are a checkpoint, not ceremony.
 
+## Security review
+
+The **Security Reviewer** (8th agent) runs when a task's effective `security_class` is `high`, off the `automated-gates` hub in both lanes — so it covers fast-lane backend work, not just full-pipeline UI work.
+
+**What triggers it.** `security_class` (`low`/`high`, independent of the UI-keyed `risk_class`) is inferred at task creation from sensitive markers (keywords + paths) and re-checked against the actual diff at review time (defense in depth — a task whose brief never says "credential" but whose diff touches `engine/exchange.py` is caught). Override at creation with `--security=high|low`.
+
+**Two passes.** (A) a deterministic secret scan (`cloverleaf-cli secret-scan`) over the diff's added lines — cloud keys, tokens, PEM headers, credentialed connection strings; (B) an LLM judgment pass reasoning about injection, broken authz, unsafe deserialization, SSRF, missing input validation, weak crypto.
+
+**Routing.** Findings merge into one feedback envelope; the max severity sets the verdict — any `blocker` (e.g. a leaked credential) → `escalated` (a human must review); `error`/`warning` → `implementing` (the Implementer fixes); clean → `automated-gates` → onward.
+
+**Customizing.** Both pattern sets are consumer-overridable: `.cloverleaf/config/security-paths.json` (sensitive paths + keywords) and `.cloverleaf/config/secret-patterns.json` (secret regexes + placeholder excludes).
+
+**Mechanical enforcement (v0.8.1+).** As of v0.8.1, the security-review state is mechanically enforced via the `security_gate` annotation on the Standard 0.7.1 state machine. `advance-status` re-runs `classify-security` on every guarded transition and refuses bypass attempts with exit code 2, naming the required recovery action (advance to `security-review`, run the Security Reviewer, write a `pass` verdict, then retry). This is a belt-and-suspenders complement to the orchestrator prose — the CLI enforces the invariant even if the driving LLM omits the bookkeeping step.
+
 ## License
 
 MIT — see [../LICENSE](../LICENSE).

package/VERSION

@@ -1 +1 @@
-0.7.5
+0.8.1

package/config/secret-patterns.json

@@ -0,0 +1,14 @@
+{
+  "patterns": [
+    { "name": "aws-access-key-id", "regex": "AKIA[0-9A-Z]{16}", "severity": "blocker" },
+    { "name": "github-token", "regex": "gh[pousr]_[A-Za-z0-9]{36,}", "severity": "blocker" },
+    { "name": "github-pat", "regex": "github_pat_[A-Za-z0-9_]{60,}", "severity": "blocker" },
+    { "name": "slack-token", "regex": "xox[baprs]-[A-Za-z0-9-]{10,}", "severity": "blocker" },
+    { "name": "stripe-live-key", "regex": "sk_live_[A-Za-z0-9]{24,}", "severity": "blocker" },
+    { "name": "google-api-key", "regex": "AIza[0-9A-Za-z_-]{35}", "severity": "blocker" },
+    { "name": "private-key-header", "regex": "-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----", "severity": "blocker" },
+    { "name": "credentialed-conn-string", "regex": "(postgres(ql)?|mysql|mongodb(\\+srv)?|redis|amqp)://[^:@/\\s]+:[^@/\\s]+@", "severity": "error" },
+    { "name": "generic-secret-assignment", "regex": "(?i)(password|passwd|secret|api[_-]?key|access[_-]?token)\\s*[=:]\\s*[\"'][^\"'$<{][^\"']{7,}[\"']", "severity": "error" }
+  ],
+  "placeholder_excludes": ["\\$\\{", "process\\.env", "<[^>]+>", "(?i)[=:\\s][\"']?(changeme|example|placeholder|xxx+|your[-_])"]
+}

package/config/security-paths.json

@@ -0,0 +1,13 @@
+{
+  "path_patterns": [
+    "**/*.env*", "**/secrets*", "**/*secret*", "**/*credential*",
+    "**/*.pem", "**/*.key", "**/id_rsa*", "**/auth*",
+    "**/deploy*.sh", "**/*.sql", "**/migrations/**",
+    "**/prompts/**", "**/skills/**", "**/*policy*.json"
+  ],
+  "keyword_patterns": [
+    "secret", "credential", "api[ _-]?key", "\\btoken\\b", "password",
+    "private key", "oauth", "exchange", "binance", "\\bsql\\b",
+    "\\beval\\b", "subprocess", "deserialize"
+  ]
+}

package/dist/cli.mjs

@@ -38,6 +38,9 @@
  *   walker-default-concurrency [--explain]
  *   check-scope <repoRoot> <taskId> --branch <branchName>
  *   extend-scope <repoRoot> <taskId> --add <file>... --reason <text>
+ *   secret-scan <repoRoot> --branch <branch>
+ *   classify-security <repoRoot> <taskId> [--branch <branch>]
+ *   set-task-field <repoRoot> <taskId> <field> <value>
  */
 import { readFileSync, mkdirSync, copyFileSync, appendFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -65,6 +68,8 @@ import { readWalkState, writeWalkState, walkStatePath } from './walk-state.mjs';
 import { loadWalkerConfig } from './walker-config.mjs';
 import { classifyFiles } from './scope-check.mjs';
 import { computeRfcTasksView } from './rfc-tasks.mjs';
+import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.mjs';
+import { classifyTaskSecurity } from './security-classify.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -106,7 +111,10 @@ function usage(msg) {
         '  walk-state-write <repoRoot> <walkStateJsonPath>\n' +
         '  walker-default-concurrency [--explain]\n' +
         '  check-scope <repoRoot> <taskId> --branch <branchName>\n' +
-        '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n');
+        '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n' +
+        '  secret-scan <repoRoot> --branch <branch>\n' +
+        '  classify-security <repoRoot> <taskId> [--branch <branch>]\n' +
+        '  set-task-field <repoRoot> <taskId> <field> <value>\n');
     process.exit(2);
 }
 const [, , command, ...rest] = process.argv;
@@ -723,12 +731,75 @@ try {
             appendFileSync(auditPath, JSON.stringify(auditEntry) + '\n');
             process.exit(0);
         }
+        case 'secret-scan': {
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const branchIdx = rest.indexOf('--branch');
+            const branch = branchIdx >= 0 ? rest[branchIdx + 1] : undefined;
+            const [repoRoot] = positional;
+            if (!repoRoot || !branch)
+                usage('secret-scan <repoRoot> --branch <branch>');
+            const cfg = loadSecretPatternsConfig(repoRoot);
+            // Scan added/changed lines only (the '+' lines of the diff, minus the +++ header),
+            // so we flag what THIS task introduced, not pre-existing secrets.
+            const diff = execSync(`git -C ${repoRoot} diff --unified=0 main..${branch}`, { encoding: 'utf-8' });
+            const addedByFile = {};
+            let curFile = '';
+            for (const line of diff.split('\n')) {
+                if (line.startsWith('+++ b/')) {
+                    curFile = line.slice(6);
+                    addedByFile[curFile] = [];
+                }
+                else if (line.startsWith('+') && !line.startsWith('+++')) {
+                    (addedByFile[curFile] ||= []).push(line.slice(1));
+                }
+            }
+            const findings = Object.entries(addedByFile).flatMap(([f, lines]) => scanSecrets(lines.join('\n'), cfg, f));
+            process.stdout.write(JSON.stringify({ findings }) + '\n');
+            break;
+        }
+        case 'classify-security': {
+            const positional = rest.filter((a) => !a.startsWith('--'));
+            const branchIdx = rest.indexOf('--branch');
+            const branch = branchIdx >= 0 ? rest[branchIdx + 1] : undefined;
+            const [repoRoot, taskId] = positional;
+            if (!repoRoot || !taskId)
+                usage('classify-security <repoRoot> <taskId> [--branch <branch>]');
+            let result;
+            try {
+                result = classifyTaskSecurity(repoRoot, taskId, branch ? { branch } : undefined);
+            }
+            catch (err) {
+                process.stderr.write(`cloverleaf-cli classify-security: ${err instanceof Error ? err.message : String(err)}\n`);
+                process.exit(2);
+            }
+            process.stdout.write(JSON.stringify(result) + '\n');
+            break;
+        }
+        case 'set-task-field': {
+            const [repoRoot, taskId, field, value] = rest;
+            if (!repoRoot || !taskId || !field || value === undefined)
+                usage('set-task-field requires <repoRoot> <taskId> <field> <value>');
+            const ALLOWED_FIELDS = new Set(['security_review_verdict']);
+            if (!ALLOWED_FIELDS.has(field)) {
+                die(`set-task-field: unknown field '${field}'. Allowed fields: ${Array.from(ALLOWED_FIELDS).join(', ')}`);
+            }
+            const task = loadTask(repoRoot, taskId);
+            const parsed = value === 'null' ? null : value;
+            task[field] = parsed;
+            saveTask(repoRoot, task);
+            break;
+        }
         default:
             usage(`Unknown command: ${command}`);
     }
 }
 catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    // SECURITY_GATE errors: write the bare validator message to stderr and exit 2
+    if (err.code === 'SECURITY_GATE') {
+        process.stderr.write(msg + '\n');
+        process.exit(2);
+    }
     // Surface "illegal transition" errors with the right language
     const lower = msg.toLowerCase();
     if (lower.includes('illegal') || lower.includes('not allowed')) {

package/dist/secret-scan.mjs

@@ -0,0 +1,75 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const here = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(here, '..', 'config', 'secret-patterns.json');
+function normalize(doc) {
+    const raw = Array.isArray(doc.patterns) ? doc.patterns : [];
+    const validSeverities = new Set(['error', 'blocker']);
+    const patterns = raw.filter((p) => typeof p.name === 'string' && p.name.length > 0 &&
+        typeof p.regex === 'string' && p.regex.length > 0 &&
+        validSeverities.has(p.severity));
+    return {
+        patterns,
+        placeholder_excludes: Array.isArray(doc.placeholder_excludes)
+            ? doc.placeholder_excludes.filter((s) => typeof s === 'string')
+            : [],
+    };
+}
+export function loadSecretPatternsConfig(repoRoot) {
+    const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'secret-patterns.json');
+    const path = existsSync(consumerPath) ? consumerPath : DEFAULT_CONFIG;
+    if (!existsSync(path))
+        throw new Error(`secret-patterns config not found at ${path}`);
+    return normalize(JSON.parse(readFileSync(path, 'utf-8')));
+}
+/**
+ * Scan text (typically the added/changed lines of a diff) for secrets.
+ * A line that matches any placeholder_exclude is skipped entirely (env refs,
+ * templates, obvious placeholders), keeping precision high.
+ */
+function compileRegex(pattern) {
+    // Support (?i) inline flag prefix (not valid in JS) by converting to the 'i' flag.
+    // Only a *leading* (?i) is supported; any occurrence elsewhere is almost certainly
+    // a mistake (it would be a JS syntax error) — reject it with a clear message.
+    const original = pattern;
+    let flags = '';
+    if (pattern.startsWith('(?i)')) {
+        pattern = pattern.slice(4);
+        flags = 'i';
+    }
+    if (pattern.includes('(?i)')) {
+        throw new Error('secret-scan: inline (?i) flag is only supported as a leading prefix: ' + original);
+    }
+    try {
+        return new RegExp(pattern, flags);
+    }
+    catch (err) {
+        throw new Error('secret-scan: invalid pattern regex /' + pattern + '/: ' + err.message);
+    }
+}
+export function scanSecrets(text, config, file) {
+    const excludes = config.placeholder_excludes.map((p) => compileRegex(p));
+    const compiled = config.patterns.map((p) => ({ ...p, re: compileRegex(p.regex) }));
+    const findings = [];
+    const lines = text.split('\n');
+    lines.forEach((line, idx) => {
+        // Deliberate line-level tradeoff: a line matching any exclude pattern is
+        // skipped entirely.  If a real secret happens to share a line with a
+        // placeholder token (e.g. a comment), it becomes a false-negative.
+        // This keeps precision high and avoids alert fatigue from generated files.
+        if (excludes.some((re) => re.test(line)))
+            return;
+        for (const p of compiled) {
+            if (p.re.test(line)) {
+                findings.push({
+                    severity: p.severity,
+                    rule: p.name,
+                    message: `Possible hardcoded secret (${p.name}) on line ${idx + 1}`,
+                    location: { ...(file ? { file } : {}), line: idx + 1 },
+                });
+            }
+        }
+    });
+    return findings;
+}

package/dist/task.mjs

@@ -1,8 +1,10 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { tasksDir, projectsDir } from './paths.mjs';
 import { validateOrThrow } from './validate.mjs';
 import { advanceWorkItemStatus, loadStateMachine } from './work-item.mjs';
+import { classifyTaskSecurity } from './security-classify.mjs';
 export function loadTask(repoRoot, taskId) {
     const path = join(tasksDir(repoRoot), `${taskId}.json`);
     if (!existsSync(path))
@@ -22,9 +24,40 @@ export function loadProject(repoRoot, projectId) {
     return JSON.parse(readFileSync(path, 'utf-8'));
 }
 export function advanceStatus(repoRoot, taskId, toStatus, actor, options = {}) {
-    const task = loadTask(repoRoot, taskId);
+    let task = loadTask(repoRoot, taskId);
     const from = task.status;
     const sm = loadStateMachine('task');
+    const targetTransition = sm.transitions.find((t) => t.from === from && t.to === toStatus);
+    // Security-gate writeback: classify the task's security and upgrade if needed.
+    if (targetTransition?.security_gate) {
+        let classification;
+        try {
+            classification = classifyTaskSecurity(repoRoot, taskId);
+        }
+        catch (err) {
+            process.stderr.write(`cloverleaf-cli advance-status: classify-security errored (${err instanceof Error ? err.message : String(err)}); treating effective security_class as "high".\n`);
+            classification = {
+                declared: (task.security_class === 'high' ? 'high' : 'low'),
+                diff_detected: true,
+                effective: 'high',
+                matched_paths: [],
+            };
+        }
+        if (classification.declared === 'low' && classification.effective === 'high') {
+            const upgraded = { ...task, security_class: 'high' };
+            saveTask(repoRoot, upgraded);
+            const taskFilePath = join(tasksDir(repoRoot), `${taskId}.json`);
+            try {
+                execFileSync('git', ['-C', repoRoot, 'add', taskFilePath], { stdio: 'pipe' });
+                execFileSync('git', ['-C', repoRoot, 'commit', '-m', `cloverleaf: ${taskId} security_class → high (diff-detected)`], { stdio: 'pipe' });
+            }
+            catch {
+                // No-op: commit is best-effort when running outside a git repo (e.g., test environments).
+            }
+            // Mutate in-memory so the validator sees the upgraded value.
+            task = { ...upgraded };
+        }
+    }
     const riskClass = options.path === 'fast_lane' ? 'low'
         : options.path === 'full_pipeline' ? 'high'
             : (task.risk_class ?? 'low');
@@ -34,11 +67,18 @@ export function advanceStatus(repoRoot, taskId, toStatus, actor, options = {}) {
         project: task.project,
         status: task.status,
         risk_class: riskClass,
+        security_class: task.security_class,
+        security_review_verdict: task.security_review_verdict,
         context: { rfc: { project: task.project, id: task.id } },
         definition_of_done: task.definition_of_done,
         acceptance_criteria: task.acceptance_criteria,
     };
-    const proposed = { ...task, status: toStatus };
+    const resetsVerdict = targetTransition?.resets_security_verdict === true;
+    const proposed = {
+        ...task,
+        status: toStatus,
+        ...(resetsVerdict ? { security_review_verdict: null } : {}),
+    };
     advanceWorkItemStatus({
         repoRoot,
         workItemType: 'task',
@@ -54,5 +94,16 @@ export function advanceStatus(repoRoot, taskId, toStatus, actor, options = {}) {
         gate: options.gate,
         path: options.path,
     });
+    // After a successful status change + verdict reset, emit a single commit covering both.
+    if (resetsVerdict) {
+        const taskFilePath = join(tasksDir(repoRoot), `${taskId}.json`);
+        try {
+            execFileSync('git', ['-C', repoRoot, 'add', taskFilePath], { stdio: 'pipe' });
+            execFileSync('git', ['-C', repoRoot, 'commit', '-m', `cloverleaf: ${taskId} status ${from} → ${toStatus}; security_review_verdict → null (rework)`], { stdio: 'pipe' });
+        }
+        catch {
+            // No-op: commit is best-effort when running outside a git repo (e.g., test environments).
+        }
+    }
     return proposed;
 }

package/dist/work-item.mjs

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { emitStatusTransition, formatReason } from './events.mjs';
-import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import { validateStatusTransitionLegality, validateSecurityGate } from '@cloverleaf/standard/validators/index.js';
 const req = createRequire(import.meta.url);
 export function loadStateMachine(type) {
     const pkgPath = req.resolve('@cloverleaf/standard/package.json');
@@ -28,6 +28,15 @@ export function advanceWorkItemStatus(params) {
         const msgs = result.violations.map((v) => v.message).join('; ');
         throw new Error(`Illegal transition ${from} → ${to}: ${msgs}`);
     }
+    if (workItemType === 'task') {
+        const sgResult = validateSecurityGate(event, stateMachine, validateFixture);
+        if (!sgResult.ok) {
+            const msgs = sgResult.violations.map((v) => v.message).join('; ');
+            const err = new Error(msgs);
+            err.code = 'SECURITY_GATE';
+            throw err;
+        }
+    }
     const emittedPath = emitStatusTransition(repoRoot, {
         project,
         workItemType,

package/lib/cli.ts

@@ -38,6 +38,9 @@
  *   walker-default-concurrency [--explain]
  *   check-scope <repoRoot> <taskId> --branch <branchName>
  *   extend-scope <repoRoot> <taskId> --add <file>... --reason <text>
+ *   secret-scan <repoRoot> --branch <branch>
+ *   classify-security <repoRoot> <taskId> [--branch <branch>]
+ *   set-task-field <repoRoot> <taskId> <field> <value>
  */
 
 import { readFileSync, mkdirSync, copyFileSync, appendFileSync, existsSync } from 'node:fs';
@@ -68,6 +71,8 @@ import { loadWalkerConfig } from './walker-config.js';
 import { classifyFiles } from './scope-check.js';
 import type { SiblingScope } from './scope-check.js';
 import { computeRfcTasksView, type RfcTasksView } from './rfc-tasks.js';
+import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.js';
+import { classifyTaskSecurity } from './security-classify.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -111,7 +116,10 @@ function usage(msg?: string): never {
       '  walk-state-write <repoRoot> <walkStateJsonPath>\n' +
       '  walker-default-concurrency [--explain]\n' +
       '  check-scope <repoRoot> <taskId> --branch <branchName>\n' +
-      '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n'
+      '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n' +
+      '  secret-scan <repoRoot> --branch <branch>\n' +
+      '  classify-security <repoRoot> <taskId> [--branch <branch>]\n' +
+      '  set-task-field <repoRoot> <taskId> <field> <value>\n'
   );
   process.exit(2);
 }
@@ -744,11 +752,71 @@ try {
       process.exit(0);
     }
 
+    case 'secret-scan': {
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const branchIdx = rest.indexOf('--branch');
+      const branch = branchIdx >= 0 ? rest[branchIdx + 1] : undefined;
+      const [repoRoot] = positional;
+      if (!repoRoot || !branch) usage('secret-scan <repoRoot> --branch <branch>');
+      const cfg = loadSecretPatternsConfig(repoRoot);
+      // Scan added/changed lines only (the '+' lines of the diff, minus the +++ header),
+      // so we flag what THIS task introduced, not pre-existing secrets.
+      const diff = execSync(`git -C ${repoRoot} diff --unified=0 main..${branch}`, { encoding: 'utf-8' });
+      const addedByFile: Record<string, string[]> = {};
+      let curFile = '';
+      for (const line of diff.split('\n')) {
+        if (line.startsWith('+++ b/')) { curFile = line.slice(6); addedByFile[curFile] = []; }
+        else if (line.startsWith('+') && !line.startsWith('+++')) { (addedByFile[curFile] ||= []).push(line.slice(1)); }
+      }
+      const findings = Object.entries(addedByFile).flatMap(([f, lines]) => scanSecrets(lines.join('\n'), cfg, f));
+      process.stdout.write(JSON.stringify({ findings }) + '\n');
+      break;
+    }
+
+    case 'classify-security': {
+      const positional = rest.filter((a) => !a.startsWith('--'));
+      const branchIdx = rest.indexOf('--branch');
+      const branch = branchIdx >= 0 ? rest[branchIdx + 1] : undefined;
+      const [repoRoot, taskId] = positional;
+      if (!repoRoot || !taskId) usage('classify-security <repoRoot> <taskId> [--branch <branch>]');
+      let result;
+      try {
+        result = classifyTaskSecurity(repoRoot, taskId, branch ? { branch } : undefined);
+      } catch (err) {
+        process.stderr.write(`cloverleaf-cli classify-security: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+      }
+      process.stdout.write(JSON.stringify(result) + '\n');
+      break;
+    }
+
+    case 'set-task-field': {
+      const [repoRoot, taskId, field, value] = rest;
+      if (!repoRoot || !taskId || !field || value === undefined)
+        usage('set-task-field requires <repoRoot> <taskId> <field> <value>');
+      const ALLOWED_FIELDS = new Set(['security_review_verdict']);
+      if (!ALLOWED_FIELDS.has(field)) {
+        die(
+          `set-task-field: unknown field '${field}'. Allowed fields: ${Array.from(ALLOWED_FIELDS).join(', ')}`
+        );
+      }
+      const task = loadTask(repoRoot, taskId);
+      const parsed: unknown = value === 'null' ? null : value;
+      (task as Record<string, unknown>)[field] = parsed;
+      saveTask(repoRoot, task);
+      break;
+    }
+
     default:
       usage(`Unknown command: ${command}`);
   }
 } catch (err: unknown) {
   const msg = err instanceof Error ? err.message : String(err);
+  // SECURITY_GATE errors: write the bare validator message to stderr and exit 2
+  if ((err as { code?: string }).code === 'SECURITY_GATE') {
+    process.stderr.write(msg + '\n');
+    process.exit(2);
+  }
   // Surface "illegal transition" errors with the right language
   const lower = msg.toLowerCase();
   if (lower.includes('illegal') || lower.includes('not allowed')) {

package/lib/secret-scan.ts

@@ -0,0 +1,90 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = join(here, '..', 'config', 'secret-patterns.json');
+
+export interface SecretPattern { name: string; regex: string; severity: 'error' | 'blocker'; }
+export interface SecretPatternsConfig { patterns: SecretPattern[]; placeholder_excludes: string[]; }
+
+export interface SecretFinding {
+  severity: 'error' | 'blocker';
+  message: string;
+  rule: string;
+  location?: { file?: string; line?: number };
+}
+
+function normalize(doc: Partial<SecretPatternsConfig>): SecretPatternsConfig {
+  const raw = Array.isArray(doc.patterns) ? doc.patterns : [];
+  const validSeverities = new Set(['error', 'blocker']);
+  const patterns = raw.filter(
+    (p): p is SecretPattern =>
+      typeof (p as SecretPattern).name === 'string' && (p as SecretPattern).name.length > 0 &&
+      typeof (p as SecretPattern).regex === 'string' && (p as SecretPattern).regex.length > 0 &&
+      validSeverities.has((p as SecretPattern).severity),
+  );
+  return {
+    patterns,
+    placeholder_excludes: Array.isArray(doc.placeholder_excludes)
+      ? (doc.placeholder_excludes as unknown[]).filter((s): s is string => typeof s === 'string')
+      : [],
+  };
+}
+
+export function loadSecretPatternsConfig(repoRoot: string): SecretPatternsConfig {
+  const consumerPath = join(repoRoot, '.cloverleaf', 'config', 'secret-patterns.json');
+  const path = existsSync(consumerPath) ? consumerPath : DEFAULT_CONFIG;
+  if (!existsSync(path)) throw new Error(`secret-patterns config not found at ${path}`);
+  return normalize(JSON.parse(readFileSync(path, 'utf-8')) as Partial<SecretPatternsConfig>);
+}
+
+/**
+ * Scan text (typically the added/changed lines of a diff) for secrets.
+ * A line that matches any placeholder_exclude is skipped entirely (env refs,
+ * templates, obvious placeholders), keeping precision high.
+ */
+function compileRegex(pattern: string): RegExp {
+  // Support (?i) inline flag prefix (not valid in JS) by converting to the 'i' flag.
+  // Only a *leading* (?i) is supported; any occurrence elsewhere is almost certainly
+  // a mistake (it would be a JS syntax error) — reject it with a clear message.
+  const original = pattern;
+  let flags = '';
+  if (pattern.startsWith('(?i)')) {
+    pattern = pattern.slice(4);
+    flags = 'i';
+  }
+  if (pattern.includes('(?i)')) {
+    throw new Error('secret-scan: inline (?i) flag is only supported as a leading prefix: ' + original);
+  }
+  try {
+    return new RegExp(pattern, flags);
+  } catch (err) {
+    throw new Error('secret-scan: invalid pattern regex /' + pattern + '/: ' + (err as Error).message);
+  }
+}
+
+export function scanSecrets(text: string, config: SecretPatternsConfig, file?: string): SecretFinding[] {
+  const excludes = config.placeholder_excludes.map((p) => compileRegex(p));
+  const compiled = config.patterns.map((p) => ({ ...p, re: compileRegex(p.regex) }));
+  const findings: SecretFinding[] = [];
+  const lines = text.split('\n');
+  lines.forEach((line, idx) => {
+    // Deliberate line-level tradeoff: a line matching any exclude pattern is
+    // skipped entirely.  If a real secret happens to share a line with a
+    // placeholder token (e.g. a comment), it becomes a false-negative.
+    // This keeps precision high and avoids alert fatigue from generated files.
+    if (excludes.some((re) => re.test(line))) return;
+    for (const p of compiled) {
+      if (p.re.test(line)) {
+        findings.push({
+          severity: p.severity,
+          rule: p.name,
+          message: `Possible hardcoded secret (${p.name}) on line ${idx + 1}`,
+          location: { ...(file ? { file } : {}), line: idx + 1 },
+        });
+      }
+    }
+  });
+  return findings;
+}

package/lib/task.ts

@@ -1,9 +1,11 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { tasksDir, projectsDir } from './paths.js';
 import type { Task as SMTask } from '@cloverleaf/standard/validators/index.js';
 import { validateOrThrow } from './validate.js';
 import { advanceWorkItemStatus, loadStateMachine } from './work-item.js';
+import { classifyTaskSecurity } from './security-classify.js';
 
 export interface TaskDoc {
   type: 'task';
@@ -12,6 +14,8 @@ export interface TaskDoc {
   title: string;
   status: string;
   risk_class: 'low' | 'high';
+  security_class?: 'low' | 'high';
+  security_review_verdict?: 'pass' | 'bounce' | 'escalate' | null;
   owner: { kind: 'agent' | 'human' | 'system'; id: string };
   acceptance_criteria: string[];
   definition_of_done: string[];
@@ -51,10 +55,47 @@ export function advanceStatus(
   actor: 'agent' | 'human',
   options: { gate?: string; path?: 'fast_lane' | 'full_pipeline' } = {}
 ): TaskDoc {
-  const task = loadTask(repoRoot, taskId);
+  let task = loadTask(repoRoot, taskId);
   const from = task.status;
   const sm = loadStateMachine('task');
 
+  const targetTransition = sm.transitions.find((t) => t.from === from && t.to === toStatus);
+
+  // Security-gate writeback: classify the task's security and upgrade if needed.
+  if (targetTransition?.security_gate) {
+    let classification;
+    try {
+      classification = classifyTaskSecurity(repoRoot, taskId);
+    } catch (err) {
+      process.stderr.write(
+        `cloverleaf-cli advance-status: classify-security errored (${err instanceof Error ? err.message : String(err)}); treating effective security_class as "high".\n`
+      );
+      classification = {
+        declared: (task.security_class === 'high' ? 'high' : 'low') as 'low' | 'high',
+        diff_detected: true,
+        effective: 'high' as const,
+        matched_paths: [],
+      };
+    }
+    if (classification.declared === 'low' && classification.effective === 'high') {
+      const upgraded: TaskDoc = { ...task, security_class: 'high' };
+      saveTask(repoRoot, upgraded);
+      const taskFilePath = join(tasksDir(repoRoot), `${taskId}.json`);
+      try {
+        execFileSync('git', ['-C', repoRoot, 'add', taskFilePath], { stdio: 'pipe' });
+        execFileSync(
+          'git',
+          ['-C', repoRoot, 'commit', '-m', `cloverleaf: ${taskId} security_class → high (diff-detected)`],
+          { stdio: 'pipe' }
+        );
+      } catch {
+        // No-op: commit is best-effort when running outside a git repo (e.g., test environments).
+      }
+      // Mutate in-memory so the validator sees the upgraded value.
+      task = { ...upgraded };
+    }
+  }
+
   const riskClass: 'low' | 'high' =
     options.path === 'fast_lane' ? 'low'
     : options.path === 'full_pipeline' ? 'high'
@@ -66,12 +107,20 @@ export function advanceStatus(
     project: task.project,
     status: task.status,
     risk_class: riskClass,
+    security_class: task.security_class,
+    security_review_verdict: task.security_review_verdict,
     context: { rfc: { project: task.project, id: task.id } },
     definition_of_done: task.definition_of_done,
     acceptance_criteria: task.acceptance_criteria,
   };
 
-  const proposed = { ...task, status: toStatus };
+  const resetsVerdict = targetTransition?.resets_security_verdict === true;
+  const proposed: TaskDoc = {
+    ...task,
+    status: toStatus,
+    ...(resetsVerdict ? { security_review_verdict: null } : {}),
+  };
+
   advanceWorkItemStatus({
     repoRoot,
     workItemType: 'task',
@@ -87,5 +136,21 @@ export function advanceStatus(
     gate: options.gate,
     path: options.path,
   });
+
+  // After a successful status change + verdict reset, emit a single commit covering both.
+  if (resetsVerdict) {
+    const taskFilePath = join(tasksDir(repoRoot), `${taskId}.json`);
+    try {
+      execFileSync('git', ['-C', repoRoot, 'add', taskFilePath], { stdio: 'pipe' });
+      execFileSync(
+        'git',
+        ['-C', repoRoot, 'commit', '-m', `cloverleaf: ${taskId} status ${from} → ${toStatus}; security_review_verdict → null (rework)`],
+        { stdio: 'pipe' }
+      );
+    } catch {
+      // No-op: commit is best-effort when running outside a git repo (e.g., test environments).
+    }
+  }
+
   return proposed;
 }

package/lib/work-item.ts

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { emitStatusTransition, formatReason } from './events.js';
-import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import { validateStatusTransitionLegality, validateSecurityGate } from '@cloverleaf/standard/validators/index.js';
 import type { StatusTransitions } from '@cloverleaf/standard/validators/index.js';
 
 const req = createRequire(import.meta.url);
@@ -56,6 +56,16 @@ export function advanceWorkItemStatus<T>(params: AdvanceWorkItemParams<T>): Adva
     throw new Error(`Illegal transition ${from} → ${to}: ${msgs}`);
   }
 
+  if (workItemType === 'task') {
+    const sgResult = validateSecurityGate(event, stateMachine, validateFixture as never);
+    if (!sgResult.ok) {
+      const msgs = sgResult.violations.map((v) => v.message).join('; ');
+      const err = new Error(msgs);
+      (err as Error & { code?: string }).code = 'SECURITY_GATE';
+      throw err;
+    }
+  }
+
   const emittedPath = emitStatusTransition(repoRoot, {
     project,
     workItemType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -48,8 +48,11 @@
     "acceptance:walker": "bash scripts/acceptance-walker.sh",
     "prepublishOnly": "node scripts/check-standard-prepped.mjs && npm test && npm run build"
   },
+  "peerDependencies": {
+    "@cloverleaf/standard": "^0.7.1"
+  },
   "dependencies": {
-    "@cloverleaf/standard": "^0.6.0",
+    "@cloverleaf/standard": "^0.7.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "axe-core": "^4.10.0",

package/prompts/security-reviewer.md

@@ -0,0 +1,55 @@
+# Security Reviewer
+
+You are a security-minded senior engineer reviewing a code change for vulnerabilities. You are read-only — do not modify code. Judge ONLY the diff provided.
+
+## Task
+{{task}}
+
+## Branch / base
+Branch `{{branch}}` against `{{base_branch}}`. Repo root `{{repo_root}}`.
+
+## Diff
+{{diff}}
+
+## What to judge
+
+Examine the changed code for:
+- **Injection** — SQL, command/shell, path traversal, template/SSTI. Any user/external input reaching an interpreter, query, filesystem path, or subprocess without parameterization/escaping.
+- **Broken or missing authorization** — endpoints/handlers that skip an access check; privilege boundaries crossed.
+- **Unsafe deserialization** — `pickle`, `yaml.load`, `eval`, untrusted JSON→object with prototype risks.
+- **SSRF / unsafe outbound** — server-side requests built from untrusted input.
+- **Missing input validation** — unchecked sizes, types, ranges on external input that reaches sensitive sinks.
+- **Unsafe file ops** — path joins from untrusted input, world-writable perms, temp-file races.
+- **Weak crypto / weak defaults** — MD5/SHA1 for security, hardcoded IVs, disabled TLS verification, permissive CORS.
+
+A deterministic secret scan runs separately; you do NOT need to hunt for hardcoded keys (but flag one if you see it).
+
+## Return contract
+
+The response envelope **must** include a top-level `verdict` field (enum: `"pass"`, `"bounce"`, or `"escalate"`). The verdict is derived from the maximum severity across all findings:
+
+| Max severity across findings | verdict |
+|------------------------------|---------|
+| any `blocker`                | `"escalate"` |
+| any `error` or `warning`     | `"bounce"` |
+| `info` only, or no findings  | `"pass"` |
+
+The host skill (`cloverleaf-security-review`) persists the verdict on the task via `cloverleaf-cli set-task-field <repo_root> <TASK-ID> security_review_verdict <verdict>`. You (the security reviewer agent) do not write to the task file — you only emit the envelope. The skill reads your `verdict` field and records it.
+
+## Output
+
+Return ONLY a feedback envelope JSON:
+
+```json
+{ "verdict": "pass" | "bounce" | "escalate",
+  "summary": "<one-line overall assessment>",
+  "findings": [
+    { "severity": "info|warning|error|blocker",
+      "message": "<what + why it matters>",
+      "location": { "file": "<path>", "line": <n> },
+      "suggestion": "<concrete fix>",
+      "rule": "<short-id e.g. injection.sql>" }
+  ] }
+```
+
+Severity guidance: `blocker` = exploitable now / credential exposure (→ human escalation). `error` = real vulnerability the implementer must fix. `warning` = weakness worth fixing. `info` = advisory, non-blocking. Set `verdict`: `escalate` if any `blocker`; else `bounce` if any `error`/`warning`; else `pass`. Be precise — false alarms erode trust. If the diff is inert (docs/tests/config with no security surface), return `{ "verdict": "pass", "summary": "no security-relevant surface", "findings": [] }`.

package/skills/cloverleaf-new-task/SKILL.md

@@ -35,7 +35,8 @@ The user has invoked this skill with a brief. Your job: turn the brief into a st
      "context": <see "context.rfc injection" below>,
      "acceptance_criteria": ["<criterion 1>", "<criterion 2>", "..."],
      "definition_of_done": ["<terminal statement of completion>"],
-     "risk_class": "low"
+     "risk_class": "low",
+     "security_class": "<see security_class inference below>"
    }
    ```
 
@@ -82,6 +83,11 @@ The user has invoked this skill with a brief. Your job: turn the brief into a st
      `site/`, `UI`, `page`, `component`, `style`, `visual`, `layout`, `render`, `display`, `accessibility`, `a11y`, `responsive`, `.astro`, `.css`, `.html`
   3. Also set `risk_class: "high"` for breaking APIs or cross-project work (v0.1.1 behavior, retained).
   4. Default: `risk_class: "low"`.
+- **`security_class` inference:** `security_class` (`"low"|"high"`, independent of `risk_class`) gates the Security Reviewer. Rules:
+  1. If the user passed `--security=high` or `--security=low`, honor it.
+  2. Otherwise set `"high"` when the brief, any acceptance criterion, OR any `scope.files_touched` entry matches a sensitive marker from `security-paths.json` (keyword patterns like `secret`, `credential`, `api key`, `token`, `password`, `exchange`, `sql`, `eval`, `subprocess`; or path patterns like `**/*.env*`, `**/secrets*`, `**/deploy*.sh`, `**/*.sql`, `**/auth*`). Consumers override the marker set at `.cloverleaf/config/security-paths.json`.
+  3. Default: `"low"`.
+- After writing the task, report the chosen `security_class` and why, e.g. `Security class: high → security review (matched keyword "credential"). Override with --security=low if desired.` Note: even when `low`, the orchestrator re-checks the actual diff at review time and routes to security-review if it touches sensitive paths (defense in depth).
 - After writing the task, report the chosen risk_class and how it was determined, e.g.:
   > "Risk class: `high` → full pipeline (matched keyword `component` in acceptance criterion). Override with `--risk=low` if desired."
 - Users can manually edit `risk_class` in the task JSON before running `/cloverleaf-run`.

package/skills/cloverleaf-run/SKILL.md

@@ -17,10 +17,40 @@ Do NOT `git checkout main` from a walker worktree — main is held by the primar
 MAX_REVIEWER_BOUNCES    = 3
 MAX_UI_REVIEWER_BOUNCES = 3
 MAX_QA_BOUNCES          = 3
+MAX_SECURITY_BOUNCES    = 3
 ```
 
 These counters live in-session (not persisted). Rerunning `/cloverleaf-run` resets.
 
+## Security gate (both lanes)
+
+Run this immediately after the task reaches `automated-gates` (Reviewer passed) and BEFORE the lane's next move (fast lane: merge; full pipeline: detect-ui-paths). Initialize `security_bounces = 0` at orchestrator start (alongside the other bounce counters).
+
+```bash
+cloverleaf-cli classify-security <repo_root> <TASK-ID> --branch cloverleaf/<TASK-ID>
+```
+
+Parse the JSON. If `classify-security` exits non-zero or emits unparseable output, do NOT silently skip security review (fail-open is unsafe for a security gate). Warn to the user and treat the task as `effective: "high"` — i.e. proceed into security-review anyway (fail toward more scrutiny). If `/cloverleaf-security-review` then cannot run either (e.g. branch/tooling broken), surface the failure and stop rather than merging unreviewed.
+
+If `effective == "low"` → skip the gate, proceed with the lane.
+
+If `effective == "high"`:
+- If `declared == "low"` (under-classification: `diff_detected` true), you may proactively run `classify-security` to confirm, but the writeback to `security_class: "high"` is now mechanical — the CLI handles it automatically when `advance-status` moves the task to `security-review`. No manual scripting of the writeback is required.
+- `cloverleaf-cli advance-status <repo_root> <TASK-ID> security-review agent`; commit.
+- Inline `/cloverleaf-security-review <TASK-ID>` steps. Reload the task:
+  - `status == "automated-gates"` → security review passed; proceed with the lane.
+  - `status == "implementing"` → bounced. `security_bounces += 1`. If `security_bounces >= MAX_SECURITY_BOUNCES`, escalate (section 6). Else re-enter the implement→review loop (fast lane section 4 / full pipeline section 5.1), which re-runs the security gate on its next pass.
+  - `status == "escalated"` → the security reviewer found a blocker; stop and surface to the user (a human must review `.cloverleaf/feedback/`). This is the security reviewer's own escalation, distinct from a bounce-budget exhaustion.
+
+### Refusal and recover
+
+In v0.8.1, `advance-status` from `automated-gates` to any post-gate state (`ui-review`, `qa`, `merged`) may exit with **exit code 2** when the task is high-security and has no pass verdict recorded (`security_review_verdict` is absent or not `"pass"`). This is a **security-gate refusal** — the CLI is enforcing that high-security tasks must pass security review before proceeding.
+
+Recovery sequence:
+1. Advance the task to `security-review` first: `cloverleaf-cli advance-status <repo_root> <TASK-ID> security-review agent`; commit.
+2. Run `/cloverleaf-security-review <TASK-ID>` to execute the security review.
+3. Retry the original `advance-status` call. If the review passed, the CLI will now allow the transition.
+
 ## Steps
 
 1. Capture TASK-ID.
@@ -33,7 +63,7 @@ These counters live in-session (not persisted). Rerunning `/cloverleaf-run` rese
 
 ### 4. Fast Lane
 
-Initialize `reviewer_bounces = 0`.
+Initialize `reviewer_bounces = 0`, `security_bounces = 0`.
 
 Loop:
   a. Inline `/cloverleaf-implement <TASK-ID>` steps.
@@ -42,11 +72,11 @@ Loop:
   d. If `status === "implementing"`: Reviewer bounced. `reviewer_bounces += 1`. If `reviewer_bounces >= MAX_REVIEWER_BOUNCES`, escalate (section 6). Else continue loop.
   e. Else: unexpected state. Report and stop.
 
-After loop: inline `/cloverleaf-merge <TASK-ID>`.
+After loop (status `automated-gates`): run the **Security gate (both lanes)** (above). Then inline `/cloverleaf-merge <TASK-ID>`.
 
 ### 5. Full Pipeline
 
-Initialize `reviewer_bounces = 0`, `ui_reviewer_bounces = 0`, `qa_bounces = 0`.
+Initialize `reviewer_bounces = 0`, `ui_reviewer_bounces = 0`, `qa_bounces = 0`, `security_bounces = 0`.
 
 5.1. **Implementer → Documenter → Reviewer loop:**
 
@@ -58,6 +88,8 @@ Loop:
   e. If `status === "implementing"`: Reviewer bounced. `reviewer_bounces += 1`. If `reviewer_bounces >= MAX_REVIEWER_BOUNCES`, escalate. Else continue loop.
   f. Else: unexpected. Report and stop.
 
+**Security gate.** Run the **Security gate (both lanes)** (above) now, before UI-path detection. Then continue to 5.2.
+
 5.2. **UI-path detection and conditional UI Review:**
 
 ```bash
@@ -88,7 +120,7 @@ Loop:
 
 - `cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent`
 - Commit: `git add .cloverleaf/ && git commit -m "cloverleaf: <TASK-ID> escalated (bounce budget exhausted)"`.
-- Report: "✗ Escalated `<TASK-ID>`. Review `.cloverleaf/feedback/` and either refine the task or take over manually. Counters: reviewer=<N>, ui_reviewer=<N>, qa=<N>."
+- Report: "✗ Escalated `<TASK-ID>`. Review `.cloverleaf/feedback/` and either refine the task or take over manually. Counters: reviewer=<N>, ui_reviewer=<N>, qa=<N>, security=<N>."
 
 ## Rules
 

package/skills/cloverleaf-run-plan/SKILL.md

@@ -394,3 +394,5 @@ The concrete policy JSON is the same one used during the CLV-16..CLV-20 dogfood
 **Vocab dependency.** The walker reads `notification_contract.vocabulary` from the `start_session` response advisorily — if the expected tokens (`DONE`, `NEEDS-INPUT`) are absent it warns to stderr but continues. The authoritative source of truth for which tokens Session B will emit is the SDK's `--driven-tokens` flag passed when claw-drive spawns the session. A mismatch between the contract and the actual flag signals a version skew between the claw-drive server and the reference-impl skill; upgrade both components together to keep them in sync.
 
 **RFC-direct task participation in RFC auto-advance.** Tasks with no `parent` field but with `context.rfc` set (created via `/cloverleaf-new-task --rfc=<RFC-ID>`) are *first-class* participants in the `can_auto_advance_rfc` check. They block the advance when in-flight; they count toward delivery when merged. See `cloverleaf-cli rfc-tasks <repo_root> <RFC-ID>` for the categorized view this dispatch reads from, or `reference-impl/README.md` § "Plans vs RFC-direct tasks" for the user-facing pattern docs.
+
+**Security-review escalations.** When a task's effective `security_class` is high, `/cloverleaf-run` routes it through `security-review` off the automated-gates hub. A `blocker` finding (e.g. a leaked credential) advances the task to `escalated`, which surfaces through the walker's existing escalation path — expect and surface these like any other escalation; do not auto-retry a security blocker.

package/skills/cloverleaf-security-review/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: cloverleaf-security-review
+description: Run the Security Reviewer agent on a task in the `security-review` state. Hybrid two-pass (deterministic secret scan + LLM vulnerability judgment); emits a feedback envelope; advances to automated-gates (pass), implementing (bounce), or escalated (blocker). Usage — /cloverleaf-security-review <TASK-ID>.
+---
+
+# Cloverleaf — security review
+
+## Steps
+
+0. Pre-flight: stay on the current branch (do NOT checkout main in walker worktrees). Clean stale temp:
+   ```bash
+   rm -f /tmp/cloverleaf-fb-s.json
+   ```
+
+1. Capture the TASK-ID argument.
+
+2. Load the task: `cloverleaf-cli load-task <repo_root> <TASK-ID>`. Verify `status === "security-review"`. If not, report the current status and stop.
+
+3. Confirm the branch `cloverleaf/<TASK-ID>` exists: `git rev-parse --verify cloverleaf/<TASK-ID>`. If missing, report the discrepancy and stop. Compute the diff for the subagent (do NOT check out): `git diff main..cloverleaf/<TASK-ID>`.
+
+4. **Pass A — deterministic secret scan:**
+   ```bash
+   cloverleaf-cli secret-scan <repo_root> --branch cloverleaf/<TASK-ID>
+   ```
+   Capture the `findings[]` array (each has `severity` of `error`/`blocker`, plus `rule`, `message`, `location`).
+
+5. **Pass B — LLM judgment:** dispatch a subagent via the Task tool:
+   - `subagent_type`: `general-purpose`
+   - `model`: `sonnet`
+   - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/security-reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
+   Parse the subagent's feedback envelope (`verdict` + `findings[]`).
+
+6. **Merge + derive verdict.** Concatenate Pass A findings + Pass B findings into one `findings[]`. Derive the final verdict from the max severity across ALL findings:
+   - any `blocker` → `verdict: "escalate"`
+   - else any `error` or `warning` → `verdict: "bounce"`
+   - else (only `info`, or none) → `verdict: "pass"`
+
+7. **Branch on verdict:**
+
+   **Pass:**
+   ```bash
+   cloverleaf-cli set-task-field <repo_root> <TASK-ID> security_review_verdict pass
+   git -C <repo_root> add .cloverleaf/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security_review_verdict → pass"
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> automated-gates agent
+   git -C <repo_root> add .cloverleaf/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security review passed → automated-gates"
+   ```
+   Report: "✓ Security review passed. State → automated-gates."
+
+   **Bounce:**
+   ```bash
+   echo '<merged-envelope-json>' > /tmp/cloverleaf-fb-s.json
+   cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb-s.json
+   git -C <repo_root> add .cloverleaf/feedback/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security review feedback"
+   cloverleaf-cli set-task-field <repo_root> <TASK-ID> security_review_verdict bounce
+   git -C <repo_root> add .cloverleaf/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security_review_verdict → bounce"
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> implementing agent
+   git -C <repo_root> add .cloverleaf/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security review bounced → implementing"
+   ```
+   Report: "✗ Security review bounced. Findings: <summarize by severity>. State → implementing."
+
+   **Escalate (blocker found):**
+   ```bash
+   echo '<merged-envelope-json>' > /tmp/cloverleaf-fb-s.json
+   cloverleaf-cli write-feedback <repo_root> <TASK-ID> /tmp/cloverleaf-fb-s.json
+   git -C <repo_root> add .cloverleaf/feedback/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security review feedback"
+   cloverleaf-cli set-task-field <repo_root> <TASK-ID> security_review_verdict escalate
+   git -C <repo_root> add .cloverleaf/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security_review_verdict → escalate"
+   cloverleaf-cli advance-status <repo_root> <TASK-ID> escalated agent
+   git -C <repo_root> add .cloverleaf/ && git -C <repo_root> commit -m "cloverleaf: <TASK-ID> security review escalated (blocker finding)"
+   ```
+   Report: "⚠ Security review found a BLOCKER. State → escalated. A human must review `.cloverleaf/feedback/` before this can proceed."
+
+## Rules
+
+- Never push. Read-only on source — the security reviewer does not modify code.
+- A `blocker` (e.g. a leaked credential) ALWAYS escalates to a human; never let the bounce loop silently "fix" it.
+- On illegal state transition, report and stop without partial commits.