@agent-plan/core 0.2.29 → 0.3.1

package/dist/mutation-reply.js

@@ -0,0 +1,203 @@
+/**
+ * Shared reply shaping for every mutation tool (update, discuss, and the
+ * small mutations around them).
+ *
+ * The rule this file exists to hold: a mutation result says what changed.
+ * It does not say what the entity now contains. Before P104(F005)/T417 each
+ * adapter hand-built `{ ...entity, updated: true }`, so changing one field
+ * on this repository's own P104 returned 139,805 characters — every task
+ * body in the phase, echoed back to a caller who already knew them. A task
+ * update peaked at 33,499. The harness had to spill those results to a file,
+ * and reading back whether `updated` was true then needed jq.
+ *
+ * The bound lives here rather than in an adapter for the reason in AGENTS.md
+ * rule 4: both adapters render what the core returns, so neither can drift
+ * and a third harness inherits the bound without knowing it exists. Four
+ * separate defects in P104 came from logic duplicated per adapter.
+ *
+ * Channel discipline matches handoff-reply.ts: `text` is the human-readable
+ * body, `structured` is the machine-readable payload, and no field is
+ * carried by both.
+ */
+import { truncateAtSafeBoundary } from "./text-bounds.js";
+/**
+ * Per-field echo budget. A changed field is worth showing back so the caller
+ * can confirm what landed without a second call; a changed field the size of
+ * a task description is not. 2,000 characters is about three screens — long
+ * enough to read a title, a status, a checklist or a short note whole, short
+ * enough that echoing a full description is impossible.
+ */
+export const MUTATION_ECHO_MAX_FIELD_CHARS = 2_000;
+/**
+ * Ceiling for the whole structured payload of a mutation reply. Chosen to
+ * match MAX_PHASE_WORK_MAP_CHARS and MAX_ACCEPTED_DECISION_CONTEXT_CHARS so
+ * an agent has one number in mind for planner payloads rather than four.
+ * When the assembled payload exceeds it, echoed values are dropped to names
+ * (see `boundMutationEcho`) — the caller still learns exactly which fields
+ * changed, which is the part it cannot get anywhere else.
+ */
+export const MUTATION_REPLY_MAX_CHARS = 8_000;
+/**
+ * The long-text size a planner tool accepts in one call, stated up front so
+ * a caller does not discover it by being rejected. This is not a limit the
+ * planner imposes for its own sake: a long `description` can be dropped by
+ * the transport before it ever reaches the planner, which arrives here as
+ * "no mutable fields received" and is why DESCRIPTION_MARKDOWN_FALLBACK_REQUIRED
+ * exists. Measured: ~13,500 characters accepted, ~17,000 rejected. 12,000 is
+ * under the observed floor with room to spare.
+ *
+ * Above this, write the prose to a committed file under `.planner/docs/` and
+ * pass `descriptionRef` — see suggestedDescriptionRefPath in payload-fallback.ts.
+ */
+export const PLANNER_LONG_TEXT_FIELD_MAX_CHARS = 12_000;
+/**
+ * One sentence for a tool description, so the limit is discoverable at the
+ * point of the call instead of after it fails. Every tool taking a long text
+ * field appends this to its own description.
+ */
+export function longTextFieldLimitNotice(field = "description") {
+    return `Keep ${field} under ${PLANNER_LONG_TEXT_FIELD_MAX_CHARS.toLocaleString("en-US")} characters; above that the transport may drop it before it arrives. Put longer prose in a committed .planner/docs/ file and pass ${field}Ref instead.`;
+}
+/**
+ * Bound one echoed value. A short string travels whole. A long one is cut at
+ * a safe boundary — paragraph, then line, then word, the same helper the
+ * handoff path uses — and reports its true length, so a caller can tell a
+ * 2,000-character field from a 20,000-character one without receiving either
+ * in full. Arrays and objects are measured by their serialized size and
+ * degrade to a count rather than a preview, because half an array read as
+ * whole is worse than no array at all.
+ */
+function boundEchoedValue(value) {
+    if (typeof value === "string") {
+        if (value.length <= MUTATION_ECHO_MAX_FIELD_CHARS)
+            return { value, truncated: false };
+        const bounded = truncateAtSafeBoundary(value, MUTATION_ECHO_MAX_FIELD_CHARS);
+        return {
+            value: { preview: bounded, fullLength: value.length, truncated: true },
+            truncated: true,
+        };
+    }
+    if (value === null || value === undefined || typeof value !== "object") {
+        return { value, truncated: false };
+    }
+    const serialized = JSON.stringify(value) ?? "";
+    if (serialized.length <= MUTATION_ECHO_MAX_FIELD_CHARS)
+        return { value, truncated: false };
+    if (Array.isArray(value)) {
+        return { value: { count: value.length, serializedLength: serialized.length, truncated: true }, truncated: true };
+    }
+    return { value: { keys: Object.keys(value), serializedLength: serialized.length, truncated: true }, truncated: true };
+}
+/**
+ * Assemble the echo of changed fields within the reply ceiling. Fields are
+ * taken in the order the caller changed them and the budget is shared, so
+ * one large field cannot crowd out the rest: what does not fit is named in
+ * `omittedValues` rather than silently dropped. Naming what was left out is
+ * the same degradation the prepare path uses — elided must never mean
+ * invisible.
+ */
+function boundMutationEcho(updatedFields, changedValues, budget) {
+    const changed = {};
+    const omittedValues = [];
+    const truncatedFields = [];
+    let remaining = budget;
+    for (const field of updatedFields) {
+        if (!(field in changedValues))
+            continue;
+        const bounded = boundEchoedValue(changedValues[field]);
+        const cost = (JSON.stringify(bounded.value) ?? "").length + field.length + 4;
+        if (cost > remaining) {
+            omittedValues.push(field);
+            continue;
+        }
+        remaining -= cost;
+        changed[field] = bounded.value;
+        if (bounded.truncated)
+            truncatedFields.push(field);
+    }
+    return { changed, omittedValues, truncatedFields };
+}
+/**
+ * Build the one reply every mutation tool returns.
+ *
+ * What a caller gets: that the write happened, which fields it touched, the
+ * canonical ref and identity of what it touched, the changed values within
+ * budget, and every diagnostic. What it does not get: the rest of the
+ * entity, which it can read with the command named in `readBack`.
+ *
+ * `updated` (or `discussed`), `updatedFields` and any `errorCode` keep their
+ * exact prior shape — mutation-integrity checking across the whole project
+ * reads those three and nothing else.
+ */
+export function buildMutationReply(input) {
+    const { identity, operation, updatedFields } = input;
+    const fields = [...updatedFields];
+    const extras = input.extras ?? {};
+    const identityPayload = {
+        entity: identity.entity,
+        ref: identity.ref,
+        ...(identity.id ? { id: identity.id } : {}),
+        ...(identity.shortId ? { shortId: identity.shortId } : {}),
+        ...(identity.title ? { title: identity.title } : {}),
+        ...(identity.status ? { status: identity.status } : {}),
+    };
+    // Everything except the echo is non-negotiable, so the echo gets whatever
+    // the ceiling leaves once identity, fields and diagnostics are counted.
+    const fixedCost = (JSON.stringify({ ...identityPayload, updatedFields: fields, ...extras }) ?? "").length;
+    const { changed, omittedValues, truncatedFields } = boundMutationEcho(fields, input.changedValues ?? {}, Math.max(0, MUTATION_REPLY_MAX_CHARS - fixedCost));
+    const structured = {
+        ...(operation === "discuss" ? { discussed: true } : { updated: true }),
+        ...identityPayload,
+        updatedFields: fields,
+        ...(Object.keys(changed).length > 0 ? { changed } : {}),
+        ...(truncatedFields.length > 0 ? { truncatedFields } : {}),
+        ...(omittedValues.length > 0 ? { omittedValues } : {}),
+        ...extras,
+        ...(input.readBackCommand ? { readBack: input.readBackCommand } : {}),
+    };
+    const descriptor = [identity.ref, identity.title].filter(Boolean).join(" — ");
+    const statusSuffix = identity.status ? ` (${identity.status})` : "";
+    const shortIdSuffix = identity.shortId ? ` · ${identity.shortId}` : "";
+    const verb = operation === "discuss" ? "discussed/updated" : "updated";
+    const entityLabel = identity.entity.charAt(0).toUpperCase() + identity.entity.slice(1);
+    const lines = [
+        `✅ ${entityLabel} ${verb}: ${descriptor}${statusSuffix}${shortIdSuffix}. Fields saved: ${fields.join(", ")}.`,
+        ...(input.notices ?? []).filter((notice) => notice.trim().length > 0),
+    ];
+    return { text: lines.join(" "), structured };
+}
+/**
+ * A feature/phase `status` field cannot be set directly — it is derived
+ * from child phases/tasks. Both adapters carried an identical copy of this
+ * refusal for feature_update/phase_update; only the retry line's tool name
+ * differs, which is why it is the one caller-supplied piece.
+ */
+export function derivedStatusReadOnlyReply(input) {
+    const { entity, ref, attemptedStatus, effectiveStatus, retryAction } = input;
+    const childKind = entity === "feature" ? "phases" : "tasks";
+    const label = `${entity[0].toUpperCase()}${entity.slice(1)}`;
+    const nextActions = [
+        `${label} status is derived from child ${childKind}; update the child ${childKind} instead of setting ${entity}.status.`,
+        retryAction,
+    ];
+    return {
+        text: [
+            `❌ ${entity.toUpperCase()} UPDATE FAILED [DERIVED_STATUS_READ_ONLY]`,
+            `${label} status is derived from child ${childKind} and cannot be set directly.`,
+            `Attempted status: ${attemptedStatus}`,
+            `Effective derived status: ${effectiveStatus}`,
+            "No planner data was changed.",
+            "Next required actions:",
+            ...nextActions.map((action, index) => `${index + 1}. ${action}`),
+        ].join("\n"),
+        structured: {
+            updated: false,
+            errorCode: "DERIVED_STATUS_READ_ONLY",
+            entity,
+            ref,
+            attemptedStatus,
+            effectiveStatus,
+            nextActions,
+        },
+    };
+}

