intentdna 1.7.4 → 1.8.0

package/dist/runtime/sync-artifact-registry.d.ts

@@ -0,0 +1,99 @@
+import type { SyncOutputArtifactId } from "./output-artifact-registry.js";
+import type { PlannedArtifact, SyncTarget } from "./sync-target-plan.js";
+export declare const SYNC_ARTIFACT_REGISTRY_PATH = ".dna/sync/registry.json";
+export declare const SYNC_ARTIFACT_REGISTRY_SCHEMA = "intentdna.sync_artifact_registry.v1";
+export type SyncArtifactOwnership = PlannedArtifact["ownership"] | "unknown";
+export type SyncArtifactStatus = "ok" | "missing" | "drifted" | "untracked";
+export interface SyncArtifactRegistryTemplate {
+    sourceDnaIds: string[];
+    configFiles: string[];
+    compiledIrHash?: string;
+}
+export interface SyncArtifactRegistryEntry {
+    artifact: SyncOutputArtifactId;
+    kind: string;
+    path: string;
+    relativePath: string;
+    target: SyncTarget | "markdown" | "generic";
+    adapter?: SyncTarget;
+    installMode?: string;
+    ownership: SyncArtifactOwnership;
+    trackedByLock: boolean;
+    sha256?: string;
+    missingAtSync?: boolean;
+}
+export interface SyncArtifactRegistry {
+    schema: typeof SYNC_ARTIFACT_REGISTRY_SCHEMA;
+    syncedAt: string;
+    projectDir: string;
+    dnaVersion?: string;
+    mode: "write";
+    template: SyncArtifactRegistryTemplate;
+    artifacts: SyncArtifactRegistryEntry[];
+}
+export interface SyncArtifactRegistryInputEntry {
+    artifact: SyncOutputArtifactId;
+    path: string;
+    kind?: string;
+    target?: SyncArtifactRegistryEntry["target"];
+    adapter?: SyncTarget;
+    installMode?: string;
+    ownership?: SyncArtifactOwnership;
+    trackedByLock?: boolean;
+}
+export interface WriteSyncArtifactRegistryOptions {
+    projectDir: string;
+    dnaVersion?: string;
+    template: SyncArtifactRegistryTemplate;
+    artifacts: SyncArtifactRegistryInputEntry[];
+}
+export interface SyncArtifactInspection extends SyncArtifactRegistryEntry {
+    status: SyncArtifactStatus;
+    currentSha256?: string;
+    reason: string;
+}
+export interface SyncArtifactRegistryInspection {
+    registry: SyncArtifactRegistry | null;
+    registryPath: string;
+    artifacts: SyncArtifactInspection[];
+    totals: {
+        artifacts: number;
+        ok: number;
+        missing: number;
+        drifted: number;
+        untracked: number;
+    };
+}
+export interface RemoveSyncArtifactsOptions {
+    projectDir?: string;
+    dryRun?: boolean;
+}
+export interface RemoveSyncArtifactsResult {
+    schema_version: "intentdna.sync_remove_result.v1";
+    mode: "sync_registry_remove";
+    registryPath: string;
+    removed: string[];
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+    preservation: {
+        note: string;
+        kept: Array<{
+            path: string;
+            reason: string;
+            explanation: string;
+        }>;
+        nextCommands: string[];
+    };
+    dryRun: boolean;
+    totals: {
+        removable: number;
+        skipped: number;
+    };
+    boundary: string;
+}
+export declare function writeSyncArtifactRegistry(options: WriteSyncArtifactRegistryOptions): Promise<SyncArtifactRegistry>;
+export declare function readSyncArtifactRegistry(projectDir?: string): Promise<SyncArtifactRegistry | null>;
+export declare function inspectSyncArtifactRegistry(projectDir?: string): Promise<SyncArtifactRegistryInspection>;
+export declare function removeSyncArtifacts(options?: RemoveSyncArtifactsOptions): Promise<RemoveSyncArtifactsResult>;

