intentdna 1.5.9 → 1.5.10

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

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

@@ -146,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 {
@@ -345,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/flutter-rewrite.dna.yaml

@@ -316,6 +316,12 @@ workflows:
         role: surgeon
         depends_on: [investigate]
         description: "Fix identified issues. Max 5 files per round."
+        max_attempts: 3
+        on_fail: handoff
+        handoff_to: investigate
+        max_handoffs: 3
+        on_handoff_exhausted: skip
+        blocked_items_path: "docs/behavior/blocked_items.md"
         checkpoints:
           - assert: clean_working_tree
             message: "Commit all changes before proceeding"
@@ -337,9 +343,26 @@ workflows:
           produces:
             - type: git_commit
               description: "Rescue round commit"
-      - id: review
+      - id: progress_check
         role: investigator
         depends_on: [fix]
+        description: "Check test progress after surgeon's fix."
+        prompt: |
+          Run tests. Compare green count with previous round.
+          If green count increased: PROGRESS — proceed to review.
+          If green count unchanged or decreased: NO_PROGRESS — record what surgeon tried
+          and why it didn't work, for the experience chain.
+        handoff:
+          consumes:
+            - type: git_commit
+              from: fix
+              description: "Fix commit from surgeon"
+          produces:
+            - type: summary
+              description: "Progress check result (PROGRESS or NO_PROGRESS)"
+      - id: review
+        role: investigator
+        depends_on: [progress_check]
         description: "Read-only review of surgeon's changes."
         prompt: |
           Review surgeon's git diff (read-only, do NOT modify any files):
@@ -352,6 +375,9 @@ workflows:
           Verdict: REQUEST_CHANGES → describe specific problems. Next round's investigate step will include this feedback.
         handoff:
           consumes:
+            - type: summary
+              from: progress_check
+              description: "Progress check result"
             - type: git_commit
               from: fix
               description: "Committed fix from surgeon"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.5.9",
+  "version": "1.5.10",
   "description": "Intent DNA — Declarative policy layer for AI agent behavior",
   "type": "module",
   "main": "dist/index.js",