package/dist/naming.d.ts

@@ -52,7 +52,7 @@ export declare function createPhaseId(): string;
 /** True for legacy phase ids that are NOT feature-scoped (e.g. `phase-01-...`). */
 export declare function isLegacyPhaseId(phaseId: string): boolean;
 /** Compute the feature-scoped id for a legacy phase, preserving featureId/number/slug. */
-export declare function migratePhaseId(featureId: string, number: number, slug: string): string;
+export declare function migratePhaseId(_featureId: string, _number: number, _slug: string): string;
 export declare function createTaskId(): string;
 export declare function createRequirementId(): string;
 export declare function createIdeaId(): string;

package/dist/naming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAKA;iFACiF;AACjF,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAErE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,YAAY,QAAoE,CAAC;AAE9F,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEtD;AAED;;gEAEgE;AAChE,wBAAsB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACnE,IAAI,EAAE,SAAS,GAAG,OAAO,EACzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACnC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAStD;AAGD;;;;;qCAKqC;AACrC,wBAAgB,aAAa,CAAC,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BtF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;8BAI8B;AAC9B,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAK,EAAE,QAAQ,SAAa,GAAG,MAAM,CAGnF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iBAEiB;AACjB,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,EAChD,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GACzC,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAKA;iFACiF;AACjF,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAErE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,YAAY,QAAoE,CAAC;AAE9F,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEtD;AAED;;gEAEgE;AAChE,wBAAsB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACnE,IAAI,EAAE,SAAS,GAAG,OAAO,EACzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACnC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAStD;AAGD;;;;;qCAKqC;AACrC,wBAAgB,aAAa,CAAC,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BtF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;8BAI8B;AAC9B,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAK,EAAE,QAAQ,SAAa,GAAG,MAAM,CAGnF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iBAEiB;AACjB,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,EAChD,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GACzC,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}

