@agent-plan/core 0.2.23 → 0.2.25

package/dist/read-tracking.d.ts

@@ -1,49 +1,95 @@
 /**
- * Per-session, ordered context-read enforcement for agent lifecycle operations.
+ * Session-scoped, 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.
+ * 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
+ * the entity's context revision remains at or before its attestation timestamp.
  */
+type SessionInfoEntry = {
+    sessionId: string;
+    createdAt: string;
+};
+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[];
 };
-/** Record a full feature read. */
+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 phase read. The parent feature is intentionally not implied. */
+/** 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 task read. Its parent phase and feature are intentionally not implied. */
+/** 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 that a requirement was explicitly read via the requirement list tool. */
+/** 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;
 /**
- * Verify the required task(full) → phase(full) → feature(full) order for one
- * exact task lineage. Orphan phases do not require a feature read.
+ * 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. */
+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;
 /**
- * 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.
+ * Whether linked requirements are read in memory or have valid persisted
+ * attestations for the current session and entity revisions.
  */
-export declare function hasReadParents(featureId: string | undefined, phaseId: string): boolean;
-/** Whether every linked requirement has been explicitly read. */
+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 all read state so later lifecycle work requires fresh context. */
-export declare function invalidateReads(): void;
+/** 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 and tests. */
-export declare function readTrackingSnapshot(): {
+/** 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

@@ -1 +1 @@
-{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAeF,kCAAkC;AAClC,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAExE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAmBlH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAItF;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAErE;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,IAAI,IAAI,CAQtC;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,CAKxE;AAED,0CAA0C;AAC1C,wBAAgB,oBAAoB,IAAI;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAMvG"}
+{"version":3,"file":"read-tracking.d.ts","sourceRoot":"","sources":["../src/read-tracking.ts"],"names":[],"mappings":"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"}

package/dist/read-tracking.js

@@ -1,46 +1,82 @@
 /**
- * Per-session, ordered context-read enforcement for agent lifecycle operations.
+ * Session-scoped, 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.
+ * 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
+ * the entity's context revision remains at or before its attestation timestamp.
  */
-let state = {
+const DEFAULT_SESSION_ID = "__default__";
+const newState = () => ({
     tasks: new Map(),
     phases: new Map(),
     features: new Map(),
     requirements: new Set(),
     nextSequence: 0,
-};
-function record(map, id) {
+});
+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);
 }
-/** Record a full feature read. */
+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) {
-    record(state.features, featureId);
+    markFeatureReadForSession(DEFAULT_SESSION_ID, featureId);
 }
-/** Record a full phase read. The parent feature is intentionally not implied. */
+/** 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) {
-    record(state.phases, phaseId);
+    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. Its parent phase and feature are intentionally not implied. */
+/** Record a full task read in the default compatibility session. */
 export function markTaskRead(taskId, _phaseId, _featureId) {
-    record(state.tasks, taskId);
+    markTaskReadForSession(DEFAULT_SESSION_ID, taskId);
 }
-/** Record that a requirement was explicitly read via the requirement list tool. */
+/** 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) {
-    state.requirements.add(requirementId);
+    stateFor(DEFAULT_SESSION_ID).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) {
+/** 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." };
@@ -57,38 +93,126 @@ export function contextReadEligibility(taskId, phaseId, featureId) {
     }
     return { eligible: true, reason: "" };
 }
+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);
+    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, "task") || !validSessionInfo(input.phase, input.sessionId, "phase"))
+        return false;
+    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 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.`;
+}
 /**
- * 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.
+ * 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 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" });
+    }
+    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) {
+    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 phaseOk = state.phases.has(phaseId);
-    const featureOk = featureId ? state.features.has(featureId) : true;
-    return phaseOk && featureOk;
+    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));
 }
-/** Whether every linked requirement has been explicitly read. */
+/** Legacy requirement check for the default compatibility session. */
 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,
-    };
+    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) {
-    if (hasReadParents(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));
@@ -96,8 +220,9 @@ export function requirementReadAdvisory(requirementIds) {
         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() {
+/** Snapshot for diagnostics. */
+export function readTrackingSnapshot(sessionId) {
+    const state = stateFor(sessionId);
     return {
         features: [...state.features.keys()],
         phases: [...state.phases.keys()],

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);