intentdna 1.5.8 → 1.5.10

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "DNA template compilation + runtime enforcement",
-      "version": "1.5.8",
+      "version": "1.5.10",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "intentdna",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "description": "Declarative policy layer for AI agent governance"
 }

package/dist/compiler/activate.d.ts

@@ -20,6 +20,7 @@ export interface ActivatedGene {
     codons: Codon[];
     tags: string[];
     expression_level: number;
+    role?: "constraint" | "workflow_hint";
 }
 /**
  * Activate a cascaded DNA for a given context and role.

package/dist/compiler/activate.js

@@ -74,6 +74,7 @@ export function activateDNA(cascaded, contextName = null, activeRole = null) {
             codons: [...gene.codons],
             tags: [...(gene.tags ?? [])],
             expression_level: 1.0,
+            role: gene.role,
         };
     }
     // Apply context modifiers if a context is active

package/dist/compiler/compile.js

@@ -55,6 +55,14 @@ function geneToDirectives(name, gene) {
     if (weights.length > 0) {
         parts.push(`Trade-offs: ${weights.join("; ")}.`);
     }
+    // For workflow_hint genes, threshold codons become prompt directives instead of gates
+    if (gene.role === "workflow_hint") {
+        for (const codon of gene.codons) {
+            if (codon.type === "threshold") {
+                parts.push(`Condition: ${codon.condition}.`);
+            }
+        }
+    }
     if (parts.length > 1) {
         directives.push({
             priority,
@@ -153,9 +161,11 @@ export function compileDNA(activated, cascaded) {
     const injections = [];
     for (const [name, gene] of Object.entries(activated.genes)) {
         directives.push(...geneToDirectives(name, gene));
-        toolFilters.push(...geneToToolFilters(name, gene));
-        gates.push(...geneToGates(name, gene));
-        validators.push(...geneToValidators(name, gene));
+        if (gene.role !== "workflow_hint") {
+            toolFilters.push(...geneToToolFilters(name, gene));
+            gates.push(...geneToGates(name, gene));
+            validators.push(...geneToValidators(name, gene));
+        }
     }
     // Compile role constraints
     let roleToolPermissions;

package/dist/compiler/workflow.js

@@ -226,7 +226,7 @@ function resolveRunIf(runIf) {
  * Map WorkflowStepDef to compiled WorkflowStep.
  */
 function toWorkflowStep(def) {
-    return {
+    const step = {
         id: def.id,
         role: def.role,
         description: def.description ?? def.id,
@@ -238,6 +238,19 @@ function toWorkflowStep(def) {
         checkpoints: def.checkpoints && def.checkpoints.length > 0 ? [...def.checkpoints] : null,
         handoff: def.handoff ?? null,
     };
+    if (def.max_attempts !== undefined)
+        step.max_attempts = def.max_attempts;
+    if (def.on_fail !== undefined)
+        step.on_fail = def.on_fail;
+    if (def.handoff_to !== undefined)
+        step.handoff_to = def.handoff_to;
+    if (def.max_handoffs !== undefined)
+        step.max_handoffs = def.max_handoffs;
+    if (def.on_handoff_exhausted !== undefined)
+        step.on_handoff_exhausted = def.on_handoff_exhausted;
+    if (def.blocked_items_path !== undefined)
+        step.blocked_items_path = def.blocked_items_path;
+    return step;
 }
 /**
  * Generate a Mermaid flowchart diagram from a WorkflowPlan.

package/dist/hooks/cli.js

@@ -15,11 +15,11 @@
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
 import { readFile, stat } from "node:fs/promises";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readStdin, writeOutput, silentOutput, allowOutput } from "./protocol.js";
-import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, } from "./enforce.js";
-import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState } from "./state.js";
+import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, } from "./enforce.js";
+import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts } from "./state.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
 const VALID_EVENTS = new Set([
@@ -160,6 +160,22 @@ async function main() {
     const start = Date.now();
     let output = dispatch(event, ir, rawInput, state);
     const durationMs = Date.now() - start;
+    // Surgeon reflection gate (PostToolUse only, async)
+    if (event === "PostToolUse") {
+        try {
+            const reflectionOutput = await handleSurgeonReflection(ir, rawInput, projectDir, sessionId);
+            if (reflectionOutput) {
+                // Merge: keep original output but append reflection warning
+                if (output.suppressOutput) {
+                    output = reflectionOutput;
+                }
+                else if (output.reason) {
+                    output = { ...output, reason: output.reason + "\n" + (reflectionOutput.reason ?? "") };
+                }
+            }
+        }
+        catch { /* fail-open */ }
+    }
     // Extract target file path for trace + pattern detection
     const toolInput = typeof rawInput.tool_input === "object" && rawInput.tool_input !== null
         ? rawInput.tool_input : undefined;
