intentdna 1.6.4 → 1.7.0

package/dist/runtime/context-sources.d.ts

@@ -0,0 +1,14 @@
+import type { CompiledAdvisoryContextSource } from "../schema/types.js";
+export interface ContextSourceDocument {
+    source: CompiledAdvisoryContextSource;
+    content?: string;
+}
+export interface ContextSourceIndex {
+    sources: CompiledAdvisoryContextSource[];
+    planning_instructions: string[];
+}
+export declare function loadContextSourceIndex(projectDir: string, files?: string[]): Promise<ContextSourceIndex>;
+export declare function searchContextSources(index: ContextSourceIndex, query: string): CompiledAdvisoryContextSource[];
+export declare function findContextSource(index: ContextSourceIndex, id: string): CompiledAdvisoryContextSource | undefined;
+export declare function readContextSourceDocument(projectDir: string, source: CompiledAdvisoryContextSource): Promise<ContextSourceDocument>;
+export declare function formatContextSource(source: CompiledAdvisoryContextSource): string;

package/dist/runtime/context-sources.js

@@ -0,0 +1,60 @@
+import { readFile, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { compileFromFiles, detectDNAConfigs, expandDNAInputFiles } from "../compiler/index.js";
+export async function loadContextSourceIndex(projectDir, files) {
+    const inputFiles = files && files.length > 0
+        ? files.map((file) => resolve(projectDir, file))
+        : await detectDNAConfigs(projectDir);
+    if (inputFiles.length === 0)
+        return { sources: [], planning_instructions: [] };
+    const expandedFiles = await expandDNAInputFiles(inputFiles);
+    const ir = await compileFromFiles(expandedFiles);
+    return {
+        sources: ir.context_sources ?? [],
+        planning_instructions: ir.planning_context?.instructions ?? [],
+    };
+}
+export function searchContextSources(index, query) {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized)
+        return index.sources;
+    return index.sources.filter((source) => {
+        const haystack = [
+            source.id,
+            source.type,
+            source.path,
+            source.url,
+            source.title,
+            source.description,
+            ...(source.tags ?? []),
+        ].filter(Boolean).join("\n").toLowerCase();
+        return haystack.includes(normalized);
+    });
+}
+export function findContextSource(index, id) {
+    return index.sources.find((source) => source.id === id);
+}
+export async function readContextSourceDocument(projectDir, source) {
+    if (source.type !== "file" && source.type !== "doc") {
+        return { source };
+    }
+    if (!source.path)
+        return { source };
+    if (isAbsolute(source.path) || source.path.split(/[\\/]+/).includes("..")) {
+        throw new Error(`Context source '${source.id}' path must stay within the project`);
+    }
+    const projectRoot = await realpath(projectDir);
+    const filePath = await realpath(resolve(projectRoot, source.path));
+    const rel = relative(projectRoot, filePath);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`Context source '${source.id}' path must stay within the project`);
+    }
+    const content = await readFile(filePath, "utf-8");
+    return { source, content };
+}
+export function formatContextSource(source) {
+    const locator = source.path ?? source.url ?? "(no locator)";
+    const title = source.title ? ` — ${source.title}` : "";
+    const tags = source.tags?.length ? ` [${source.tags.join(", ")}]` : "";
+    return `${source.id}: ${source.type} ${locator}${title}${tags}`;
+}

package/dist/runtime/markdown-target-registry.d.ts

