intentdna 1.6.4 → 1.7.0

package/dist/hooks/state.js

@@ -330,13 +330,34 @@ export async function appendSessionRead(projectDir, filePath, sessionId) {
     }
 }
 const VERIFIER_RESULTS_FILE = "workflow/verifier-results.json";
+export function verifierResultId(result) {
+    return "vr_" + createHash("sha256")
+        .update(JSON.stringify({
+        verifier_id: result.verifier_id,
+        when: result.when,
+        severity: result.severity,
+        kind: result.kind,
+        workflow: result.workflow ?? "",
+        step_id: result.step_id ?? "",
+        status: result.status,
+        target: result.target ?? "",
+        evidence: result.evidence ?? "",
+        artifact: result.artifact ?? "",
+        timestamp: result.timestamp,
+    }))
+        .digest("hex")
+        .slice(0, 16);
+}
+function normalizeVerifierResult(result) {
+    return result.result_id ? result : { ...result, result_id: verifierResultId(result) };
+}
 async function readVerifierResultsFile(projectDir, sessionId) {
     const stateDir = resolveStateDir(projectDir, sessionId);
     const filePath = join(stateDir, VERIFIER_RESULTS_FILE);
     try {
         const raw = await readFile(filePath, "utf-8");
         const parsed = JSON.parse(raw);
-        return Array.isArray(parsed) ? parsed : [];
+        return Array.isArray(parsed) ? parsed.map(normalizeVerifierResult) : [];
     }
     catch {
         return [];
@@ -381,7 +402,7 @@ export async function writeVerifierResults(projectDir, results, sessionId) {
 }
 export async function appendVerifierResult(projectDir, result, sessionId) {
     const results = await readVerifierResultsFile(projectDir, sessionId);
-    results.push(result);
+    results.push(normalizeVerifierResult(result));
     await writeVerifierResults(projectDir, results, sessionId);
 }
 const TRACE_DIR = "trace";

package/dist/mcp/index.js

@@ -15,6 +15,7 @@ import { createStateTools } from "./tools-state.js";
 import { createCompileTools } from "./tools-compile.js";
 import { createEnforceTools } from "./tools-enforce.js";
 import { createObservabilityTools } from "./tools-observability.js";
+import { createContextTools } from "./tools-context.js";
 // Parse args
 const args = process.argv.slice(2);
 let projectDir = process.cwd();
@@ -36,6 +37,7 @@ catch { /* use default */ }
 const tools = [
     ...createStateTools(projectDir),
     ...createCompileTools(projectDir),
+    ...createContextTools(projectDir),
     ...createEnforceTools(projectDir),
     ...createObservabilityTools(projectDir),
 ];

package/dist/mcp/tools-compile.js

@@ -7,45 +7,8 @@
  *   - dna_sync: Run full sync pipeline (compile + inject + hooks)
  */
 import { resolve } from "node:path";
-import { stat } from "node:fs/promises";
-import { loadDNA, compileFromFiles } from "../compiler/index.js";
+import { compileFromFiles, detectDNAConfigs, expandDNAInputFiles, formatDiagnostic, loadDNAWithDiagnostics } from "../compiler/index.js";
 import { textResult, errorResult } from "./server.js";
-async function fileExists(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** Auto-detect DNA config files in the project directory. */
-async function detectConfigs(projectDir) {
-    const { readdir } = await import("node:fs/promises");
-    // Multi-config: .dna/configs/*.yaml
-    const configsDir = resolve(projectDir, ".dna", "configs");
-    try {
-        const files = await readdir(configsDir);
-        const yamls = files
-            .filter(f => f.endsWith(".yaml") || f.endsWith(".yml"))
-            .sort()
-            .map(f => resolve(configsDir, f));
-        if (yamls.length > 0)
-            return yamls;
-    }
-    catch { /* dir doesn't exist */ }
-    // Legacy single-config
-    const candidates = [
-        ".dna/config.yaml", ".dna/config.yml", ".dna/config.json",
-        ".dna.yaml", ".dna.yml", ".dna.json",
-    ];
-    for (const name of candidates) {
-        const path = resolve(projectDir, name);
-        if (await fileExists(path))
-            return [path];
-    }
-    return [];
-}
 export function createCompileTools(projectDir) {
     return [
         // ── dna_validate ─────────────────────────────────────
@@ -62,20 +25,23 @@ export function createCompileTools(projectDir) {
                 const configPath = typeof args.config_path === "string"
                     ? resolve(projectDir, args.config_path)
                     : undefined;
-                const files = configPath ? [configPath] : await detectConfigs(projectDir);
+                const files = configPath ? [configPath] : await detectDNAConfigs(projectDir);
                 if (files.length === 0)
                     return errorResult("No DNA config files found.");
                 const results = [];
                 let allValid = true;
                 for (const file of files) {
-                    try {
-                        // loadDNA calls validateDNA internally — throws on invalid
-                        await loadDNA(file);
+                    const result = await loadDNAWithDiagnostics(file);
+                    const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+                    if (errors.length > 0 || !result.dna) {
+                        allValid = false;
+                        results.push(`${file}: INVALID`);
+                    }
+                    else {
                         results.push(`${file}: valid`);
                     }
-                    catch (err) {
-                        allValid = false;
-                        results.push(`${file}: INVALID — ${err instanceof Error ? err.message : String(err)}`);
+                    for (const diagnostic of result.diagnostics) {
+                        results.push(`  ${formatDiagnostic(diagnostic)}`);
                     }
                 }
                 results.unshift(allValid ? "All configs valid." : "Validation errors found.");
@@ -98,11 +64,12 @@ export function createCompileTools(projectDir) {
                 const configPath = typeof args.config_path === "string"
                     ? resolve(projectDir, args.config_path)
                     : undefined;
-                const files = configPath ? [configPath] : await detectConfigs(projectDir);
+                const files = configPath ? [configPath] : await detectDNAConfigs(projectDir);
                 if (files.length === 0)
                     return errorResult("No DNA config files found.");
                 try {
-                    const ir = await compileFromFiles(files, {
+                    const expandedFiles = await expandDNAInputFiles(files);
+                    const ir = await compileFromFiles(expandedFiles, {
                         context: typeof args.context === "string" ? args.context : undefined,
                         role: typeof args.role === "string" ? args.role : undefined,
                     });
@@ -142,12 +109,13 @@ export function createCompileTools(projectDir) {
                     evolve: { type: "boolean", description: "Run evolution engine before compiling (default false)" },
                     context: { type: "string", description: "Active context name" },
                     role: { type: "string", description: "Active role name" },
+                    mode: { type: "string", enum: ["auto", "plugin", "bin"], description: "Sync mode (default auto)" },
                 },
             },
             handler: async (args) => {
                 // Import sync command dynamically to avoid circular deps
-                const { runSync, autoDetectConfigs: detectAll } = await import("../cli/commands/sync.js");
-                const files = await detectAll();
+                const { runSync } = await import("../cli/commands/sync.js");
+                const files = await detectDNAConfigs(projectDir);
                 if (files.length === 0)
                     return errorResult("No DNA config files found.");
                 const exitCode = await runSync({
@@ -160,6 +128,7 @@ export function createCompileTools(projectDir) {
                     skillsDir: resolve(projectDir, ".claude", "skills"),
                     settingsPath: resolve(projectDir, ".claude", "settings.json"),
                     remove: false,
+                    mode: typeof args.mode === "string" && ["auto", "plugin", "bin"].includes(args.mode) ? args.mode : "auto",
                 });
                 if (exitCode === 0) {
                     return textResult("Sync completed successfully.");

package/dist/mcp/tools-context.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from "./server.js";
+export declare function createContextTools(projectDir: string): ToolDef[];

package/dist/mcp/tools-context.js

@@ -0,0 +1,85 @@
+import { resolve } from "node:path";
+import { findContextSource, formatContextSource, loadContextSourceIndex, readContextSourceDocument, searchContextSources, } from "../runtime/context-sources.js";
+import { errorResult, textResult } from "./server.js";
+function filesArg(args, projectDir) {
+    if (typeof args.config_path === "string")
+        return [resolve(projectDir, args.config_path)];
+    return undefined;
+}
+export function createContextTools(projectDir) {
+    return [
+        {
+            name: "dna_context_sources",
+            description: "List explicitly declared planning-only advisory context sources",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    config_path: { type: "string", description: "Path to DNA config (auto-detected if omitted)" },
+                },
+            },
+            handler: async (args) => {
+                const index = await loadContextSourceIndex(projectDir, filesArg(args, projectDir));
+                if (index.sources.length === 0)
+                    return textResult("No advisory context sources declared.");
+                const lines = index.sources.map(formatContextSource);
+                if (index.planning_instructions.length > 0) {
+                    lines.push("", "Planning instructions:");
+                    for (const instruction of index.planning_instructions)
+                        lines.push(`- ${instruction}`);
+                }
+                return textResult(lines.join("\n"));
+            },
+        },
+        {
+            name: "dna_context_search",
+            description: "Search advisory context source metadata. This does not search repository files.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Metadata query" },
+                    config_path: { type: "string", description: "Path to DNA config (auto-detected if omitted)" },
+                },
+                required: ["query"],
+            },
+            handler: async (args) => {
+                const query = typeof args.query === "string" ? args.query : "";
+                const index = await loadContextSourceIndex(projectDir, filesArg(args, projectDir));
+                const matches = searchContextSources(index, query);
+                if (matches.length === 0)
+                    return errorResult(`No advisory context sources matched '${query}'.`);
+                return textResult(matches.map(formatContextSource).join("\n"));
+            },
+        },
+        {
+            name: "dna_get_context",
+            description: "Read a declared local advisory context document by source id",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "Context source id" },
+                    config_path: { type: "string", description: "Path to DNA config (auto-detected if omitted)" },
+                },
+                required: ["id"],
+            },
+            handler: async (args) => {
+                const id = typeof args.id === "string" ? args.id : "";
+                const index = await loadContextSourceIndex(projectDir, filesArg(args, projectDir));
+                const source = findContextSource(index, id);
+                if (!source)
+                    return errorResult(`Unknown advisory context source '${id}'.`);
+                const doc = await readContextSourceDocument(projectDir, source);
+                const lines = [
+                    formatContextSource(source),
+                    "Planning-only advisory context; does not satisfy enforcement, handoff, or ArtifactManifest requirements.",
+                ];
+                if (doc.content !== undefined) {
+                    lines.push("", "---", doc.content);
+                }
+                else {
+                    lines.push("No local document body is available for this source type.");
+                }
+                return textResult(lines.join("\n"));
+            },
+        },
+    ];
+}

package/dist/mcp/tools-enforce.d.ts

@@ -1,8 +1,8 @@
 /**
  * Intent DNA — MCP Enforce Tools (U2)
  *
- * Provides enforcement via MCP server with in-memory IR cache.
- * Zero cold-start: IR is loaded once and cached with mtime-based invalidation.
+ * Provides enforcement via a persistent MCP server with in-memory IR cache.
+ * MCP calls reuse the full hook runtime without reloading IR on every request.
  *
  * Tools:
  *   - dna_enforce: Run enforcement for a hook event (PreToolUse, PostToolUse, etc.)

package/dist/mcp/tools-enforce.js

@@ -1,15 +1,18 @@
 /**
  * Intent DNA — MCP Enforce Tools (U2)
  *
- * Provides enforcement via MCP server with in-memory IR cache.
- * Zero cold-start: IR is loaded once and cached with mtime-based invalidation.
+ * Provides enforcement via a persistent MCP server with in-memory IR cache.
+ * MCP calls reuse the full hook runtime without reloading IR on every request.
  *
  * Tools:
  *   - dna_enforce: Run enforcement for a hook event (PreToolUse, PostToolUse, etc.)
  */
 import { resolve } from "node:path";
 import { stat, readFile } from "node:fs/promises";
-import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, } from "../hooks/enforce.js";
+import { silentOutput } from "../hooks/protocol.js";
+import { hookEventsForSurface } from "../hooks/event-registry.js";
+import { validateHookInput } from "../hooks/schema.js";
+import { runHookEvent } from "../hooks/cli.js";
 import { textResult, errorResult } from "./server.js";
 // ── IR Cache ────────────────────────────────────────────────
 /** In-memory IR cache with mtime-based invalidation. */
@@ -61,53 +64,18 @@ export class IRCache {
         this.lastMtime = 0;
     }
 }
-const VALID_EVENTS = new Set([
-    "PreToolUse", "PostToolUse", "UserPromptSubmit",
-    "SubagentStop", "PreCompact", "Notification", "SessionStart",
-]);
-function dispatchEnforce(event, ir, input, roles) {
-    const result = dispatchEnforceInner(event, ir, input, roles);
-    return result?.output ?? { continue: true, suppressOutput: true };
-}
-function dispatchEnforceInner(event, ir, input, roles) {
-    switch (event) {
-        case "PreToolUse":
-            return enforcePreToolUse(ir, {
-                tool_name: String(input.tool_name ?? ""),
-                tool_input: (input.tool_input ?? {}),
-                agent_type: typeof input.agent_type === "string" ? input.agent_type : undefined,
-                cwd: typeof input.cwd === "string" ? input.cwd : undefined,
-            }, undefined, roles);
-        case "PostToolUse":
-            return enforcePostToolUse(ir, {
-                tool_name: String(input.tool_name ?? ""),
-                tool_input: (input.tool_input ?? {}),
-                tool_output: typeof input.tool_output === "string" ? input.tool_output : undefined,
-                agent_type: typeof input.agent_type === "string" ? input.agent_type : undefined,
-            });
-        case "UserPromptSubmit":
-            return enforceUserPromptSubmit(ir, {
-                prompt: typeof input.prompt === "string" ? input.prompt : undefined,
-            });
-        case "SubagentStop":
-            return enforceSubagentStop(ir, {
-                agent_name: typeof input.agent_name === "string" ? input.agent_name : undefined,
-                agent_type: typeof input.agent_type === "string" ? input.agent_type : undefined,
-            });
-        case "PreCompact":
-            return enforcePreCompact(ir);
-        case "Notification":
-            return enforceNotification(ir, {
-                title: typeof input.title === "string" ? input.title : undefined,
-                message: typeof input.message === "string" ? input.message : undefined,
-            });
-        case "SessionStart":
-            return enforceSessionStart(ir, {
-                cwd: typeof input.cwd === "string" ? input.cwd : undefined,
-                sessionId: typeof input.session_id === "string" ? input.session_id : undefined,
-            });
-        default:
-            return null;
+const VALID_EVENTS = new Set(hookEventsForSurface("mcp"));
+async function dispatchEnforce(event, ir, input, projectDir, roles) {
+    try {
+        const validation = validateHookInput(event, input);
+        if (!validation.valid)
+            return silentOutput();
+        const rawInput = validation.normalized;
+        const sessionId = typeof rawInput.sessionId === "string" ? rawInput.sessionId : undefined;
+        return await runHookEvent({ event, ir, rawInput, projectDir, sessionId, roles });
+    }
+    catch {
+        return silentOutput();
     }
 }
 // ── Tool Registration ───────────────────────────────────────
@@ -116,8 +84,8 @@ export function createEnforceTools(projectDir) {
     return [
         {
             name: "dna_enforce",
-            description: "Run DNA enforcement for a hook event. Uses in-memory cached IR for zero cold-start. " +
-                "Returns the same result as the dna-hook binary but without spawning a new process.",
+            description: "Run DNA enforcement for a hook event inside the persistent MCP server. " +
+                "Uses cached IR and the same runtime path as the dna-hook binary.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -143,7 +111,7 @@ export function createEnforceTools(projectDir) {
                     return errorResult("No compiled IR found. Run `dna sync` to compile your DNA config.");
                 }
                 const input = (args.input ?? {});
-                const result = dispatchEnforce(event, cached.ir, input, cached.roles);
+                const result = await dispatchEnforce(event, cached.ir, input, projectDir, cached.roles);
                 // Format as human-readable text
                 const lines = [];
                 lines.push(`Decision: ${result.continue ? "allow" : "BLOCK"}`);

package/dist/mcp/tools-observability.js

@@ -1,5 +1,6 @@
 import { textResult } from "./server.js";
 import { buildKernelReport, formatKernelReport } from "../report/kernel-report.js";
+import { buildReportPackage } from "../report/report-package.js";
 export function createObservabilityTools(projectDir) {
     return [
         {
@@ -30,5 +31,28 @@ export function createObservabilityTools(projectDir) {
                     "\nMCP observability only: this tool does not execute verifiers, does not enforce hook parity, and does not mutate state or markers.\n");
             },
         },
+        {
+            name: "dna_report_package",
+            description: "Read-only local evidence package with traces, verifier results, handoffs, diagnostics, deferrals, and fact-backed critical decisions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    days: { type: "number", description: "Days to look back (default 7)" },
+                    session_id: { type: "string", description: "Session ID filter" },
+                    dna_id: { type: "string", description: "DNA ID for marker preview; derived from compiled IR if omitted and unambiguous" },
+                    include_marker_preview: { type: "boolean", description: "Include preview-only marker changes (default false)" },
+                },
+            },
+            handler: async (args) => {
+                const reportPackage = await buildReportPackage({
+                    projectDir,
+                    days: typeof args.days === "number" ? args.days : 7,
+                    sessionId: typeof args.session_id === "string" ? args.session_id : undefined,
+                    dnaId: typeof args.dna_id === "string" ? args.dna_id : undefined,
+                    includeMarkerPreview: typeof args.include_marker_preview === "boolean" ? args.include_marker_preview : false,
+                });
+                return textResult(JSON.stringify(reportPackage, null, 2));
+            },
+        },
     ];
 }

package/dist/report/kernel-signals.js

@@ -11,6 +11,8 @@ function extractGeneFromReason(reason) {
     return sourceMatch?.[1];
 }
 function verifierSourceRef(result) {
+    if (result.result_id)
+        return `verifier:${result.result_id}`;
     return [
         "verifier",
         result.workflow ?? "unknown-workflow",
@@ -21,6 +23,7 @@ function verifierSourceRef(result) {
 }
 function verifierEvidencePayload(result) {
     const payload = {
+        result_id: result.result_id,
         verifier_id: result.verifier_id,
         when: result.when,
         severity: result.severity,

package/dist/report/report-package.d.ts

@@ -0,0 +1,56 @@
+import type { DNAWorkflowState, TraceEntry, VerifierResultEntry } from "../hooks/state.js";
+import type { CompletedArtifactEntry } from "../schema/types.js";
+import { type KernelReport, type KernelReportOptions } from "./kernel-report.js";
+export type EvidenceRef = {
+    type: "trace";
+    trace_id: string;
+} | {
+    type: "verifier_result";
+    result_id: string;
+} | {
+    type: "artifact";
+    artifact_id: string;
+    path?: string;
+};
+export interface CriticalDecision {
+    decision_id: string;
+    kind: "block" | "warn" | "verifier_failure" | "handoff_gate";
+    summary: string;
+    refs: EvidenceRef[];
+}
+export interface ReportPackage {
+    schema_version: "intentdna.report_package.v1";
+    generated_at: string;
+    source: KernelReport["source"];
+    kernel_report: KernelReport;
+    traces: TraceEntry[];
+    verifier_results: VerifierResultEntry[];
+    handoffs: {
+        workflow_state?: DNAWorkflowState;
+        completed_artifacts: CompletedArtifactEntry[];
+        artifact_refs: Array<{
+            artifact_id: string;
+            path: string;
+            metadata?: Record<string, unknown>;
+        }>;
+    };
+    diagnostics: Array<{
+        severity: "error" | "warning" | "info";
+        message: string;
+        code?: string;
+    }>;
+    deferrals: Array<{
+        id: string;
+        reason: string;
+        refs: EvidenceRef[];
+    }>;
+    critical_decisions: CriticalDecision[];
+    mutation: {
+        command_class: "read-only" | "preview-only";
+        wrote_state: false;
+        wrote_evolution: false;
+        persisted_outcomes: false;
+        mutated_markers: false;
+    };
+}
+export declare function buildReportPackage(options: KernelReportOptions): Promise<ReportPackage>;

package/dist/report/report-package.js

@@ -0,0 +1,85 @@
+import { readTraces, readVerifierResults, readWorkflowState } from "../hooks/state.js";
+import { buildKernelReport } from "./kernel-report.js";
+function withinDays(timestamp, days) {
+    const parsed = Date.parse(timestamp);
+    if (Number.isNaN(parsed))
+        return true;
+    return parsed >= Date.now() - days * 24 * 60 * 60 * 1000;
+}
+function artifactRefs(completed) {
+    const refs = [];
+    for (const entry of completed) {
+        for (const artifact of entry.artifacts) {
+            refs.push({
+                artifact_id: artifact.artifact_id ?? `${entry.step_id}:${artifact.type}:${artifact.path}`,
+                path: artifact.path,
+                metadata: artifact.metadata,
+            });
+        }
+    }
+    return refs;
+}
+function buildCriticalDecisions(traces, verifierResults, completed) {
+    const decisions = [];
+    for (const trace of traces) {
+        if (trace.decision !== "block" && trace.decision !== "warn")
+            continue;
+        decisions.push({
+            decision_id: `${trace.decision}:${trace.trace_id}`,
+            kind: trace.decision,
+            summary: trace.reason?.split("\n")[0] ?? `${trace.decision} decision`,
+            refs: [{ type: "trace", trace_id: trace.trace_id }],
+        });
+    }
+    for (const result of verifierResults) {
+        if (result.status !== "fail")
+            continue;
+        decisions.push({
+            decision_id: `verifier_failure:${result.result_id ?? result.verifier_id}`,
+            kind: "verifier_failure",
+            summary: result.message ?? `Verifier failed: ${result.verifier_id}`,
+            refs: [{ type: "verifier_result", result_id: result.result_id ?? result.verifier_id }],
+        });
+    }
+    for (const ref of artifactRefs(completed)) {
+        decisions.push({
+            decision_id: `handoff_gate:${ref.artifact_id}`,
+            kind: "handoff_gate",
+            summary: `Completed handoff artifact ${ref.artifact_id}`,
+            refs: [{ type: "artifact", artifact_id: ref.artifact_id, path: ref.path }],
+        });
+    }
+    return decisions;
+}
+export async function buildReportPackage(options) {
+    const days = options.days ?? 7;
+    const kernelReport = await buildKernelReport(options);
+    const traces = await readTraces(options.projectDir, days, options.sessionId);
+    const verifierResults = (await readVerifierResults(options.projectDir, options.sessionId))
+        .filter((result) => withinDays(result.timestamp, days));
+    const workflowState = await readWorkflowState(options.projectDir, options.sessionId, 0) ?? undefined;
+    const completedArtifacts = workflowState?.completed_artifacts ?? [];
+    return {
+        schema_version: "intentdna.report_package.v1",
+        generated_at: new Date().toISOString(),
+        source: kernelReport.source,
+        kernel_report: kernelReport,
+        traces,
+        verifier_results: verifierResults,
+        handoffs: {
+            workflow_state: workflowState,
+            completed_artifacts: completedArtifacts,
+            artifact_refs: artifactRefs(completedArtifacts),
+        },
+        diagnostics: [],
+        deferrals: [],
+        critical_decisions: buildCriticalDecisions(traces, verifierResults, completedArtifacts),
+        mutation: {
+            command_class: options.includeMarkerPreview ? "preview-only" : "read-only",
+            wrote_state: false,
+            wrote_evolution: false,
+            persisted_outcomes: false,
+            mutated_markers: false,
+        },
+    };
+}

package/dist/runtime/agent-md.d.ts

@@ -31,6 +31,7 @@ export interface AgentMDResult {
  * Convert camelCase or snake_case to kebab-case.
  */
 export declare function toKebabCase(name: string): string;
+export declare function assertSafeGeneratedName(name: string, label?: string): void;
 /**
  * Compile a single RoleDef into an agent MD file.
  * Pure function, no side effects.

package/dist/runtime/agent-md.js

@@ -9,8 +9,9 @@
  * Output directory: .claude/agents/<name>.md
  */
 import { mkdir, writeFile, readFile, readdir, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve, sep } from "node:path";
 const SENTINEL_COMMENT = "<!-- intentdna:managed — do not edit manually -->";
+const SAFE_GENERATED_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 // ── Helpers ────────────────────────────────────────────────
 /**
  * Convert camelCase or snake_case to kebab-case.
@@ -23,12 +24,26 @@ export function toKebabCase(name) {
         .replace(/[_\s]+/g, "-")
         .toLowerCase();
 }
+export function assertSafeGeneratedName(name, label = "generated name") {
+    if (!SAFE_GENERATED_NAME.test(name)) {
+        throw new Error(`${label} '${name}' must contain only lowercase letters, digits, and single hyphens`);
+    }
+}
+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;
+}
 /**
  * Render YAML frontmatter string (without --- delimiters).
  */
 function renderFrontmatter(name, role, options) {
     const prefix = options?.namePrefix ?? "dna-";
     const fullName = `${prefix}${toKebabCase(name)}`;
+    assertSafeGeneratedName(fullName, "agent name");
     const lines = [];
     lines.push(`name: ${fullName}`);
     lines.push(`description: "${escapeYamlString(role.description)}"`);
@@ -65,6 +80,7 @@ function renderConstraints(ir) {
 function renderBody(name, role, ir, options) {
     const prefix = options?.namePrefix ?? "dna-";
     const fullName = `${prefix}${toKebabCase(name)}`;
+    assertSafeGeneratedName(fullName, "agent name");
     const compiledAt = new Date().toISOString();
     const includeDNA = options?.includeDNAGuidelines ?? true;
     const sections = [];
@@ -184,7 +200,9 @@ function renderBody(name, role, ir, options) {
 export function compileRoleToAgentMD(roleName, role, ir, options) {
     const prefix = options?.namePrefix ?? "dna-";
     const kebabName = toKebabCase(roleName);
-    const fileName = `${prefix}${kebabName}.md`;
+    const fullName = `${prefix}${kebabName}`;
+    assertSafeGeneratedName(fullName, "agent name");
+    const fileName = `${fullName}.md`;
     const frontmatter = renderFrontmatter(roleName, role, options);
     const body = renderBody(roleName, role, ir, options);
     const content = `---\n${frontmatter}\n---\n\n${body}`;
@@ -207,7 +225,7 @@ export async function writeAgentMDFiles(results, outputDir) {
     await mkdir(outputDir, { recursive: true });
     const written = [];
     for (const result of results) {
-        const path = join(outputDir, result.fileName);
+        const path = resolveContainedPath(outputDir, result.fileName);
         await writeFile(path, result.content, "utf-8");
         written.push(path);
     }