@n-dx/core 0.1.0

package/packages/rex/dist/core/parent-completion.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Automatic parent completion for PRD items.
+ *
+ * When all children of a parent item are completed (or deferred), the parent
+ * can be automatically marked as completed. This walks up the tree from a
+ * given item, propagating completion as far as it goes.
+ *
+ * Rules:
+ * - A parent is auto-completable when *every* child is `completed` or `deferred`.
+ * - Propagation walks up the ancestor chain: if completing a parent makes its
+ *   own parent fully done, that grandparent is completed too.
+ * - Only items with `pending` or `in_progress` status are auto-completed
+ *   (already-completed, deferred, and blocked parents are left alone).
+ * - Returns the list of item IDs that were auto-completed, bottom-up.
+ *
+ * @module core/parent-completion
+ */
+import type { PRDItem } from "../schema/index.js";
+export interface AutoCompletionResult {
+    /** IDs of items that should be auto-completed, ordered bottom-up (child → ancestor). */
+    completedIds: string[];
+    /** Human-readable descriptions of what was auto-completed. */
+    completedItems: Array<{
+        id: string;
+        title: string;
+        level: string;
+    }>;
+}
+/**
+ * Given a recently-completed item, find all ancestors that should be
+ * auto-completed because all their children are now done.
+ *
+ * Walks up the parent chain, simulating each completion so that
+ * grandparents can see their child (which we just decided to complete)
+ * as terminal.
+ *
+ * @param items     - The full PRD item tree.
+ * @param itemId    - The ID of the item that just completed.
+ * @returns Items to auto-complete, ordered bottom-up. Empty if no propagation needed.
+ */
+export declare function findAutoCompletions(items: PRDItem[], itemId: string): AutoCompletionResult;

package/packages/rex/dist/core/parent-completion.js

@@ -0,0 +1,75 @@
+/**
+ * Automatic parent completion for PRD items.
+ *
+ * When all children of a parent item are completed (or deferred), the parent
+ * can be automatically marked as completed. This walks up the tree from a
+ * given item, propagating completion as far as it goes.
+ *
+ * Rules:
+ * - A parent is auto-completable when *every* child is `completed` or `deferred`.
+ * - Propagation walks up the ancestor chain: if completing a parent makes its
+ *   own parent fully done, that grandparent is completed too.
+ * - Only items with `pending` or `in_progress` status are auto-completed
+ *   (already-completed, deferred, and blocked parents are left alone).
+ * - Returns the list of item IDs that were auto-completed, bottom-up.
+ *
+ * @module core/parent-completion
+ */
+import { findItem } from "./tree.js";
+const AUTO_COMPLETABLE_STATUSES = new Set(["pending", "in_progress"]);
+const TERMINAL_CHILD_STATUSES = new Set(["completed", "deferred"]);
+/**
+ * Check whether all children of an item are in a terminal state
+ * (completed or deferred), treating any IDs in `virtuallyCompleted`
+ * as if they were already completed.
+ */
+function allChildrenTerminal(item, virtuallyCompleted) {
+    if (!item.children || item.children.length === 0)
+        return false;
+    return item.children.every((c) => TERMINAL_CHILD_STATUSES.has(c.status) || virtuallyCompleted.has(c.id));
+}
+/**
+ * Given a recently-completed item, find all ancestors that should be
+ * auto-completed because all their children are now done.
+ *
+ * Walks up the parent chain, simulating each completion so that
+ * grandparents can see their child (which we just decided to complete)
+ * as terminal.
+ *
+ * @param items     - The full PRD item tree.
+ * @param itemId    - The ID of the item that just completed.
+ * @returns Items to auto-complete, ordered bottom-up. Empty if no propagation needed.
+ */
+export function findAutoCompletions(items, itemId) {
+    const result = {
+        completedIds: [],
+        completedItems: [],
+    };
+    const entry = findItem(items, itemId);
+    if (!entry)
+        return result;
+    // Track items we've decided to auto-complete so higher ancestors
+    // see them as terminal when checking their own children.
+    const virtuallyCompleted = new Set([itemId]);
+    // Walk up the parent chain from immediate parent to root
+    const parents = entry.parents;
+    for (let i = parents.length - 1; i >= 0; i--) {
+        const parent = parents[i];
+        // Only auto-complete parents that are pending or in_progress
+        if (!AUTO_COMPLETABLE_STATUSES.has(parent.status))
+            break;
+        // Check if all children are terminal (including virtually completed ones)
+        if (!allChildrenTerminal(parent, virtuallyCompleted))
+            break;
+        result.completedIds.push(parent.id);
+        result.completedItems.push({
+            id: parent.id,
+            title: parent.title,
+            level: parent.level,
+        });
+        // This parent is now virtually completed for the next ancestor check
+        virtuallyCompleted.add(parent.id);
+    }
+    return result;
+}
+//# sourceMappingURL=parent-completion.js.map

