@agent-plan/core 0.2.22 → 0.2.23-next.0

package/dist/planner-rules.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Canonical planner extension rules — the agent-behavior contract that applies
+ * to EVERY project using the Agent Plan extension (Pi, MCP / Claude Code / Codex,
+ * future harnesses). These are STATIC: no timestamps, no dynamic content, so the
+ * same text seeds every .planner/ and never diverges across worktrees or
+ * branches (no conflict from date/timestamp changes).
+ *
+ * AGENTS.md governs ONLY the development of the agent-plan extension and must
+ * not duplicate these rules.
+ */
+export declare const PLANNER_EXTENSION_RULES: string[];
+export interface ExtensionRulesFile {
+    extensionRules: string[];
+}
+/**
+ * Load the effective extension rules for a planner root. Returns the project's
+ * own .planner/rules.json (static, user-overridable) when present and non-empty,
+ * otherwise the canonical code set. Never returns timestamps or dynamic data.
+ */
+export declare function loadExtensionRules(plannerRoot: string): Promise<string[]>;
+//# sourceMappingURL=planner-rules.d.ts.map

package/dist/planner-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-rules.d.ts","sourceRoot":"","sources":["../src/planner-rules.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,EA2B3C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW/E"}

package/dist/planner-rules.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Canonical planner extension rules — the agent-behavior contract that applies
+ * to EVERY project using the Agent Plan extension (Pi, MCP / Claude Code / Codex,
+ * future harnesses). These are STATIC: no timestamps, no dynamic content, so the
+ * same text seeds every .planner/ and never diverges across worktrees or
+ * branches (no conflict from date/timestamp changes).
+ *
+ * AGENTS.md governs ONLY the development of the agent-plan extension and must
+ * not duplicate these rules.
+ */
+export const PLANNER_EXTENSION_RULES = [
+    // §1 — source of truth
+    "Keep the planner as the single operational source of truth while working: read the relevant planner state before starting; update it when an activity starts, changes state, blocks, or concludes; and record next steps, blockers, and decisions in the relevant planner entities. Never leave work only in the conversation.",
+    // §2 — task lifecycle
+    "Respect the task lifecycle strictly. Always call task_start before touching code, and task_complete with durable evidence of shipped work, verification (including partial verification), remaining/unverified work, files, and decisions when a deliverable is done. Never enter in-progress or done through task_update. Sync state changes (start/complete/block) to the planner at the exact moment they happen — never batch updates at session end. If task_start is denied, the task remains planned: satisfy the stated read prerequisites and retry, and never claim work started without an explicit successful start result. A task marked in-progress means you are actually working on it; if you stop, close or block it with a motivation in statusLog. Derived feature/phase status is computed from tasks, not stored in JSON.",
+    // §3 — markdown not source of truth
+    "Do not treat markdown as the source of truth for the plan. The plan's primary source is structured data in .planner/; markdown is a generated, human/agent-readable view.",
+    // §5 — plan location
+    "The plan lives in .planner/ within the target project. Whether .planner/ is git-tracked is at the project's discretion.",
+    // §6 — discuss per phase
+    "Discuss the plan per phase: clarify objective, scope, non-scope, dependencies, risks, and outcomes before working a phase; detail implementation when the phase is actually worked, not up front.",
+    // §7 — naming
+    "Naming: phases and tasks use global project-wide numbering (P001, T001, …) with a slug derived from the title. Numbers are assigned once at creation from a monotonic global counter and never reused (deletes leave gaps).",
+    // §8 — status changes & motivation
+    "Every task status change is recorded in an incremental statusLog. Motivation is mandatory for blocked/canceled/rejected/deferred/waiting and for returning to planned from a non-planned status; not required for done or for normal in-progress-from-planned. Use task_update (not task_start/task_complete) for non-lifecycle status changes, with an exhaustive motivation.",
+    // §10 — references
+    "Reference entities with human, unique, composite IDs — Feature 'F001 - Name', Phase 'P001(F001) - Title', Task 'T003 - Number'. Short forms P003/T007 and the 5-char global shortId (e.g. UUXD1) are also valid. Never reference raw UUIDs. To locate an entity, use the compact list tools (feature_list/phase_list/task_list), not by reading .planner/*.json files.",
+    // §12 — handoff
+    "Handoff is per-phase (phase.handoff), not a file. Write it only on explicit user request and only after the exact feature+phase target is confirmed. Run handoff_prepare for that phase, reconcile all still-relevant existing content into one active handoff, and synchronize durable task/phase/feature context in the same handoff_write operation. A pending handoff never blocks task_start and is archived only when the phase completes or the user explicitly clears it; refreshing it must not create superseded copies.",
+    // §12 — operational hygiene
+    "Operational hygiene: start the task (task_start) before thinking about implementation; complete it (task_complete) as part of delivering the deliverable, not after; motivate every block so a third party can understand the impediment.",
+    // Avvio del planner
+    "The planner and Web UI never start automatically. Do not start the Web UI or show its URL unless the user runs load/recap/web-status. The Web UI URL appears only in the recap after load, or on explicit web status.",
+    // Regola dettagli
+    "Write relevant points (decisions, constraints, current state, file:line refs, edge cases) into the task/phase/feature description or notes as soon as they emerge. Before starting, resuming, or switching to a task, read task_get(full=true), then its parent phase_get(full=true), then its parent feature_get(full=true), in that exact order; read linked requirements explicitly when present. Cite entities with composite IDs, not bare UUIDs.",
+    // Expected operational behavior
+    "When you begin work, task_start and task_switch enforce the required ordered full reads. Read any relevant phase handoff as additional context, then update the planner before and after significant changes. If you change an architectural decision, document it explicitly.",
+];
+/**
+ * Load the effective extension rules for a planner root. Returns the project's
+ * own .planner/rules.json (static, user-overridable) when present and non-empty,
+ * otherwise the canonical code set. Never returns timestamps or dynamic data.
+ */
+export async function loadExtensionRules(plannerRoot) {
+    try {
+        const raw = await readFile(join(plannerRoot, "rules.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed.extensionRules) && parsed.extensionRules.length > 0) {
+            return parsed.extensionRules.filter((r) => typeof r === "string" && r.length > 0);
+        }
+    }
+    catch {
+        // Missing or malformed rules.json → fall back to the canonical code set.
+    }
+    return PLANNER_EXTENSION_RULES;
+}

package/dist/read-tracking.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Session-scoped, ordered context-read enforcement for agent lifecycle operations.
+ *
+ * The first complete read for a task must be task(full) → phase(full) →
+ * feature(full), with linked requirements read independently. A persisted
+ * sessionInfo attestation may satisfy later checks in the same session while
+ * every entity's updatedAt remains at or before its attestation timestamp.
+ */
+type SessionInfoEntry = {
+    sessionId: string;
+    createdAt: string;
+};
+type ReadTrackedEntity = {
+    updatedAt: string;
+    sessionInfo?: SessionInfoEntry[];
+};
+export type ContextReadEligibility = {
+    eligible: boolean;
+    reason: string;
+};
+export interface SessionContextReadInput {
+    sessionId: string;
+    taskId: string;
+    phaseId: string;
+    featureId?: string;
+    task?: ReadTrackedEntity;
+    phase?: ReadTrackedEntity;
+    feature?: ReadTrackedEntity;
+    requirements?: Array<ReadTrackedEntity & {
+        id: string;
+    }>;
+    requirementIds?: string[];
+}
+/** Record a full feature read in the default compatibility session. */
+export declare function markFeatureRead(featureId: string): void;
+/** Record a full feature read for an explicit harness session. */
+export declare function markFeatureReadForSessionId(sessionId: string, featureId: string): void;
+/** Record a full phase read in the default compatibility session. */
+export declare function markPhaseRead(phaseId: string, _featureId?: string): void;
+/** Record a full phase read for an explicit harness session. */
+export declare function markPhaseReadForSessionId(sessionId: string, phaseId: string): void;
+/** Record a full task read in the default compatibility session. */
+export declare function markTaskRead(taskId: string, _phaseId?: string, _featureId?: string): void;
+/** Record a full task read for an explicit harness session. */
+export declare function markTaskReadForSessionId(sessionId: string, taskId: string): void;
+/** Record that a requirement was explicitly read in the default session. */
+export declare function markRequirementRead(requirementId: string): void;
+/** Record that a requirement was explicitly read for an explicit session. */
+export declare function markRequirementReadForSessionId(sessionId: string, requirementId: string): void;
+/**
+ * Evaluate exact in-memory read ordering first, then a persisted attestation
+ * for the same session and current entity revisions. A previously persisted
+ * but now stale attestation always wins over stale in-memory ordering.
+ */
+export declare function contextReadEligibilityForSession(input: SessionContextReadInput): ContextReadEligibility;
+/** Return true only when the persisted attestation covers the current revisions. */
+export declare function hasValidSessionAttestation(input: SessionContextReadInput): boolean;
+/** Compatibility check for the default session and in-memory reads only. */
+export declare function contextReadEligibility(taskId: string, phaseId: string, featureId?: string): ContextReadEligibility;
+/** Legacy parent-read check retained for callers that only need independent parent state. */
+export declare function hasReadParents(featureId: string | undefined, phaseId: string): boolean;
+/**
+ * Whether linked requirements are read in memory or have valid persisted
+ * attestations for the current session and entity revisions.
+ */
+export declare function hasReadRequirementsForSession(sessionId: string, requirementIds: string[], requirements?: Array<ReadTrackedEntity & {
+    id: string;
+}>): boolean;
+/** Legacy requirement check for the default compatibility session. */
+export declare function hasReadRequirements(requirementIds: string[]): boolean;
+/** Clear one session's read state, or all state for legacy callers. */
+export declare function invalidateReads(sessionId?: string): void;
+/** Initialize an explicit session without clearing other harness sessions. */
+export declare function startReadSession(sessionId: string): void;
+/** Compatibility advisory for non-lifecycle callers. */
+export declare function parentReadAdvisory(featureId: string | undefined, phaseId: string): string;
+/** Advisory text for the separate linked-requirements gate. */
+export declare function requirementReadAdvisory(requirementIds: string[]): string;
+/** Snapshot for diagnostics. */
+export declare function readTrackingSnapshot(sessionId?: string): {
+    features: string[];
+    phases: string[];
+    requirements: string[];
+};
+export {};
+//# sourceMappingURL=read-tracking.d.ts.map

package/dist/read-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"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"}

