intentdna 1.7.5 → 1.8.0

package/dist/runtime/codex-sync-target.d.ts

@@ -0,0 +1,33 @@
+import type { ConstraintIR } from "../schema/types.js";
+import { type CodexAdapterArtifacts, type CodexHookInstallMode } from "./codex-adapter.js";
+import type { AdapterCapabilityReport, CapabilityReportEntry, EvidencePlan, PlannedArtifact, SyncTargetPlan } from "./sync-target-plan.js";
+export interface CodexSyncTargetPlanOptions {
+    hookInstallMode?: CodexHookInstallMode;
+    packageVersion: string;
+}
+export type CodexPlannedArtifact = PlannedArtifact;
+export type CodexCapabilityReportEntry = CapabilityReportEntry;
+export type CodexAdapterCapabilityReport = AdapterCapabilityReport & {
+    adapter: "codex_cli";
+    runtime: "codex_cli";
+};
+export type CodexEvidencePlan = EvidencePlan;
+export interface CodexSyncTargetPlan extends SyncTargetPlan {
+    target: "codex_cli";
+    hookInstallMode: CodexHookInstallMode;
+    artifacts: CodexAdapterArtifacts;
+    plannedArtifacts: CodexPlannedArtifact[];
+    capabilityReport: CodexAdapterCapabilityReport;
+    evidencePlan: CodexEvidencePlan;
+    warnings: string[];
+    unsupported: string[];
+}
+export interface ExecuteCodexSyncTargetPlanOptions {
+    projectDir: string;
+    dogfood?: boolean;
+}
+export declare function createCodexSyncTargetPlan(ir: ConstraintIR, options: CodexSyncTargetPlanOptions): CodexSyncTargetPlan;
+export declare function executeCodexSyncTargetPlan(plan: CodexSyncTargetPlan, options: ExecuteCodexSyncTargetPlanOptions): Promise<string[]>;
+export declare function codexSyncDispatcherCommand(): string;
+export declare function removeCodexSyncTargetArtifacts(projectDir: string): Promise<string[]>;
+export declare function formatCodexSyncTargetPlanSummary(plan: CodexSyncTargetPlan): string;

package/dist/runtime/codex-sync-target.js

