@goondocks/myco 0.15.1 → 0.16.1

package/dist/{executor-4OXDK4ZA.js → executor-PUKL76TU.js}

@@ -1,5 +1,6 @@
 import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);
 import {
+  SKILL_GENERATE_TASK,
   STATUS_COMPLETED,
   STATUS_FAILED,
   STATUS_RUNNING,
@@ -30,13 +31,20 @@ import {
   updateRunStatus,
   updateSkillRecord,
   upsertDigestExtract
-} from "./chunk-75J2BR4P.js";
+} from "./chunk-D63XTGBV.js";
 import {
   fullTextSearch
-} from "./chunk-DTE3SHYK.js";
+} from "./chunk-UILSK6DK.js";
+import {
+  cleanupStagedSkill,
+  readStagedManifest,
+  readStagedSkill,
+  writeStagedManifest,
+  writeStagedSkill
+} from "./chunk-U5EW2VIQ.js";
 import {
   loadAllTasks
-} from "./chunk-3MEOYXOW.js";
+} from "./chunk-D2NTFSVO.js";
 import {
   getAgent,
   getDefaultTask,
@@ -45,31 +53,33 @@ import {
   loadSystemPrompt,
   resolveDefinitionsDir,
   resolveEffectiveConfig
-} from "./chunk-X4XFJG6I.js";
+} from "./chunk-W7ZOOZMK.js";
 import {
   insertTurn
 } from "./chunk-QLCD77AN.js";
 import {
   insertResolutionEvent
-} from "./chunk-Z7TZJ2SP.js";
+} from "./chunk-P6C6ADBU.js";
 import "./chunk-IB76KGBY.js";
 import {
   DEFAULT_IMPORTANCE,
   insertSpore,
   listSpores,
   updateSporeStatus
-} from "./chunk-SPJGJEFV.js";
+} from "./chunk-IRSNOBGD.js";
 import {
   listSessions,
   updateSession
-} from "./chunk-23FJUKCN.js";
-import "./chunk-LF5Z62X6.js";
+} from "./chunk-SGYYOTNM.js";
+import "./chunk-4JVHWBZF.js";
 import {
+  AGENT_SETTABLE_STATUSES,
+  CANDIDATE_STATUS,
   createSchema
-} from "./chunk-DJQOYEK3.js";
+} from "./chunk-CJ2KTRWI.js";
 import {
   loadConfig
-} from "./chunk-4BQ5QE76.js";
+} from "./chunk-XAXQ72L3.js";
 import {
   getDatabase,
   initDatabase,
@@ -77,7 +87,7 @@ import {
 } from "./chunk-MYX5NCRH.js";
 import {
   getPluginVersion
-} from "./chunk-BFM6AM6R.js";
+} from "./chunk-VTSNXAW7.js";
 import {
   findPackageRoot
 } from "./chunk-LPUQPDC2.js";
