@agent-plan/core 0.2.28 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./naming.js";
 export * from "./refs.js";
+export * from "./render-utils.js";
+export * from "./pagination.js";
+export * from "./task-lifecycle.js";
 export * from "./schema.js";
 export * from "./checklist.js";
 export * from "./recap.js";
@@ -7,18 +10,29 @@ export * from "./planner-rules.js";
 export * from "./planner-skill.js";
 export * from "./display-status.js";
 export * from "./description-freshness.js";
+export * from "./text-bounds.js";
 export * from "./task-context.js";
 export * from "./task-selection.js";
 export * from "./task-start-outcome.js";
+export * from "./task-order-context.js";
+export * from "./task-completion-gate.js";
+export * from "./stranded-phase.js";
 export * from "./read-tracking.js";
 export * from "./payload-fallback.js";
 export * from "./handoff-context.js";
+export * from "./handoff-reply.js";
+export * from "./mutation-reply.js";
+export * from "./recommend-reply.js";
+export * from "./feature-delete.js";
+export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
+export * from "./project-context.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
 export * from "./runtime-diagnostics.js";
 export * from "./write-coordination.js";
-export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, type IdeaCreateInput, type IdeaUpdateInput, type IdeaPromotionTargetInput, type AcceptedDecisionOwner, type AcceptedDecisionCreateInput, type AcceptedDecisionUpdateInput, type PhaseHandoffSummary, type OrphanPhaseSummary } from "./plan-store.js";
+export * from "./guard-decision.js";
+export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, nowISO, type IdeaCreateInput, type IdeaUpdateInput, type IdeaPromotionTargetInput, type AcceptedDecisionOwner, type AcceptedDecisionCreateInput, type AcceptedDecisionUpdateInput, type RecordProjectContextReadInput, type RecordProjectContextReadResult, type PhaseHandoffSummary, type OrphanPhaseSummary } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";
 export type { CodebaseProfile, ResumeFocus, ActivityEntry, ActivityLog, AmbientFacts } from "./schema.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1c,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,6BAA6B,EAAE,KAAK,8BAA8B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3hB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,5 +1,8 @@
 export * from "./naming.js";
 export * from "./refs.js";
+export * from "./render-utils.js";
+export * from "./pagination.js";
+export * from "./task-lifecycle.js";
 export * from "./schema.js";
 export * from "./checklist.js";
 export * from "./recap.js";
@@ -7,17 +10,28 @@ export * from "./planner-rules.js";
 export * from "./planner-skill.js";
 export * from "./display-status.js";
 export * from "./description-freshness.js";
+export * from "./text-bounds.js";
 export * from "./task-context.js";
 export * from "./task-selection.js";
 export * from "./task-start-outcome.js";
+export * from "./task-order-context.js";
+export * from "./task-completion-gate.js";
+export * from "./stranded-phase.js";
 export * from "./read-tracking.js";
 export * from "./payload-fallback.js";
 export * from "./handoff-context.js";
+export * from "./handoff-reply.js";
+export * from "./mutation-reply.js";
+export * from "./recommend-reply.js";
+export * from "./feature-delete.js";
+export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
+export * from "./project-context.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
 export * from "./runtime-diagnostics.js";
 export * from "./write-coordination.js";
-export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock } from "./plan-store.js";
+export * from "./guard-decision.js";
+export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, nowISO } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";

package/dist/mutation-reply.d.ts

@@ -0,0 +1,105 @@
+import type { PlannerPayloadEntity, PlannerPayloadOperation } from "./payload-fallback.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 declare const MUTATION_ECHO_MAX_FIELD_CHARS = 2000;
+/**
+ * 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 declare const MUTATION_REPLY_MAX_CHARS = 8000;
+/**
+ * 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 declare const PLANNER_LONG_TEXT_FIELD_MAX_CHARS = 12000;
+/**
+ * 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 declare function longTextFieldLimitNotice(field?: string): string;
+/** A tool reply as one result: the human-readable body and the structured
+ * payload, with no field present in both. */
+export interface MutationReply {
+    text: string;
+    structured: Record<string, unknown>;
+}
+/** Who was mutated, in the terms a caller refers to it by. The canonical
+ * `ref` is what travels — never the raw text the caller happened to type,
+ * which may be a short id, a title or a UUID. */
+export interface MutationIdentity {
+    entity: PlannerPayloadEntity;
+    ref: string;
+    id?: string;
+    shortId?: string;
+    title?: string;
+    status?: string;
+}
+export interface MutationReplyInput {
+    identity: MutationIdentity;
+    operation: PlannerPayloadOperation;
+    /** Fields the caller actually changed, in the order they were received. */
+    updatedFields: readonly string[];
+    /** The persisted values of those fields, to be echoed back within budget.
+     * Keys outside `updatedFields` are ignored: a mutation reply never carries
+     * a field the mutation did not touch. */
+    changedValues?: Record<string, unknown>;
+    /** Diagnostics that are not the entity — description freshness, stale
+     * parents, lost checklist ticks, resume-required notices. These are the
+     * reason to read a mutation result at all, so they are never trimmed. */
+    extras?: Record<string, unknown>;
+    /** Extra lines for the human channel, such as a lost-tick warning. */
+    notices?: readonly string[];
+    /** The command that returns the full entity, for a caller that wants what
+     * this reply deliberately leaves out. */
+    readBackCommand?: string;
+}
+/**
+ * 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 declare function buildMutationReply(input: MutationReplyInput): MutationReply;
+export interface DerivedStatusReadOnlyInput {
+    entity: "feature" | "phase";
+    ref: string;
+    attemptedStatus: string;
+    effectiveStatus: string;
+    /** Full "retry without the status field" instruction. Each adapter names
+     *  its own update tool (`planner-feature-update` vs `feature_update`), so
+     *  this one line stays adapter-supplied rather than templated here —
+     *  moving it into the core would restate a tool name the core doesn't own. */
+    retryAction: string;
+}
+/**
+ * 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 declare function derivedStatusReadOnlyReply(input: DerivedStatusReadOnlyInput): MutationReply;
+//# sourceMappingURL=mutation-reply.d.ts.map

package/dist/mutation-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-reply.d.ts","sourceRoot":"","sources":["../src/mutation-reply.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAE3F;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,OAAQ,CAAC;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,SAAgB,GAAG,MAAM,CAEtE;AAED;6CAC6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;iDAEiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,uBAAuB,CAAC;IACnC,2EAA2E;IAC3E,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;6CAEyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;6EAEyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sEAAsE;IACtE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;6CACyC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CA6C3E;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB;;;kFAG8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,aAAa,CA4B3F"}

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