package/dist/read-tracking.js

@@ -0,0 +1,192 @@
+/**
+ * Session-scoped, ordered context-read enforcement for agent lifecycle operations.
+ *
+ * The first complete read for a task must be task(full) → phase(full) →
+ * feature(full), with linked requirements read independently. A persisted
+ * sessionInfo attestation may satisfy later checks in the same session while
+ * every entity's updatedAt remains at or before its attestation timestamp.
+ */
+const DEFAULT_SESSION_ID = "__default__";
+const newState = () => ({
+    tasks: new Map(),
+    phases: new Map(),
+    features: new Map(),
+    requirements: new Set(),
+    nextSequence: 0,
+});
+const states = new Map([[DEFAULT_SESSION_ID, newState()]]);
+function normalizeSessionId(sessionId) {
+    return sessionId?.trim() || DEFAULT_SESSION_ID;
+}
+function stateFor(sessionId) {
+    const key = normalizeSessionId(sessionId);
+    let state = states.get(key);
+    if (!state) {
+        state = newState();
+        states.set(key, state);
+    }
+    return state;
+}
+function record(map, id, state) {
+    state.nextSequence += 1;
+    map.set(id, state.nextSequence);
+}
+function markTaskReadForSession(sessionId, taskId) {
+    const state = stateFor(sessionId);
+    record(state.tasks, taskId, state);
+}
+function markPhaseReadForSession(sessionId, phaseId) {
+    const state = stateFor(sessionId);
+    record(state.phases, phaseId, state);
+}
+function markFeatureReadForSession(sessionId, featureId) {
+    const state = stateFor(sessionId);
+    record(state.features, featureId, state);
+}
+/** Record a full feature read in the default compatibility session. */
+export function markFeatureRead(featureId) {
+    markFeatureReadForSession(DEFAULT_SESSION_ID, featureId);
+}
+/** Record a full feature read for an explicit harness session. */
+export function markFeatureReadForSessionId(sessionId, featureId) {
+    markFeatureReadForSession(sessionId, featureId);
+}
+/** Record a full phase read in the default compatibility session. */
+export function markPhaseRead(phaseId, _featureId) {
+    markPhaseReadForSession(DEFAULT_SESSION_ID, phaseId);
+}
+/** Record a full phase read for an explicit harness session. */
+export function markPhaseReadForSessionId(sessionId, phaseId) {
+    markPhaseReadForSession(sessionId, phaseId);
+}
+/** Record a full task read in the default compatibility session. */
+export function markTaskRead(taskId, _phaseId, _featureId) {
+    markTaskReadForSession(DEFAULT_SESSION_ID, taskId);
+}
+/** Record a full task read for an explicit harness session. */
+export function markTaskReadForSessionId(sessionId, taskId) {
+    markTaskReadForSession(sessionId, taskId);
+}
+/** Record that a requirement was explicitly read in the default session. */
+export function markRequirementRead(requirementId) {
+    stateFor(DEFAULT_SESSION_ID).requirements.add(requirementId);
+}
+/** Record that a requirement was explicitly read for an explicit session. */
+export function markRequirementReadForSessionId(sessionId, requirementId) {
+    stateFor(sessionId).requirements.add(requirementId);
+}
+function orderedEligibility(sessionId, taskId, phaseId, featureId) {
+    const state = stateFor(sessionId);
+    const taskSequence = state.tasks.get(taskId);
+    if (taskSequence === undefined) {
+        return { eligible: false, reason: "Read this exact task with full=true first." };
+    }
+    const phaseSequence = state.phases.get(phaseId);
+    if (phaseSequence === undefined || phaseSequence <= taskSequence) {
+        return { eligible: false, reason: "After reading the task, read its parent phase with full=true." };
+    }
+    if (!featureId)
+        return { eligible: true, reason: "" };
+    const featureSequence = state.features.get(featureId);
+    if (featureSequence === undefined || featureSequence <= phaseSequence) {
+        return { eligible: false, reason: "After reading the phase, read its parent feature with full=true." };
+    }
+    return { eligible: true, reason: "" };
+}
+function validSessionInfo(entity, sessionId) {
+    const entry = entity?.sessionInfo?.find((candidate) => candidate.sessionId === sessionId);
+    return Boolean(entity && entry && entity.updatedAt <= entry.createdAt);
+}
+function persistedEligibility(input) {
+    if (!validSessionInfo(input.task, input.sessionId) || !validSessionInfo(input.phase, input.sessionId))
+        return false;
+    if (input.featureId && !validSessionInfo(input.feature, input.sessionId))
+        return false;
+    const requirementIds = input.requirementIds ?? [];
+    return requirementIds.every((id) => validSessionInfo(input.requirements?.find((requirement) => requirement.id === id), input.sessionId));
+}
+function hasStoredSessionAttestation(input) {
+    const entities = [input.task, input.phase, input.feature, ...(input.requirements ?? [])];
+    return entities.some((entity) => entity?.sessionInfo?.some((entry) => entry.sessionId === input.sessionId));
+}
+/**
+ * Evaluate exact in-memory read ordering first, then a persisted attestation
+ * for the same session and current entity revisions. A previously persisted
+ * but now stale attestation always wins over stale in-memory ordering.
+ */
+export function contextReadEligibilityForSession(input) {
+    const ordered = orderedEligibility(input.sessionId, input.taskId, input.phaseId, input.featureId);
+    if (ordered.eligible)
+        return ordered;
+    if (input.task && input.phase && persistedEligibility(input))
+        return { eligible: true, reason: "" };
+    if (input.task && input.phase && hasStoredSessionAttestation(input)) {
+        return { eligible: false, reason: "Context changed since the last session read; reread the exact task, phase, feature, and linked requirements." };
+    }
+    return ordered;
+}
+/** Return true only when the persisted attestation covers the current revisions. */
+export function hasValidSessionAttestation(input) {
+    return persistedEligibility(input);
+}
+/** Compatibility check for the default session and in-memory reads only. */
+export function contextReadEligibility(taskId, phaseId, featureId) {
+    return orderedEligibility(DEFAULT_SESSION_ID, taskId, phaseId, featureId);
+}
+/** Legacy parent-read check retained for callers that only need independent parent state. */
+export function hasReadParents(featureId, phaseId) {
+    const state = stateFor(DEFAULT_SESSION_ID);
+    return state.phases.has(phaseId) && (!featureId || state.features.has(featureId));
+}
+/**
+ * Whether linked requirements are read in memory or have valid persisted
+ * attestations for the current session and entity revisions.
+ */
+export function hasReadRequirementsForSession(sessionId, requirementIds, requirements = []) {
+    const state = stateFor(sessionId);
+    return requirementIds.every((id) => state.requirements.has(id) || validSessionInfo(requirements.find((requirement) => requirement.id === id), sessionId));
+}
+/** Legacy requirement check for the default compatibility session. */
+export function hasReadRequirements(requirementIds) {
+    return requirementIds.every((id) => stateFor(DEFAULT_SESSION_ID).requirements.has(id));
+}
+/** Clear one session's read state, or all state for legacy callers. */
+export function invalidateReads(sessionId) {
+    if (sessionId) {
+        states.delete(normalizeSessionId(sessionId));
+        stateFor(sessionId);
+        return;
+    }
+    states.clear();
+    states.set(DEFAULT_SESSION_ID, newState());
+}
+/** Initialize an explicit session without clearing other harness sessions. */
+export function startReadSession(sessionId) {
+    stateFor(sessionId);
+}
+/** Compatibility advisory for non-lifecycle callers. */
+export function parentReadAdvisory(featureId, phaseId) {
+    const state = stateFor(DEFAULT_SESSION_ID);
+    if (state.phases.has(phaseId) && (!featureId || state.features.has(featureId)))
+        return "";
+    return "\n\n⚠️ READ REQUIRED before proceeding: read the parent phase and feature with full=true.";
+}
+/** Advisory text for the separate linked-requirements gate. */
+export function requirementReadAdvisory(requirementIds) {
+    const state = stateFor(DEFAULT_SESSION_ID);
+    if (requirementIds.length === 0)
+        return "";
+    const unread = requirementIds.filter((id) => !state.requirements.has(id));
+    if (unread.length === 0)
+        return "";
+    return "\n\n⚠️ REQUIREMENTS READ REQUIRED before proceeding: read the requirements linked to this phase and feature.";
+}
+/** Snapshot for diagnostics. */
+export function readTrackingSnapshot(sessionId) {
+    const state = stateFor(sessionId);
+    return {
+        features: [...state.features.keys()],
+        phases: [...state.phases.keys()],
+        requirements: [...state.requirements],
+    };
+}

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;AAGjD;;;;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,CAmOhH"}
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;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,CA4OhH"}

