zelari-code 0.7.5 → 0.7.9

package/dist/cli/workspace/stubs.js

@@ -1,21 +1,22 @@
 /**
  * workspace/stubs.ts — CLI workspace tool stubs.
  *
- * Implements the 9 council workspace tools (`createPhase`, `createTask`,
- * `updateTask`, `addIdea`, `createMilestone`, `createDocument`,
- * `searchDocuments`, `linkDocuments`, `getDocumentBacklinks`) as
- * filesystem-backed stubs that persist to `.zelari/` at the project root.
+ * Implements the 10 council workspace tools (`createPlan`, `createPhase`,
+ * `createTask`, `updateTask`, `addIdea`, `createMilestone`,
+ * `createDocument`, `searchDocuments`, `linkDocuments`,
+ * `getDocumentBacklinks`) as filesystem-backed stubs that persist to
+ * `.zelari/` at the project root.
  *
  * Replaces the AnathemaBrain Electron-only ctx (e.g. `ctx.addIdea(...)`)
  * with a `WorkspaceContext` that writes Markdown + YAML frontmatter files.
  *
  * @see docs/plans/2026-07-01-council-workspace-cli-stubs.md
  */
-import { existsSync, readdirSync, writeFileSync, readFileSync, mkdirSync, renameSync } from 'node:fs';
-import { join, basename, dirname, relative } from 'node:path';
-import { workspaceMutex } from './storage.js';
-import { resolveWorkspaceRoot, workspaceFile, workspaceArtifact, projectName as deriveProjectName, } from './paths.js';
-import { Storage } from './storage.js';
+import { existsSync, readdirSync, writeFileSync, readFileSync, mkdirSync, renameSync, } from "node:fs";
+import { join, basename, dirname, relative } from "node:path";
+import { workspaceMutex } from "./storage.js";
+import { resolveWorkspaceRoot, workspaceFile, workspaceArtifact, projectName as deriveProjectName, } from "./paths.js";
+import { Storage } from "./storage.js";
 // ── Context factory ───────────────────────────────────────────────────
 /**
  * Build a WorkspaceContext rooted at the project's `.zelari/` directory.
@@ -31,7 +32,7 @@ export function createWorkspaceContext(projectRoot = process.cwd()) {
 }
 /** Path of the machine-readable plan store (source of truth since v0.7.3). */
 function planJsonPath(ctx) {
-    return join(ctx.rootDir, 'plan.json');
+    return join(ctx.rootDir, "plan.json");
 }
 function readPlan(ctx) {
     // v0.7.3: the plan's source of truth is plan.json. The previous
@@ -44,7 +45,7 @@ function readPlan(ctx) {
     const jsonPath = planJsonPath(ctx);
     if (existsSync(jsonPath)) {
         try {
-            const parsed = JSON.parse(readFileSync(jsonPath, 'utf8'));
+            const parsed = JSON.parse(readFileSync(jsonPath, "utf8"));
             return {
                 phases: Array.isArray(parsed.phases) ? parsed.phases : [],
                 tasks: Array.isArray(parsed.tasks) ? parsed.tasks : [],
@@ -57,7 +58,7 @@ function readPlan(ctx) {
     }
     // Legacy migration: one best-effort parse of the old plan.md frontmatter
     // (pre-v0.7.3 files). The next writePlan persists it as plan.json.
-    const path = workspaceFile(ctx.rootDir, 'plan');
+    const path = workspaceFile(ctx.rootDir, "plan");
     const doc = ctx.storage.readIfExists(path);
     if (!doc)
         return { phases: [], tasks: [], milestones: [] };
@@ -77,13 +78,13 @@ function readPlan(ctx) {
 function writePlan(ctx, summary) {
     const jsonPath = planJsonPath(ctx);
     mkdirSync(dirname(jsonPath), { recursive: true });
-    const tmp = jsonPath + '.tmp-' + process.pid;
-    writeFileSync(tmp, JSON.stringify(summary, null, 2), 'utf8');
+    const tmp = jsonPath + ".tmp-" + process.pid;
+    writeFileSync(tmp, JSON.stringify(summary, null, 2), "utf8");
     renameSync(tmp, jsonPath);
-    const mdPath = workspaceFile(ctx.rootDir, 'plan');
+    const mdPath = workspaceFile(ctx.rootDir, "plan");
     const summaryMeta = {
-        kind: 'plan-summary',
-        id: '_plan',
+        kind: "plan-summary",
+        id: "_plan",
         updatedAt: new Date().toISOString(),
     };
     ctx.storage.write(mdPath, summaryMeta, renderPlanBody(summary));
@@ -92,77 +93,195 @@ function writePlan(ctx, summary) {
 function renderPlanBody(summary) {
     const lines = [];
     lines.push(`# Execution Plan`);
-    lines.push('');
+    lines.push("");
     lines.push(`> Auto-generated by Zelari Code council. Do not edit by hand.`);
-    lines.push('');
+    lines.push("");
     // Phases
     lines.push(`## Phases`);
-    lines.push('');
+    lines.push("");
     if (summary.phases.length === 0) {
         lines.push(`_(none yet)_`);
     }
     else {
         for (const phase of [...summary.phases].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))) {
-            lines.push(`### ${phase.order ?? '?'}. ${phase.id} \`${phase.color ?? ''}\``);
-            lines.push('');
+            lines.push(`### ${phase.order ?? "?"}. ${phase.id} \`${phase.color ?? ""}\``);
+            lines.push("");
         }
     }
-    lines.push('');
+    lines.push("");
     // Tasks grouped by phase
     lines.push(`## Tasks`);
-    lines.push('');
+    lines.push("");
     if (summary.tasks.length === 0) {
         lines.push(`_(none yet)_`);
     }
     else {
         const byPhase = new Map();
         for (const task of summary.tasks) {
-            const pid = task.phaseId ?? '_unassigned';
+            const pid = task.phaseId ?? "_unassigned";
             if (!byPhase.has(pid))
                 byPhase.set(pid, []);
             byPhase.get(pid).push(task);
         }
         for (const [phaseId, tasks] of byPhase) {
             lines.push(`### Phase: \`${phaseId}\``);
-            lines.push('');
+            lines.push("");
             for (const t of tasks) {
-                const status = t.status ?? 'pending';
-                const pri = t.priority ?? 'medium';
+                const status = t.status ?? "pending";
+                const pri = t.priority ?? "medium";
                 lines.push(`- [ ] **${t.id}** _(${status}, ${pri})_`);
             }
-            lines.push('');
+            lines.push("");
         }
     }
-    lines.push('');
+    lines.push("");
     // Milestones
     lines.push(`## Milestones`);
-    lines.push('');
+    lines.push("");
     if (summary.milestones.length === 0) {
         lines.push(`_(none yet)_`);
     }
     else {
         for (const m of summary.milestones) {
-            lines.push(`- **${m.id}** → ${m.targetVersion ?? '?'}`);
+            lines.push(`- **${m.id}** → ${m.targetVersion ?? "?"}`);
         }
     }
-    lines.push('');
-    return lines.join('\n');
+    lines.push("");
+    return lines.join("\n");
 }
 // ── ADR (decisions/) helpers ──────────────────────────────────────────
 function nextAdrId(ctx) {
-    const decisionsDir = join(ctx.rootDir, 'decisions');
+    const decisionsDir = join(ctx.rootDir, "decisions");
     if (!existsSync(decisionsDir))
-        return '001';
+        return "001";
     const existing = readdirSync(decisionsDir)
-        .filter((f) => f.endsWith('.md'))
+        .filter((f) => f.endsWith(".md"))
         .map((f) => f.match(/^(\d+)-/))
         .filter((m) => !!m)
         .map((m) => parseInt(m[1], 10));
     const max = existing.length === 0 ? 0 : Math.max(...existing);
-    return String(max + 1).padStart(3, '0');
+    return String(max + 1).padStart(3, "0");
 }
 function slugify(s) {
-    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60);
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 60);
+}
+/** Add a phase record. Returns the phase id and whether it was newly created. */
+function addPhaseRecord(summary, input) {
+    const id = slugify(input.name) || `phase-${input.order}`;
+    if (summary.phases.some((p) => p.id === id)) {
+        return { id, created: false };
+    }
+    summary.phases.push({
+        kind: "phase",
+        id,
+        name: input.name,
+        description: input.description,
+        order: input.order,
+        color: input.color,
+    });
+    return { id, created: true };
+}
+/**
+ * Add a task record + its per-task file. With `dedupe: true` a task whose
+ * title already exists in the same phase is treated as the same task and
+ * NOT re-added (protects the createPlan batch path from duplicating tasks
+ * that a partial itemized run already persisted). The itemized createTask
+ * stub keeps `dedupe: false` for backward compatibility.
+ */
+function addTaskRecord(ctx, summary, phaseId, t, options) {
+    const slug = slugify(t.title);
+    if (options.dedupe) {
+        const existing = summary.tasks.find((k) => k.phaseId === phaseId &&
+            k.id.replace(/-\d+$/, "") === `${phaseId}-${slug}`);
+        if (existing)
+            return { id: existing.id, created: false };
+    }
+    const id = `${phaseId}-${slug}-${summary.tasks.filter((k) => k.phaseId === phaseId).length + 1}`;
+    summary.tasks.push({
+        kind: "task",
+        id,
+        // v0.7.3: keep the human-readable title in plan.json so
+        // buildPlanSummary can render it in the system prompt.
+        name: t.title,
+        phaseId,
+        status: "pending",
+        priority: t.priority,
+    });
+    const taskPath = join(ctx.rootDir, "plan-tasks", `${id}.md`);
+    const meta = {
+        kind: "task",
+        id,
+        phaseId,
+        status: "pending",
+        priority: t.priority,
+        tags: t.fileRefs,
+    };
+    const body = [
+        `# ${t.title}`,
+        "",
+        t.description,
+        "",
+        `## File references`,
+        ...t.fileRefs.map((f) => `- \`${f}\``),
+        "",
+        `## Acceptance criteria`,
+        ...t.acceptance.map((a) => `- ${a}`),
+        "",
+        `## QA scenario`,
+        "",
+        t.qaScenario || "_(not specified)_",
+        "",
+    ].join("\n");
+    ctx.storage.write(taskPath, meta, body);
+    return { id, created: true };
+}
+/** Add a milestone record + its file. Returns id and whether newly created. */
+function addMilestoneRecord(ctx, summary, input) {
+    const id = `m-${slugify(input.title)}`;
+    if (summary.milestones.some((m) => m.id === id)) {
+        return { id, created: false };
+    }
+    const version = input.targetVersion ?? input.dueDate ?? "TBD";
+    summary.milestones.push({
+        kind: "milestone",
+        id,
+        name: input.title,
+        description: input.description,
+        dueDate: input.dueDate,
+        targetVersion: version,
+    });
+    const path = join(ctx.rootDir, "milestones", `${id}.md`);
+    const meta = {
+        kind: "milestone",
+        id,
+        name: input.title,
+        description: input.description,
+        dueDate: input.dueDate,
+        targetVersion: version,
+    };
+    const body = [
+        `# Milestone: ${input.title}`,
+        "",
+        input.description,
+        "",
+        `Target version: ${version}`,
+        "",
+    ].join("\n");
+    ctx.storage.write(path, meta, body);
+    return { id, created: true };
+}
+/**
+ * Read-only view of the current plan (phases + tasks + milestones).
+ * Exported for the built-in complete-design fallback (completeDesign.ts)
+ * so it can inspect per-phase task coverage without duplicating the
+ * plan.json / legacy plan.md read logic.
+ */
+export function readPlanSummary(ctx) {
+    return readPlan(ctx);
 }
 // ── Stub factory ─────────────────────────────────────────────────────
 /**
@@ -173,6 +292,7 @@ function slugify(s) {
  */
 export function createWorkspaceStubs(ctx) {
     return [
+        createPlanStub(ctx),
         createPhaseStub(ctx),
         createTaskStub(ctx),
         updateTaskStub(ctx),
@@ -185,32 +305,106 @@ export function createWorkspaceStubs(ctx) {
     ];
 }
 // ── Individual stubs ──────────────────────────────────────────────────
-function createPhaseStub(ctx) {
+/**
+ * v0.7.8 — Batch plan creation. One tool call persists the WHOLE plan:
+ * every phase, the tasks nested under each phase, and the milestone.
+ *
+ * Rationale: the itemized contract (4×createPhase + 12×createTask +
+ * 1×createMilestone = 17 sequential tool calls) exceeds what mid-tier
+ * council models reliably emit in one turn (composer-2.5 persisted ≤7 of
+ * 17 in the 2026-07-03 live tests, see HANDOFF.md). A single structured
+ * call collapses the whole contract into one emission, which the same
+ * models satisfy reliably (proven by the 1-call retry paths of Minosse
+ * and Lucifero).
+ */
+function createPlanStub(ctx) {
     return {
-        name: 'createPhase',
-        description: 'Create a new execution phase in the project plan. Each phase is a milestone toward shipping a feature.',
-        category: 'project',
+        name: "createPlan",
+        description: "Create the FULL project plan in one call: all phases, the tasks nested under each phase, and the target milestone. " +
+            "Preferred over itemized createPhase/createTask/createMilestone calls — one createPlan call persists everything atomically.",
+        category: "project",
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
-                const name = args['name'] ?? 'New Phase';
-                const description = args['description'] ?? '';
-                const order = args['order'] ?? 0;
-                const color = args['color'] ?? '#3b82f6';
-                const id = slugify(name) || `phase-${order}`;
+                const rawPhases = Array.isArray(args["phases"])
+                    ? args["phases"]
+                    : [];
+                if (rawPhases.length === 0) {
+                    return 'createPlan requires a non-empty "phases" array (each phase: { name, description, order, color, tasks: [{ title, description, fileRefs, acceptance, qaScenario, priority }] }).';
+                }
                 const summary = readPlan(ctx);
-                // Check uniqueness
-                if (summary.phases.some((p) => p.id === id)) {
-                    return `Phase "${id}" already exists.`;
+                let phasesCreated = 0;
+                let tasksCreated = 0;
+                const phaseIds = [];
+                rawPhases.forEach((rawPhase, idx) => {
+                    const { id: phaseId, created } = addPhaseRecord(summary, {
+                        name: rawPhase["name"] ?? `Phase ${idx + 1}`,
+                        description: rawPhase["description"] ?? "",
+                        order: rawPhase["order"] ?? idx + 1,
+                        color: rawPhase["color"] ?? "#3b82f6",
+                    });
+                    if (created)
+                        phasesCreated += 1;
+                    phaseIds.push(phaseId);
+                    const rawTasks = Array.isArray(rawPhase["tasks"])
+                        ? rawPhase["tasks"]
+                        : [];
+                    for (const rawTask of rawTasks) {
+                        const { created: taskCreated } = addTaskRecord(ctx, summary, phaseId, {
+                            title: rawTask["title"] ?? "New Task",
+                            description: rawTask["description"] ?? "",
+                            fileRefs: rawTask["fileRefs"] ??
+                                rawTask["files"] ??
+                                [],
+                            acceptance: rawTask["acceptance"] ?? [],
+                            qaScenario: rawTask["qaScenario"] ??
+                                rawTask["qa"] ??
+                                "",
+                            priority: (rawTask["priority"] ??
+                                "medium"),
+                        }, { dedupe: true });
+                        if (taskCreated)
+                            tasksCreated += 1;
+                    }
+                });
+                let milestonesCreated = 0;
+                const rawMilestone = args["milestone"];
+                if (rawMilestone && typeof rawMilestone === "object") {
+                    const { created } = addMilestoneRecord(ctx, summary, {
+                        title: rawMilestone["title"] ?? "v0.1.0 design-complete",
+                        description: rawMilestone["description"] ?? "",
+                        dueDate: rawMilestone["dueDate"],
+                        targetVersion: rawMilestone["targetVersion"],
+                    });
+                    if (created)
+                        milestonesCreated += 1;
                 }
-                summary.phases.push({
-                    kind: 'phase',
-                    id,
+                writePlan(ctx, summary);
+                return `Plan created: ${phasesCreated} phases, ${tasksCreated} tasks, ${milestonesCreated} milestone(s). Phase ids: ${phaseIds.join(", ")}.`;
+            });
+        },
+    };
+}
+function createPhaseStub(ctx) {
+    return {
+        name: "createPhase",
+        description: "Create a new execution phase in the project plan. Each phase is a milestone toward shipping a feature.",
+        category: "project",
+        parameters: [],
+        execute: async (args) => {
+            return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
+                const name = args["name"] ?? "New Phase";
+                const order = args["order"] ?? 0;
+                const summary = readPlan(ctx);
+                const { id, created } = addPhaseRecord(summary, {
                     name,
-                    description,
+                    description: args["description"] ?? "",
                     order,
-                    color,
+                    color: args["color"] ?? "#3b82f6",
                 });
+                if (!created) {
+                    return `Phase "${id}" already exists.`;
+                }
                 writePlan(ctx, summary);
                 return `Phase "${name}" created (id: ${id}, order: ${order}).`;
             });
@@ -219,64 +413,32 @@ function createPhaseStub(ctx) {
 }
 function createTaskStub(ctx) {
     return {
-        name: 'createTask',
-        description: 'Create a task within an existing phase. Tasks have file references, acceptance criteria, and a QA scenario.',
-        category: 'project',
+        name: "createTask",
+        description: "Create a task within an existing phase. Tasks have file references, acceptance criteria, and a QA scenario.",
+        category: "project",
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
-                const phaseId = args['phaseId'] ?? args['phase'];
-                const title = args['title'] ?? 'New Task';
-                const description = args['description'] ?? '';
-                const fileRefs = args['fileRefs'] ?? args['files'] ?? [];
-                const acceptance = args['acceptance'] ?? [];
-                const qaScenario = args['qaScenario'] ?? args['qa'] ?? '';
-                const priority = args['priority'] ?? 'medium';
+                const phaseId = args["phaseId"] ?? args["phase"];
+                const title = args["title"] ?? "New Task";
                 if (!phaseId)
-                    return 'Task requires a phaseId.';
+                    return "Task requires a phaseId.";
                 const summary = readPlan(ctx);
                 if (!summary.phases.some((p) => p.id === phaseId)) {
                     return `Phase "${phaseId}" not found. Create it first via /createPhase.`;
                 }
-                const id = `${phaseId}-${slugify(title)}-${summary.tasks.filter((t) => t.phaseId === phaseId).length + 1}`;
-                summary.tasks.push({
-                    kind: 'task',
-                    id,
-                    // v0.7.3: keep the human-readable title in plan.json so
-                    // buildPlanSummary can render it in the system prompt.
-                    name: title,
-                    phaseId,
-                    status: 'pending',
-                    priority: priority,
-                });
+                const { id } = addTaskRecord(ctx, summary, phaseId, {
+                    title,
+                    description: args["description"] ?? "",
+                    fileRefs: args["fileRefs"] ??
+                        args["files"] ??
+                        [],
+                    acceptance: args["acceptance"] ?? [],
+                    qaScenario: args["qaScenario"] ?? args["qa"] ?? "",
+                    priority: (args["priority"] ??
+                        "medium"),
+                }, { dedupe: false });
                 writePlan(ctx, summary);
-                // Also write the task body to a per-task file so it doesn't get lost
-                const taskPath = join(ctx.rootDir, 'plan-tasks', `${id}.md`);
-                const meta = {
-                    kind: 'task',
-                    id,
-                    phaseId,
-                    status: 'pending',
-                    priority: priority,
-                    tags: fileRefs,
-                };
-                const body = [
-                    `# ${title}`,
-                    '',
-                    description,
-                    '',
-                    `## File references`,
-                    ...fileRefs.map((f) => `- \`${f}\``),
-                    '',
-                    `## Acceptance criteria`,
-                    ...acceptance.map((a) => `- ${a}`),
-                    '',
-                    `## QA scenario`,
-                    '',
-                    qaScenario || '_(not specified)_',
-                    '',
-                ].join('\n');
-                ctx.storage.write(taskPath, meta, body);
                 return `Task "${title}" created (id: ${id}) under phase "${phaseId}".`;
             });
         },
@@ -284,28 +446,44 @@ function createTaskStub(ctx) {
 }
 function updateTaskStub(ctx) {
     return {
-        name: 'updateTask',
-        description: 'Update a task\'s status (pending|in_progress|done|blocked).',
-        category: 'project',
+        name: "updateTask",
+        description: "Update a task's status (pending|in_progress|done|blocked).",
+        category: "project",
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
-                const taskId = args['taskId'];
-                const rawStatus = args['status'];
+                const taskId = args["taskId"];
+                const rawStatus = args["status"];
                 if (!taskId || !rawStatus)
-                    return 'updateTask requires taskId and status.';
-                const valid = ['pending', 'in_progress', 'done', 'blocked'];
+                    return "updateTask requires taskId and status.";
+                const valid = ["pending", "in_progress", "done", "blocked"];
                 // v0.7.3: models routinely use kanban vocabulary ("todo", "completed")
                 // — map the common synonyms instead of erroring on each attempt.
                 const aliases = {
-                    'todo': 'pending', 'to-do': 'pending', 'open': 'pending', 'backlog': 'pending',
-                    'in-progress': 'in_progress', 'in progress': 'in_progress', 'doing': 'in_progress', 'started': 'in_progress', 'active': 'in_progress',
-                    'complete': 'done', 'completed': 'done', 'finished': 'done', 'closed': 'done', 'resolved': 'done',
-                    'stuck': 'blocked', 'waiting': 'blocked', 'on-hold': 'blocked', 'on hold': 'blocked',
+                    todo: "pending",
+                    "to-do": "pending",
+                    open: "pending",
+                    backlog: "pending",
+                    "in-progress": "in_progress",
+                    "in progress": "in_progress",
+                    doing: "in_progress",
+                    started: "in_progress",
+                    active: "in_progress",
+                    complete: "done",
+                    completed: "done",
+                    finished: "done",
+                    closed: "done",
+                    resolved: "done",
+                    stuck: "blocked",
+                    waiting: "blocked",
+                    "on-hold": "blocked",
+                    "on hold": "blocked",
                 };
-                const status = valid.includes(rawStatus) ? rawStatus : aliases[rawStatus.toLowerCase()];
+                const status = valid.includes(rawStatus)
+                    ? rawStatus
+                    : aliases[rawStatus.toLowerCase()];
                 if (!status)
-                    return `Invalid status: ${rawStatus}. Must be one of: ${valid.join(', ')}.`;
+                    return `Invalid status: ${rawStatus}. Must be one of: ${valid.join(", ")}.`;
                 const summary = readPlan(ctx);
                 const task = summary.tasks.find((t) => t.id === taskId);
                 if (!task)
@@ -319,45 +497,45 @@ function updateTaskStub(ctx) {
 }
 function addIdeaStub(ctx) {
     return {
-        name: 'addIdea',
-        description: 'Add an Architecture Decision Record (ADR) to the project. ADRs document the context, decision, and consequences of significant choices.',
-        category: 'project',
+        name: "addIdea",
+        description: "Add an Architecture Decision Record (ADR) to the project. ADRs document the context, decision, and consequences of significant choices.",
+        category: "project",
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:adr`, () => {
-                const title = args['title'] ?? 'New Decision';
-                const context = args['context'] ?? args['content'] ?? '';
-                const decision = args['decision'] ?? title;
-                const consequences = args['consequences'] ?? [];
-                const tags = args['tags'] ?? [];
-                const category = args['category'] ?? 'General';
+                const title = args["title"] ?? "New Decision";
+                const context = args["context"] ?? args["content"] ?? "";
+                const decision = args["decision"] ?? title;
+                const consequences = args["consequences"] ?? [];
+                const tags = args["tags"] ?? [];
+                const category = args["category"] ?? "General";
                 const id = `${nextAdrId(ctx)}-${slugify(title)}`;
-                const path = workspaceArtifact(ctx.rootDir, 'decisions', id);
+                const path = workspaceArtifact(ctx.rootDir, "decisions", id);
                 const meta = {
-                    kind: 'adr',
-                    status: 'proposed',
+                    kind: "adr",
+                    status: "proposed",
                     id,
                     date: new Date().toISOString().slice(0, 10),
                     tags,
                 };
                 const body = [
                     `# ADR ${id}: ${title}`,
-                    '',
+                    "",
                     `> Category: ${category}  ·  Status: **proposed**  ·  ${meta.date}`,
-                    '',
+                    "",
                     `## Context`,
-                    '',
+                    "",
                     context,
-                    '',
+                    "",
                     `## Decision`,
-                    '',
+                    "",
                     decision,
-                    '',
+                    "",
                     `## Consequences`,
-                    '',
+                    "",
                     ...consequences.map((c) => `- ${c}`),
-                    '',
-                ].join('\n');
+                    "",
+                ].join("\n");
                 ctx.storage.write(path, meta, body);
                 return `ADR ${id} created: "${title}". Status: proposed. Promote to accepted via /update ADR or manual edit.`;
             });
@@ -366,48 +544,24 @@ function addIdeaStub(ctx) {
 }
 function createMilestoneStub(ctx) {
     return {
-        name: 'createMilestone',
-        description: 'Create a project milestone (a code version that ships when specific acceptance criteria are met).',
-        category: 'project',
+        name: "createMilestone",
+        description: "Create a project milestone (a code version that ships when specific acceptance criteria are met).",
+        category: "project",
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
-                const title = args['title'] ?? 'New Milestone';
-                const description = args['description'] ?? '';
-                const dueDate = args['dueDate'];
-                const id = `m-${slugify(title)}`;
+                const title = args["title"] ?? "New Milestone";
                 const summary = readPlan(ctx);
-                if (summary.milestones.some((m) => m.id === id))
-                    return `Milestone "${id}" already exists.`;
-                const version = args['targetVersion'] ?? dueDate ?? 'TBD';
-                summary.milestones.push({
-                    kind: 'milestone',
-                    id,
-                    name: title,
-                    description,
-                    dueDate,
-                    targetVersion: version,
+                const { id, created } = addMilestoneRecord(ctx, summary, {
+                    title,
+                    description: args["description"] ?? "",
+                    dueDate: args["dueDate"],
+                    targetVersion: args["targetVersion"],
                 });
+                if (!created)
+                    return `Milestone "${id}" already exists.`;
                 writePlan(ctx, summary);
-                // Also write the body
-                const path = join(ctx.rootDir, 'milestones', `${id}.md`);
-                const meta = {
-                    kind: 'milestone',
-                    id,
-                    name: title,
-                    description,
-                    dueDate,
-                    targetVersion: version,
-                };
-                const body = [
-                    `# Milestone: ${title}`,
-                    '',
-                    description,
-                    '',
-                    `Target version: ${version}`,
-                    '',
-                ].join('\n');
-                ctx.storage.write(path, meta, body);
+                const version = summary.milestones.find((m) => m.id === id)?.targetVersion ?? "TBD";
                 return `Milestone "${title}" created (id: ${id}, version: ${version}).`;
             });
         },
@@ -415,25 +569,41 @@ function createMilestoneStub(ctx) {
 }
 function createDocumentStub(ctx) {
     return {
-        name: 'createDocument',
-        description: 'Create a Markdown document in the project docs (README/CHANGELOG/spec draft produced by the council).',
-        category: 'vault',
+        name: "createDocument",
+        description: "Create a Markdown document in the project docs (README/CHANGELOG/spec draft produced by the council).",
+        category: "vault",
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:doc`, () => {
-                const title = args['title'] ?? 'New Document';
-                const content = args['content'] ?? '';
-                const tags = args['tags'] ?? [];
-                const id = slugify(title) || `doc-${Date.now()}`;
-                const path = workspaceArtifact(ctx.rootDir, 'docs', id);
+                const title = args["title"] ?? "New Document";
+                const content = args["content"] ?? "";
+                const tags = args["tags"] ?? [];
+                // v0.7.8: models routinely pass the FILENAME as title ("risks.md",
+                // "synthesis.md"), which slugified to "risks-md"/"synthesis-md" and
+                // produced duplicated artifacts (docs/risks-md.md next to risks.md,
+                // HANDOFF 2026-07-03 §5.1). Strip the extension before slugifying.
+                const normalizedTitle = title.replace(/\.(md|markdown)\s*$/i, "");
+                const slug = slugify(normalizedTitle) || `doc-${Date.now()}`;
+                if (slug === "risks") {
+                    const risksPath = workspaceFile(ctx.rootDir, "risks");
+                    const riskMeta = {
+                        kind: "risk",
+                        id: "risks",
+                        severity: "medium",
+                        date: new Date().toISOString().slice(0, 10),
+                    };
+                    ctx.storage.write(risksPath, riskMeta, content);
+                    return `Document "${title}" created at risks.md (workspace root).`;
+                }
+                const path = workspaceArtifact(ctx.rootDir, "docs", slug);
                 const meta = {
-                    kind: 'doc',
-                    id,
+                    kind: "doc",
+                    id: slug,
                     date: new Date().toISOString().slice(0, 10),
                     tags,
                 };
                 ctx.storage.write(path, meta, content);
-                return `Document "${title}" created at docs/${id}.md.`;
+                return `Document "${title}" created at docs/${slug}.md.`;
             });
         },
     };
@@ -449,20 +619,20 @@ const SEARCH_NUDGE_THRESHOLD = 5;
 function searchDocumentsStub(ctx) {
     let callCount = 0;
     return {
-        name: 'searchDocuments',
-        description: 'Search all workspace documents (`.zelari/**`) for a keyword. Returns matching files with snippets. ' +
-            'Search AT MOST 2-3 times, then act on the results: read the matched files with read_file instead of rephrasing the same search.',
-        category: 'analysis',
+        name: "searchDocuments",
+        description: "Search all workspace documents (`.zelari/**`) for a keyword. Returns matching files with snippets. " +
+            "Search AT MOST 2-3 times, then act on the results: read the matched files with read_file instead of rephrasing the same search.",
+        category: "analysis",
         parameters: [],
         execute: async (args) => {
             callCount++;
             const nudge = callCount > SEARCH_NUDGE_THRESHOLD
                 ? `[note] This is searchDocuments call #${callCount} in this run — STOP searching. Read the files you already found with read_file and act on them.\n\n`
-                : '';
-            const rawQuery = (args['query'] ?? '').trim();
-            const limit = args['limit'] ?? 5;
+                : "";
+            const rawQuery = (args["query"] ?? "").trim();
+            const limit = args["limit"] ?? 5;
             if (!rawQuery)
-                return 'searchDocuments requires a query.';
+                return "searchDocuments requires a query.";
             // v0.7.3: models routinely write boolean-ish queries ("plan OR phase OR
             // milestone"). The previous implementation substring-matched the WHOLE
             // query string, so every OR query — and any multi-word query that didn't
@@ -477,21 +647,21 @@ function searchDocumentsStub(ctx) {
             const words = rawQuery
                 .toLowerCase()
                 .split(/[^a-z0-9_-]+/)
-                .filter((w) => w.length >= 3 && w !== 'or' && w !== 'and' && w !== 'the');
+                .filter((w) => w.length >= 3 && w !== "or" && w !== "and" && w !== "the");
             const files = [
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'decisions')),
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'docs')),
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'reviews')),
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'plan-tasks')),
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'milestones')),
-                workspaceFile(ctx.rootDir, 'plan'),
-                workspaceFile(ctx.rootDir, 'risks'),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "decisions")),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "docs")),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "reviews")),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "plan-tasks")),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "milestones")),
+                workspaceFile(ctx.rootDir, "plan"),
+                workspaceFile(ctx.rootDir, "risks"),
             ];
             const results = [];
             for (const file of files) {
                 if (!existsSync(file))
                     continue;
-                const raw = readFileSync(file, 'utf8');
+                const raw = readFileSync(file, "utf8");
                 const content = raw.toLowerCase();
                 let idx = -1;
                 let matchLen = 0;
@@ -517,34 +687,42 @@ function searchDocumentsStub(ctx) {
                     continue;
                 const start = Math.max(0, idx - 40);
                 const end = Math.min(raw.length, idx + matchLen + 40);
-                const snippet = '…' + raw.slice(start, end).replace(/\n/g, ' ').trim() + '…';
-                results.push({ path: relative(ctx.rootDir, file) || basename(file), snippet });
+                const snippet = "…" + raw.slice(start, end).replace(/\n/g, " ").trim() + "…";
+                results.push({
+                    path: relative(ctx.rootDir, file) || basename(file),
+                    snippet,
+                });
                 if (results.length >= limit)
                     break;
             }
             if (results.length === 0)
                 return `${nudge}No matches for "${rawQuery}" in workspace.`;
-            return nudge + results.map((r) => `[${r.path}]\n${r.snippet}`).join('\n\n');
+            return (nudge + results.map((r) => `[${r.path}]\n${r.snippet}`).join("\n\n"));
         },
     };
 }
 function linkDocumentsStub(ctx) {
     return {
-        name: 'linkDocuments',
-        description: 'Link two workspace artifacts. Adds the `related:` field to the source frontmatter so backreferences can be traced.',
-        category: 'vault',
+        name: "linkDocuments",
+        description: "Link two workspace artifacts. Adds the `related:` field to the source frontmatter so backreferences can be traced.",
+        category: "vault",
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:link`, () => {
-                const fromId = args['fromId'];
-                const toId = args['toId'];
+                // v0.7.8: the provider-facing JSON schema (toolSchemas.ts) advertises
+                // sourceId/targetPathOrTitle — accept those aliases too, otherwise
+                // every schema-conformant call fails with "requires fromId and toId".
+                const fromId = args["fromId"] ?? args["sourceId"];
+                const toId = args["toId"] ??
+                    args["targetId"] ??
+                    args["targetPathOrTitle"];
                 if (!fromId || !toId)
-                    return 'linkDocuments requires fromId and toId.';
+                    return "linkDocuments requires fromId and toId.";
                 // Find the source file by id
                 const allFiles = [
-                    ...ctx.storage.listMarkdown(join(ctx.rootDir, 'decisions')),
-                    ...ctx.storage.listMarkdown(join(ctx.rootDir, 'docs')),
-                    ...ctx.storage.listMarkdown(join(ctx.rootDir, 'reviews')),
+                    ...ctx.storage.listMarkdown(join(ctx.rootDir, "decisions")),
+                    ...ctx.storage.listMarkdown(join(ctx.rootDir, "docs")),
+                    ...ctx.storage.listMarkdown(join(ctx.rootDir, "reviews")),
                 ];
                 const source = allFiles.find((f) => {
                     try {
@@ -570,18 +748,19 @@ function linkDocumentsStub(ctx) {
 }
 function getDocumentBacklinksStub(ctx) {
     return {
-        name: 'getDocumentBacklinks',
-        description: 'List all workspace artifacts that link to the given artifact via their `related:` frontmatter.',
-        category: 'analysis',
+        name: "getDocumentBacklinks",
+        description: "List all workspace artifacts that link to the given artifact via their `related:` frontmatter.",
+        category: "analysis",
         parameters: [],
         execute: async (args) => {
-            const targetId = args['targetId'];
+            // v0.7.8: the provider-facing JSON schema advertises `id` — accept it.
+            const targetId = args["targetId"] ?? args["id"];
             if (!targetId)
-                return 'getDocumentBacklinks requires targetId.';
+                return "getDocumentBacklinks requires targetId.";
             const allFiles = [
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'decisions')),
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'docs')),
-                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'reviews')),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "decisions")),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "docs")),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, "reviews")),
             ];
             const backlinks = [];
             for (const file of allFiles) {
@@ -593,11 +772,13 @@ function getDocumentBacklinksStub(ctx) {
                         backlinks.push(doc.meta.id);
                     }
                 }
-                catch { /* skip */ }
+                catch {
+                    /* skip */
+                }
             }
             if (backlinks.length === 0)
                 return `No backlinks to "${targetId}".`;
-            return backlinks.map((id) => `- ${id}`).join('\n');
+            return backlinks.map((id) => `- ${id}`).join("\n");
         },
     };
 }