intentdna 1.6.3 → 1.6.5

package/dist/runtime/skill-adapter.js

@@ -8,11 +8,13 @@
  */
 import { mkdir, writeFile, readdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
+import { getControllerKindMetadata } from "../schema/controller-registry.js";
 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") {
+    const kindMetadata = getControllerKindMetadata(controller.kind);
+    if (!kindMetadata?.supportsSkillGeneration) {
         throw new Error(`Unsupported controller kind: ${controller.kind}`);
     }
     const skillName = `dna-${toKebabCase(controllerKey)}`;
@@ -29,6 +31,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     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 policy = normalizeControllerPolicy(controller);
     const lines = [];
     lines.push("---");
     lines.push(`name: ${skillName}`);
@@ -49,7 +52,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push("</Purpose>");
     lines.push("");
     lines.push("<Controller>");
-    lines.push("kind: flutter_rewrite_fix_loop");
+    lines.push(`kind: ${controller.kind}`);
     lines.push(`max_rounds: ${controller.max_rounds}`);
     lines.push(`diagnosis_workflow: ${controller.diagnosis_workflow}`);
     lines.push(`fix_workflow: ${controller.fix_workflow}`);
@@ -59,7 +62,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     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("   - If it contains '/', '.', '..', spaces, braces, glob characters, or path separators, stop with the configured stop report.");
     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}`);
@@ -68,12 +71,9 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     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");
+    for (const criterion of policy.diagnosis_reuse_criteria) {
+        lines.push(`   - ${criterion}`);
+    }
     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("   ```");
@@ -91,7 +91,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     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("   If the review JSON is missing, invalid, or verdict is not APPROVE, stop immediately with the configured stop report; 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("   ```");
@@ -118,43 +118,33 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     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");
+    for (const check of policy.progress_provenance_checks) {
+        lines.push(`      - ${check}`);
+    }
+    lines.push(`      - ${policy.progress_provenance_failure}`);
     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.`);
