@cloverleaf/reference-impl 0.8.0 → 0.8.2

package/README.md

@@ -211,6 +211,8 @@ The **Security Reviewer** (8th agent) runs when a task's effective `security_cla
 
 **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.8.0
+0.8.2

package/dist/cli.mjs

@@ -40,10 +40,11 @@
  *   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';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import { loadTask, saveTask } from './task.mjs';
 import { advanceStatus } from './task.mjs';
 import { emitGateDecision } from './events.mjs';
@@ -65,10 +66,10 @@ import { buildBaselinePath } from './visual-diff.mjs';
 import { computeReadyTasks, detectCycle } from './dag-walker.mjs';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.mjs';
 import { loadWalkerConfig } from './walker-config.mjs';
-import { classifyFiles } from './scope-check.mjs';
+import { classifyFiles, normalizePath } from './scope-check.mjs';
 import { computeRfcTasksView } from './rfc-tasks.mjs';
 import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.mjs';
-import { loadSecurityPathsConfig, computeSecurityClassification } from './security-classify.mjs';
+import { classifyTaskSecurity } from './security-classify.mjs';
 function die(msg, code = 1) {
     process.stderr.write(msg + '\n');
     process.exit(code);
@@ -112,7 +113,8 @@ function usage(msg) {
         '  check-scope <repoRoot> <taskId> --branch <branchName>\n' +
         '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n' +
         '  secret-scan <repoRoot> --branch <branch>\n' +
-        '  classify-security <repoRoot> <taskId> [--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;
@@ -650,8 +652,29 @@ try {
             catch {
                 // No diff is fine (empty branch)
             }
-            // 4. Classify and output
-            const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes);
+            // 4. Compute sharedFiles via git check-attr (merge=union honors user's multi-writer intent)
+            let sharedFiles = new Set();
+            if (modifiedFiles.length > 0) {
+                try {
+                    const out = execFileSync('git', ['-C', repoRoot, 'check-attr', '-z', 'merge', '--', ...modifiedFiles], { encoding: 'utf-8' });
+                    // -z output: NUL-separated triplets: path\0attr\0value\0
+                    const parts = out.split('\0');
+                    for (let i = 0; i + 2 < parts.length; i += 3) {
+                        const path = parts[i];
+                        const attr = parts[i + 1];
+                        const value = parts[i + 2];
+                        if (attr === 'merge' && value === 'union') {
+                            sharedFiles.add(normalizePath(path));
+                        }
+                    }
+                }
+                catch (err) {
+                    process.stderr.write(`cloverleaf-cli check-scope: git check-attr failed (${err instanceof Error ? err.message : String(err)}); proceeding with no shared-file annotations.\n`);
+                    sharedFiles = new Set();
+                }
+            }
+            // 5. Classify and output
+            const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes, sharedFiles);
             process.stdout.write(JSON.stringify(result) + '\n');
             process.exit(0);
         }
@@ -762,31 +785,42 @@ try {
             const [repoRoot, taskId] = positional;
             if (!repoRoot || !taskId)
                 usage('classify-security <repoRoot> <taskId> [--branch <branch>]');
-            let task;
+            let result;
             try {
-                task = loadTask(repoRoot, taskId);
+                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);
             }
-            const declared = task.security_class === 'high' ? 'high' : 'low';
-            const cfg = loadSecurityPathsConfig(repoRoot);
-            let changed = [];
-            if (branch) {
-                const out = execSync(`git -C ${repoRoot} diff --name-only main..${branch}`, { encoding: 'utf-8' });
-                changed = out.split('\n').filter(Boolean);
-            }
-            const result = computeSecurityClassification(declared, changed, cfg);
             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/scope-check.mjs

@@ -37,7 +37,7 @@
  *  - Strip trailing `/` (preserving a non-empty result)
  *  - Return the resulting string (may be empty for degenerate inputs; caller filters)
  */