@@ -335,6 +351,125 @@ async function scanConsumedArtifactPaths(projectDir, ir, workflowName, currentSt
     }
     return paths;
 }
+// ── Surgeon Reflection Gate ──────────────────────────────
+/** Regex to parse test green count from vitest/flutter test output */
+const TEST_PASSED_RE = /(\d+)\s+(?:tests?\s+)?passed/i;
+/**
+ * Handle surgeon reflection gate for PostToolUse events.
+ * Tracks edit/test progress and warns when no progress is detected.
+ * Returns modified HookOutput with warning injected, or null to use original.
+ */
+async function handleSurgeonReflection(ir, input, projectDir, sessionId) {
+    const agentType = typeof input.agent_type === "string" ? input.agent_type : undefined;
+    if (!agentType)
+        return null;
+    const toolName = String(input.tool_name ?? "");
+    const toolOutput = typeof input.tool_output === "string" ? input.tool_output : undefined;
+    // Find if any workflow step with max_attempts matches this agent_type
+    const workflows = ir.workflows_ir;
+    if (!workflows || workflows.length === 0)
+        return null;
+    let maxAttempts;
+    let handoffTo;
+    let maxHandoffs;
+    let blockedItemsPath;
+    // Search all workflows for a step whose role matches agent_type and has max_attempts
+    // We need the original DNA step defs, which are encoded in the IR's step_enforce_rules
+    // But the original step config (max_attempts etc) isn't in the IR yet.
+    // Instead, scan workflow state to find the current step, then check if the IR source has the fields.
+    const wfState = await readWorkflowState(projectDir, sessionId);
+    if (!wfState || !wfState.active)
+        return null;
+    // Match agent_type to current role in workflow
+    const expectedAgentType = `dna-${wfState.current_role.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase()}`;
+    if (agentType !== expectedAgentType)
+        return null;
+    // Look up step config from the compiled IR's workflow
+    // We need the original step definitions — they are not directly in IR.
+    // For now, we encode max_attempts info in the IR via step_enforce_rules extension.
+    // Fallback: check if workflow state has reflection config.
+    // Since the IR doesn't carry max_attempts yet, we use a convention:
+    // The plugin-adapter will encode reflection fields into step_enforce_rules.
+    // For Phase 1, we read from a sidecar file: .dna/compiled/reflection-config.json
+    const reflectionConfig = await loadReflectionConfig(projectDir, wfState.workflow, wfState.current_step);
+    if (!reflectionConfig)
+        return null;
+    maxAttempts = reflectionConfig.max_attempts;
+    handoffTo = reflectionConfig.handoff_to;
+    maxHandoffs = reflectionConfig.max_handoffs ?? 3;
+    blockedItemsPath = reflectionConfig.blocked_items_path;
+    if (!maxAttempts)
+        return null;
+    // Read current surgeon state
+    const surgeonState = await readSurgeonAttempts(projectDir, sessionId);
+    // Track edits
+    if (toolName === "Edit") {
+        surgeonState.edit_count++;
+        await writeSurgeonAttempts(projectDir, surgeonState, sessionId);
+        return null;
+    }
+    // Track test results from Bash
+    if (toolName === "Bash" && toolOutput) {
+        const match = toolOutput.match(TEST_PASSED_RE);
+        if (!match)
+            return null; // Can't parse — fail-open
+        const greenCount = parseInt(match[1], 10);
+        surgeonState.bash_test_count++;
+        surgeonState.current_green_count = greenCount;
+        if (!surgeonState.baseline_established) {
+            surgeonState.baseline_established = true;
+            surgeonState.last_green_count = greenCount;
+            await writeSurgeonAttempts(projectDir, surgeonState, sessionId);
+            return null;
+        }
+        // Check progress: green count should increase after edits
+        if (surgeonState.edit_count >= 2 && greenCount <= surgeonState.last_green_count) {
+            surgeonState.fail_count++;
+            const result = checkReflectionLimit(surgeonState.fail_count, maxAttempts, surgeonState.handoff_count, maxHandoffs);
+            // Update last_green_count for next comparison
+            surgeonState.last_green_count = greenCount;
+            surgeonState.edit_count = 0;
+            await writeSurgeonAttempts(projectDir, surgeonState, sessionId);
+            if (result.action === "handoff" || result.action === "warn") {
+                const target = handoffTo ? ` Hand off to '${handoffTo}' for re-analysis.` : "";
+                return allowOutput(`WARN [Intent DNA] Reflection Gate: ${result.reason}${target}\n` +
+                    `Review experience_chain in .dna/state/workflow/surgeon-attempts.json before next attempt.`);
+            }
+            if (result.action === "skip") {
+                const path = blockedItemsPath ? ` Record blocked item to ${blockedItemsPath}.` : "";
+                return allowOutput(`WARN [Intent DNA] Reflection Gate: ${result.reason}${path}\n` +
+                    `SKIP this item and move to the next.`);
+            }
+        }
+        else {
+            // Progress made — reset counters
+            surgeonState.last_green_count = greenCount;
+            surgeonState.edit_count = 0;
+            if (greenCount > surgeonState.last_green_count) {
+                surgeonState.fail_count = 0;
+            }
+        }
+        await writeSurgeonAttempts(projectDir, surgeonState, sessionId);
+    }
+    return null;
+}
+/**
+ * Load reflection config for a specific workflow step.
+ * Reads from .dna/compiled/ir.json — scans workflows_ir for step metadata.
+ * Falls back to sidecar .dna/compiled/reflection-config.json for Phase 1.
+ */
+async function loadReflectionConfig(projectDir, _workflowName, _stepId) {
+    // Phase 1: read sidecar config
+    const configPath = join(projectDir, ".dna", "compiled", "reflection-config.json");
+    try {
+        const raw = await readFile(configPath, "utf-8");
+        const config = JSON.parse(raw);
+        return config[_workflowName]?.[_stepId] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 // ── Entry Point ────────────────────────────────────────────
 main().catch(() => {
     // Fail-open: never block Claude Code on unexpected errors

package/dist/hooks/enforce.d.ts

@@ -139,3 +139,12 @@ export declare function resolveToolTarget(target?: string): string[] | null;
  * Returns deduplicated list of target paths.
  */
 export declare function extractBashWritePaths(command: string): string[];
+export interface ReflectionResult {
+    action: "continue" | "warn" | "handoff" | "skip";
+    reason: string;
+}
+/**
+ * Determine the reflection gate action based on fail/handoff counts.
+ * Pure function — no I/O.
+ */
+export declare function checkReflectionLimit(failCount: number, maxAttempts: number, handoffCount: number, maxHandoffs: number): ReflectionResult;

package/dist/hooks/enforce.js

@@ -690,3 +690,16 @@ function toKebabCase(s) {
         .replace(/[_\s]+/g, "-")
         .toLowerCase();
 }
+/**
+ * Determine the reflection gate action based on fail/handoff counts.
+ * Pure function — no I/O.
+ */
+export function checkReflectionLimit(failCount, maxAttempts, handoffCount, maxHandoffs) {
+    if (failCount < maxAttempts) {
+        return { action: "continue", reason: `Attempt ${failCount + 1}/${maxAttempts}` };
+    }
+    if (handoffCount < maxHandoffs) {
+        return { action: "handoff", reason: `No progress after ${maxAttempts} attempts, handing off for re-analysis (handoff ${handoffCount + 1}/${maxHandoffs})` };
+    }
+    return { action: "skip", reason: `No progress after ${maxAttempts} attempts and ${maxHandoffs} handoffs exhausted — skipping` };
+}

package/dist/hooks/state.d.ts

@@ -30,6 +30,24 @@ export interface AuditEntry {
     message: string;
     session_id?: string;
 }
+/** Surgeon attempt state for reflection gate tracking */
+export interface SurgeonAttemptState {
+    round: number;
+    edit_count: number;
+    bash_test_count: number;
+    last_green_count: number;
+    current_green_count: number;
+    fail_count: number;
+    handoff_count: number;
+    baseline_established: boolean;
+    experience_chain: Array<{
+        round: number;
+        analysis_summary: string;
+        attempt: string;
+        result: string;
+        lesson: string;
+    }>;
+}
 /**
  * Resolve state directory path.
  * With session isolation: `.dna/state/sessions/<sessionId>/`
@@ -64,6 +82,14 @@ export declare function appendCompletedArtifact(projectDir: string, stepId: stri
 }, sessionId?: string): Promise<void>;
 /** Atomic write: write to temp file then rename. */
 export declare function atomicWrite(filePath: string, data: string): Promise<void>;
+/**
+ * Read surgeon attempt state. Returns default state if not found.
+ */
+export declare function readSurgeonAttempts(projectDir: string, sessionId?: string): Promise<SurgeonAttemptState>;
+/**
+ * Write surgeon attempt state atomically.
+ */
+export declare function writeSurgeonAttempts(projectDir: string, state: SurgeonAttemptState, sessionId?: string): Promise<void>;
 /** Trace entry for hook call observability */
 export interface TraceEntry {
     trace_id: string;

package/dist/hooks/state.js

@@ -136,6 +136,43 @@ export async function atomicWrite(filePath, data) {
     await writeFile(tmpPath, data, "utf-8");
     await rename(tmpPath, filePath);
 }
+// ── Surgeon Attempt State ────────────────────────────────
+const SURGEON_ATTEMPTS_FILE = "workflow/surgeon-attempts.json";
+function defaultSurgeonState() {
+    return {
+        round: 0,
+        edit_count: 0,
+        bash_test_count: 0,
+        last_green_count: 0,
+        current_green_count: 0,
+        fail_count: 0,
+        handoff_count: 0,
+        baseline_established: false,
+        experience_chain: [],
+    };
+}
+/**
+ * Read surgeon attempt state. Returns default state if not found.
+ */
+export async function readSurgeonAttempts(projectDir, sessionId) {
+    const stateDir = resolveStateDir(projectDir, sessionId);
+    const filePath = join(stateDir, SURGEON_ATTEMPTS_FILE);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return defaultSurgeonState();
+    }
+}
+/**
+ * Write surgeon attempt state atomically.
+ */
+export async function writeSurgeonAttempts(projectDir, state, sessionId) {
+    const stateDir = resolveStateDir(projectDir, sessionId);
+    const filePath = join(stateDir, SURGEON_ATTEMPTS_FILE);
+    await atomicWrite(filePath, JSON.stringify(state, null, 2));
+}
 const TRACE_DIR = "trace";
 const MAX_TRACE_SIZE = 10 * 1024 * 1024; // 10MB
 const TRACE_RETENTION_DAYS = 7;

package/dist/runtime/skill-adapter.js

@@ -44,6 +44,12 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
     }
     // Steps — each step MUST be executed via Agent() tool call
     const usedRoles = new Set(plan.steps.map((s) => s.role));
+    // Pre-compute handoff targets: steps that are pointed to by another step's handoff_to
+    const handoffTargets = new Set();
+    for (const step of plan.steps) {
+        if (step.handoff_to)
+            handoffTargets.add(step.handoff_to);
+    }
     lines.push("<Steps>");
     let stepNumber = 0;
     for (let i = 0; i < plan.parallel_groups.length; i++) {
@@ -58,8 +64,24 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
             const promptParts = [
                 "Do NOT spawn sub-agents.",
                 `You are the ${agentType} agent.`,
-                step.prompt || step.description,
             ];
+            // Reflection gate: inject Previous_Attempts for handoff target steps
+            if (handoffTargets.has(step.id)) {
+                promptParts.push("<Previous_Attempts>\\n" +
+                    "If this is not the first round, the workflow state contains an experience_chain " +
+                    "with previous analysis, what surgeon tried, results, and lessons learned. " +
+                    "Read the experience chain from workflow state before analyzing. " +
+                    "DO NOT repeat approaches that already failed.\\n" +
+                    "</Previous_Attempts>");
+            }
+            // Reflection gate: inject Failed_Approaches for steps with max_attempts + handoff_to
+            if (step.max_attempts && step.handoff_to) {
+                promptParts.push("<Failed_Approaches>\\n" +
+                    "If previous attempts exist in the experience chain, review what was tried " +
+                    "and why it failed. You MUST use a DIFFERENT approach.\\n" +
+                    "</Failed_Approaches>");
+            }
+            promptParts.push(step.prompt || step.description);
             const agentPrompt = escapePrompt(promptParts.join(" "));
             lines.push(`${stepNumber}. **${step.id}**${optional}`);
             lines.push(`   ${step.description}${runIf}`);
@@ -77,6 +99,18 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
                 lines.push(`   Verify produced artifacts: ${artifacts}`);
             }
             lines.push("");
+            // Reflection gate: inject Reflection_Gate after steps with max_attempts
+            if (step.max_attempts) {
+                const handoffStep = step.handoff_to ?? "previous step";
+                const maxH = step.max_handoffs ?? 3;
+                const blockedPath = step.blocked_items_path ?? "blocked_items.md";
+                lines.push(`<Reflection_Gate>`);
+                lines.push(`max_attempts=${step.max_attempts}, handoff_to=${handoffStep}, max_handoffs=${maxH}`);
+                lines.push(`No test progress after ${step.max_attempts} attempts → handoff to ${handoffStep} for re-analysis.`);
+                lines.push(`After ${maxH} handoffs with no progress → SKIP and record to ${blockedPath}.`);
+                lines.push(`</Reflection_Gate>`);
+                lines.push("");
+            }
         }
     }
     lines.push("</Steps>");
@@ -184,6 +218,12 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Variables>");
         lines.push("");
     }