@@ -0,0 +1,17 @@
+export declare const MARKDOWN_TARGET_IDS: readonly ["claude-md", "soul-md", "cursorrules", "system-prompt", "agents-md"];
+export type MarkdownTarget = typeof MARKDOWN_TARGET_IDS[number];
+export type MarkdownRenderer<TIR = unknown> = (ir: TIR) => string;
+export interface MarkdownTargetMetadata {
+    id: MarkdownTarget;
+    label: string;
+    supportsSyncInject: boolean;
+}
+export interface MarkdownTargetRuntime<TIR = unknown> extends MarkdownTargetMetadata {
+    render: MarkdownRenderer<TIR>;
+}
+export declare const MARKDOWN_TARGET_REGISTRY: readonly MarkdownTargetMetadata[];
+export declare function getMarkdownTargetMetadata(target: unknown): MarkdownTargetMetadata | undefined;
+export declare function isMarkdownTarget(target: unknown): target is MarkdownTarget;
+export declare function syncInjectMarkdownTargets(): MarkdownTarget[];
+export declare function bindMarkdownTargetRenderers<TIR>(renderers: Record<MarkdownTarget, MarkdownRenderer<TIR>>): readonly MarkdownTargetRuntime<TIR>[];
+export declare function getMarkdownTargetRuntime<TIR>(target: unknown, renderers: Record<MarkdownTarget, MarkdownRenderer<TIR>>): MarkdownTargetRuntime<TIR> | undefined;

package/dist/runtime/markdown-target-registry.js

@@ -0,0 +1,37 @@
+export const MARKDOWN_TARGET_IDS = [
+    "claude-md",
+    "soul-md",
+    "cursorrules",
+    "system-prompt",
+    "agents-md",
+];
+export const MARKDOWN_TARGET_REGISTRY = [
+    { id: "claude-md", label: "CLAUDE.md", supportsSyncInject: true },
+    { id: "soul-md", label: "SOUL.md", supportsSyncInject: true },
+    { id: "cursorrules", label: ".cursorrules", supportsSyncInject: true },
+    { id: "system-prompt", label: "System prompt", supportsSyncInject: true },
+    { id: "agents-md", label: "AGENTS.md", supportsSyncInject: false },
+];
+const TARGET_BY_ID = new Map(MARKDOWN_TARGET_REGISTRY.map((entry) => [entry.id, entry]));
+export function getMarkdownTargetMetadata(target) {
+    return typeof target === "string" ? TARGET_BY_ID.get(target) : undefined;
+}
+export function isMarkdownTarget(target) {
+    return getMarkdownTargetMetadata(target) !== undefined;
+}
+export function syncInjectMarkdownTargets() {
+    return MARKDOWN_TARGET_REGISTRY
+        .filter((entry) => entry.supportsSyncInject)
+        .map((entry) => entry.id);
+}
+export function bindMarkdownTargetRenderers(renderers) {
+    return MARKDOWN_TARGET_REGISTRY.map((entry) => ({
+        ...entry,
+        render: renderers[entry.id],
+    }));
+}
+export function getMarkdownTargetRuntime(target, renderers) {
+    if (typeof target !== "string")
+        return undefined;
+    return bindMarkdownTargetRenderers(renderers).find((entry) => entry.id === target);
+}

package/dist/runtime/markdown.d.ts

@@ -13,7 +13,8 @@
  *   <!-- intentdna:end -->
  */
 import type { ConstraintIR } from "../schema/types.js";
-export type MarkdownTarget = "claude-md" | "soul-md" | "cursorrules" | "system-prompt" | "agents-md";
+import { type MarkdownTarget } from "./markdown-target-registry.js";
+export type { MarkdownTarget } from "./markdown-target-registry.js";
 /**
  * Compile Constraint IR to a markdown block suitable for the target format.
  */

package/dist/runtime/markdown.js

@@ -13,24 +13,21 @@
  *   <!-- intentdna:end -->
  */
 import { readFile, writeFile } from "node:fs/promises";
+import { getMarkdownTargetRuntime } from "./markdown-target-registry.js";
 const SENTINEL_START = "<!-- intentdna:start -->";
 const SENTINEL_END = "<!-- intentdna:end -->";