@@ -0,0 +1,241 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compileCodexAdapterArtifacts, removeCodexAdapterArtifacts, runCodexExecDogfood, withCodexDogfoodEvidence, writeCodexAdapterArtifacts, } from "./codex-adapter.js";
+import { formatSyncTargetPlanDiagnostics } from "./sync-target-plan.js";
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const CODEX_DISPATCHER_SCRIPT = "dist/hooks/cli.js";
+function plannedArtifacts(artifacts) {
+    const plans = [
+        {
+            kind: "codex_instruction",
+            path: artifacts.instruction.path,
+            ownership: "intentdna_owned",
+            trackedByLock: true,
+            outputArtifact: "codex-adapter",
+        },
+        {
+            kind: "codex_policy_map",
+            path: artifacts.policyMap.path,
+            ownership: "diagnostic",
+            trackedByLock: true,
+            outputArtifact: "codex-adapter",
+        },
+        {
+            kind: "codex_adapter_evidence",
+            path: ".dna/compiled/codex-adapter-evidence.json",
+            ownership: "diagnostic",
+            trackedByLock: true,
+            outputArtifact: "codex-adapter",
+        },
+    ];
+    if (artifacts.evidence.install_mode_semantics.writes_project_fallback) {
+        plans.push({
+            kind: "codex_fallback_hooks",
+            path: artifacts.evidence.fallback_hooks_path,
+            ownership: "merge_preserve_user",
+            trackedByLock: true,
+            outputArtifact: "codex-adapter",
+        }, {
+            kind: "codex_fallback_trust_state",
+            path: artifacts.evidence.fallback_config_path,
+            ownership: "merge_preserve_user",
+            trackedByLock: true,
+            outputArtifact: "codex-adapter",
+        });
+    }
+    if (artifacts.evidence.install_mode_semantics.writes_plugin_artifacts) {
+        plans.push({
+            kind: "codex_plugin_manifest",
+            path: "codex-plugin/.codex-plugin/plugin.json",
+            ownership: "intentdna_owned",
+            trackedByLock: true,
+            outputArtifact: "codex-adapter",
+        }, {
+            kind: "codex_plugin_hooks",
+            path: "codex-plugin/hooks/hooks.json",
+            ownership: "intentdna_owned",
+            trackedByLock: true,
+            outputArtifact: "codex-adapter",
+        });
+    }
+    return plans;
+}
+function supportStatus(status, keys, fallback = "unknown") {
+    const values = keys.map((key) => status[key]).filter((value) => value !== undefined);
+    if (values.includes("partial"))
+        return "partial";
+    if (values.includes("supported"))
+        return "supported";
+    if (values.includes("unsupported"))
+        return "unsupported";
+    return values[0] ?? fallback;
+}
+function capabilityReport(artifacts) {
+    const status = artifacts.evidence.support_status;
+    const instructionPath = artifacts.evidence.instruction_path;
+    const capabilities = {
+        intent_lock: {
+            status: supportStatus(status, ["prompt_directives"]),
+            surfaces: [instructionPath],
+            evidenceRefs: ["codex-instruction-artifact"],
+            notes: ["Prompt directives are rendered as Codex instructions and remain soft guidance until paired with runtime evidence."],
+        },
+        boundary_constraint: {
+            status: supportStatus(status, ["role_scope", "pre_execution_gates"]),
+            surfaces: ["Codex permissions/rules plus PreToolUse hook diagnostics"],
+            evidenceRefs: ["codex-role-scope-map", "codex-pre-tool-use-hook"],
+            notes: ["Scope constraints require concrete Codex permission and hook coverage for each runtime path."],
+        },
+        context_control: {
+            status: supportStatus(status, ["context_injections"]),
+            surfaces: [instructionPath],
+            evidenceRefs: ["codex-context-instruction-artifact"],
+            notes: ["Static context can be injected into instructions; dynamic context control remains event-limited."],
+        },
+        tool_policy: {
+            status: supportStatus(status, ["tool_filters", "role_tool_permissions"]),
+            surfaces: ["Codex execpolicy/rules and PreToolUse hook subset"],
+            evidenceRefs: ["codex-tool-filter-map", "codex-role-scope-map"],
+            notes: ["Non-Bash and unsupported tool paths stay explicit in unsupported gaps."],
+        },
+        approval_gate: {
+            status: supportStatus(status, ["pre_execution_gates", "permission_request"]),
+            surfaces: ["PreToolUse hook", "PermissionRequest unsupported fixture"],
+            evidenceRefs: ["codex-pre-tool-use-hook"],
+            notes: ["PreToolUse gates can diagnose or block supported paths; native permission-request parity is not claimed."],
+        },
+        checkpoint: {
+            status: supportStatus(status, ["post_execution_validators"]),
+            surfaces: ["PostToolUse/Stop validation evidence"],
+            evidenceRefs: ["codex-validation-hook"],
+            notes: ["Validation hooks can record evidence but cannot reverse completed side effects."],
+        },
+        completion_check: {
+            status: supportStatus(status, ["post_execution_validators"]),
+            surfaces: ["PostToolUse/Stop validation evidence"],
+            evidenceRefs: ["codex-validation-hook"],
+            notes: ["Completion checks remain partial until verifier outcomes are backed by RuntimeDecisionEvent provenance."],
+        },
+        artifact_handoff: {
+            status: "partial",
+            surfaces: [...new Set([artifacts.policyMap.path, artifacts.evidence.policy_map_path, artifacts.evidence.dispatcher_script])],
+            evidenceRefs: ["codex-policy-map", "codex-adapter-evidence"],
+            notes: ["Generated artifacts describe handoff surfaces but are diagnostic artifacts, not policy truth."],
+        },
+        isolation: {
+            status: "unknown",
+            surfaces: ["Codex sandbox flags are execution-time choices outside sync artifact generation"],
+            evidenceRefs: [],
+            notes: ["Workflow isolation requirements can be declared, but this sync target does not yet prove runtime sandbox isolation."],
+        },
+        dry_run: {
+            status: "supported",
+            surfaces: ["dna sync --dry-run Codex target plan"],
+            evidenceRefs: ["codex-sync-target-plan"],
+            notes: ["Dry-run reports planned Codex artifacts, support posture, evidence classification, and unsupported gaps without writing files."],
+        },
+        rollback_or_compensation: {
+            status: "unsupported",
+            surfaces: [],
+            evidenceRefs: ["post_execution_side_effect_rollback"],
+            notes: ["Codex validation hooks can observe outcomes but cannot roll back completed side effects."],
+        },
+        trace: {
+            status: supportStatus(status, ["runtime_decision_event"]),
+            surfaces: ["RuntimeDecisionEvent state writer", ".dna/compiled/codex-adapter-evidence.json"],
+            evidenceRefs: ["RuntimeDecisionEvent", "codex-adapter-evidence"],
+            notes: ["Adapter evidence is trace-adjacent diagnostic data; RuntimeDecisionEvent remains the primary trace contract."],
+        },
+        runtime_decision_evidence: {
+            status: supportStatus(status, ["runtime_decision_event"]),
+            surfaces: ["appendRuntimeDecisionEvent", ".dna/compiled/codex-adapter-evidence.json"],
+            evidenceRefs: ["RuntimeDecisionEvent", "codex-adapter-evidence"],
+            notes: ["Diagnostic adapter evidence must not be upgraded to enterprise evidence without trusted RuntimeDecisionEvent provenance."],
+        },
+        logic_equivalence_validation: {
+            status: "unknown",
+            surfaces: ["Workflow verifier specs and external test commands"],
+            evidenceRefs: ["verifier_specs", "RuntimeDecisionEvent"],
+            notes: ["Equivalence validation is a workflow capability, not a Codex-native sync artifact; concrete proof must come from verifier execution evidence."],
+        },
+    };
+    return {
+        adapter: "codex_cli",
+        runtime: "codex_cli",
+        capabilities,
+        unsupported: artifacts.evidence.unsupported,
+    };
+}
+function evidencePlan(artifacts) {
+    return {
+        primary: "RuntimeDecisionEvent",
+        diagnosticArtifacts: [
+            artifacts.evidence.policy_map_path,
+            ".dna/compiled/codex-adapter-evidence.json",
+            artifacts.evidence.instruction_path,
+        ],
+        classification: artifacts.evidence.trust_verification?.classification ?? artifacts.evidence.install_mode_semantics.classification,
+        notes: artifacts.evidence.notes,
+    };
+}
+export function createCodexSyncTargetPlan(ir, options) {
+    const hookInstallMode = options.hookInstallMode ?? "project_fallback";
+    const artifacts = compileCodexAdapterArtifacts(ir, {
+        adapterRoot: PACKAGE_ROOT,
+        dispatcherScript: CODEX_DISPATCHER_SCRIPT,
+        hookInstallMode,
+        pluginVersion: options.packageVersion,
+    });
+    return {
+        target: "codex_cli",
+        hookInstallMode,
+        artifacts,
+        plannedArtifacts: plannedArtifacts(artifacts),
+        capabilityReport: capabilityReport(artifacts),
+        evidencePlan: evidencePlan(artifacts),
+        warnings: artifacts.evidence.notes,
+        unsupported: artifacts.evidence.unsupported,
+    };
+}
+export async function executeCodexSyncTargetPlan(plan, options) {
+    let artifacts = plan.artifacts;
+    if (options.dogfood) {
+        const dogfood = await runCodexExecDogfood({ projectDir: options.projectDir });
+        artifacts = { ...artifacts, evidence: withCodexDogfoodEvidence(artifacts.evidence, dogfood) };
+    }
+    return writeCodexAdapterArtifacts(options.projectDir, artifacts);
+}
+export function codexSyncDispatcherCommand() {
+    return createCodexSyncTargetPlan({
+        source_dna_ids: [],
+        compiled_at: new Date().toISOString(),
+        prompt_directives: [],
+        tool_filters: [],
+        pre_execution_gates: [],
+        post_execution_validators: [],
+        context_injections: [],
+    }, {
+        packageVersion: "0.0.0",
+    }).artifacts.evidence.dispatcher_command;
+}
+export async function removeCodexSyncTargetArtifacts(projectDir) {
+    return removeCodexAdapterArtifacts(projectDir, codexSyncDispatcherCommand());
+}
+export function formatCodexSyncTargetPlanSummary(plan) {
+    const lines = [
+        `Codex target support posture: ${plan.artifacts.evidence.install_mode_semantics.support_status}`,
+        `Codex evidence plan: primary=${plan.evidencePlan.primary}, classification=${plan.evidencePlan.classification}`,
+        `Codex planned artifacts: ${plan.plannedArtifacts.length}`,
+    ];
+    for (const artifact of plan.plannedArtifacts) {
+        lines.push(`  - ${artifact.kind}: ${artifact.path} (${artifact.ownership})`);
+    }
+    const capabilityEntries = Object.entries(plan.capabilityReport.capabilities)
+        .sort(([left], [right]) => left.localeCompare(right));
+    lines.push("Codex capability report:");
+    for (const [capability, entry] of capabilityEntries) {
+        const surfaces = entry.surfaces.length > 0 ? entry.surfaces.join(", ") : "no Codex sync surface";
+        lines.push(`  - ${capability}: ${entry.status} via ${surfaces}`);
+    }
+    return `${lines.join("\n")}\n${formatSyncTargetPlanDiagnostics(plan)}`;
+}