package/packages/rex/dist/core/parent-completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent-completion.js","sourceRoot":"","sources":["../../src/core/parent-completion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC,MAAM,yBAAyB,GAAoB,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;AACvF,MAAM,uBAAuB,GAAoB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AAEpF;;;;GAIG;AACH,SAAS,mBAAmB,CAC1B,IAAa,EACb,kBAA+B;IAE/B,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/D,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAC7E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAgB,EAChB,MAAc;IAEd,MAAM,MAAM,GAAyB;QACnC,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,EAAE;KACnB,CAAC;IAEF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAE1B,iEAAiE;IACjE,yDAAyD;IACzD,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAErD,yDAAyD;IACzD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAE9B,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAE1B,6DAA6D;QAC7D,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;YAAE,MAAM;QAEzD,0EAA0E;QAC1E,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,CAAC;YAAE,MAAM;QAE5D,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC;YACzB,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;QAEH,qEAAqE;QACrE,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/packages/rex/dist/core/parent-reset.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Automatic parent status reset for PRD items.
+ *
+ * When a new child is added under a completed parent, the parent should be
+ * reset to `pending` since it now has outstanding work. This walks up the
+ * tree from the given parent, resetting any completed ancestors.
+ *
+ * Rules:
+ * - Only parents with `completed` status are reset (pending, in_progress,
+ *   deferred, and blocked parents are left alone).
+ * - Reset cascades up the ancestor chain: if a parent is reset, its own
+ *   parent should also be checked.
+ * - Stops cascading when an ancestor is not `completed`.
+ * - Returns the list of item IDs that should be reset, ordered from the
+ *   immediate parent outward (bottom-up).
+ *
+ * This is the inverse complement of {@link findAutoCompletions} in
+ * `parent-completion.ts`.
+ *
+ * @module core/parent-reset
+ */
+import type { PRDItem } from "../schema/index.js";
+export interface ParentResetResult {
+    /** IDs of items that should be reset, ordered bottom-up (child → ancestor). */
+    resetIds: string[];
+    /** Human-readable descriptions of what was reset. */
+    resetItems: Array<{
+        id: string;
+        title: string;
+        level: string;
+    }>;
+}
+/**
+ * Given a parent item that just received a new child, find all ancestors
+ * (including the parent itself) that should be reset from `completed` to
+ * `pending`.
+ *
+ * Call this after `store.addItem(child, parentId)` with the parentId to
+ * determine which completed ancestors need to be reopened.
+ *
+ * @param items     - The full PRD item tree (after the child was added).
+ * @param parentId  - The ID of the parent that received the new child.
+ * @returns Items to reset, ordered bottom-up. Empty if no reset needed.
+ */
+export declare function findParentResets(items: PRDItem[], parentId: string): ParentResetResult;

package/packages/rex/dist/core/parent-reset.js

