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

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,CAkJhH"}
+{"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,CAyPhH"}

package/dist/recap.js

@@ -33,6 +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 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 === "planned" || task.status === "waiting" || task.status === "in-progress")));
+    const pendingResume = pendingDeviation
+        ? allTasks.find(({ task }) => task.id === pendingDeviation.resumeTaskId)
+        : undefined;
+    const standaloneCheckpoints = checkpointedTasks
+        .filter(({ task }) => task.id !== pendingResume?.task.id)
+        .sort((left, right) => (right.task.pauseSnapshot?.pausedAt ?? "").localeCompare(left.task.pauseSnapshot?.pausedAt ?? ""));
+    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;
@@ -49,18 +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)`
-        : `Progress: Features ${doneF}/${totalF} done (${activeF} active) · Phases ${doneP}/${totalP} done (${activeP} active) · Tasks ${doneT}/${totalT} done (${activeT} active)`);
+        ? `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 (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];
@@ -74,12 +104,35 @@ export async function buildRecap(st, web = {}, opts = {}) {
     else {
         lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "nessun task attivo — rivedi il piano e scegli il prossimo task concreto" : "no active task — review the plan and pick the next concrete task"}`);
     }
+    // Planner extension rules — the agent-behavior contract for every project
+    // using the extension. Static (no timestamps), loaded from .planner/rules.json
+    // or the canonical code set. Kept out of project.json so it never diverges
+    // across worktrees/branches.
+    const extensionRules = await st.extensionRules();
+    if (extensionRules.length > 0) {
+        lines.push("", italian ? "## Regole del planner (estensione)" : "## Planner rules (extension)");
+        extensionRules.forEach((rule, i) => lines.push(`${i + 1}. ${rule}`));
+    }
     // Next step: the phase handoff (phase.handoff) is the authoritative,
     // actively-managed resume context. When a handoff is pending, point to it
     // instead of surfacing potentially-stale resume.json nextSteps. When no
     // handoff exists, fall back to resume.nextSteps but mark them as possibly
     // stale (free-text that refreshResume never touches, so they can drift).
-    if (handoffs.length > 0) {
+    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
+            ? `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 (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
+            ? `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
             ? `Prossimo step: leggi l'handoff di fase pendente sotto (fonte autorevole, gestita attivamente). I nextSteps legacy di resume.json sono soppressi perché possono essere stale.`
             : `Next step: read the pending phase handoff below (authoritative, actively maintained). Legacy resume.json nextSteps are suppressed because they may be stale.`);
@@ -95,11 +148,31 @@ 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);
     }
+    if (pendingResume) {
+        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 ? "## 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 (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;
+            lines.push(`${ref} — ${entry.task.title}`, snapshot ? `  ${italian ? "Perché" : "Why"}: ${snapshot.reason}` : "", snapshot ? `  ${italian ? "Stato" : "Checkpoint"}: ${snapshot.whatWasBeingDone}` : "", snapshot ? `  ${italian ? "Riprendi da" : "Resume from"}: ${snapshot.resumeLocation}` : "", snapshot ? `  ${italian ? "Come" : "How"}: ${snapshot.howToResume}` : "");
+        }
+    }
     if (handoffs.length > 0) {
         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 (handoffs.length === 1) {
+        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.");
+        }
+        else if (handoffs.length === 1) {
             lines.push("", italian
                 ? `→ Vuoi riprendere da ${top.compositeRef}? Leggi l'handoff con ${handoffShowCmd} ${top.compositeRef} e avvia il primo task pertinente. L'handoff resta attivo finché tutti i task della fase non sono done/canceled, viene sostituito da un nuovo handoff, oppure viene cancellato esplicitamente.`
                 : `→ Do you want to resume from ${top.compositeRef}? Read the handoff with ${handoffShowCmd} ${top.compositeRef} and start the first relevant task. It stays active until every phase task is done/canceled, a new handoff replaces it, or it is explicitly cleared.`);
@@ -115,7 +188,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) {
+    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.`);