package/dist/runtime/index.d.ts

@@ -7,3 +7,11 @@ export type { WorkflowShellOptions, WorkflowShellResult } from "./workflow-runne
 export { createCompiledIR, writeCompiledIR, loadCompiledIR, removeCompiledIR, } from "./plugin-adapter.js";
 export type { CompiledIRFile } from "./plugin-adapter.js";
 export { compilePluginSettings, detectEnabledEvents, } from "./settings-adapter.js";
+export { CODEX_ADAPTER_MINIMUM_VERSION, CODEX_NATIVE_HOOK_EVENTS, appendCodexRuntimeDecisionEvent, buildCodexDispatcherCommand, buildCodexHookTrustState, codexHookTrustedHash, codexInstallModeSemantics, codexTrustStateToml, compileCodexAdapterArtifacts, compileCodexHooksConfig, compileCodexInstructionArtifact, compileCodexPluginManifest, compileCodexPolicyMapArtifact, mapCodexDecisionEvent, mergeCodexFallbackHooks, mergeCodexTrustStateConfig, normalizeCodexHookInput, probeCodexRuntime, runCodexExecDogfood, removeCodexAdapterArtifacts, removeCodexFallbackHooks, removeCodexTrustStateConfig, runCodexHook, withCodexDogfoodEvidence, verifyCodexHookTrust, writeCodexAdapterArtifacts, } from "./codex-adapter.js";
+export type { CodexAdapterArtifacts, CodexAdapterEvidence, CodexAdapterSupportStatus, CodexCommandHook, CodexDecisionMappingInput, CodexDogfoodResult, CodexEvidenceClassification, CodexExecJsonEvent, CodexHookGroup, CodexHookInput, CodexHookInstallMode, CodexHookRunnerOptions, CodexHookRunnerResult, CodexHookTrustState, CodexHooksConfig, CodexInstallModeSemantics, CodexInstructionArtifact, CodexNativeHookEvent, CodexPluginManifest, CodexPolicyMap, CodexPolicyMapArtifact, CodexPolicyMapEntry, CodexRuntimeProbe, CodexTrustVerification, RunCodexDogfoodOptions, CodexTrustVerificationInput, CompileCodexAdapterOptions, } from "./codex-adapter.js";
+export { codexSyncDispatcherCommand, createCodexSyncTargetPlan, executeCodexSyncTargetPlan, formatCodexSyncTargetPlanSummary, removeCodexSyncTargetArtifacts, } from "./codex-sync-target.js";
+export type { CodexAdapterCapabilityReport, CodexCapabilityReportEntry, CodexEvidencePlan, CodexPlannedArtifact, CodexSyncTargetPlan, CodexSyncTargetPlanOptions, ExecuteCodexSyncTargetPlanOptions, } from "./codex-sync-target.js";
+export { createClaudeCoreSyncTargetPlan, executeClaudeCoreSyncTargetPlan, formatClaudeCoreSyncTargetPlanDryRun, removeLegacyBashHooks, } from "./claude-sync-target.js";
+export type { ClaudeCoreAdapterCapabilityReport, ClaudeCoreCapabilityReportEntry, ClaudeCorePlannedArtifact, ClaudeCoreSyncTargetPlan, ClaudeCoreSyncTargetPlanOptions, ClaudeSettingsHookRegistration, ClaudeSyncMode, ExecuteClaudeCoreSyncTargetPlanResult, } from "./claude-sync-target.js";
+export type { AdapterCapabilityReport, CapabilityReportEntry, CapabilitySupportStatus, EvidenceClassification, EvidencePlan, PlannedArtifact, SyncTarget, SyncTargetMode, SyncTargetPlan, } from "./sync-target-plan.js";
+export { formatSyncTargetPlanDiagnostics, trackedOutputsForSyncTargetPlan, } from "./sync-target-plan.js";

