intentdna 1.5.20 → 1.6.0

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.
@@ -42,6 +206,12 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Purpose>");
         lines.push("");
     }
+    lines.push("<Workflow_State>");
+    lines.push("At workflow start, persist runtime inputs in DNA workflow state before executing steps.");
+    lines.push("Record the invocation argument as inputs.ARGUMENTS so handoff artifact paths like $ARGUMENTS can be resolved deterministically.");
+    lines.push("If template variables are shown below, persist their resolved values as resolved_variables.");
+    lines.push("</Workflow_State>");
+    lines.push("");
     // Required Context — context files that must be read before any work
     const workflowKeys = [plan.workflow_key, plan.source_workflow, plan.name].filter((key, index, keys) => Boolean(key) && keys.indexOf(key) === index);
     const requiredReadAssets = [];

package/dist/schema/types.d.ts

@@ -94,9 +94,38 @@ export type HandoffType = "file" | "directory" | "test_result" | "git_commit" |
 export interface HandoffArtifact {
     type: HandoffType;
     path?: string;
+    name?: string;
+    artifact_id?: string;
     from?: string;
+    required?: boolean;
     description: string;
 }
+export interface ArtifactKey {
+    workflow: string;
+    session_id: string;
+    producer_step: string;
+    type: HandoffType;
+    identity: string;
+}
+export interface ArtifactManifest {
+    id: string;
+    key: ArtifactKey;
+    type: HandoffType;
+    workflow: string;
+    session_id: string;
+    producer_step: string;
+    identity: string;
+    path?: string;
+    contract_path?: string;
+    name?: string;
+    artifact_id?: string;
+    metadata?: Record<string, unknown>;
+    recorded_at: string;
+    resolver_version: number;
+}
+export interface ArtifactFact extends ArtifactManifest {
+    manifest_path: string;
+}
 /** Handoff declaration for a workflow step */
 export interface StepHandoff {
     consumes?: HandoffArtifact[];
@@ -171,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: {
@@ -247,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;
@@ -344,13 +395,19 @@ export interface WorkflowIR {
     step_enforce_rules?: StepEnforceRule[];
 }
 /** Record of artifacts completed by a step — used for cross-session resume */
+export interface CompletedArtifactMetadata {
+    [key: string]: unknown;
+}
+export interface CompletedArtifactRecord {
+    type: string;
+    path: string;
+    verified_at: string;
+    artifact_id?: string;
+    metadata?: CompletedArtifactMetadata;
+}
 export interface CompletedArtifactEntry {
     step_id: string;
-    artifacts: {
-        type: string;
-        path: string;
-        verified_at: string;
-    }[];
+    artifacts: CompletedArtifactRecord[];
 }
 /** Runtime workflow state written to .dna/state/workflow.json */
 export interface WorkflowState {
@@ -361,6 +418,8 @@ export interface WorkflowState {
     iteration: number;
     session_id: string;
     started_at: string;
+    inputs?: Record<string, string>;
+    resolved_variables?: Record<string, string>;
     completed_artifacts?: CompletedArtifactEntry[];
 }
 export interface ConstraintIR {

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";
@@ -382,6 +475,16 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
                 }
             }
         }
+        for (const direction of ["consumes", "produces"]) {
+            const artifacts = step.handoff?.[direction] ?? [];
+            for (let j = 0; j < artifacts.length; j++) {
+                const artifact = artifacts[j];
+                const artifactPath = `${stepPath}.handoff.${direction}[${j}]`;
+                if (artifact.required !== false && artifact.type !== "git_commit" && !artifact.path && !artifact.name && !artifact.artifact_id) {
+                    errors.push({ path: artifactPath, message: "required handoff artifacts must define path, name, or artifact_id" });
+                }
+            }
+        }
         // checkpoints validation
         if (step.checkpoints) {
             if (!Array.isArray(step.checkpoints)) {
@@ -572,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/code-review-pipeline.dna.yaml

@@ -99,6 +99,7 @@ workflow:
             description: "Implementation to review"
         produces:
           - type: summary
+            required: false
             description: "Review verdict (PASS/FAIL)"
   transitions:
     - from: review

package/dist/templates/flutter-refactoring-rescue.dna.yaml

@@ -133,6 +133,7 @@ workflows:
         handoff:
           produces:
             - type: summary
+              name: breakpoint_analysis
               description: "Breakpoint analysis with file paths and line numbers"
       - id: fix
         role: surgeon
@@ -143,6 +144,7 @@ workflows:
           consumes:
             - type: summary
               from: trace
+              name: breakpoint_analysis
               description: "Breakpoint analysis from investigator"
           produces:
             - type: git_commit
@@ -159,4 +161,5 @@ workflows:
               description: "Fix commit to verify"
           produces:
             - type: summary
+              required: false
               description: "Verification result with screenshots"