+    for (const branch of policy.verdict_branches) {
+        lines.push(`      - ${branch}`);
+    }
+    lines.push(`6. If max ${controller.max_rounds} rounds is reached, stop with the configured stop 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");
+    for (const line of policy.verdict_mapping) {
+        lines.push(line);
+    }
     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("下一步：...");
+    for (const line of policy.stop_report) {
+        lines.push(line);
+    }
     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.");
+    for (const constraint of policy.constraints) {
+        lines.push(`- ${constraint}`);
+    }
     lines.push("</Constraints>");
     lines.push("");
     let content = lines.join("\n") + "\n";
@@ -174,6 +164,84 @@ function requireStepByRole(workflow, role, workflowName) {
     }
     return step;
 }
+function normalizeControllerPolicy(controller) {
+    const defaults = defaultControllerPolicy(controller);
+    const policy = {
+        diagnosis_reuse_criteria: controller.policy?.diagnosis_reuse_criteria ?? defaults.diagnosis_reuse_criteria,
+        progress_provenance_checks: controller.policy?.progress_provenance_checks ?? defaults.progress_provenance_checks,
+        progress_provenance_failure: controller.policy?.progress_provenance_failure ?? defaults.progress_provenance_failure,
+        verdict_branches: controller.policy?.verdict_branches ?? defaults.verdict_branches,
+        verdict_mapping: controller.policy?.verdict_mapping ?? defaults.verdict_mapping,
+        stop_report: controller.policy?.stop_report ?? defaults.stop_report,
+        constraints: controller.policy?.constraints ?? defaults.constraints,
+    };
+    return {
+        diagnosis_reuse_criteria: renderControllerPolicyLines(policy.diagnosis_reuse_criteria, controller),
+        progress_provenance_checks: renderControllerPolicyLines(policy.progress_provenance_checks, controller),
+        progress_provenance_failure: renderControllerPolicyText(policy.progress_provenance_failure, controller),
+        verdict_branches: renderControllerPolicyLines(policy.verdict_branches, controller),
+        verdict_mapping: renderControllerPolicyLines(policy.verdict_mapping, controller),
+        stop_report: renderControllerPolicyLines(policy.stop_report, controller),
+        constraints: renderControllerPolicyLines(policy.constraints, controller),
+    };
+}
+function renderControllerPolicyLines(lines, controller) {
+    return lines.map((line) => renderControllerPolicyText(line, controller));
+}
+function renderControllerPolicyText(text, controller) {
+    const replacements = {
+        "$progress_artifact_path": controller.progress_artifact_path,
+        "$diagnosis_artifact_path": controller.diagnosis_artifact_path,
+        "$diagnosis_review_artifact_path": controller.diagnosis_review_artifact_path,
+        "$review_artifact_path": controller.review_artifact_path,
+    };
+    let rendered = text;
+    for (const [token, value] of Object.entries(replacements)) {
+        rendered = rendered.replaceAll(token, value);
+    }
+    return rendered;
+}
+function defaultControllerPolicy(controller) {
+    return {
+        diagnosis_reuse_criteria: [
+            `${controller.diagnosis_artifact_path} exists`,
+            `${controller.diagnosis_review_artifact_path} exists and verdict is APPROVE`,
+            "the user did not explicitly request reanalysis",
+            "progress JSON does not invalidate the diagnosis",
+        ],
+        progress_provenance_checks: [
+            "module equals the safe module argument",
+            "round equals the provided current_round",
+            "run_id equals the provided controller_run_id",
+            `diagnosis_artifact equals ${controller.diagnosis_artifact_path}`,
+            `review_artifact equals ${controller.review_artifact_path}`,
+            "git_head or last_fix_commit references the current round's fix commit when available",
+            "updated_at is not earlier than the current round start time",
+        ],
+        progress_provenance_failure: "if provenance is missing, stale, or mismatched, stop with Verdict BLOCKED and failure_reason PROGRESS_PROVENANCE_MISMATCH",
+        verdict_branches: [
+            "PASS -> success stop",
+            "CONTINUE -> next fresh context fix round",
+            "REQUEST_CHANGES -> stop with the configured stop report",
+            "BLOCKED -> stop with the configured stop report",
+        ],
+        verdict_mapping: [
+            "PASS / CONTINUE / REQUEST_CHANGES / BLOCKED mapping:",
+            "- PASS: success stop",
+            "- CONTINUE: start the next fresh context round",
+            "- REQUEST_CHANGES: stop and report the requested changes",
+            "- BLOCKED: stop and report the blocker",
+            "- MAX_ROUNDS: stop and report max rounds reached",
+        ],
+        stop_report: [
+            "On REQUEST_CHANGES, BLOCKED, or MAX_ROUNDS, explain the stop reason, the evidence, and the next action.",
+        ],
+        constraints: [
+            `The controller must schedule only from ${controller.progress_artifact_path}.`,
+            "Branch only from the progress JSON verdict.",
+        ],
+    };
+}
 // ── Compile Workflow → Skill ───────────────────────────────
 /**
  * Compile a WorkflowPlan + roles + IR into a SKILL.md file.

package/dist/schema/controller-registry.d.ts

@@ -0,0 +1,29 @@
+import type { ControllerKind } from "./types.js";
+export declare const CONTROLLER_ROLE_KEYS: readonly ["analyzer", "analysis_reviewer", "surgeon", "fix_reviewer", "test_runner"];
+export type ControllerRoleKey = typeof CONTROLLER_ROLE_KEYS[number];
+export interface ControllerKindMetadata {
+    kind: ControllerKind;
+    label: string;
+    supportsSkillGeneration: boolean;
+    requiredRoleKeys: readonly ControllerRoleKey[];
+    diagnosisRoleKeys: readonly ControllerRoleKey[];
+    fixRoleKeys: readonly ControllerRoleKey[];
+}
+export declare const CONTROLLER_KIND_REGISTRY: readonly [{
+    readonly kind: "fix_loop";
+    readonly label: "Fix loop";
+    readonly supportsSkillGeneration: true;
+    readonly requiredRoleKeys: readonly ["analyzer", "analysis_reviewer", "surgeon", "fix_reviewer", "test_runner"];
+    readonly diagnosisRoleKeys: readonly ["analyzer", "analysis_reviewer"];
+    readonly fixRoleKeys: readonly ["surgeon", "fix_reviewer", "test_runner"];
+}, {
+    readonly kind: "flutter_rewrite_fix_loop";
+    readonly label: "Flutter rewrite fix loop";
+    readonly supportsSkillGeneration: true;
+    readonly requiredRoleKeys: readonly ["analyzer", "analysis_reviewer", "surgeon", "fix_reviewer", "test_runner"];
+    readonly diagnosisRoleKeys: readonly ["analyzer", "analysis_reviewer"];
+    readonly fixRoleKeys: readonly ["surgeon", "fix_reviewer", "test_runner"];
+}];
+export declare function getControllerKindMetadata(kind: unknown): ControllerKindMetadata | undefined;
+export declare function isSupportedControllerKind(kind: unknown): kind is ControllerKind;
+export declare function supportedControllerKinds(): ControllerKind[];

package/dist/schema/controller-registry.js

@@ -0,0 +1,35 @@
+export const CONTROLLER_ROLE_KEYS = [
+    "analyzer",
+    "analysis_reviewer",
+    "surgeon",
+    "fix_reviewer",
+    "test_runner",
+];
+export const CONTROLLER_KIND_REGISTRY = [
+    {
+        kind: "fix_loop",
+        label: "Fix loop",
+        supportsSkillGeneration: true,
+        requiredRoleKeys: CONTROLLER_ROLE_KEYS,
+        diagnosisRoleKeys: ["analyzer", "analysis_reviewer"],
+        fixRoleKeys: ["surgeon", "fix_reviewer", "test_runner"],
+    },
+    {
+        kind: "flutter_rewrite_fix_loop",
+        label: "Flutter rewrite fix loop",
+        supportsSkillGeneration: true,
+        requiredRoleKeys: CONTROLLER_ROLE_KEYS,
+        diagnosisRoleKeys: ["analyzer", "analysis_reviewer"],
+        fixRoleKeys: ["surgeon", "fix_reviewer", "test_runner"],
+    },
+];
+const CONTROLLER_KIND_BY_ID = new Map(CONTROLLER_KIND_REGISTRY.map((entry) => [entry.kind, entry]));
+export function getControllerKindMetadata(kind) {
+    return typeof kind === "string" ? CONTROLLER_KIND_BY_ID.get(kind) : undefined;
+}
+export function isSupportedControllerKind(kind) {
+    return getControllerKindMetadata(kind) !== undefined;
+}
+export function supportedControllerKinds() {
+    return CONTROLLER_KIND_REGISTRY.map((entry) => entry.kind);
+}

package/dist/schema/types.d.ts

@@ -200,7 +200,16 @@ export interface WorkflowDef {
     default_isolation?: "none" | "worktree" | "auto";
     merge_strategy?: "escalate";
 }
-export type ControllerKind = "flutter_rewrite_fix_loop";
+export type ControllerKind = "fix_loop" | "flutter_rewrite_fix_loop";
+export interface ControllerPolicyDef {
+    diagnosis_reuse_criteria?: string[];
+    progress_provenance_checks?: string[];
+    progress_provenance_failure?: string;
+    verdict_branches?: string[];
+    verdict_mapping?: string[];
+    stop_report?: string[];
+    constraints?: string[];
+}
 export interface ControllerDef {
     name: string;
     description?: string;
@@ -219,7 +228,8 @@ export interface ControllerDef {
         fix_reviewer: string;
         test_runner: string;
     };
-    stop_format: "zh_three_part";
+    stop_format: "configured_stop_report" | "zh_three_part";
+    policy?: ControllerPolicyDef;
 }
 /** Parallel block syntax sugar — expanded by compiler into steps with depends_on */
 export interface ParallelBlockDef {

package/dist/schema/validate.js

@@ -7,6 +7,7 @@
  *   - Codon values in valid ranges
  *   - No circular inheritance
  */
+import { validateController } from "./validators/controllers.js";
 function isLegibilityAssetArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "object" && item !== null &&
         typeof item.type === "string" &&
@@ -299,99 +300,6 @@ 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";

package/dist/schema/validators/controllers.d.ts

@@ -0,0 +1,3 @@
+import type { ControllerDef, WorkflowDef } from "../types.js";
+import type { ValidationError } from "../validate.js";
+export declare function validateController(controller: ControllerDef, roleNames: Set<string>, workflows: Record<string, WorkflowDef>, path: string): ValidationError[];

package/dist/schema/validators/controllers.js

@@ -0,0 +1,140 @@
+import { CONTROLLER_ROLE_KEYS, getControllerKindMetadata, isSupportedControllerKind } from "../controller-registry.js";
+function isSafeControllerArtifactPath(path) {
+    return path.startsWith(".dna/") &&
+        !path.startsWith("/") &&
+        !path.includes("..") &&
+        !/[*?[\]{}]/.test(path) &&
+        !path.includes("{{") &&
+        !path.includes("}}") &&
+        path.includes("$ARGUMENTS");
+}
+function validateStringList(value, path, errors) {
+    if (!Array.isArray(value)) {
+        errors.push({ path, message: "must be an array of non-empty strings" });
+        return;
+    }
+    value.forEach((item, index) => {
+        if (typeof item !== "string" || item.trim() === "") {
+            errors.push({ path: `${path}.${index}`, message: "must be a non-empty string" });
+        }
+    });
+}
+function validateControllerPolicy(policy, path, errors) {
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        errors.push({ path, message: "policy must be an object" });
+        return;
+    }
+    const record = policy;
+    const listFields = [
+        "diagnosis_reuse_criteria",
+        "progress_provenance_checks",
+        "verdict_branches",
+        "verdict_mapping",
+        "stop_report",
+        "constraints",
+    ];
+    const allowedFields = new Set([...listFields, "progress_provenance_failure"]);
+    for (const field of Object.keys(record)) {
+        if (!allowedFields.has(field)) {
+            errors.push({ path: `${path}.${field}`, message: "unknown controller policy field" });
+        }
+    }
+    for (const field of listFields) {
+        if (record[field] !== undefined)
+            validateStringList(record[field], `${path}.${field}`, errors);
+    }
+    if (record.progress_provenance_failure !== undefined &&
+        (typeof record.progress_provenance_failure !== "string" || record.progress_provenance_failure.trim() === "")) {
+        errors.push({ path: `${path}.progress_provenance_failure`, message: "must be a non-empty string" });
+    }
+}
+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}'`,
+            });
+        }
+    }
+}
+export function validateController(controller, roleNames, workflows, path) {
+    const errors = [];
+    if (!controller.name) {
+        errors.push({ path: `${path}.name`, message: "controller requires 'name'" });
+    }
+    const kindMetadata = isSupportedControllerKind(controller.kind)
+        ? getControllerKindMetadata(controller.kind)
+        : undefined;
+    if (!kindMetadata) {
+        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 = kindMetadata?.requiredRoleKeys ?? CONTROLLER_ROLE_KEYS;
+    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, kindMetadata?.diagnosisRoleKeys ?? ["analyzer", "analysis_reviewer"], roleMap, `${path}.diagnosis_workflow`, errors);
+        validateControllerWorkflowRoles(fixWorkflow, kindMetadata?.fixRoleKeys ?? ["surgeon", "fix_reviewer", "test_runner"], roleMap, `${path}.fix_workflow`, errors);
+    }
+    if (controller.stop_format !== "configured_stop_report" && controller.stop_format !== "zh_three_part") {
+        errors.push({ path: `${path}.stop_format`, message: "stop_format must be 'configured_stop_report' or legacy 'zh_three_part'" });
+    }
+    if (controller.policy !== undefined) {
+        validateControllerPolicy(controller.policy, `${path}.policy`, errors);
+    }
+    return errors;
+}