intentdna 1.8.7 → 1.9.0-rc.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "Declarative policy layer for AI agent behavior with plugin-managed hook runtime for Claude Code.",
-      "version": "1.8.7",
+      "version": "1.9.0-rc.1",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.8.7"
+  "version": "1.9.0-rc.1"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.8.7",
+  "version": "1.9.0-rc.1",
   "description": "Declarative policy layer for AI agent behavior",
   "author": {
     "name": "Samuel"

package/dist/cli/commands/candidate-promotion.d.ts

@@ -0,0 +1,15 @@
+export interface PromoteCandidateOptions {
+    projectDir: string;
+    candidatePath: string;
+    templateName: string;
+}
+export interface CandidatePromotionResult {
+    schema_version: "intentdna.candidate_promotion_result.v1";
+    candidate_path: string;
+    template_path: string;
+    receipt_path: string;
+    candidate_sha256: string;
+    template_sha256: string;
+    exact_bytes_preserved: true;
+}
+export declare function promoteCandidate(options: PromoteCandidateOptions): Promise<CandidatePromotionResult>;

package/dist/cli/commands/candidate-promotion.js

@@ -0,0 +1,197 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rm, stat, } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { formatDiagnostics, hasDiagnosticErrors } from "../../compiler/diagnostics.js";
+import { loadDNAWithDiagnostics } from "../../compiler/input-resolver.js";
+const CANDIDATE_SUFFIX = ".candidate.dna.yaml";
+const SAFE_TEMPLATE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isErrnoException(error) {
+    return error instanceof Error && "code" in error;
+}
+function isStrictlyWithin(parent, child) {
+    const pathFromParent = relative(parent, child);
+    return pathFromParent !== ""
+        && pathFromParent !== ".."
+        && !pathFromParent.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)
+        && !isAbsolute(pathFromParent);
+}
+function validateTemplateName(templateName) {
+    if (!SAFE_TEMPLATE_NAME.test(templateName)) {
+        throw new Error("Invalid template name: use one safe path component containing only letters, numbers, hyphens, or underscores");
+    }
+}
+async function assertPathMissing(path, label) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    throw new Error(`${label} already exists; overwrite is not allowed`);
+}
+async function ensureSafeTemplatesDirectory(templatesDir, dnaRealPath) {
+    try {
+        const entry = await lstat(templatesDir);
+        if (entry.isSymbolicLink()) {
+            throw new Error("Templates directory must not be a symlink");
+        }
+        if (!entry.isDirectory()) {
+            throw new Error("Templates path is not a directory");
+        }
+    }
+    catch (error) {
+        if (!isErrnoException(error) || error.code !== "ENOENT")
+            throw error;
+        await mkdir(templatesDir);
+    }
+    const entry = await lstat(templatesDir);
+    if (entry.isSymbolicLink()) {
+        throw new Error("Templates directory must not be a symlink");
+    }
+    if (!entry.isDirectory()) {
+        throw new Error("Templates path is not a directory");
+    }
+    const templatesRealPath = await realpath(templatesDir);
+    if (!isStrictlyWithin(dnaRealPath, templatesRealPath)) {
+        throw new Error("Templates directory escapes the project .dna directory");
+    }
+    return templatesRealPath;
+}
+async function removeCreatedPath(path) {
+    try {
+        await rm(path, { force: true });
+        return undefined;
+    }
+    catch (error) {
+        return error;
+    }
+}
+export async function promoteCandidate(options) {
+    validateTemplateName(options.templateName);
+    const projectPath = resolve(options.projectDir);
+    const projectRealPath = await realpath(projectPath);
+    const dnaPath = join(projectPath, ".dna");
+    const authoringPath = join(dnaPath, "authoring");
+    const candidatePath = resolve(projectPath, options.candidatePath);
+    if (!isStrictlyWithin(authoringPath, candidatePath)) {
+        throw new Error("Candidate must be located within the project .dna/authoring directory");
+    }
+    const candidateFilename = basename(candidatePath);
+    if (!candidateFilename.endsWith(CANDIDATE_SUFFIX)
+        || candidateFilename.length === CANDIDATE_SUFFIX.length) {
+        throw new Error(`Candidate filename must end with ${CANDIDATE_SUFFIX}`);
+    }
+    const dnaRealPath = await realpath(dnaPath);
+    if (!isStrictlyWithin(projectRealPath, dnaRealPath)) {
+        throw new Error("Project .dna directory escapes the project root");
+    }
+    const authoringRealPath = await realpath(authoringPath);
+    if (!isStrictlyWithin(dnaRealPath, authoringRealPath)) {
+        throw new Error("Authoring directory escapes the project .dna directory");
+    }
+    const candidateRealPath = await realpath(candidatePath);
+    if (!isStrictlyWithin(authoringRealPath, candidateRealPath)) {
+        throw new Error("Candidate symlink or path escapes the project authoring directory");
+    }
+    const candidateEntry = await stat(candidateRealPath);
+    if (!candidateEntry.isFile()) {
+        throw new Error("Candidate must be a regular file in the project authoring directory");
+    }
+    const candidateBytesBeforeValidation = await readFile(candidateRealPath);
+    const validation = await loadDNAWithDiagnostics(candidateRealPath);
+    if (!validation.dna || hasDiagnosticErrors(validation.diagnostics)) {
+        const details = formatDiagnostics(validation.diagnostics);
+        throw new Error(`Candidate validation failed${details ? `:\n${details}` : ""}`);
+    }
+    const candidateRealPathAfterValidation = await realpath(candidatePath);
+    if (candidateRealPathAfterValidation !== candidateRealPath) {
+        throw new Error("Candidate path changed during validation; promotion refused");
+    }
+    const candidateBytes = await readFile(candidateRealPathAfterValidation);
+    if (!candidateBytes.equals(candidateBytesBeforeValidation)) {
+        throw new Error("Candidate bytes changed during validation; promotion refused");
+    }
+    const templatesPath = join(dnaPath, "templates");
+    const templatesRealPath = await ensureSafeTemplatesDirectory(templatesPath, dnaRealPath);
+    const templatePath = join(templatesPath, `${options.templateName}.dna.yaml`);
+    const templateWritePath = join(templatesRealPath, `${options.templateName}.dna.yaml`);
+    const candidateName = candidateFilename.slice(0, -CANDIDATE_SUFFIX.length);
+    const receiptPath = join(authoringPath, `${candidateName}.candidate-review.json`);
+    const receiptWritePath = join(authoringRealPath, `${candidateName}.candidate-review.json`);
+    await assertPathMissing(templateWritePath, "Promotion target");
+    await assertPathMissing(receiptWritePath, "Candidate review receipt");
+    const candidateHash = sha256(candidateBytes);
+    let templateCreated = false;
+    let receiptCreated = false;
+    let templateHandle;
+    let receiptHandle;
+    try {
+        templateHandle = await open(templateWritePath, "wx");
+        templateCreated = true;
+        await templateHandle.writeFile(candidateBytes);
+        await templateHandle.sync();
+        await templateHandle.close();
+        templateHandle = undefined;
+        const currentTemplatesRealPath = await realpath(templatesPath);
+        if (currentTemplatesRealPath !== templatesRealPath) {
+            throw new Error("Templates directory changed during promotion; promotion refused");
+        }
+        const promotedBytes = await readFile(templateWritePath);
+        const templateHash = sha256(promotedBytes);
+        if (!promotedBytes.equals(candidateBytes) || templateHash !== candidateHash) {
+            throw new Error("Promoted template does not preserve the validated candidate bytes exactly");
+        }
+        const receipt = {
+            schema_version: "intentdna.candidate_promotion_receipt.v1",
+            decision: "promoted",
+            source: "explicit_human_promotion",
+            mutation_performed: true,
+            promoted_at: new Date().toISOString(),
+            candidate_path: candidatePath,
+            template_path: templatePath,
+            candidate_sha256: candidateHash,
+            template_sha256: templateHash,
+            exact_bytes_preserved: true,
+        };
+        const receiptBytes = Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+        receiptHandle = await open(receiptWritePath, "wx");
+        receiptCreated = true;
+        await receiptHandle.writeFile(receiptBytes);
+        await receiptHandle.sync();
+        await receiptHandle.close();
+        receiptHandle = undefined;
+        return {
+            schema_version: "intentdna.candidate_promotion_result.v1",
+            candidate_path: candidatePath,
+            template_path: templatePath,
+            receipt_path: receiptPath,
+            candidate_sha256: candidateHash,
+            template_sha256: templateHash,
+            exact_bytes_preserved: true,
+        };
+    }
+    catch (error) {
+        await receiptHandle?.close().catch(() => undefined);
+        await templateHandle?.close().catch(() => undefined);
+        const cleanupErrors = [];
+        if (receiptCreated) {
+            const cleanupError = await removeCreatedPath(receiptWritePath);
+            if (cleanupError)
+                cleanupErrors.push(cleanupError);
+        }
+        if (templateCreated) {
+            const cleanupError = await removeCreatedPath(templateWritePath);
+            if (cleanupError)
+                cleanupErrors.push(cleanupError);
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError([error, ...cleanupErrors], "Candidate promotion failed and cleanup did not complete");
+        }
+        throw error;
+    }
+}

