@agent-plan/core 0.2.22 → 0.2.23

package/dist/read-tracking.js

@@ -0,0 +1,106 @@
+/**
+ * Per-session, ordered context-read enforcement for agent lifecycle operations.
+ *
+ * An agent must read the exact task, then its parent phase, then its parent
+ * feature with full=true before it can start, resume, or switch to that task.
+ * Compact list/identity reads never count. The state is process-local and is
+ * cleared on pause, switch, and session startup by the harness adapters.
+ *
+ * Linked requirements remain a separate explicit-read gate. They are recorded
+ * only through the requirement list tool and never by an entity read.
+ */
+let state = {
+    tasks: new Map(),
+    phases: new Map(),
+    features: new Map(),
+    requirements: new Set(),
+    nextSequence: 0,
+};
+function record(map, id) {
+    state.nextSequence += 1;
+    map.set(id, state.nextSequence);
+}
+/** Record a full feature read. */
+export function markFeatureRead(featureId) {
+    record(state.features, featureId);
+}
+/** Record a full phase read. The parent feature is intentionally not implied. */
+export function markPhaseRead(phaseId, _featureId) {
+    record(state.phases, phaseId);
+}
+/** Record a full task read. Its parent phase and feature are intentionally not implied. */
+export function markTaskRead(taskId, _phaseId, _featureId) {
+    record(state.tasks, taskId);
+}
+/** Record that a requirement was explicitly read via the requirement list tool. */
+export function markRequirementRead(requirementId) {
+    state.requirements.add(requirementId);
+}
+/**
+ * Verify the required task(full) → phase(full) → feature(full) order for one
+ * exact task lineage. Orphan phases do not require a feature read.
+ */
+export function contextReadEligibility(taskId, phaseId, featureId) {
+    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: "" };
+}
+/**
+ * Legacy parent-read check retained for callers that only need to know whether
+ * both parent entities have been read. Lifecycle gates must use
+ * contextReadEligibility so the task and ordering cannot be bypassed.
+ */
+export function hasReadParents(featureId, phaseId) {
+    const phaseOk = state.phases.has(phaseId);
+    const featureOk = featureId ? state.features.has(featureId) : true;
+    return phaseOk && featureOk;
+}
+/** Whether every linked requirement has been explicitly read. */
+export function hasReadRequirements(requirementIds) {
+    return requirementIds.every((id) => state.requirements.has(id));
+}
+/** Clear all read state so later lifecycle work requires fresh context. */
+export function invalidateReads() {
+    state = {
+        tasks: new Map(),
+        phases: new Map(),
+        features: new Map(),
+        requirements: new Set(),
+        nextSequence: 0,
+    };
+}
+/** Compatibility advisory for non-lifecycle callers. */
+export function parentReadAdvisory(featureId, phaseId) {
+    if (hasReadParents(featureId, phaseId))
+        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) {
+    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 and tests. */
+export function readTrackingSnapshot() {
+    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.`);