intentdna 1.6.4 → 1.7.0

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

@@ -295,6 +295,35 @@ export interface LegibilityAssetMap {
     per_role?: Record<string, LegibilityAsset[]>;
     per_workflow?: Record<string, LegibilityAsset[]>;
 }
+export type AdvisoryContextSourceType = "file" | "url" | "doc" | "note";
+export interface AdvisoryContextSource {
+    id: string;
+    type: AdvisoryContextSourceType;
+    path?: string;
+    url?: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+}
+export interface PlanningContext {
+    sources: string[];
+    instructions?: string[];
+    require_quotes?: boolean;
+    require_attribution?: boolean;
+}
+export interface CompiledAdvisoryContextSource extends AdvisoryContextSource {
+    usage: "planning_only";
+    non_enforcing: true;
+    requires_quotes: boolean;
+    requires_attribution: boolean;
+}
+export interface CompiledPlanningContext {
+    sources: string[];
+    instructions?: string[];
+    require_quotes: boolean;
+    require_attribution: boolean;
+    non_enforcing: true;
+}
 export interface IntentDNA {
     $schema?: string;
     version: string;
@@ -311,6 +340,8 @@ export interface IntentDNA {
     variables?: Record<string, string | VariableDef>;
     mcp?: Record<string, MCPServerDef>;
     legibility_assets?: LegibilityAssetMap;
+    context_sources?: AdvisoryContextSource[];
+    planning_context?: PlanningContext;
     context_files?: {
         mandatory?: string[];
         per_role?: Record<string, string[]>;
@@ -439,6 +470,8 @@ export interface ConstraintIR {
     post_execution_validators: PostExecutionValidator[];
     verifier_specs?: VerifierSpec[];
     context_injections: ContextInjection[];
+    context_sources?: CompiledAdvisoryContextSource[];
+    planning_context?: CompiledPlanningContext;
     source_dna_ids: string[];
     compiled_at: string;
     active_context?: string;

package/dist/schema/validate.js

@@ -7,6 +7,25 @@
  *   - Codon values in valid ranges
  *   - No circular inheritance
  */
+import { isAbsolute } from "node:path";
+import { validateController } from "./validators/controllers.js";
+const SAFE_GENERATED_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
+const SAFE_GENERATED_DISPLAY_NAME = /^[A-Za-z0-9][A-Za-z0-9 _-]*$/;
+function isSafeGeneratedIdentifier(value) {
+    return SAFE_GENERATED_IDENTIFIER.test(value) && !value.includes("..") && !value.includes("/") && !value.includes("\\");
+}
+function isSafeGeneratedDisplayName(value) {
+    return SAFE_GENERATED_DISPLAY_NAME.test(value) && !value.includes("..");
+}
+function isSafeProjectTemplatePath(value) {
+    const withoutPlaceholders = value.replace(/\{\{[A-Za-z_][A-Za-z0-9_]*\}\}/g, "placeholder");
+    return value.trim().length > 0 &&
+        !isAbsolute(value) &&
+        !value.split(/[\\/]+/).includes("..") &&
+        !/[*?[\]{}]/.test(withoutPlaceholders) &&
+        !value.includes("${") &&
+        !value.includes("$(`");
+}
 function isLegibilityAssetArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "object" && item !== null &&
         typeof item.type === "string" &&
@@ -71,6 +90,126 @@ function validateLegibilityAssets(dna, roleNamesSet, errors, warnings) {
         }
     }
 }
+function validateContextSources(dna, errors) {
+    const sources = dna.context_sources;
+    if (sources !== undefined) {
+        if (!Array.isArray(sources)) {
+            errors.push({ path: "context_sources", message: "must be an array" });
+        }
+        else {
+            const seen = new Set();
+            for (let i = 0; i < sources.length; i++) {
+                const path = `context_sources[${i}]`;
+                if (typeof sources[i] !== "object" || sources[i] === null || Array.isArray(sources[i])) {
+                    errors.push({ path, message: "context source must be an object" });
+                    continue;
+                }
+                const source = sources[i];
+                if (!source.id || typeof source.id !== "string") {
+                    errors.push({ path: `${path}.id`, message: "context source requires non-empty id" });
+                }
+                else if (seen.has(source.id)) {
+                    errors.push({ path: `${path}.id`, message: `duplicate context source id '${source.id}'` });
+                }
+                else {
+                    seen.add(source.id);
+                }
+                if (!["file", "url", "doc", "note"].includes(source.type)) {
+                    errors.push({ path: `${path}.type`, message: "must be one of: file, url, doc, note" });
+                }
+                if (source.type === "file" || source.type === "doc") {
+                    if (typeof source.path !== "string" || !source.path) {
+                        errors.push({ path: `${path}.path`, message: `${source.type} context source requires non-empty path` });
+                    }
+                    else if (isAbsolute(source.path) || source.path.split(/[\\/]+/).includes("..")) {
+                        errors.push({ path: `${path}.path`, message: "context source path must stay within the project" });
+                    }
+                }
+                if (source.type === "url" && (typeof source.url !== "string" || !source.url)) {
+                    errors.push({ path: `${path}.url`, message: "url context source requires non-empty url" });
+                }
+                if (source.tags !== undefined && (!Array.isArray(source.tags) || source.tags.some((tag) => typeof tag !== "string" || !tag))) {
+                    errors.push({ path: `${path}.tags`, message: "tags must be an array of non-empty strings" });
+                }
+            }
+        }
+    }
+    if (dna.planning_context) {
+        const pc = dna.planning_context;
+        if (!Array.isArray(pc.sources) || pc.sources.some((sourceId) => typeof sourceId !== "string" || !sourceId)) {
+            errors.push({ path: "planning_context.sources", message: "must be an array of non-empty context source ids" });
+        }
+        else {
+            const sourceList = Array.isArray(sources) ? sources : [];
+            const declared = new Set(sourceList.map((source) => source.id));
+            for (const sourceId of pc.sources) {
+                if (!declared.has(sourceId)) {
+                    errors.push({ path: "planning_context.sources", message: `references unknown context source '${sourceId}'` });
+                }
+            }
+        }
+        if (pc.instructions !== undefined && (!Array.isArray(pc.instructions) || pc.instructions.some((instruction) => typeof instruction !== "string" || !instruction))) {
+            errors.push({ path: "planning_context.instructions", message: "must be an array of non-empty strings" });
+        }
+        if (pc.require_quotes !== undefined && typeof pc.require_quotes !== "boolean") {
+            errors.push({ path: "planning_context.require_quotes", message: "must be a boolean" });
+        }
+        if (pc.require_attribution !== undefined && typeof pc.require_attribution !== "boolean") {
+            errors.push({ path: "planning_context.require_attribution", message: "must be a boolean" });
+        }
+    }
+}
+function contextSourceIdentities(source) {
+    const identities = [source.id];
+    if (source.type === "file" || source.type === "doc")
+        identities.push(source.path);
+    if (source.type === "url")
+        identities.push(source.url);
+    return identities.filter((identity) => typeof identity === "string" && identity.length > 0);
+}
+function handoffArtifactIdentities(artifact) {
+    return [artifact.artifact_id, artifact.name, artifact.path, artifact.type === "git_commit" ? "git_commit" : undefined]
+        .filter((identity) => typeof identity === "string" && identity.length > 0);
+}
+function validateContextSourceHandoffOverlap(dna, errors) {
+    const contextSources = Array.isArray(dna.context_sources) ? dna.context_sources : [];
+    if (contextSources.length === 0)
+        return;
+    const advisoryIdentities = new Set(contextSources.flatMap(contextSourceIdentities));
+    if (advisoryIdentities.size === 0)
+        return;
+    const checkArtifact = (artifact, path) => {
+        if (artifact.required === false)
+            return;
+        for (const identity of handoffArtifactIdentities(artifact)) {
+            if (!advisoryIdentities.has(identity))
+                continue;
+            errors.push({
+                path,
+                message: `planning-only context source '${identity}' cannot be used as a required handoff artifact`,
+            });
+            return;
+        }
+    };
+    const checkWorkflow = (workflow, path) => {
+        for (let i = 0; i < (workflow.steps ?? []).length; i++) {
+            const step = workflow.steps[i];
+            for (const direction of ["consumes", "produces"]) {
+                const artifacts = step.handoff?.[direction] ?? [];
+                for (let j = 0; j < artifacts.length; j++) {
+                    checkArtifact(artifacts[j], `${path}.steps[${i}].handoff.${direction}[${j}]`);
+                }
+            }
+        }
+    };
+    if (dna.workflow)
+        checkWorkflow(dna.workflow, "workflow");
+    if (dna.workflows) {
+        for (const [wfName, wfDef] of Object.entries(dna.workflows)) {
+            checkWorkflow(wfDef, `workflows.${wfName}`);
+        }
+    }
+}
 function validateCodon(codon, path) {
     const errors = [];
     switch (codon.type) {
@@ -149,6 +288,9 @@ function validateContext(name, ctx, geneNames) {
 function validateRole(name, role, geneNames) {
     const errors = [];
     const path = `roles.${name}`;
+    if (!isSafeGeneratedIdentifier(name)) {
+        errors.push({ path, message: "role name must contain only letters, digits, underscores, and hyphens" });
+    }
     // description required
     if (!role.description) {
         errors.push({ path: `${path}.description`, message: "role requires 'description'" });
@@ -244,8 +386,10 @@ function validateRole(name, role, geneNames) {
         if (os.converter !== undefined && (typeof os.converter !== "string" || !os.converter)) {
             errors.push({ path: `${osPath}.converter`, message: "must be a non-empty string" });
         }
-        if (os.path !== undefined && (typeof os.path !== "string" || !os.path)) {
-            errors.push({ path: `${osPath}.path`, message: "must be a non-empty string" });
+        if (os.path !== undefined) {
+            if (typeof os.path !== "string" || !isSafeProjectTemplatePath(os.path)) {
+                errors.push({ path: `${osPath}.path`, message: "must be a safe project-relative path template" });
+            }
         }
     }
     return errors;
@@ -299,142 +443,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 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 validateController(controller, roleNames, workflows, path) {
-    const errors = [];
-    if (!controller.name) {
-        errors.push({ path: `${path}.name`, message: "controller requires 'name'" });
-    }
-    if (controller.kind !== "fix_loop" && 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 !== "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;
-}
-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";
@@ -442,6 +450,9 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
     if (!workflow.name) {
         errors.push({ path: `${path}.name`, message: "workflow requires 'name'" });
     }
+    else if (!isSafeGeneratedDisplayName(workflow.name)) {
+        errors.push({ path: `${path}.name`, message: "workflow name must contain only letters, digits, spaces, underscores, and hyphens" });
+    }
     // steps required and non-empty
     if (!workflow.steps || workflow.steps.length === 0) {
         errors.push({ path: `${path}.steps`, message: "workflow requires at least one step" });
@@ -457,6 +468,9 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         if (!step.id) {
             errors.push({ path: `${stepPath}.id`, message: "step requires 'id'" });
         }
+        else if (!isSafeGeneratedIdentifier(step.id)) {
+            errors.push({ path: `${stepPath}.id`, message: "step id must contain only letters, digits, underscores, and hyphens" });
+        }
         else if (seenStepIds.has(step.id)) {
             errors.push({ path: `${stepPath}.id`, message: `duplicate step id '${step.id}'` });
         }
@@ -468,6 +482,9 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         if (!step.role) {
             errors.push({ path: `${stepPath}.role`, message: "step requires 'role'" });
         }
+        else if (!isSafeGeneratedIdentifier(step.role)) {
+            errors.push({ path: `${stepPath}.role`, message: "step role must contain only letters, digits, underscores, and hyphens" });
+        }
         else if (roleNames.size > 0 && !roleNames.has(step.role)) {
             errors.push({
                 path: `${stepPath}.role`,
@@ -718,6 +735,7 @@ export function validateDNA(dna) {
             errors.push(...validateWorkflow(wfDef, roleNamesSet, `workflows.${wfName}`));
         }
     }
+    validateContextSourceHandoffOverlap(dna, errors);
     if (dna.controllers) {
         const workflowsForControllers = { ...(dna.workflows ?? {}) };
         if (dna.workflow)
@@ -756,6 +774,7 @@ export function validateDNA(dna) {
         }
     }
     validateLegibilityAssets(dna, roleNamesSet, errors, warnings);
+    validateContextSources(dna, errors);
     // Validate context_files
     if (dna.context_files) {
         const cf = dna.context_files;

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,156 @@
+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 isSafeGeneratedIdentifier(value) {
+    return /^[A-Za-z0-9_-]+$/.test(value) && !value.includes("..") && !value.includes("/") && !value.includes("\\");
+}
+function isSafeGeneratedDisplayName(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9 _-]*$/.test(value) && !value.includes("..");
+}
+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'" });
+    }
+    else if (!isSafeGeneratedDisplayName(controller.name)) {
+        errors.push({ path: `${path}.name`, message: "controller name must contain only letters, digits, spaces, underscores, and hyphens" });
+    }
+    const controllerKey = path.startsWith("controllers.") ? path.slice("controllers.".length) : "";
+    if (controllerKey && !isSafeGeneratedIdentifier(controllerKey)) {
+        errors.push({ path, message: "controller key must contain only letters, digits, underscores, and hyphens" });
+    }
+    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 (!isSafeGeneratedIdentifier(roleName)) {
+                errors.push({ path: `${path}.roles.${roleKey}`, message: "role name must contain only letters, digits, underscores, and hyphens" });
+            }
+            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;
+}

package/dist/signals/index.d.ts

@@ -2,12 +2,14 @@ import type { TraceEntry, VerifierResultEntry } from "../hooks/state.js";
 import type { ExecutionOutcome } from "../evolution/types.js";
 export type SignalKind = "trace" | "verifier" | "external";
 export type SignalStatus = "positive" | "negative" | "neutral";
+export type ExternalSignalClassification = "protective" | "friction" | "unknown";
 export interface SignalEvidence {
     target?: string;
     evidence?: string;
     exit_code?: number;
     artifact?: string;
     message?: string;
+    evidence_ref?: string;
 }
 export interface SignalEnvelope {
     id: string;
@@ -19,6 +21,10 @@ export interface SignalEnvelope {
     detail?: string;
     adapter?: string;
     evidence_payload?: SignalEvidence;
+    classification?: ExternalSignalClassification;
+    confidence?: number;
+    mapping_policy?: string;
+    evolution_eligible?: boolean;
 }
 export interface ExternalSignalInput {
     id?: string;
@@ -32,6 +38,10 @@ export interface ExternalSignalInput {
     exit_code?: number;
     artifact?: string;
     message?: string;
+    evidence_ref?: string;
+    classification?: ExternalSignalClassification;
+    confidence?: number;
+    mapping_policy?: string;
 }
 export interface SignalSourceAdapter<T = unknown> {
     name: string;