@plandesk/api 0.8.0 → 0.10.0

package/dist/services/goals.js

@@ -0,0 +1,323 @@
+import { createGoal, createTask, getGoal, getProject, InvalidGoalStatusError, isGoalStatus, listGoals, listTagsByTaskForProject, listTasks, updateGoal, updateGoalStatus, updateTask, } from '@plandesk/db';
+import { serializeGoal, serializeTask } from '../serialize.js';
+export class InvalidGoalTransitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidGoalTransitionError';
+    }
+}
+export class GoalCompletionBlockedError extends Error {
+    incompleteTaskIds;
+    constructor(incompleteTaskIds) {
+        super('Goal cannot be completed until all cycle-tasks are done');
+        this.name = 'GoalCompletionBlockedError';
+        this.incompleteTaskIds = incompleteTaskIds;
+    }
+}
+export class InvalidVerificationSurfaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidVerificationSurfaceError';
+    }
+}
+export class GoalVerificationRequiredError extends Error {
+    requiredKind;
+    constructor(requiredKind) {
+        super(`Verification evidence required for surface kind: ${requiredKind}`);
+        this.name = 'GoalVerificationRequiredError';
+        this.requiredKind = requiredKind;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function parseVerificationSurface(raw) {
+    if (raw === null) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new InvalidVerificationSurfaceError('verification_surface must be valid JSON');
+    }
+    if (!isRecord(parsed) || typeof parsed.kind !== 'string') {
+        throw new InvalidVerificationSurfaceError('verification_surface must include a kind');
+    }
+    switch (parsed.kind) {
+        case 'gate_command': {
+            if (!isNonEmptyString(parsed.command)) {
+                throw new InvalidVerificationSurfaceError('gate_command requires a command');
+            }
+            return { kind: 'gate_command', command: parsed.command };
+        }
+        case 'acceptance_checklist': {
+            if (!Array.isArray(parsed.items) || parsed.items.length === 0) {
+                throw new InvalidVerificationSurfaceError('acceptance_checklist requires non-empty items');
+            }
+            const items = [];
+            for (const item of parsed.items) {
+                if (!isRecord(item) || !isNonEmptyString(item.criterion)) {
+                    throw new InvalidVerificationSurfaceError('acceptance_checklist items require a criterion');
+                }
+                items.push({ criterion: item.criterion });
+            }
+            return { kind: 'acceptance_checklist', items };
+        }
+        case 'human_sign_off':
+            return { kind: 'human_sign_off' };
+        default:
+            throw new InvalidVerificationSurfaceError(`Unknown verification_surface kind: ${parsed.kind}`);
+    }
+}
+export function evaluateEvidence(surface, evidence) {
+    if (surface.kind !== evidence.kind) {
+        return { green: false, detail: `Expected evidence kind ${surface.kind}` };
+    }
+    if (surface.kind === 'gate_command' && evidence.kind === 'gate_command') {
+        if (evidence.exit_code === 0) {
+            return { green: true };
+        }
+        const detail = evidence.detail ??
+            `exit_code ${String(evidence.exit_code)}${evidence.command ? ` for \`${evidence.command}\`` : ''}`;
+        return { green: false, detail };
+    }
+    if (surface.kind === 'acceptance_checklist' && evidence.kind === 'acceptance_checklist') {
+        const missing = surface.items
+            .map((item) => item.criterion)
+            .filter((criterion) => !evidence.checked.includes(criterion));
+        if (missing.length === 0) {
+            return { green: true };
+        }
+        return { green: false, detail: `Missing criteria: ${missing.join(', ')}` };
+    }
+    if (surface.kind === 'human_sign_off' && evidence.kind === 'human_sign_off') {
+        if (isNonEmptyString(evidence.approved_by)) {
+            return { green: true };
+        }
+        return { green: false, detail: 'approved_by is required' };
+    }
+    return { green: false, detail: `Expected evidence kind ${surface.kind}` };
+}
+function validateVerificationSurfaceInput(raw) {
+    if (raw === undefined) {
+        return;
+    }
+    parseVerificationSurface(raw);
+}
+function acceptanceBlockMarker(goalId) {
+    return `Acceptance-block-for: ${goalId}`;
+}
+function hasUnresolvedBlockingTask(db, projectId, goalId) {
+    const marker = acceptanceBlockMarker(goalId);
+    return listTasks(db, projectId).some((task) => task.goalId === goalId && task.status === 'scope' && task.description?.includes(marker));
+}
+// When acceptance finally passes, the remediation task filed on the earlier red
+// result is obsolete — resolve it so a completed goal never shows open work.
+function resolveBlockingTasks(db, projectId, goalId) {
+    const marker = acceptanceBlockMarker(goalId);
+    for (const task of listTasks(db, projectId)) {
+        if (task.goalId === goalId && task.status !== 'done' && task.description?.includes(marker)) {
+            updateTask(db, task.id, { status: 'done' });
+        }
+    }
+}
+function truncateObjective(objective, maxLength = 80) {
+    if (objective.length <= maxLength) {
+        return objective;
+    }
+    return `${objective.slice(0, maxLength - 1)}…`;
+}
+function buildBlockingTaskDescription(goalId, surfaceKind, detail) {
+    const lines = [acceptanceBlockMarker(goalId), '', `Surface kind: ${surfaceKind}`];
+    if (detail) {
+        lines.push(`Detail: ${detail}`);
+    }
+    return lines.join('\n');
+}
+function cycleTasksForGoal(db, projectId, goalId) {
+    const tagsByTask = listTagsByTaskForProject(db, projectId);
+    return listTasks(db, projectId)
+        .filter((task) => task.goalId === goalId)
+        .map((task) => serializeTask(task, tagsByTask.get(task.id) ?? []));
+}
+function emitGoalUpdated(eventBus, goalId, projectId) {
+    eventBus.emit({ type: 'goal_updated', goalId, projectId });
+}
+function recordLastVerification(at, green, kind, detail) {
+    const record = { at, green, kind };
+    if (detail) {
+        record.detail = detail;
+    }
+    return JSON.stringify(record);
+}
+export function createGoalService(deps) {
+    const { db, eventBus } = deps;
+    return {
+        create(projectId, input) {
+            if (input.status !== undefined && !isGoalStatus(input.status)) {
+                throw new InvalidGoalStatusError(input.status);
+            }
+            validateVerificationSurfaceInput(input.verificationSurface);
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            const goal = db.transaction((tx) => createGoal(tx, {
+                projectId,
+                objective: input.objective,
+                status: input.status,
+                verificationSurface: input.verificationSurface,
+                constraints: input.constraints,
+                boundaries: input.boundaries,
+                iterationPolicy: input.iterationPolicy,
+                stopCondition: input.stopCondition,
+                budget: input.budget,
+            }));
+            emitGoalUpdated(eventBus, goal.id, projectId);
+            return serializeGoal(goal);
+        },
+        get(goalId) {
+            const goal = getGoal(db, goalId);
+            if (!goal) {
+                return undefined;
+            }
+            return {
+                ...serializeGoal(goal),
+                cycle_tasks: cycleTasksForGoal(db, goal.projectId, goalId),
+            };
+        },
+        listByProject(projectId) {
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            return listGoals(db, projectId).map(serializeGoal);
+        },
+        update(goalId, input) {
+            const existing = getGoal(db, goalId);
+            if (!existing) {
+                return undefined;
+            }
+            validateVerificationSurfaceInput(input.verificationSurface);
+            const goal = db.transaction((tx) => updateGoal(tx, goalId, input));
+            if (!goal) {
+                return undefined;
+            }
+            emitGoalUpdated(eventBus, goalId, existing.projectId);
+            return serializeGoal(goal);
+        },
+        pause(goalId) {
+            const existing = getGoal(db, goalId);
+            if (!existing) {
+                return undefined;
+            }
+            if (existing.status !== 'active') {
+                throw new InvalidGoalTransitionError('Goal can only be paused from active status');
+            }
+            const goal = db.transaction((tx) => updateGoalStatus(tx, goalId, 'paused'));
+            if (!goal) {
+                return undefined;
+            }
+            emitGoalUpdated(eventBus, goalId, existing.projectId);
+            return serializeGoal(goal);
+        },
+        resume(goalId) {
+            const existing = getGoal(db, goalId);
+            if (!existing) {
+                return undefined;
+            }
+            if (existing.status !== 'paused') {
+                throw new InvalidGoalTransitionError('Goal can only be resumed from paused status');
+            }
+            const goal = db.transaction((tx) => updateGoalStatus(tx, goalId, 'active'));
+            if (!goal) {
+                return undefined;
+            }
+            emitGoalUpdated(eventBus, goalId, existing.projectId);
+            return serializeGoal(goal);
+        },
+        complete(goalId, evidence) {
+            const existing = getGoal(db, goalId);
+            if (!existing) {
+                return undefined;
+            }
+            if (existing.status === 'complete') {
+                throw new InvalidGoalTransitionError('Goal is already complete');
+            }
+            if (existing.status !== 'blocked') {
+                const incomplete = listTasks(db, existing.projectId)
+                    .filter((task) => task.goalId === goalId && task.status !== 'done')
+                    .map((task) => task.id);
+                if (incomplete.length > 0) {
+                    throw new GoalCompletionBlockedError(incomplete);
+                }
+            }
+            const surface = parseVerificationSurface(existing.verificationSurface);
+            const at = new Date().toISOString();
+            if (!surface) {
+                const goal = db.transaction((tx) => updateGoal(tx, goalId, {
+                    status: 'complete',
+                    lastVerification: recordLastVerification(at, true, null),
+                }));
+                if (!goal) {
+                    return undefined;
+                }
+                emitGoalUpdated(eventBus, goalId, existing.projectId);
+                return serializeGoal(goal);
+            }
+            if (!evidence || evidence.kind !== surface.kind) {
+                throw new GoalVerificationRequiredError(surface.kind);
+            }
+            const evaluation = evaluateEvidence(surface, evidence);
+            const lastVerification = recordLastVerification(at, evaluation.green, surface.kind, evaluation.detail);
+            if (evaluation.green) {
+                const goal = db.transaction((tx) => {
+                    const updated = updateGoal(tx, goalId, {
+                        status: 'complete',
+                        lastVerification,
+                    });
+                    if (!updated) {
+                        return undefined;
+                    }
+                    resolveBlockingTasks(tx, existing.projectId, goalId);
+                    return updated;
+                });
+                if (!goal) {
+                    return undefined;
+                }
+                emitGoalUpdated(eventBus, goalId, existing.projectId);
+                return serializeGoal(goal);
+            }
+            const goal = db.transaction((tx) => {
+                const updated = updateGoal(tx, goalId, {
+                    status: 'blocked',
+                    lastVerification,
+                });
+                if (!updated) {
+                    return undefined;
+                }
+                if (!hasUnresolvedBlockingTask(tx, existing.projectId, goalId)) {
+                    createTask(tx, {
+                        projectId: existing.projectId,
+                        goalId,
+                        label: `Fix acceptance failure: ${truncateObjective(existing.objective)}`,
+                        status: 'scope',
+                        description: buildBlockingTaskDescription(goalId, surface.kind, evaluation.detail),
+                    });
+                }
+                return updated;
+            });
+            if (!goal) {
+                return undefined;
+            }
+            emitGoalUpdated(eventBus, goalId, existing.projectId);
+            return serializeGoal(goal);
+        },
+    };
+}
+//# sourceMappingURL=goals.js.map

package/dist/services/index.d.ts

@@ -8,6 +8,7 @@ import { type NoteService } from './notes.js';
 import { type ProjectService } from './projects.js';
 import { type AgentRunService } from './agent-runs.js';
 import { type TagService } from './tags.js';
+import { type GoalService } from './goals.js';
 import { type TaskService } from './tasks.js';
 import { type TokenService } from './tokens.js';
 import { type ShareService } from './share.js';
@@ -19,6 +20,7 @@ export type ServicesDeps = {
 export type Services = {
     eventBus: EventBus;
     projectService: ProjectService;
+    goalService: GoalService;
     taskService: TaskService;
     tagService: TagService;
     canvasService: CanvasService;

package/dist/services/index.js

@@ -7,6 +7,7 @@ import { createNoteService } from './notes.js';
 import { createProjectService } from './projects.js';
 import { createAgentRunService } from './agent-runs.js';
 import { createTagService } from './tags.js';
+import { createGoalService } from './goals.js';
 import { createTaskService } from './tasks.js';
 import { createTokenService } from './tokens.js';
 import { createShareService } from './share.js';
@@ -14,6 +15,7 @@ import { createSyncService } from './sync.js';
 export function createServices(deps) {
     const eventBus = deps.eventBus ?? createEventBus();
     const projectService = createProjectService({ db: deps.db, eventBus });
+    const goalService = createGoalService({ db: deps.db, eventBus });
     const taskService = createTaskService({ db: deps.db, eventBus });
     const tagService = createTagService({ db: deps.db, eventBus });
     const canvasService = createCanvasService({ db: deps.db, eventBus });
@@ -28,6 +30,7 @@ export function createServices(deps) {
     return {
         eventBus,
         projectService,
+        goalService,
         taskService,
         tagService,
         canvasService,

package/dist/services/notes.js

@@ -1,4 +1,4 @@
-import { createNote as dbCreateNote, deleteNote as dbDeleteNote, getNote as dbGetNote, getProject, listNotes as dbListNotes, updateNote as dbUpdateNote, } from '@plandesk/db';
+import { createNote as dbCreateNote, deleteCommentsByTarget, deleteNote as dbDeleteNote, getNote as dbGetNote, getProject, listNotes as dbListNotes, updateNote as dbUpdateNote, } from '@plandesk/db';
 import { serializeNote } from '../serialize.js';
 export class InvalidNoteError extends Error {
     constructor(message) {
@@ -66,6 +66,7 @@ export function createNoteService(deps) {
             if (!deleted) {
                 return false;
             }
+            deleteCommentsByTarget(db, 'note', id);
             eventBus.emit({ type: 'note_updated', noteId: id, projectId: existing.projectId });
             return true;
         },

package/dist/services/projects.js

@@ -1,4 +1,4 @@
-import { clearDocumentParentRefsByProject, clearFolderParentRefsByProject, createDocument, createEdge, createProject as dbCreateProject, createTask, deleteAgentRun, deleteAgentRunEventsByRunId, deleteCommentsByProjectId, deleteDocumentsByProjectId, deleteFoldersByProjectId, deleteNotesByProjectId, deleteEdgesByProjectId, deleteShareSubmissionsByProjectId, deleteSharesByProjectId, deleteTagsByProjectId, deleteSyncRemoteByProjectId, deleteSyncStateByProjectId, deleteProject as dbDeleteProject, deleteTasksByProjectId, getProject as dbGetProject, InvalidTaskStatusError, isTaskStatus, listAgentRuns, listProjects as dbListProjects, listTasks, updateProject as dbUpdateProject, } from '@plandesk/db';
+import { clearDocumentParentRefsByProject, clearFolderParentRefsByProject, createDocument, createEdge, createProject as dbCreateProject, createTask, deleteAgentRun, deleteAgentRunEventsByRunId, deleteCommentsByProjectId, deleteDocumentsByProjectId, deleteFoldersByProjectId, deleteNotesByProjectId, deleteEdgesByProjectId, deleteGoalsByProjectId, deleteShareSubmissionsByProjectId, deleteSharesByProjectId, deleteTagsByProjectId, deleteSyncRemoteByProjectId, deleteSyncStateByProjectId, deleteProject as dbDeleteProject, deleteTasksByProjectId, getOrCreateDefaultGoal, getProject as dbGetProject, InvalidTaskStatusError, isTaskStatus, listAgentRuns, listProjects as dbListProjects, listTasks, updateProject as dbUpdateProject, } from '@plandesk/db';
 import { emptyTaskStatusSummary, serializeDocument, serializeEdge, serializeProject, serializeProjectDetail, serializeTask, } from '../serialize.js';
 export class InvalidScaffoldError extends Error {
     constructor(message) {
@@ -94,6 +94,7 @@ export function createProjectService(deps) {
                 deleteNotesByProjectId(tx, id);
                 deleteTagsByProjectId(tx, id);
                 deleteTasksByProjectId(tx, id);
+                deleteGoalsByProjectId(tx, id);
                 deleteShareSubmissionsByProjectId(tx, id);
                 deleteSyncStateByProjectId(tx, id);
                 deleteSyncRemoteByProjectId(tx, id);
@@ -116,11 +117,13 @@ export function createProjectService(deps) {
                     description: input.description,
                 });
                 projectId = project.id;
+                const defaultGoal = getOrCreateDefaultGoal(tx, project.id);
                 input.tasks.forEach((taskInput, i) => {
                     const x = taskInput.x ?? (i % 4) * 240;
                     const y = taskInput.y ?? Math.floor(i / 4) * 160;
                     const task = createTask(tx, {
                         projectId: project.id,
+                        goalId: defaultGoal.id,
                         label: taskInput.label,
                         status: taskInput.status,
                         description: taskInput.description,

package/dist/services/sync.d.ts

@@ -1,4 +1,4 @@
-import { type Db, type ShareSubmission, type ShareSubmissionStatus, type TaskStatus } from '@plandesk/db';
+import { type Db, type ShareSubmission, type ShareSubmissionStatus } from '@plandesk/db';
 import type { EventBus } from '../events.js';
 import type { ShareService } from './share.js';
 import type { TaskService } from './tasks.js';
@@ -11,6 +11,9 @@ export declare class SyncUnauthorizedError extends Error {
 export declare class InvalidTriageError extends Error {
     constructor(message?: string);
 }
+export declare class InvalidTriageInputError extends Error {
+    constructor(message: string);
+}
 export type SyncRemote = {
     serverUrl: string;
     globalProjectId: string;
@@ -65,9 +68,8 @@ export declare function createSyncService(deps: SyncServiceDeps): {
     getRemote(projectId: string): SyncRemote | undefined;
     triage(submissionId: string, action: "accept" | "reject", remote: SyncRemote, asTask?: {
         label?: string;
-        status?: TaskStatus;
         description?: string;
-    }): Promise<SerializedSubmission>;
+    }, linkTaskId?: string): Promise<SerializedSubmission>;
     watchPush(projectId: string, remote: SyncRemote, opts?: WatchPushOptions): WatchPushController;
 };
 export type SyncService = ReturnType<typeof createSyncService>;

package/dist/services/sync.js

@@ -18,6 +18,12 @@ export class InvalidTriageError extends Error {
         this.name = 'InvalidTriageError';
     }
 }
+export class InvalidTriageInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidTriageInputError';
+    }
+}
 export function serializeSubmission(row) {
     return {
         id: row.id,
@@ -252,19 +258,56 @@ export function createSyncService(deps) {
                 syncToken: row.syncToken,
             };
         },
-        async triage(submissionId, action, remote, asTask) {
+        async triage(submissionId, action, remote, asTask, linkTaskId) {
+            if (asTask !== undefined && linkTaskId !== undefined) {
+                throw new InvalidTriageInputError('as_task and link_task_id are mutually exclusive');
+            }
             const submission = dbGetSubmission(db, submissionId);
             if (submission === undefined) {
                 throw new InvalidTriageError();
             }
             if (submission.status !== 'pending') {
+                // Idempotent retry recovery: a prior triage may have committed the terminal
+                // status locally but failed to ack the remote (sync server briefly down),
+                // leaving local/remote divergence with no recovery path. Re-ack when the
+                // retry's action matches the recorded outcome; ack is idempotent remotely.
+                if ((action === 'accept' && submission.status === 'accepted') ||
+                    (action === 'reject' && submission.status === 'rejected')) {
+                    await ackSubmission(remote, submissionId, submission.status);
+                }
                 return serializeSubmission(submission);
             }
             const projectId = submission.projectId;
+            if (action === 'accept' && linkTaskId !== undefined) {
+                const existingTask = taskService.get(linkTaskId);
+                if (existingTask === undefined || existingTask.project_id !== projectId) {
+                    throw new InvalidTriageInputError('link_task_id does not reference an existing task in this project');
+                }
+                const updated = setSubmissionStatus(db, submissionId, {
+                    status: 'accepted',
+                    linkedTaskId: linkTaskId,
+                });
+                if (updated === undefined) {
+                    throw new InvalidTriageError();
+                }
+                eventBus.emit({ type: 'submissions_pulled', projectId });
+                await ackSubmission(remote, submissionId, 'accepted');
+                return serializeSubmission(updated);
+            }
             if (action === 'accept') {
+                // Triage never releases work to `todo`: the scope->todo gate is the human's
+                // own board action. Every accepted submission lands in `scope`, regardless of
+                // caller — enforced here at the single service chokepoint so both the HTTP
+                // route and the MCP tool are covered.
+                //
+                // create + setSubmissionStatus run as two synchronous steps, but the submission
+                // was validated to exist immediately above with no intervening await, so under
+                // better-sqlite3's single-connection sync model the row cannot vanish and
+                // setSubmissionStatus cannot spuriously return undefined. taskService.create
+                // self-transacts, so an outer transaction here is neither possible nor needed.
                 const task = taskService.create(projectId, {
                     label: asTask?.label ?? submission.title,
-                    status: asTask?.status ?? 'todo',
+                    status: 'scope',
                     description: asTask?.description ?? buildDesc(submission),
                 });
                 if (task === undefined) {

package/dist/services/tasks.d.ts

@@ -2,7 +2,10 @@ import { type Db, type TaskStatus } from '@plandesk/db';
 import type { EventBus } from '../events.js';
 import { serializeTask, type PaginationParams } from '../serialize.js';
 type SerializedTask = ReturnType<typeof serializeTask>;
-export type NextActionableReason = 'ok' | 'no_tasks' | 'no_todo_tasks' | 'all_blocked';
+export declare class InvalidGoalReferenceError extends Error {
+    constructor(goalId: string);
+}
+export type NextActionableReason = 'ok' | 'no_tasks' | 'no_todo_tasks' | 'all_blocked' | 'no_active_goal' | 'multiple_active_goals';
 export type NextActionableResult = {
     next_task: SerializedTask | null;
     reason: NextActionableReason;
@@ -23,6 +26,7 @@ export type CreateTaskInput = {
     y?: number;
     assignee?: string | null;
     dueDate?: Date | null;
+    goalId?: string;
     tags?: string[];
 };
 export type UpdateTaskInput = {
@@ -42,6 +46,7 @@ export declare function createTaskService(deps: TaskServiceDeps): {
         tags?: import("../serialize.js").SerializedTag[] | undefined;
         id: string;
         project_id: string;
+        goal_id: string;
         label: string;
         status: "scope" | "todo" | "in_progress" | "done" | "backlog";
         description: string | null;
@@ -56,6 +61,7 @@ export declare function createTaskService(deps: TaskServiceDeps): {
         tags?: import("../serialize.js").SerializedTag[] | undefined;
         id: string;
         project_id: string;
+        goal_id: string;
         label: string;
         status: "scope" | "todo" | "in_progress" | "done" | "backlog";
         description: string | null;
@@ -70,6 +76,7 @@ export declare function createTaskService(deps: TaskServiceDeps): {
         tags?: import("../serialize.js").SerializedTag[] | undefined;
         id: string;
         project_id: string;
+        goal_id: string;
         label: string;
         status: "scope" | "todo" | "in_progress" | "done" | "backlog";
         description: string | null;
@@ -84,6 +91,7 @@ export declare function createTaskService(deps: TaskServiceDeps): {
         tags?: import("../serialize.js").SerializedTag[] | undefined;
         id: string;
         project_id: string;
+        goal_id: string;
         label: string;
         status: "scope" | "todo" | "in_progress" | "done" | "backlog";
         description: string | null;
@@ -96,6 +104,7 @@ export declare function createTaskService(deps: TaskServiceDeps): {
     } | undefined;
     delete(id: string): boolean;
     nextActionable(projectId: string, filter?: {
+        goalId?: string;
         tags?: string[];
     }): NextActionableResult | undefined;
 };

package/dist/services/tasks.js

@@ -1,6 +1,12 @@
-import { createTag, createTask, deleteEdgesByTaskId, deleteTask as dbDeleteTask, deleteTaskTagsByTaskId, getProject, getTagByName, getTask, InvalidTaskStatusError, isTaskStatus, listEdges, listTagsByTaskForProject, listTagsForTask, listTasks, nullDocumentsLinkedTask, setTaskTags, taskIdsWithAnyTagName, updateTask, } from '@plandesk/db';
+import { createTag, createTask, deleteCommentsByTarget, deleteEdgesByTaskId, deleteTask as dbDeleteTask, deleteTaskTagsByTaskId, getOrCreateDefaultGoal, getProject, listGoals, getTagByName, getTask, InvalidTaskStatusError, isTaskStatus, listEdges, listTagsByTaskForProject, listTagsForTask, listTasks, nullDocumentsLinkedTask, setTaskTags, taskIdsWithAnyTagName, updateTask, } from '@plandesk/db';
 import { serializeTask } from '../serialize.js';
 import { normalizeTagName } from './tags.js';
+export class InvalidGoalReferenceError extends Error {
+    constructor(goalId) {
+        super(`Goal ${goalId} does not exist in this project`);
+        this.name = 'InvalidGoalReferenceError';
+    }
+}
 // depends_on: prerequisite = to, dependent = from. All other labels: prerequisite = from, dependent = to.
 function prerequisiteAndDependent(edge) {
     if (edge.fromTaskId === edge.toTaskId) {
@@ -61,9 +67,15 @@ export function createTaskService(deps) {
             if (!project) {
                 return undefined;
             }
+            if (input.goalId !== undefined &&
+                !listGoals(db, projectId).some((g) => g.id === input.goalId)) {
+                throw new InvalidGoalReferenceError(input.goalId);
+            }
             const { task, tags } = db.transaction((tx) => {
+                const goalId = input.goalId ?? getOrCreateDefaultGoal(tx, projectId).id;
                 const row = createTask(tx, {
                     projectId,
+                    goalId,
                     label: input.label,
                     status: input.status,
                     description: input.description,
@@ -120,6 +132,7 @@ export function createTaskService(deps) {
             }
             const projectId = task.projectId;
             db.transaction((tx) => {
+                deleteCommentsByTarget(tx, 'task', id);
                 deleteEdgesByTaskId(tx, id);
                 nullDocumentsLinkedTask(tx, id);
                 deleteTaskTagsByTaskId(tx, id);
@@ -128,14 +141,28 @@ export function createTaskService(deps) {
             eventBus.emit({ type: 'canvas_updated', projectId });
             return true;
         },
-        // filter.tags (OR semantics): only tasks carrying ANY of the given tag names
-        // are candidates for next_task / blocked; prerequisite completion is still
-        // evaluated against all tasks in the project.
+        // filter.goalId scopes candidates to one goal; when omitted, the project's sole
+        // active goal is resolved. filter.tags (OR semantics) composes with goal scope;
+        // prerequisite completion is still evaluated against all tasks in the project.
         nextActionable(projectId, filter = {}) {
             const project = getProject(db, projectId);
             if (!project) {
                 return undefined;
             }
+            let goalId = filter.goalId;
+            if (goalId === undefined) {
+                const active = listGoals(db, projectId).filter((goal) => goal.status === 'active');
+                if (active.length === 0) {
+                    return { next_task: null, reason: 'no_active_goal', blocked: [] };
+                }
+                if (active.length > 1) {
+                    return { next_task: null, reason: 'multiple_active_goals', blocked: [] };
+                }
+                goalId = active[0]?.id;
+            }
+            else if (!listGoals(db, projectId).some((goal) => goal.id === goalId)) {
+                return undefined;
+            }
             const tasks = listTasks(db, projectId).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
             const edges = listEdges(db, projectId);
             const taskById = new Map(tasks.map((task) => [task.id, task]));
@@ -160,7 +187,9 @@ export function createTaskService(deps) {
             if (tasks.length === 0) {
                 return { next_task: null, reason: 'no_tasks', blocked: [] };
             }
-            const todoTasks = tasks.filter((task) => task.status === 'todo' && (tagMatches === undefined || tagMatches.has(task.id)));
+            const todoTasks = tasks.filter((task) => task.goalId === goalId &&
+                task.status === 'todo' &&
+                (tagMatches === undefined || tagMatches.has(task.id)));
             if (todoTasks.length === 0) {
                 return { next_task: null, reason: 'no_todo_tasks', blocked: [] };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plandesk/api",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "exports": {
     ".": {
@@ -18,7 +18,7 @@
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^3.2.6",
-    "@plandesk/db": "0.6.0",
+    "@plandesk/db": "0.8.0",
     "@plandesk/sync-server": "0.5.0"
   },
   "dependencies": {