zelari-code 0.7.8 → 0.7.10

package/dist/cli/workspace/stubs.js

@@ -12,11 +12,11 @@
  *
  * @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.
@@ -32,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
@@ -45,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 : [],
@@ -58,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: [] };
@@ -78,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));
@@ -93,77 +93,81 @@ 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) {
@@ -172,7 +176,7 @@ function addPhaseRecord(summary, input) {
         return { id, created: false };
     }
     summary.phases.push({
-        kind: 'phase',
+        kind: "phase",
         id,
         name: input.name,
         description: input.description,
@@ -191,46 +195,47 @@ function addPhaseRecord(summary, input) {
 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}`);
+        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',
+        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',
+        status: "pending",
         priority: t.priority,
     });
-    const taskPath = join(ctx.rootDir, 'plan-tasks', `${id}.md`);
+    const taskPath = join(ctx.rootDir, "plan-tasks", `${id}.md`);
     const meta = {
-        kind: 'task',
+        kind: "task",
         id,
         phaseId,
-        status: 'pending',
+        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');
+        "",
+        t.qaScenario || "_(not specified)_",
+        "",
+    ].join("\n");
     ctx.storage.write(taskPath, meta, body);
     return { id, created: true };
 }
@@ -240,18 +245,18 @@ function addMilestoneRecord(ctx, summary, input) {
     if (summary.milestones.some((m) => m.id === id)) {
         return { id, created: false };
     }
-    const version = input.targetVersion ?? input.dueDate ?? 'TBD';
+    const version = input.targetVersion ?? input.dueDate ?? "TBD";
     summary.milestones.push({
-        kind: 'milestone',
+        kind: "milestone",
         id,
         name: input.title,
         description: input.description,
         dueDate: input.dueDate,
         targetVersion: version,
     });
-    const path = join(ctx.rootDir, 'milestones', `${id}.md`);
+    const path = join(ctx.rootDir, "milestones", `${id}.md`);
     const meta = {
-        kind: 'milestone',
+        kind: "milestone",
         id,
         name: input.title,
         description: input.description,
@@ -260,12 +265,12 @@ function addMilestoneRecord(ctx, summary, input) {
     };
     const body = [
         `# Milestone: ${input.title}`,
-        '',
+        "",
         input.description,
-        '',
+        "",
         `Target version: ${version}`,
-        '',
-    ].join('\n');
+        "",
+    ].join("\n");
     ctx.storage.write(path, meta, body);
     return { id, created: true };
 }
@@ -314,15 +319,15 @@ export function createWorkspaceStubs(ctx) {
  */
 function createPlanStub(ctx) {
     return {
-        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',
+        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 rawPhases = Array.isArray(args['phases'])
-                    ? args['phases']
+                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 }] }).';
@@ -333,64 +338,69 @@ function createPlanStub(ctx) {
                 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',
+                        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']
+                    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'),
+                            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 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'],
+                        title: rawMilestone["title"] ?? "v0.1.0 design-complete",
+                        description: rawMilestone["description"] ?? "",
+                        dueDate: rawMilestone["dueDate"],
+                        targetVersion: rawMilestone["targetVersion"],
                     });
                     if (created)
                         milestonesCreated += 1;
                 }
                 writePlan(ctx, summary);
-                return `Plan created: ${phasesCreated} phases, ${tasksCreated} tasks, ${milestonesCreated} milestone(s). Phase ids: ${phaseIds.join(', ')}.`;
+                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',
+        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 name = args["name"] ?? "New Phase";
+                const order = args["order"] ?? 0;
                 const summary = readPlan(ctx);
                 const { id, created } = addPhaseRecord(summary, {
                     name,
-                    description: args['description'] ?? '',
+                    description: args["description"] ?? "",
                     order,
-                    color: args['color'] ?? '#3b82f6',
+                    color: args["color"] ?? "#3b82f6",
                 });
                 if (!created) {
                     return `Phase "${id}" already exists.`;
@@ -403,27 +413,30 @@ 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 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 } = 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'),
+                    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);
                 return `Task "${title}" created (id: ${id}) under phase "${phaseId}".`;
@@ -433,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)
@@ -468,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.`;
             });
@@ -515,24 +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 title = args["title"] ?? "New Milestone";
                 const summary = readPlan(ctx);
                 const { id, created } = addMilestoneRecord(ctx, summary, {
                     title,
-                    description: args['description'] ?? '',
-                    dueDate: args['dueDate'],
-                    targetVersion: args['targetVersion'],
+                    description: args["description"] ?? "",
+                    dueDate: args["dueDate"],
+                    targetVersion: args["targetVersion"],
                 });
                 if (!created)
                     return `Milestone "${id}" already exists.`;
                 writePlan(ctx, summary);
-                const version = summary.milestones.find((m) => m.id === id)?.targetVersion ?? 'TBD';
+                const version = summary.milestones.find((m) => m.id === id)?.targetVersion ?? "TBD";
                 return `Milestone "${title}" created (id: ${id}, version: ${version}).`;
             });
         },
@@ -540,30 +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 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 id = slugify(normalizedTitle) || `doc-${Date.now()}`;
-                const path = workspaceArtifact(ctx.rootDir, 'docs', id);
+                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.`;
             });
         },
     };
@@ -579,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
@@ -607,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;
@@ -647,39 +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`, () => {
                 // 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'];
+                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 {
@@ -705,19 +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) => {
             // v0.7.8: the provider-facing JSON schema advertises `id` — accept it.
-            const targetId = args['targetId'] ?? args['id'];
+            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) {
@@ -729,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");
         },
     };
 }