package/dist/recap.js

@@ -33,20 +33,20 @@ export async function buildRecap(st, web = {}, opts = {}) {
     const totalT = allTasks.length;
     const doneT = allTasks.filter(({ task }) => task.status === "done").length;
     const activeT = allTasks.filter(({ task }) => task.status === "in-progress").length;
-    const pausedTasks = allTasks.filter(({ task }) => task.status === "paused");
-    const pausedT = pausedTasks.length;
+    const checkpointedTasks = allTasks.filter(({ task }) => !["done", "canceled", "rejected"].includes(task.status) && task.pauseSnapshot);
+    const checkpointedT = checkpointedTasks.length;
     const pendingDeviation = [...plan.project.workDeviations]
         .filter((deviation) => deviation.state === "resume-required" || deviation.state === "resolved")
         .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
         .find((deviation) => allTasks.some(({ task }) => task.id === deviation.resumeTaskId
-        && (task.status === "paused" || task.status === "planned" || task.status === "waiting")));
+        && (task.status === "planned" || task.status === "waiting" || task.status === "in-progress")));
     const pendingResume = pendingDeviation
         ? allTasks.find(({ task }) => task.id === pendingDeviation.resumeTaskId)
         : undefined;
-    const standalonePaused = pausedTasks
+    const standaloneCheckpoints = checkpointedTasks
         .filter(({ task }) => task.id !== pendingResume?.task.id)
         .sort((left, right) => (right.task.pauseSnapshot?.pausedAt ?? "").localeCompare(left.task.pauseSnapshot?.pausedAt ?? ""));