package/dist/naming.js

@@ -110,7 +110,7 @@ export function isLegacyPhaseId(phaseId) {
     return phaseId.startsWith("phase-") && !phaseId.startsWith("feature-");
 }
 /** Compute the feature-scoped id for a legacy phase, preserving featureId/number/slug. */
-export function migratePhaseId(featureId, number, slug) {
+export function migratePhaseId(_featureId, _number, _slug) {
     // In UUID world, this is just randomUUID, but we keep signature for compatibility if needed
     return randomUUID();
 }

package/dist/on-hold.d.ts

@@ -0,0 +1,55 @@
+import type { Feature, Phase } from "./schema.js";
+/**
+ * On-hold work that may be ready to resume.
+ *
+ * A task parked as deferred, waiting or blocked keeps its reason in the
+ * status log ("Resume once P097 lands"). Nothing used to look at those
+ * reasons again, so work whose blocker had finished stayed parked until a
+ * person noticed. This module is the one place that lists on-hold tasks
+ * with their reasons and checks the ones whose reason names planner refs:
+ * the recommendation and the load recap both read it, so they cannot
+ * disagree.
+ */
+export declare const ON_HOLD_STATUSES: Set<string>;
+export interface OnHoldRef {
+    /** The ref as written in the reason, normalized (e.g. `P097(F003)`, `T468`). */
+    ref: string;
+    /** Whether the named phase or task exists and is finished. */
+    finished: boolean;
+    /** False when the ref names nothing in this plan. */
+    found: boolean;
+}
+export interface OnHoldTask {
+    taskId: string;
+    ref: string;
+    title: string;
+    status: string;
+    phaseId: string;
+    phaseRef: string;
+    /** Why it was put on hold: the motivation of the status change that parked it. */
+    reason: string;
+    heldSince: string;
+    /** Planner refs named in the reason, each checked against the plan. */
+    namedRefs: OnHoldRef[];
+    /** True when the reason names at least one ref and every named ref is finished. */
+    readyToResume: boolean;
+}
+/** Resolve every planner ref named in `text`, by number only (never by title). */
+export declare function refsNamedIn(text: string, phases: Phase[], features: Feature[], selfTaskId?: string): OnHoldRef[];
+/**
+ * Every on-hold task, ready-to-resume ones first. Pass `phaseIds` to limit
+ * the list to the phases a caller is about to act on.
+ */
+export declare function listOnHoldWork(features: Feature[], phases: Phase[], phaseIds?: Set<string>): OnHoldTask[];
+/**
+ * The phases whose on-hold work matters now: phases where work has started
+ * (some task finished or in progress) but not every task is finished. A
+ * phase nobody has started yet keeps its on-hold tasks out of the way.
+ */
+export declare function startedOpenPhaseIds(phases: Phase[]): Set<string>;
+/**
+ * One bounded text block for any reply. Ready-to-resume tasks first; each
+ * line carries the reason so the agent can re-check it against the plan.
+ */
+export declare function renderOnHoldWork(items: OnHoldTask[], limit?: number): string;
+//# sourceMappingURL=on-hold.d.ts.map

package/dist/on-hold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-hold.d.ts","sourceRoot":"","sources":["../src/on-hold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAQ,MAAM,aAAa,CAAC;AAGxD;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB,aAA8C,CAAC;AAG5E,MAAM,WAAW,SAAS;IACxB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,mFAAmF;IACnF,aAAa,EAAE,OAAO,CAAC;CACxB;AAgBD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,SAAK,GAAG,SAAS,EAAE,CA8B5G;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,UAAU,EAAE,CAwBzG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAKhE;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,SAAI,GAAG,MAAM,CAiBvE"}

package/dist/on-hold.js

@@ -0,0 +1,123 @@
+import { featureNumberOfPhase, formatPhaseRef } from "./naming.js";
+/**
+ * On-hold work that may be ready to resume.
+ *
+ * A task parked as deferred, waiting or blocked keeps its reason in the
+ * status log ("Resume once P097 lands"). Nothing used to look at those
+ * reasons again, so work whose blocker had finished stayed parked until a
+ * person noticed. This module is the one place that lists on-hold tasks
+ * with their reasons and checks the ones whose reason names planner refs:
+ * the recommendation and the load recap both read it, so they cannot
+ * disagree.
+ */
+export const ON_HOLD_STATUSES = new Set(["deferred", "waiting", "blocked"]);
+const FINISHED = new Set(["done", "canceled", "rejected"]);
+// A phase ref with optional feature and task, in either spelling
+// (`P097`, `P097(F003)`, `F003/P097`, `P094(F011)/T449`, `F011/P094/T449`),
+// or a bare task ref (`T468`). Word-bounded so prose like "HTTP2" or
+// "T-shirt" never matches.
+const REF_IN_TEXT = /\b(?:F(\d{1,4})\/)?P(\d{1,4})(?:\(F(\d{1,4})\))?(?:\/T(\d{1,4}))?(?!\w)|\bT(\d{1,4})(?!\w)/g;
+const pad = (n) => String(n).padStart(3, "0");
+function holdEntry(task) {
+    const entry = [...(task.statusLog ?? [])].reverse().find((log) => log.toStatus === task.status);
+    const reason = (entry?.description ?? "").replace(/^Motivation:\s*/i, "").trim();
+    return { reason, at: entry?.date ?? task.updatedAt ?? "" };
+}
+/** Resolve every planner ref named in `text`, by number only (never by title). */
+export function refsNamedIn(text, phases, features, selfTaskId = "") {
+    const phaseByNumber = new Map(phases.map((phase) => [phase.number, phase]));
+    const taskByNumber = new Map(phases.flatMap((phase) => phase.tasks.map((task) => [task.number, { phase, task }])));
+    const featureByNumber = new Map(features.map((feature) => [feature.number, feature]));
+    const seen = new Map();
+    for (const match of text.matchAll(REF_IN_TEXT)) {
+        const [, leadingFeatureNum, phaseNum, trailingFeatureNum, phaseTaskNum, bareTaskNum] = match;
+        const featureNum = trailingFeatureNum ?? leadingFeatureNum;
+        if (bareTaskNum || phaseTaskNum) {
+            const taskNum = Number(bareTaskNum ?? phaseTaskNum);
+            const hit = taskByNumber.get(taskNum);
+            const parentOk = !phaseNum || hit?.phase.number === Number(phaseNum);
+            const featureOk = !featureNum || (hit && hit.phase.featureId === featureByNumber.get(Number(featureNum))?.id);
+            const ref = phaseNum
+                ? `P${pad(Number(phaseNum))}${featureNum ? `(F${pad(Number(featureNum))})` : ""}/T${pad(taskNum)}`
+                : `T${pad(taskNum)}`;
+            if (hit?.task.id === selfTaskId)
+                continue;
+            const found = Boolean(hit && parentOk && featureOk);
+            seen.set(ref, { ref, found, finished: found && FINISHED.has(hit.task.status) });
+            continue;
+        }
+        const phase = phaseByNumber.get(Number(phaseNum));
+        const featureOk = !featureNum || (phase && phase.featureId === featureByNumber.get(Number(featureNum))?.id);
+        const ref = `P${pad(Number(phaseNum))}${featureNum ? `(F${pad(Number(featureNum))})` : ""}`;
+        const found = Boolean(phase && featureOk);
+        const finished = found && phase.tasks.length > 0 && phase.tasks.every((task) => FINISHED.has(task.status));
+        seen.set(ref, { ref, found, finished });
+    }
+    return [...seen.values()];
+}
+/**
+ * Every on-hold task, ready-to-resume ones first. Pass `phaseIds` to limit
+ * the list to the phases a caller is about to act on.
+ */
+export function listOnHoldWork(features, phases, phaseIds) {
+    const items = [];
+    for (const phase of phases) {
+        if (phaseIds && !phaseIds.has(phase.id))
+            continue;
+        const phaseRef = formatPhaseRef(phase.number, featureNumberOfPhase(phase, features));
+        for (const task of phase.tasks) {
+            if (!ON_HOLD_STATUSES.has(task.status))
+                continue;
+            const { reason, at } = holdEntry(task);
+            const namedRefs = refsNamedIn(reason, phases, features, task.id);
+            items.push({
+                taskId: task.id,
+                ref: `${phaseRef}/T${pad(task.number)}`,
+                title: task.title,
+                status: task.status,
+                phaseId: phase.id,
+                phaseRef,
+                reason,
+                heldSince: at,
+                namedRefs,
+                readyToResume: namedRefs.length > 0 && namedRefs.every((named) => named.finished),
+            });
+        }
+    }
+    return items.sort((left, right) => Number(right.readyToResume) - Number(left.readyToResume));
+}
+/**
+ * The phases whose on-hold work matters now: phases where work has started
+ * (some task finished or in progress) but not every task is finished. A
+ * phase nobody has started yet keeps its on-hold tasks out of the way.
+ */
+export function startedOpenPhaseIds(phases) {
+    return new Set(phases
+        .filter((phase) => phase.tasks.some((task) => FINISHED.has(task.status) || task.status === "in-progress"))
+        .filter((phase) => phase.tasks.some((task) => !FINISHED.has(task.status)))
+        .map((phase) => phase.id));
+}
+const REASON_PREVIEW_CHARS = 160;
+/**
+ * One bounded text block for any reply. Ready-to-resume tasks first; each
+ * line carries the reason so the agent can re-check it against the plan.
+ */
+export function renderOnHoldWork(items, limit = 8) {
+    if (items.length === 0)
+        return "";
+    const shown = items.slice(0, limit);
+    const lines = shown.map((item) => {
+        const reason = item.reason
+            ? item.reason.length > REASON_PREVIEW_CHARS ? `${item.reason.slice(0, REASON_PREVIEW_CHARS).trimEnd()}…` : item.reason
+            : "(no reason recorded)";
+        const check = item.readyToResume
+            ? ` — MAY BE READY: everything its reason names is finished (${item.namedRefs.map((named) => named.ref).join(", ")}); re-check and resume it if nothing else holds it`
+            : item.namedRefs.some((named) => !named.finished)
+                ? ` — still waiting on ${item.namedRefs.filter((named) => !named.finished).map((named) => named.found ? named.ref : `${named.ref} (not found)`).join(", ")}`
+                : "";
+        return `- ${item.ref} — ${item.title} [${item.status}]${check}\n  Reason: ${reason}`;
+    });
+    const more = items.length > shown.length ? `\n(${items.length - shown.length} more on hold; list them with the phase's task list.)` : "";
+    const ready = items.filter((item) => item.readyToResume).length;
+    return `On hold — check whether these can resume (${items.length} on hold${ready ? `, ${ready} may be ready` : ""}):\n${lines.join("\n")}${more}`;
+}

package/dist/package-version.d.ts

@@ -8,4 +8,17 @@ export interface RuntimePackageVersion {
 export declare function packageVersionFromModule(moduleUrlOrPath: string, expectedName: string): RuntimePackageVersion;
 /** Resolve a dependency exactly as the caller loaded it, then read its manifest. */
 export declare function resolvedPackageVersion(packageName: string, fromModuleUrl: string): RuntimePackageVersion;
+/**
+ * A long-lived process (an MCP server a session started, a Pi extension)
+ * keeps running the code it loaded. After an upgrade it silently runs old
+ * code, so an already-fixed bug looks like it came back. This returns a
+ * checker that re-reads the loaded package's manifest — one small file, at
+ * most once per `intervalMs` — and returns a one-line notice while the
+ * version on disk differs from the one loaded. It never throws: an
+ * unreadable manifest means no notice.
+ */
+export declare function createStaleProcessCheck(loaded: RuntimePackageVersion, { intervalMs, now }?: {
+    intervalMs?: number;
+    now?: () => number;
+}): () => string | undefined;
 //# sourceMappingURL=package-version.d.ts.map

package/dist/package-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../src/package-version.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAaD,wEAAwE;AACxE,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAqBvB;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB,qBAAqB,CAGvB"}
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../src/package-version.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAaD,wEAAwE;AACxE,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAqBvB;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,GACpB,qBAAqB,CAGvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,qBAAqB,EAC7B,EAAE,UAAwB,EAAE,GAAsB,EAAE,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GACrG,MAAM,MAAM,GAAG,SAAS,CAmB1B"}

package/dist/package-version.js

@@ -33,3 +33,35 @@ export function resolvedPackageVersion(packageName, fromModuleUrl) {
     const entryPath = createRequire(fromModuleUrl).resolve(packageName);
     return packageVersionFromModule(entryPath, packageName);
 }
+/**
+ * A long-lived process (an MCP server a session started, a Pi extension)
+ * keeps running the code it loaded. After an upgrade it silently runs old
+ * code, so an already-fixed bug looks like it came back. This returns a
+ * checker that re-reads the loaded package's manifest — one small file, at
+ * most once per `intervalMs` — and returns a one-line notice while the
+ * version on disk differs from the one loaded. It never throws: an
+ * unreadable manifest means no notice.
+ */
+export function createStaleProcessCheck(loaded, { intervalMs = 10 * 60_000, now = () => Date.now() } = {}) {
+    let checkedAt = Number.NEGATIVE_INFINITY;
+    let notice;
+    return () => {
+        if (!loaded.packageJsonPath)
+            return undefined;
+        const time = now();
+        if (time - checkedAt < intervalMs)
+            return notice;
+        checkedAt = time;
+        notice = undefined;
+        try {
+            const manifest = JSON.parse(readFileSync(loaded.packageJsonPath, "utf-8"));
+            if (typeof manifest.version === "string" && manifest.version.trim() && manifest.version !== loaded.version) {
+                notice = `⚠️ This session is running ${loaded.name} ${loaded.version}, but ${manifest.version} is now installed. Restart the session (in Claude Code: /mcp, then reconnect agent-plan) to use it; until then, fixes made after ${loaded.version} are not active here.`;
+            }
+        }
+        catch {
+            notice = undefined;
+        }
+        return notice;
+    };
+}

package/dist/pagination.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared list-pagination primitive. Both adapters defined an identical
+ * `boundedPage` (page list tools: feature/phase/task/requirement listing,
+ * idea listing) with the same 1-25 page-size clamp and the same
+ * page-out-of-range clamp. One copy here so the bound is a single decision,
+ * not something each adapter must independently re-derive and keep in sync.
+ */
+export interface BoundedPage<T> {
+    items: T[];
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+}
+/** Slice `items` into a bounded page. `pageSize` is clamped to [1, 25];
+ *  `page` is clamped to [1, totalPages] so an out-of-range request degrades
+ *  to the nearest valid page instead of an empty result. */
+export declare function boundedPage<T>(items: T[], page: number, pageSize: number): BoundedPage<T>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;4DAE4D;AAC5D,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAWzF"}

package/dist/pagination.js

@@ -0,0 +1,15 @@
+/** Slice `items` into a bounded page. `pageSize` is clamped to [1, 25];
+ *  `page` is clamped to [1, totalPages] so an out-of-range request degrades
+ *  to the nearest valid page instead of an empty result. */
+export function boundedPage(items, page, pageSize) {
+    const size = Math.min(25, Math.max(1, Math.trunc(pageSize)));
+    const totalPages = Math.max(1, Math.ceil(items.length / size));
+    const currentPage = Math.min(totalPages, Math.max(1, Math.trunc(page)));
+    return {
+        items: items.slice((currentPage - 1) * size, currentPage * size),
+        page: currentPage,
+        pageSize: size,
+        total: items.length,
+        totalPages,
+    };
+}

package/dist/payload-fallback.js

@@ -8,7 +8,7 @@ export function isPlannerDescriptionRef(value) {
     if (value.includes("\\") || value.includes("\0"))
         return false;
     const parts = value.split("/");
-    if (parts.length < 4)
+    if (parts.length < 3)
         return false;
     if (parts[0] !== ".planner" || parts[1] !== "docs")
         return false;