@agent-plan/core 0.2.29 → 0.3.0

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,118 @@
+/**
+ * Harness-agnostic decision logic for the "no task in progress" edit guard.
+ * Any adapter (Claude Code PreToolUse hook, Pi's advisory guard, a future
+ * harness) can feed it a parsed tool-use event plus already-fetched planner
+ * state and get back the same decision. 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.
+ */
+export type GuardPermissionDecision = "allow" | "ask" | "deny";
+/** 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 {
+    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. */
+    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;
+    /** Human-readable "start this task" hint, or the generic fallback; empty allowed. */
+    startHint: string;
+}
+export interface GuardClassification {
+    /** Whether this tool call is one the guard evaluates at all. */
+    guarded: boolean;
+    /** Best-effort candidate paths the call would write to (may be empty when unknown). */
+    paths: string[];
+}
+export interface GuardDecision {
+    decision: GuardPermissionDecision;
+    reason?: 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 — the
+ * cost of a false positive here is one extra prompt, not a blocked
+ * operation, 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/` can still be
+ * recognized and allowed. 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 is expected to fall through to
+ * the normal in-progress/bypass checks below, not to be silently allowed.
+ *
+ * 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;
+/** True only when every candidate path is inside the planner root, and there
+ * is at least one candidate — an empty/unknown path list must never count as
+ * "inside", or an unresolvable target would be silently allowed. Exported so
+ * a hook harness can use the exact same check for its cheap early-allow path
+ * without duplicating the rule. */
+export declare function isEntirelyInsidePlannerRoot(paths: string[], plannerRoot: string, cwd: string): boolean;
+/**
+ * Which tool calls the guard covers, and what path(s) they would write to.
+ * Everything else (Read, Grep, WebFetch, MCP tools, read-only Bash, ...) is
+ * unguarded and returns `{ guarded: false }` without touching the planner
+ * store.
+ */
+export declare function classifyGuardedTool(event: GuardEventInput): GuardClassification;
+/**
+ * The full "no task in progress" guard decision, as a pure function: given a
+ * parsed tool-use event and planner state the caller already fetched, decide
+ * allow or ask (deny is part of the type for a future genuinely-deny case,
+ * but nothing here returns it today). No stdin/stdout and no plan-store
+ * calls — the hook harness (or a Pi equivalent) does the reading and
+ * printing around this; the only filesystem access is the cheap symlink
+ * canonicalization in {@link isPathInsidePlannerRoot}.
+ *
+ * Order matters and mirrors the cost of finding out: anything the guard
+ * doesn't cover, and anything that resolves entirely inside the planner
+ * root, is decided from the event alone (no planner state needed). Only a
+ * real candidate for blocking reaches the state-based checks.
+ */
+export declare function decideGuardPreToolUse(event: GuardEventInput, state: GuardStateInput): GuardDecision;
+//# 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":"AAGA;;;;;;;;;GASG;AAEH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/D;;qCAEqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,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,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BjE;AAsBD,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAKpG;AAED;;;;mCAImC;AACnC,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAa/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,aAAa,CAkBnG"}