-    const latestStandalonePaused = standalonePaused[0];
+    const latestStandaloneCheckpoint = standaloneCheckpoints[0];
     // Plan is fully complete: there is work and all of it is done, nothing active.
     // (totalT > 0 guards the empty/unstarted case from looking "complete".)
     const planComplete = totalT > 0 && doneT === totalT && doneP === totalP && doneF === totalF;
@@ -63,28 +63,34 @@ export async function buildRecap(st, web = {}, opts = {}) {
     const featureAddCmd = cmd("/planner feature add", "planner-feature-add");
     const phaseAddCmd = cmd("/planner phase add", "planner-phase-add");
     const handoffShowCmd = cmd("/planner handoff show", "planner-handoff-show");
+    const featureShowCmd = cmd("/planner feature show", "planner-feature-show");
+    const phaseShowCmd = cmd("/planner phase show", "planner-phase-show");
+    const taskShowCmd = cmd("/planner task show", "planner-task-show");
     const lines = [];
     lines.push(italian ? "## Ripresa planner" : "## Planner recap");
     const name = plan.project.name || "(unnamed project)";
     lines.push(`${italian ? "Progetto" : "Project"}: ${name}${plan.project.goal ? " — " + plan.project.goal : ""}`);
     lines.push(italian
-        ? `Avanzamento: feature ${doneF}/${totalF} completate (${activeF} attive) · fasi ${doneP}/${totalP} completate (${activeP} attive) · task ${doneT}/${totalT} completati (${activeT} attivi, ${pausedT} in pausa)`
-        : `Progress: Features ${doneF}/${totalF} done (${activeF} active) · Phases ${doneP}/${totalP} done (${activeP} active) · Tasks ${doneT}/${totalT} done (${activeT} active, ${pausedT} paused)`);
+        ? `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)`);
     if (focusTask && focusPhase) {
         const fr = focusFeature ? fref(focusFeature.number) : "?";
         const pr = formatPhaseRef(focusPhase.number, focusFeature?.number);
         const tr = tref(focusTask.task.number);
         lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${fr} — ${focusFeature?.name ?? "?"} / ${pr} — ${focusPhase.title} / ${tr} — ${focusTask.task.title} (in-progress)`);
+        lines.push("", italian
+            ? `Questo task è in-progress (lavoro iniziato in una sessione precedente). Prima di continuare, rileggi il contesto completo: ${taskShowCmd} ${tr} (full=true), ${phaseShowCmd} ${pr} (full=true), ${featureShowCmd} ${fr} (full=true).`
+            : `⚠️ This task is in-progress (work started in a previous session). Before continuing, re-read the full context in this order: ${taskShowCmd} ${tr} (full=true), ${phaseShowCmd} ${pr} (full=true), ${featureShowCmd} ${fr} (full=true).`);
     }
     else if (pendingResume) {
         const feature = feats.find((entry) => entry.id === pendingResume.phase.featureId);
         const ref = `${formatPhaseRef(pendingResume.phase.number, feature?.number)}/${tref(pendingResume.task.number)}`;
         lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "ripresa obbligatoria" : "resume required"} — ${ref} — ${pendingResume.task.title} (${pendingResume.task.status})`);
     }
