intentdna 1.5.21 → 1.6.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "Declarative policy layer for AI agent behavior with plugin-managed hook runtime for Claude Code.",
-      "version": "1.5.21",
+      "version": "1.6.1",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.5.21"
+  "version": "1.6.1"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.5.21",
+  "version": "1.6.1",
   "description": "Declarative policy layer for AI agent behavior",
   "author": {
     "name": "Samuel"

package/dist/cli/commands/sync.js

@@ -20,7 +20,7 @@ import { parseYAML } from "../../schema/yaml-parser.js";
 import { compileToMarkdown, injectIntoFile, removeFromFile } from "../../runtime/markdown.js";
 import { compileAllRolesToAgentMD, writeAgentMDFiles, removeAgentMDFiles } from "../../runtime/agent-md.js";
 import { removeWorkflowScripts } from "../../runtime/workflow-runner.js";
-import { compileWorkflowToSkill, writeSkillFiles } from "../../runtime/skill-adapter.js";
+import { compileWorkflowToSkill, compileControllerToSkill, writeSkillFiles } from "../../runtime/skill-adapter.js";
 import { compilePluginSettings, detectEnabledEvents, mergeSettingsFile, recommendHookTimeouts } from "../../runtime/settings-adapter.js";
 import { createCompiledIR, writeCompiledIR } from "../../runtime/plugin-adapter.js";
 import { cascadeDNA } from "../../compiler/cascade.js";
@@ -127,11 +127,9 @@ export async function cleanStaleDNAFiles(dir, type, activeNamespaces) {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = resolve(dir, entry.name);
-            // Extract namespace from filename: dna-{namespace}-*
-            const nsMatch = entry.name.match(/^dna-([a-z0-9_-]+)-/);
-            const fileNamespace = nsMatch ? nsMatch[1] : null;
-            // Skip if namespace doesn't match active namespaces
-            if (!fileNamespace || !activeNamespaces.includes(fileNamespace)) {
+            // Match active namespace prefixes directly so multi-hyphen names like
+            // dna-frw-fix-loop still resolve to namespace frw.
+            if (!activeNamespaces.some(ns => entry.name.startsWith(`dna-${ns}-`))) {
                 continue;
             }
             if (type === "agents" && entry.isFile() && entry.name.endsWith(".md")) {
@@ -653,6 +651,7 @@ export async function runSync(opts) {
             const dnas = loadedDNAs;
             const cascadedForSkills = cascadeDNA(dnas);
             const workflows = cascadedForSkills.workflows;
+            const controllers = cascadedForSkills.controllers;
             const roles = cascadedForSkills.roles;
             // Collect and resolve variables from all DNA files
             const rawVars = {};
@@ -676,8 +675,8 @@ export async function runSync(opts) {
                     process.stderr.write(`MCP: wrote ${Object.keys(mcpDeps).length} server(s) to ${mcpJsonPath}\n`);
                 }
             }
-            if (Object.keys(workflows).length === 0) {
-                process.stderr.write("No workflow defined — no skills to generate\n");
+            if (Object.keys(workflows).length === 0 && Object.keys(controllers).length === 0) {
+                process.stderr.write("No workflow or controller defined — no skills to generate\n");
             }
             else {
                 const { compileWorkflow } = await import("../../compiler/workflow.js");
@@ -688,6 +687,9 @@ export async function runSync(opts) {
                         skillResults.push(compileWorkflowToSkill(result.plan, roles, ir, variables));
                     }
                 }
+                for (const [name, controllerDef] of Object.entries(controllers)) {
+                    skillResults.push(compileControllerToSkill(name, controllerDef, variables, workflows));
+                }
                 if (skillResults.length > 0) {
                     const written = await writeSkillFiles(skillResults, opts.skillsDir);
                     process.stderr.write(`Generated ${written.length} skill file(s) in ${opts.skillsDir}\n`);

package/dist/compiler/cascade.d.ts

@@ -10,12 +10,13 @@
  *   - attract/repel: same target accumulates, different targets independent
  *   - amplify/suppress: factors multiply (1.5x × 2.0x = 3.0x)
  */
-import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef, LegibilityAssetMap, VerifierCommandPolicy } from "../schema/types.js";
+import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef, LegibilityAssetMap, VerifierCommandPolicy, ControllerDef } from "../schema/types.js";
 export interface CascadedDNA {
     genes: Record<string, Gene>;
     contexts: Record<string, ContextRegion>;
     roles: Record<string, RoleDef>;
     workflows: Record<string, WorkflowDef>;
+    controllers: Record<string, ControllerDef>;
     epigenetic_markers: EpigeneticMarker[];
     source_ids: string[];
     /** Warnings from cascade process (e.g., cross-namespace gene collisions) */

package/dist/compiler/cascade.js

@@ -91,6 +91,20 @@ function prefixRecordKeys(record, ns) {
         return record;
     return Object.fromEntries(Object.entries(record).map(([key, value]) => [`${ns}_${key}`, value]));
 }
+function prefixController(controller, ns) {
+    return {
+        ...controller,
+        diagnosis_workflow: `${ns}_${controller.diagnosis_workflow}`,
+        fix_workflow: `${ns}_${controller.fix_workflow}`,
+        roles: {
+            analyzer: `${ns}_${controller.roles.analyzer}`,
+            analysis_reviewer: `${ns}_${controller.roles.analysis_reviewer}`,
+            surgeon: `${ns}_${controller.roles.surgeon}`,
+            fix_reviewer: `${ns}_${controller.roles.fix_reviewer}`,
+            test_runner: `${ns}_${controller.roles.test_runner}`,
+        },
+    };
+}
 function prefixLegibilityAssets(map, ns) {
     if (!map)
         return undefined;
@@ -176,6 +190,7 @@ export function cascadeDNA(layers) {
     const mergedContexts = {};
     const mergedRoles = {};
     const mergedWorkflows = {};
+    const mergedControllers = {};
     const allMarkers = [];
     const sourceIds = [];
     const warnings = [];
@@ -225,6 +240,15 @@ export function cascadeDNA(layers) {
                 mergedWorkflows[name] = wf;
             }
         }
+        // Merge controllers: namespace-prefixed keys + workflow/role references
+        for (const [name, controller] of Object.entries(dna.controllers ?? {})) {
+            if (ns) {
+                mergedControllers[`${ns}_${name}`] = prefixController(controller, ns);
+            }
+            else {
+                mergedControllers[name] = controller;
+            }
+        }
         // Collect epigenetic markers
         if (dna.epigenetic?.markers) {
             allMarkers.push(...dna.epigenetic.markers);
@@ -250,6 +274,7 @@ export function cascadeDNA(layers) {
         contexts: mergedContexts,
         roles: mergedRoles,
         workflows: mergedWorkflows,
+        controllers: mergedControllers,
         epigenetic_markers: allMarkers,
         source_ids: sourceIds,
         warnings: warnings.length > 0 ? warnings : undefined,

package/dist/hooks/enforce.d.ts

@@ -114,7 +114,7 @@ export declare function enforceHandoffProduces(ir: ConstraintIR, wfState: {
     workflow: string;
     artifact_facts?: ArtifactFact[];
 }): EnforceResult | null;
-/** Check if a file path is allowed by a list of write globs (prefix matching). */
+/** Check if a file path is allowed by a list of write globs. */
 export declare function checkWriteAllowed(filePath: string, allowedGlobs: string[]): boolean;
 /**
  * Extract directory prefix from a glob pattern.

package/dist/hooks/enforce.js

@@ -439,7 +439,7 @@ function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = []) {
         const filePath = extractFilePath(input);
         if (!filePath)
             return null;
-        return checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePaths);
+        return checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePaths, true);
     }
     // Bash: extract potential write targets from command
     if (input.tool_name === "Bash") {
@@ -450,7 +450,7 @@ function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = []) {
         if (writePaths.length === 0)
             return null;
         for (const p of writePaths) {
-            const result = checkPathAgainstScope(rolesScopeMap, input, p, additionalWritePaths);
+            const result = checkPathAgainstScope(rolesScopeMap, input, p, additionalWritePaths, false);
             if (result)
                 return result;
         }
@@ -459,7 +459,7 @@ function enforceRoleScope(rolesScopeMap, input, additionalWritePaths = []) {
     return null;
 }
 /** Check a single file path against role scope. Shared by Write tools and Bash. */
-function checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePaths = []) {
+function checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePaths = [], blockViolation = true) {
     const cwd = input.cwd;
     let relativePath = cwd && filePath.startsWith("/") ? relative(cwd, filePath) : filePath;
     // Normalize to resolve traversal (e.g., "src/../../test/x.ts" → "../test/x.ts")
@@ -474,10 +474,16 @@ function checkPathAgainstScope(rolesScopeMap, input, filePath, additionalWritePa
             ? [...writeGlobs, ...additionalWritePaths]
             : writeGlobs;
         if (allWriteGlobs.length === 0) {
-            return allowOutput(`WARN [Intent DNA]: Role '${entry.role_name}' has no write permission (path: ${filePath}). Merge-time scope gate will filter.`);
+            const message = `Role '${entry.role_name}' has no write permission (path: ${filePath}).`;
+            return blockViolation
+                ? blockOutput(`[Intent DNA]: ${message}`)
+                : allowOutput(`WARN [Intent DNA]: ${message}`);
         }
         if (!checkWriteAllowed(relativePath, allWriteGlobs)) {
-            return allowOutput(`WARN [Intent DNA]: Role '${entry.role_name}' cannot write to '${filePath}' (allowed: ${allWriteGlobs.join(", ")}). Merge-time scope gate will filter.`);
+            const message = `Role '${entry.role_name}' cannot write to '${filePath}' (allowed: ${allWriteGlobs.join(", ")}).`;
+            return blockViolation
+                ? blockOutput(`[Intent DNA]: ${message}`)
+                : allowOutput(`WARN [Intent DNA]: ${message}`);
         }
         return null; // Role matched, write allowed
     }
@@ -565,20 +571,48 @@ function enforceOutputSchema(roles, input) {
     return null;
 }
 // ── Public Helpers ──────────────────────────────────────────
-/** Check if a file path is allowed by a list of write globs (prefix matching). */
+/** Check if a file path is allowed by a list of write globs. */
 export function checkWriteAllowed(filePath, allowedGlobs) {
+    const normalizedPath = normalize(filePath).replace(/\\/g, "/");
     for (const glob of allowedGlobs) {
-        const prefix = globToPrefix(glob);
-        if (prefix.length === 0)
-            return true; // Root glob like "*.md" — allow all
-        if (filePath.startsWith(prefix))
-            return true;
-        // Also check exact match for non-glob patterns
-        if (!glob.includes("*") && filePath === glob)
+        const normalizedGlob = normalize(glob).replace(/\\/g, "/");
+        if (normalizedGlob.includes("*")) {
+            if (globToRegExp(normalizedGlob).test(normalizedPath))
+                return true;
+            continue;
+        }
+        if (normalizedPath.startsWith(normalizedGlob))
             return true;
     }
     return false;
 }
+function globToRegExp(glob) {
+    let source = "^";
+    for (let i = 0; i < glob.length; i++) {
+        const char = glob[i];
+        if (char === "*") {
+            if (glob[i + 1] === "*") {
+                if (glob[i + 2] === "/") {
+                    source += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    source += ".*";
+                    i += 1;
+                }
+            }
+            else {
+                source += "[^/]*";
+            }
+            continue;
+        }
+        source += escapeRegExp(char);
+    }
+    return new RegExp(`${source}$`);
+}
+function escapeRegExp(char) {
+    return char.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
+}
 /**
  * Extract directory prefix from a glob pattern.
  * "src/**\/*.ts" → "src/"
@@ -649,7 +683,9 @@ function isWriteTool(toolName) {
     return WRITE_TOOLS.has(toolName);
 }
 function extractFilePath(input) {
-    const fp = input.tool_input.file_path;
+    const fp = input.tool_name === "NotebookEdit"
+        ? input.tool_input.notebook_path
+        : input.tool_input.file_path;
     if (typeof fp === "string" && fp)
         return fp;
     return null;

package/dist/runtime/skill-adapter.d.ts

@@ -6,13 +6,14 @@
  *
  * Skills are compiled views of DNA's structured definitions — not stored content.
  */
-import type { WorkflowPlan, RoleDef, ConstraintIR } from "../schema/types.js";
+import type { WorkflowPlan, WorkflowDef, RoleDef, ConstraintIR, ControllerDef } from "../schema/types.js";
 export interface SkillResult {
     name: string;
     fileName: string;
     dirName: string;
     content: string;
 }
+export declare function compileControllerToSkill(controllerKey: string, controller: ControllerDef, variables?: Record<string, string>, workflows?: Record<string, WorkflowDef>): SkillResult;
 /**
  * Compile a WorkflowPlan + roles + IR into a SKILL.md file.
  * Variables from DNA config are substituted into prompts and descriptions.

package/dist/runtime/skill-adapter.js

@@ -10,6 +10,170 @@ import { mkdir, writeFile, readdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { toKebabCase } from "./agent-md.js";
 const SENTINEL = "<!-- intentdna:managed — do not edit manually -->";
+// ── Compile Controller → Skill ─────────────────────────────
+export function compileControllerToSkill(controllerKey, controller, variables, workflows) {
+    if (controller.kind !== "flutter_rewrite_fix_loop") {
+        throw new Error(`Unsupported controller kind: ${controller.kind}`);
+    }
+    const skillName = `dna-${toKebabCase(controllerKey)}`;
+    const analyzerAgent = `dna-${toKebabCase(controller.roles.analyzer)}`;
+    const analysisReviewerAgent = `dna-${toKebabCase(controller.roles.analysis_reviewer)}`;
+    const surgeonAgent = `dna-${toKebabCase(controller.roles.surgeon)}`;
+    const fixReviewerAgent = `dna-${toKebabCase(controller.roles.fix_reviewer)}`;
+    const testRunnerAgent = `dna-${toKebabCase(controller.roles.test_runner)}`;
+    const diagnosisWorkflow = workflows?.[controller.diagnosis_workflow];
+    const fixWorkflow = workflows?.[controller.fix_workflow];
+    const diagnosisAnalyzeStep = requireStepByRole(diagnosisWorkflow, controller.roles.analyzer, controller.diagnosis_workflow);
+    const diagnosisReviewStep = requireStepByRole(diagnosisWorkflow, controller.roles.analysis_reviewer, controller.diagnosis_workflow);
+    const fixBugsStep = requireStepByRole(fixWorkflow, controller.roles.surgeon, controller.fix_workflow);
+    const reviewChangesStep = requireStepByRole(fixWorkflow, controller.roles.fix_reviewer, controller.fix_workflow);
+    const verifyReportStep = requireStepByRole(fixWorkflow, controller.roles.test_runner, controller.fix_workflow);
+    const stepPrompt = (step) => step.prompt || step.description || "";
+    const lines = [];
+    lines.push("---");
+    lines.push(`name: ${skillName}`);
+    lines.push(`description: "Use when user says /${skillName}. ${escapeYaml(controller.description || controller.name)}"`);
+    lines.push("user-invocable: true");
+    lines.push("triggers:");
+    lines.push(`  - "${toKebabCase(controllerKey)}"`);
+    lines.push(`  - "run ${toKebabCase(controllerKey)}"`);
+    lines.push("---");
+    lines.push("");
+    lines.push(SENTINEL);
+    lines.push(`<!-- Compiled: ${new Date().toISOString()} -->`);
+    lines.push("");
+    lines.push(`# /${skillName} <module>`);
+    lines.push("");
+    lines.push("<Purpose>");
+    lines.push(controller.description || controller.name);
+    lines.push("</Purpose>");
+    lines.push("");
+    lines.push("<Controller>");
+    lines.push("kind: flutter_rewrite_fix_loop");
+    lines.push(`max_rounds: ${controller.max_rounds}`);
+    lines.push(`diagnosis_workflow: ${controller.diagnosis_workflow}`);
+    lines.push(`fix_workflow: ${controller.fix_workflow}`);
+    lines.push(`progress_artifact_path: ${controller.progress_artifact_path}`);
+    lines.push("</Controller>");
+    lines.push("");
+    lines.push("<Steps>");
+    lines.push("0. Validate the module argument before using it in any artifact path.");
+    lines.push("   - The module argument must match /^[A-Za-z0-9_-]+$/.");
+    lines.push("   - If it contains '/', '.', '..', spaces, braces, glob characters, or path separators, stop with the Chinese report format.");
+    lines.push("   - Do not read or write controller artifacts until the module argument is safe.");
+    lines.push("1. Check diagnosis artifact freshness before any fix round.");
+    lines.push(`   - Diagnosis artifact: ${controller.diagnosis_artifact_path}`);
+    lines.push(`   - Diagnosis review artifact: ${controller.diagnosis_review_artifact_path}`);
+    lines.push("2. Create a stable controller_run_id once for this invocation before using any artifact path.");
+    lines.push("   - Reuse the same controller_run_id in every child Agent prompt and in every progress validation.");
+    lines.push("   - Do not regenerate controller_run_id inside fix rounds.");
+    lines.push("3. Reuse diagnosis only when all diagnosis reuse criteria pass:");
+    lines.push(`   - ${controller.diagnosis_artifact_path} exists`);
+    lines.push(`   - ${controller.diagnosis_review_artifact_path} exists and verdict is APPROVE`);
+    lines.push("   - behavior doc is not newer than diagnosis spec");
+    lines.push("   - baseline artifact is not newer than diagnosis spec");
+    lines.push("   - user did not explicitly pass reanalyze or scope changed");
+    lines.push("   - progress JSON does not say diagnosis_invalid");
+    lines.push(`4. If diagnosis is missing, invalid, stale, or scope-changed, run diagnosis once with fresh context and sequential gates:`);
+    lines.push("   a. Spawn fresh analyzer agent with controller_run_id, then wait for completion.");
+    lines.push("   ```");
+    lines.push("   Agent(");
+    lines.push(`     subagent_type="${analyzerAgent}",`);
+    lines.push(`     prompt="controller_run_id=<controller_run_id>. ${escapePrompt(stepPrompt(diagnosisAnalyzeStep))}"`);
+    lines.push("   )");
+    lines.push("   ```");
+    lines.push(`   b. Diagnosis artifact gate: read ${controller.diagnosis_artifact_path}; validate it exists, is non-empty, names the safe module argument, and is current for this module before continuing.`);
+    lines.push("   c. Spawn fresh analysis_reviewer agent with controller_run_id, then wait for completion.");
+    lines.push("   ```");
+    lines.push("   Agent(");
+    lines.push(`     subagent_type="${analysisReviewerAgent}",`);
+    lines.push(`     prompt="controller_run_id=<controller_run_id>; expected_review_artifact=${controller.diagnosis_review_artifact_path}. ${escapePrompt(stepPrompt(diagnosisReviewStep))}"`);
+    lines.push("   )");
+    lines.push("   ```");
+    lines.push(`   d. Diagnosis review JSON gate: read ${controller.diagnosis_review_artifact_path}; require existing valid JSON with verdict APPROVE before fix rounds.`);
+    lines.push("   If the review JSON is missing, invalid, or verdict is not APPROVE, stop immediately with the Chinese report format; do NOT enter fix rounds.");
+    lines.push(`5. For round 1..${controller.max_rounds}, set current_round to the loop number and run one fresh context fix round with sequential gates:`);
+    lines.push("   a. Spawn fresh surgeon agent with controller_run_id and current_round, then wait for completion.");
+    lines.push("   ```");
+    lines.push("   Agent(");
+    lines.push(`     subagent_type="${surgeonAgent}",`);
+    lines.push(`     prompt="controller_run_id=<controller_run_id>; current_round=<current_round>. Fresh context round for $ARGUMENTS. ${escapePrompt(stepPrompt(fixBugsStep))}"`);
+    lines.push("   )");
+    lines.push("   ```");
+    lines.push("   b. Fix handoff gate: validate the current round handoff and fix commit, or an explicit no-commit handoff for current_round, before review.");
+    lines.push("   c. Spawn fresh fix_reviewer agent with controller_run_id, current_round, and expected review artifact path, then wait for completion.");
+    lines.push("   ```");
+    lines.push("   Agent(");
+    lines.push(`     subagent_type="${fixReviewerAgent}",`);
+    lines.push(`     prompt="controller_run_id=<controller_run_id>; current_round=<current_round>; expected_review_artifact=${controller.review_artifact_path}. Fresh context review for $ARGUMENTS. ${escapePrompt(stepPrompt(reviewChangesStep))}"`);
+    lines.push("   )");
+    lines.push("   ```");
+    lines.push(`   d. Review JSON gate: read ${controller.review_artifact_path}; validate it exists, is valid JSON, module equals the safe module argument, round equals the provided current_round, run_id equals the provided controller_run_id, updated_at is present, and verdict is APPROVE or REQUEST_CHANGES before verification.`);
+    lines.push("   e. Spawn fresh test_runner agent only after the review gate passes; include controller_run_id and current_round, then wait for completion.");
+    lines.push("   ```");
+    lines.push("   Agent(");
+    lines.push(`     subagent_type="${testRunnerAgent}",`);
+    lines.push(`     prompt="controller_run_id=<controller_run_id>; current_round=<current_round>. Fresh context verification for $ARGUMENTS. The progress JSON run_id must equal the provided controller_run_id and round must equal the provided current_round; do not use manual-run during controller execution. ${escapePrompt(stepPrompt(verifyReportStep))}"`);
+    lines.push("   )");
+    lines.push("   ```");
+    lines.push(`   f. Progress JSON read/provenance validation: read ${controller.progress_artifact_path}. The controller must read this JSON sidecar, not Markdown prose.`);
+    lines.push("   g. Verify progress JSON provenance before branching:");
+    lines.push("      - module equals the safe module argument");
+    lines.push("      - round equals the provided current_round");
+    lines.push("      - run_id equals the provided controller_run_id");
+    lines.push(`      - diagnosis_artifact equals ${controller.diagnosis_artifact_path}`);
+    lines.push(`      - review_artifact equals ${controller.review_artifact_path}`);
+    lines.push("      - git_head or last_fix_commit references the current round's fix commit when available");
+    lines.push("      - updated_at is not earlier than the current round start time");
+    lines.push("      - if provenance is missing, stale, or mismatched, stop with Verdict BLOCKED and failure_reason PROGRESS_PROVENANCE_MISMATCH");
+    lines.push("   h. Branch only from the JSON verdict:");
+    lines.push("      - PASS -> success stop");
+    lines.push("      - CONTINUE -> next fresh context fix round");
+    lines.push("      - REQUEST_CHANGES -> stop with Chinese report");
+    lines.push("      - BLOCKED -> stop with Chinese report");
+    lines.push(`6. If max ${controller.max_rounds} rounds is reached, stop with Chinese report.`);
+    lines.push("</Steps>");
+    lines.push("");
+    lines.push("<Verdict_Mapping>");
+    lines.push("PASS / CONTINUE / REQUEST_CHANGES / BLOCKED mapping:");
+    lines.push("- PASS: success stop");
+    lines.push("- CONTINUE: start the next fresh context round");
+    lines.push("- REQUEST_CHANGES: stop, report reviewer/verifier requested changes");
+    lines.push("- BLOCKED: stop, report blocker");
+    lines.push("- MAX_ROUNDS: stop, report max rounds reached and next focus");
+    lines.push("</Verdict_Mapping>");
+    lines.push("");
+    lines.push("<Stop_Report>");
+    lines.push("On REQUEST_CHANGES, BLOCKED, or MAX_ROUNDS, output exactly three Chinese sections:");
+    lines.push("结论：...");
+    lines.push("卡点：...");
+    lines.push("下一步：...");
+    lines.push("</Stop_Report>");
+    lines.push("");
+    lines.push("<Constraints>");
+    lines.push("- Do not infer module completion from raw test output.");
+    lines.push(`- The controller must schedule only from ${controller.progress_artifact_path}.`);
+    lines.push("- Manual /dna-frw-diagnosis and /dna-frw-fix flows remain separate and available.");
+    lines.push("- Do not use the generic workflow policy block; branch only from the progress JSON verdict.");
+    lines.push("</Constraints>");
+    lines.push("");
+    let content = lines.join("\n") + "\n";
+    if (variables) {
+        for (const [key, value] of Object.entries(variables)) {
+            content = content.replaceAll(`{{${key}}}`, value);
+        }
+    }
+    const dirName = skillName;
+    const fileName = join(dirName, "SKILL.md");
+    return { name: skillName, fileName, dirName, content };
+}
+function requireStepByRole(workflow, role, workflowName) {
+    const step = workflow?.steps.find((candidate) => candidate.role === role);
+    if (!step) {
+        throw new Error(`Controller workflow '${workflowName}' must include a step for role '${role}'`);
+    }
+    return step;
+}
 // ── Compile Workflow → Skill ───────────────────────────────
 /**
  * Compile a WorkflowPlan + roles + IR into a SKILL.md file.

package/dist/schema/types.d.ts

@@ -200,6 +200,27 @@ export interface WorkflowDef {
     default_isolation?: "none" | "worktree" | "auto";
     merge_strategy?: "escalate";
 }
+export type ControllerKind = "flutter_rewrite_fix_loop";
+export interface ControllerDef {
+    name: string;
+    description?: string;
+    kind: ControllerKind;
+    max_rounds: number;
+    progress_artifact_path: string;
+    diagnosis_workflow: string;
+    fix_workflow: string;
+    diagnosis_artifact_path: string;
+    diagnosis_review_artifact_path: string;
+    review_artifact_path: string;
+    roles: {
+        analyzer: string;
+        analysis_reviewer: string;
+        surgeon: string;
+        fix_reviewer: string;
+        test_runner: string;
+    };
+    stop_format: "zh_three_part";
+}
 /** Parallel block syntax sugar — expanded by compiler into steps with depends_on */
 export interface ParallelBlockDef {
     parallel: {
@@ -276,6 +297,7 @@ export interface IntentDNA {
     roles?: Record<string, RoleDef>;
     workflow?: WorkflowDef;
     workflows?: Record<string, WorkflowDef>;
+    controllers?: Record<string, ControllerDef>;
     variables?: Record<string, string | VariableDef>;
     mcp?: Record<string, MCPServerDef>;
     legibility_assets?: LegibilityAssetMap;

package/dist/schema/validate.js

@@ -299,6 +299,99 @@ function validateCompletionCheck(check, path) {
     }
     return errors;
 }
+function isSafeControllerArtifactPath(path) {
+    return path.startsWith(".dna/") &&
+        !path.startsWith("/") &&
+        !path.includes("..") &&
+        !/[*?[\]{}]/.test(path) &&
+        !path.includes("{{") &&
+        !path.includes("}}") &&
+        path.includes("$ARGUMENTS");
+}
+function validateController(controller, roleNames, workflows, path) {
+    const errors = [];
+    if (!controller.name) {
+        errors.push({ path: `${path}.name`, message: "controller requires 'name'" });
+    }
+    if (controller.kind !== "flutter_rewrite_fix_loop") {
+        errors.push({ path: `${path}.kind`, message: "unsupported controller kind" });
+    }
+    if (!Number.isInteger(controller.max_rounds) || controller.max_rounds < 1 || controller.max_rounds > 20) {
+        errors.push({ path: `${path}.max_rounds`, message: "max_rounds must be an integer in 1..20" });
+    }
+    const requiredStringFields = [
+        "progress_artifact_path",
+        "diagnosis_workflow",
+        "fix_workflow",
+        "diagnosis_artifact_path",
+        "diagnosis_review_artifact_path",
+        "review_artifact_path",
+    ];
+    for (const field of requiredStringFields) {
+        if (typeof controller[field] !== "string" || !controller[field]) {
+            errors.push({ path: `${path}.${field}`, message: "must be a non-empty string" });
+        }
+    }
+    const artifactPathFields = [
+        "progress_artifact_path",
+        "diagnosis_artifact_path",
+        "diagnosis_review_artifact_path",
+        "review_artifact_path",
+    ];
+    for (const field of artifactPathFields) {
+        if (typeof controller[field] === "string" && !isSafeControllerArtifactPath(controller[field])) {
+            errors.push({ path: `${path}.${field}`, message: "must be a relative .dna/ artifact template containing $ARGUMENTS without glob, brace, absolute, or parent traversal syntax" });
+        }
+    }
+    const diagnosisWorkflow = controller.diagnosis_workflow ? workflows[controller.diagnosis_workflow] : undefined;
+    const fixWorkflow = controller.fix_workflow ? workflows[controller.fix_workflow] : undefined;
+    if (controller.diagnosis_workflow && !diagnosisWorkflow) {
+        errors.push({ path: `${path}.diagnosis_workflow`, message: `references unknown workflow '${controller.diagnosis_workflow}'` });
+    }
+    if (controller.fix_workflow && !fixWorkflow) {
+        errors.push({ path: `${path}.fix_workflow`, message: `references unknown workflow '${controller.fix_workflow}'` });
+    }
+    const roleMap = controller.roles;
+    const requiredRoles = ["analyzer", "analysis_reviewer", "surgeon", "fix_reviewer", "test_runner"];
+    if (!roleMap || typeof roleMap !== "object") {
+        errors.push({ path: `${path}.roles`, message: "controller requires roles" });
+    }
+    else {
+        for (const roleKey of requiredRoles) {
+            const roleName = roleMap[roleKey];
+            if (typeof roleName !== "string" || !roleName) {
+                errors.push({ path: `${path}.roles.${roleKey}`, message: "must be a non-empty role name" });
+            }
+            else if (!roleNames.has(roleName)) {
+                errors.push({ path: `${path}.roles.${roleKey}`, message: `references unknown role '${roleName}'` });
+            }
+        }
+    }
+    if (roleMap && typeof roleMap === "object") {
+        validateControllerWorkflowRoles(diagnosisWorkflow, ["analyzer", "analysis_reviewer"], roleMap, `${path}.diagnosis_workflow`, errors);
+        validateControllerWorkflowRoles(fixWorkflow, ["surgeon", "fix_reviewer", "test_runner"], roleMap, `${path}.fix_workflow`, errors);
+    }
+    if (controller.stop_format !== "zh_three_part") {
+        errors.push({ path: `${path}.stop_format`, message: "stop_format must be 'zh_three_part'" });
+    }
+    return errors;
+}
+function validateControllerWorkflowRoles(workflow, requiredRoleKeys, roleMap, path, errors) {
+    if (!workflow)
+        return;
+    const workflowRoles = new Set(workflow.steps.map((step) => step.role));
+    for (const roleKey of requiredRoleKeys) {
+        const roleName = roleMap[roleKey];
+        if (typeof roleName !== "string" || !roleName)
+            continue;
+        if (!workflowRoles.has(roleName)) {
+            errors.push({
+                path: `${path}.${roleKey}`,
+                message: `workflow '${workflow.name}' must include a step with controller role '${roleName}'`,
+            });
+        }
+    }
+}
 function validateWorkflow(workflow, roleNames, pathPrefix) {
     const errors = [];
     const path = pathPrefix ?? "workflow";
@@ -582,6 +675,14 @@ export function validateDNA(dna) {
             errors.push(...validateWorkflow(wfDef, roleNamesSet, `workflows.${wfName}`));
         }
     }
+    if (dna.controllers) {
+        const workflowsForControllers = { ...(dna.workflows ?? {}) };
+        if (dna.workflow)
+            workflowsForControllers[dna.workflow.name] = dna.workflow;
+        for (const [controllerName, controllerDef] of Object.entries(dna.controllers)) {
+            errors.push(...validateController(controllerDef, roleNamesSet, workflowsForControllers, `controllers.${controllerName}`));
+        }
+    }
     // Validate mcp
     if (dna.mcp) {
         for (const [name, server] of Object.entries(dna.mcp)) {

package/dist/templates/flutter-rewrite.dna.yaml

@@ -134,6 +134,7 @@ context_files:
       - ".dna/specs/diagnosis-{{ARGUMENTS}}.md"
     surgeon:
       - ".dna/specs/diagnosis-{{ARGUMENTS}}.md"
+      - ".dna/specs/diagnosis-{{ARGUMENTS}}.review.json"
     fix_reviewer:
       - "docs/behavior/{{ARGUMENTS}}.md"
       - ".dna/specs/diagnosis-{{ARGUMENTS}}.md"
@@ -239,19 +240,20 @@ roles:
       - "DO NOT run tests. DO NOT edit app code. Analysis only."
 
   analysis_reviewer:
-    description: "Reviews analyzer output quality. Read-only."
+    description: "Reviews analyzer output quality and writes durable diagnosis review verdict."
     tool_permissions:
-      allow: [Read, Grep, Glob]
-      deny: [Bash, Edit, Write, NotebookEdit]
+      allow: [Read, Grep, Glob, Write]
+      deny: [Bash, Edit, NotebookEdit]
     scope:
       read: ["**/*"]
-      write: []
+      write: [".dna/specs/diagnosis-*.review.json"]
     instructions:
       - "REQUIRED FIRST: Read all context files listed in SKILL.md"
       - "Verify analyzer spec: v1 references exist? Classifications sound?"
       - "Check missing: any failing test not covered?"
       - "Verify diagnosis remains evidence-only: no fix prescriptions, implementation order, call-site instructions, or Notes for Surgeon"
-      - "Output a structured verdict block with verdict, artifact_reviewed, sections_to_fix, evidence_paths, confidence, and summary"
+      - "Output a structured verdict block with verdict, artifact_reviewed, sections_to_fix, evidence_paths, confidence, summary, and updated_at"
+      - "Write the same structured verdict JSON to .dna/specs/diagnosis-$ARGUMENTS.review.json before finishing"
 
   fix_reviewer:
     description: "Reviews surgeon changes against approved diagnosis, v1 evidence, and v2 architecture. Writes only the structured review verdict artifact."
@@ -283,6 +285,26 @@ roles:
       - "Classify red tests by type (compile/logic/widget/hung)"
       - "Output progress delta, not test content"
 
+controllers:
+  fix-loop:
+    name: Fix Loop
+    description: "Run diagnosis once if needed, then loop fix/review/verify until PASS or stop condition"
+    kind: flutter_rewrite_fix_loop
+    max_rounds: 10
+    progress_artifact_path: ".dna/fix-progress/$ARGUMENTS.json"
+    diagnosis_workflow: diagnosis
+    fix_workflow: fix
+    diagnosis_artifact_path: ".dna/specs/diagnosis-$ARGUMENTS.md"
+    diagnosis_review_artifact_path: ".dna/specs/diagnosis-$ARGUMENTS.review.json"
+    review_artifact_path: ".dna/reviews/$ARGUMENTS-review.json"
+    roles:
+      analyzer: analyzer
+      analysis_reviewer: analysis_reviewer
+      surgeon: surgeon
+      fix_reviewer: fix_reviewer
+      test_runner: test_runner
+    stop_format: zh_three_part
+
 workflows:
   behavior-lock:
     name: Behavior Lock
@@ -411,10 +433,13 @@ workflows:
             "sections_to_fix": ["section ids or titles; empty when approved"],
             "evidence_paths": ["paths that justify the verdict"],
             "confidence": "high" | "medium" | "low",
-            "summary": "brief reason"
+            "summary": "brief reason",
+            "updated_at": "ISO-8601 timestamp"
           }
           ```
 
+          Write the same verdict JSON to .dna/specs/diagnosis-$ARGUMENTS.review.json before finishing.
+
           APPROVE → diagnosis complete.
           REQUEST_REANALYSIS → sections_to_fix must be passed back to analyze. docs/behavior/blocked_items.md is historical context only and must not be treated as the current run verdict.
         handoff:
@@ -423,6 +448,9 @@ workflows:
               path: ".dna/specs/diagnosis-$ARGUMENTS.md"
               description: "Diagnosis spec from analyzer"
           produces:
+            - type: file
+              path: ".dna/specs/diagnosis-$ARGUMENTS.review.json"
+              description: "Durable diagnosis review verdict (APPROVE or REQUEST_REANALYSIS)"
             - type: summary
               required: false
               description: "Review verdict (APPROVE or REQUEST_REANALYSIS)"
@@ -438,13 +466,20 @@ workflows:
         prompt: |
           This invocation is one fix round.
 
-          Before editing, check whether .dna/fix-progress/$ARGUMENTS.md exists.
-          - If it exists, read it before the diagnosis spec and continue from its Next Round Focus.
-          - If it records REQUEST_CHANGES or BLOCKED_BY_REVIEW, address those review issues before starting unrelated diagnosis items.
-          - Use Failed approaches / Do not repeat to avoid repeating unsuccessful fixes.
-          - If it does not exist, treat this as round 1.
+          Before editing, read .dna/specs/diagnosis-$ARGUMENTS.review.json.
+          - If it is missing, invalid, or verdict is not APPROVE, stop immediately; do not edit.
+          - Manual fix invocations must obey this same gate.
+          - If verdict is REQUEST_REANALYSIS, run diagnosis reanalysis first instead of fixing.
+
+          Read context + diagnosis spec only after the diagnosis review gate passes.
 
-          Read context + diagnosis spec first.
+          Progress artifacts:
+          - .dna/fix-progress/$ARGUMENTS.json is the machine-readable source of truth for controller scheduling.
+          - If JSON exists and provenance matches this module, use its next_round_focus/verdict for the current round.
+          - .dna/fix-progress/$ARGUMENTS.md is human-readable legacy/manual context only; read it for Failed approaches / Do not repeat and evidence, but never use it as the controller verdict or source of truth.
+          - If .md exists without .json, treat it as legacy context only; do not infer PASS/CONTINUE/BLOCKED from it.
+          - If progress records REQUEST_CHANGES or BLOCKED_BY_REVIEW, address those review issues before starting unrelated diagnosis items.
+          - If neither progress artifact exists, treat this as round 1.
 
           Count diagnosis classifications before editing. If UNIMPLEMENTED count is greater than 100, this round is implementation-first: fix UNIMPLEMENTED items by priority only, and leave TEST_BUG / BUG / INFRA / REMOVED for later rounds unless they block implementation.
 
@@ -466,6 +501,9 @@ workflows:
             - type: file
               path: ".dna/specs/diagnosis-$ARGUMENTS.md"
               description: "Diagnosis spec"
+            - type: file
+              path: ".dna/specs/diagnosis-$ARGUMENTS.review.json"
+              description: "Approved diagnosis review gate"
           produces:
             - type: git_commit
               description: "Fix commit"
@@ -488,16 +526,26 @@ workflows:
           ```json
           {
             "verdict": "APPROVE" | "REQUEST_CHANGES",
+            "module": "$ARGUMENTS",
+            "round": 1,
+            "run_id": "controller run id or manual-run",
             "issues": ["specific issue with evidence path; empty when approved"],
             "evidence_paths": ["paths that justify the verdict"],
             "failure_reason": "why changes need another round; empty when approved",
             "next_round_focus": "specific priority/classification/test file for the next fix invocation; empty when approved",
-            "summary": "brief reason"
+            "summary": "brief reason",
+            "updated_at": "ISO-8601 timestamp"
           }
           ```
 
           Write the same verdict JSON to .dna/reviews/$ARGUMENTS-review.json before finishing.
 
+          JSON field rules:
+          - module is required and must equal $ARGUMENTS.
+          - round is required and must be the provided current_round, or 1 for manual fix invocation.
+          - run_id is required and must equal the provided controller_run_id, or "manual-run" for manual fix invocation.
+          - updated_at is a required ISO timestamp string.
+
           REQUEST_CHANGES → include failure_reason and concrete next_round_focus for the next fix invocation. The next_round_focus must name the priority/classification and specific test file or evidence path to address first.
         handoff:
           consumes:
@@ -526,33 +574,96 @@ workflows:
 
           If the review verdict is APPROVE:
           - Run full module test suite for $ARGUMENTS.
+          - Read diagnosis classification summary.
+          - Read current test summary.
           - Compare with diagnosis spec baseline.
+          - Compare skipped tests against remaining UNIMPLEMENTED diagnosis items.
+
+          Hard PASS rules:
+          - 0 failed is not sufficient for PASS.
+          - PASS is forbidden if any approved diagnosis UNIMPLEMENTED item remains skipped.
+          - Diagnosis-backed UNIMPLEMENTED skipped tests count as Remaining, not Blocked.
+          - UNIMPLEMENTED skipped tests count as Remaining.
+          - Before writing Module complete: yes, read diagnosis classification summary, read current test summary, compare skipped tests against remaining UNIMPLEMENTED diagnosis items, and if any UNIMPLEMENTED skipped remains, Module complete must be no.
+
+          Verdict mapping:
+          - review REQUEST_CHANGES -> Verdict: BLOCKED, Failure reason: BLOCKED_BY_REVIEW.
+          - 0 failed + remaining UNIMPLEMENTED skipped > 0 -> Verdict: CONTINUE, Module complete: no, Next Round Focus: next diagnosis-backed UNIMPLEMENTED test/evidence path.
+          - progress contradicts diagnosis/test evidence -> Verdict: BLOCKED, Failure reason: PROGRESS_DIAGNOSIS_CONFLICT.
+          - new red caused by current round -> Verdict: REQUEST_CHANGES.
+          - new red appears to be newly exposed baseline gap AND remaining count decreases -> Verdict: CONTINUE.
+          - ambiguous new red -> Verdict: BLOCKED, Failure reason: AMBIGUOUS_NEW_RED.
+          - 0 failed + no remaining diagnosis-backed UNIMPLEMENTED skipped + no unresolved actionable BUG / UNIMPLEMENTED items + only TEST_BUG / INFRA / REMOVED / explicitly user-approved blocked items remain -> Verdict: PASS.
 
           Output report:
           - Verdict: PASS / CONTINUE / REQUEST_CHANGES / BLOCKED
           - Review: APPROVE / REQUEST_CHANGES
+          - Module complete: yes/no
           - Fixed: N tests now green
           - New red: M tests that regressed
-          - Blocked: K tests skipped (see blocked_items.md)
-          - Remaining: R tests still failing
+          - Blocked: K tests skipped for TEST_BUG / INFRA / REMOVED / user-approved blocked reasons
+          - Remaining: R tests still failing or diagnosis-backed UNIMPLEMENTED skipped
+          - Remaining UNIMPLEMENTED skipped: U diagnosis-backed skipped tests still remaining
           - Failure reason: why progress stopped, if any
           - Next round focus: the priority/classification/test file to continue with, if verdict is CONTINUE or REQUEST_CHANGES
 
           Always write or update .dna/fix-progress/$ARGUMENTS.md before finishing, even when review blocks verification. Include these sections:
-          - Current verdict: Verdict, Review, Last fix commit, Updated at
-          - Round summary: Fixed, New red, Blocked, Remaining, Failure reason
+          - Current verdict: Verdict, Review, Module complete, Last fix commit, Updated at
+          - Round summary: Fixed, New red, Blocked, Remaining, Remaining UNIMPLEMENTED skipped, Failure reason
           - Next Round Focus: non-empty when Verdict is CONTINUE or REQUEST_CHANGES
           - Review Issues To Address First: reviewer issues when Review is REQUEST_CHANGES
           - Failed approaches / Do not repeat: approaches that failed or caused regressions
           - Evidence: commands run and relevant paths
 
-          If Verdict is PASS, mark the module complete in .dna/fix-progress/$ARGUMENTS.md.
+          Always write or update .dna/fix-progress/$ARGUMENTS.json before finishing, even when review blocks verification. The JSON must match this contract exactly:
+          ```json
+          {
+            "verdict": "PASS | CONTINUE | REQUEST_CHANGES | BLOCKED",
+            "review": "APPROVE | REQUEST_CHANGES",
+            "module": "$ARGUMENTS",
+            "round": 1,
+            "run_id": "controller run id or manual-run",
+            "diagnosis_artifact": ".dna/specs/diagnosis-$ARGUMENTS.md",
+            "review_artifact": ".dna/reviews/$ARGUMENTS-review.json",
+            "git_head": null,
+            "module_complete": false,
+            "fixed_count": 0,
+            "new_red_count": 0,
+            "blocked_count": 0,
+            "remaining_count": 0,
+            "remaining_unimplemented_skipped_count": 0,
+            "next_round_focus": "",
+            "failure_reason": "",
+            "last_fix_commit": null,
+            "evidence_paths": [],
+            "updated_at": "ISO-8601 timestamp"
+          }
+          ```
+
+          JSON field rules:
+          - module is required and must equal $ARGUMENTS.
+          - round is required and must be the current fix-loop round number, or 1 for manual fix invocation.
+          - run_id is required and must identify the current controller run, or "manual-run" for manual fix invocation.
+          - diagnosis_artifact is required and must equal .dna/specs/diagnosis-$ARGUMENTS.md.
+          - review_artifact is required and must equal .dna/reviews/$ARGUMENTS-review.json.
+          - git_head is the current git HEAD after verification if available, otherwise null.
+          - verdict is required and must be PASS, CONTINUE, REQUEST_CHANGES, or BLOCKED.
+          - review is required and must be APPROVE or REQUEST_CHANGES.
+          - module_complete is a required boolean and must match the Markdown Module complete value.
+          - fixed_count, new_red_count, blocked_count, remaining_count, and remaining_unimplemented_skipped_count are required non-negative integers.
+          - next_round_focus is required and non-empty when verdict is CONTINUE or REQUEST_CHANGES; empty string is allowed when verdict is PASS.
+          - failure_reason is required and non-empty when verdict is BLOCKED or REQUEST_CHANGES; empty string is allowed when verdict is PASS or CONTINUE.
+          - last_fix_commit is the commit hash string if available, otherwise null.
+          - evidence_paths is a required array of command/test/diagnosis/review evidence paths.
+          - updated_at is a required ISO timestamp string.
+
+          If Verdict is PASS, mark Module complete: yes in .dna/fix-progress/$ARGUMENTS.md and set module_complete true in .dna/fix-progress/$ARGUMENTS.json.
 
           Verdict meanings:
-          - PASS: all approved diagnosis items are fixed or intentionally skipped
+          - PASS: all actionable BUG / UNIMPLEMENTED items are fixed, with no diagnosis-backed UNIMPLEMENTED skipped tests remaining; only TEST_BUG / INFRA / REMOVED / explicitly user-approved blocked items may remain
           - CONTINUE: this round made progress and remaining approved items should continue in the next fix invocation
-          - REQUEST_CHANGES: review or verification found issues in this round's changes
-          - BLOCKED: user confirmation is needed or repeated no-progress prevents safe continuation
+          - REQUEST_CHANGES: verification found issues in this round's changes
+          - BLOCKED: review blocks verification, user confirmation is needed, evidence conflicts, or repeated no-progress prevents safe continuation
         handoff:
           consumes:
             - type: file
@@ -569,6 +680,9 @@ workflows:
             - type: file
               path: ".dna/fix-progress/$ARGUMENTS.md"
               description: "Durable cumulative fix-progress artifact for the next fix invocation"
+            - type: file
+              path: ".dna/fix-progress/$ARGUMENTS.json"
+              description: "Machine-readable fix-progress verdict sidecar for controllers"
             - type: summary
               required: false
               description: "Verification report with test delta"

package/package.json

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