package/dist/runtime/index.js

@@ -3,3 +3,7 @@ export { compileRoleToAgentMD, compileAllRolesToAgentMD, writeAgentMDFiles, remo
 export { compileWorkflowToShell, writeWorkflowScript, removeWorkflowScripts, } from "./workflow-runner.js";
 export { createCompiledIR, writeCompiledIR, loadCompiledIR, removeCompiledIR, } from "./plugin-adapter.js";
 export { compilePluginSettings, detectEnabledEvents, } from "./settings-adapter.js";
+export { CODEX_ADAPTER_MINIMUM_VERSION, CODEX_NATIVE_HOOK_EVENTS, appendCodexRuntimeDecisionEvent, buildCodexDispatcherCommand, buildCodexHookTrustState, codexHookTrustedHash, codexInstallModeSemantics, codexTrustStateToml, compileCodexAdapterArtifacts, compileCodexHooksConfig, compileCodexInstructionArtifact, compileCodexPluginManifest, compileCodexPolicyMapArtifact, mapCodexDecisionEvent, mergeCodexFallbackHooks, mergeCodexTrustStateConfig, normalizeCodexHookInput, probeCodexRuntime, runCodexExecDogfood, removeCodexAdapterArtifacts, removeCodexFallbackHooks, removeCodexTrustStateConfig, runCodexHook, withCodexDogfoodEvidence, verifyCodexHookTrust, writeCodexAdapterArtifacts, } from "./codex-adapter.js";
+export { codexSyncDispatcherCommand, createCodexSyncTargetPlan, executeCodexSyncTargetPlan, formatCodexSyncTargetPlanSummary, removeCodexSyncTargetArtifacts, } from "./codex-sync-target.js";
+export { createClaudeCoreSyncTargetPlan, executeClaudeCoreSyncTargetPlan, formatClaudeCoreSyncTargetPlanDryRun, removeLegacyBashHooks, } from "./claude-sync-target.js";
+export { formatSyncTargetPlanDiagnostics, trackedOutputsForSyncTargetPlan, } from "./sync-target-plan.js";

package/dist/runtime/output-artifact-registry.d.ts

@@ -1,4 +1,4 @@
-export declare const SYNC_OUTPUT_ARTIFACT_IDS: readonly ["markdown-injection", "compiled-ir", "settings-hooks", "agents", "workflows", "skills-controllers", "mcp-config", "lock-file"];
+export declare const SYNC_OUTPUT_ARTIFACT_IDS: readonly ["markdown-injection", "compiled-ir", "settings-hooks", "agents", "workflows", "skills-controllers", "mcp-config", "codex-adapter", "lock-file"];
 export type SyncOutputArtifactId = typeof SYNC_OUTPUT_ARTIFACT_IDS[number];
 export interface SyncOutputArtifactMetadata {
     id: SyncOutputArtifactId;

package/dist/runtime/output-artifact-registry.js

@@ -6,6 +6,7 @@ export const SYNC_OUTPUT_ARTIFACT_IDS = [
     "workflows",
     "skills-controllers",
     "mcp-config",
+    "codex-adapter",
     "lock-file",
 ];
 export const SYNC_OUTPUT_ARTIFACT_REGISTRY = [
@@ -16,6 +17,7 @@ export const SYNC_OUTPUT_ARTIFACT_REGISTRY = [
     { id: "workflows", order: 60, label: "Workflows", trackedByLock: true },
     { id: "skills-controllers", order: 70, label: "Skills and controllers", trackedByLock: true },
     { id: "mcp-config", order: 80, label: "MCP config", trackedByLock: false },
+    { id: "codex-adapter", order: 85, label: "Codex adapter", trackedByLock: true },
     { id: "lock-file", order: 90, label: "Lock file", trackedByLock: false },
 ];
 const ARTIFACT_BY_ID = new Map(SYNC_OUTPUT_ARTIFACT_REGISTRY.map((entry) => [entry.id, entry]));

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

@@ -4,7 +4,7 @@
  * Compiles DNA hook events into Claude Code settings.json
  * hook configurations for the dna-hook binary.
  *
- * See docs/references/cc-source-analysis.md §2 for the full hook event catalog.
+ * See docs/archive/2026H1/references/cc-source-analysis.md §2 for the full hook event catalog.
  */
 import { type SettingsHookEventKey } from "../hooks/event-registry.js";
 export type HookEventKey = SettingsHookEventKey;

package/dist/runtime/settings-adapter.js

@@ -4,7 +4,7 @@
  * Compiles DNA hook events into Claude Code settings.json
  * hook configurations for the dna-hook binary.
  *
- * See docs/references/cc-source-analysis.md §2 for the full hook event catalog.
+ * See docs/archive/2026H1/references/cc-source-analysis.md §2 for the full hook event catalog.
  */
 import { readFile, writeFile } from "node:fs/promises";
 import { getHookEventBySettingsKey, settingsHookEventKeys } from "../hooks/event-registry.js";

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

@@ -45,7 +45,11 @@ export interface SkillResult {
     bodyFileName?: string;
     mapEntry?: SkillMapEntry;
 }
+export type WorkflowSkillSurface = "claude_code" | "codex_cli";
+export interface WorkflowSkillOptions {
+    surface?: WorkflowSkillSurface;
+}
 export declare function compileControllerToSkill(controllerKey: string, controller: ControllerDef, variables?: Record<string, string>, workflows?: Record<string, WorkflowDef>): SkillResult;
-export declare function compileWorkflowToSkill(plan: WorkflowPlan, roles: Record<string, RoleDef>, ir?: ConstraintIR, variables?: Record<string, string>): SkillResult;
+export declare function compileWorkflowToSkill(plan: WorkflowPlan, roles: Record<string, RoleDef>, ir?: ConstraintIR, variables?: Record<string, string>, options?: WorkflowSkillOptions): SkillResult;
 export declare function writeSkillFiles(results: SkillResult[], outputDir: string): Promise<string[]>;
 export declare function removeSkillFiles(outputDir: string): Promise<number>;

package/dist/runtime/skill-adapter.js

@@ -19,26 +19,54 @@ function resolveContainedPath(baseDir, ...segments) {
     }
     return target;
 }
+function isHumanRole(role) {
+    return role?.model?.trim().toLowerCase() === "human";
+}
+function isInteractiveRole(role) {
+    return role?.model?.trim().toLowerCase() === "interactive";
+}
 // ── Compile Controller → Skill ─────────────────────────────
 export function compileControllerToSkill(controllerKey, controller, variables, workflows) {
     const kindMetadata = getControllerKindMetadata(controller.kind);
     if (!kindMetadata?.supportsSkillGeneration) {
         throw new Error(`Unsupported controller kind: ${controller.kind}`);
     }
+    const diagnosisWorkflowName = controller.diagnosis_workflow;
+    const fixWorkflowName = controller.fix_workflow;
+    const diagnosisArtifactPath = controller.diagnosis_artifact_path;
+    const diagnosisReviewArtifactPath = controller.diagnosis_review_artifact_path;
+    const reviewArtifactPath = controller.review_artifact_path;
+    const analyzerRole = controller.roles.analyzer;
+    const analysisReviewerRole = controller.roles.analysis_reviewer;
+    const surgeonRole = controller.roles.surgeon;
+    const fixReviewerRole = controller.roles.fix_reviewer;
+    const testRunnerRole = controller.roles.test_runner;
+    if (!diagnosisWorkflowName ||
+        !fixWorkflowName ||
+        !diagnosisArtifactPath ||
+        !diagnosisReviewArtifactPath ||
+        !reviewArtifactPath ||
+        !analyzerRole ||
+        !analysisReviewerRole ||
+        !surgeonRole ||
+        !fixReviewerRole ||
+        !testRunnerRole) {
+        throw new Error(`Controller '${controllerKey}' is missing fix-loop skill generation fields`);
+    }
     const skillName = `dna-${toKebabCase(controllerKey)}`;
     assertSafeGeneratedName(skillName, "skill name");
-    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 analyzerAgent = `dna-${toKebabCase(analyzerRole)}`;
+    const analysisReviewerAgent = `dna-${toKebabCase(analysisReviewerRole)}`;
+    const surgeonAgent = `dna-${toKebabCase(surgeonRole)}`;
+    const fixReviewerAgent = `dna-${toKebabCase(fixReviewerRole)}`;
+    const testRunnerAgent = `dna-${toKebabCase(testRunnerRole)}`;
+    const diagnosisWorkflow = workflows?.[diagnosisWorkflowName];
+    const fixWorkflow = workflows?.[fixWorkflowName];
+    const diagnosisAnalyzeStep = requireStepByRole(diagnosisWorkflow, analyzerRole, diagnosisWorkflowName);
+    const diagnosisReviewStep = requireStepByRole(diagnosisWorkflow, analysisReviewerRole, diagnosisWorkflowName);
+    const fixBugsStep = requireStepByRole(fixWorkflow, surgeonRole, fixWorkflowName);
+    const reviewChangesStep = requireStepByRole(fixWorkflow, fixReviewerRole, fixWorkflowName);
+    const verifyReportStep = requireStepByRole(fixWorkflow, testRunnerRole, fixWorkflowName);
     const stepPrompt = (step) => step.prompt || step.description || "";
     const policy = normalizeControllerPolicy(controller);
     const lines = [];
@@ -63,8 +91,8 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push("<Controller>");
     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}`);
+    lines.push(`diagnosis_workflow: ${diagnosisWorkflowName}`);
+    lines.push(`fix_workflow: ${fixWorkflowName}`);
     lines.push(`progress_artifact_path: ${controller.progress_artifact_path}`);
     lines.push("</Controller>");
     lines.push("");
@@ -74,8 +102,8 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     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}`);
-    lines.push(`   - Diagnosis review artifact: ${controller.diagnosis_review_artifact_path}`);
+    lines.push(`   - Diagnosis artifact: ${diagnosisArtifactPath}`);
+    lines.push(`   - Diagnosis review artifact: ${diagnosisReviewArtifactPath}`);
     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.");
@@ -289,9 +317,9 @@ function renderControllerPolicyLines(lines, 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,
+        "$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)) {
@@ -381,9 +409,10 @@ function workflowSkillMapEntry(skillName, dirName, plan) {
         produces,
     };
 }
-export function compileWorkflowToSkill(plan, roles, ir, variables) {
+export function compileWorkflowToSkill(plan, roles, ir, variables, options) {
     const lines = [];
     const skillName = `dna-${toKebabCase(plan.name)}`;
+    const surface = options?.surface ?? "claude_code";
     assertSafeGeneratedName(skillName, "skill name");
     // Frontmatter
     lines.push("---");
@@ -492,8 +521,10 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Advisory_Context>");
         lines.push("");
     }
-    // Steps — each step MUST be executed via Agent() tool call
+    // Steps — agent-owned steps are delegated; human-owned steps stay in the main session.
     const usedRoles = new Set(plan.steps.map((s) => s.role));
+    const hasHumanSteps = plan.steps.some((step) => isHumanRole(roles[step.role]));
+    const hasInteractiveSteps = plan.steps.some((step) => isInteractiveRole(roles[step.role]));
     // Pre-compute handoff targets: steps that are pointed to by another step's handoff_to
     const handoffTargets = new Set();
     for (const step of plan.steps) {
@@ -508,6 +539,8 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
             stepNumber++;
             const step = plan.steps.find((s) => s.id === stepId);
             const agentType = `dna-${toKebabCase(step.role)}`;
+            const humanOwned = isHumanRole(roles[step.role]);
+            const interactiveOwned = isInteractiveRole(roles[step.role]);
             const runIf = step.run_if ? `\n   **Condition**: ${step.run_if}` : "";
             const optional = step.optional ? " (optional)" : "";
             // Build agent prompt: anti-recursion + role identity + task
@@ -536,14 +569,34 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
             lines.push(`${stepNumber}. **${step.id}**${optional}`);
             lines.push(`   ${step.description}${runIf}`);
             lines.push("");
-            lines.push(`   Execute with Agent tool — DO NOT perform this work yourself:`);
-            lines.push(`   \`\`\``);
-            lines.push(`   Agent(`);
-            lines.push(`     subagent_type="${agentType}",`);
-            lines.push(`     prompt="${agentPrompt}"`);
-            lines.push(`   )`);
-            lines.push(`   \`\`\``);
-            lines.push(`   Wait for agent to complete. Read the output before proceeding.`);
+            if (humanOwned) {
+                lines.push("   **Human-owned gate (`model: human`)**");
+                lines.push(`   Ask the user in the main session: ${step.prompt || step.description}`);
+                lines.push("   Do not delegate this decision, infer approval, or continue from silence. Continue only after an explicit human response.");
+            }
+            else if (interactiveOwned) {
+                lines.push("   **Main-session external-agent step (`model: interactive`)**");
+                lines.push(`   Perform directly in the main session: ${step.prompt || step.description}`);
+                lines.push("   This step may interview the user or edit the candidate YAML inside its declared scope. Do not delegate away the conversation context.");
+            }
+            else if (surface === "codex_cli") {
+                lines.push("   Delegate to a Codex native subagent with this role contract; do not discard the role boundaries:");
+                lines.push("   ```text");
+                lines.push(`   role: ${agentType}`);
+                lines.push(`   prompt: ${agentPrompt}`);
+                lines.push("   ```");
+                lines.push("   Wait for the subagent to complete and read its output before proceeding.");
+            }
+            else {
+                lines.push(`   Execute with Agent tool — DO NOT perform this work yourself:`);
+                lines.push(`   \`\`\``);
+                lines.push(`   Agent(`);
+                lines.push(`     subagent_type="${agentType}",`);
+                lines.push(`     prompt="${agentPrompt}"`);
+                lines.push(`   )`);
+                lines.push(`   \`\`\``);
+                lines.push(`   Wait for agent to complete. Read the output before proceeding.`);
+            }
             if (step.handoff?.produces && step.handoff.produces.length > 0) {
                 const artifacts = step.handoff.produces.map(p => p.description).join(", ");
                 lines.push(`   Verify produced artifacts: ${artifacts}`);
@@ -565,14 +618,39 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
     }
     lines.push("</Steps>");
     lines.push("");
-    // Execution Policy — force Agent dispatch
+    if (plan.retry.max_retries > 0) {
+        lines.push("<Retry_Policy>");
+        lines.push(`- max_retries: ${plan.retry.max_retries}`);
+        lines.push(`- retry_from: ${plan.retry.retry_from ?? "first_failed_step"}`);
+        lines.push(`- backoff: ${plan.retry.backoff}`);
+        lines.push("- On a blocking checkpoint or validator failure, preserve the exact diagnostics and return them to the retry_from step.");
+        lines.push("- Repeat only the retry slice and its dependent steps; do not continue to save, adoption, or sync while validation is red.");
+        lines.push("- Stop and report the remaining diagnostics when the retry budget is exhausted.");
+        lines.push("</Retry_Policy>");
+        lines.push("");
+    }
+    // Execution Policy — force delegation while preserving explicit human gates.
     lines.push("<Execution_Policy>");
-    lines.push("- **CRITICAL**: Each step MUST be executed by spawning an Agent using the Agent tool with the specified subagent_type. DO NOT perform any step's work directly in the main session.");
+    if (surface === "codex_cli") {
+        lines.push("- **CRITICAL**: Delegate each delegated-agent step to a Codex native subagent using the specified role contract. Do not collapse distinct roles into an unreviewed single pass.");
+    }
+    else {
+        lines.push(hasHumanSteps || hasInteractiveSteps
+            ? "- **CRITICAL**: Each delegated-agent step MUST be executed by spawning an Agent using the Agent tool with the specified subagent_type. DO NOT perform delegated-agent work directly in the main session."
+            : "- **CRITICAL**: Each step MUST be executed by spawning an Agent using the Agent tool with the specified subagent_type. DO NOT perform any step's work directly in the main session.");
+    }
     lines.push("- Use the task tracker to track each step only as pending/in_progress/completed; use deleted only for skipped dependent tasks.");
-    lines.push("- After completing each step, immediately proceed to the next — do not stop, summarize, or wait for confirmation.");
+    lines.push(hasHumanSteps
+        ? "- Proceed automatically between non-human steps, but stop at every `model: human` step and require an explicit user response before continuing."
+        : "- After completing each step, immediately proceed to the next — do not stop, summarize, or wait for confirmation.");
+    if (hasInteractiveSteps) {
+        lines.push("- Execute `model: interactive` steps in the main session so interview answers and candidate edits remain in the user-visible conversation.");
+    }
     lines.push("- If a step cannot complete, do not use a failed status. Keep the current task in_progress or record the blocker in the task description/output, delete skipped dependent tasks, and continue only to non-dependent steps.");
-    lines.push("- Do not ask the user for permission between steps — the workflow is pre-approved.");
-    lines.push("- Wait for each Agent to complete and read its output before proceeding to the next step.");
+    lines.push(hasHumanSteps
+        ? "- Never auto-approve, delegate, or synthesize a human-owned decision."
+        : "- Do not ask the user for permission between steps — the workflow is pre-approved.");
+    lines.push("- Wait for each delegated agent to complete and read its output before proceeding to the next step.");
     lines.push("</Execution_Policy>");
     lines.push("");
     // Tool_Usage — only if roles have permissions or scope
@@ -585,9 +663,15 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         const denied = role.tool_permissions?.deny?.join(", ") || "none";
         const writeScope = role.scope?.write?.join(", ") || "none";
         toolUsageLines.push(`### ${roleName}`);
+        toolUsageLines.push(`- Owner: ${isHumanRole(role) ? "human" : isInteractiveRole(role) ? "main_session_external_agent" : "delegated_agent"}`);
+        toolUsageLines.push(`- Description: ${role.description}`);
         toolUsageLines.push(`- Allowed: ${allowed}`);
         toolUsageLines.push(`- Denied: ${denied}`);
         toolUsageLines.push(`- Write scope: ${writeScope}`);
+        for (const instruction of role.instructions ?? [])
+            toolUsageLines.push(`- Instruction: ${instruction}`);
+        for (const criterion of role.success_criteria ?? [])
+            toolUsageLines.push(`- Success criterion: ${criterion}`);
     }
     if (toolUsageLines.length > 0) {
         lines.push("<Tool_Usage>");
@@ -631,6 +715,8 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
             for (const cp of step.checkpoints) {
                 const action = cp.action || "block";
                 lines.push(`- ${cp.assert}: ${cp.message} (${action})`);
+                if (cp.command)
+                    lines.push(`  command: ${cp.command}`);
             }
         }
         lines.push("</Checkpoints>");