intentdna 1.6.4 → 1.7.0

package/dist/cli/commands/templates.js

@@ -1,9 +1,11 @@
 /**
- * dna templates deploy — copy local src/templates/*.dna.yaml to global intentdna install
+ * dna templates — template catalog and deployment commands.
  */
 import { readdirSync, copyFileSync, existsSync, readFileSync, mkdirSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { execSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { findTemplateCatalogEntry, listTemplateCatalog } from "../../templates/catalog.js";
 /**
  * Resolve the global intentdna templates directory.
  * Strategy: npm root -g + /intentdna/dist/templates
@@ -45,6 +47,53 @@ function verifyProjectRoot(cwd) {
     }
     return cwd;
 }
+export async function runTemplatesList(opts = {}) {
+    const templates = await listTemplateCatalog({ projectDir: opts.projectDir });
+    if (templates.length === 0) {
+        process.stderr.write("No templates found.\n");
+        return 1;
+    }
+    process.stderr.write(`Available templates (${templates.length}):\n`);
+    for (const template of templates) {
+        const ns = template.namespace ? ` ns=${template.namespace}` : "";
+        const version = template.version ? ` v${template.version}` : "";
+        process.stderr.write(`  - ${template.name} [${template.source}]${ns}${version}`);
+        if (template.displayName)
+            process.stderr.write(` — ${template.displayName}`);
+        process.stderr.write("\n");
+    }
+    return 0;
+}
+export async function runTemplatesShow(opts) {
+    if (!opts.name) {
+        process.stderr.write("Usage: dna templates show <name>\n");
+        return 2;
+    }
+    const template = await findTemplateCatalogEntry(opts.name, { projectDir: opts.projectDir });
+    if (!template) {
+        process.stderr.write(`Unknown template: ${opts.name}\n`);
+        return 2;
+    }
+    const content = await readFile(template.path, "utf-8");
+    process.stderr.write(`Template: ${template.name}\n`);
+    process.stderr.write(`Source: ${template.source}\n`);
+    process.stderr.write(`Path: ${template.path}\n`);
+    if (template.displayName)
+        process.stderr.write(`Name: ${template.displayName}\n`);
+    if (template.namespace)
+        process.stderr.write(`Namespace: ${template.namespace}\n`);
+    if (template.version)
+        process.stderr.write(`Version: ${template.version}\n`);
+    process.stderr.write(`Content hash: ${template.contentHash}\n`);
+    if (template.keywords.length > 0) {
+        process.stderr.write(`Match keywords: ${template.keywords.join(", ")}\n`);
+    }
+    process.stderr.write("\n---\n");
+    process.stdout.write(content);
+    if (!content.endsWith("\n"))
+        process.stdout.write("\n");
+    return 0;
+}
 export async function runTemplatesDeploy(opts = {}) {
     try {
         const cwd = process.cwd();

package/dist/cli/commands/validate.js

@@ -3,7 +3,7 @@
  *
  * Validate DNA files for structural correctness.
  */
-import { loadDNA } from "../../compiler/index.js";
+import { formatDiagnostic, loadDNAWithDiagnostics } from "../../compiler/index.js";
 export async function runValidate(opts) {
     if (opts.files.length === 0) {
         process.stderr.write("Error: no files specified\n");
@@ -11,17 +11,23 @@ export async function runValidate(opts) {
     }
     let allValid = true;
     for (const file of opts.files) {
-        try {
-            await loadDNA(file);
+        const result = await loadDNAWithDiagnostics(file);
+        const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+        const warnings = result.diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+        if (errors.length > 0 || !result.dna) {
+            allValid = false;
+            process.stderr.write(`invalid: ${file}\n`);
             if (!opts.quiet) {
-                process.stderr.write(`valid: ${file}\n`);
+                for (const diagnostic of result.diagnostics) {
+                    process.stderr.write(`${formatDiagnostic(diagnostic)}\n`);
+                }
             }
+            continue;
         }
-        catch (err) {
-            allValid = false;
-            process.stderr.write(`invalid: ${file}\n`);
-            if (!opts.quiet && err instanceof Error) {
-                process.stderr.write(`${err.message}\n`);
+        if (!opts.quiet) {
+            process.stderr.write(`valid: ${file}\n`);
+            for (const warning of warnings) {
+                process.stderr.write(`${formatDiagnostic(warning)}\n`);
             }
         }
     }

package/dist/cli/commands/verify.js

@@ -218,6 +218,18 @@ function truncate(s, max) {
         return s;
     return s.slice(0, max - 3) + "...";
 }
+async function checkTemplateVersionsQuiet(configs) {
+    const stderr = process.stderr;
+    const originalWrite = stderr.write;
+    stderr.write = (() => true);
+    try {
+        const { checkTemplateVersions } = await import("./sync.js");
+        return await checkTemplateVersions(configs);
+    }
+    finally {
+        stderr.write = originalWrite;
+    }
+}
 /**
  * U3: Comprehensive health report for DNA installation.
  * Checks IR, configs, templates, hooks, and trace system.
@@ -225,7 +237,7 @@ function truncate(s, max) {
 export async function runHealth() {
     const cwd = process.cwd();
     const checks = [];
-    const { resolve } = await import("node:path");
+    const { resolve, basename } = await import("node:path");
     const { stat, readFile: rf, readdir } = await import("node:fs/promises");
     // 1. Check compiled IR
     const irPath = resolve(cwd, ".dna", "compiled", "ir.json");
@@ -245,15 +257,15 @@ export async function runHealth() {
             checks.push({ name: "Compiled IR", status: "warn", detail: "Legacy format — run `dna sync` to upgrade" });
         }
         else {
-            checks.push({ name: "Compiled IR", status: "fail", detail: "Unrecognized format" });
+            checks.push({ name: "Compiled IR", status: "fail", detail: "Unrecognized format — run `dna sync` to regenerate" });
         }
     }
     catch {
         checks.push({ name: "Compiled IR", status: "fail", detail: "Not found — run `dna sync`" });
     }
     // 2. Check DNA config files
-    const { autoDetectConfigs } = await import("./sync.js");
-    const configs = await autoDetectConfigs();
+    const { detectDNAConfigs } = await import("../../compiler/index.js");
+    const configs = await detectDNAConfigs(cwd);
     if (configs.length > 0) {
         checks.push({ name: "DNA configs", status: "pass", detail: `${configs.length} config(s) found` });
     }
@@ -262,51 +274,72 @@ export async function runHealth() {
     }
     // 3. Check config validity
     if (configs.length > 0) {
-        const { loadDNA } = await import("../../compiler/index.js");
+        const { loadDNAWithDiagnostics, formatDiagnostic } = await import("../../compiler/index.js");
         let valid = 0;
         let invalid = 0;
+        let warningCount = 0;
         const errors = [];
         for (const configPath of configs) {
-            try {
-                await loadDNA(configPath);
+            const result = await loadDNAWithDiagnostics(configPath);
+            const errorDiagnostics = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+            const warningDiagnostics = result.diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+            warningCount += warningDiagnostics.length;
+            if (errorDiagnostics.length === 0 && result.dna) {
                 valid++;
             }
-            catch (err) {
+            else {
                 invalid++;
-                const { basename } = await import("node:path");
-                errors.push(`${basename(configPath)}: ${err instanceof Error ? err.message : String(err)}`);
+                errors.push(`${basename(configPath)}: ${errorDiagnostics.map(formatDiagnostic).join(", ")}`);
             }
         }
         if (invalid === 0) {
-            checks.push({ name: "Config validity", status: "pass", detail: `${valid} config(s) valid` });
+            const detail = warningCount > 0 ? `${valid} config(s) valid, ${warningCount} warning(s)` : `${valid} config(s) valid`;
+            checks.push({ name: "Config validity", status: warningCount > 0 ? "warn" : "pass", detail });
         }
         else {
-            checks.push({ name: "Config validity", status: "fail", detail: errors.join("; ") });
+            checks.push({ name: "Config validity", status: "fail", detail: `${errors.join("; ")} — fix listed config errors, then run \`dna validate\`` });
         }
     }
     // 4. Check template versions
     if (configs.length > 0) {
-        const { checkTemplateVersions: checkVersions } = await import("./sync.js");
-        // Suppress stderr output from checkTemplateVersions — we'll report ourselves
-        const origWrite = process.stderr.write;
-        process.stderr.write = (() => true);
         try {
-            const upgrades = await checkVersions(configs);
+            const upgrades = await checkTemplateVersionsQuiet(configs);
             if (upgrades.length === 0) {
                 checks.push({ name: "Template versions", status: "pass", detail: "All up to date" });
             }
             else {
-                const names = upgrades.map(u => `${u.templateName} (${u.currentVersion} → ${u.availableVersion})`);
-                checks.push({ name: "Template versions", status: "warn", detail: `Upgrade available: ${names.join(", ")}` });
+                const versionUpdates = upgrades.filter(u => u.reason === "version-update");
+                const missingHash = upgrades.filter(u => u.reason === "missing-hash");
+                const contentDrift = upgrades.filter(u => u.reason === "content-drift");
+                const parts = [];
+                if (versionUpdates.length > 0) {
+                    const names = versionUpdates.map(u => `${u.templateName} (${u.currentVersion} → ${u.availableVersion})`);
+                    parts.push(`Upgrade available: ${names.join(", ")}`);
+                }
+                if (missingHash.length > 0) {
+                    const names = missingHash.map(u => `${u.templateName} (${u.currentVersion})`);
+                    parts.push(`Template metadata incomplete: ${names.join(", ")} — run dna init --upgrade <template>`);
+                }
+                if (contentDrift.length > 0) {
+                    const names = contentDrift.map(u => `${u.templateName} (${u.currentVersion})`);
+                    parts.push(`Template content drift: ${names.join(", ")} — run dna init --upgrade <template>`);
+                }
+                checks.push({ name: "Template versions", status: "warn", detail: parts.join("; ") });
             }
         }
         catch {
-            checks.push({ name: "Template versions", status: "warn", detail: "Could not check versions" });
-        }
-        finally {
-            process.stderr.write = origWrite;
+            checks.push({ name: "Template versions", status: "warn", detail: "Could not check versions — run `dna templates list` and retry `dna verify --health`" });
         }
     }
+    // 4.5 Check sync mode detection
+    try {
+        const { detectMode } = await import("./sync.js");
+        const mode = await detectMode();
+        checks.push({ name: "Sync mode", status: "pass", detail: `auto resolves to ${mode}` });
+    }
+    catch {
+        checks.push({ name: "Sync mode", status: "warn", detail: "Could not auto-detect plugin/bin mode — use `dna sync --mode bin` if plugin mode is unavailable" });
+    }
     // 5. Check .claude settings or plugin registration
     const settingsPath = resolve(cwd, ".claude", "settings.json");
     try {
@@ -319,7 +352,7 @@ export async function runHealth() {
             checks.push({ name: "Hook registration", status: "pass", detail: `${eventCount} event(s) in settings.json` });
         }
         else {
-            checks.push({ name: "Hook registration", status: "warn", detail: "No hooks in settings.json — using plugin mode?" });
+            checks.push({ name: "Hook registration", status: "warn", detail: "settings.json has no hooks — run `dna sync --mode bin` or use plugin-managed hooks" });
         }
     }
     catch {
@@ -332,13 +365,52 @@ export async function runHealth() {
                 checks.push({ name: "MCP server", status: "pass", detail: "dna-mcp registered in .mcp.json" });
             }
             else {
-                checks.push({ name: "Hook registration", status: "warn", detail: "No hooks or MCP server found" });
+                checks.push({ name: "Hook registration", status: "warn", detail: "No hooks or MCP server found — run `dna sync`" });
             }
         }
         catch {
             checks.push({ name: "Hook registration", status: "warn", detail: "No settings.json or .mcp.json — run `dna setup` or `dna sync`" });
         }
     }
+    // 5.5 Check generated skill map/body references
+    const skillsDir = resolve(cwd, ".claude", "skills");
+    const skillMapPath = resolve(skillsDir, ".intentdna-skill-map.json");
+    try {
+        const raw = await rf(skillMapPath, "utf-8");
+        const map = JSON.parse(raw);
+        const skills = Array.isArray(map.skills) ? map.skills : [];
+        const missingBodies = [];
+        for (const skill of skills) {
+            if (!skill.bodyPath)
+                continue;
+            try {
+                await stat(resolve(skillsDir, skill.bodyPath));
+            }
+            catch {
+                missingBodies.push(`${skill.name ?? "unknown"}: ${skill.bodyPath}`);
+            }
+        }
+        if (missingBodies.length === 0) {
+            checks.push({ name: "Generated skills", status: "pass", detail: `${skills.length} skill map entr${skills.length === 1 ? "y" : "ies"} with valid bodies` });
+        }
+        else {
+            checks.push({ name: "Generated skills", status: "fail", detail: `Missing body files: ${missingBodies.join(", ")} — run \`dna sync --skills .claude/skills\`` });
+        }
+    }
+    catch {
+        try {
+            const entries = await readdir(skillsDir);
+            const hasSkillDirs = entries.some((entry) => entry.startsWith("dna-"));
+            checks.push({
+                name: "Generated skills",
+                status: hasSkillDirs ? "warn" : "pass",
+                detail: hasSkillDirs ? "Skill dirs exist without .intentdna-skill-map.json — run `dna sync`" : "No generated skill dirs found",
+            });
+        }
+        catch {
+            checks.push({ name: "Generated skills", status: "pass", detail: "No skills directory" });
+        }
+    }
     // 6. Check trace system
     const traceDir = resolve(cwd, ".dna", "state", "trace");
     try {

package/dist/cli/index.js

@@ -12,7 +12,7 @@
  *   help       Show this help message
  */
 import { parseArgs } from "node:util";
-const HELP = `Intent DNA CLI v0.3.0
+const HELP = `Intent DNA CLI v1.7.0
 
 Usage: dna <command> [options]
 
@@ -29,7 +29,8 @@ Commands:
   show          Show gene expression state
   evolve        Preview epigenetic marker changes from persisted outcomes
   epigenetic    Record outcomes, view markers and summaries
-  feedback      Build local kernel report (--days <N>, --json, --evolve preview, --dna-id <id>)
+  feedback      Build local kernel report (--days <N>, --json, --package, --evolve preview, --dna-id <id>)
+  context       Inspect planning-only advisory context sources
   templates     Template management (deploy to global install)
 
 Options:
@@ -68,15 +69,39 @@ Examples:
   dna evolve my_dna_id                  Preview marker changes without persisting
   dna evolve my_dna_id --apply           Unsupported in this kernel; use sync --evolve for explicit mutation
 `;
+const COMMAND_HELP = {
+    sync: `Usage: dna sync [files...] [options]\n\nOptions:\n  --mode auto|plugin|bin   Sync mode (default: auto)\n  --dry-run                Print planned outputs without writing files\n  --post-summary           Print registry-backed output summary\n  --target <target>        Markdown target for injection\n  --inject <path>          File to inject markdown into\n  --agents <dir>           Generate agent files\n  --skills <dir>           Generate skill files\n  --workflow <dir>         Generate workflow shell scripts\n  --settings <path>        Write hook settings in bin mode\n  --lock <path>            Write lock file (default .dna/lock)\n`,
+    verify: `Usage: dna verify [--lock <path>] [--stats] [--health]\n\nOptions:\n  --health                 Comprehensive installation health check\n  --stats                  Show hook call statistics\n  --lock <path>            Lock file path (default .dna/lock)\n`,
+    templates: `Usage: dna templates <list|show|deploy>\n\nSubcommands:\n  list                     List built-in and project templates\n  show <name>              Show template metadata and YAML\n  deploy                   Copy local templates to global install\n`,
+    context: `Usage: dna context <index|search|doc> [query|id] [files...]\n\nSubcommands:\n  index                    List explicitly declared planning-only advisory context sources\n  search <query>           Search source metadata\n  doc <id>                 Read a local file/doc source body\n`,
+    run: `Usage: dna run --dna <file> --workflow <name> --task <id> [options]\n\nOptions:\n  --dry-run                Print execution plan only\n  --permission-mode <mode> Claude permission mode (default: default)\n`,
+    compile: `Usage: dna compile <files...> [--target claude-sdk] [--context <name>] [--output <path>] [--ir]\n`,
+    validate: `Usage: dna validate <files...> [--quiet]\n`,
+    show: `Usage: dna show <files...> [--context <name>] [--json]\n`,
+    init: `Usage: dna init [--template <name>|--template list|--register <path>|--upgrade <name>]\n`,
+};
+function commandHelp(command) {
+    return command ? COMMAND_HELP[command] : undefined;
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
-    if (!command || command === "help" || command === "--help" || command === "-h") {
+    if (!command || command === "--help" || command === "-h") {
         process.stderr.write(HELP);
         process.exit(0);
     }
+    if (command === "help") {
+        const help = commandHelp(args[1]);
+        process.stderr.write(help ?? HELP);
+        process.exit(0);
+    }
     // Parse remaining args (after command)
     const rest = args.slice(1);
+    if (rest.includes("--help") || rest.includes("-h")) {
+        const help = commandHelp(command);
+        process.stderr.write(help ?? HELP);
+        process.exit(help ? 0 : 2);
+    }
     switch (command) {
         case "sync": {
             const { values, positionals } = parseArgs({
@@ -96,11 +121,19 @@ async function main() {
                     settings: { type: "string" },
                     lock: { type: "string", default: ".dna/lock" },
                     remove: { type: "boolean", default: false },
-                    plugin: { type: "boolean", default: false },
+                    mode: { type: "string", default: "auto" },
+                    plugin: { type: "boolean" },
+                    "dry-run": { type: "boolean", default: false },
+                    "post-summary": { type: "boolean", default: false },
                 },
                 allowPositionals: true,
                 strict: false,
             });
+            const mode = values.mode;
+            if (!["auto", "plugin", "bin"].includes(mode)) {
+                process.stderr.write(`Error: --mode must be one of: auto, plugin, bin\n`);
+                process.exit(2);
+            }
             const { runSync } = await import("./commands/sync.js");
             const code = await runSync({
                 files: positionals,
@@ -118,7 +151,10 @@ async function main() {
                 settingsPath: values.settings,
                 lockFile: values.lock,
                 remove: values.remove,
+                mode: mode,
                 plugin: values.plugin,
+                dryRun: values["dry-run"],
+                postSummary: values["post-summary"],
             });
             process.exit(code);
             break;
@@ -413,6 +449,25 @@ async function main() {
             process.exit(code);
             break;
         }
+        case "context": {
+            const subcommand = rest[0] ?? "index";
+            const contextRest = rest.slice(1);
+            const { positionals } = parseArgs({
+                args: contextRest,
+                options: {},
+                allowPositionals: true,
+                strict: false,
+            });
+            const { runContext } = await import("./commands/context.js");
+            const code = await runContext({
+                subcommand,
+                query: subcommand === "search" ? positionals[0] : undefined,
+                id: subcommand === "doc" ? positionals[0] : undefined,
+                files: subcommand === "index" ? positionals : positionals.slice(1),
+            });
+            process.exit(code);
+            break;
+        }
         case "feedback": {
             const { values: fbValues } = parseArgs({
                 args: rest,
@@ -420,6 +475,7 @@ async function main() {
                     days: { type: "string", short: "d", default: "7" },
                     json: { type: "boolean", default: false },
                     evolve: { type: "boolean", default: false },
+                    package: { type: "boolean", default: false },
                     "dna-id": { type: "string" },
                 },
                 strict: false,
@@ -429,20 +485,29 @@ async function main() {
                 days: parseInt(fbValues.days, 10) || 7,
                 json: fbValues.json,
                 evolve: fbValues.evolve,
+                packageReport: fbValues.package,
                 dnaId: fbValues["dna-id"],
             });
             process.exit(code);
             break;
         }
         case "templates": {
-            const subcommand = rest[0] ?? "";
-            if (subcommand !== "deploy") {
-                process.stderr.write(`Usage: dna templates deploy\n\nCopy local src/templates/*.dna.yaml to global intentdna install.\n`);
-                process.exit(subcommand ? 2 : 0);
+            const subcommand = rest[0] ?? "list";
+            const { runTemplatesDeploy, runTemplatesList, runTemplatesShow } = await import("./commands/templates.js");
+            if (subcommand === "list") {
+                const code = await runTemplatesList();
+                process.exit(code);
             }
-            const { runTemplatesDeploy } = await import("./commands/templates.js");
-            const code = await runTemplatesDeploy();
-            process.exit(code);
+            if (subcommand === "show") {
+                const code = await runTemplatesShow({ name: rest[1] ?? "" });
+                process.exit(code);
+            }
+            if (subcommand === "deploy") {
+                const code = await runTemplatesDeploy();
+                process.exit(code);
+            }
+            process.stderr.write(COMMAND_HELP.templates);
+            process.exit(2);
             break;
         }
         default:

package/dist/compiler/cascade.d.ts

@@ -10,7 +10,7 @@
  *   - attract/repel: same target accumulates, different targets independent
  *   - amplify/suppress: factors multiply (1.5x × 2.0x = 3.0x)
  */
-import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef, LegibilityAssetMap, VerifierCommandPolicy, ControllerDef } from "../schema/types.js";
+import type { IntentDNA, Gene, ContextRegion, EpigeneticMarker, RoleDef, WorkflowDef, LegibilityAssetMap, VerifierCommandPolicy, ControllerDef, AdvisoryContextSource, PlanningContext } from "../schema/types.js";
 export interface CascadedDNA {
     genes: Record<string, Gene>;
     contexts: Record<string, ContextRegion>;
@@ -27,6 +27,8 @@ export interface CascadedDNA {
         per_role?: Record<string, string[]>;
         per_workflow?: Record<string, string[]>;
     };
+    context_sources?: AdvisoryContextSource[];
+    planning_context?: PlanningContext;
     verifier_policy?: VerifierCommandPolicy;
 }
 /**

package/dist/compiler/cascade.js

@@ -156,6 +156,47 @@ function mergeContextFiles(base, incoming) {
         per_workflow: mergePrefixedRecords(base.per_workflow, incoming.per_workflow),
     };
 }
+function prefixContextSources(sources, ns) {
+    if (!sources)
+        return undefined;
+    if (!ns)
+        return sources;
+    return sources.map((source) => ({ ...source, id: `${ns}_${source.id}` }));
+}
+function prefixPlanningContext(planning, ns) {
+    if (!planning)
+        return undefined;
+    if (!ns)
+        return planning;
+    return {
+        ...planning,
+        sources: planning.sources.map((sourceId) => `${ns}_${sourceId}`),
+    };
+}
+function mergeContextSources(base, incoming) {
+    if (!base)
+        return incoming;
+    if (!incoming)
+        return base;
+    const merged = new Map();
+    for (const source of base)
+        merged.set(source.id, source);
+    for (const source of incoming)
+        merged.set(source.id, source);
+    return [...merged.values()];
+}
+function mergePlanningContext(base, incoming) {
+    if (!base)
+        return incoming;
+    if (!incoming)
+        return base;
+    return {
+        sources: incoming.sources,
+        instructions: incoming.instructions ?? base.instructions,
+        require_quotes: incoming.require_quotes ?? base.require_quotes,
+        require_attribution: incoming.require_attribution ?? base.require_attribution,
+    };
+}
 function mergeVerifierPolicy(base, incoming) {
     if (!base)
         return incoming;
@@ -257,6 +298,8 @@ export function cascadeDNA(layers) {
     // legibility_assets/context_files: highest-priority DNA wins (last in sorted layers)
     let legibilityAssets;
     let contextFiles;
+    let contextSources;
+    let planningContext;
     let verifierPolicy;
     for (const dna of sorted) {
         if (dna.legibility_assets) {
@@ -265,6 +308,12 @@ export function cascadeDNA(layers) {
         if (dna.context_files) {
             contextFiles = mergeContextFiles(contextFiles, prefixContextFiles(dna.context_files, dna.namespace));
         }
+        if (dna.context_sources) {
+            contextSources = mergeContextSources(contextSources, prefixContextSources(dna.context_sources, dna.namespace));
+        }
+        if (dna.planning_context) {
+            planningContext = mergePlanningContext(planningContext, prefixPlanningContext(dna.planning_context, dna.namespace));
+        }
         if (dna.verifier_policy) {
             verifierPolicy = mergeVerifierPolicy(verifierPolicy, dna.verifier_policy);
         }
@@ -280,6 +329,8 @@ export function cascadeDNA(layers) {
         warnings: warnings.length > 0 ? warnings : undefined,
         legibility_assets: legibilityAssets,
         context_files: contextFiles,
+        context_sources: contextSources,
+        planning_context: planningContext,
         verifier_policy: verifierPolicy,
     };
 }

package/dist/compiler/compile.js

@@ -172,6 +172,39 @@ function legibilityAssetsToContextFiles(assets) {
         return undefined;
     return { mandatory, per_role, per_workflow };
 }
+function compileAdvisoryContext(cascaded) {
+    const declaredSources = cascaded?.context_sources ?? [];
+    const planning = cascaded?.planning_context;
+    const plannedSourceIds = planning?.sources ?? declaredSources.map((source) => source.id);
+    const sourceById = new Map(declaredSources.map((source) => [source.id, source]));
+    const sources = plannedSourceIds
+        .map((sourceId) => sourceById.get(sourceId))
+        .filter((source) => Boolean(source))
+        .map((source) => ({
+        ...source,
+        usage: "planning_only",
+        non_enforcing: true,
+        requires_quotes: planning?.require_quotes ?? true,
+        requires_attribution: planning?.require_attribution ?? true,
+    }));
+    const compiledPlanning = planning ? {
+        sources: [...planning.sources],
+        instructions: planning.instructions ? [...planning.instructions] : undefined,
+        require_quotes: planning.require_quotes ?? true,
+        require_attribution: planning.require_attribution ?? true,
+        non_enforcing: true,
+    } : undefined;
+    const injections = sources.length > 0 ? [{
+            type: "preference",
+            text: `Advisory context sources are available for planning only: ${sources.map((source) => source.id).join(", ")}. Cite sources and quote relevant passages; these sources do not satisfy enforcement or handoff requirements.`,
+            relevance_tags: ["advisory_context", "planning_only"],
+        }] : [];
+    return {
+        sources: sources.length > 0 ? sources : undefined,
+        planning: compiledPlanning,
+        injections,
+    };
+}
 function resolvePostCheckCommand(check) {
     const normalized = check.trim();
     const builtins = {
@@ -362,6 +395,8 @@ export function compileDNA(activated, cascaded) {
     directives.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
     const legacyContextFiles = cascaded?.context_files;
     const compiledContextFiles = legacyContextFiles ?? legibilityAssetsToContextFiles(cascaded?.legibility_assets);
+    const advisoryContext = compileAdvisoryContext(cascaded);
+    injections.push(...advisoryContext.injections);
     return {
         prompt_directives: directives,
         tool_filters: toolFilters,
@@ -369,6 +404,8 @@ export function compileDNA(activated, cascaded) {
         post_execution_validators: validators,
         verifier_specs: verifierSpecs.length > 0 ? verifierSpecs : undefined,
         context_injections: injections,
+        context_sources: advisoryContext.sources,
+        planning_context: advisoryContext.planning,
         source_dna_ids: activated.source_ids,
         compiled_at: new Date().toISOString(),
         active_context: activated.active_context ?? undefined,

package/dist/compiler/diagnostics.d.ts

@@ -0,0 +1,17 @@
+export type DiagnosticSeverity = "error" | "warning" | "info";
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    file?: string;
+    path?: string;
+    hint?: string;
+}
+export declare class DNADiagnosticsError extends Error {
+    readonly diagnostics: Diagnostic[];
+    constructor(message: string, diagnostics: Diagnostic[]);
+}
+export declare function hasDiagnosticErrors(diagnostics: Diagnostic[]): boolean;
+export declare function formatDiagnostic(diagnostic: Diagnostic): string;
+export declare function formatDiagnostics(diagnostics: Diagnostic[]): string;
+export declare function diagnosticsFromError(error: unknown, file?: string): Diagnostic[];