-function normalizePath(p) {
+export function normalizePath(p) {
     let s = p.trim().replace(/\\/g, '/');
     // Strip leading `./` repeatedly
     while (s.startsWith('./')) {
@@ -71,7 +71,7 @@ function normalizePaths(paths) {
  * @param siblingScopes - Other tasks in the same Plan with their declared files.
  * @returns             - { contested, own, extension } with arrays sorted by file path.
  */
-export function classifyFiles(taskDoc, modifiedFiles, siblingScopes) {
+export function classifyFiles(taskDoc, modifiedFiles, siblingScopes, sharedFiles) {
     // 1. Normalize own files from taskDoc.scope.files_touched
     const scope = taskDoc['scope'];
     const rawOwn = Array.isArray(scope?.['files_touched'])
@@ -117,6 +117,11 @@ export function classifyFiles(taskDoc, modifiedFiles, siblingScopes) {
         if (ownSet.has(f)) {
             own.push(f);
         }
+        else if (sharedFiles?.has(f)) {
+            // merge=union (or other shared-intent annotation): never contested.
+            // Falls into extension so post-merge auto-extend picks it up.
+            extension.push(f);
+        }
         else if (siblingMap.has(f)) {
             const owners = siblingMap.get(f);
             contested.push({ file: f, owner: owners[0] }); // lex-smallest wins

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

@@ -40,11 +40,12 @@
  *   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';
 import { dirname, join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import { loadTask, saveTask } from './task.js';
 import { advanceStatus } from './task.js';
 import { emitGateDecision } from './events.js';
@@ -67,11 +68,11 @@ import { buildBaselinePath } from './visual-diff.js';
 import { computeReadyTasks, detectCycle } from './dag-walker.js';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.js';
 import { loadWalkerConfig } from './walker-config.js';
-import { classifyFiles } from './scope-check.js';
+import { classifyFiles, normalizePath } 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 { loadSecurityPathsConfig, computeSecurityClassification } from './security-classify.js';
+import { classifyTaskSecurity } from './security-classify.js';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(msg + '\n');
@@ -117,7 +118,8 @@ function usage(msg?: string): never {
       '  check-scope <repoRoot> <taskId> --branch <branchName>\n' +
       '  extend-scope <repoRoot> <taskId> --add <file>... --reason <text>\n' +
       '  secret-scan <repoRoot> --branch <branch>\n' +
-      '  classify-security <repoRoot> <taskId> [--branch <branch>]\n'
+      '  classify-security <repoRoot> <taskId> [--branch <branch>]\n' +
+      '  set-task-field <repoRoot> <taskId> <field> <value>\n'
   );
   process.exit(2);
 }
@@ -661,8 +663,35 @@ try {
         // No diff is fine (empty branch)
       }
 
-      // 4. Classify and output
-      const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes);
+      // 4. Compute sharedFiles via git check-attr (merge=union honors user's multi-writer intent)
+      let sharedFiles = new Set<string>();
+      if (modifiedFiles.length > 0) {
+        try {
+          const out = execFileSync(
+            'git',
+            ['-C', repoRoot, 'check-attr', '-z', 'merge', '--', ...modifiedFiles],
+            { encoding: 'utf-8' },
+          );
+          // -z output: NUL-separated triplets: path\0attr\0value\0
+          const parts = out.split('\0');
+          for (let i = 0; i + 2 < parts.length; i += 3) {
+            const path = parts[i];
+            const attr = parts[i + 1];
+            const value = parts[i + 2];
+            if (attr === 'merge' && value === 'union') {
+              sharedFiles.add(normalizePath(path));
+            }
+          }
+        } catch (err) {
+          process.stderr.write(
+            `cloverleaf-cli check-scope: git check-attr failed (${err instanceof Error ? err.message : String(err)}); proceeding with no shared-file annotations.\n`,
+          );
+          sharedFiles = new Set();
+        }
+      }
+
+      // 5. Classify and output
+      const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes, sharedFiles);
       process.stdout.write(JSON.stringify(result) + '\n');
       process.exit(0);
     }
@@ -777,30 +806,44 @@ try {
       const branch = branchIdx >= 0 ? rest[branchIdx + 1] : undefined;
       const [repoRoot, taskId] = positional;
       if (!repoRoot || !taskId) usage('classify-security <repoRoot> <taskId> [--branch <branch>]');
-      let task;
+      let result;
       try {
-        task = loadTask(repoRoot, taskId);
+        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);
       }
-      const declared = (task as Record<string, unknown>).security_class === 'high' ? 'high' : 'low';
-      const cfg = loadSecurityPathsConfig(repoRoot);
-      let changed: string[] = [];
-      if (branch) {
-        const out = execSync(`git -C ${repoRoot} diff --name-only main..${branch}`, { encoding: 'utf-8' });
-        changed = out.split('\n').filter(Boolean);
-      }
-      const result = computeSecurityClassification(declared, changed, cfg);
       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/scope-check.ts

@@ -56,7 +56,7 @@ export interface SiblingScope {
  *  - Strip trailing `/` (preserving a non-empty result)
  *  - Return the resulting string (may be empty for degenerate inputs; caller filters)
  */
-function normalizePath(p: string): string {
+export function normalizePath(p: string): string {
   let s = p.trim().replace(/\\/g, '/');
   // Strip leading `./` repeatedly
   while (s.startsWith('./')) {
@@ -93,7 +93,8 @@ function normalizePaths(paths: string[]): string[] {
 export function classifyFiles(
   taskDoc: TaskDoc,
   modifiedFiles: string[],
-  siblingScopes: SiblingScope[]
+  siblingScopes: SiblingScope[],
+  sharedFiles?: Set<string>
 ): ClassifyResult {
   // 1. Normalize own files from taskDoc.scope.files_touched
   const scope = taskDoc['scope'] as Record<string, unknown> | undefined;
@@ -138,6 +139,10 @@ export function classifyFiles(
   for (const f of filteredModified) {
     if (ownSet.has(f)) {
       own.push(f);
+    } else if (sharedFiles?.has(f)) {
+      // merge=union (or other shared-intent annotation): never contested.
+      // Falls into extension so post-merge auto-extend picks it up.
+      extension.push(f);
     } else if (siblingMap.has(f)) {
       const owners = siblingMap.get(f)!;
       contested.push({ file: f, owner: owners[0] }); // lex-smallest wins

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.8.0",
+  "version": "0.8.2",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,9 @@
     "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.7.0",
     "ajv": "^8.17.1",

package/prompts/security-reviewer.md

@@ -24,6 +24,18 @@ Examine the changed code for:
 
 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:

package/skills/cloverleaf-run/SKILL.md

@@ -35,13 +35,22 @@ Parse the JSON. If `classify-security` exits non-zero or emits unparseable outpu
 If `effective == "low"` → skip the gate, proceed with the lane.
 
 If `effective == "high"`:
-- If `declared == "low"` (under-classification: `diff_detected` true), write back: load the task, set `security_class: "high"`, save it, then commit `cloverleaf: <TASK-ID> security_class → high (diff-detected)`.
+- 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.

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

@@ -39,6 +39,8 @@ description: Run the Security Reviewer agent on a task in the `security-review`
 
    **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"
    ```
@@ -49,6 +51,8 @@ description: Run the Security Reviewer agent on a task in the `security-review`
    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"
    ```
@@ -59,6 +63,8 @@ description: Run the Security Reviewer agent on a task in the `security-review`
    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)"
    ```