package/dist/cli/commands/run-lifecycle.js

@@ -9,6 +9,7 @@ const TASK_STATES = [
     "ready",
     "claimed",
     "running",
+    "round_succeeded",
     "succeeded",
     "failed",
     "skipped",

package/dist/cli/commands/run.js

@@ -22,7 +22,7 @@ import { DurableRunStore, RunStoreError, } from "../../runtime/run-store.js";
 import { createClaudeExecutionProvider } from "../../runtime/providers/claude.js";
 import { createCodexExecutionProvider } from "../../runtime/providers/codex.js";
 import { runCheckpointVerifier, runCompletionVerifier, } from "../../runtime/verifier.js";
-import { adaptWorkflowPlan, } from "../../runtime/workflow-plan-adapter.js";
+import { adaptWorkflowPlan, adaptWorkflowRetryLoop, } from "../../runtime/workflow-plan-adapter.js";
 import { executeWorkerAttempt, } from "../../runtime/worker-executor.js";
 import { allocateAttemptWorkspace, applyWorkspaceLifecycleDecision, planAttemptWorkspace, } from "../../runtime/workspace-isolation.js";
 import { runLifecycleCancel, runLifecycleInspect, runLifecycleResume, runLifecycleStart, runLifecycleStatus, } from "./run-lifecycle.js";
@@ -237,6 +237,7 @@ async function compileCanonicalRun(metadata) {
     return {
         ...assets,
         definitions: adaptWorkflowPlan(assets.plan, adapterOptions),
+        retry_loop: adaptWorkflowRetryLoop(assets.plan, adapterOptions),
     };
 }
 async function syncRuntimeArtifacts(compiled, metadata) {
@@ -371,7 +372,7 @@ async function applyStepValidation(metadata, compiled, packet, execution) {
     }
     const variables = {
         ...metadata.variables,
-        round: String(packet.attempt_number),
+        round: String(packet.workflow_round),
     };
     let failure = null;
     for (const completion of step.completion ?? []) {
@@ -468,7 +469,7 @@ function createWorkspaceAwareExecutor(metadata, compiled, runStore) {
                     workflow: metadata.workflow_name,
                     current_step: packet.step_id,
                     current_role: packet.role,
-                    iteration: packet.attempt_number,
+                    iteration: packet.workflow_round,
                     session_id: packet.worker_session_id,
                     worker_session_id: packet.worker_session_id,
                     run_id: packet.run_id,
@@ -478,7 +479,7 @@ function createWorkspaceAwareExecutor(metadata, compiled, runStore) {
                     inputs: { ...metadata.variables },
                     resolved_variables: {
                         ...metadata.variables,
-                        round: String(packet.attempt_number),
+                        round: String(packet.workflow_round),
                     },
                 });
             }
@@ -533,6 +534,7 @@ function buildRuntime(metadata, compiled) {
         run_store: runStore,
         handoff_resolver: resolver,
         steps: compiled.definitions,
+        workflow_retry_loop: compiled.retry_loop,
         provider_for_step: () => provider,
         reconcile_attempt: reconcileLocalProcess,
         execute_attempt: createWorkspaceAwareExecutor(metadata, compiled, runStore),

package/dist/cli/commands/source-assets.d.ts

@@ -0,0 +1,32 @@
+import type { DiscoveredSkillSource, SourceSnapshot } from "../../sources/types.js";
+export interface SourceAssetsOptions {
+    homeDir?: string;
+    projectDir?: string;
+    sourceDirs?: readonly string[];
+    customRoots?: readonly string[];
+    sourceId?: string;
+    snapshot?: boolean;
+    packet?: boolean;
+    write?: string;
+    json?: boolean;
+    generatedAt?: string;
+}
+export interface SourceAssetsCatalog {
+    schema_version: "intentdna.source_catalog.v1";
+    generated_at: string;
+    sources: DiscoveredSkillSource[];
+    network_performed: false;
+    mutation_performed: false;
+    runtime_authority: false;
+}
+export interface SourceSnapshotCollection {
+    schema_version: "intentdna.source_snapshot_collection.v1";
+    generated_at: string;
+    snapshots: SourceSnapshot[];
+    network_performed: false;
+    mutation_performed: false;
+    runtime_authority: false;
+}
+export declare function buildSourceAssetsCatalog(options?: SourceAssetsOptions): Promise<SourceAssetsCatalog>;
+export declare function buildSourceAssetsSnapshots(options?: SourceAssetsOptions): Promise<SourceSnapshotCollection>;
+export declare function runSourceAssets(options?: SourceAssetsOptions): Promise<number>;

package/dist/cli/commands/source-assets.js

@@ -0,0 +1,154 @@
+import { lstat, mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { buildSourceAuthoringPacket } from "../../sources/authoring-packet.js";
+import { discoverSkillSources } from "../../sources/discovery.js";
+import { createSourceSnapshot } from "../../sources/manifest.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+function inside(root, target) {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function selectSource(sources, selector, preferredRoots = []) {
+    const exact = sources.find((source) => source.source_id === selector);
+    if (exact)
+        return exact;
+    const named = sources.filter((source) => source.name === selector);
+    for (const preferredRoot of preferredRoots) {
+        const root = resolve(preferredRoot);
+        const preferred = named.find((source) => {
+            const skillDir = resolve(source.skill_dir);
+            return skillDir === root || inside(root, skillDir);
+        });
+        if (preferred)
+            return preferred;
+    }
+    return named[0];
+}
+async function assertNoSymlinkedParents(root, target) {
+    const parentRelative = relative(root, dirname(target));
+    let current = root;
+    for (const segment of parentRelative.split(sep)) {
+        if (!segment)
+            continue;
+        current = resolve(current, segment);
+        try {
+            const metadata = await lstat(current);
+            if (metadata.isSymbolicLink()) {
+                throw new Error(`Source artifact parent must not be a symbolic link: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+}
+async function writePacketOrSnapshot(payload, projectDir, destination) {
+    const authoringRoot = resolve(projectDir, ".dna", "authoring");
+    const target = resolve(projectDir, destination);
+    if (!inside(authoringRoot, target)) {
+        throw new Error(`Source artifacts may only be written inside ${authoringRoot}`);
+    }
+    await assertNoSymlinkedParents(projectDir, target);
+    await mkdir(dirname(target), { recursive: true });
+    await assertNoSymlinkedParents(projectDir, target);
+    await writeFile(target, `${JSON.stringify(payload, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+    return target;
+}
+export async function buildSourceAssetsCatalog(options = {}) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const sources = await discoverSkillSources({
+        homeDir: options.homeDir,
+        projectDir: options.projectDir,
+        customRoots: unique([...(options.sourceDirs ?? []), ...(options.customRoots ?? [])]),
+    });
+    return {
+        schema_version: "intentdna.source_catalog.v1",
+        generated_at: generatedAt,
+        sources,
+        network_performed: false,
+        mutation_performed: false,
+        runtime_authority: false,
+    };
+}
+export async function buildSourceAssetsSnapshots(options = {}) {
+    const catalog = await buildSourceAssetsCatalog(options);
+    const snapshots = await Promise.all(catalog.sources.map((source) => createSourceSnapshot({
+        sourceId: source.source_id,
+        skillDir: source.skill_dir,
+        generatedAt: catalog.generated_at,
+    })));
+    return {
+        schema_version: "intentdna.source_snapshot_collection.v1",
+        generated_at: catalog.generated_at,
+        snapshots,
+        network_performed: false,
+        mutation_performed: false,
+        runtime_authority: false,
+    };
+}
+export async function runSourceAssets(options = {}) {
+    const projectDir = resolve(options.projectDir ?? process.cwd());
+    try {
+        const catalog = await buildSourceAssetsCatalog({ ...options, projectDir });
+        let payload = catalog;
+        if (options.sourceId) {
+            const source = selectSource(catalog.sources, options.sourceId, options.sourceDirs);
+            if (!source) {
+                process.stderr.write(`Unknown source asset: ${options.sourceId}\n`);
+                return 2;
+            }
+            if (!options.packet) {
+                process.stderr.write("Error: selecting a source requires --packet.\n");
+                return 2;
+            }
+            payload = await buildSourceAuthoringPacket({
+                skillDir: source.skill_dir,
+                projectDir,
+                generatedAt: catalog.generated_at,
+                sourceId: source.source_id,
+            });
+        }
+        else if (options.packet) {
+            process.stderr.write("Error: --packet requires a source ID or source name.\n");
+            return 2;
+        }
+        else if (options.snapshot) {
+            payload = await buildSourceAssetsSnapshots({ ...options, projectDir, generatedAt: catalog.generated_at });
+        }
+        if (options.write) {
+            if (payload.schema_version === "intentdna.source_catalog.v1") {
+                process.stderr.write("Error: --write requires --snapshot or --packet.\n");
+                return 2;
+            }
+            const written = await writePacketOrSnapshot(payload, projectDir, options.write);
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify({ written, payload }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`Wrote source artifact: ${written}\n`);
+            }
+            return 0;
+        }
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        }
+        else if (payload.schema_version === "intentdna.source_catalog.v1") {
+            process.stderr.write(`Source assets: ${payload.sources.length}\n`);
+            for (const source of payload.sources) {
+                process.stderr.write(`  - ${source.source_id} (${source.skill_markdown_path})\n`);
+            }
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+}

package/dist/cli/commands/templates.js

@@ -1,7 +1,7 @@
 /**
  * dna templates — template catalog and deployment commands.
  */
-import { readdirSync, copyFileSync, existsSync, readFileSync, mkdirSync } from "node:fs";
+import { readdirSync, copyFileSync, existsSync, readFileSync, mkdirSync, lstatSync, } from "node:fs";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { resolve, join, basename, dirname } from "node:path";
@@ -15,6 +15,7 @@ import { resolveAuthToken } from "./auth.js";
 import { missingCliApiTokenReason } from "./cloud-auth-guidance.js";
 import { createWorkflowDraft, workflowDraftToTemplateYaml, } from "../../workflow/index.js";
 import { WORKFLOW_ASSET_IDS } from "../../templates/metadata.js";
+import { buildSourceAuthoringPacket } from "../../sources/authoring-packet.js";
 /**
  * Resolve the global intentdna templates directory.
  * Strategy: npm root -g + /intentdna/dist/templates
@@ -1774,6 +1775,9 @@ function candidateTemplateName(sourceId) {
 function normalizeTemplateSaveName(name) {
     return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "source-candidate";
 }
+function isSafeCandidateName(name) {
+    return /^[a-z][a-z0-9-]{1,62}$/.test(name);
+}
 function workflowFromSourceCandidate(candidate) {
     const closestTemplate = candidate.coverage.matchedTemplates[0]?.name;
     const comparePrompt = closestTemplate
@@ -1922,37 +1926,50 @@ function buildSourceCandidatePreview(candidate, requestedTemplateName) {
         boundary: "Read-only candidate preview. It prints a reviewable template YAML draft but does not write files, configure projects, sync runtimes, deploy, or mutate evolution markers.",
     };
 }
-function writeSourceCandidatePreview(preview) {
-    process.stderr.write("Template reference candidate preview\n");
-    process.stderr.write(`Reference: ${preview.candidate.id}\n`);
-    process.stderr.write(`Template: ${preview.templateName}\n`);
-    process.stderr.write(`Decision: ${preview.decision.status}\n`);
-    process.stderr.write(`Workflow: ${preview.draft.workflow.name}\n`);
-    process.stderr.write(`Steps: ${preview.draft.workflow.steps.length}\n`);
-    process.stderr.write("\nReview commands\n");
-    for (const command of preview.reviewCommands)
-        process.stderr.write(`  - ${command}\n`);
-    process.stderr.write("\nBlocked until review\n");
-    for (const blocker of preview.blockedUntilReview)
-        process.stderr.write(`  - ${blocker}\n`);
-    process.stderr.write(`Boundary: ${preview.boundary}\n`);
-    process.stderr.write("\n--- YAML preview is written to stdout ---\n");
-    process.stdout.write(preview.templateYaml);
-    if (!preview.templateYaml.endsWith("\n"))
-        process.stdout.write("\n");
-}
 async function saveSourceCandidatePreview(params) {
-    const projectDir = params.projectDir ?? process.cwd();
-    const templateDir = join(projectDir, ".dna", "templates");
-    const path = join(templateDir, `${params.preview.templateName}.dna.yaml`);
+    const projectDir = resolve(params.projectDir ?? process.cwd());
+    const dnaDir = join(projectDir, ".dna");
+    const authoringDir = join(dnaDir, "authoring");
+    const path = join(authoringDir, `${params.preview.templateName}.candidate.dna.yaml`);
+    for (const stagingParent of [dnaDir, authoringDir]) {
+        if (existsSync(stagingParent)
+            && lstatSync(stagingParent).isSymbolicLink()) {
+            return {
+                error: `Candidate staging path must not contain a symlink: ${stagingParent}`,
+                path,
+            };
+        }
+    }
     if (existsSync(path)) {
         return {
-            error: `Workflow asset draft already exists: ${params.preview.templateName}`,
+            error: `Candidate already exists: ${params.preview.templateName}`,
             path,
         };
     }
-    await mkdir(templateDir, { recursive: true });
-    await writeFile(path, params.preview.templateYaml, "utf-8");
+    await mkdir(authoringDir, { recursive: true });
+    for (const stagingParent of [dnaDir, authoringDir]) {
+        if (lstatSync(stagingParent).isSymbolicLink()) {
+            return {
+                error: `Candidate staging path must not contain a symlink: ${stagingParent}`,
+                path,
+            };
+        }
+    }
+    try {
+        await writeFile(path, params.preview.templateYaml, {
+            encoding: "utf-8",
+            flag: "wx",
+        });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            return {
+                error: `Candidate already exists: ${params.preview.templateName}`,
+                path,
+            };
+        }
+        throw error;
+    }
     const closestTemplate = params.preview.candidate.coverage.matchedTemplates[0]?.name ?? "<current-template>";
     return {
         mode: "saved_template_source_candidate",
@@ -1963,19 +1980,18 @@ async function saveSourceCandidatePreview(params) {
         decision: params.preview.decision,
         reviewCommands: params.preview.reviewCommands,
         nextCommands: [
-            `dna assets inspect ${params.preview.templateName} --evidence`,
+            `dna validate ${path}`,
+            `dna workflow project-candidate ${path} --target claude --dry-run`,
+            `dna workflow project-candidate ${path} --target codex --dry-run`,
             `dna assets diff ${closestTemplate} ${params.preview.templateName}`,
             `dna assets adoption ${params.preview.templateName}`,
-            `dna org bind --asset ${params.preview.templateName} --status planned --sync-target codex`,
-            "dna org rollout",
-            "dna sync --codex --dry-run",
         ],
         blockedUntilReview: [
             "Runtime sync remains blocked until asset diff/adoption and organization rollout review pass.",
             "Vercel deployment is unrelated unless a web/public surface changes.",
             "Evolution marker mutation remains blocked until evidence-backed suggestions are reviewed.",
         ],
-        boundary: "Saved reference candidate as a project-local draft only. It is not adopted, organization-bound, synced, deployed, or evolved.",
+        boundary: "Saved an unreviewed candidate under .dna/authoring only. It is not promoted, adopted, organization-bound, synced, deployed, or evolved.",
     };
 }
 function writeSavedSourceCandidate(result) {
@@ -2029,8 +2045,12 @@ export async function runTemplatesSources(opts = {}) {
             return 2;
         }
         if (opts.candidate) {
-            const preview = buildSourceCandidatePreview(candidate, opts.saveTemplate);
             if (opts.saveTemplate) {
+                if (!isSafeCandidateName(opts.saveTemplate)) {
+                    process.stderr.write("Error: invalid candidate name; use 2-63 lowercase letters, digits, or hyphens, starting with a letter.\n");
+                    return 2;
+                }
+                const preview = buildSourceCandidatePreview(candidate, opts.saveTemplate);
                 const saved = await saveSourceCandidatePreview({ preview, projectDir: opts.projectDir });
                 if ("error" in saved) {
                     process.stderr.write(`${saved.error}\n`);
@@ -2045,11 +2065,13 @@ export async function runTemplatesSources(opts = {}) {
                 writeSavedSourceCandidate(saved);
                 return 0;
             }
-            if (opts.json) {
-                process.stdout.write(`${JSON.stringify(preview, null, 2)}\n`);
-                return 0;
-            }
-            writeSourceCandidatePreview(preview);
+            const packet = await buildSourceAuthoringPacket({
+                skillDir: dirname(candidate.path),
+                projectDir: opts.projectDir,
+                sourceId: candidate.id,
+            });
+            process.stderr.write("Warning: deprecated --candidate alias; use --packet for source authoring packets.\n");
+            process.stdout.write(`${JSON.stringify(packet, null, 2)}\n`);
             return 0;
         }
         const packet = await buildTemplateSourceReviewPacket(candidate);