+const MARKDOWN_RENDERERS = {
+    "claude-md": renderClaudeMd,
+    "soul-md": renderSoulMd,
+    cursorrules: renderCursorrules,
+    "system-prompt": renderSystemPrompt,
+    "agents-md": renderAgentsMd,
+};
 /**
  * Compile Constraint IR to a markdown block suitable for the target format.
  */
 export function compileToMarkdown(ir, target) {
-    switch (target) {
-        case "claude-md":
-            return renderClaudeMd(ir);
-        case "soul-md":
-            return renderSoulMd(ir);
-        case "cursorrules":
-            return renderCursorrules(ir);
-        case "system-prompt":
-            return renderSystemPrompt(ir);
-        case "agents-md":
-            return renderAgentsMd(ir);
-    }
+    return getMarkdownTargetRuntime(target, MARKDOWN_RENDERERS).render(ir);
 }
 /**
  * Wrap content in sentinel comments for idempotent injection.

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

@@ -0,0 +1,11 @@
+export declare const SYNC_OUTPUT_ARTIFACT_IDS: readonly ["markdown-injection", "compiled-ir", "settings-hooks", "agents", "workflows", "skills-controllers", "mcp-config", "lock-file"];
+export type SyncOutputArtifactId = typeof SYNC_OUTPUT_ARTIFACT_IDS[number];
+export interface SyncOutputArtifactMetadata {
+    id: SyncOutputArtifactId;
+    order: number;
+    label: string;
+    trackedByLock: boolean;
+}
+export declare const SYNC_OUTPUT_ARTIFACT_REGISTRY: readonly SyncOutputArtifactMetadata[];
+export declare function getSyncOutputArtifactMetadata(id: unknown): SyncOutputArtifactMetadata | undefined;
+export declare function syncOutputArtifactIds(): SyncOutputArtifactId[];

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

@@ -0,0 +1,30 @@
+export const SYNC_OUTPUT_ARTIFACT_IDS = [
+    "markdown-injection",
+    "compiled-ir",
+    "settings-hooks",
+    "agents",
+    "workflows",
+    "skills-controllers",
+    "mcp-config",
+    "lock-file",
+];
+export const SYNC_OUTPUT_ARTIFACT_REGISTRY = [
+    { id: "markdown-injection", order: 30, label: "Markdown injection", trackedByLock: true },
+    { id: "compiled-ir", order: 35, label: "Compiled IR", trackedByLock: true },
+    { id: "settings-hooks", order: 36, label: "Settings hooks", trackedByLock: true },
+    { id: "agents", order: 50, label: "Agents", trackedByLock: true },
+    { 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: "lock-file", order: 90, label: "Lock file", trackedByLock: false },
+];
+const ARTIFACT_BY_ID = new Map(SYNC_OUTPUT_ARTIFACT_REGISTRY.map((entry) => [entry.id, entry]));
+export function getSyncOutputArtifactMetadata(id) {
+    return typeof id === "string" ? ARTIFACT_BY_ID.get(id) : undefined;
+}
+export function syncOutputArtifactIds() {
+    return SYNC_OUTPUT_ARTIFACT_REGISTRY
+        .slice()
+        .sort((a, b) => a.order - b.order)
+        .map((entry) => entry.id);
+}

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

@@ -6,7 +6,8 @@
  *
  * See docs/references/cc-source-analysis.md §2 for the full hook event catalog.
  */
