@agent-plan/core 0.2.24 → 0.2.25

package/dist/planner-rules.d.ts

@@ -1,13 +1,3 @@
-/**
- * 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[];
@@ -15,7 +5,9 @@ export interface ExtensionRulesFile {
 /**
  * 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.
+ * otherwise the canonical code set. Exact legacy canonical read-protocol rules
+ * are upgraded in memory without rewriting the project file; unrelated project
+ * overrides remain untouched. 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

@@ -1 +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"}
+{"version":3,"file":"planner-rules.d.ts","sourceRoot":"","sources":["../src/planner-rules.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,uBAAuB,EAAE,MAAM,EA2B3C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAUD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW/E"}

package/dist/planner-rules.js

@@ -10,6 +10,10 @@ import { join } from "node:path";
  * AGENTS.md governs ONLY the development of the agent-plan extension and must
  * not duplicate these rules.
  */
+const DETAIL_WRITING_RULE = "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. For starting, resuming, or switching, call the lifecycle tool first so valid session attestations can be reused. If it denies the operation, perform only the missing or stale full reads listed in nextActions, in that exact order, then retry; read linked requirements explicitly only when requested. Cite entities with composite IDs, not bare UUIDs.";
+const EXPECTED_OPERATIONAL_RULE = "When you begin work, task_start and task_switch enforce session-scoped context reads and return precise missing/stale read actions when needed. 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.";
+const LEGACY_DETAIL_WRITING_RULE = "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.";
+const LEGACY_EXPECTED_OPERATIONAL_RULE = "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.";
 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.",
@@ -31,24 +35,35 @@ export const PLANNER_EXTENSION_RULES = [
     "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
+    // Planner startup
     "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.",
+    // Detail-writing rule
+    DETAIL_WRITING_RULE,
     // 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.",
+    EXPECTED_OPERATIONAL_RULE,
 ];
