intentdna 1.7.5 → 1.8.1

package/dist/runtime/skill-adapter.js

@@ -19,26 +19,54 @@ function resolveContainedPath(baseDir, ...segments) {
     }
     return target;
 }
+function isHumanRole(role) {
+    return role?.model?.trim().toLowerCase() === "human";
+}
+function isInteractiveRole(role) {
+    return role?.model?.trim().toLowerCase() === "interactive";
+}
 // ── Compile Controller → Skill ─────────────────────────────
 export function compileControllerToSkill(controllerKey, controller, variables, workflows) {
     const kindMetadata = getControllerKindMetadata(controller.kind);
     if (!kindMetadata?.supportsSkillGeneration) {
         throw new Error(`Unsupported controller kind: ${controller.kind}`);
     }
+    const diagnosisWorkflowName = controller.diagnosis_workflow;
+    const fixWorkflowName = controller.fix_workflow;
+    const diagnosisArtifactPath = controller.diagnosis_artifact_path;
+    const diagnosisReviewArtifactPath = controller.diagnosis_review_artifact_path;
+    const reviewArtifactPath = controller.review_artifact_path;
+    const analyzerRole = controller.roles.analyzer;
+    const analysisReviewerRole = controller.roles.analysis_reviewer;
+    const surgeonRole = controller.roles.surgeon;
+    const fixReviewerRole = controller.roles.fix_reviewer;
+    const testRunnerRole = controller.roles.test_runner;
+    if (!diagnosisWorkflowName ||
+        !fixWorkflowName ||
+        !diagnosisArtifactPath ||
+        !diagnosisReviewArtifactPath ||
+        !reviewArtifactPath ||
+        !analyzerRole ||
+        !analysisReviewerRole ||
+        !surgeonRole ||
+        !fixReviewerRole ||
+        !testRunnerRole) {
+        throw new Error(`Controller '${controllerKey}' is missing fix-loop skill generation fields`);
+    }
     const skillName = `dna-${toKebabCase(controllerKey)}`;
     assertSafeGeneratedName(skillName, "skill name");
-    const analyzerAgent = `dna-${toKebabCase(controller.roles.analyzer)}`;
-    const analysisReviewerAgent = `dna-${toKebabCase(controller.roles.analysis_reviewer)}`;
-    const surgeonAgent = `dna-${toKebabCase(controller.roles.surgeon)}`;
-    const fixReviewerAgent = `dna-${toKebabCase(controller.roles.fix_reviewer)}`;
-    const testRunnerAgent = `dna-${toKebabCase(controller.roles.test_runner)}`;
-    const diagnosisWorkflow = workflows?.[controller.diagnosis_workflow];
-    const fixWorkflow = workflows?.[controller.fix_workflow];
-    const diagnosisAnalyzeStep = requireStepByRole(diagnosisWorkflow, controller.roles.analyzer, controller.diagnosis_workflow);
-    const diagnosisReviewStep = requireStepByRole(diagnosisWorkflow, controller.roles.analysis_reviewer, controller.diagnosis_workflow);
-    const fixBugsStep = requireStepByRole(fixWorkflow, controller.roles.surgeon, controller.fix_workflow);
-    const reviewChangesStep = requireStepByRole(fixWorkflow, controller.roles.fix_reviewer, controller.fix_workflow);
-    const verifyReportStep = requireStepByRole(fixWorkflow, controller.roles.test_runner, controller.fix_workflow);
+    const analyzerAgent = `dna-${toKebabCase(analyzerRole)}`;
+    const analysisReviewerAgent = `dna-${toKebabCase(analysisReviewerRole)}`;
+    const surgeonAgent = `dna-${toKebabCase(surgeonRole)}`;
+    const fixReviewerAgent = `dna-${toKebabCase(fixReviewerRole)}`;
+    const testRunnerAgent = `dna-${toKebabCase(testRunnerRole)}`;
+    const diagnosisWorkflow = workflows?.[diagnosisWorkflowName];
+    const fixWorkflow = workflows?.[fixWorkflowName];
+    const diagnosisAnalyzeStep = requireStepByRole(diagnosisWorkflow, analyzerRole, diagnosisWorkflowName);
+    const diagnosisReviewStep = requireStepByRole(diagnosisWorkflow, analysisReviewerRole, diagnosisWorkflowName);
+    const fixBugsStep = requireStepByRole(fixWorkflow, surgeonRole, fixWorkflowName);
+    const reviewChangesStep = requireStepByRole(fixWorkflow, fixReviewerRole, fixWorkflowName);
+    const verifyReportStep = requireStepByRole(fixWorkflow, testRunnerRole, fixWorkflowName);
     const stepPrompt = (step) => step.prompt || step.description || "";
     const policy = normalizeControllerPolicy(controller);
     const lines = [];
@@ -63,8 +91,8 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push("<Controller>");
     lines.push(`kind: ${controller.kind}`);
     lines.push(`max_rounds: ${controller.max_rounds}`);
-    lines.push(`diagnosis_workflow: ${controller.diagnosis_workflow}`);
-    lines.push(`fix_workflow: ${controller.fix_workflow}`);
+    lines.push(`diagnosis_workflow: ${diagnosisWorkflowName}`);
+    lines.push(`fix_workflow: ${fixWorkflowName}`);
     lines.push(`progress_artifact_path: ${controller.progress_artifact_path}`);
     lines.push("</Controller>");
     lines.push("");
@@ -74,16 +102,17 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push("   - If it contains '/', '.', '..', spaces, braces, glob characters, or path separators, stop with the configured stop report.");
     lines.push("   - Do not read or write controller artifacts until the module argument is safe.");
     lines.push("1. Check diagnosis artifact freshness before any fix round.");
-    lines.push(`   - Diagnosis artifact: ${controller.diagnosis_artifact_path}`);
-    lines.push(`   - Diagnosis review artifact: ${controller.diagnosis_review_artifact_path}`);
+    lines.push(`   - Diagnosis artifact: ${diagnosisArtifactPath}`);
+    lines.push(`   - Diagnosis review artifact: ${diagnosisReviewArtifactPath}`);
     lines.push("2. Create a stable controller_run_id once for this invocation before using any artifact path.");
     lines.push("   - Reuse the same controller_run_id in every child Agent prompt and in every progress validation.");
     lines.push("   - Do not regenerate controller_run_id inside fix rounds.");
-    lines.push("3. Reuse diagnosis only when all diagnosis reuse criteria pass:");
+    lines.push("3. Reuse the diagnosis artifact only when all diagnosis reuse criteria pass:");
     for (const criterion of policy.diagnosis_reuse_criteria) {
         lines.push(`   - ${criterion}`);
     }
-    lines.push(`4. If diagnosis is missing, invalid, stale, or scope-changed, run diagnosis once with fresh context and sequential gates:`);
+    lines.push("   Reuse skips fresh analyzer and analysis_reviewer agents; it never skips the declared diagnosis contract completion gates or the persisted diagnosis review JSON approval gate before any surgeon step.");
+    lines.push(`4. If diagnosis is missing, invalid, stale, or scope-changed, run the analyzer once with fresh context:`);
     lines.push("   a. Spawn fresh analyzer agent with controller_run_id, then wait for completion.");
     lines.push("   ```");
     lines.push("   Agent(");
@@ -91,6 +120,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push(`     prompt="controller_run_id=<controller_run_id>. ${escapePrompt(stepPrompt(diagnosisAnalyzeStep))}"`);
     lines.push("   )");
     lines.push("   ```");
+    pushWorkflowStepVerifierLines(lines, diagnosisAnalyzeStep, "   ");
     lines.push(`   b. Diagnosis artifact gate: read ${controller.diagnosis_artifact_path}; validate it exists, is non-empty, names the safe module argument, and is current for this module before continuing.`);
     lines.push("   c. Spawn fresh analysis_reviewer agent with controller_run_id, then wait for completion.");
     lines.push("   ```");
@@ -99,9 +129,12 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push(`     prompt="controller_run_id=<controller_run_id>; expected_review_artifact=${controller.diagnosis_review_artifact_path}. ${escapePrompt(stepPrompt(diagnosisReviewStep))}"`);
     lines.push("   )");
     lines.push("   ```");
-    lines.push(`   d. Diagnosis review JSON gate: read ${controller.diagnosis_review_artifact_path}; require existing valid JSON with verdict APPROVE before fix rounds.`);
+    pushWorkflowStepVerifierLines(lines, diagnosisReviewStep, "   ");
+    lines.push("5. If the diagnosis artifact was reused, do not spawn analyzer or analysis_reviewer; rerun the declared diagnosis contract completion gates against the existing artifacts:");
+    pushWorkflowStepVerifierLines(lines, diagnosisReviewStep, "   ");
+    lines.push(`6. Diagnosis review JSON gate: read ${controller.diagnosis_review_artifact_path}; require existing valid JSON with verdict APPROVE before fix rounds.`);
     lines.push("   If the review JSON is missing, invalid, or verdict is not APPROVE, stop immediately with the configured stop report; do NOT enter fix rounds.");
-    lines.push(`5. For round 1..${controller.max_rounds}, set current_round to the loop number and run one fresh context fix round with sequential gates:`);
+    lines.push(`7. For round 1..${controller.max_rounds}, set current_round to the loop number and run one fresh context fix round with sequential gates:`);
     lines.push("   a. Spawn fresh surgeon agent with controller_run_id and current_round, then wait for completion.");
     lines.push("   ```");
     lines.push("   Agent(");
@@ -109,6 +142,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push(`     prompt="controller_run_id=<controller_run_id>; current_round=<current_round>. Fresh context round for $ARGUMENTS. ${escapePrompt(stepPrompt(fixBugsStep))}"`);
     lines.push("   )");
     lines.push("   ```");
+    pushWorkflowStepVerifierLines(lines, fixBugsStep, "   ");
     lines.push("   b. Fix handoff gate: validate the current round handoff and fix commit, or an explicit no-commit handoff for current_round, before review.");
     lines.push("   c. Spawn fresh fix_reviewer agent with controller_run_id, current_round, and expected review artifact path, then wait for completion.");
     lines.push("   ```");
@@ -117,6 +151,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push(`     prompt="controller_run_id=<controller_run_id>; current_round=<current_round>; expected_review_artifact=${controller.review_artifact_path}. Fresh context review for $ARGUMENTS. ${escapePrompt(stepPrompt(reviewChangesStep))}"`);
     lines.push("   )");
     lines.push("   ```");
+    pushWorkflowStepVerifierLines(lines, reviewChangesStep, "   ");
     lines.push(`   d. Review JSON gate: read ${controller.review_artifact_path}; validate it exists, is valid JSON, module equals the safe module argument, round equals the provided current_round, run_id equals the provided controller_run_id, updated_at is present, and verdict is APPROVE or REQUEST_CHANGES before verification.`);
     lines.push("   e. Spawn fresh test_runner agent only after the review gate passes; include controller_run_id and current_round, then wait for completion.");
     lines.push("   ```");
@@ -125,6 +160,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     lines.push(`     prompt="controller_run_id=<controller_run_id>; current_round=<current_round>. Fresh context verification for $ARGUMENTS. The progress JSON run_id must equal the provided controller_run_id and round must equal the provided current_round; do not use manual-run during controller execution. ${escapePrompt(stepPrompt(verifyReportStep))}"`);
     lines.push("   )");
     lines.push("   ```");
+    pushWorkflowStepVerifierLines(lines, verifyReportStep, "   ");
     lines.push(`   f. Progress JSON read/provenance validation: read ${controller.progress_artifact_path}. The controller must read this JSON sidecar, not Markdown prose.`);
     lines.push("   g. Verify progress JSON provenance before branching:");
     for (const check of policy.progress_provenance_checks) {
@@ -135,7 +171,7 @@ export function compileControllerToSkill(controllerKey, controller, variables, w
     for (const branch of policy.verdict_branches) {
         lines.push(`      - ${branch}`);
     }
-    lines.push(`6. If max ${controller.max_rounds} rounds is reached, stop with the configured stop report.`);
+    lines.push(`8. If max ${controller.max_rounds} rounds is reached, stop with the configured stop report.`);
     lines.push("</Steps>");
     lines.push("");
     lines.push("<Verdict_Mapping>");
@@ -195,6 +231,37 @@ function requireStepByRole(workflow, role, workflowName) {
     }
     return step;
 }
+function pushWorkflowStepVerifierLines(lines, step, indent) {
+    if (step.completion?.length) {
+        lines.push(`${indent}Completion gates for workflow step '${step.id}' must pass in declaration order before treating the step as complete:`);
+        for (let i = 0; i < step.completion.length; i++) {
+            lines.push(`${indent}   ${i + 1}. ${describeCompletionCheck(step.completion[i])}`);
+        }
+    }
+    if (step.checkpoints?.length) {
+        lines.push(`${indent}Checkpoint gates for workflow step '${step.id}' must pass in declaration order before transitioning:`);
+        for (let i = 0; i < step.checkpoints.length; i++) {
+            const checkpoint = step.checkpoints[i];
+            const action = checkpoint.action ?? "block";
+            const command = checkpoint.command ? `; command: ${checkpoint.command}` : "";
+            lines.push(`${indent}   ${i + 1}. ${checkpoint.assert}: ${checkpoint.message} (${action}${command})`);
+        }
+    }
+    if (step.completion?.some((check) => check.command_success) || step.checkpoints?.some((check) => check.command)) {
+        lines.push(`${indent}Command-backed completion/checkpoint gates must use runtime verifier_policy semantics: first authorize the declared raw command against exact allow_commands or allow_command_prefixes, then resolve templates safely, execute the exact resolved command, require exit code 0 for pass, treat policy denial as exit_code=126, and treat any non-zero exit code as blocking failure unless the checkpoint action is warn.`);
+    }
+}
+function describeCompletionCheck(check) {
+    if (check.file_exists)
+        return `file_exists: ${check.file_exists}`;
+    if (check.file_not_empty)
+        return `file_not_empty: ${check.file_not_empty}`;
+    if (check.file_contains)
+        return `file_contains: ${check.file_contains.path} matches ${check.file_contains.pattern}`;
+    if (check.command_success)
+        return `command_success: execute exact command "${check.command_success}", require exit code 0, and block on any non-zero exit code`;
+    return "invalid completion check: exactly one completion check field is required";
+}
 function createSkillLauncher(params) {
     const lines = [];
     lines.push("---");
@@ -289,9 +356,9 @@ function renderControllerPolicyLines(lines, controller) {
 function renderControllerPolicyText(text, controller) {
     const replacements = {
         "$progress_artifact_path": controller.progress_artifact_path,
-        "$diagnosis_artifact_path": controller.diagnosis_artifact_path,
-        "$diagnosis_review_artifact_path": controller.diagnosis_review_artifact_path,
-        "$review_artifact_path": controller.review_artifact_path,
+        "$diagnosis_artifact_path": controller.diagnosis_artifact_path ?? "",
+        "$diagnosis_review_artifact_path": controller.diagnosis_review_artifact_path ?? "",
+        "$review_artifact_path": controller.review_artifact_path ?? "",
     };
     let rendered = text;
     for (const [token, value] of Object.entries(replacements)) {
@@ -381,9 +448,10 @@ function workflowSkillMapEntry(skillName, dirName, plan) {
         produces,
     };
 }
-export function compileWorkflowToSkill(plan, roles, ir, variables) {
+export function compileWorkflowToSkill(plan, roles, ir, variables, options) {
     const lines = [];
     const skillName = `dna-${toKebabCase(plan.name)}`;
+    const surface = options?.surface ?? "claude_code";
     assertSafeGeneratedName(skillName, "skill name");
     // Frontmatter
     lines.push("---");
@@ -492,8 +560,10 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         lines.push("</Advisory_Context>");
         lines.push("");
     }
-    // Steps — each step MUST be executed via Agent() tool call
+    // Steps — agent-owned steps are delegated; human-owned steps stay in the main session.
     const usedRoles = new Set(plan.steps.map((s) => s.role));
+    const hasHumanSteps = plan.steps.some((step) => isHumanRole(roles[step.role]));
+    const hasInteractiveSteps = plan.steps.some((step) => isInteractiveRole(roles[step.role]));
     // Pre-compute handoff targets: steps that are pointed to by another step's handoff_to
     const handoffTargets = new Set();
     for (const step of plan.steps) {
@@ -508,6 +578,8 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
             stepNumber++;
             const step = plan.steps.find((s) => s.id === stepId);
             const agentType = `dna-${toKebabCase(step.role)}`;
+            const humanOwned = isHumanRole(roles[step.role]);
+            const interactiveOwned = isInteractiveRole(roles[step.role]);
             const runIf = step.run_if ? `\n   **Condition**: ${step.run_if}` : "";
             const optional = step.optional ? " (optional)" : "";
             // Build agent prompt: anti-recursion + role identity + task
@@ -536,14 +608,34 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
             lines.push(`${stepNumber}. **${step.id}**${optional}`);
             lines.push(`   ${step.description}${runIf}`);
             lines.push("");
-            lines.push(`   Execute with Agent tool — DO NOT perform this work yourself:`);
-            lines.push(`   \`\`\``);
-            lines.push(`   Agent(`);
-            lines.push(`     subagent_type="${agentType}",`);
-            lines.push(`     prompt="${agentPrompt}"`);
-            lines.push(`   )`);
-            lines.push(`   \`\`\``);
-            lines.push(`   Wait for agent to complete. Read the output before proceeding.`);
+            if (humanOwned) {
+                lines.push("   **Human-owned gate (`model: human`)**");
+                lines.push(`   Ask the user in the main session: ${step.prompt || step.description}`);
+                lines.push("   Do not delegate this decision, infer approval, or continue from silence. Continue only after an explicit human response.");
+            }
+            else if (interactiveOwned) {
+                lines.push("   **Main-session external-agent step (`model: interactive`)**");
+                lines.push(`   Perform directly in the main session: ${step.prompt || step.description}`);
+                lines.push("   This step may interview the user or edit the candidate YAML inside its declared scope. Do not delegate away the conversation context.");
+            }
+            else if (surface === "codex_cli") {
+                lines.push("   Delegate to a Codex native subagent with this role contract; do not discard the role boundaries:");
+                lines.push("   ```text");
+                lines.push(`   role: ${agentType}`);
+                lines.push(`   prompt: ${agentPrompt}`);
+                lines.push("   ```");
+                lines.push("   Wait for the subagent to complete and read its output before proceeding.");
+            }
+            else {
+                lines.push(`   Execute with Agent tool — DO NOT perform this work yourself:`);
+                lines.push(`   \`\`\``);
+                lines.push(`   Agent(`);
+                lines.push(`     subagent_type="${agentType}",`);
+                lines.push(`     prompt="${agentPrompt}"`);
+                lines.push(`   )`);
+                lines.push(`   \`\`\``);
+                lines.push(`   Wait for agent to complete. Read the output before proceeding.`);
+            }
             if (step.handoff?.produces && step.handoff.produces.length > 0) {
                 const artifacts = step.handoff.produces.map(p => p.description).join(", ");
                 lines.push(`   Verify produced artifacts: ${artifacts}`);
@@ -565,14 +657,39 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
     }
     lines.push("</Steps>");
     lines.push("");
-    // Execution Policy — force Agent dispatch
+    if (plan.retry.max_retries > 0) {
+        lines.push("<Retry_Policy>");
+        lines.push(`- max_retries: ${plan.retry.max_retries}`);
+        lines.push(`- retry_from: ${plan.retry.retry_from ?? "first_failed_step"}`);
+        lines.push(`- backoff: ${plan.retry.backoff}`);
+        lines.push("- On a blocking checkpoint or validator failure, preserve the exact diagnostics and return them to the retry_from step.");
+        lines.push("- Repeat only the retry slice and its dependent steps; do not continue to save, adoption, or sync while validation is red.");
+        lines.push("- Stop and report the remaining diagnostics when the retry budget is exhausted.");
+        lines.push("</Retry_Policy>");
+        lines.push("");
+    }
+    // Execution Policy — force delegation while preserving explicit human gates.
     lines.push("<Execution_Policy>");
-    lines.push("- **CRITICAL**: Each step MUST be executed by spawning an Agent using the Agent tool with the specified subagent_type. DO NOT perform any step's work directly in the main session.");
+    if (surface === "codex_cli") {
+        lines.push("- **CRITICAL**: Delegate each delegated-agent step to a Codex native subagent using the specified role contract. Do not collapse distinct roles into an unreviewed single pass.");
+    }
+    else {
+        lines.push(hasHumanSteps || hasInteractiveSteps
+            ? "- **CRITICAL**: Each delegated-agent step MUST be executed by spawning an Agent using the Agent tool with the specified subagent_type. DO NOT perform delegated-agent work directly in the main session."
+            : "- **CRITICAL**: Each step MUST be executed by spawning an Agent using the Agent tool with the specified subagent_type. DO NOT perform any step's work directly in the main session.");
+    }
     lines.push("- Use the task tracker to track each step only as pending/in_progress/completed; use deleted only for skipped dependent tasks.");
-    lines.push("- After completing each step, immediately proceed to the next — do not stop, summarize, or wait for confirmation.");
+    lines.push(hasHumanSteps
+        ? "- Proceed automatically between non-human steps, but stop at every `model: human` step and require an explicit user response before continuing."
+        : "- After completing each step, immediately proceed to the next — do not stop, summarize, or wait for confirmation.");
+    if (hasInteractiveSteps) {
+        lines.push("- Execute `model: interactive` steps in the main session so interview answers and candidate edits remain in the user-visible conversation.");
+    }
     lines.push("- If a step cannot complete, do not use a failed status. Keep the current task in_progress or record the blocker in the task description/output, delete skipped dependent tasks, and continue only to non-dependent steps.");
-    lines.push("- Do not ask the user for permission between steps — the workflow is pre-approved.");
-    lines.push("- Wait for each Agent to complete and read its output before proceeding to the next step.");
+    lines.push(hasHumanSteps
+        ? "- Never auto-approve, delegate, or synthesize a human-owned decision."
+        : "- Do not ask the user for permission between steps — the workflow is pre-approved.");
+    lines.push("- Wait for each delegated agent to complete and read its output before proceeding to the next step.");
     lines.push("</Execution_Policy>");
     lines.push("");
     // Tool_Usage — only if roles have permissions or scope
@@ -585,9 +702,15 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
         const denied = role.tool_permissions?.deny?.join(", ") || "none";
         const writeScope = role.scope?.write?.join(", ") || "none";
         toolUsageLines.push(`### ${roleName}`);
+        toolUsageLines.push(`- Owner: ${isHumanRole(role) ? "human" : isInteractiveRole(role) ? "main_session_external_agent" : "delegated_agent"}`);
+        toolUsageLines.push(`- Description: ${role.description}`);
         toolUsageLines.push(`- Allowed: ${allowed}`);
         toolUsageLines.push(`- Denied: ${denied}`);
         toolUsageLines.push(`- Write scope: ${writeScope}`);
+        for (const instruction of role.instructions ?? [])
+            toolUsageLines.push(`- Instruction: ${instruction}`);
+        for (const criterion of role.success_criteria ?? [])
+            toolUsageLines.push(`- Success criterion: ${criterion}`);
     }
     if (toolUsageLines.length > 0) {
         lines.push("<Tool_Usage>");
@@ -631,6 +754,8 @@ export function compileWorkflowToSkill(plan, roles, ir, variables) {
             for (const cp of step.checkpoints) {
                 const action = cp.action || "block";
                 lines.push(`- ${cp.assert}: ${cp.message} (${action})`);
+                if (cp.command)
+                    lines.push(`  command: ${cp.command}`);
             }
         }
         lines.push("</Checkpoints>");

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",
+    };
+}