-export type HookEventKey = "preToolUse" | "postToolUse" | "userPromptSubmit" | "subagentStop" | "preCompact" | "notification" | "stop";
+import { type SettingsHookEventKey } from "../hooks/event-registry.js";
+export type HookEventKey = SettingsHookEventKey;
 export interface SettingsHookEntry {
     matcher: string;
     hooks: Array<{

package/dist/runtime/settings-adapter.js

@@ -7,17 +7,8 @@
  * See docs/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";
 // ── Plugin Mode (Node.js hooks via dna-hook binary) ───────
-/** Hook event key → Claude Code settings event name */
-const HOOK_EVENT_MAP = {
-    preToolUse: "PreToolUse",
-    postToolUse: "PostToolUse",
-    userPromptSubmit: "UserPromptSubmit",
-    subagentStop: "SubagentStop",
-    preCompact: "PreCompact",
-    notification: "Notification",
-    stop: "Stop",
-};
 /**
  * Compile settings.json hook configuration for dna-hook binary.
  * Uses `dna-hook <event>` commands.
@@ -25,7 +16,7 @@ const HOOK_EVENT_MAP = {
 export function compilePluginSettings(enabledEvents, timeout = 10, timeouts) {
     const settings = { hooks: {} };
     for (const key of enabledEvents) {
-        const eventName = HOOK_EVENT_MAP[key];
+        const eventName = getHookEventBySettingsKey(key)?.event;
         if (!eventName)
             continue;
         const eventTimeout = timeouts?.[key] ?? timeout;
@@ -120,7 +111,8 @@ export async function mergeSettingsFile(dnaSettings, settingsPath) {
         mergedHooks[eventName] = [...nonDNA, ...entries];
     }
     // Remove DNA hook events that are no longer generated
-    for (const eventName of Object.values(HOOK_EVENT_MAP)) {
+    for (const key of settingsHookEventKeys()) {
+        const eventName = getHookEventBySettingsKey(key).event;
         if (!dnaSettings.hooks[eventName] && mergedHooks[eventName]) {
             const entries = mergedHooks[eventName];
             const nonDNA = entries.filter((h) => {

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

@@ -7,17 +7,45 @@
  * Skills are compiled views of DNA's structured definitions — not stored content.
  */
 import type { WorkflowPlan, WorkflowDef, RoleDef, ConstraintIR, ControllerDef } from "../schema/types.js";
+export interface SkillFile {
+    relativePath: string;
+    content: string;
+}
+export interface SkillMapEntry {
+    name: string;
+    dirName: string;
+    source: string;
+    kind: "workflow" | "controller";
+    bodyPath: string;
+    roles: string[];
+    consumes: Array<{
+        step_id: string;
+        type: string;
+        path?: string;
+        name?: string;
+        artifact_id?: string;
+        description: string;
+    }>;
+    produces: Array<{
+        step_id: string;
+        type: string;
+        path?: string;
+        name?: string;
+        artifact_id?: string;
+        description: string;
+    }>;
+}
 export interface SkillResult {
     name: string;
     fileName: string;
     dirName: string;
     content: string;
+    launcherContent?: string;
+    bodyContent?: string;
+    bodyFileName?: string;
+    mapEntry?: SkillMapEntry;
 }
 export declare function compileControllerToSkill(controllerKey: string, controller: ControllerDef, variables?: Record<string, string>, workflows?: Record<string, WorkflowDef>): SkillResult;
-/**
- * Compile a WorkflowPlan + roles + IR into a SKILL.md file.
- * Variables from DNA config are substituted into prompts and descriptions.
- */
 export declare function compileWorkflowToSkill(plan: WorkflowPlan, roles: Record<string, RoleDef>, ir?: ConstraintIR, variables?: Record<string, string>): 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

@@ -7,15 +7,26 @@
  * Skills are compiled views of DNA's structured definitions — not stored content.
  */
 import { mkdir, writeFile, readdir, readFile, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { toKebabCase } from "./agent-md.js";
+import { join, resolve, sep } from "node:path";
+import { getControllerKindMetadata } from "../schema/controller-registry.js";
+import { assertSafeGeneratedName, toKebabCase } from "./agent-md.js";
 const SENTINEL = "<!-- intentdna:managed — do not edit manually -->";
+function resolveContainedPath(baseDir, ...segments) {
+    const base = resolve(baseDir);
+    const target = resolve(baseDir, ...segments);
+    if (target !== base && !target.startsWith(`${base}${sep}`)) {
+        throw new Error(`generated path escapes output directory: ${target}`);
+    }
+    return target;
+}
 // ── Compile Controller → Skill ─────────────────────────────
 export function compileControllerToSkill(controllerKey, controller, variables, workflows) {
-    if (controller.kind !== "fix_loop" && controller.kind !== "flutter_rewrite_fix_loop") {
+    const kindMetadata = getControllerKindMetadata(controller.kind);
+    if (!kindMetadata?.supportsSkillGeneration) {
         throw new Error(`Unsupported controller kind: ${controller.kind}`);
     }
     const skillName = `dna-${toKebabCase(controllerKey)}`;
+    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)}`;
@@ -134,6 +145,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push("</Verdict_Mapping>");
     lines.push("");
     lines.push("<Stop_Report>");
+    lines.push("Every critical decision in the stop report must cite at least one verifier result_id, trace_id, or ArtifactManifest artifact id; prose-only claims are not sufficient.");
     for (const line of policy.stop_report) {
         lines.push(line);
     }
@@ -153,7 +165,28 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     }
     const dirName = skillName;
     const fileName = join(dirName, "SKILL.md");
-    return { name: skillName, fileName, dirName, content };
+    return attachSkillBody({ name: skillName, fileName, dirName, content }, {
+        description: controller.description || controller.name,
+        triggers: [toKebabCase(controllerKey), `run ${toKebabCase(controllerKey)}`],
+        kind: "controller",
+        mapEntry: {
+            name: skillName,
+            dirName,
+            source: controllerKey,
+            kind: "controller",
+            bodyPath: join(dirName, "skill-bodies", "body.md"),
+            roles: Object.values(controller.roles),
+            consumes: [
+                { step_id: "controller", type: "file", path: controller.diagnosis_artifact_path, description: "Diagnosis artifact" },
+                { step_id: "controller", type: "file", path: controller.diagnosis_review_artifact_path, description: "Diagnosis review artifact" },
+                { step_id: "controller", type: "file", path: controller.review_artifact_path, description: "Fix review artifact" },
+                { step_id: "controller", type: "file", path: controller.progress_artifact_path, description: "Progress JSON artifact" },
+            ],
+            produces: [
+                { step_id: "controller", type: "file", path: controller.progress_artifact_path, description: "Progress JSON artifact" },
+            ],
+        },
+    });
 }
 function requireStepByRole(workflow, role, workflowName) {
     const step = workflow?.steps.find((candidate) => candidate.role === role);
@@ -162,6 +195,73 @@ function requireStepByRole(workflow, role, workflowName) {
     }
     return step;
 }
+function createSkillLauncher(params) {
+    const lines = [];
+    lines.push("---");
+    lines.push(`name: ${params.skillName}`);
+    lines.push(`description: "Use when user says /${params.skillName}. ${escapeYaml(params.description)}"`);
+    lines.push("user-invocable: true");
+    lines.push("triggers:");
+    for (const trigger of params.triggers)
+        lines.push(`  - "${escapeYaml(trigger)}"`);
+    lines.push("---");
+    lines.push("");
+    lines.push(SENTINEL);
+    lines.push(`<!-- Compiled: ${new Date().toISOString()} -->`);
+    lines.push("");
+    lines.push(`# /${params.skillName}`);
+    lines.push("");
+    lines.push("<Purpose>");
+    lines.push(params.description);
+    lines.push("</Purpose>");
+    lines.push("");
+    lines.push("<Skill_Body>");
+    lines.push(`Full ${params.kind} instructions live in \`skill-bodies/${params.bodyFileName}\`.`);
+    lines.push("Read that body before executing any step; the launcher is only an entrypoint.");
+    lines.push("</Skill_Body>");
+    lines.push("");
+    if (params.bodyContent.includes("<Required_Context>")) {
+        lines.push("<Required_Context>");
+        lines.push("The skill body contains required context files. Read them before any Edit, Write, or Bash action.");
+        lines.push("</Required_Context>");
+        lines.push("");
+    }
+    if (params.bodyContent.includes("<Advisory_Context>")) {
+        lines.push("<Advisory_Context>");
+        lines.push("The skill body contains planning-only advisory context sources. Quote and cite them when used; they never satisfy handoff or enforcement checks.");
+        lines.push("</Advisory_Context>");
+        lines.push("");
+    }
+    if (params.bodyContent.includes("<Handoff>")) {
+        lines.push("<Handoff>");
+        lines.push("Write human-readable handoff notes when requested, but do not treat handoff.md as a machine fact.");
+        lines.push("ArtifactManifest entries written by runtime hooks remain the machine source of truth for handoff satisfaction.");
+        lines.push("</Handoff>");
+        lines.push("");
+    }
+    lines.push("<Execution>");
+    lines.push(`Follow \`skill-bodies/${params.bodyFileName}\` exactly.`);
+    lines.push("</Execution>");
+    return lines.join("\n") + "\n";
+}
+function attachSkillBody(result, params) {
+    const bodyFileName = "body.md";
+    const launcherContent = createSkillLauncher({
+        skillName: result.name,
+        description: params.description,
+        triggers: params.triggers,
+        bodyFileName,
+        bodyContent: result.content,
+        kind: params.kind,
+    });
+    return {
+        ...result,
+        launcherContent,
+        bodyContent: result.content,
+        bodyFileName,
+        mapEntry: params.mapEntry,
+    };
+}
 function normalizeControllerPolicy(controller) {
     const defaults = defaultControllerPolicy(controller);
     const policy = {
@@ -232,7 +332,7 @@ function defaultControllerPolicy(controller) {
             "- MAX_ROUNDS: stop and report max rounds reached",
         ],
         stop_report: [
-            "On REQUEST_CHANGES, BLOCKED, or MAX_ROUNDS, explain the stop reason, the evidence, and the next action.",
+            "On REQUEST_CHANGES, BLOCKED, or MAX_ROUNDS, explain the stop reason, the evidence, the next action, and cite at least one verifier result_id, trace_id, or ArtifactManifest artifact id.",
         ],
         constraints: [
             `The controller must schedule only from ${controller.progress_artifact_path}.`,
@@ -245,9 +345,46 @@ function defaultControllerPolicy(controller) {
  * Compile a WorkflowPlan + roles + IR into a SKILL.md file.
  * Variables from DNA config are substituted into prompts and descriptions.
  */
+function workflowSkillMapEntry(skillName, dirName, plan) {
+    const consumes = [];
+    const produces = [];
+    for (const step of plan.steps) {
+        for (const artifact of step.handoff?.consumes ?? []) {
+            consumes.push({
+                step_id: step.id,
+                type: artifact.type,
+                path: artifact.path,
+                name: artifact.name,
+                artifact_id: artifact.artifact_id,
+                description: artifact.description,
+            });
+        }
+        for (const artifact of step.handoff?.produces ?? []) {
+            produces.push({
+                step_id: step.id,
+                type: artifact.type,
+                path: artifact.path,
+                name: artifact.name,
+                artifact_id: artifact.artifact_id,
+                description: artifact.description,
+            });
+        }
+    }
+    return {
+        name: skillName,
+        dirName,
+        source: plan.workflow_key ?? plan.source_workflow,
+        kind: "workflow",
+        bodyPath: join(dirName, "skill-bodies", "body.md"),
+        roles: [...new Set(plan.steps.map((step) => step.role))],
+        consumes,
+        produces,
+    };
+}
 export function compileWorkflowToSkill(plan, roles, ir, variables) {
     const lines = [];
     const skillName = `dna-${toKebabCase(plan.name)}`;
+    assertSafeGeneratedName(skillName, "skill name");
     // Frontmatter
     lines.push("---");
     lines.push(`name: ${skillName}`);
@@ -339,6 +476,22 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Required_Context>");
         lines.push("");
     }
+    if (ir?.context_sources?.length) {
+        lines.push("<Advisory_Context>");
+        lines.push("These sources are planning-only references. They do not satisfy ArtifactManifest, handoff consumes, completion checks, or enforcement facts.");
+        lines.push("If you use them, quote the relevant passage and cite the source id.");
+        lines.push("");
+        for (const source of ir.context_sources) {
+            const locator = source.path ?? source.url ?? "(no locator)";
+            const title = source.title ? ` — ${source.title}` : "";
+            lines.push(`- ${source.id}: ${source.type} ${locator}${title}`);
+        }
+        for (const instruction of ir.planning_context?.instructions ?? []) {
+            lines.push(`- Planning instruction: ${instruction}`);
+        }
+        lines.push("</Advisory_Context>");
+        lines.push("");
+    }
     // Steps — each step MUST be executed via Agent() tool call
     const usedRoles = new Set(plan.steps.map((s) => s.role));
     // Pre-compute handoff targets: steps that are pointed to by another step's handoff_to
@@ -487,6 +640,8 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
     const stepsWithHandoff = plan.steps.filter((s) => s.handoff && (s.handoff.consumes?.length || s.handoff.produces?.length));
     if (stepsWithHandoff.length > 0) {
         lines.push("<Handoff>");
+        lines.push("Human-readable handoff notes are useful for review, but they do not satisfy machine handoff gates.");
+        lines.push("ArtifactManifest records written by runtime hooks remain the machine source of truth for produced/consumed artifacts.");
         for (const step of stepsWithHandoff) {
             const h = step.handoff;
             if (h.produces && h.produces.length > 0) {
@@ -530,7 +685,12 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
     }
     const dirName = skillName;
     const fileName = join(dirName, "SKILL.md");
-    return { name: skillName, fileName, dirName, content };
+    return attachSkillBody({ name: skillName, fileName, dirName, content }, {
+        description: plan.description || plan.name,
+        triggers: [plan.name, `run ${plan.name}`],
+        kind: "workflow",
+        mapEntry: workflowSkillMapEntry(skillName, dirName, plan),
+    });
 }
 /** Collect all {{var_name}} references from a workflow plan. */
 function collectVariableRefs(plan) {
@@ -553,12 +713,29 @@ function collectVariableRefs(plan) {
 // ── File Operations ────────────────────────────────────────
 export async function writeSkillFiles(results, outputDir) {
     const written = [];
+    const mapEntries = [];
     for (const result of results) {
-        const dir = join(outputDir, result.dirName);
+        assertSafeGeneratedName(result.dirName, "skill directory");
+        const dir = resolveContainedPath(outputDir, result.dirName);
         await mkdir(dir, { recursive: true });
-        const path = join(dir, "SKILL.md");
-        await writeFile(path, result.content, "utf-8");
-        written.push(path);
+        const skillPath = resolveContainedPath(dir, "SKILL.md");
+        await writeFile(skillPath, result.launcherContent ?? result.content, "utf-8");
+        written.push(skillPath);
+        if (result.bodyContent && result.bodyFileName) {
+            assertSafeGeneratedName(result.bodyFileName.replace(/\.md$/, ""), "skill body file");
+            const bodyDir = resolveContainedPath(dir, "skill-bodies");
+            await mkdir(bodyDir, { recursive: true });
+            const bodyPath = resolveContainedPath(bodyDir, result.bodyFileName);
+            await writeFile(bodyPath, result.bodyContent, "utf-8");
+            written.push(bodyPath);
+        }
+        if (result.mapEntry)
+            mapEntries.push(result.mapEntry);
+    }
+    if (mapEntries.length > 0) {
+        const mapPath = resolveContainedPath(outputDir, ".intentdna-skill-map.json");
+        await writeFile(mapPath, JSON.stringify({ generated_at: new Date().toISOString(), skills: mapEntries }, null, 2) + "\n", "utf-8");
+        written.push(mapPath);
     }
     return written;
 }

package/dist/runtime/workflow-runner.d.ts

@@ -19,7 +19,7 @@ export interface WorkflowShellOptions {
     maxBudgetPerAgent?: number;
     /** Output format for agent results (default "json") */
     outputFormat?: "json" | "text";
-    /** Permission mode (default "bypassPermissions") */
+    /** Permission mode (default "default") */
     permissionMode?: string;
     /** Log directory relative to project root (default ".") */
     logDir?: string;

package/dist/runtime/workflow-runner.js

@@ -466,7 +466,7 @@ export function compileWorkflowToShell(plan, options) {
         agentPrefix: options?.agentPrefix ?? "dna-",
         maxBudgetPerAgent: options?.maxBudgetPerAgent ?? 10,
         outputFormat: options?.outputFormat ?? "json",
-        permissionMode: options?.permissionMode ?? "bypassPermissions",
+        permissionMode: options?.permissionMode ?? "default",
         logDir: options?.logDir ?? ".",
         pauseSupport: options?.pauseSupport ?? false,
     };

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

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