@agent-plan/core 0.2.28 → 0.3.0

package/dist/project-context.js

@@ -0,0 +1,295 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { AcceptedDecisionSchema, DescriptionRefSchema, MacroTaskSchema, TimestampSchema, } from "./schema.js";
+import { renderAcceptedDecisionsSection } from "./task-context.js";
+export const PROJECT_CONTEXT_DELIVERY_VERSION = 1;
+export const DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS = 16_000;
+export const ProjectContextReadAttestationSchema = z.object({
+    sessionId: z.string().min(1),
+    createdAt: TimestampSchema,
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export const ProjectContextReadStateDocumentSchema = z.object({
+    version: z.literal(PROJECT_CONTEXT_DELIVERY_VERSION).default(PROJECT_CONTEXT_DELIVERY_VERSION),
+    sessionInfo: z.array(ProjectContextReadAttestationSchema).default([]),
+});
+const ProjectContextRequirementSchema = z.object({
+    id: z.string(),
+    title: z.string().min(1),
+    description: z.string().default(""),
+    macroTasks: z.array(MacroTaskSchema).default([]),
+    linkedPhaseIds: z.array(z.string().min(1)).default([]),
+    createdAt: TimestampSchema,
+    updatedAt: TimestampSchema,
+});
+export const ProjectContextSnapshotSchema = z.object({
+    version: z.literal(PROJECT_CONTEXT_DELIVERY_VERSION),
+    project: z.object({
+        name: z.string().min(1),
+        goal: z.string(),
+        description: z.string(),
+        descriptionRef: DescriptionRefSchema.optional(),
+        scope: z.array(z.string().min(1)),
+        outOfScope: z.array(z.string().min(1)),
+        technologies: z.array(z.string().min(1)),
+        tools: z.array(z.string().min(1)),
+        contentLanguage: z.string(),
+        chatLanguage: z.string(),
+        projectGuidelines: z.object({
+            content: z.string(),
+            updatedAt: z.string(),
+        }),
+        acceptedDecisions: z.array(AcceptedDecisionSchema),
+    }),
+    requirements: z.array(ProjectContextRequirementSchema),
+});
+export const ProjectContextChunkSchema = z.object({
+    version: z.literal(PROJECT_CONTEXT_DELIVERY_VERSION),
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    status: z.literal("partial"),
+    complete: z.literal(false),
+    truncated: z.boolean(),
+    deliveredChunks: z.literal(1),
+    index: z.number().int().nonnegative(),
+    totalChunks: z.number().int().positive(),
+    cursor: z.string().min(1).optional(),
+    nextCursor: z.string().min(1).optional(),
+    content: z.string(),
+});
+export class ProjectContextDeliveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ProjectContextDeliveryError";
+        this.code = code;
+    }
+}
+/** Build the content-only project snapshot used by every harness. */
+export function createProjectContextSnapshot(project, requirements) {
+    return ProjectContextSnapshotSchema.parse({
+        version: PROJECT_CONTEXT_DELIVERY_VERSION,
+        project: {
+            name: project.name,
+            goal: project.goal,
+            description: project.description,
+            ...(project.descriptionRef ? { descriptionRef: project.descriptionRef } : {}),
+            scope: project.scope,
+            outOfScope: project.outOfScope,
+            technologies: project.technologies,
+            tools: project.tools,
+            contentLanguage: project.contentLanguage,
+            chatLanguage: project.chatLanguage,
+            projectGuidelines: {
+                content: project.projectGuidelines.content,
+                updatedAt: project.projectGuidelines.updatedAt,
+            },
+            acceptedDecisions: project.acceptedDecisions,
+        },
+        requirements: requirements.requirements.map((requirement) => ({
+            id: requirement.id,
+            title: requirement.title,
+            description: requirement.description,
+            macroTasks: requirement.macroTasks,
+            linkedPhaseIds: requirement.linkedPhaseIds,
+            createdAt: requirement.createdAt,
+            updatedAt: requirement.updatedAt,
+        })),
+    });
+}
+export function serializeProjectContext(snapshot) {
+    return JSON.stringify(ProjectContextSnapshotSchema.parse(snapshot));
+}
+export function projectContextFingerprint(snapshot) {
+    return createHash("sha256").update(serializeProjectContext(snapshot), "utf8").digest("hex");
+}
+/**
+ * Split canonical JSON without dropping data. Individual chunks never assert
+ * completeness; only verifyProjectContextChunks can produce complete evidence.
+ */
+export function createProjectContextChunks(snapshot, maxChars = DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS) {
+    if (!Number.isInteger(maxChars) || maxChars < 1) {
+        throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_INVALID", "Project-context chunk size must be a positive integer.");
+    }
+    const serialized = serializeProjectContext(snapshot);
+    const fingerprint = projectContextFingerprint(snapshot);
+    const parts = serialized.length === 0
+        ? [""]
+        : Array.from({ length: Math.ceil(serialized.length / maxChars) }, (_, index) => serialized.slice(index * maxChars, (index + 1) * maxChars));
+    return parts.map((content, index) => ({
+        version: PROJECT_CONTEXT_DELIVERY_VERSION,
+        fingerprint,
+        status: "partial",
+        complete: false,
+        truncated: parts.length > 1,
+        deliveredChunks: 1,
+        index,
+        totalChunks: parts.length,
+        ...(parts.length > 1 ? { cursor: `${fingerprint}:${index}` } : {}),
+        ...(index + 1 < parts.length ? { nextCursor: `${fingerprint}:${index + 1}` } : {}),
+        content,
+    }));
+}
+/** Verify an exact, ordered, complete chunk sequence and reconstruct its DTO. */
+export function verifyProjectContextChunks(chunks) {
+    if (chunks.length === 0) {
+        throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_INCOMPLETE", "Project-context delivery contains no chunks.");
+    }
+    let parsedChunks;
+    try {
+        parsedChunks = ProjectContextChunkSchema.array().parse(chunks);
+    }
+    catch (error) {
+        throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_INVALID", `Project-context chunk metadata is invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const first = parsedChunks[0];
+    const receivedIndexes = parsedChunks.map((chunk) => chunk.index);
+    if (parsedChunks.length !== first.totalChunks || parsedChunks.some((chunk, index) => chunk.index !== index)) {
+        throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_INCOMPLETE", `Project-context delivery is incomplete: received ordered chunks [${receivedIndexes.join(", ")}], expected indexes 0 through ${first.totalChunks - 1}.`);
+    }
+    const chunked = first.totalChunks > 1;
+    if (parsedChunks.some((chunk) => chunk.version !== PROJECT_CONTEXT_DELIVERY_VERSION
+        || chunk.fingerprint !== first.fingerprint
+        || chunk.totalChunks !== first.totalChunks
+        || chunk.truncated !== chunked
+        || (chunked ? chunk.cursor !== `${first.fingerprint}:${chunk.index}` : chunk.cursor !== undefined)
+        || (chunk.index + 1 < chunk.totalChunks
+            ? chunk.nextCursor !== `${first.fingerprint}:${chunk.index + 1}`
+            : chunk.nextCursor !== undefined))) {
+        throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_INVALID", "Project-context chunks have inconsistent version, fingerprint, truncation, cursor, or sequence metadata.");
+    }
+    const serialized = parsedChunks.map((chunk) => chunk.content).join("");
+    let snapshot;
+    try {
+        snapshot = ProjectContextSnapshotSchema.parse(JSON.parse(serialized));
+    }
+    catch (error) {
+        throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_INVALID", `Project-context chunks do not reconstruct a valid canonical snapshot: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const fingerprint = projectContextFingerprint(snapshot);
+    if (fingerprint !== first.fingerprint) {
+        throw new ProjectContextDeliveryError("PROJECT_CONTEXT_DELIVERY_INVALID", "Project-context fingerprint does not match the reconstructed canonical snapshot.");
+    }
+    return {
+        snapshot,
+        chunks: parsedChunks,
+        evidence: {
+            version: PROJECT_CONTEXT_DELIVERY_VERSION,
+            fingerprint,
+            status: "complete",
+            complete: true,
+            truncated: false,
+            chunked,
+            deliveredChunks: parsedChunks.length,
+            totalChunks: parsedChunks.length,
+            serializedChars: serialized.length,
+        },
+    };
+}
+export function createCompleteProjectContextDelivery(project, requirements, maxChars = DEFAULT_PROJECT_CONTEXT_CHUNK_CHARS) {
+    const snapshot = createProjectContextSnapshot(project, requirements);
+    return verifyProjectContextChunks(createProjectContextChunks(snapshot, maxChars));
+}
+export function projectContextReadState(snapshot, attestations, sessionId) {
+    const normalizedSessionId = sessionId.trim();
+    if (!normalizedSessionId)
+        return "missing";
+    const attestation = attestations?.find((entry) => entry.sessionId === normalizedSessionId);
+    if (!attestation)
+        return "missing";
+    return attestation.fingerprint === projectContextFingerprint(snapshot) ? "valid" : "stale";
+}
+/**
+ * Non-blocking task-start advisory for when project-level context (delivered
+ * through explicit planner load) has drifted since this session's last
+ * attested read. Task-start's own gates stay scoped to feature/phase/task
+ * context (P102(F005)/T404 keeps that delivery separate and un-duplicated);
+ * this only signals that a targeted planner-load refresh is due, without
+ * blocking the task from starting.
+ */
+export function projectContextStaleAdvisory(state) {
+    if (state !== "stale")
+        return "";
+    return "\n\n⚠️ Project-context advisory: project-level context (description, scope, technologies, tools, languages, Requirements, or project Accepted Decisions) changed since your last planner-load. Call planner-load again to refresh it before relying on it.";
+}
+/** Render the complete snapshot without applying a transport truncation policy. */
+export function renderProjectContext(snapshot) {
+    const { project, requirements } = snapshot;
+    const lines = [
+        `Project context v${snapshot.version}`,
+        `Name: ${project.name}`,
+        `Short description: ${project.description || "(not set)"}`,
+        `Description reference: ${project.descriptionRef ?? "(not set)"}`,
+        `Goal: ${project.goal || "(not set)"}`,
+        `Scope: ${project.scope.join("; ") || "(none)"}`,
+        `Out of scope: ${project.outOfScope.join("; ") || "(none)"}`,
+        `Technologies: ${project.technologies.join("; ") || "(none)"}`,
+        `Tools: ${project.tools.join("; ") || "(none)"}`,
+        `Content language: ${project.contentLanguage || "(not set)"}`,
+        `Chat language: ${project.chatLanguage || "(not set)"}`,
+        "",
+        "Project Guidelines:",
+        project.projectGuidelines.content || "(none)",
+        `Guidelines updated at: ${project.projectGuidelines.updatedAt || "(not set)"}`,
+        "",
+        `Requirements (${requirements.length}):`,
+    ];
+    if (requirements.length === 0) {
+        lines.push("  - None.");
+    }
+    else {
+        for (const requirement of requirements) {
+            lines.push(`  - ${requirement.id} — ${requirement.title}`);
+            lines.push(`    Description: ${requirement.description || "(not provided)"}`);
+            lines.push(`    Linked phases: ${requirement.linkedPhaseIds.join(", ") || "None"}`);
+            lines.push(`    Created at: ${requirement.createdAt}`);
+            lines.push(`    Updated at: ${requirement.updatedAt}`);
+            lines.push(`    Macro tasks (${requirement.macroTasks.length}):`);
+            if (requirement.macroTasks.length === 0)
+                lines.push("      - None.");
+            for (const macroTask of requirement.macroTasks) {
+                lines.push(`      - ${macroTask.id} — ${macroTask.title} (${macroTask.status})`);
+                lines.push(`        Description: ${macroTask.description || "(not provided)"}`);
+                lines.push(`        Created at: ${macroTask.createdAt}`);
+                lines.push(`        Updated at: ${macroTask.updatedAt}`);
+            }
+        }
+    }
+    lines.push("", renderAcceptedDecisionsSection("Project Accepted Decisions", project.acceptedDecisions));
+    return lines.join("\n");
+}
+/**
+ * Build the reply for an explicit planner-load project-context delivery.
+ * `delivery` must come straight from `PlanStore.loadProjectContextDelivery`.
+ * This function only shapes the reply and never mutates; the caller is
+ * responsible for calling `PlanStore.recordProjectContextRead` with
+ * `delivery.chunks` immediately afterward, and only when, this returns
+ * `structured.contextComplete === true`.
+ */
+export function buildProjectContextLoadReply(delivery, maxChars) {
+    if (delivery.chunks.length > 1) {
+        return {
+            text: `Project context exceeds the ${maxChars}-character single-response bound (${delivery.evidence.serializedChars} characters across ${delivery.evidence.totalChunks} chunks). Project-level context (description, scope, out-of-scope, technologies, tools, languages, Project Guidelines, every Requirement, and every project Accepted Decision) was NOT delivered this turn, and the read was not attested.`,
+            structured: {
+                loaded: false,
+                contextComplete: false,
+                fingerprint: delivery.evidence.fingerprint,
+                totalChunks: delivery.evidence.totalChunks,
+                serializedChars: delivery.evidence.serializedChars,
+                nextActions: [
+                    `Retry planner-load with a larger maxChars (at least ${delivery.evidence.serializedChars}) so the complete project context fits in one response.`,
+                    "Do not treat this response as a complete project-context read: REQUIREMENTS_READ_REQUIRED and equivalent gates remain unsatisfied until a complete read is attested.",
+                ],
+            },
+        };
+    }
+    return {
+        text: renderProjectContext(delivery.snapshot),
+        structured: {
+            loaded: true,
+            contextComplete: true,
+            project: delivery.snapshot.project,
+            requirements: delivery.snapshot.requirements,
+            fingerprint: delivery.evidence.fingerprint,
+        },
+    };
+}

package/dist/recap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,GAAE,YAAiB,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4QhH"}
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,GAAE,YAAiB,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2ShH"}

package/dist/recap.js

@@ -1,5 +1,7 @@
 import { formatPhaseRef, formatTwoDigitNumber } from "./naming.js";
 import { buildPhaseWorkMap } from "./task-context.js";
+import { recommendNextTask } from "./task-selection.js";
+import { listOpenPhaseWork, openPhaseWorkLines } from "./stranded-phase.js";
 const fref = (n) => `F${formatTwoDigitNumber(n)}`;
 const tref = (n) => `T${formatTwoDigitNumber(n)}`;
 /**
@@ -74,6 +76,15 @@ export async function buildRecap(st, web = {}, opts = {}) {
     lines.push(italian
         ? `Avanzamento: feature ${doneF}/${totalF} completate (${activeF} attive) · fasi ${doneP}/${totalP} completate (${activeP} attive) · task ${doneT}/${totalT} completati (${activeT} attivi, ${checkpointedT} con checkpoint)`
         : `Progress: Features ${doneF}/${totalF} done (${activeF} active) · Phases ${doneP}/${totalP} done (${activeP} active) · Tasks ${doneT}/${totalT} done (${activeT} active, ${checkpointedT} with checkpoints)`);
+    // P104(F005)/T422: a phase left in-progress with no active task had no
+    // signal anywhere cheap to read — this states it, priority-ordered, every
+    // recap, instead of leaving it discoverable only by paying for
+    // task_recommend's full claim evidence.
+    const openPhaseWork = listOpenPhaseWork(phases, feats);
+    const openPhaseWorkText = openPhaseWorkLines(openPhaseWork);
+    if (openPhaseWorkText) {
+        lines.push("", italian ? "In-progress: fasi con lavoro rimanente (ordine di priorità):" : "In-progress phases with work left (priority order):", openPhaseWorkText);
+    }
     if (activeTasks.length > 1) {
         const conflicts = activeTasks.map(({ phase, task }) => {
             const feature = feats.find((entry) => entry.id === phase.featureId);
@@ -159,6 +170,22 @@ export async function buildRecap(st, web = {}, opts = {}) {
                 : `⚠️ nextSteps are free-text from resume.json — may be stale; verify against current state before acting.`);
         lines.push(staleNote);
     }
+    else if (!planComplete) {
+        // No active task, resume advisory, checkpoint, pending handoff, or
+        // legacy resume.json nextSteps: every branch above already names a
+        // concrete ref to act on, but this, the ordinary case, previously fell
+        // through with no "Next step" line at all — the reader had to go call
+        // task_recommend to learn what the recap already knew (P104(F005)/T421).
+        const recommendation = recommendNextTask(feats, phases, plan.project.workDeviations);
+        if (recommendation.kind === "priority" && recommendation.candidate) {
+            const { candidate } = recommendation;
+            const candidateFeature = feats.find((entry) => entry.id === candidate.phase.featureId);
+            const ref = `${formatPhaseRef(candidate.phase.number, candidateFeature?.number)}/${tref(candidate.task.number)}`;
+            lines.push(italian
+                ? `Prossimo step: ${ref} — ${candidate.task.title} (priorità più bassa pronta). Avvia con ${taskStartCmd} ${ref}.`
+                : `Next step: ${ref} — ${candidate.task.title} (lowest-priority ready task). Start with ${taskStartCmd} ${ref}.`);
+        }
+    }
     if (pendingResume) {
         const feature = feats.find((entry) => entry.id === pendingResume.phase.featureId);
         const ref = `${formatPhaseRef(pendingResume.phase.number, feature?.number)}/${tref(pendingResume.task.number)}`;

package/dist/recommend-reply.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared reply shaping for `planner-task-recommend` / `task_recommend`.
+ *
+ * Measured on this repository's own planner (P104(F005)/T419): the raw
+ * result of `recommendNextWork` was 48,869 characters, because both
+ * adapters spread `selection` whole into the reply. `selection.candidate`
+ * carries full `Feature`/`Phase`/`Task` entities — every sibling task's
+ * complete description and completion summary, every checklist, every
+ * statusLog entry, the whole persisted handoff body — to answer a question
+ * whose only useful payload is "which task, and why." The compact fields
+ * this builder already assembles (`taskId`, `phaseId`, `featureId`,
+ * `activeTask`, `nextFeature`, `nextPhase`, `nextTask`, `claims`) carry the
+ * answer; nothing reads the fat.
+ *
+ * Placed in plan-core per AGENTS.md rule 4: both adapters call
+ * `recommendNextWork` themselves (the pure selector stays adapter-visible
+ * for their own routing), then hand the result here once so neither can
+ * drift from the other. Follows the shape of handoff-reply.ts and
+ * mutation-reply.ts: one `text`/`structured` reply, built once, consumed by
+ * every adapter.
+ */
+import type { Feature } from "./schema.js";
+import type { NextWorkRecommendation } from "./task-selection.js";
+export interface RecommendReply {
+    text: string;
+    structured: Record<string, unknown>;
+}
+/** What `selection.candidate` shrinks to: the composite ref and title a
+ * caller acts on, not the full entities behind them. */
+export interface RecommendationCandidateSummary {
+    ref: string;
+    taskId: string;
+    phaseId: string;
+    featureId?: string;
+    title: string;
+    status: string;
+}
+/**
+ * Build the reply for `planner-task-recommend` / `task_recommend`, covering
+ * both the candidate and no-candidate branches through one shared shape.
+ *
+ * `kind`, `reason`, `taskId`, `phaseId`, `featureId`, `deviation`,
+ * `activeTask`, `nextFeature`, `nextPhase`, `nextTask`, `claims`, and the
+ * no-candidate branch's `activeTaskIds` keep their exact prior shape and
+ * position — the lifecycle protocol and the recommendation claims contract
+ * read those fields. Only `selection.candidate` (and, symmetrically,
+ * `selection.activeCandidates` on the conflict branch) is replaced with
+ * bounded summaries instead of full entities.
+ */
+export declare function buildRecommendationReply(result: NextWorkRecommendation, features: Feature[]): RecommendReply;
+//# sourceMappingURL=recommend-reply.d.ts.map

package/dist/recommend-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-reply.d.ts","sourceRoot":"","sources":["../src/recommend-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,sBAAsB,EAAiB,MAAM,qBAAqB,CAAC;AAEjF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;wDACwD;AACxD,MAAM,WAAW,8BAA8B;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAwBD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,sBAAsB,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,cAAc,CAsD5G"}

package/dist/recommend-reply.js

@@ -0,0 +1,84 @@
+import { featureNumberOfPhase, formatPhaseRef } from "./naming.js";
+function compositeTaskRef(candidate, features) {
+    const featureNumber = featureNumberOfPhase(candidate.phase, features);
+    return `${formatPhaseRef(candidate.phase.number, featureNumber)}/T${String(candidate.task.number).padStart(3, "0")}`;
+}
+function summarizeCandidate(candidate, features) {
+    return {
+        ref: compositeTaskRef(candidate, features),
+        taskId: candidate.task.id,
+        phaseId: candidate.phase.id,
+        ...(candidate.feature?.id ? { featureId: candidate.feature.id } : {}),
+        title: candidate.task.title,
+        status: candidate.task.status,
+    };
+}
+function renderClaimsText(claims) {
+    return claims.length
+        ? `\nClaims:\n${claims.map((claim) => `- ${claim.kind} (${claim.source}): ${claim.ref || claim.title} — ${claim.reason}`).join("\n")}`
+        : "";
+}
+/**
+ * Build the reply for `planner-task-recommend` / `task_recommend`, covering
+ * both the candidate and no-candidate branches through one shared shape.
+ *
+ * `kind`, `reason`, `taskId`, `phaseId`, `featureId`, `deviation`,
+ * `activeTask`, `nextFeature`, `nextPhase`, `nextTask`, `claims`, and the
+ * no-candidate branch's `activeTaskIds` keep their exact prior shape and
+ * position — the lifecycle protocol and the recommendation claims contract
+ * read those fields. Only `selection.candidate` (and, symmetrically,
+ * `selection.activeCandidates` on the conflict branch) is replaced with
+ * bounded summaries instead of full entities.
+ */
+export function buildRecommendationReply(result, features) {
+    const { selection } = result;
+    const claimsText = renderClaimsText(result.claims);
+    if (!selection.candidate) {
+        const activeCandidates = selection.activeCandidates ?? [];
+        return {
+            text: `No work recommendation: ${selection.reason}${claimsText}`,
+            structured: {
+                kind: selection.kind,
+                reason: selection.reason,
+                activeTaskIds: activeCandidates.map((candidate) => candidate.task.id),
+                activeTask: result.activeTask,
+                nextFeature: result.nextFeature,
+                nextPhase: result.nextPhase,
+                nextTask: result.nextTask,
+                claims: result.claims,
+                selection: {
+                    kind: selection.kind,
+                    reason: selection.reason,
+                    deviation: selection.deviation,
+                    activeCandidates: activeCandidates.map((candidate) => summarizeCandidate(candidate, features)),
+                },
+            },
+        };
+    }
+    const { candidate } = selection;
+    const candidateSummary = summarizeCandidate(candidate, features);
+    const activeLine = result.activeTask ? `Active task: ${result.activeTask.id} — ${result.activeTask.title}\n` : "";
+    const deviationLine = selection.deviation ? `\nDeviation: ${selection.deviation.id}; resume target ${selection.deviation.resumeTaskId}.` : "";
+    const text = `${activeLine}Next work (${selection.kind}): ${candidateSummary.ref} — ${candidate.task.title}\n${selection.reason}${deviationLine}${claimsText}`;
+    return {
+        text,
+        structured: {
+            kind: selection.kind,
+            taskId: candidate.task.id,
+            phaseId: candidate.phase.id,
+            featureId: candidate.feature?.id,
+            deviation: selection.deviation,
+            activeTask: result.activeTask,
+            nextFeature: result.nextFeature,
+            nextPhase: result.nextPhase,
+            nextTask: result.nextTask,
+            claims: result.claims,
+            selection: {
+                kind: selection.kind,
+                reason: selection.reason,
+                deviation: selection.deviation,
+                candidate: candidateSummary,
+            },
+        },
+    };
+}

package/dist/refs.d.ts

@@ -17,6 +17,22 @@ import type { Phase, Feature, Idea } from "./schema.js";
  * inclusion. Ideas are top-level and never require feature/phase context.
  */
 export declare function findIdeaByRef(ideas: Idea[], ref: string): Idea | undefined;
+/**
+ * Resolve a feature reference to a Feature, or a typed error when it can't
+ * be resolved unambiguously. Unlike `findPhaseByRef`/`findTaskByRef` (which
+ * return `undefined` on any miss), callers of this one — accepted-decision
+ * target resolution, feature-scoped tools — need to tell "not found" apart
+ * from "ambiguous" so the message can say which. Both adapters carried an
+ * identical copy; kept here so the ref grammar (number, shortId, UUID, exact
+ * name, partial name with ambiguity detection) is one decision.
+ */
+export declare function resolveFeatureRefStrict(features: Feature[], ref: string): {
+    ok: true;
+    feature: Feature;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Resolve a phase reference to a Phase. Returns `undefined` when not found or
  * when a composite (F00x) parent does not match the phase's featureId.

package/dist/refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAMxD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAmB1E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAgCnB;AACD;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAiBxC,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CA2D1C"}
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAOxD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAmB1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,GACpE;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAwB/B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAgCnB;AACD;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAiBxC,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CA2D1C"}

package/dist/refs.js

@@ -1,3 +1,4 @@
+import { formatFeatureRef } from "./naming.js";
 // P00x  or  P00x(F00x)  — accept 1+ digits so "p1" == "p001".
 const PHASE_REF_RE = /^p(\d+)(?:\(f(\d+)\))?$/;
 const IDEA_REF_RE = /^i(\d+)$/;
@@ -25,6 +26,43 @@ export function findIdeaByRef(ideas, ref) {
     return ideas.find((idea) => idea.title.toLowerCase() === normalized)
         ?? ideas.find((idea) => idea.title.toLowerCase().includes(normalized));
 }
+/**
+ * Resolve a feature reference to a Feature, or a typed error when it can't
+ * be resolved unambiguously. Unlike `findPhaseByRef`/`findTaskByRef` (which
+ * return `undefined` on any miss), callers of this one — accepted-decision
+ * target resolution, feature-scoped tools — need to tell "not found" apart
+ * from "ambiguous" so the message can say which. Both adapters carried an
+ * identical copy; kept here so the ref grammar (number, shortId, UUID, exact
+ * name, partial name with ambiguity detection) is one decision.
+ */
+export function resolveFeatureRefStrict(features, ref) {
+    const raw = ref.trim();
+    if (!raw)
+        return { ok: false, error: "Feature ref is required." };
+    const normalized = raw.toLowerCase();
+    const byNumber = normalized.match(/^f(\d+)$/)
+        ? features.find((feature) => feature.number === parseInt(normalized.slice(1), 10))
+        : undefined;
+    if (byNumber)
+        return { ok: true, feature: byNumber };
+    const byShortId = features.find((feature) => feature.shortId?.toLowerCase() === normalized);
+    if (byShortId)
+        return { ok: true, feature: byShortId };
+    const byId = features.find((feature) => feature.id.toLowerCase() === normalized);
+    if (byId)
+        return { ok: true, feature: byId };
+    const exactName = features.filter((feature) => feature.name.toLowerCase() === normalized);
+    if (exactName.length === 1)
+        return { ok: true, feature: exactName[0] };
+    if (exactName.length > 1)
+        return { ok: false, error: `Ambiguous feature ref: ${raw}. Multiple features have that exact name; use F00x, shortId, or UUID.` };
+    const partialName = features.filter((feature) => feature.name.toLowerCase().includes(normalized));
+    if (partialName.length === 1)
+        return { ok: true, feature: partialName[0] };
+    if (partialName.length > 1)
+        return { ok: false, error: `Ambiguous feature ref: ${raw}. Matches: ${partialName.map((feature) => formatFeatureRef(feature.number)).join(", ")}. Use a specific F00x, shortId, or UUID.` };
+    return { ok: false, error: `Feature not found: ${raw}` };
+}
 /**
  * Resolve a phase reference to a Phase. Returns `undefined` when not found or
  * when a composite (F00x) parent does not match the phase's featureId.

package/dist/renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,OAAO,EAAQ,KAAK,EAAE,aAAa,EAAqB,MAAM,aAAa,CAAC;AAuB5G,qBAAa,YAAY;IACvB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IA+LvC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAIjC,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,eAAe;IA2GvB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM;IAmDxD,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAejD"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAQ,KAAK,EAAE,aAAa,EAAQ,MAAM,aAAa,CAAC;AAuB7E,qBAAa,YAAY;IACvB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IA+LvC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAIjC,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,eAAe;IA2GvB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM;IAmDxD,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAejD"}

package/dist/schema.d.ts

@@ -799,11 +799,16 @@ export declare const ChecklistItemSchema: z.ZodObject<{
 export declare const STATUS_LOG_MOTIVATION_REQUIRED: Set<string>;
 /**
  * Returns true when a status transition requires a written motivation.
- * - → DONE never requires motivation.
+ * - → DONE never requires motivation for an ordinary completion.
+ * - → DONE with `forced: true` — a completion pushed through past checklist
+ *   items still open (see task-completion-gate.ts, P104(F005)/T428) — is the
+ *   one case where a → DONE transition does require it: the same rule this
+ *   function already enforces for blocked/canceled/deferred/rejected,
+ *   applied to the one case where reaching DONE is itself an override.
  * - → BLOCKED / CANCELED / DEFERRED / REJECTED / WAITING always require it.
  * - → PLANNED from a non-PLANNED status requires it.
  */
-export declare function needsMotivation(fromStatus: string, toStatus: string): boolean;
+export declare function needsMotivation(fromStatus: string, toStatus: string, forced?: boolean): boolean;
 export declare const SessionInfoSchema: z.ZodObject<{
     sessionId: z.ZodString;
     createdAt: z.ZodString;