package/dist/runtime/sync-artifact-registry.js

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+export const SYNC_ARTIFACT_REGISTRY_PATH = ".dna/sync/registry.json";
+export const SYNC_ARTIFACT_REGISTRY_SCHEMA = "intentdna.sync_artifact_registry.v1";
+function fileSha256(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+async function computeFileHash(path) {
+    try {
+        return fileSha256(await readFile(path, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function registryPath(projectDir) {
+    return resolve(projectDir, SYNC_ARTIFACT_REGISTRY_PATH);
+}
+async function canonicalPath(path) {
+    return realpath(path).catch(() => resolve(path));
+}
+async function normalizeEntry(projectDir, entry) {
+    const canonicalProjectDir = await canonicalPath(projectDir);
+    const absolutePath = resolve(projectDir, entry.path);
+    const canonicalArtifactPath = await canonicalPath(absolutePath);
+    return {
+        artifact: entry.artifact,
+        kind: entry.kind ?? entry.artifact,
+        path: canonicalArtifactPath,
+        relativePath: relative(canonicalProjectDir, canonicalArtifactPath) || ".",
+        target: entry.target ?? entry.adapter ?? "generic",
+        adapter: entry.adapter,
+        installMode: entry.installMode,
+        ownership: entry.ownership ?? "unknown",
+        trackedByLock: entry.trackedByLock ?? true,
+    };
+}
+function uniqueArtifacts(artifacts) {
+    const byKey = new Map();
+    for (const artifact of artifacts) {
+        byKey.set(`${artifact.artifact}:${artifact.path}:${artifact.kind}`, artifact);
+    }
+    return [...byKey.values()].sort((a, b) => a.target.localeCompare(b.target) ||
+        a.relativePath.localeCompare(b.relativePath) ||
+        a.kind.localeCompare(b.kind));
+}
+export async function writeSyncArtifactRegistry(options) {
+    const projectDir = await canonicalPath(options.projectDir);
+    const artifacts = uniqueArtifacts(await Promise.all(options.artifacts.map((entry) => normalizeEntry(projectDir, entry))));
+    const withHashes = [];
+    for (const artifact of artifacts) {
+        const sha256 = await computeFileHash(artifact.path);
+        withHashes.push(sha256 ? { ...artifact, sha256 } : { ...artifact, missingAtSync: true });
+    }
+    const registry = {
+        schema: SYNC_ARTIFACT_REGISTRY_SCHEMA,
+        syncedAt: new Date().toISOString(),
+        projectDir,
+        dnaVersion: options.dnaVersion,
+        mode: "write",
+        template: options.template,
+        artifacts: withHashes,
+    };
+    const path = registryPath(options.projectDir);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(registry, null, 2) + "\n", "utf-8");
+    return registry;
+}
+export async function readSyncArtifactRegistry(projectDir = process.cwd()) {
+    try {
+        const raw = await readFile(registryPath(projectDir), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schema !== SYNC_ARTIFACT_REGISTRY_SCHEMA || !Array.isArray(parsed.artifacts))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function inspectEntry(entry) {
+    if (!entry.sha256) {
+        const exists = await stat(entry.path).then(() => true, () => false);
+        return {
+            ...entry,
+            status: exists ? "untracked" : "missing",
+            reason: exists ? "No sync-time hash recorded for this artifact." : "Artifact did not exist when inspected.",
+        };
+    }
+    const currentSha256 = await computeFileHash(entry.path);
+    if (!currentSha256) {
+        return { ...entry, status: "missing", reason: "Artifact path is missing." };
+    }
+    if (currentSha256 !== entry.sha256) {
+        return { ...entry, status: "drifted", currentSha256, reason: "Artifact hash differs from last sync." };
+    }
+    return { ...entry, status: "ok", currentSha256, reason: "Artifact matches last sync." };
+}
+export async function inspectSyncArtifactRegistry(projectDir = process.cwd()) {
+    const registry = await readSyncArtifactRegistry(projectDir);
+    const artifacts = registry ? await Promise.all(registry.artifacts.map(inspectEntry)) : [];
+    const totals = {
+        artifacts: artifacts.length,
+        ok: artifacts.filter((entry) => entry.status === "ok").length,
+        missing: artifacts.filter((entry) => entry.status === "missing").length,
+        drifted: artifacts.filter((entry) => entry.status === "drifted").length,
+        untracked: artifacts.filter((entry) => entry.status === "untracked").length,
+    };
+    return { registry, registryPath: registryPath(projectDir), artifacts, totals };
+}
+function isSafeToRemove(entry) {
+    if (entry.status !== "ok")
+        return false;
+    if (!entry.sha256 || entry.currentSha256 !== entry.sha256)
+        return false;
+    return entry.ownership === "intentdna_owned" || entry.ownership === "diagnostic";
+}
+function removalSkipExplanation(entry) {
+    if (entry.status === "drifted") {
+        return "Preserved because the file changed after the last sync; review the diff or rerun dna sync before cleanup.";
+    }
+    if (entry.status === "missing") {
+        return "No file was deleted because the registry path is already missing.";
+    }
+    if (entry.status === "untracked") {
+        return "Preserved because no sync-time hash proves IntentDNA still owns the current file.";
+    }
+    if (entry.ownership === "merge_preserve_user") {
+        return "Preserved because the artifact is a merge-preserve user configuration surface.";
+    }
+    if (entry.ownership === "owned_block") {
+        return "Preserved because IntentDNA owns only an injected block inside this user file.";
+    }
+    if (entry.ownership === "unknown") {
+        return "Preserved because ownership is unknown.";
+    }
+    return "Preserved because this artifact is outside the safe remove set.";
+}
+export async function removeSyncArtifacts(options = {}) {
+    const projectDir = options.projectDir ?? process.cwd();
+    const inspection = await inspectSyncArtifactRegistry(projectDir);
+    const removed = [];
+    const skipped = [];
+    const kept = [];
+    for (const artifact of inspection.artifacts) {
+        if (!isSafeToRemove(artifact)) {
+            const reason = `${artifact.ownership}/${artifact.status}`;
+            skipped.push({ path: artifact.path, reason });
+            kept.push({ path: artifact.path, reason, explanation: removalSkipExplanation(artifact) });
+            continue;
+        }
+        if (!options.dryRun)
+            await rm(artifact.path, { recursive: true, force: true });
+        removed.push(artifact.path);
+    }
+    if (inspection.registry && !options.dryRun && skipped.length === 0) {
+        await rm(inspection.registryPath, { force: true });
+        removed.push(inspection.registryPath);
+    }
+    else if (inspection.registry && !options.dryRun) {
+        const keptPaths = new Set(skipped.map((entry) => entry.path));
+        const preservedRegistry = {
+            ...inspection.registry,
+            artifacts: inspection.registry.artifacts.filter((artifact) => keptPaths.has(artifact.path)),
+        };
+        await writeFile(inspection.registryPath, JSON.stringify(preservedRegistry, null, 2) + "\n", "utf-8");
+    }
+    else if (inspection.registry && skipped.length === 0) {
+        removed.push(inspection.registryPath);
+    }
+    return {
+        schema_version: "intentdna.sync_remove_result.v1",
+        mode: "sync_registry_remove",
+        registryPath: inspection.registryPath,
+        removed,
+        skipped,
+        preservation: {
+            note: "Safe remove preserves user-owned, merge-preserve, owned-block, drifted, missing, untracked, and unknown-ownership registry entries.",
+            kept,
+            nextCommands: [
+                "dna sync status",
+                "dna sync doctor",
+                "dna sync remove --dry-run",
+            ],
+        },
+        dryRun: options.dryRun === true,
+        totals: {
+            removable: removed.length,
+            skipped: skipped.length,
+        },
+        boundary: "remove only deletes hash-matching IntentDNA-owned/diagnostic artifacts from the sync registry; merge-preserve/user-owned files are skipped",
+    };
+}

package/dist/runtime/sync-target-plan.d.ts

@@ -0,0 +1,45 @@
+import type { SyncOutputArtifactId } from "./output-artifact-registry.js";
+export type SyncTarget = "claude_code" | "codex_cli";
+export type SyncTargetMode = "write" | "remove" | "dry_run";
+export type CapabilitySupportStatus = "supported" | "partial" | "unknown" | "unsupported";
+export type EvidenceClassification = "enterprise_evidence" | "diagnostic_only" | "unsupported";
+export interface PlannedArtifact {
+    kind: string;
+    path: string;
+    ownership: "intentdna_owned" | "owned_block" | "merge_preserve_user" | "diagnostic";
+    trackedByLock: boolean;
+    outputArtifact?: SyncOutputArtifactId;
+}
+export interface CapabilityReportEntry {
+    status: CapabilitySupportStatus;
+    surfaces: string[];
+    evidenceRefs: string[];
+    notes: string[];
+}
+export interface AdapterCapabilityReport {
+    adapter: SyncTarget;
+    runtime?: string;
+    capabilities: Record<string, CapabilityReportEntry>;
+    unsupported: string[];
+}
+export interface EvidencePlan {
+    primary: "RuntimeDecisionEvent" | "none";
+    diagnosticArtifacts: string[];
+    classification: EvidenceClassification;
+    notes: string[];
+}
+export interface SyncTargetPlan {
+    target: SyncTarget;
+    mode?: SyncTargetMode;
+    plannedArtifacts: PlannedArtifact[];
+    capabilityReport?: AdapterCapabilityReport;
+    evidencePlan: EvidencePlan;
+    warnings: string[];
+    unsupported: string[];
+}
+export interface SyncTargetTrackedOutput {
+    artifact: SyncOutputArtifactId;
+    path: string;
+}
+export declare function trackedOutputsForSyncTargetPlan(plan: SyncTargetPlan): SyncTargetTrackedOutput[];
+export declare function formatSyncTargetPlanDiagnostics(plan: SyncTargetPlan): string;

package/dist/runtime/sync-target-plan.js

@@ -0,0 +1,19 @@
+export function trackedOutputsForSyncTargetPlan(plan) {
+    return plan.plannedArtifacts
+        .filter((artifact) => typeof artifact.outputArtifact === "string" && artifact.outputArtifact.length > 0)
+        .map((artifact) => ({ artifact: artifact.outputArtifact, path: artifact.path }));
+}
+export function formatSyncTargetPlanDiagnostics(plan) {
+    const lines = [];
+    if (plan.warnings.length > 0) {
+        lines.push(`${plan.target} warnings:`);
+        for (const warning of plan.warnings)
+            lines.push(`  - ${warning}`);
+    }
+    if (plan.unsupported.length > 0) {
+        lines.push(`${plan.target} unsupported gaps:`);
+        for (const gap of plan.unsupported)
+            lines.push(`  - ${gap}`);
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}

package/dist/schema/controller-registry.d.ts

@@ -5,7 +5,7 @@ export interface ControllerKindMetadata {
     kind: ControllerKind;
     label: string;
     supportsSkillGeneration: boolean;
-    requiredRoleKeys: readonly ControllerRoleKey[];
+    requiredRoleKeys: readonly string[];
     diagnosisRoleKeys: readonly ControllerRoleKey[];
     fixRoleKeys: readonly ControllerRoleKey[];
 }
@@ -23,6 +23,13 @@ export declare const CONTROLLER_KIND_REGISTRY: readonly [{
     readonly requiredRoleKeys: readonly ["analyzer", "analysis_reviewer", "surgeon", "fix_reviewer", "test_runner"];
     readonly diagnosisRoleKeys: readonly ["analyzer", "analysis_reviewer"];
     readonly fixRoleKeys: readonly ["surgeon", "fix_reviewer", "test_runner"];
+}, {
+    readonly kind: "sequential";
+    readonly label: "Sequential workflow gate";
+    readonly supportsSkillGeneration: false;
+    readonly requiredRoleKeys: readonly [];
+    readonly diagnosisRoleKeys: readonly [];
+    readonly fixRoleKeys: readonly [];
 }];
 export declare function getControllerKindMetadata(kind: unknown): ControllerKindMetadata | undefined;
 export declare function isSupportedControllerKind(kind: unknown): kind is ControllerKind;

package/dist/schema/controller-registry.js

@@ -22,6 +22,14 @@ export const CONTROLLER_KIND_REGISTRY = [
         diagnosisRoleKeys: ["analyzer", "analysis_reviewer"],
         fixRoleKeys: ["surgeon", "fix_reviewer", "test_runner"],
     },
+    {
+        kind: "sequential",
+        label: "Sequential workflow gate",
+        supportsSkillGeneration: false,
+        requiredRoleKeys: [],
+        diagnosisRoleKeys: [],
+        fixRoleKeys: [],
+    },
 ];
 const CONTROLLER_KIND_BY_ID = new Map(CONTROLLER_KIND_REGISTRY.map((entry) => [entry.kind, entry]));
 export function getControllerKindMetadata(kind) {

package/dist/schema/types.d.ts

@@ -96,7 +96,8 @@ export interface VerifierCommandPolicy {
     allow_builtin_asserts?: string[];
 }
 /** Handoff artifact type — what kind of artifact is passed between steps */
-export type HandoffType = "file" | "directory" | "test_result" | "git_commit" | "summary" | "state";
+export declare const HANDOFF_TYPE_VALUES: readonly ["file", "directory", "test_result", "git_commit", "summary", "state"];
+export type HandoffType = typeof HANDOFF_TYPE_VALUES[number];
 /** A single artifact consumed or produced by a workflow step */
 export interface HandoffArtifact {
     type: HandoffType;
@@ -142,14 +143,18 @@ export interface StepHandoff {
 export interface TransitionDef {
     from: string;
     to: string;
-    condition: "pass" | "fail" | "always" | "error";
+    condition: TransitionCondition;
 }
+export declare const TRANSITION_CONDITION_VALUES: readonly ["pass", "fail", "always", "error"];
+export type TransitionCondition = typeof TRANSITION_CONDITION_VALUES[number];
 /** Retry policy for the workflow */
 export interface RetryPolicy {
     max_retries: number;
     retry_from?: string;
-    backoff?: "none" | "linear" | "exponential";
+    backoff?: RetryBackoff;
 }
+export declare const RETRY_BACKOFF_VALUES: readonly ["none", "linear", "exponential"];
+export type RetryBackoff = typeof RETRY_BACKOFF_VALUES[number];
 /** Predefined checkpoint assertion types — compiler knows how to translate each to shell */
 export type CheckpointAssertType = "clean_working_tree" | "no_test_regression" | "lint_passing" | "build_passing";
 /** Step checkpoint — condition that must be met before transitioning to next step */
@@ -157,8 +162,18 @@ export interface StepCheckpoint {
     assert: CheckpointAssertType | string;
     command?: string;
     message: string;
-    action?: "block" | "warn";
-}
+    action?: CheckpointAction;
+}
+export declare const CHECKPOINT_ACTION_VALUES: readonly ["block", "warn"];
+export type CheckpointAction = typeof CHECKPOINT_ACTION_VALUES[number];
+export declare const WORKFLOW_ISOLATION_VALUES: readonly ["none", "worktree", "auto"];
+export type WorkflowIsolation = typeof WORKFLOW_ISOLATION_VALUES[number];
+export declare const WORKFLOW_STEP_FAILURE_VALUES: readonly ["retry_with_feedback", "handoff", "skip"];
+export type WorkflowStepFailureAction = typeof WORKFLOW_STEP_FAILURE_VALUES[number];
+export declare const WORKFLOW_HANDOFF_EXHAUSTED_VALUES: readonly ["skip", "stop"];
+export type WorkflowHandoffExhaustedAction = typeof WORKFLOW_HANDOFF_EXHAUSTED_VALUES[number];
+export declare const WORKFLOW_MERGE_STRATEGY_VALUES: readonly ["escalate"];
+export type WorkflowMergeStrategy = typeof WORKFLOW_MERGE_STRATEGY_VALUES[number];
 /** Completion check for a workflow step */
 export interface CompletionCheck {
     file_exists?: string;
@@ -181,17 +196,17 @@ export interface WorkflowStepDef {
     completion?: CompletionCheck[];
     checkpoints?: StepCheckpoint[];
     handoff?: StepHandoff;
-    isolation?: "none" | "worktree" | "auto";
+    isolation?: WorkflowIsolation;
     enforce?: {
         read_only?: boolean;
         relax_after_iteration?: number;
         additional_write_paths?: string[];
     };
     max_attempts?: number;
-    on_fail?: "retry_with_feedback" | "handoff" | "skip";
+    on_fail?: WorkflowStepFailureAction;
     handoff_to?: string;
     max_handoffs?: number;
-    on_handoff_exhausted?: "skip" | "stop";
+    on_handoff_exhausted?: WorkflowHandoffExhaustedAction;
     blocked_items_path?: string;
 }
 /** Top-level workflow definition */
@@ -204,10 +219,10 @@ export interface WorkflowDef {
     max_rounds?: number;
     produces?: HandoffArtifact[];
     consumes?: HandoffArtifact[];
-    default_isolation?: "none" | "worktree" | "auto";
-    merge_strategy?: "escalate";
+    default_isolation?: WorkflowIsolation;
+    merge_strategy?: WorkflowMergeStrategy;
 }
-export type ControllerKind = "fix_loop" | "flutter_rewrite_fix_loop";
+export type ControllerKind = "fix_loop" | "flutter_rewrite_fix_loop" | "sequential";
 export interface ControllerPolicyDef {
     diagnosis_reuse_criteria?: string[];
     progress_provenance_checks?: string[];
@@ -223,18 +238,13 @@ export interface ControllerDef {
     kind: ControllerKind;
     max_rounds: number;
     progress_artifact_path: string;
-    diagnosis_workflow: string;
-    fix_workflow: string;
-    diagnosis_artifact_path: string;
-    diagnosis_review_artifact_path: string;
-    review_artifact_path: string;
-    roles: {
-        analyzer: string;
-        analysis_reviewer: string;
-        surgeon: string;
-        fix_reviewer: string;
-        test_runner: string;
-    };
+    workflow?: string;
+    diagnosis_workflow?: string;
+    fix_workflow?: string;
+    diagnosis_artifact_path?: string;
+    diagnosis_review_artifact_path?: string;
+    review_artifact_path?: string;
+    roles: Record<string, string>;
     stop_format: "configured_stop_report" | "zh_three_part";
     policy?: ControllerPolicyDef;
 }
@@ -479,6 +489,7 @@ export interface StepEnforceRule {
 export interface WorkflowIR {
     workflow_name: string;
     namespace: string;
+    step_ids?: string[];
     step_checkpoints: StepCheckpointIR[];
     active_roles: string[];
     handoff_chain: HandoffChainEntry[];
@@ -502,6 +513,7 @@ export interface CompletedArtifactEntry {
 /** Runtime workflow state written to .dna/state/workflow.json */
 export interface WorkflowState {
     active: boolean;
+    workflow_asset?: string;
     workflow: string;
     current_step: string;
     current_role: string;

package/dist/schema/types.js

@@ -7,4 +7,13 @@
  *   Layer 3: Regulatory Regions (context-dependent expression)
  *   Layer 4: Epigenetic Markers (experience-driven modulation)
  */
-export {};
+// ── Workflow System ─────────────────────────────────────────
+/** Handoff artifact type — what kind of artifact is passed between steps */
+export const HANDOFF_TYPE_VALUES = ["file", "directory", "test_result", "git_commit", "summary", "state"];
+export const TRANSITION_CONDITION_VALUES = ["pass", "fail", "always", "error"];
+export const RETRY_BACKOFF_VALUES = ["none", "linear", "exponential"];
+export const CHECKPOINT_ACTION_VALUES = ["block", "warn"];
+export const WORKFLOW_ISOLATION_VALUES = ["none", "worktree", "auto"];
+export const WORKFLOW_STEP_FAILURE_VALUES = ["retry_with_feedback", "handoff", "skip"];
+export const WORKFLOW_HANDOFF_EXHAUSTED_VALUES = ["skip", "stop"];
+export const WORKFLOW_MERGE_STRATEGY_VALUES = ["escalate"];

package/dist/schema/validate.js

@@ -8,6 +8,7 @@
  *   - No circular inheritance
  */
 import { isAbsolute } from "node:path";
+import { CHECKPOINT_ACTION_VALUES, HANDOFF_TYPE_VALUES, RETRY_BACKOFF_VALUES, TRANSITION_CONDITION_VALUES, WORKFLOW_HANDOFF_EXHAUSTED_VALUES, WORKFLOW_ISOLATION_VALUES, WORKFLOW_MERGE_STRATEGY_VALUES, WORKFLOW_STEP_FAILURE_VALUES, } from "./types.js";
 import { validateController } from "./validators/controllers.js";
 const SAFE_GENERATED_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
 const SAFE_GENERATED_DISPLAY_NAME = /^[A-Za-z0-9][A-Za-z0-9 _-]*$/;
@@ -503,25 +504,22 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         }
         // on_fail: must be a valid enum value
         if (step.on_fail !== undefined) {
-            const validOnFail = ["retry_with_feedback", "handoff", "skip"];
-            if (!validOnFail.includes(step.on_fail)) {
-                errors.push({ path: `${stepPath}.on_fail`, message: `must be one of: ${validOnFail.join(", ")}` });
+            if (!WORKFLOW_STEP_FAILURE_VALUES.includes(step.on_fail)) {
+                errors.push({ path: `${stepPath}.on_fail`, message: `must be one of: ${WORKFLOW_STEP_FAILURE_VALUES.join(", ")}` });
             }
         }
         // on_handoff_exhausted: must be a valid enum value
         if (step.on_handoff_exhausted !== undefined) {
-            const validExhausted = ["skip", "stop"];
-            if (!validExhausted.includes(step.on_handoff_exhausted)) {
-                errors.push({ path: `${stepPath}.on_handoff_exhausted`, message: `must be one of: ${validExhausted.join(", ")}` });
+            if (!WORKFLOW_HANDOFF_EXHAUSTED_VALUES.includes(step.on_handoff_exhausted)) {
+                errors.push({ path: `${stepPath}.on_handoff_exhausted`, message: `must be one of: ${WORKFLOW_HANDOFF_EXHAUSTED_VALUES.join(", ")}` });
             }
         }
         // isolation: must be a valid enum value
         if (step.isolation !== undefined) {
-            const validIsolation = ["none", "worktree", "auto"];
-            if (!validIsolation.includes(step.isolation)) {
+            if (!WORKFLOW_ISOLATION_VALUES.includes(step.isolation)) {
                 errors.push({
                     path: `${stepPath}.isolation`,
-                    message: `must be one of: ${validIsolation.join(", ")}`,
+                    message: `must be one of: ${WORKFLOW_ISOLATION_VALUES.join(", ")}`,
                 });
             }
         }
@@ -540,6 +538,12 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
             for (let j = 0; j < artifacts.length; j++) {
                 const artifact = artifacts[j];
                 const artifactPath = `${stepPath}.handoff.${direction}[${j}]`;
+                if (!HANDOFF_TYPE_VALUES.includes(artifact.type)) {
+                    errors.push({ path: `${artifactPath}.type`, message: `must be one of: ${HANDOFF_TYPE_VALUES.join(", ")}` });
+                }
+                if (!artifact.description) {
+                    errors.push({ path: `${artifactPath}.description`, message: "handoff artifact requires 'description'" });
+                }
                 if (artifact.required !== false && artifact.type !== "git_commit" && !artifact.path && !artifact.name && !artifact.artifact_id) {
                     errors.push({ path: artifactPath, message: "required handoff artifacts must define path, name, or artifact_id" });
                 }
@@ -567,7 +571,7 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
                     if (!cp.message) {
                         errors.push({ path: `${cpPath}.message`, message: "checkpoint requires 'message'" });
                     }
-                    if (cp.action && cp.action !== "block" && cp.action !== "warn") {
+                    if (cp.action && !CHECKPOINT_ACTION_VALUES.includes(cp.action)) {
                         errors.push({ path: `${cpPath}.action`, message: "checkpoint action must be 'block' or 'warn'" });
                     }
                 }
@@ -607,26 +611,23 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
     }
     // Validate default_isolation
     if (workflow.default_isolation !== undefined) {
-        const validIsolation = ["none", "worktree", "auto"];
-        if (!validIsolation.includes(workflow.default_isolation)) {
+        if (!WORKFLOW_ISOLATION_VALUES.includes(workflow.default_isolation)) {
             errors.push({
                 path: `${path}.default_isolation`,
-                message: `must be one of: ${validIsolation.join(", ")}`,
+                message: `must be one of: ${WORKFLOW_ISOLATION_VALUES.join(", ")}`,
             });
         }
     }
     // Validate merge_strategy
     if (workflow.merge_strategy !== undefined) {
-        const validStrategies = ["escalate"];
-        if (!validStrategies.includes(workflow.merge_strategy)) {
+        if (!WORKFLOW_MERGE_STRATEGY_VALUES.includes(workflow.merge_strategy)) {
             errors.push({
                 path: `${path}.merge_strategy`,
-                message: `must be one of: ${validStrategies.join(", ")}`,
+                message: `must be one of: ${WORKFLOW_MERGE_STRATEGY_VALUES.join(", ")}`,
             });
         }
     }
     // Validate transitions
-    const validConditions = ["pass", "fail", "always", "error"];
     for (let i = 0; i < (workflow.transitions?.length ?? 0); i++) {
         const t = workflow.transitions[i];
         const tPath = `${path}.transitions[${i}]`;
@@ -642,10 +643,10 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
         else if (!stepIds.has(t.to)) {
             errors.push({ path: `${tPath}.to`, message: `transition references unknown step '${t.to}'` });
         }
-        if (!t.condition || !validConditions.includes(t.condition)) {
+        if (!t.condition || !TRANSITION_CONDITION_VALUES.includes(t.condition)) {
             errors.push({
                 path: `${tPath}.condition`,
-                message: `transition condition must be one of: ${validConditions.join(", ")}`,
+                message: `transition condition must be one of: ${TRANSITION_CONDITION_VALUES.join(", ")}`,
             });
         }
     }
@@ -665,11 +666,10 @@ function validateWorkflow(workflow, roleNames, pathPrefix) {
                 message: `retry_from references unknown step '${rp.retry_from}'`,
             });
         }
-        const validBackoff = ["none", "linear", "exponential"];
-        if (rp.backoff && !validBackoff.includes(rp.backoff)) {
+        if (rp.backoff && !RETRY_BACKOFF_VALUES.includes(rp.backoff)) {
             errors.push({
                 path: `${rpPath}.backoff`,
-                message: `backoff must be one of: ${validBackoff.join(", ")}`,
+                message: `backoff must be one of: ${RETRY_BACKOFF_VALUES.join(", ")}`,
             });
         }
     }