@agent-plan/core 0.2.21 → 0.2.22-next.1

package/dist/read-tracking.js

@@ -0,0 +1,87 @@
+/**
+ * T307 (P072/F005) — tracked, deduplicated parent read-enforcement.
+ *
+ * Analogous to the existing NO ACTIVE TASK advisory: an in-memory, per-session
+ * record of which feature/phase refs the agent has actually read (via the
+ * feature/phase/task get/show tools). Starting, resuming, or switching a task
+ * checks that the target's parent feature + phase are in the read set; a missing
+ * read yields an unavoidable (non-blocking) advisory instead of a silent skip.
+ *
+ * Dedupe: reading a phase (or any task inside it) records both its phase and
+ * feature, so 10 sibling tasks need a single feature + phase read. Switching to
+ * a different phase/feature naturally fails (that phase is not recorded). A
+ * pause invalidates the set, so resuming forces a fresh read.
+ *
+ * T319 (P072/F005) extends the set with requirements: starting/resuming/switching
+ * also requires the requirements linked to the phase (and, when present, the
+ * feature) to have been explicitly read. Requirements are NOT auto-recorded by a
+ * phase/feature/task read (per project decision: explicit separate read); they
+ * are recorded only via the requirement list tool (markRequirementRead). An empty
+ * linked-requirement list means nothing is required.
+ */
+let state = { features: new Set(), phases: new Set(), requirements: new Set() };
+/** Record that a feature was read. Does NOT imply any phase was read. */
+export function markFeatureRead(featureId) {
+    state.features.add(featureId);
+}
+/** Record that a phase (and, when known, its feature) was read. */
+export function markPhaseRead(phaseId, featureId) {
+    state.phases.add(phaseId);
+    if (featureId)
+        state.features.add(featureId);
+}
+/** Record that a task (and, by context, its parent phase + feature) was read. */
+export function markTaskRead(_taskId, phaseId, featureId) {
+    state.phases.add(phaseId);
+    if (featureId)
+        state.features.add(featureId);
+}
+/** Record that a requirement was explicitly read (via the requirement list tool). */
+export function markRequirementRead(requirementId) {
+    state.requirements.add(requirementId);
+}
+/**
+ * Whether the target task's parent feature + phase have both been read.
+ * `featureId` is optional: an orphan phase (no feature) only requires the phase.
+ */
+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 (phase + feature) has been explicitly read. */
+export function hasReadRequirements(requirementIds) {
+    return requirementIds.every((id) => state.requirements.has(id));
+}
+/** Clear the read set (e.g. on pause, so resuming forces a fresh read). */
+export function invalidateReads() {
+    state = { features: new Set(), phases: new Set(), requirements: new Set() };
+}
+/**
+ * Non-blocking advisory (mirrors the NO ACTIVE TASK pattern): empty when the
+ * target's parent feature + phase have both been read, otherwise a loud
+ * READ REQUIRED notice the agent cannot silently skip.
+ */
+export function parentReadAdvisory(featureId, phaseId) {
+    if (hasReadParents(featureId, phaseId))
+        return "";
+    return "\n\n⚠️ READ REQUIRED before proceeding: read the parent feature and phase (full=true) for this task before starting or resuming it. One feature+phase read covers every task in that phase; a pause/resume invalidates the read and requires re-reading.";
+}
+/**
+ * Non-blocking advisory (mirrors parentReadAdvisory): empty when every linked
+ * requirement (phase + feature) has been explicitly read, otherwise a loud
+ * REQUIREMENTS READ REQUIRED notice. An empty list means the phase/feature has
+ * no linked requirements, so nothing is required.
+ */
+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) before starting or resuming the task. Use the requirement list tool to read them (one read covers every task in that phase; a pause/resume invalidates the read).";
+}
+/** Snapshot for diagnostics/tests. */
+export function readTrackingSnapshot() {
+    return { features: [...state.features], phases: [...state.phases], 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: ${featureShowCmd} ${fr}, ${phaseShowCmd} ${pr}, ${taskShowCmd} ${tr} (full).`
+            : `⚠️ This task is in-progress (work started in a previous session). Before continuing, re-read the full context: ${featureShowCmd} ${fr}, ${phaseShowCmd} ${pr}, ${taskShowCmd} ${tr} (full).`);
     }
     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.`);