intentdna 1.6.5 → 1.7.4

package/dist/runtime/claude-sdk.d.ts

@@ -8,7 +8,7 @@
  *   post_execution_validators → PostToolUse hooks
  *   context_injections    → UserPromptSubmit hook
  */
-import type { ConstraintIR } from "../schema/types.js";
+import type { CompiledProvenanceManifest, ConstraintIR, ConstraintProvenance } from "../schema/types.js";
 export interface DNAHookOutput {
     hookSpecificOutput?: {
         hookEventName: string;
@@ -32,19 +32,24 @@ export interface ClaudeDNAConfig {
     source_dna_ids: string[];
     /** Compilation timestamp */
     compiled_at: string;
+    /** Stable compiled IR hash for runtime decision events */
+    compiled_ir_hash?: string;
+    /** Cascade/source provenance for SDK-side checks */
+    provenance?: CompiledProvenanceManifest;
 }
 export interface PreToolRule {
     condition: string;
     action: "block" | "escalate" | "warn";
     message: string;
     source_gene: string;
+    constraint_provenance?: ConstraintProvenance;
+    compiled_ir_hash?: string;
 }
 export interface PostToolRule {
     check: string;
     threshold?: number;
     source_gene: string;
+    constraint_provenance?: ConstraintProvenance;
+    compiled_ir_hash?: string;
 }
-/**
- * Compile Constraint IR to Claude Agent SDK configuration.
- */
 export declare function compileForClaude(ir: ConstraintIR): ClaudeDNAConfig;

package/dist/runtime/claude-sdk.js

@@ -12,6 +12,9 @@
 /**
  * Compile Constraint IR to Claude Agent SDK configuration.
  */
+function provenanceForGene(ir, geneId) {
+    return ir.provenance?.constraint_winners.find((constraint) => constraint.gene_id === geneId);
+}
 export function compileForClaude(ir) {
     // Build system prompt addition from directives
     const promptLines = [];
@@ -61,11 +64,15 @@ export function compileForClaude(ir) {
             action: g.action,
             message: g.message,
             source_gene: g.source_gene,
+            constraint_provenance: provenanceForGene(ir, g.source_gene),
+            compiled_ir_hash: ir.compiled_ir_hash,
         })),
         post_tool_rules: ir.post_execution_validators.map((v) => ({
             check: v.check,
             threshold: v.threshold,
             source_gene: v.source_gene,
+            constraint_provenance: provenanceForGene(ir, v.source_gene),
+            compiled_ir_hash: ir.compiled_ir_hash,
         })),
         context_additions: ir.context_injections.map((c) => c.text),
         deprioritized_tools: ir.tool_filters
@@ -73,5 +80,7 @@ export function compileForClaude(ir) {
             .map((f) => f.target),
         source_dna_ids: ir.source_dna_ids,
         compiled_at: ir.compiled_at,
+        compiled_ir_hash: ir.compiled_ir_hash,
+        provenance: ir.provenance,
     };
 }

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/plugin-adapter.d.ts

@@ -6,7 +6,7 @@
  *
  * This is the bridge between compile-time (dna sync) and runtime (hook execution).
  */
-import type { ConstraintIR, RoleDef } from "../schema/types.js";
+import type { CompiledProvenanceManifest, ConstraintIR, RoleDef } from "../schema/types.js";
 /** Wrapper around ConstraintIR with versioning metadata */
 export interface CompiledIRFile {
     /** Schema version for forward compatibility */
@@ -19,6 +19,10 @@ export interface CompiledIRFile {
     ir: ConstraintIR;
     /** Cascaded role definitions (for output_schema enforcement) */
     roles?: Record<string, RoleDef>;
+    /** Stable hash of the compiled IR payload, excluding provenance/hash fields */
+    compiled_ir_hash?: string;
+    /** Cascade and source provenance used by enterprise evidence */
+    provenance?: CompiledProvenanceManifest;
 }
 /**
  * Create a CompiledIRFile wrapper around a ConstraintIR.

package/dist/runtime/plugin-adapter.js

@@ -20,6 +20,8 @@ export function createCompiledIR(ir, roles) {
         source_dna_ids: ir.source_dna_ids,
         ir,
         roles: roles && Object.keys(roles).length > 0 ? roles : undefined,
+        compiled_ir_hash: ir.compiled_ir_hash,
+        provenance: ir.provenance,
     };
 }
 /**

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

@@ -17,9 +17,16 @@ export interface RepelCodon {
     type: "repel";
     target: string;
 }
+export interface ConstraintOrigin {
+    source_dna_id: string;
+    source_layer: DNAType;
+    cascade_priority: number;
+    protected_threshold?: boolean;
+}
 export interface ThresholdCodon {
     type: "threshold";
     condition: string;
+    origin?: ConstraintOrigin;
 }
 export interface WeightCodon {
     type: "weight";
@@ -262,6 +269,47 @@ export interface CascadeConfig {
     inherits: string[];
     priority: number;
 }
+export type ProvenanceCascadeLayerName = "species" | "enterprise" | "project" | "personal" | "role" | "context" | "task";
+export type ProvenanceLayerStatus = "active" | "unknown" | "unsupported";
+export type ProvenanceSourceTrust = "builtin" | "admin_shared" | "project_local" | "user_local" | "explicit_file" | "input";
+export interface DNASourceProvenance {
+    source_id: string;
+    source_ref: string;
+    resolved_path: string;
+    fingerprint: string;
+    type: DNAType;
+    cascade_priority: number;
+    version: string;
+    trust: ProvenanceSourceTrust;
+    inherited_by?: string;
+    genes?: string[];
+}
+export interface CascadeLayerProvenance {
+    layer: ProvenanceCascadeLayerName;
+    source_id: string;
+    source_ref: string;
+    fingerprint: string;
+    status: ProvenanceLayerStatus;
+    sources?: string[];
+}
+export interface ConstraintProvenance {
+    constraint_id: string;
+    source_layer: ProvenanceCascadeLayerName | "unknown" | "unsupported";
+    source_dna_id: string;
+    gene_id: string;
+    codon_type: CodonType | "unknown";
+    action: "allow" | "warn" | "block" | "escalate" | "validate";
+    provenance_reason: string;
+}
+export interface CompiledProvenanceManifest {
+    schema_version: "intentdna.provenance.v1.7.2";
+    policy_bundle_id: string;
+    policy_bundle_version: string;
+    sources: DNASourceProvenance[];
+    cascade_layers: Record<ProvenanceCascadeLayerName, CascadeLayerProvenance>;
+    constraint_winners: ConstraintProvenance[];
+    compiled_ir_hash: string;
+}
 export interface VariableDef {
     description: string;
     default: string;
@@ -295,6 +343,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 +388,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[]>;
@@ -341,6 +420,7 @@ export interface PreExecutionGate {
     action: "block" | "escalate" | "warn";
     message: string;
     source_gene: string;
+    origin?: ConstraintOrigin;
 }
 export interface PostExecutionValidator {
     check: string;
@@ -439,6 +519,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;
@@ -455,6 +537,8 @@ export interface ConstraintIR {
         per_workflow?: Record<string, string[]>;
     };
     verifier_policy?: VerifierCommandPolicy;
+    provenance?: CompiledProvenanceManifest;
+    compiled_ir_hash?: string;
 }
 /** A compiled workflow step with resolved metadata */
 export interface WorkflowStep {