@phren/cli 0.0.28 → 0.0.33

package/mcp/dist/{mcp-tasks.js → tools/tasks.js}

@@ -1,15 +1,15 @@
-import { mcpResponse } from "./mcp-types.js";
+import { mcpResponse } from "./types.js";
 import { z } from "zod";
 import * as fs from "fs";
 import * as path from "path";
-import { isValidProjectName } from "./utils.js";
-import { addTask as addTaskStore, addTasks as addTasksBatch, taskMarkdown, completeTask as completeTaskStore, completeTasks as completeTasksBatch, removeTask as removeTaskStore, removeTasks as removeTasksBatch, linkTaskIssue, pinTask, workNextTask, tidyDoneTasks, readTasks, readTasksAcrossProjects, resolveTaskItem, TASKS_FILENAME, updateTask as updateTaskStore, promoteTask, } from "./data-access.js";
-import { applyGravity } from "./data-tasks.js";
-import { buildTaskIssueBody, createGithubIssueForTask, parseGithubIssueUrl, resolveProjectGithubRepo, } from "./tasks-github.js";
-import { clearTaskCheckpoint } from "./session-checkpoints.js";
-import { incrementSessionTasksCompleted } from "./mcp-session.js";
-import { normalizeMemoryScope } from "./shared.js";
-import { permissionDeniedError } from "./governance-rbac.js";
+import { isValidProjectName } from "../utils.js";
+import { addTask as addTaskStore, addTasks as addTasksBatch, taskMarkdown, completeTask as completeTaskStore, completeTasks as completeTasksBatch, removeTask as removeTaskStore, removeTasks as removeTasksBatch, linkTaskIssue, pinTask, workNextTask, tidyDoneTasks, readTasks, readTasksAcrossProjects, resolveTaskItem, TASKS_FILENAME, updateTask as updateTaskStore, promoteTask, } from "../data/access.js";
+import { applyGravity } from "../data/tasks.js";
+import { parseGithubIssueUrl, } from "../task/github.js";
+import { clearTaskCheckpoint } from "../session/checkpoints.js";
+import { incrementSessionTasksCompleted } from "./session.js";
+import { normalizeMemoryScope } from "../shared.js";
+import { permissionDeniedError } from "../governance/rbac.js";
 const TASK_SECTION_ORDER = ["Active", "Queue", "Done"];
 const DEFAULT_TASK_LIMIT = 20;
 /** Done items are historical — cap tightly by default to avoid large responses. */