-    else if (latestStandalonePaused) {
-        const feature = feats.find((entry) => entry.id === latestStandalonePaused.phase.featureId);
-        const ref = `${formatPhaseRef(latestStandalonePaused.phase.number, feature?.number)}/${tref(latestStandalonePaused.task.number)}`;
-        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "task in pausa da riprendere" : "paused task to resume"} — ${ref} — ${latestStandalonePaused.task.title}`);
+    else if (latestStandaloneCheckpoint) {
+        const feature = feats.find((entry) => entry.id === latestStandaloneCheckpoint.phase.featureId);
+        const ref = `${formatPhaseRef(latestStandaloneCheckpoint.phase.number, feature?.number)}/${tref(latestStandaloneCheckpoint.task.number)}`;
+        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "checkpoint da valutare" : "checkpoint to evaluate"} — ${ref} — ${latestStandaloneCheckpoint.task.title}`);
     }
     else if (handoffs.length > 0) {
         const top = handoffs[0];
@@ -107,15 +113,15 @@ export async function buildRecap(st, web = {}, opts = {}) {
         const feature = feats.find((entry) => entry.id === pendingResume.phase.featureId);
         const ref = `${formatPhaseRef(pendingResume.phase.number, feature?.number)}/${tref(pendingResume.task.number)}`;
         lines.push(italian
-            ? `Prossimo step: riprendi ${ref} con ${taskStartCmd}. Il checkpoint del task è prioritario rispetto a nuovo lavoro e handoff di fase.`
-            : `Next step: resume ${ref} with ${taskStartCmd}. Its task checkpoint takes precedence over new work and phase handoffs.`);
+            ? `Avviso ripresa: valuta se riprendere ${ref} con ${taskStartCmd}. Il checkpoint del task va letto prima di decidere se tornare su questo lavoro o proseguire altrove.`
+            : `Resume advisory: evaluate whether to resume ${ref} with ${taskStartCmd}. Read its checkpoint before deciding whether to return to this work or continue elsewhere.`);
     }