@@ -89,8 +99,8 @@ import {
   SEARCH_SIMILARITY_THRESHOLD,
   TEAM_SOURCE_PREFIX,
   epochSeconds
-} from "./chunk-TRA3R4EC.js";
-import "./chunk-CUADDHHU.js";
+} from "./chunk-34NHDRWI.js";
+import "./chunk-E7NUADTQ.js";
 import "./chunk-D7TYRPRM.js";
 import "./chunk-E4VLWIJC.js";
 import {
@@ -836,6 +846,200 @@ function validateSkillContent(content, dirName) {
 // src/agent/tools/skill-tools.ts
 function createSkillTools(deps) {
   const { agentId, machineId, projectRoot, vaultDir, recordTurn } = deps;
+  function findOverlappingCandidate(newTopic, existing) {
+    let best = null;
+    for (const candidate of existing) {
+      const score = descriptionSimilarity(newTopic, candidate.topic);
+      if (score >= DESCRIPTION_DUPLICATE_THRESHOLD && (!best || score > best.score)) {
+        best = { candidate, score };
+      }
+    }
+    return best;
+  }
+  function candidateOverlapError(match) {
+    const common = `already has an existing candidate with a similar topic: "${match.topic}"`;
+    switch (match.status) {
+      case CANDIDATE_STATUS.DISMISSED:
+        return `Candidate rejected: the vault ${common} that was previously dismissed. Do not re-identify dismissed topics.`;
+      case CANDIDATE_STATUS.GENERATED:
+        return `Candidate rejected: the vault ${common} that was already fulfilled by a generated skill. Do not re-identify.`;
+      case CANDIDATE_STATUS.APPROVED:
+        return `Candidate rejected: the vault ${common} that is already queued in approved state. Wait for the generate task to process it.`;
+      case CANDIDATE_STATUS.IDENTIFIED:
+        return `Candidate rejected: the vault ${common} already in the review queue. Update the existing candidate with new evidence (action: update) instead of creating a duplicate.`;
+      default:
+        return `Candidate rejected: the vault ${common} in status '${match.status}'.`;
+    }
+  }
+  function requireApprovedCandidate(candidateId) {
+    const candidate = getCandidate(candidateId);
+    if (!candidate) {
+      return {
+        error: `Candidate ${candidateId} not found. Skill writes require a candidate in the approved state.`
+      };
+    }
+    if (candidate.status !== CANDIDATE_STATUS.APPROVED) {
+      return {
+        error: `Candidate ${candidateId} is in '${candidate.status}' state. Skills can only be generated from candidates in 'approved' state \u2014 the human review step. If a candidate in an earlier state needs to become a skill, route it through the normal approval flow first.`,
+        candidate_status: candidate.status
+      };
+    }
+    return null;
+  }
+  function checkDedupGates(args) {
+    const existingSameName = getSkillRecordByName(args.name);
+    if (existingSameName) {
+      if (args.rejectSameName) {
+        return {
+          error: `Skill "${args.name}" already exists. This path is create-only. Use vault_write_skill to evolve the existing skill (it bumps the generation), or mark the current record stale via vault_skill_records first.`,
+          existing_skill: {
+            id: existingSameName.id,
+            name: existingSameName.name,
+            path: existingSameName.path
+          }
+        };
+      }
+      return null;
+    }
+    if (args.candidate_id) {
+      const candidate = getCandidate(args.candidate_id);
+      if (candidate?.skill_id) {
+        const linkedSkill = getSkillRecord(candidate.skill_id);
+        if (linkedSkill && linkedSkill.name !== args.name) {
+          return {
+            error: `Candidate ${args.candidate_id} is already fulfilled by skill "${linkedSkill.name}". Do not create a sibling skill. If the existing skill needs changes, write to the same name to evolve it (this bumps its generation), or mark it stale via vault_skill_records before replacing.`,
+            existing_skill: {
+              id: linkedSkill.id,
+              name: linkedSkill.name,
+              description: linkedSkill.description,
+              path: linkedSkill.path
+            }
+          };
+        }
+      }
+    }
+    const activeSkills = listSkillRecords({ agent_id: agentId, status: "active", limit: 200 });
+    let bestMatch = null;
+    for (const skill of activeSkills) {
+      const score = descriptionSimilarity(args.description, skill.description);
+      if (score >= DESCRIPTION_DUPLICATE_THRESHOLD && (!bestMatch || score > bestMatch.score)) {
+        bestMatch = { skill, score };
+      }
+    }
+    if (bestMatch) {
+      return {
+        error: `Description overlaps with existing active skill "${bestMatch.skill.name}" (Jaccard ${bestMatch.score.toFixed(2)}, threshold ${DESCRIPTION_DUPLICATE_THRESHOLD}). Do not create a duplicate. Either evolve the existing skill by writing to its name ("${bestMatch.skill.name}"), or reframe this skill so its description describes a distinct procedure.`,
+        overlapping_skill: {
+          id: bestMatch.skill.id,
+          name: bestMatch.skill.name,
+          description: bestMatch.skill.description,
+          path: bestMatch.skill.path
+        },
+        similarity: bestMatch.score
+      };
+    }
+    return null;
+  }
+  async function promoteNewSkill(params) {
+    const root = projectRoot ?? process.cwd();
+    const skillDir = resolve(root, ".agents", "skills", params.name);
+    const skillPath = resolve(skillDir, "SKILL.md");
+    const skillDirPreexisted = existsSync(skillDir);
+    async function cleanupCreatedSkillArtifactsOnRollback() {
+      try {
+        if (!skillDirPreexisted) {
+          rmSync(skillDir, { recursive: true, force: true });
+        } else {
+          rmSync(skillPath, { force: true });
+        }
+      } catch (rollbackErr) {
+        console.warn(
+          `[${params.label}] file rollback after DB failure also failed:`,
+          rollbackErr instanceof Error ? rollbackErr.message : rollbackErr
+        );
+      }
+      try {
+        const { syncSkillSymlinks } = await import("./installer-AARSFXI6.js");
+        syncSkillSymlinks(root, params.name, { remove: true });
+      } catch (rollbackErr) {
+        console.warn(
+          `[${params.label}] symlink rollback after DB failure also failed:`,
+          rollbackErr instanceof Error ? rollbackErr.message : rollbackErr
+        );
+      }
+    }
+    try {
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(skillPath, params.content, "utf-8");
+    } catch (err) {
+      return {
+        error: `Failed to write skill file: ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+    try {
+      const { syncSkillSymlinks } = await import("./installer-AARSFXI6.js");
+      syncSkillSymlinks(root, params.name);
+    } catch (err) {
+      console.warn(
+        `[${params.label}] syncSkillSymlinks failed:`,
+        err instanceof Error ? err.message : err
+      );
+    }
+    const now = epochSeconds();
+    const relativePath = `.agents/skills/${params.name}/SKILL.md`;
+    const recordId = crypto2.randomUUID();
+    const generation = 1;
+    const txDb = getDatabase();
+    try {
+      txDb.transaction(() => {
+        insertSkillRecord({
+          id: recordId,
+          agent_id: agentId,
+          machine_id: machineId,
+          name: params.name,
+          display_name: params.display_name,
+          description: params.description,
+          candidate_id: params.candidate_id ?? null,
+          source_ids: params.source_ids,
+          path: relativePath,
+          created_at: now,
+          updated_at: now
+        });
+        insertLineage({
+          id: crypto2.randomUUID(),
+          skill_id: recordId,
+          generation,
+          action: "created",
+          rationale: params.rationale ?? "Initial skill creation",
+          source_ids_added: params.source_ids,
+          content_snapshot: params.content,
+          created_at: now
+        });
+        params.linkCandidate?.(recordId, now);
+      })();
+    } catch (err) {
+      await cleanupCreatedSkillArtifactsOnRollback();
+      return {
+        error: `Skill write aborted: database transaction failed and on-disk state was rolled back. ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+    return {
+      id: recordId,
+      name: params.name,
+      path: relativePath,
+      generation
+    };
+  }
+  function emitSkillNotification(kind, opts) {
+    notify(vaultDir, {
+      domain: "skills",
+      type: kind === "created" ? "skill.created" : "skill.evolved",
+      title: `Skill ${kind}: ${opts.display_name}`,
+      message: opts.description.slice(0, 120),
+      link: `/skills?skill=${encodeURIComponent(opts.name)}`,
+      metadata: { skillId: opts.recordId, name: opts.name, generation: opts.generation }
+    });
+  }
   const vaultSkillCandidates = tool4(
     "vault_skill_candidates",
     "Manage skill candidates (identified topics that may become skills). Supports list, get, create, and update actions.",
@@ -845,7 +1049,9 @@ function createSkillTools(deps) {
       topic: external_exports.string().optional().describe("Skill topic (required for create)"),
       rationale: external_exports.string().optional().describe("Why this should be a skill (required for create)"),
       confidence: external_exports.number().optional().describe("Confidence score 0-1"),
-      status: external_exports.enum(["identified", "approved", "generated", "dismissed"]).optional().describe("Candidate status. Only these values are valid."),
+      status: external_exports.enum(AGENT_SETTABLE_STATUSES).optional().describe(
+        "Candidate status \u2014 agent-settable values only. 'identified' is the initial state; 'dismissed' retires a candidate. 'approved' and 'generated' are lifecycle transitions owned by the human UI and vault_finalize_skill respectively."
+      ),
       source_ids: external_exports.string().optional().describe("JSON array of source spore/entity IDs"),
       skill_id: external_exports.string().optional().describe("Associated skill record ID (after materialization)"),
       limit: external_exports.number().optional().describe("Maximum candidates to return (for list)")
@@ -884,6 +1090,19 @@ function createSkillTools(deps) {
               overlapping_skills: overlapping.map((s) => ({ name: s.name, display_name: s.display_name, description: s.description }))
             });
           }
+          const allExisting = listCandidates({ agent_id: agentId, limit: 500 });
+          const match = findOverlappingCandidate(args.topic, allExisting);
+          if (match) {
+            return textResult({
+              error: candidateOverlapError(match.candidate),
+              existing_candidate: {
+                id: match.candidate.id,
+                status: match.candidate.status,
+                topic: match.candidate.topic
+              },
+              similarity: match.score
+            });
+          }
           const now = epochSeconds();
           const candidate = insertCandidate({
             id: crypto2.randomUUID(),
@@ -991,7 +1210,7 @@ function createSkillTools(deps) {
               console.warn("[vault_skill_records] Failed to remove skill directory:", err instanceof Error ? err.message : err);
             }
             try {
-              const { syncSkillSymlinks } = await import("./installer-BTUNKWOU.js");
+              const { syncSkillSymlinks } = await import("./installer-AARSFXI6.js");
               syncSkillSymlinks(root, result.name, { remove: true });
             } catch (err) {
               console.warn("[vault_skill_records] Failed to remove symlinks:", err instanceof Error ? err.message : err);
@@ -1032,51 +1251,18 @@ function createSkillTools(deps) {
           error: 'Invalid skill name: must be a simple directory name without path separators or ".."'
         });
       }
-      const existingSameName = getSkillRecordByName(args.name);
-      if (!existingSameName) {
-        if (args.candidate_id) {
-          const candidate = getCandidate(args.candidate_id);
-          if (candidate?.skill_id) {
-            const linkedSkill = getSkillRecord(candidate.skill_id);
-            if (linkedSkill && linkedSkill.name !== args.name) {
-              recordTurn("vault_write_skill", args);
-              return textResult({
-                error: `Candidate ${args.candidate_id} is already fulfilled by skill "${linkedSkill.name}". Do not create a sibling skill. If the existing skill needs changes, write to the same name to evolve it (this bumps its generation), or mark it stale via vault_skill_records before replacing.`,
-                existing_skill: {
-                  id: linkedSkill.id,
-                  name: linkedSkill.name,
-                  description: linkedSkill.description,
-                  path: linkedSkill.path
-                }
-              });
-            }
-          }
-        }
-        const activeSkills = listSkillRecords({ agent_id: agentId, status: "active", limit: 200 });
-        let bestMatch = null;
-        for (const skill of activeSkills) {
-          const score = descriptionSimilarity(args.description, skill.description);
-          if (score >= DESCRIPTION_DUPLICATE_THRESHOLD && (!bestMatch || score > bestMatch.score)) {
-            bestMatch = { skill, score };
-          }
-        }
-        if (bestMatch) {
-          recordTurn("vault_write_skill", args);
-          return textResult({
-            error: `Description overlaps with existing active skill "${bestMatch.skill.name}" (Jaccard ${bestMatch.score.toFixed(2)}, threshold ${DESCRIPTION_DUPLICATE_THRESHOLD}). Do not create a duplicate. Either evolve the existing skill by writing to its name ("${bestMatch.skill.name}"), or reframe this skill so its description describes a distinct procedure.`,
-            overlapping_skill: {
-              id: bestMatch.skill.id,
-              name: bestMatch.skill.name,
-              description: bestMatch.skill.description,
-              path: bestMatch.skill.path
-            },
-            similarity: bestMatch.score
-          });
-        }
+      const dedupError = checkDedupGates({
+        candidate_id: args.candidate_id,
+        name: args.name,
+        description: args.description
+      });
+      if (dedupError) {
+        recordTurn("vault_write_skill", args);
+        return textResult(dedupError);
       }
+      const existing = getSkillRecordByName(args.name);
       const root = projectRoot ?? process.cwd();
-      const skillDir = resolve(root, ".agents", "skills", args.name);
-      const skillPath = resolve(skillDir, "SKILL.md");
+      const skillPath = resolve(root, ".agents", "skills", args.name, "SKILL.md");
       if (existsSync(skillPath)) {
         const existingContent = readFileSync(skillPath, "utf-8");
         const violations = checkFrontmatterPreservation(existingContent, args.content);
@@ -1088,114 +1274,95 @@ function createSkillTools(deps) {
           });
         }
       }
-      const skillDirPreexisted = existsSync(skillDir);
-      let priorSkillContent = null;
-      if (existsSync(skillPath)) {
-        try {
-          priorSkillContent = readFileSync(skillPath, "utf-8");
-        } catch {
-          priorSkillContent = null;
+      if (!existing) {
+        if (args.candidate_id) {
+          const candidateError = requireApprovedCandidate(args.candidate_id);
+          if (candidateError) {
+            recordTurn("vault_write_skill", args);
+            return textResult(candidateError);
+          }
         }
+        const linkCandidate = (recordId2, now2) => {
+          if (!args.candidate_id) return;
+          const exact = updateCandidate(args.candidate_id, {
+            status: CANDIDATE_STATUS.GENERATED,
+            skill_id: recordId2,
+            updated_at: now2
+          });
+          if (exact) return;
+          const approvedCandidates = listCandidates({ status: CANDIDATE_STATUS.APPROVED, limit: 10 });
+          const prefixMatch = approvedCandidates.find((c) => c.id.startsWith(args.candidate_id));
+          if (prefixMatch) {
+            updateCandidate(prefixMatch.id, {
+              status: CANDIDATE_STATUS.GENERATED,
+              skill_id: recordId2,
+              updated_at: now2
+            });
+          }
+        };
+        const result = await promoteNewSkill({
+          name: args.name,
+          display_name: args.display_name,
+          description: args.description,
+          content: args.content,
+          source_ids: args.source_ids,
+          candidate_id: args.candidate_id,
+          rationale: args.rationale,
+          linkCandidate,
+          label: "vault_write_skill"
+        });
+        recordTurn("vault_write_skill", args);
+        if ("error" in result) return textResult(result);
+        emitSkillNotification("created", {
+          name: result.name,
+          display_name: args.display_name,
+          description: args.description,
+          recordId: result.id,
+          generation: result.generation
+        });
+        return textResult(result);
       }
+      const priorSkillContent = readFileSync(skillPath, "utf-8");
       try {
-        mkdirSync(skillDir, { recursive: true });
         writeFileSync(skillPath, args.content, "utf-8");
       } catch (err) {
         return textResult({ error: `Failed to write skill file: ${err instanceof Error ? err.message : String(err)}` });
       }
       try {
-        const { syncSkillSymlinks } = await import("./installer-BTUNKWOU.js");
+        const { syncSkillSymlinks } = await import("./installer-AARSFXI6.js");
         syncSkillSymlinks(root, args.name);
       } catch (err) {
         console.warn("[vault_write_skill] syncSkillSymlinks failed:", err instanceof Error ? err.message : err);
       }
       const now = epochSeconds();
       const relativePath = `.agents/skills/${args.name}/SKILL.md`;
-      const existing = getSkillRecordByName(args.name);
-      let recordId = "";
-      let generation = 0;
+      const generation = existing.generation + 1;
+      const recordId = existing.id;
       const txDb = getDatabase();
       try {
         txDb.transaction(() => {
-          if (existing) {
-            generation = existing.generation + 1;
-            recordId = existing.id;
-            updateSkillRecord(existing.id, {
-              display_name: args.display_name,
-              description: args.description,
-              generation,
-              ...args.source_ids !== void 0 ? { source_ids: args.source_ids } : {},
-              path: relativePath,
-              updated_at: now
-            });
-            insertLineage({
-              id: crypto2.randomUUID(),
-              skill_id: existing.id,
-              generation,
-              action: "updated",
-              rationale: args.rationale ?? "Skill content updated",
-              source_ids_added: args.source_ids,
-              content_snapshot: args.content,
-              created_at: now
-            });
-          } else {
-            recordId = crypto2.randomUUID();
-            generation = 1;
-            insertSkillRecord({
-              id: recordId,
-              agent_id: agentId,
-              machine_id: machineId,
-              name: args.name,
-              display_name: args.display_name,
-              description: args.description,
-              candidate_id: args.candidate_id ?? null,
-              source_ids: args.source_ids,
-              path: relativePath,
-              created_at: now,
-              updated_at: now
-            });
-            insertLineage({
-              id: crypto2.randomUUID(),
-              skill_id: recordId,
-              generation,
-              action: "created",
-              rationale: args.rationale ?? "Initial skill creation",
-              source_ids_added: args.source_ids,
-              content_snapshot: args.content,
-              created_at: now
-            });
-            const approvedCandidates = listCandidates({ status: "approved", limit: 10 });
-            let linkedCandidate = false;
-            if (args.candidate_id && !linkedCandidate) {
-              const exact = updateCandidate(args.candidate_id, {
-                status: "generated",
-                skill_id: recordId,
-                updated_at: now
-              });
-              if (exact) linkedCandidate = true;
-            }
-            if (args.candidate_id && !linkedCandidate) {
-              const prefixMatch = approvedCandidates.find((c) => c.id.startsWith(args.candidate_id));
-              if (prefixMatch) {
-                updateCandidate(prefixMatch.id, {
-                  status: "generated",
-                  skill_id: recordId,
-                  updated_at: now
-                });
-                linkedCandidate = true;
-              }
-            }
-          }
+          updateSkillRecord(existing.id, {
+            display_name: args.display_name,
+            description: args.description,
+            generation,
+            ...args.source_ids !== void 0 ? { source_ids: args.source_ids } : {},
+            path: relativePath,
+            updated_at: now
+          });
+          insertLineage({
+            id: crypto2.randomUUID(),
+            skill_id: existing.id,
+            generation,
+            action: "updated",
+            rationale: args.rationale ?? "Skill content updated",
+            source_ids_added: args.source_ids,
+            content_snapshot: args.content,
+            created_at: now
+          });
         })();
       } catch (err) {
         try {
-          if (priorSkillContent !== null) {
-            writeFileSync(skillPath, priorSkillContent, "utf-8");
-          } else if (!skillDirPreexisted) {
-            rmSync(skillDir, { recursive: true, force: true });
-          } else {
-            rmSync(skillPath, { force: true });
-          }
+          writeFileSync(skillPath, priorSkillContent, "utf-8");
         } catch (rollbackErr) {
           console.warn(
             "[vault_write_skill] file rollback after DB failure also failed:",
@@ -1207,14 +1374,12 @@ function createSkillTools(deps) {
           error: `Skill write aborted: database transaction failed and on-disk state was rolled back. ${err instanceof Error ? err.message : String(err)}`
         });
       }
-      const isNew = generation === 1;
-      notify(vaultDir, {
-        domain: "skills",
-        type: isNew ? "skill.created" : "skill.evolved",
-        title: isNew ? `Skill created: ${args.display_name}` : `Skill evolved: ${args.display_name}`,
-        message: args.description.slice(0, 120),
-        link: `/skills?skill=${encodeURIComponent(args.name)}`,
-        metadata: { skillId: recordId, name: args.name, generation }
+      emitSkillNotification("evolved", {
+        name: args.name,
+        display_name: args.display_name,
+        description: args.description,
+        recordId,
+        generation
       });
       recordTurn("vault_write_skill", args);
       return textResult({
@@ -1226,10 +1391,145 @@ function createSkillTools(deps) {
     },
     { annotations: { openWorldHint: true } }
   );
+  const vaultStageSkill = tool4(
+    "vault_stage_skill",
+    "Stage a provisional SKILL.md under .myco/staging/skills/<candidate_id>/ for later promotion by vault_finalize_skill. Use this from the skill-generate draft phase. The write is NOT live \u2014 the skill does not appear under .agents/skills/ and no DB rows are created until vault_finalize_skill is called with the same candidate_id.",
+    {
+      candidate_id: external_exports.string().describe(
+        "Candidate ID from the instruction. Required \u2014 staging is keyed by candidate so the validate phase (and on-failure cleanup) can find the staged content."
+      ),
+      name: external_exports.string().describe("Final skill directory name (kebab-case, no colon). Stored in the manifest for finalize."),
+      display_name: external_exports.string().describe("Human-readable display name"),
+      description: external_exports.string().describe("Short description \u2014 used for the dedup gate and the final skill record"),
+      content: external_exports.string().describe("Full SKILL.md content in markdown including frontmatter"),
+      source_ids: external_exports.string().optional().describe("JSON array of source spore/entity IDs"),
+      rationale: external_exports.string().optional().describe("Why this skill is being created \u2014 stored in lineage after finalize")
+    },
+    async (args) => {
+      recordTurn("vault_stage_skill", args);
+      if (!vaultDir) {
+        return textResult({
+          error: "vault_stage_skill requires vaultDir on the tool deps \u2014 staging has no location otherwise"
+        });
+      }
+      const validationErrors = validateSkillContent(args.content, args.name);
+      if (validationErrors.length > 0) {
+        return textResult({
+          error: "Skill validation failed. Fix these issues and re-stage.",
+          issues: validationErrors
+        });
+      }
+      if (!args.name || /[/\\]|\.\./.test(args.name)) {
+        return textResult({
+          error: 'Invalid skill name: must be a simple directory name without path separators or ".."'
+        });
+      }
+      const candidateError = requireApprovedCandidate(args.candidate_id);
+      if (candidateError) return textResult(candidateError);
+      const dedupError = checkDedupGates({
+        candidate_id: args.candidate_id,
+        name: args.name,
+        description: args.description,
+        rejectSameName: true
+      });
+      if (dedupError) return textResult(dedupError);
+      let stagingFilePath;
+      try {
+        stagingFilePath = writeStagedSkill(vaultDir, args.candidate_id, args.content);
+        const manifest = {
+          candidate_id: args.candidate_id,
+          name: args.name,
+          display_name: args.display_name,
+          description: args.description,
+          source_ids: args.source_ids ?? "[]",
+          rationale: args.rationale ?? "Initial draft"
+        };
+        writeStagedManifest(vaultDir, args.candidate_id, manifest);
+      } catch (err) {
+        return textResult({
+          error: `Failed to write staged skill: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      return textResult({
+        candidate_id: args.candidate_id,
+        staging_path: stagingFilePath,
+        status: "staged"
+      });
+    },
+    { annotations: { openWorldHint: true } }
+  );
+  const vaultFinalizeSkill = tool4(
+    "vault_finalize_skill",
+    "Promote a staged skill to live at .agents/skills/<name>/ and insert the skill_records / lineage rows. Call this from skill-generate validate phase after your quality checks pass. Requires vault_stage_skill to have been called earlier with the same candidate_id; reads the staged SKILL.md + manifest rather than taking duplicate metadata.",
+    {
+      candidate_id: external_exports.string().describe("Candidate ID whose staged skill should be promoted. Must match a previous vault_stage_skill call.")
+    },
+    async (args) => {
+      recordTurn("vault_finalize_skill", args);
+      if (!vaultDir) {
+        return textResult({
+          error: "vault_finalize_skill requires vaultDir on the tool deps"
+        });
+      }
+      const stagedContent = readStagedSkill(vaultDir, args.candidate_id);
+      const manifest = readStagedManifest(vaultDir, args.candidate_id);
+      if (!stagedContent || !manifest) {
+        return textResult({
+          error: `No staged skill found for candidate ${args.candidate_id}. Call vault_stage_skill first.`
+        });
+      }
+      const candidateError = requireApprovedCandidate(args.candidate_id);
+      if (candidateError) return textResult(candidateError);
+      const validationErrors = validateSkillContent(stagedContent, manifest.name);
+      if (validationErrors.length > 0) {
+        return textResult({
+          error: "Staged skill failed validation on finalize. Re-stage with valid content.",
+          issues: validationErrors
+        });
+      }
+      const dedupError = checkDedupGates({
+        candidate_id: args.candidate_id,
+        name: manifest.name,
+        description: manifest.description,
+        rejectSameName: true
+      });
+      if (dedupError) return textResult(dedupError);
+      const result = await promoteNewSkill({
+        name: manifest.name,
+        display_name: manifest.display_name,
+        description: manifest.description,
+        content: stagedContent,
+        source_ids: manifest.source_ids,
+        candidate_id: manifest.candidate_id,
+        rationale: manifest.rationale,
+        linkCandidate: (recordId, now) => {
+          updateCandidate(manifest.candidate_id, {
+            status: CANDIDATE_STATUS.GENERATED,
+            skill_id: recordId,
+            updated_at: now
+          });
+        },
+        label: "vault_finalize_skill"
+      });
+      if ("error" in result) return textResult(result);
+      cleanupStagedSkill(vaultDir, args.candidate_id);
+      emitSkillNotification("created", {
+        name: manifest.name,
+        display_name: manifest.display_name,
+        description: manifest.description,
+        recordId: result.id,
+        generation: result.generation
+      });
+      return textResult(result);
+    },
+    { annotations: { openWorldHint: true } }
+  );
   return [
     vaultSkillCandidates,
     vaultSkillRecords,
-    vaultWriteSkill
+    vaultWriteSkill,
+    vaultStageSkill,
+    vaultFinalizeSkill
   ];
 }
 
@@ -1259,8 +1559,11 @@ var OBSERVABILITY_TOOL_NAMES = /* @__PURE__ */ new Set(["vault_report"]);
 var SKILL_TOOL_NAMES = /* @__PURE__ */ new Set([
   "vault_skill_candidates",
   "vault_skill_records",
-  "vault_write_skill"
+  "vault_write_skill",
+  "vault_stage_skill",
+  "vault_finalize_skill"
 ]);
+var VAULT_TOOL_COUNT = READ_TOOL_NAMES.size + WRITE_TOOL_NAMES.size + OBSERVABILITY_TOOL_NAMES.size + SKILL_TOOL_NAMES.size;
 function setsOverlap(a, b) {
   for (const item of a) {
     if (b.has(item)) return true;
@@ -2233,6 +2536,17 @@ async function runAgent(vaultDir, options) {
       tokensUsed = result.tokensUsed;
       costUsd = result.costUsd;
       phaseResults = result.phases;
+      const requiredPhaseNames = new Set(
+        config.phases.filter((p) => p.required).map((p) => p.name)
+      );
+      const failedRequired = phaseResults.find(
+        (p) => p.status === "failed" && requiredPhaseNames.has(p.name)
+      );
+      if (failedRequired) {
+        throw new Error(
+          `Required phase "${failedRequired.name}" failed: ${failedRequired.summary}`
+        );
+      }
     } else {
       const taskPrompt = composeTaskPrompt(
         vaultContext,
@@ -2298,6 +2612,11 @@ ${err.stack.split("\n").slice(0, 3).join("\n")}`;
     } catch (dbErr) {
       console.error(`[agent] Failed to save error to DB:`, dbErr);
     }
+    await cleanupOnTaskFailure({
+      taskName: config.taskName,
+      vaultDir,
+      runContext: options?.runContext
+    });
     return {
       runId,
       status: STATUS_FAILED,
@@ -2306,10 +2625,29 @@ ${err.stack.split("\n").slice(0, 3).join("\n")}`;
     };
   }
 }
+async function cleanupOnTaskFailure(args) {
+  if (args.taskName !== SKILL_GENERATE_TASK) return;
+  if (!args.vaultDir) return;
+  const candidateId = args.runContext?.candidate_id;
+  if (!candidateId) return;
+  try {
+    const { cleanupStagedSkill: cleanupStagedSkill2 } = await import("./skill-staging-SWM7UC5D.js");
+    cleanupStagedSkill2(args.vaultDir, candidateId);
+    console.warn(
+      `[agent] skill-generate failed \u2014 cleaned up staging for candidate ${candidateId}`
+    );
+  } catch (cleanupErr) {
+    console.warn(
+      `[agent] Failed to clean staging for candidate ${candidateId}:`,
+      cleanupErr instanceof Error ? cleanupErr.message : cleanupErr
+    );
+  }
+}
 export {
+  cleanupOnTaskFailure,
   composePhasePrompt,
   composeTaskPrompt,
   computeWaves,
   runAgent
 };
-//# sourceMappingURL=executor-4OXDK4ZA.js.map
+//# sourceMappingURL=executor-PUKL76TU.js.map