@agent-plan/core 0.2.29 → 0.3.1

package/dist/accepted-decision-guard.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Accepted Decision ownership rule and the compatibility guards that enforce
+ * it, shared by every adapter (MCP, Pi, HTTP, and any future harness).
+ *
+ * The rule: a decision has exactly one owner. Project-wide decisions belong
+ * only to project.acceptedDecisions; feature-wide decisions only to that
+ * feature; phase-specific decisions only to that phase; genuinely
+ * task-local decisions only to that task. Nothing duplicates a decision
+ * across two owners by default — see the semantic createAcceptedDecision /
+ * updateAcceptedDecision / deleteAcceptedDecision operations in
+ * plan-store.ts, which already write to exactly one target.
+ *
+ * Two things previously worked against that rule, both fixed here once so
+ * no adapter has to restate the wording (AGENTS.md rule 4):
+ *
+ * 1. `decision_record` (Pi) wrote the same decision onto both a feature and
+ *    a phase. It no longer writes anything; see
+ *    buildDecisionRecordRedirectReply.
+ * 2. The legacy free-form `decisions: string[]` field on project, phase,
+ *    and task let an agent keep "recording" decisions in a place nothing
+ *    treats as authoritative (buildBoundedAcceptedDecisionContext only ever
+ *    reads acceptedDecisions). Every update tool that exposes this field
+ *    now rejects new writes to it with LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE,
+ *    the same way raw acceptedDecisions replacement was already rejected.
+ *    Existing legacy content is left exactly as persisted — read-only, not
+ *    deleted or migrated; only project-level legacy decisions get folded
+ *    into acceptedDecisions, and only through the existing explicit
+ *    project-context migration, never automatically here.
+ */
+import { type PlanStore } from "./plan-store.js";
+import type { MutationReply } from "./mutation-reply.js";
+export declare const ACCEPTED_DECISION_OWNERSHIP_RULE = "A decision has exactly one owner: the project when it is project-wide, a feature when it is feature-wide, a phase when it is phase-specific, or a task when the decision is genuinely local to that task's work and will not outlive it. Never record the same decision on more than one owner.";
+export declare const ACCEPTED_DECISION_RAW_REPLACEMENT_DISABLED_MESSAGE = "Raw acceptedDecisions replacement is disabled. Use the accepted-decision create, update, or delete operations (accepted_decision_create/update/delete, planner-accepted-decision-create/update/delete, or the /accepted-decisions HTTP endpoints) so IDs and acceptedAt are preserved.";
+export declare const LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE = "The legacy free-form decisions list is retained read-only for history; it is not decision authority. A decision has exactly one owner: the project when it is project-wide, a feature when it is feature-wide, a phase when it is phase-specific, or a task when the decision is genuinely local to that task's work and will not outlive it. Never record the same decision on more than one owner. Record new durable decisions with the accepted-decision create operation on the owner that actually holds this one.";
+export declare const ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED_ERROR_CODE = "ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED";
+export declare const LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE = "LEGACY_DECISIONS_ARRAY_READ_ONLY";
+/**
+ * decision_record's compatibility reply: a typed redirect, never a write.
+ * It cannot dual-write because it performs no write at all — the caller
+ * must pick exactly one owner and call the semantic create operation
+ * itself. Kept here so every current or future surface offering a
+ * decision_record-shaped compatibility tool renders identical guidance
+ * instead of drifting.
+ */
+export interface DecisionRecordRedirectInput {
+    /** Resolved, human-readable feature ref (e.g. "F005"), for the feature suggestion. */
+    featureRef: string;
+    /** Resolved, human-readable phase ref (e.g. "P102(F005)"), for the phase suggestion. */
+    phaseRef: string;
+}
+export interface DecisionRecordRedirectReply {
+    text: string;
+    structured: Record<string, unknown>;
+}
+export declare function buildDecisionRecordRedirectReply(input: DecisionRecordRedirectInput): DecisionRecordRedirectReply;
+/**
+ * Resolve an Accepted Decision target (project/feature/phase/task) to its
+ * owning entity id and a display ref. Both adapters carried an identical
+ * copy for accepted_decision_create/update/delete; kept here so target
+ * resolution can never drift from `resolveFeatureRefStrict`/
+ * `findPhaseByRef`/`findTaskByRef` — the same ref grammar this project uses
+ * everywhere else.
+ */
+export type AcceptedDecisionTargetType = "project" | "feature" | "phase" | "task";
+export type AcceptedDecisionTargetResolution = {
+    ok: true;
+    owner: {
+        kind: "project";
+    } | {
+        kind: "feature";
+        featureId: string;
+    } | {
+        kind: "phase";
+        phaseId: string;
+    } | {
+        kind: "task";
+        phaseId: string;
+        taskId: string;
+    };
+    ref: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveAcceptedDecisionTarget(st: PlanStore, targetType: AcceptedDecisionTargetType, targetRef: string | undefined): Promise<AcceptedDecisionTargetResolution>;
+/**
+ * Render a PlanStoreError raised by an Accepted Decision create/update/delete
+ * as a text/structured pair, or rethrow when it isn't one of those (a
+ * different failure is the caller's to handle). Both adapters carried an
+ * identical copy of this decision; kept here so the type check and the
+ * message can never drift. Each adapter still wraps its own envelope.
+ */
+export declare function acceptedDecisionMutationFailureReply(error: unknown, outcome: "created" | "updated" | "deleted"): MutationReply;
+//# sourceMappingURL=accepted-decision-guard.d.ts.map

package/dist/accepted-decision-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accepted-decision-guard.d.ts","sourceRoot":"","sources":["../src/accepted-decision-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,eAAO,MAAM,gCAAgC,oSACsP,CAAC;AAEpS,eAAO,MAAM,kDAAkD,2RAC2N,CAAC;AAE3R,eAAO,MAAM,wCAAwC,6fAC2M,CAAC;AAEjQ,eAAO,MAAM,uDAAuD,iDAAiD,CAAC;AACtH,eAAO,MAAM,2CAA2C,qCAAqC,CAAC;AAE9F;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,2BAA2B,GAAG,2BAA2B,CA0BhH;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAClF,MAAM,MAAM,gCAAgC,GACxC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACvL;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,wBAAsB,6BAA6B,CACjD,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,0BAA0B,EACtC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,gCAAgC,CAAC,CA0B3C;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAM9H"}

package/dist/accepted-decision-guard.js

@@ -0,0 +1,110 @@
+/**
+ * Accepted Decision ownership rule and the compatibility guards that enforce
+ * it, shared by every adapter (MCP, Pi, HTTP, and any future harness).
+ *
+ * The rule: a decision has exactly one owner. Project-wide decisions belong
+ * only to project.acceptedDecisions; feature-wide decisions only to that
+ * feature; phase-specific decisions only to that phase; genuinely
+ * task-local decisions only to that task. Nothing duplicates a decision
+ * across two owners by default — see the semantic createAcceptedDecision /
+ * updateAcceptedDecision / deleteAcceptedDecision operations in
+ * plan-store.ts, which already write to exactly one target.
+ *
+ * Two things previously worked against that rule, both fixed here once so
+ * no adapter has to restate the wording (AGENTS.md rule 4):
+ *
+ * 1. `decision_record` (Pi) wrote the same decision onto both a feature and
+ *    a phase. It no longer writes anything; see
+ *    buildDecisionRecordRedirectReply.
+ * 2. The legacy free-form `decisions: string[]` field on project, phase,
+ *    and task let an agent keep "recording" decisions in a place nothing
+ *    treats as authoritative (buildBoundedAcceptedDecisionContext only ever
+ *    reads acceptedDecisions). Every update tool that exposes this field
+ *    now rejects new writes to it with LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE,
+ *    the same way raw acceptedDecisions replacement was already rejected.
+ *    Existing legacy content is left exactly as persisted — read-only, not
+ *    deleted or migrated; only project-level legacy decisions get folded
+ *    into acceptedDecisions, and only through the existing explicit
+ *    project-context migration, never automatically here.
+ */
+import { PlanStoreError } from "./plan-store.js";
+import { formatFeatureRef, formatPhaseRef, featureNumberOfPhase } from "./naming.js";
+import { findPhaseByRef, findTaskByRef, resolveFeatureRefStrict } from "./refs.js";
+export const ACCEPTED_DECISION_OWNERSHIP_RULE = "A decision has exactly one owner: the project when it is project-wide, a feature when it is feature-wide, a phase when it is phase-specific, or a task when the decision is genuinely local to that task's work and will not outlive it. Never record the same decision on more than one owner.";
+export const ACCEPTED_DECISION_RAW_REPLACEMENT_DISABLED_MESSAGE = "Raw acceptedDecisions replacement is disabled. Use the accepted-decision create, update, or delete operations (accepted_decision_create/update/delete, planner-accepted-decision-create/update/delete, or the /accepted-decisions HTTP endpoints) so IDs and acceptedAt are preserved.";
+export const LEGACY_DECISIONS_ARRAY_READ_ONLY_MESSAGE = `The legacy free-form decisions list is retained read-only for history; it is not decision authority. ${ACCEPTED_DECISION_OWNERSHIP_RULE} Record new durable decisions with the accepted-decision create operation on the owner that actually holds this one.`;
+export const ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED_ERROR_CODE = "ACCEPTED_DECISION_SEMANTIC_MUTATION_REQUIRED";
+export const LEGACY_DECISIONS_ARRAY_READ_ONLY_ERROR_CODE = "LEGACY_DECISIONS_ARRAY_READ_ONLY";
+export function buildDecisionRecordRedirectReply(input) {
+    const { featureRef, phaseRef } = input;
+    return {
+        text: [
+            `decision_record no longer writes a decision on both ${featureRef} and ${phaseRef}.`,
+            ACCEPTED_DECISION_OWNERSHIP_RULE,
+            "Call accepted_decision_create with the single owner this decision actually belongs to:",
+            `- Project-wide: targetType "project" (omit targetRef).`,
+            `- Feature-wide: targetType "feature", targetRef "${featureRef}".`,
+            `- Phase-specific: targetType "phase", targetRef "${phaseRef}".`,
+            `- Task-local: targetType "task", targetRef the exact task composite ref.`,
+        ].join("\n"),
+        structured: {
+            recorded: false,
+            written: false,
+            redirected: true,
+            redirectTool: "accepted_decision_create",
+            ownershipRule: ACCEPTED_DECISION_OWNERSHIP_RULE,
+            suggestions: {
+                project: { targetType: "project" },
+                feature: { targetType: "feature", targetRef: featureRef },
+                phase: { targetType: "phase", targetRef: phaseRef },
+                task: { targetType: "task", targetRef: null },
+            },
+        },
+    };
+}
+export async function resolveAcceptedDecisionTarget(st, targetType, targetRef) {
+    if (targetType === "project") {
+        const project = await st.loadProject();
+        return { ok: true, owner: { kind: "project" }, ref: project.name };
+    }
+    const ref = targetRef?.trim();
+    if (!ref)
+        return { ok: false, error: `targetRef is required for ${targetType} accepted decisions.` };
+    const [featuresDoc, phases] = await Promise.all([st.loadFeatures(), st.loadAllPhases()]);
+    const features = featuresDoc.features;
+    if (targetType === "feature") {
+        const resolved = resolveFeatureRefStrict(features, ref);
+        if (!resolved.ok)
+            return { ok: false, error: resolved.error };
+        return { ok: true, owner: { kind: "feature", featureId: resolved.feature.id }, ref: formatFeatureRef(resolved.feature.number) };
+    }
+    if (targetType === "phase") {
+        const phase = findPhaseByRef(phases, features, ref);
+        if (!phase)
+            return { ok: false, error: `Phase not found: ${ref}` };
+        return { ok: true, owner: { kind: "phase", phaseId: phase.id }, ref: formatPhaseRef(phase.number, featureNumberOfPhase(phase, features)) };
+    }
+    const found = findTaskByRef(phases, features, ref);
+    if (!found)
+        return { ok: false, error: `Task not found: ${ref}` };
+    return {
+        ok: true,
+        owner: { kind: "task", phaseId: found.phase.id, taskId: found.task.id },
+        ref: `${formatPhaseRef(found.phase.number, featureNumberOfPhase(found.phase, features))}/T${String(found.task.number).padStart(3, "0")}`,
+    };
+}
+/**
+ * Render a PlanStoreError raised by an Accepted Decision create/update/delete
+ * as a text/structured pair, or rethrow when it isn't one of those (a
+ * different failure is the caller's to handle). Both adapters carried an
+ * identical copy of this decision; kept here so the type check and the
+ * message can never drift. Each adapter still wraps its own envelope.
+ */
+export function acceptedDecisionMutationFailureReply(error, outcome) {
+    if (!(error instanceof PlanStoreError) || !String(error.details?.errorCode ?? "").startsWith("ACCEPTED_DECISION_"))
+        throw error;
+    return {
+        text: `❌ Accepted Decision mutation failed [${error.details?.errorCode}]: ${error.message}`,
+        structured: { [outcome]: false, ...error.details },
+    };
+}

package/dist/checklist.d.ts

@@ -13,4 +13,32 @@ export declare function addChecklistItem(items: ChecklistItem[], taskId: string,
 export declare function removeChecklistItem(items: ChecklistItem[], selector: string): ChecklistItem | undefined;
 /** Tick/untick the matched item in place. checked omitted → toggle. Returns the item, or undefined. */
 export declare function toggleChecklistItem(items: ChecklistItem[], selector: string, checked?: boolean): ChecklistItem | undefined;
+export interface ChecklistReplacement {
+    items: ChecklistItem[];
+    /** Titles of previously-ticked items whose tick could not be carried over.
+     *  Empty on the common paths. Callers MUST surface a non-empty list: a
+     *  success result that drops ticks without saying so is the defect this
+     *  function exists to prevent. */
+    lostTicks: string[];
+}
+/**
+ * Build the replacement list for a whole-checklist update, carrying tick state
+ * across from the items being replaced.
+ *
+ * The input is plain titles, so item identity has to be reconstructed. Two
+ * passes, in this order:
+ *
+ *  1. Exact trimmed title. Order-independent, so reordering a list keeps every
+ *     tick. Each surviving item is consumed at most once, so duplicate titles
+ *     carry over one tick each rather than multiplying.
+ *  2. Position, but ONLY when the list length is unchanged. This is what makes
+ *     renaming an item keep its tick — the reported failure case. Restricting
+ *     it to equal-length lists means an insertion or deletion never shifts a
+ *     tick onto a neighbour.
+ *
+ * Anything still unmatched is a new item and starts unchecked; if it displaced
+ * a ticked item, that title is reported in `lostTicks` rather than dropped in
+ * silence.
+ */
+export declare function replaceChecklist(existing: ChecklistItem[], titles: string[], taskId: string): ChecklistReplacement;
 //# sourceMappingURL=checklist.d.ts.map

package/dist/checklist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checklist.d.ts","sourceRoot":"","sources":["../src/checklist.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AAEH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAerG;AAED,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAKrG;AAED,oHAAoH;AACpH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CASvG;AAED,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAK1H"}
+{"version":3,"file":"checklist.d.ts","sourceRoot":"","sources":["../src/checklist.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AAEH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAerG;AAED,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAKrG;AAED,oHAAoH;AACpH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CASvG;AAED,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAK1H;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB;;;sCAGkC;IAClC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,oBAAoB,CA0ClH"}

package/dist/checklist.js

@@ -50,3 +50,62 @@ export function toggleChecklistItem(items, selector, checked) {
     found.checked = checked ?? !found.checked;
     return found;
 }
+/**
+ * Build the replacement list for a whole-checklist update, carrying tick state
+ * across from the items being replaced.
+ *
+ * The input is plain titles, so item identity has to be reconstructed. Two
+ * passes, in this order:
+ *
+ *  1. Exact trimmed title. Order-independent, so reordering a list keeps every
+ *     tick. Each surviving item is consumed at most once, so duplicate titles
+ *     carry over one tick each rather than multiplying.
+ *  2. Position, but ONLY when the list length is unchanged. This is what makes
+ *     renaming an item keep its tick — the reported failure case. Restricting
+ *     it to equal-length lists means an insertion or deletion never shifts a
+ *     tick onto a neighbour.
+ *
+ * Anything still unmatched is a new item and starts unchecked; if it displaced
+ * a ticked item, that title is reported in `lostTicks` rather than dropped in
+ * silence.
+ */
+export function replaceChecklist(existing, titles, taskId) {
+    const cleanTitles = titles.map((title) => title.trim()).filter((title) => title.length > 0);
+    const consumed = new Set();
+    const carried = new Array(cleanTitles.length).fill(false);
+    // Tracks whether pass 1 found an exact-title match, independent of that
+    // match's checked value. `carried[index]` alone cannot stand in for this:
+    // an exact match to an unticked item legitimately produces carried=false,
+    // and pass 2 must not treat that as "unmatched" and overwrite it with a
+    // stray tick from whatever unrelated item previously sat at this position.
+    const matchedByTitle = new Array(cleanTitles.length).fill(false);
+    cleanTitles.forEach((title, index) => {
+        const match = existing.findIndex((item, i) => !consumed.has(i) && item.title.trim() === title);
+        if (match >= 0) {
+            consumed.add(match);
+            matchedByTitle[index] = true;
+            carried[index] = existing[match].checked;
+        }
+    });
+    if (cleanTitles.length === existing.length) {
+        cleanTitles.forEach((_title, index) => {
+            if (matchedByTitle[index])
+                return;
+            const candidate = existing[index];
+            if (!candidate || consumed.has(index))
+                return;
+            consumed.add(index);
+            carried[index] = candidate.checked;
+        });
+    }
+    const items = cleanTitles.map((title, index) => ({
+        id: createChecklistItemId(taskId, index + 1, title),
+        number: index + 1,
+        title,
+        checked: carried[index] ?? false,
+    }));
+    const lostTicks = existing
+        .filter((item, i) => item.checked && !consumed.has(i))
+        .map((item) => item.title);
+    return { items, lostTicks };
+}

package/dist/feature-delete.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Delete a feature the same way from every surface — MCP, the pi adapter's
+ * tool and interactive paths, and the REST server. Before this task each of
+ * those four wrote its own delete, and two of them cleared the feature
+ * record and never touched its phases: the phases were left pointing at a
+ * featureId that no longer existed anywhere — an orphan, not a link. Per
+ * AGENTS.md rule 4, "also unlink the phases" is not a rule a caller should
+ * have to remember; it lives here once and every caller gets it whether it
+ * asked for it or not.
+ *
+ * Cascade semantics (must match exactly — do not "simplify" to one
+ * behaviour): `cascade: true` deletes the feature's phases outright (phase
+ * deletion already archives their handoffs; this does not reimplement
+ * that). `cascade: false` unlinks each phase (clears `featureId`) and
+ * leaves it alive — the phase still exists with its tasks, it just no
+ * longer belongs to a feature.
+ *
+ * The delete is verified, not assumed: after writing, the feature list is
+ * read back from disk and the id must actually be gone. Reporting success
+ * without checking is the same defect class as T413.
+ */
+import type { PlanStore } from "./plan-store.js";
+export interface DeleteFeatureCascadeOptions {
+    /** true deletes the feature's phases; false unlinks them and leaves them alive. */
+    cascade: boolean;
+}
+/** One phase's fate, for callers (the REST server's WS broadcast, in
+ * particular) that need to say what happened to each affected phase. */
+export interface DeleteFeatureCascadePhase {
+    id: string;
+    action: "deleted" | "unlinked";
+}
+export interface DeleteFeatureCascadeResult {
+    /** Canonical F00x ref — never the caller's raw input. */
+    ref: string;
+    id: string;
+    name: string;
+    cascade: boolean;
+    phaseCount: number;
+    phases: DeleteFeatureCascadePhase[];
+}
+export type DeleteFeatureCascadeErrorCode = "FEATURE_NOT_FOUND" | "FEATURE_DELETE_NOT_PERSISTED";
+export type DeleteFeatureCascadeOutcome = {
+    ok: true;
+    result: DeleteFeatureCascadeResult;
+} | {
+    ok: false;
+    errorCode: DeleteFeatureCascadeErrorCode;
+    error: string;
+};
+/**
+ * Delete the feature identified by the already-resolved `featureId` (a
+ * canonical UUID — turning a caller's fuzzy ref like "checkout" or "F5"
+ * into that id is the caller's job, same as every other mutation in this
+ * codebase; resolveFeatureRefStrict does that today). The feature is
+ * re-read fresh, inside the write lock, immediately before the mutation —
+ * not trusted from whatever the caller resolved earlier — so a feature
+ * that another process deleted between the caller's resolve and this call
+ * fails loudly (FEATURE_NOT_FOUND) instead of reporting a phantom success.
+ */
+export declare function deleteFeatureCascade(store: PlanStore, featureId: string, options: DeleteFeatureCascadeOptions): Promise<DeleteFeatureCascadeOutcome>;
+//# sourceMappingURL=feature-delete.d.ts.map

package/dist/feature-delete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-delete.d.ts","sourceRoot":"","sources":["../src/feature-delete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,MAAM,WAAW,2BAA2B;IAC1C,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;wEACwE;AACxE,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC;CAChC;AAED,MAAM,WAAW,0BAA0B;IACzC,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,yBAAyB,EAAE,CAAC;CACrC;AAED,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,GAAG,8BAA8B,CAAC;AAEjG,MAAM,MAAM,2BAA2B,GACnC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,6BAA6B,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,2BAA2B,CAAC,CAyCtC"}

package/dist/feature-delete.js

@@ -0,0 +1,49 @@
+import { formatFeatureRef } from "./naming.js";
+/**
+ * Delete the feature identified by the already-resolved `featureId` (a
+ * canonical UUID — turning a caller's fuzzy ref like "checkout" or "F5"
+ * into that id is the caller's job, same as every other mutation in this
+ * codebase; resolveFeatureRefStrict does that today). The feature is
+ * re-read fresh, inside the write lock, immediately before the mutation —
+ * not trusted from whatever the caller resolved earlier — so a feature
+ * that another process deleted between the caller's resolve and this call
+ * fails loudly (FEATURE_NOT_FOUND) instead of reporting a phantom success.
+ */
+export async function deleteFeatureCascade(store, featureId, options) {
+    return store.runBatch(async () => {
+        const features = (await store.loadFeatures()).features;
+        const feature = features.find((entry) => entry.id === featureId);
+        if (!feature) {
+            return { ok: false, errorCode: "FEATURE_NOT_FOUND", error: `Feature not found: ${featureId}` };
+        }
+        const ref = formatFeatureRef(feature.number);
+        const phases = (await store.loadAllPhases()).filter((phase) => phase.featureId === feature.id);
+        await store.updateFeatures((doc) => {
+            doc.features = doc.features.filter((entry) => entry.id !== feature.id);
+            return doc;
+        });
+        const phaseResults = [];
+        for (const phase of phases) {
+            if (options.cascade) {
+                await store.deletePhase(phase.id);
+                phaseResults.push({ id: phase.id, action: "deleted" });
+            }
+            else {
+                await store.updatePhase(phase.id, (current) => ({ ...current, featureId: undefined, updatedAt: new Date().toISOString() }));
+                phaseResults.push({ id: phase.id, action: "unlinked" });
+            }
+        }
+        await store.writeGenerated();
+        // Prove it happened: the feature must actually be gone from a fresh
+        // disk read, not merely filtered out of an in-memory copy that a
+        // subsequent write silently dropped.
+        const stillPresent = (await store.loadFeatures()).features.some((entry) => entry.id === feature.id);
+        if (stillPresent) {
+            return { ok: false, errorCode: "FEATURE_DELETE_NOT_PERSISTED", error: `Feature delete did not persist: ${ref}` };
+        }
+        return {
+            ok: true,
+            result: { ref, id: feature.id, name: feature.name, cascade: options.cascade, phaseCount: phaseResults.length, phases: phaseResults },
+        };
+    });
+}

package/dist/guard-decision.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Harness-agnostic logic for the "no task in progress" warning. The guard
+ * never blocks and never asks: every tool call proceeds, and a call that
+ * changes project code while no task is in progress only earns the agent a
+ * warning. Planner operations never need a task. Any adapter (Claude Code
+ * PreToolUse hook, Pi's tool_call handler, a future harness) feeds it a
+ * parsed tool-use event plus already-fetched planner state and gets back the
+ * same warning, or none. This never talks to the plan store
+ * or stdin/stdout — callers own that I/O. It does read the filesystem in one
+ * narrow way (see {@link canonicalize}): resolving symlinks so a path
+ * comparison isn't fooled by one, which is cheap (a handful of stat calls,
+ * not a plan load) and safe to call on paths that don't exist yet.
+ */
+/** The tool-use fields the decision needs, already pulled out of whatever
+ * shape the harness's raw event uses (Claude Code's `tool_input.file_path`,
+ * Pi's `event.input.path`, etc.). */
+export interface GuardEventInput {
+    /** Tool name in any case: Claude Code's `Edit`/`Bash` and Pi's `edit`/`bash` are the same tool. */
+    toolName: string;
+    /** Absolute (or resolvable) working directory used to resolve relative paths. */
+    cwd: string;
+    /** Absolute planner root, e.g. `join(cwd, ".planner")`. */
+    plannerRoot: string;
+    /** Edit / Write target path (Pi: `path`). */
+    filePath?: string;
+    /** NotebookEdit target path. */
+    notebookPath?: string;
+    /** Bash command line, when toolName is "Bash". */
+    command?: string;
+}
+/** Planner state the caller already fetched (I/O happens once, upstream). */
+export interface GuardStateInput {
+    hasPlannerDir: boolean;
+    totalTasks: number;
+    hasInProgressTask: boolean;
+    guardBypassed: boolean;
+    /** The task the warning suggests starting, when there is an obvious one. */
+    focusTask?: {
+        id: string;
+        title: string;
+    };
+}
+export interface GuardClassification {
+    /** Whether this tool call may write project code, so the guard must look at task state. */
+    guarded: boolean;
+    /** The project paths outside `.planner/` the call would write to; empty when the target is unknown. */
+    paths: string[];
+}
+export interface NoTaskWarning {
+    /** Text for the agent, present only when it should be warned. */
+    warning?: string;
+}
+/**
+ * Whether a Bash command line contains a write-shaped operation: output
+ * redirection, `tee`, in-place `sed`/`perl`, a file-creating `cp`/`mv`,
+ * `rm`, or a `git` operation that rewrites tracked files. Deliberately
+ * over-inclusive: `git`, build/test runners, `ls`, `cat`, `grep`, `find`
+ * and friends must stay unmatched, but when in doubt this returns true — a
+ * false positive costs one warning to the agent, never a blocked call or a
+ * prompt, so under-matching (missing a real edit) is the worse failure.
+ */
+export declare function isWriteShapedBashCommand(command: string): boolean;
+/**
+ * Best-effort extraction of the file path(s) a write-shaped Bash segment
+ * targets, so a command that only touches `.planner/` or files outside the
+ * project earns no warning. This cannot see through a heredoc whose target
+ * is computed (a variable, command substitution, etc.) rather than written
+ * literally in the command line — that case still reaches the in-progress /
+ * bypass checks and can warn, rather than being silently treated as safe.
+ *
+ * A wider gap of the same kind: a command that writes through an
+ * interpreter (`python3 - <<PY` then `open(path, "w")`, `node -e`, a script
+ * invoked by name) is opaque here — nothing in the command line looks
+ * write-shaped. P105(F005)/T431 evaluated closing this and chose not to,
+ * for reasons that also rule out revisiting it the same way later:
+ *   - Parsing the script body is unbounded (a path can be computed, read
+ *     from argv, or built at runtime) and would trade an honest documented
+ *     limit for false confidence.
+ *   - A PostToolUse hook that notices tracked files changed while no task
+ *     was in progress sounds like a fit (the guard's job is visibility, not
+ *     prevention), but it collides with this project's own workflow: a
+ *     task is left with its changes uncommitted for the orchestrator to
+ *     review, so "no task in-progress, tracked files changed outside
+ *     .planner/" is the routine state right after every task completes,
+ *     not a signal of anything wrong. Telling that apart from a real
+ *     interpreter write means diffing only the delta from one specific
+ *     Bash call, which needs a session-scoped git-status baseline checked
+ *     on every Bash invocation — read-only ones included, since which
+ *     commands wrote can't be known in advance. That statefulness and
+ *     per-call cost is worse than the gap it would close.
+ * The limit stands, documented rather than silently assumed away.
+ */
+export declare function extractBashWriteTargets(command: string): string[];
+/** Whether `candidate` resolves to a path inside `plannerRoot` (or is it exactly). */
+export declare function isPathInsidePlannerRoot(candidate: string, plannerRoot: string, cwd: string): boolean;
+/** Whether writing `candidate` changes the project's code: it is inside the
+ * project (the directory that owns `.planner/`) and not inside `.planner/`.
+ * `/dev/null`, `~/.claude/...`, temp dirs and other repositories are not. */
+export declare function isProjectCodePath(candidate: string, plannerRoot: string, cwd: string): boolean;
+/**
+ * Whether a tool call may change the project's code, and so needs the guard
+ * to look at task state. This is the one place that rule lives; the hook's
+ * cheap early exit and {@link noTaskWarning} both read `guarded`.
+ *
+ * - Tools that never write (Read, Grep, MCP tools, read-only Bash, ...) are
+ *   not guarded.
+ * - A write whose targets are all known and none is project code (inside
+ *   `.planner/`, `/dev/null`, `~/.claude/...`, a temp dir, another repo) is
+ *   not guarded: updating the planner or the user's own config never needs a
+ *   task.
+ * - A write with at least one project-code target is guarded, with `paths`
+ *   narrowed to those targets.
+ * - A write whose target is unknown (a computed heredoc, an Edit with no
+ *   path) is guarded with empty `paths` — never silently allowed.
+ */
+export declare function classifyGuardedTool(event: GuardEventInput): GuardClassification;
+/**
+ * The warning for a tool call that changes project code while no task is in
+ * progress, or none. Never a block or a prompt: the adapter lets the call
+ * proceed either way and only passes the text to the agent. Pure apart from
+ * the cheap symlink canonicalization in {@link isPathInsidePlannerRoot}.
+ *
+ * Order mirrors the cost of finding out: anything that cannot change project
+ * code (see {@link classifyGuardedTool}) is settled from the event alone, so
+ * adapters can skip loading the plan for it.
+ */
+export declare function noTaskWarning(event: GuardEventInput, state: GuardStateInput): NoTaskWarning;
+//# sourceMappingURL=guard-decision.d.ts.map

package/dist/guard-decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-decision.d.ts","sourceRoot":"","sources":["../src/guard-decision.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH;;qCAEqC;AACrC,MAAM,WAAW,eAAe;IAC9B,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,SAAS,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,uGAAuG;IACvG,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiFD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BjE;AAuCD,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpG;AAED;;6EAE6E;AAC7E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9F;AAoBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAM/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,aAAa,CAa3F"}