+function normalizeLegacyRules(rules) {
+    return rules.map((rule) => {
+        if (rule === LEGACY_DETAIL_WRITING_RULE)
+            return DETAIL_WRITING_RULE;
+        if (rule === LEGACY_EXPECTED_OPERATIONAL_RULE)
+            return EXPECTED_OPERATIONAL_RULE;
+        return rule;
+    });
+}
 /**
  * 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.
+ * otherwise the canonical code set. Exact legacy canonical read-protocol rules
+ * are upgraded in memory without rewriting the project file; unrelated project
+ * overrides remain untouched. 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);
+            return normalizeLegacyRules(parsed.extensionRules.filter((r) => typeof r === "string" && r.length > 0));
         }
     }
     catch {

package/dist/read-tracking.d.ts

@@ -4,7 +4,7 @@
  * 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.
+ * the entity's context revision remains at or before its attestation timestamp.
  */
 type SessionInfoEntry = {
     sessionId: string;
@@ -12,11 +12,19 @@ type SessionInfoEntry = {
 };
 type ReadTrackedEntity = {
     updatedAt: string;
+    descriptionUpdatedAt?: string;
     sessionInfo?: SessionInfoEntry[];
 };
+export type ContextReadEntityKind = "task" | "phase" | "feature";
+export type RequiredContextRead = {
+    kind: ContextReadEntityKind;
+    id: string;
+    state: "missing" | "stale" | "out-of-order";
+};
 export type ContextReadEligibility = {
     eligible: boolean;
     reason: string;
+    requiredReads?: RequiredContextRead[];
 };
 export interface SessionContextReadInput {
     sessionId: string;
@@ -48,9 +56,10 @@ 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.
+ * Combine valid persisted attestations with fresh in-memory reads. The initial
+ * uncached lineage still requires task → phase → feature ordering, while a
+ * stale or missing individual entity can be reread without discarding valid
+ * parent attestations from the same harness session.
  */
 export declare function contextReadEligibilityForSession(input: SessionContextReadInput): ContextReadEligibility;
 /** Return true only when the persisted attestation covers the current revisions. */

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

@@ -1 +1 @@
-{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,KAAK,gBAAgB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,KAAK,iBAAiB,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAClC,CAAC;AAUF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,YAAY,CAAC,EAAE,KAAK,CAAC,iBAAiB,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AA8CD,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,kEAAkE;AAClE,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAEtF;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAExE;AAED,gEAAgE;AAChE,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAElF;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF;AAED,+DAA+D;AAC/D,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEhF;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED,6EAA6E;AAC7E,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAE9F;AAyCD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,uBAAuB,GAAG,sBAAsB,CAQvG;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAElF;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAElH;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGtF;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EAAE,EACxB,YAAY,GAAE,KAAK,CAAC,iBAAiB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAM,GAC3D,OAAO,CAGT;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAErE;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAQxD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAExD;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIzF;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,CAMxE;AAED,gCAAgC;AAChC,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAOzH"}
+{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"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"}

package/dist/read-tracking.js

@@ -4,7 +4,7 @@
  * 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.
+ * the entity's context revision remains at or before its attestation timestamp.
  */
 const DEFAULT_SESSION_ID = "__default__";
 const newState = () => ({
@@ -93,37 +93,76 @@ function orderedEligibility(sessionId, taskId, phaseId, featureId) {
     }
     return { eligible: true, reason: "" };
 }
-function validSessionInfo(entity, sessionId) {
+function entityRevision(entity, kind) {
+    if ((kind === "phase" || kind === "feature") && entity.descriptionUpdatedAt?.trim()) {
+        return entity.descriptionUpdatedAt;
+    }
+    return entity.updatedAt;
+}
+function storedReadState(entity, sessionId, kind) {
     const entry = entity?.sessionInfo?.find((candidate) => candidate.sessionId === sessionId);
-    return Boolean(entity && entry && entity.updatedAt <= entry.createdAt);
+    if (!entity || !entry)
+        return "missing";
+    return entityRevision(entity, kind) <= entry.createdAt ? "valid" : "stale";
+}
+function validSessionInfo(entity, sessionId, kind = "requirement") {
+    return storedReadState(entity, sessionId, kind) === "valid";
 }
 function persistedEligibility(input) {
-    if (!validSessionInfo(input.task, input.sessionId) || !validSessionInfo(input.phase, input.sessionId))
+    if (!validSessionInfo(input.task, input.sessionId, "task") || !validSessionInfo(input.phase, input.sessionId, "phase"))
         return false;
-    if (input.featureId && !validSessionInfo(input.feature, input.sessionId))
+    if (input.featureId && !validSessionInfo(input.feature, input.sessionId, "feature"))
         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));
+function requiredReadReason(requiredReads) {
+    const labels = requiredReads.map((read) => `${read.kind} ${read.id} (${read.state})`);
+    return `Read required context only for: ${labels.join(", ")}. Follow these reads in the listed order, then retry.`;
 }
 /**
- * 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.
+ * Combine valid persisted attestations with fresh in-memory reads. The initial
+ * uncached lineage still requires task → phase → feature ordering, while a
+ * stale or missing individual entity can be reread without discarding valid
+ * parent attestations from the same harness session.
  */
 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." };
+    const state = stateFor(input.sessionId);
+    const requiredReads = [];
+    const taskStored = storedReadState(input.task, input.sessionId, "task");
+    const taskSequence = state.tasks.get(input.taskId);
+    const taskReady = taskStored === "valid" || taskSequence !== undefined;
+    if (!taskReady) {
+        requiredReads.push({ kind: "task", id: input.taskId, state: taskStored === "stale" ? "stale" : "missing" });
     }
-    return ordered;
+    const phaseStored = storedReadState(input.phase, input.sessionId, "phase");
+    const phaseSequence = state.phases.get(input.phaseId);
+    const phaseReadInOrder = phaseSequence !== undefined
+        && (taskStored === "valid" || (taskSequence !== undefined && phaseSequence > taskSequence));
+    const phaseReady = phaseStored === "valid" || phaseReadInOrder;
+    if (!phaseReady) {
+        requiredReads.push({
+            kind: "phase",
+            id: input.phaseId,
+            state: phaseStored === "stale" ? "stale" : phaseSequence !== undefined ? "out-of-order" : "missing",
+        });
+    }
+    if (input.featureId) {
+        const featureStored = storedReadState(input.feature, input.sessionId, "feature");
+        const featureSequence = state.features.get(input.featureId);
+        const featureReadInOrder = featureSequence !== undefined
+            && (phaseStored === "valid" || (phaseReadInOrder && phaseSequence !== undefined && featureSequence > phaseSequence));
+        if (featureStored !== "valid" && !featureReadInOrder) {
+            requiredReads.push({
+                kind: "feature",
+                id: input.featureId,
+                state: featureStored === "stale" ? "stale" : featureSequence !== undefined ? "out-of-order" : "missing",
+            });
+        }
+    }
+    if (requiredReads.length === 0)
+        return { eligible: true, reason: "" };
+    return { eligible: false, reason: requiredReadReason(requiredReads), requiredReads };
 }
 /** Return true only when the persisted attestation covers the current revisions. */
 export function hasValidSessionAttestation(input) {

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,CA4OhH"}
+{"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,CAuOhH"}

package/dist/recap.js

@@ -63,9 +63,6 @@ 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)";
@@ -78,9 +75,7 @@ export async function buildRecap(st, web = {}, opts = {}) {
         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).`);
+        lines.push("", `Continue with ${taskStartCmd} ${tr}. If context reads are required, follow only the missing or stale reads in its nextActions, then retry.`);
     }
     else if (pendingResume) {
         const feature = feats.find((entry) => entry.id === pendingResume.phase.featureId);

package/dist/task-selection.js

@@ -27,7 +27,7 @@ export function checkExplicitTaskStart(features, phases, taskId, deviations = []
         return { eligible: false, reason: `Task is not startable from ${candidate.task.status}.` };
     const parentHasHardBlock = hardUnavailable.has(candidate.phase.status)
         || (candidate.feature && hardUnavailable.has(candidate.feature.status));
-    if (parentHasHardBlock || (!isTemporaryOverride && (unavailable.has(candidate.phase.status) || (candidate.feature && unavailable.has(candidate.feature.status))))) {
+    if (parentHasHardBlock) {
         return { eligible: false, reason: "Task belongs to an unavailable phase or feature." };
     }
     const taskById = new Map(candidates.map((entry) => [entry.task.id, entry]));
@@ -91,7 +91,7 @@ export function recommendNextTask(features, phases, deviations = [], currentPhas
     const ready = candidates.filter(({ feature, phase, task }) => {
         if (task.status !== "planned")
             return false;
-        if (unavailable.has(phase.status) || (feature && unavailable.has(feature.status)))
+        if (hardUnavailable.has(phase.status) || (feature && hardUnavailable.has(feature.status)))
             return false;
         return task.dependsOn.every((id) => byTaskId.get(id)?.task.status === "done");
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/core",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "private": false,
   "description": "Harness-agnostic core for Agent Plan: schemas, persistence, ordering, status rollups, and markdown rendering.",
   "license": "MIT",