intentdna 1.6.5 → 1.7.0

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/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,10 +7,18 @@
  * 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 { join, resolve, sep } from "node:path";
 import { getControllerKindMetadata } from "../schema/controller-registry.js";
-import { toKebabCase } from "./agent-md.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) {
     const kindMetadata = getControllerKindMetadata(controller.kind);
@@ -18,6 +26,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
         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)}`;
@@ -136,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);
     }
@@ -155,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);
@@ -164,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 = {
@@ -234,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}.`,
@@ -247,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}`);
@@ -341,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
@@ -489,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) {
@@ -532,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) {
@@ -555,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/types.d.ts

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

package/dist/schema/validate.js

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