@@ -198,10 +198,13 @@ export function register(server, ctx) {
     });
     server.registerTool("add_task", {
         title: "◆ phren · add task",
-        description: "Append a task to a project's tasks.md file. Adds to the Queue section.",
+        description: "Append one or more tasks to a project's tasks.md file. Adds to the Queue section. Pass a single string or an array of strings.",
         inputSchema: z.object({
             project: z.string().describe("Project name (must match a directory in your phren)."),
-            item: z.string().describe("The task to add."),
+            item: z.union([
+                z.string().describe("A single task to add."),
+                z.array(z.string()).describe("Multiple tasks to add in one call."),
+            ]).describe("The task(s) to add. Pass a string for one task, or an array for bulk."),
             scope: z.string().optional().describe("Optional memory scope label. Defaults to 'shared'. Example: 'researcher' or 'builder'."),
         }),
     }, async ({ project, item, scope }) => {
@@ -213,6 +216,17 @@ export function register(server, ctx) {
         const normalizedScope = normalizeMemoryScope(scope ?? "shared");
         if (!normalizedScope)
             return mcpResponse({ ok: false, error: `Invalid scope: "${scope}". Use lowercase letters/numbers with '-' or '_' (max 64 chars), e.g. "researcher".` });
+        if (Array.isArray(item)) {
+            return withWriteQueue(async () => {
+                const result = addTasksBatch(phrenPath, project, item, { scope: normalizedScope });
+                if (!result.ok)
+                    return mcpResponse({ ok: false, error: result.error });
+                const { added, errors } = result.data;
+                if (added.length > 0)
+                    refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({ ok: added.length > 0, ...(added.length === 0 ? { error: `No tasks added: ${errors.join("; ")}` } : {}), message: `Added ${added.length} of ${item.length} tasks to ${project}`, data: { project, added, errors } });
+            });
+        }
         return withWriteQueue(async () => {
             const result = addTaskStore(phrenPath, project, item, { scope: normalizedScope });
             if (!result.ok)
@@ -221,35 +235,15 @@ export function register(server, ctx) {
             return mcpResponse({ ok: true, message: `Task added: ${result.data.line}`, data: { project, item, scope: normalizedScope } });
         });
     });
-    server.registerTool("add_tasks", {
-        title: "◆ phren · add tasks (bulk)",
-        description: "Append multiple tasks to a project's tasks.md file in one call. Adds to the Queue section.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-            items: z.array(z.string()).describe("List of tasks to add."),
-        }),
-    }, async ({ project, items }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const addTasksDenied = permissionDeniedError(phrenPath, "add_task", project);
-        if (addTasksDenied)
-            return mcpResponse({ ok: false, error: addTasksDenied });
-        return withWriteQueue(async () => {
-            const result = addTasksBatch(phrenPath, project, items);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error });
-            const { added, errors } = result.data;
-            if (added.length > 0)
-                refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({ ok: added.length > 0, ...(added.length === 0 ? { error: `No tasks added: ${errors.join("; ")}` } : {}), message: `Added ${added.length} of ${items.length} tasks to ${project}`, data: { project, added, errors } });
-        });
-    });
     server.registerTool("complete_task", {
         title: "◆ phren · done",
-        description: "Move a task to the Done section by matching text.",
+        description: "Move one or more tasks to the Done section by matching text. Pass a single string or an array of strings.",
         inputSchema: z.object({
             project: z.string().describe("Project name."),
-            item: z.string().describe("Exact or partial text of the item to complete."),
+            item: z.union([
+                z.string().describe("Exact or partial text of the item to complete."),
+                z.array(z.string()).describe("List of partial item texts to complete."),
+            ]).describe("The task(s) to complete. Pass a string for one, or an array for bulk."),
             sessionId: z.string().optional().describe("Optional session ID from session_start. Pass this to track per-session task completion metrics."),
         }),
     }, async ({ project, item, sessionId }) => {
@@ -258,6 +252,38 @@ export function register(server, ctx) {
         const completeTaskDenied = permissionDeniedError(phrenPath, "complete_task", project);
         if (completeTaskDenied)
             return mcpResponse({ ok: false, error: completeTaskDenied });
+        if (Array.isArray(item)) {
+            return withWriteQueue(async () => {
+                const resolvedItems = item
+                    .map((match) => {
+                    const resolved = resolveTaskItem(phrenPath, project, match);
+                    return resolved.ok ? resolved.data : null;
+                })
+                    .filter((task) => task !== null);
+                const result = completeTasksBatch(phrenPath, project, item);
+                if (!result.ok)
+                    return mcpResponse({ ok: false, error: result.error });
+                const { completed, errors } = result.data;
+                if (completed.length > 0) {
+                    const completedSet = new Set(completed);
+                    for (const task of resolvedItems) {
+                        if (!completedSet.has(task.line))
+                            continue;
+                        clearTaskCheckpoint(phrenPath, {
+                            project,
+                            taskId: task.stableId ?? task.id,
+                            stableId: task.stableId,
+                            positionalId: task.id,
+                            taskLine: task.line,
+                        });
+                    }
+                    incrementSessionTasksCompleted(phrenPath, completed.length, sessionId, project);
+                }
+                if (completed.length > 0)
+                    refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({ ok: completed.length > 0, ...(completed.length === 0 ? { error: `No tasks completed: ${errors.join("; ")}` } : {}), message: `Completed ${completed.length}/${item.length} items`, data: { project, completed, errors } });
+            });
+        }
         return withWriteQueue(async () => {
             const before = resolveTaskItem(phrenPath, project, item);
             const result = completeTaskStore(phrenPath, project, item);
@@ -277,57 +303,15 @@ export function register(server, ctx) {
             return mcpResponse({ ok: true, message: result.data, data: { project, item } });
         });
     });
-    server.registerTool("complete_tasks", {
-        title: "◆ phren · done (bulk)",
-        description: "Move multiple tasks to Done in one call. Pass an array of partial item texts.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-            items: z.array(z.string()).describe("List of partial item texts to complete."),
-            sessionId: z.string().optional().describe("Optional session ID from session_start. Pass this to track per-session task completion metrics."),
-        }),
-    }, async ({ project, items, sessionId }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const completeTasksDenied = permissionDeniedError(phrenPath, "complete_task", project);
-        if (completeTasksDenied)
-            return mcpResponse({ ok: false, error: completeTasksDenied });
-        return withWriteQueue(async () => {
-            const resolvedItems = items
-                .map((match) => {
-                const resolved = resolveTaskItem(phrenPath, project, match);
-                return resolved.ok ? resolved.data : null;
-            })
-                .filter((task) => task !== null);
-            const result = completeTasksBatch(phrenPath, project, items);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error });
-            const { completed, errors } = result.data;
-            if (completed.length > 0) {
-                const completedSet = new Set(completed);
-                for (const task of resolvedItems) {
-                    if (!completedSet.has(task.line))
-                        continue;
-                    clearTaskCheckpoint(phrenPath, {
-                        project,
-                        taskId: task.stableId ?? task.id,
-                        stableId: task.stableId,
-                        positionalId: task.id,
-                        taskLine: task.line,
-                    });
-                }
-                incrementSessionTasksCompleted(phrenPath, completed.length, sessionId, project);
-            }
-            if (completed.length > 0)
-                refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({ ok: completed.length > 0, ...(completed.length === 0 ? { error: `No tasks completed: ${errors.join("; ")}` } : {}), message: `Completed ${completed.length}/${items.length} items`, data: { project, completed, errors } });
-        });
-    });
     server.registerTool("remove_task", {
         title: "◆ phren · remove task",
-        description: "Remove a task from a project's tasks.md file by matching text or ID.",
+        description: "Remove one or more tasks from a project's tasks.md file by matching text or ID. Pass a single string or an array of strings.",
         inputSchema: z.object({
             project: z.string().describe("Project name."),
-            item: z.string().describe("Exact or partial text of the task, or a task ID like A1/Q3/D2."),
+            item: z.union([
+                z.string().describe("Exact or partial text of the task, or a task ID like A1/Q3/D2."),
+                z.array(z.string()).describe("List of partial item texts or IDs to remove."),
+            ]).describe("The task(s) to remove. Pass a string for one, or an array for bulk."),
         }),
     }, async ({ project, item }) => {
         if (!isValidProjectName(project))
@@ -335,6 +319,17 @@ export function register(server, ctx) {
         const removeTaskDenied = permissionDeniedError(phrenPath, "remove_task", project);
         if (removeTaskDenied)
             return mcpResponse({ ok: false, error: removeTaskDenied });
+        if (Array.isArray(item)) {
+            return withWriteQueue(async () => {
+                const result = removeTasksBatch(phrenPath, project, item);
+                if (!result.ok)
+                    return mcpResponse({ ok: false, error: result.error });
+                const { removed, errors } = result.data;
+                if (removed.length > 0)
+                    refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({ ok: removed.length > 0, ...(removed.length === 0 ? { error: `No tasks removed: ${errors.join("; ")}` } : {}), message: `Removed ${removed.length}/${item.length} items`, data: { project, removed, errors } });
+            });
+        }
         return withWriteQueue(async () => {
             const result = removeTaskStore(phrenPath, project, item);
             if (!result.ok)
@@ -343,35 +338,14 @@ export function register(server, ctx) {
             return mcpResponse({ ok: true, message: result.data, data: { project, item } });
         });
     });
-    server.registerTool("remove_tasks", {
-        title: "◆ phren · remove tasks (bulk)",
-        description: "Remove multiple tasks in one call. Pass an array of partial item texts or IDs.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-            items: z.array(z.string()).describe("List of partial item texts or IDs to remove."),
-        }),
-    }, async ({ project, items }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const removeTasksDenied = permissionDeniedError(phrenPath, "remove_task", project);
-        if (removeTasksDenied)
-            return mcpResponse({ ok: false, error: removeTasksDenied });
-        return withWriteQueue(async () => {
-            const result = removeTasksBatch(phrenPath, project, items);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error });
-            const { removed, errors } = result.data;
-            if (removed.length > 0)
-                refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({ ok: removed.length > 0, ...(removed.length === 0 ? { error: `No tasks removed: ${errors.join("; ")}` } : {}), message: `Removed ${removed.length}/${items.length} items`, data: { project, removed, errors } });
-        });
-    });
     server.registerTool("update_task", {
         title: "◆ phren · update task",
-        description: "Update a task's text, priority, context, section, or GitHub metadata by matching text.",
+        description: "Update a task's text, priority, context, section, GitHub metadata, pin status, or promote it. " +
+            "Also supports work_next (pick highest-priority Queue item) and promote (clear speculative flag). " +
+            "When work_next is true, item is not needed.",
         inputSchema: z.object({
             project: z.string().describe("Project name."),
-            item: z.string().describe("Partial text to match against existing tasks."),
+            item: z.string().optional().describe("Partial text to match against existing tasks. Required unless work_next is true."),
             updates: z.object({
                 text: z.string().optional().describe("Replacement text for the task line."),
                 priority: z.enum(["high", "medium", "low"]).optional().describe("New priority tag: high, medium, or low."),
@@ -381,6 +355,10 @@ export function register(server, ctx) {
                 github_issue: z.union([z.number().int().positive(), z.string()]).optional().describe("GitHub issue number (for example 14 or '#14')."),
                 github_url: z.string().optional().describe("GitHub issue URL to associate with the task item."),
                 unlink_github: z.boolean().optional().describe("If true, remove any linked GitHub issue metadata from the item."),
+                pin: z.boolean().optional().describe("If true, pin the task so it floats to the top of its section."),
+                promote: z.boolean().optional().describe("If true, clear the speculative flag on this task (confirm the user wants it)."),
+                move_to_active: z.boolean().optional().describe("Used with promote: also move the task to the Active section."),
+                work_next: z.boolean().optional().describe("If true, pick the highest-priority Queue item and move it to Active. Ignores item param."),
             }).describe("Fields to update. All are optional."),
         }),
     }, async ({ project, item, updates }) => {
@@ -389,189 +367,84 @@ export function register(server, ctx) {
         const updateTaskDenied = permissionDeniedError(phrenPath, "update_task", project);
         if (updateTaskDenied)
             return mcpResponse({ ok: false, error: updateTaskDenied });
-        return withWriteQueue(async () => {
-            const result = updateTaskStore(phrenPath, project, item, updates);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error });
-            refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({ ok: true, message: result.data, data: { project, item, updates } });
-        });
-    });
-    server.registerTool("link_task_issue", {
-        title: "◆ phren · link task issue",
-        description: "Link or unlink a task to an existing GitHub issue.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-            item: z.string().describe("Task text, ID, or stable bid to link."),
-            issue_number: z.union([z.number().int().positive(), z.string()]).optional().describe("Existing GitHub issue number (for example 14 or '#14')."),
-            issue_url: z.string().optional().describe("Existing GitHub issue URL."),
-            unlink: z.boolean().optional().describe("If true, remove any linked issue from the task item."),
-        }),
-    }, async ({ project, item, issue_number, issue_url, unlink }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        return withWriteQueue(async () => {
-            if (unlink && (issue_number !== undefined || issue_url)) {
-                return mcpResponse({ ok: false, error: "Use either unlink=true or issue_number/issue_url, not both." });
-            }
-            if (!unlink && issue_number === undefined && !issue_url) {
-                return mcpResponse({ ok: false, error: "Provide issue_number or issue_url to link, or unlink=true to remove the link." });
-            }
-            if (issue_url) {
-                const parsed = parseGithubIssueUrl(issue_url);
-                if (!parsed)
-                    return mcpResponse({ ok: false, error: "issue_url must be a valid GitHub issue URL." });
-                if (issue_number !== undefined) {
-                    const normalizedIssue = Number.parseInt(String(issue_number).replace(/^#/, ""), 10);
-                    if (normalizedIssue !== parsed.issueNumber) {
-                        return mcpResponse({ ok: false, error: "issue_number and issue_url refer to different issues." });
-                    }
+        // Runtime validation: item is required unless work_next is true
+        if (!updates.work_next && !item) {
+            return mcpResponse({ ok: false, error: "item is required unless updates.work_next is true." });
+        }
+        // Cross-validate github_issue and github_url
+        if (updates.github_url) {
+            const parsed = parseGithubIssueUrl(updates.github_url);
+            if (!parsed)
+                return mcpResponse({ ok: false, error: "github_url must be a valid GitHub issue URL." });
+            if (updates.github_issue !== undefined) {
+                const normalizedIssue = Number.parseInt(String(updates.github_issue).replace(/^#/, ""), 10);
+                if (normalizedIssue !== parsed.issueNumber) {
+                    return mcpResponse({ ok: false, error: "github_issue and github_url refer to different issues." });
                 }
             }
-            const result = linkTaskIssue(phrenPath, project, item, {
-                github_issue: issue_number,
-                github_url: issue_url,
-                unlink: unlink ?? false,
-            });
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error, errorCode: result.code });
-            refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({
-                ok: true,
-                message: unlink
-                    ? `Removed GitHub link from ${project} task.`
-                    : `Linked ${project} task to ${result.data.githubIssue ? `#${result.data.githubIssue}` : result.data.githubUrl}.`,
-                data: {
-                    project,
-                    item,
-                    stableId: result.data.stableId || null,
-                    githubIssue: result.data.githubIssue ?? null,
-                    githubUrl: result.data.githubUrl || null,
-                },
-            });
-        });
-    });
-    server.registerTool("promote_task_to_issue", {
-        title: "◆ phren · promote task",
-        description: "Create a GitHub issue from a task and link it back into the task list.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-            item: z.string().describe("Task text, ID, or stable bid to promote."),
-            repo: z.string().optional().describe("Target GitHub repo in owner/name form. If omitted, phren tries to infer it from CLAUDE.md or summary.md."),
-            title: z.string().optional().describe("Optional GitHub issue title. Defaults to the task text."),
-            body: z.string().optional().describe("Optional GitHub issue body. Defaults to a body built from the task plus context."),
-            mark_done: z.boolean().optional().describe("If true, mark the task Done after creating and linking the issue."),
-        }),
-    }, async ({ project, item, repo, title, body, mark_done }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+        }
         return withWriteQueue(async () => {
-            const match = resolveTaskItem(phrenPath, project, item);
-            if (!match.ok)
-                return mcpResponse({ ok: false, error: match.error, errorCode: match.code });
-            const targetRepo = repo || resolveProjectGithubRepo(phrenPath, project);
-            if (!targetRepo) {
-                return mcpResponse({ ok: false, error: "Could not infer a GitHub repo for this project. Provide repo in owner/name form or add a GitHub URL to CLAUDE.md/summary.md." });
+            // Handle work_next: pick highest-priority Queue item, move to Active
+            if (updates.work_next) {
+                const result = workNextTask(phrenPath, project);
+                if (!result.ok)
+                    return mcpResponse({ ok: false, error: result.error });
+                refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({ ok: true, message: result.data, data: { project } });
             }
-            const created = createGithubIssueForTask({
-                repo: targetRepo,
-                title: title?.trim() || match.data.line.replace(/\s*\[(high|medium|low)\]\s*$/i, "").trim(),
-                body: body?.trim() || buildTaskIssueBody(project, match.data),
-            });
-            if (!created.ok)
-                return mcpResponse({ ok: false, error: created.error, errorCode: created.code });
-            const linked = linkTaskIssue(phrenPath, project, match.data.stableId ? `bid:${match.data.stableId}` : match.data.id, {
-                github_issue: created.data.issueNumber,
-                github_url: created.data.url,
-            });
-            if (!linked.ok)
-                return mcpResponse({ ok: false, error: linked.error, errorCode: linked.code });
-            if (mark_done) {
-                const completionMatch = linked.data.stableId ? `bid:${linked.data.stableId}` : linked.data.id;
-                const completed = completeTaskStore(phrenPath, project, completionMatch);
-                if (!completed.ok)
-                    return mcpResponse({ ok: false, error: completed.error, errorCode: completed.code });
-                clearTaskCheckpoint(phrenPath, {
-                    project,
-                    taskId: match.data.stableId ?? match.data.id,
-                    stableId: match.data.stableId,
-                    positionalId: match.data.id,
-                    taskLine: match.data.line,
+            // Handle pin
+            if (updates.pin) {
+                const result = pinTask(phrenPath, project, item);
+                if (!result.ok)
+                    return mcpResponse({ ok: false, error: result.error });
+                refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({ ok: true, message: result.data, data: { project, item } });
+            }
+            // Handle promote (clear speculative flag)
+            if (updates.promote) {
+                const result = promoteTask(phrenPath, project, item, updates.move_to_active ?? false);
+                if (!result.ok)
+                    return mcpResponse({ ok: false, error: result.error });
+                refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({
+                    ok: true,
+                    message: `Promoted task "${result.data.line}" in ${project}${updates.move_to_active ? " (moved to Active)" : ""}.`,
+                    data: { project, item: result.data },
                 });
             }
-            refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({
-                ok: true,
-                message: `Created GitHub issue ${created.data.issueNumber ? `#${created.data.issueNumber}` : created.data.url} for ${project} task.`,
-                data: {
-                    project,
-                    item,
-                    repo: targetRepo,
-                    githubIssue: created.data.issueNumber ?? null,
-                    githubUrl: created.data.url,
-                    markDone: mark_done ?? false,
-                },
-            });
-        });
-    });
-    server.registerTool("pin_task", {
-        title: "◆ phren · pin task",
-        description: "Pin a task so it floats to the top of its section.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-            item: z.string().describe("Partial item text or ID to pin."),
-        }),
-    }, async ({ project, item }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        return withWriteQueue(async () => {
-            const result = pinTask(phrenPath, project, item);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error });
-            refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({ ok: true, message: result.data, data: { project, item } });
-        });
-    });
-    server.registerTool("work_next_task", {
-        title: "◆ phren · work next",
-        description: "Move the highest-priority Queue item to Active so it becomes the next task to work on.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-        }),
-    }, async ({ project }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        return withWriteQueue(async () => {
-            const result = workNextTask(phrenPath, project);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error });
-            refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({ ok: true, message: result.data, data: { project } });
-        });
-    });
-    server.registerTool("promote_task", {
-        title: "◆ phren · promote task",
-        description: "Promote a speculative task to committed by clearing the speculative flag. " +
-            "Use this when the user says 'yes do it', 'let's work on that', or otherwise confirms " +
-            "they want to commit to a suggested task. Optionally moves it to Active.",
-        inputSchema: z.object({
-            project: z.string().describe("Project name."),
-            item: z.string().describe("Partial text, stable ID (bid:XXXX), or positional ID of the speculative task."),
-            move_to_active: z.boolean().optional().describe("If true, also move the task to the Active section. Default false."),
-        }),
-    }, async ({ project, item, move_to_active }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        return withWriteQueue(async () => {
-            const result = promoteTask(phrenPath, project, item, move_to_active ?? false);
+            // Handle github issue linking via update_task when github_issue or github_url is set (and no other field updates)
+            if ((updates.github_issue !== undefined || updates.github_url || updates.unlink_github) && !updates.text && !updates.priority && !updates.context && !updates.section) {
+                if (updates.unlink_github && (updates.github_issue !== undefined || updates.github_url)) {
+                    return mcpResponse({ ok: false, error: "Use either unlink_github=true or github_issue/github_url, not both." });
+                }
+                const result = linkTaskIssue(phrenPath, project, item, {
+                    github_issue: updates.github_issue,
+                    github_url: updates.github_url,
+                    unlink: updates.unlink_github ?? false,
+                });
+                if (!result.ok)
+                    return mcpResponse({ ok: false, error: result.error, errorCode: result.code });
+                refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({
+                    ok: true,
+                    message: updates.unlink_github
+                        ? `Removed GitHub link from ${project} task.`
+                        : `Linked ${project} task to ${result.data.githubIssue ? `#${result.data.githubIssue}` : result.data.githubUrl}.`,
+                    data: {
+                        project,
+                        item,
+                        stableId: result.data.stableId || null,
+                        githubIssue: result.data.githubIssue ?? null,
+                        githubUrl: result.data.githubUrl || null,
+                    },
+                });
+            }
+            // Standard update path
+            const result = updateTaskStore(phrenPath, project, item, updates);
             if (!result.ok)
                 return mcpResponse({ ok: false, error: result.error });
             refreshTaskIndex(updateFileInIndex, phrenPath, project);
-            return mcpResponse({
-                ok: true,
-                message: `Promoted task "${result.data.line}" in ${project}${move_to_active ? " (moved to Active)" : ""}.`,
-                data: { project, item: result.data },
-            });
+            return mcpResponse({ ok: true, message: result.data, data: { project, item, updates } });
         });
     });
     server.registerTool("tidy_done_tasks", {

package/mcp/dist/{memory-ui-data.js → ui/data.js}

@@ -1,17 +1,18 @@
 import * as fs from "fs";
 import * as path from "path";
 import { createHash } from "crypto";
-import { getProjectDirs, runtimeDir, runtimeHealthFile, memoryUsageLogFile, homePath, } from "./shared.js";
-import { errorMessage } from "./utils.js";
-import { readInstallPreferences } from "./init-preferences.js";
-import { readCustomHooks } from "./hooks.js";
-import { hookConfigPaths, hookConfigRoots } from "./provider-adapters.js";
-import { readProjectConfig, isProjectHookEnabled, PROJECT_HOOK_EVENTS } from "./project-config.js";
-import { getAllSkills } from "./skill-registry.js";
-import { resolveTaskFilePath, readTasks, TASKS_FILENAME } from "./data-tasks.js";
-import { buildIndex, queryDocBySourceKey, queryRows } from "./shared-index.js";
-import { readProjectTopics, classifyTopicForText } from "./project-topics.js";
-import { entryScoreKey } from "./governance-scores.js";
+import { getProjectDirs, runtimeDir, runtimeHealthFile, memoryUsageLogFile, homePath, } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { readInstallPreferences } from "../init/preferences.js";
+import { readCustomHooks } from "../hooks.js";
+import { hookConfigPaths, hookConfigRoots } from "../provider-adapters.js";
+import { readProjectConfig, isProjectHookEnabled, PROJECT_HOOK_EVENTS } from "../project-config.js";
+import { getAllSkills } from "../skill/registry.js";
+import { resolveTaskFilePath, readTasks, TASKS_FILENAME } from "../data/tasks.js";
+import { buildIndex, queryDocBySourceKey, queryRows } from "../shared/index.js";
+import { readProjectTopics, classifyTopicForText } from "../project-topics.js";
+import { entryScoreKey } from "../governance/scores.js";
+import { logger } from "../logger.js";
 function extractGithubUrl(content) {
     const match = content.match(/https?:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+/);
     return match ? match[0] : undefined;
@@ -94,6 +95,18 @@ export function isAllowedFilePath(filePath, phrenPath) {
     });
     return allowedRealRoots.some((root) => realResolved === root || realResolved.startsWith(root + path.sep));
 }
+/**
+ * Stricter path check for skill endpoints — only allows files under skills/ directories,
+ * not the entire phren store.
+ */
+export function isAllowedSkillPath(filePath, phrenPath) {
+    if (!isAllowedFilePath(filePath, phrenPath))
+        return false;
+    const resolved = path.resolve(filePath);
+    // Must be under a "skills" directory segment
+    const segments = resolved.split(path.sep);
+    return segments.some((seg) => seg === "skills");
+}
 export function collectSkillsForUI(phrenPath, profile = "") {
     return getAllSkills(phrenPath, profile).map((skill) => ({
         name: skill.name,
@@ -136,7 +149,7 @@ export function getHooksData(phrenPath, profile) {
     }
     return { globalEnabled, tools, customHooks: readCustomHooks(phrenPath), projectOverrides };
 }
-export async function buildGraph(phrenPath, profile, focusProject) {
+export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
     const projects = getProjectDirs(phrenPath, profile).map((projectDir) => path.basename(projectDir)).filter((project) => project !== "global");
     const nodes = [];
     const links = [];
@@ -287,9 +300,11 @@ export async function buildGraph(phrenPath, profile, focusProject) {
         // task loading failed — continue with other data sources
     }
     // ── Fragments (fragment graph) ──────────────────────────────────────
-    let db = null;
+    const ownDb = !existingDb;
+    let db = existingDb ?? null;
     try {
-        db = await buildIndex(phrenPath, profile);
+        if (!db)
+            db = await buildIndex(phrenPath, profile);
         const rows = queryRows(db, `SELECT e.id, e.name, e.type, COUNT(DISTINCT el.source_doc) as ref_count
        FROM entities e JOIN entity_links el ON el.target_id = e.id WHERE e.type != 'document'
        GROUP BY e.id, e.name, e.type ORDER BY ref_count DESC LIMIT 5000`, []);
@@ -364,7 +379,7 @@ export async function buildGraph(phrenPath, profile, focusProject) {
         // fragment loading failed — continue with other data sources
     }
     finally {
-        if (db) {
+        if (ownDb && db) {
             try {
                 db.close();
             }
@@ -467,8 +482,7 @@ export function collectProjectsForUI(phrenPath, profile) {
         }
     }
     catch (err) {
-        if (process.env.PHREN_DEBUG)
-            process.stderr.write(`[phren] memory-ui filterByProfile: ${errorMessage(err)}\n`);
+        logger.debug("memory-ui", `memory-ui filterByProfile: ${errorMessage(err)}`);
     }
     const results = [];
     for (const project of projects) {

package/mcp/dist/{memory-ui.js → ui/memory-ui.js}

@@ -1,6 +1,6 @@
-import { createWebUiHttpServer, startWebUiServer, } from "./memory-ui-server.js";
-import { renderWebUiPage } from "./memory-ui-page.js";
-export { renderPageForTests } from "./memory-ui-page.js";
+import { createWebUiHttpServer, startWebUiServer, } from "./server.js";
+import { renderWebUiPage } from "./page.js";
+export { renderPageForTests } from "./page.js";
 export function createWebUiServer(phrenPath, opts, profile) {
     return createWebUiHttpServer(phrenPath, renderWebUiPage, profile, opts);
 }