+    // Workflow Boundary — prevent cross-workflow execution
+    lines.push("<Workflow_Boundary>");
+    lines.push("This workflow is COMPLETE. Do NOT proceed to any other workflow.");
+    lines.push("Report your results and STOP. The user will decide the next step.");
+    lines.push("</Workflow_Boundary>");
+    lines.push("");
     let content = lines.join("\n") + "\n";
     // Substitute project variables: {{var_name}} → value
     if (variables) {

package/dist/schema/types.d.ts

@@ -37,6 +37,7 @@ export interface Gene {
     description: string;
     codons: Codon[];
     tags?: string[];
+    role?: "constraint" | "workflow_hint";
 }
 export type ModifierAction = "amplify" | "suppress" | "activate" | "deactivate";
 export interface GeneModifier {
@@ -145,6 +146,12 @@ export interface WorkflowStepDef {
         relax_after_iteration?: number;
         additional_write_paths?: string[];
     };
+    max_attempts?: number;
+    on_fail?: "retry_with_feedback" | "handoff" | "skip";
+    handoff_to?: string;
+    max_handoffs?: number;
+    on_handoff_exhausted?: "skip" | "stop";
+    blocked_items_path?: string;
 }
 /** Top-level workflow definition */
 export interface WorkflowDef {
@@ -344,6 +351,12 @@ export interface WorkflowStep {
     completion: CompletionCheck[] | null;
     checkpoints: StepCheckpoint[] | null;
     handoff: StepHandoff | null;
+    max_attempts?: number;
+    on_fail?: "retry_with_feedback" | "handoff" | "skip";
+    handoff_to?: string;
+    max_handoffs?: number;
+    on_handoff_exhausted?: "skip" | "stop";
+    blocked_items_path?: string;
 }
 /** A group of steps that can execute in parallel */
 export interface ParallelGroup {

package/dist/schema/validate.js

@@ -235,6 +235,20 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         if (step.prompt !== undefined && (typeof step.prompt !== "string" || !step.prompt)) {
             errors.push({ path: `${stepPath}.prompt`, message: "prompt must be a non-empty string" });
         }
+        // on_fail: must be a valid enum value
+        if (step.on_fail !== undefined) {
+            const validOnFail = ["retry_with_feedback", "handoff", "skip"];
+            if (!validOnFail.includes(step.on_fail)) {
+                errors.push({ path: `${stepPath}.on_fail`, message: `must be one of: ${validOnFail.join(", ")}` });
+            }
+        }
+        // on_handoff_exhausted: must be a valid enum value
+        if (step.on_handoff_exhausted !== undefined) {
+            const validExhausted = ["skip", "stop"];
+            if (!validExhausted.includes(step.on_handoff_exhausted)) {
+                errors.push({ path: `${stepPath}.on_handoff_exhausted`, message: `must be one of: ${validExhausted.join(", ")}` });
+            }
+        }
         // isolation: must be a valid enum value
         if (step.isolation !== undefined) {
             const validIsolation = ["none", "worktree", "auto"];
@@ -292,6 +306,18 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
                 });
             }
         }