-    else if (latestStandalonePaused) {
-        const feature = feats.find((entry) => entry.id === latestStandalonePaused.phase.featureId);
-        const ref = `${formatPhaseRef(latestStandalonePaused.phase.number, feature?.number)}/${tref(latestStandalonePaused.task.number)}`;
+    else if (latestStandaloneCheckpoint) {
+        const feature = feats.find((entry) => entry.id === latestStandaloneCheckpoint.phase.featureId);
+        const ref = `${formatPhaseRef(latestStandaloneCheckpoint.phase.number, feature?.number)}/${tref(latestStandaloneCheckpoint.task.number)}`;
         lines.push(italian
-            ? `Prossimo step: riprendi il checkpoint più recente, ${ref}, con ${taskStartCmd}, prima di scegliere nuovo lavoro.`
-            : `Next step: resume the newest checkpoint, ${ref}, with ${taskStartCmd} before selecting new work.`);
+            ? `Avviso ripresa: valuta il checkpoint più recente, ${ref}, con ${taskStartCmd}, prima di scegliere se tornare su quel lavoro o avviarne altro.`
+            : `Resume advisory: evaluate the newest checkpoint, ${ref}, with ${taskStartCmd} before deciding whether to return to it or start other work.`);
     }
     else if (handoffs.length > 0) {
         lines.push(italian
@@ -137,11 +143,11 @@ export async function buildRecap(st, web = {}, opts = {}) {
         const feature = feats.find((entry) => entry.id === pendingResume.phase.featureId);
         const ref = `${formatPhaseRef(pendingResume.phase.number, feature?.number)}/${tref(pendingResume.task.number)}`;
         const snapshot = pendingResume.task.pauseSnapshot ?? pendingDeviation?.snapshot;
-        lines.push("", italian ? "## Ripresa task obbligatoria" : "## Task resume required", `${ref} — ${pendingResume.task.title}`, snapshot ? `${italian ? "Perché è stato sospeso" : "Paused because"}: ${snapshot.reason}` : "", snapshot ? `${italian ? "Stato del lavoro" : "Work checkpoint"}: ${snapshot.whatWasBeingDone}` : "", snapshot ? `${italian ? "Riprendi da" : "Resume from"}: ${snapshot.resumeLocation}` : "", snapshot ? `${italian ? "Come riprendere" : "How to resume"}: ${snapshot.howToResume}` : "", `${italian ? "Azione" : "Action"}: ${taskStartCmd} ${ref}`);
+        lines.push("", italian ? "## Avviso ripresa task" : "## Task resume advisory", `${ref} — ${pendingResume.task.title}`, snapshot ? `${italian ? "Perché è stato salvato il checkpoint" : "Checkpoint reason"}: ${snapshot.reason}` : "", snapshot ? `${italian ? "Stato del lavoro" : "Work checkpoint"}: ${snapshot.whatWasBeingDone}` : "", snapshot ? `${italian ? "Riprendi da" : "Resume from"}: ${snapshot.resumeLocation}` : "", snapshot ? `${italian ? "Come riprendere" : "How to resume"}: ${snapshot.howToResume}` : "", italian ? `Azione suggerita: valuta ${taskStartCmd} ${ref}` : `Suggested action: evaluate ${taskStartCmd} ${ref}`);
     }
-    if (standalonePaused.length > 0) {
-        lines.push("", italian ? `## Task in pausa (${standalonePaused.length})` : `## Paused tasks (${standalonePaused.length})`);
-        for (const entry of standalonePaused) {
+    if (standaloneCheckpoints.length > 0) {
+        lines.push("", italian ? `## Checkpoint salvati (${standaloneCheckpoints.length})` : `## Saved checkpoints (${standaloneCheckpoints.length})`);
+        for (const entry of standaloneCheckpoints) {
             const feature = feats.find((item) => item.id === entry.phase.featureId);
             const ref = `${formatPhaseRef(entry.phase.number, feature?.number)}/${tref(entry.task.number)}`;
             const snapshot = entry.task.pauseSnapshot;
@@ -152,7 +158,7 @@ export async function buildRecap(st, web = {}, opts = {}) {
         const top = handoffs[0];
         lines.push("", italian ? `## Handoff di fase pendenti (${handoffs.length})` : `## Pending phase handoffs (${handoffs.length})`);
         handoffs.forEach((h, i) => lines.push(`[${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`));
-        if (pendingResume || latestStandalonePaused) {
+        if (pendingResume || latestStandaloneCheckpoint) {
             lines.push("", italian
                 ? "→ Questi handoff restano disponibili come contesto, ma prima risolvi il task da riprendere indicato sopra."
                 : "→ These handoffs remain available as context, but first resolve the task resume shown above.");
@@ -173,7 +179,7 @@ export async function buildRecap(st, web = {}, opts = {}) {
             ? `Piano completo — aggiungi una nuova feature (${featureAddCmd}) o fase (${phaseAddCmd}) per continuare.`
             : `Plan complete — add a new feature (${featureAddCmd}) or phase (${phaseAddCmd}) to continue.`);
     }
-    else if (activeT === 0 && !pendingResume && standalonePaused.length === 0) {
+    else if (activeT === 0 && !pendingResume && standaloneCheckpoints.length === 0) {
         lines.push("", italian
             ? `Nessun handoff pendente e nessun task in-progress. Usa ${taskAddCmd} / ${taskStartCmd} per iniziare.`
             : `No phase handoff pending and no task in-progress. Use ${taskAddCmd} / ${taskStartCmd} to begin work.`);