@@ -0,0 +1,59 @@
+/**
+ * Automatic parent status reset for PRD items.
+ *
+ * When a new child is added under a completed parent, the parent should be
+ * reset to `pending` since it now has outstanding work. This walks up the
+ * tree from the given parent, resetting any completed ancestors.
+ *
+ * Rules:
+ * - Only parents with `completed` status are reset (pending, in_progress,
+ *   deferred, and blocked parents are left alone).
+ * - Reset cascades up the ancestor chain: if a parent is reset, its own
+ *   parent should also be checked.
+ * - Stops cascading when an ancestor is not `completed`.
+ * - Returns the list of item IDs that should be reset, ordered from the
+ *   immediate parent outward (bottom-up).
+ *
+ * This is the inverse complement of {@link findAutoCompletions} in
+ * `parent-completion.ts`.
+ *
+ * @module core/parent-reset
+ */
+import { findItem } from "./tree.js";
+/**
+ * Given a parent item that just received a new child, find all ancestors
+ * (including the parent itself) that should be reset from `completed` to
+ * `pending`.
+ *
+ * Call this after `store.addItem(child, parentId)` with the parentId to
+ * determine which completed ancestors need to be reopened.
+ *
+ * @param items     - The full PRD item tree (after the child was added).
+ * @param parentId  - The ID of the parent that received the new child.
+ * @returns Items to reset, ordered bottom-up. Empty if no reset needed.
+ */
+export function findParentResets(items, parentId) {
+    const result = {
+        resetIds: [],
+        resetItems: [],
+    };
+    const entry = findItem(items, parentId);
+    if (!entry)
+        return result;
+    // Check the parent itself first, then walk up its ancestors
+    const chain = [...entry.parents, entry.item];
+    // Walk from the target item (end of chain) upward
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const item = chain[i];
+        if (item.status !== "completed")
+            break;
+        result.resetIds.push(item.id);
+        result.resetItems.push({
+            id: item.id,
+            title: item.title,
+            level: item.level,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=parent-reset.js.map

package/packages/rex/dist/core/parent-reset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent-reset.js","sourceRoot":"","sources":["../../src/core/parent-reset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AASrC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAgB,EAChB,QAAgB;IAEhB,MAAM,MAAM,GAAsB;QAChC,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,EAAE;KACf,CAAC;IAEF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAE1B,4DAA4D;IAC5D,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAE7C,kDAAkD;IAClD,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAEtB,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW;YAAE,MAAM;QAEvC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;YACrB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/packages/rex/dist/core/pending-cache.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pending proposal cache infrastructure for smart prune operations.
+ *
+ * Provides save/load/clear operations for caching LLM-generated reshape
+ * proposals between dry-run and accept passes, avoiding redundant LLM calls.
+ * Includes PRD hash validation to detect stale caches.
+ *
+ * @module core/pending-cache
+ */
+import type { ReshapeProposal } from "./reshape.js";
+import type { PRDItem } from "../schema/index.js";
+export declare const PENDING_SMART_PRUNE_FILE = "pending-smart-prune.json";
+export interface PendingSmartPruneCache {
+    generatedAt: string;
+    prdHash: string;
+    proposals: ReshapeProposal[];
+}
+/**
+ * Compute a truncated SHA-256 hash of the PRD items array.
+ *
+ * Uses canonical JSON serialization to ensure deterministic output
+ * regardless of object key ordering.
+ */
+export declare function hashPRD(items: PRDItem[]): string;
+export declare function savePendingSmartPrune(rexDir: string, proposals: ReshapeProposal[], prdHash: string): Promise<void>;
+export declare function loadPendingSmartPrune(rexDir: string): Promise<PendingSmartPruneCache | null>;
+export declare function clearPendingSmartPrune(rexDir: string): Promise<void>;

package/packages/rex/dist/core/pending-cache.js

@@ -0,0 +1,55 @@
+/**
+ * Pending proposal cache infrastructure for smart prune operations.
+ *
+ * Provides save/load/clear operations for caching LLM-generated reshape
+ * proposals between dry-run and accept passes, avoiding redundant LLM calls.
+ * Includes PRD hash validation to detect stale caches.
+ *
+ * @module core/pending-cache
+ */
+import { createHash } from "node:crypto";
+import { readFile, writeFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { toCanonicalJSON } from "./canonical.js";
+const REX_DIR = ".rex";
+export const PENDING_SMART_PRUNE_FILE = "pending-smart-prune.json";
+/**
+ * Compute a truncated SHA-256 hash of the PRD items array.
+ *
+ * Uses canonical JSON serialization to ensure deterministic output
+ * regardless of object key ordering.
+ */
+export function hashPRD(items) {
+    return createHash("sha256")
+        .update(toCanonicalJSON(items))
+        .digest("hex")
+        .slice(0, 12);
+}
+export async function savePendingSmartPrune(rexDir, proposals, prdHash) {
+    const cache = {
+        generatedAt: new Date().toISOString(),
+        prdHash,
+        proposals,
+    };
+    const filePath = join(rexDir, PENDING_SMART_PRUNE_FILE);
+    await writeFile(filePath, JSON.stringify(cache, null, 2));
+}
+export async function loadPendingSmartPrune(rexDir) {
+    const filePath = join(rexDir, PENDING_SMART_PRUNE_FILE);
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function clearPendingSmartPrune(rexDir) {
+    try {
+        await unlink(join(rexDir, PENDING_SMART_PRUNE_FILE));
+    }
+    catch {
+        // Already gone
+    }
+}
+//# sourceMappingURL=pending-cache.js.map

package/packages/rex/dist/core/pending-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-cache.js","sourceRoot":"","sources":["../../src/core/pending-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAIjD,MAAM,OAAO,GAAG,MAAM,CAAC;AAEvB,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAA0B,CAAC;AAQnE;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,KAAgB;IACtC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;SAC9B,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,SAA4B,EAC5B,OAAe;IAEf,MAAM,KAAK,GAA2B;QACpC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,OAAO;QACP,SAAS;KACV,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IACxD,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc;IAEd,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAc;IAEd,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;AACH,CAAC"}

package/packages/rex/dist/core/prune.d.ts

@@ -0,0 +1,50 @@
+import type { PRDItem } from "../schema/index.js";
+/**
+ * Result of a prune operation on the PRD tree.
+ *
+ * Contains the pruned items (archived subtrees) and the count of
+ * items removed. The pruned items preserve their full subtree structure
+ * so they can be archived and reviewed later.
+ */
+export interface PruneResult {
+    /** Items removed from the tree (full subtrees, with children intact). */
+    pruned: PRDItem[];
+    /** Total number of individual items removed (including nested children). */
+    prunedCount: number;
+}
+/**
+ * Count the total number of items in a subtree (item + all descendants).
+ */
+export declare function countSubtree(item: PRDItem): number;
+/**
+ * Check whether an item and all its descendants are completed.
+ *
+ * An item is considered "fully completed" when:
+ * - Its own status is "completed"
+ * - All children (recursively) are also "completed"
+ *
+ * Leaf items (no children) only need their own status to be "completed".
+ */
+export declare function isFullyCompleted(item: PRDItem): boolean;
+/**
+ * Identify which root-level subtrees (and nested subtrees) are fully
+ * completed and eligible for pruning.
+ *
+ * This is a read-only preview — it does not mutate the tree.
+ * Use {@link pruneItems} to actually remove items.
+ */
+export declare function findPrunableItems(items: PRDItem[]): PRDItem[];
+/**
+ * Remove all fully-completed subtrees from the item tree.
+ *
+ * Mutates `items` in place — completed subtrees are spliced out
+ * and returned in the result so they can be archived.
+ *
+ * A subtree is pruned when:
+ * 1. The item's status is "completed"
+ * 2. Every descendant is also "completed"
+ *
+ * Items that are completed but have non-completed children are NOT pruned
+ * (to avoid losing in-progress work).
+ */
+export declare function pruneItems(items: PRDItem[]): PruneResult;

package/packages/rex/dist/core/prune.js

@@ -0,0 +1,89 @@
+import { walkTree } from "./tree.js";
+/**
+ * Count the total number of items in a subtree (item + all descendants).
+ */
+export function countSubtree(item) {
+    let count = 1;
+    if (item.children) {
+        for (const child of item.children) {
+            count += countSubtree(child);
+        }
+    }
+    return count;
+}
+/**
+ * Check whether an item and all its descendants are completed.
+ *
+ * An item is considered "fully completed" when:
+ * - Its own status is "completed"
+ * - All children (recursively) are also "completed"
+ *
+ * Leaf items (no children) only need their own status to be "completed".
+ */
+export function isFullyCompleted(item) {
+    if (item.status !== "completed")
+        return false;
+    if (item.children && item.children.length > 0) {
+        return item.children.every(isFullyCompleted);
+    }
+    return true;
+}
+/**
+ * Identify which root-level subtrees (and nested subtrees) are fully
+ * completed and eligible for pruning.
+ *
+ * This is a read-only preview — it does not mutate the tree.
+ * Use {@link pruneItems} to actually remove items.
+ */
+export function findPrunableItems(items) {
+    const prunable = [];
+    for (const { item, parents } of walkTree(items)) {
+        // Only prune top-level completed subtrees — skip items whose parent
+        // is also fully completed (they'll be pruned as part of the parent).
+        if (!isFullyCompleted(item))
+            continue;
+        const parent = parents[parents.length - 1];
+        if (parent && isFullyCompleted(parent))
+            continue;
+        prunable.push(item);
+    }
+    return prunable;
+}
+/**
+ * Remove all fully-completed subtrees from the item tree.
+ *
+ * Mutates `items` in place — completed subtrees are spliced out
+ * and returned in the result so they can be archived.
+ *
+ * A subtree is pruned when:
+ * 1. The item's status is "completed"
+ * 2. Every descendant is also "completed"
+ *
+ * Items that are completed but have non-completed children are NOT pruned
+ * (to avoid losing in-progress work).
+ */
+export function pruneItems(items) {
+    const pruned = [];
+    let prunedCount = 0;
+    // Walk the array in reverse so splicing doesn't shift unvisited indices.
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i];
+        if (isFullyCompleted(item)) {
+            // The entire subtree is completed — remove it.
+            // Use unshift to maintain original order despite reverse iteration.
+            pruned.unshift(item);
+            prunedCount += countSubtree(item);
+            items.splice(i, 1);
+        }
+        else {
+            // The item itself isn't fully done, but some children might be.
+            if (item.children && item.children.length > 0) {
+                const childResult = pruneItems(item.children);
+                pruned.push(...childResult.pruned);
+                prunedCount += childResult.prunedCount;
+            }
+        }
+    }
+    return { pruned, prunedCount };
+}
+//# sourceMappingURL=prune.js.map

package/packages/rex/dist/core/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.js","sourceRoot":"","sources":["../../src/core/prune.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAgBrC;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,KAAK,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAgB;IAChD,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,oEAAoE;QACpE,qEAAqE;QACrE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;YAAE,SAAS;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC3C,IAAI,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC;YAAE,SAAS;QACjD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB;IACzC,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,yEAAyE;IACzE,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,+CAA+C;YAC/C,oEAAoE;YACpE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrB,WAAW,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;YAClC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,gEAAgE;YAChE,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9C,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC9C,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;gBACnC,WAAW,IAAI,WAAW,CAAC,WAAW,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACjC,CAAC"}

package/packages/rex/dist/core/remove-epic.d.ts

@@ -0,0 +1,35 @@
+import type { PRDItem } from "../schema/index.js";
+/**
+ * Result of a {@link removeEpic} operation.
+ *
+ * On success, `ok` is `true` and `deletedIds` contains the IDs of every
+ * item removed (the epic itself plus all descendants). On failure, `ok`
+ * is `false`, `error` explains why, and the tree is left unchanged.
+ */
+export interface RemoveEpicResult {
+    /** Whether the removal succeeded. */
+    ok: boolean;
+    /** IDs of all items removed (epic + descendants). Empty on failure. */
+    deletedIds: string[];
+    /** Human-readable description of what happened. */
+    detail: string;
+    /** Error message when `ok` is `false`. Undefined on success. */
+    error?: string;
+}
+/**
+ * Remove an epic and all its descendants from the PRD tree.
+ *
+ * This is a safe, atomic operation:
+ * - Validates the target exists and is actually an epic before mutating.
+ * - Removes the epic and every nested feature/task/subtask.
+ * - Cleans up `blockedBy` references in remaining items that pointed
+ *   to any of the deleted items.
+ *
+ * The function mutates `items` in place (consistent with {@link deleteItem}
+ * and {@link pruneItems}).
+ *
+ * @param items - The root-level PRD item array (mutated on success).
+ * @param epicId - The ID of the epic to remove.
+ * @returns A result object describing success/failure and deleted IDs.
+ */
+export declare function removeEpic(items: PRDItem[], epicId: string): RemoveEpicResult;

package/packages/rex/dist/core/remove-epic.js

@@ -0,0 +1,51 @@
+import { getLevelLabel } from "../schema/index.js";
+import { findItem } from "./tree.js";
+import { deleteItem, cleanBlockedByRefs } from "./delete.js";
+/**
+ * Remove an epic and all its descendants from the PRD tree.
+ *
+ * This is a safe, atomic operation:
+ * - Validates the target exists and is actually an epic before mutating.
+ * - Removes the epic and every nested feature/task/subtask.
+ * - Cleans up `blockedBy` references in remaining items that pointed
+ *   to any of the deleted items.
+ *
+ * The function mutates `items` in place (consistent with {@link deleteItem}
+ * and {@link pruneItems}).
+ *
+ * @param items - The root-level PRD item array (mutated on success).
+ * @param epicId - The ID of the epic to remove.
+ * @returns A result object describing success/failure and deleted IDs.
+ */
+export function removeEpic(items, epicId) {
+    // 1. Validate the item exists
+    const entry = findItem(items, epicId);
+    if (!entry) {
+        return {
+            ok: false,
+            deletedIds: [],
+            detail: `Epic "${epicId}" not found.`,
+            error: `Item "${epicId}" not found in the PRD tree.`,
+        };
+    }
+    // 2. Validate it's actually an epic
+    if (entry.item.level !== "epic") {
+        return {
+            ok: false,
+            deletedIds: [],
+            detail: `Item "${epicId}" is a ${getLevelLabel(entry.item.level)}, not an ${getLevelLabel("epic")}.`,
+            error: `Item "${entry.item.title}" (${epicId}) is not an ${getLevelLabel("epic")} — it is a ${getLevelLabel(entry.item.level)}.`,
+        };
+    }
+    const epicTitle = entry.item.title;
+    // 3. Delete the epic and all descendants
+    const deletedIds = deleteItem(items, epicId);
+    // 4. Clean up blockedBy references pointing to deleted items
+    cleanBlockedByRefs(items, new Set(deletedIds));
+    return {
+        ok: true,
+        deletedIds,
+        detail: `Removed epic: ${epicTitle} (${deletedIds.length} item(s) deleted)`,
+    };
+}
+//# sourceMappingURL=remove-epic.js.map

package/packages/rex/dist/core/remove-epic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-epic.js","sourceRoot":"","sources":["../../src/core/remove-epic.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAoB7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB,EAAE,MAAc;IACzD,8BAA8B;IAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,SAAS,MAAM,cAAc;YACrC,KAAK,EAAE,SAAS,MAAM,8BAA8B;SACrD,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAChC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,EAAE;YACd,MAAM,EAAE,SAAS,MAAM,UAAU,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,aAAa,CAAC,MAAM,CAAC,GAAG;YACpG,KAAK,EAAE,SAAS,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,MAAM,eAAe,aAAa,CAAC,MAAM,CAAC,cAAc,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG;SACjI,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;IAEnC,yCAAyC;IACzC,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAE7C,6DAA6D;IAC7D,kBAAkB,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;IAE/C,OAAO;QACL,EAAE,EAAE,IAAI;QACR,UAAU;QACV,MAAM,EAAE,iBAAiB,SAAS,KAAK,UAAU,CAAC,MAAM,mBAAmB;KAC5E,CAAC;AACJ,CAAC"}

package/packages/rex/dist/core/remove-feature.d.ts

@@ -0,0 +1,100 @@
+import type { PRDItem } from "../schema/index.js";
+/**
+ * An external item that depends on something inside the feature's subtree
+ * via `blockedBy`.
+ */
+export interface ExternalDependent {
+    /** ID of the item that has the blockedBy reference. */
+    itemId: string;
+    /** Title of the item that has the blockedBy reference. */
+    title: string;
+    /** The ID within the feature's subtree that this item is blocked by. */
+    blockedById: string;
+}
+/**
+ * An item inside the feature's subtree that carries sync metadata
+ * (has been synced to an external system).
+ */
+export interface SyncedItem {
+    /** ID of the synced item. */
+    itemId: string;
+    /** Title of the synced item. */
+    title: string;
+    /** Remote system identifier. */
+    remoteId: string;
+}
+/**
+ * Result of pre-deletion integrity checks for a feature.
+ *
+ * Inspects the feature's subtree for external blockedBy references
+ * and sync metadata that could indicate corruption risk if deleted.
+ */
+export interface DeletionPreCheck {
+    /** ID of the feature being checked. */
+    featureId: string;
+    /** Title of the feature being checked. */
+    featureTitle: string;
+    /** Total number of items in the feature's subtree (including the feature). */
+    subtreeCount: number;
+    /** Items outside the subtree that reference items inside via blockedBy. */
+    externalDependents: ExternalDependent[];
+    /** Items in the subtree that have sync metadata (remoteId). */
+    syncedItems: SyncedItem[];
+    /** Whether deletion is safe (no external dependents, no synced items). */
+    safe: boolean;
+    /** Warning messages summarising the risks. */
+    warnings: string[];
+}
+/**
+ * Result of a {@link removeFeature} operation.
+ *
+ * On success, `ok` is `true` and `deletedIds` contains the IDs of every
+ * item removed (the feature itself plus all descendants). On failure,
+ * `ok` is `false`, `error` explains why, and the tree is left unchanged.
+ */
+export interface RemoveFeatureResult {
+    /** Whether the removal succeeded. */
+    ok: boolean;
+    /** IDs of all items removed (feature + descendants). Empty on failure. */
+    deletedIds: string[];
+    /** Human-readable description of what happened. */
+    detail: string;
+    /** Error message when `ok` is `false`. Undefined on success. */
+    error?: string;
+    /** Number of blockedBy references cleaned up in remaining items. */
+    cleanedRefs: number;
+}
+/**
+ * Run pre-deletion integrity checks on a feature.
+ *
+ * Inspects the feature's subtree for:
+ * 1. **External dependents** — items outside the subtree that reference
+ *    items inside via `blockedBy`. Deleting would leave dangling references.
+ * 2. **Synced items** — items in the subtree that carry sync metadata
+ *    (`remoteId`). Deleting locally without syncing the deletion to the
+ *    remote system risks data corruption.
+ *
+ * @param items     - The root-level PRD item array (read-only).
+ * @param featureId - The ID of the feature to check.
+ * @returns Pre-check result with safety assessment and warnings.
+ */
+export declare function preCheckFeatureDeletion(items: PRDItem[], featureId: string): DeletionPreCheck;
+/**
+ * Remove a feature and all its descendants from the PRD tree with
+ * full integrity protection.
+ *
+ * This is a safe, atomic operation:
+ * - Validates the target exists and is actually a feature before mutating.
+ * - Removes the feature and every nested task/subtask.
+ * - Cleans up `blockedBy` references in remaining items that pointed
+ *   to any of the deleted items.
+ *
+ * The function mutates `items` in place (consistent with {@link deleteItem}
+ * and {@link removeEpic}).
+ *
+ * @param items     - The root-level PRD item array (mutated on success).
+ * @param featureId - The ID of the feature to remove.
+ * @returns A result object describing success/failure, deleted IDs, and
+ *          the number of cleaned-up blockedBy references.
+ */
+export declare function removeFeature(items: PRDItem[], featureId: string): RemoveFeatureResult;