+        // handoff_to: must reference an existing step in this workflow
+        if (step.handoff_to !== undefined) {
+            if (typeof step.handoff_to !== "string" || !step.handoff_to) {
+                errors.push({ path: `${stepPath}.handoff_to`, message: "handoff_to must be a non-empty string" });
+            }
+            else if (!stepIds.has(step.handoff_to)) {
+                errors.push({
+                    path: `${stepPath}.handoff_to`,
+                    message: `step '${step.handoff_to}' not found in workflow`,
+                });
+            }
+        }
     }
     // Validate default_isolation
     if (workflow.default_isolation !== undefined) {

package/dist/templates/code-cleanup.dna.yaml

@@ -0,0 +1,152 @@
+version: "0.1.0"
+id: template_code_cleanup
+name: Code Cleanup (Regression-Safe)
+type: project
+namespace: cc
+
+cascade:
+  inherits: ["species:default"]
+  priority: 100
+
+genes:
+  test_between_passes:
+    description: Tests must pass between each cleanup pass
+    codons:
+      - type: threshold
+        condition: "tests_passing == true"
+        action: block
+      - type: attract
+        target: run_tests_after_each_pass
+
+  no_behavior_change:
+    description: Cleanup must not change observable behavior
+    codons:
+      - type: threshold
+        condition: "behavior_changed == false"
+        action: block
+      - type: repel
+        target: modify_public_api
+      - type: attract
+        target: same_inputs_same_outputs
+
+  smell_focused:
+    description: Clean by smell type in order - dead code, duplication, naming
+    role: workflow_hint
+    codons:
+      - type: attract
+        target: categorize_before_cleaning
+      - type: attract
+        target: one_smell_type_per_pass
+
+  minimal_cleanup:
+    description: Each pass focuses on one type of issue
+    codons:
+      - type: attract
+        target: single_concern_per_pass
+      - type: repel
+        target: mixed_cleanup_types
+      - type: threshold
+        condition: "files_changed_per_pass <= 10"
+        action: escalate
+
+contexts: {}
+
+roles:
+  analyzer:
+    description: Analyzes code for cleanup opportunities. Read-only.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash]
+      deny: [Edit, Write, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: []
+    instructions:
+      - Classify code smells by type (dead code, duplication, naming, complexity)
+      - Prioritize by impact and risk
+      - Do NOT suggest behavioral changes
+      - Output a categorized cleanup plan
+
+  cleaner:
+    description: Executes cleanup changes. Can modify code.
+    tool_permissions:
+      allow: [Read, Edit, Write, Grep, Glob, Bash]
+    scope:
+      read: ["**/*"]
+      write: ["src/**", "lib/**"]
+    instructions:
+      - Follow the analyzer's cleanup plan
+      - One smell type per pass
+      - Run tests after each file change
+      - Revert if tests fail
+      - Do not change public APIs or observable behavior
+      - Commit after each successful pass
+
+  reviewer:
+    description: Reviews cleanup changes for correctness. Read-only.
+    tool_permissions:
+      allow: [Read, Grep, Glob, Bash]
+      deny: [Edit, Write, NotebookEdit]
+    scope:
+      read: ["**/*"]
+      write: []
+    instructions:
+      - Review git diff for each cleanup pass
+      - Verify no behavioral changes
+      - Check test coverage unchanged
+      - "Verdict: APPROVE or REQUEST_CHANGES"
+
+workflows:
+  cleanup:
+    name: Code Cleanup
+    description: "Regression-safe code cleanup: analyze, classify, clean by smell type, verify"
+    steps:
+      - id: lock_behavior
+        role: analyzer
+        description: "Assess current test coverage and establish behavior baseline."
+        prompt: |
+          Run existing tests to establish baseline.
+          Record: total tests, passing, failing.
+          If test coverage is insufficient, warn before proceeding.
+          Output: baseline test results + coverage assessment.
+
+      - id: classify
+        role: analyzer
+        depends_on: [lock_behavior]
+        description: "Scan codebase and categorize code smells."
+        prompt: |
+          Scan the codebase for code smells. Categorize:
+          1. Dead code (unused imports, unreachable branches, commented-out code)
+          2. Duplication (copy-paste patterns, similar functions)
+          3. Naming (unclear names, inconsistent conventions)
+          4. Complexity (long functions, deep nesting)
+
+          Prioritize: dead code first (safest), then duplication, then naming.
+          Output: categorized cleanup plan with file paths and line numbers.
+
+      - id: clean
+        role: cleaner
+        depends_on: [classify]
+        description: "Execute cleanup one smell type at a time."
+        prompt: |
+          Follow the cleanup plan. Rules:
+          - One smell type per pass (start with dead code)
+          - Run tests after each file change
+          - If tests fail: revert immediately, report the issue
+          - Maximum 10 files per pass
+          - Commit after each successful pass: "cleanup($TYPE): description"
+          - Do NOT change any public API signatures
+          - Do NOT rename exported symbols
+          - Do NOT modify test files (unless removing dead test helpers)
+
+      - id: verify
+        role: reviewer
+        depends_on: [clean]
+        description: "Verify cleanup preserved behavior."
+        prompt: |
+          Review all cleanup changes (git diff from baseline):
+          1. Any behavioral changes? (API signatures, return values, side effects)
+          2. Test count unchanged or increased?
+          3. All tests still passing?
+          4. No unintended file modifications?
+
+          Verdict: APPROVE (cleanup complete) or REQUEST_CHANGES (list issues)