@n-dx/core 0.1.0

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

@@ -0,0 +1,47 @@
+/**
+ * Helper to reset completed ancestors after a child is added.
+ *
+ * This is the integration glue between `findParentResets` and the store.
+ * Call it after `store.addItem(child, parentId)` to automatically reopen
+ * any completed parents that now have outstanding work.
+ *
+ * @module core/cascade-reset
+ */
+import { findParentResets } from "./parent-reset.js";
+/**
+ * After adding a child to a parent, check whether the parent (and its
+ * ancestors) need to be reset from `completed` to `pending`.
+ *
+ * Loads the current document from the store, computes resets, applies
+ * them, and logs each reset.
+ *
+ * @param store    - The PRD store to read/write.
+ * @param parentId - The ID of the parent the child was added to.
+ *                   Pass `undefined` for root-level items (no reset needed).
+ * @returns Items that were reset. Empty array when no reset was needed.
+ */
+export async function cascadeParentReset(store, parentId) {
+    if (!parentId)
+        return { resetItems: [] };
+    const doc = await store.loadDocument();
+    const { resetIds, resetItems } = findParentResets(doc.items, parentId);
+    if (resetIds.length === 0)
+        return { resetItems: [] };
+    for (const id of resetIds) {
+        const item = await store.getItem(id);
+        if (!item)
+            continue;
+        await store.updateItem(id, {
+            status: "pending",
+            completedAt: undefined,
+        });
+        await store.appendLog({
+            timestamp: new Date().toISOString(),
+            event: "status_reset",
+            itemId: id,
+            detail: `Reset ${item.level}: ${item.title} from completed to pending (new child added)`,
+        });
+    }
+    return { resetItems };
+}
+//# sourceMappingURL=cascade-reset.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cascade-reset.js","sourceRoot":"","sources":["../../src/core/cascade-reset.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAOrD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAe,EACf,QAA4B;IAE5B,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAEzC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,YAAY,EAAE,CAAC;IACvC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAEvE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAErD,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,MAAM,KAAK,CAAC,UAAU,CAAC,EAAE,EAAE;YACzB,MAAM,EAAE,SAAuB;YAC/B,WAAW,EAAE,SAAS;SACvB,CAAC,CAAC;QACH,MAAM,KAAK,CAAC,SAAS,CAAC;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,cAAc;YACrB,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,SAAS,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,8CAA8C;SACzF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACxB,CAAC"}

package/packages/rex/dist/core/code-coverage.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Code coverage cross-reference for PRD items.
+ *
+ * Matches file paths mentioned in task descriptions and acceptance criteria
+ * against a list of changed files to suggest:
+ * - Tasks that may be addressed by recent changes
+ * - Changed files not covered by any task
+ *
+ * @module rex/core/code-coverage
+ */
+import type { PRDItem } from "../schema/index.js";
+/** A task that may be related to changed files. */
+export interface AffectedTask {
+    id: string;
+    title: string;
+    level: string;
+    status: string;
+    matchedFiles: string[];
+}
+/** A changed file not covered by any task. */
+export interface UncoveredChange {
+    file: string;
+}
+/** Result of cross-referencing changes with PRD tasks. */
+export interface CrossReferenceResult {
+    /** Tasks whose descriptions/criteria mention changed files. */
+    affectedTasks: AffectedTask[];
+    /** Changed files not mentioned in any task. */
+    uncoveredChanges: UncoveredChange[];
+}
+/**
+ * Cross-reference changed files with PRD items.
+ *
+ * @param items - PRD item tree
+ * @param changedFiles - list of file paths that have changed
+ * @returns tasks related to changes + uncovered change files
+ */
+export declare function crossReferenceChanges(items: PRDItem[], changedFiles: string[]): CrossReferenceResult;

package/packages/rex/dist/core/code-coverage.js

@@ -0,0 +1,85 @@
+/**
+ * Code coverage cross-reference for PRD items.
+ *
+ * Matches file paths mentioned in task descriptions and acceptance criteria
+ * against a list of changed files to suggest:
+ * - Tasks that may be addressed by recent changes
+ * - Changed files not covered by any task
+ *
+ * @module rex/core/code-coverage
+ */
+import { walkTree } from "./tree.js";
+/**
+ * Extract file path references from a text string.
+ * Matches common file path patterns (e.g. src/foo/bar.ts, ./lib/util.js).
+ */
+function extractFilePaths(text) {
+    // Match paths like src/foo.ts, ./lib/bar.js, packages/x/y.ts
+    const pattern = /(?:\.\/)?(?:[\w@-]+\/)+[\w.-]+\.\w+/g;
+    const matches = text.match(pattern);
+    return matches ? [...new Set(matches)] : [];
+}
+/**
+ * Collect all file path references from a PRD item's text fields.
+ */
+function collectItemFilePaths(item) {
+    const paths = [];
+    if (item.description) {
+        paths.push(...extractFilePaths(item.description));
+    }
+    if (item.acceptanceCriteria) {
+        for (const criterion of item.acceptanceCriteria) {
+            paths.push(...extractFilePaths(criterion));
+        }
+    }
+    return [...new Set(paths)];
+}
+/**
+ * Normalize a file path for matching (strip leading ./ and trailing whitespace).
+ */
+function normalizePath(path) {
+    return path.replace(/^\.\//, "").trim();
+}
+/**
+ * Cross-reference changed files with PRD items.
+ *
+ * @param items - PRD item tree
+ * @param changedFiles - list of file paths that have changed
+ * @returns tasks related to changes + uncovered change files
+ */
+export function crossReferenceChanges(items, changedFiles) {
+    const normalizedChanges = changedFiles.map(normalizePath);
+    const coveredFiles = new Set();
+    const affectedTasks = [];
+    for (const { item } of walkTree(items)) {
+        const itemPaths = collectItemFilePaths(item).map(normalizePath);
+        if (itemPaths.length === 0)
+            continue;
+        const matchedFiles = [];
+        for (const changed of normalizedChanges) {
+            for (const itemPath of itemPaths) {
+                // Match if the changed file ends with the item's referenced path
+                // or if the item's path ends with the changed file
+                if (changed.endsWith(itemPath) || itemPath.endsWith(changed) || changed === itemPath) {
+                    matchedFiles.push(changed);
+                    coveredFiles.add(changed);
+                    break;
+                }
+            }
+        }
+        if (matchedFiles.length > 0) {
+            affectedTasks.push({
+                id: item.id,
+                title: item.title,
+                level: item.level,
+                status: item.status,
+                matchedFiles: [...new Set(matchedFiles)],
+            });
+        }
+    }
+    const uncoveredChanges = normalizedChanges
+        .filter((f) => !coveredFiles.has(f))
+        .map((file) => ({ file }));
+    return { affectedTasks, uncoveredChanges };
+}
+//# sourceMappingURL=code-coverage.js.map

package/packages/rex/dist/core/code-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-coverage.js","sourceRoot":"","sources":["../../src/core/code-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAwBrC;;;GAGG;AACH,SAAS,gBAAgB,CAAC,IAAY;IACpC,6DAA6D;IAC7D,MAAM,OAAO,GAAG,sCAAsC,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,IAAa;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5B,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAgB,EAChB,YAAsB;IAEtB,MAAM,iBAAiB,GAAG,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,aAAa,GAAmB,EAAE,CAAC;IAEzC,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAChE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAErC,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;YACxC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,iEAAiE;gBACjE,mDAAmD;gBACnD,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;oBACrF,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBAC3B,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;oBAC1B,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,aAAa,CAAC,IAAI,CAAC;gBACjB,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;aACzC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,gBAAgB,GAAsB,iBAAiB;SAC1D,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACnC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE7B,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC;AAC7C,CAAC"}

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

@@ -0,0 +1,6 @@
+import type { PRDItem } from "../schema/index.js";
+export interface DAGResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateDAG(items: PRDItem[]): DAGResult;

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

@@ -0,0 +1,67 @@
+import { walkTree, collectAllIds } from "./tree.js";
+export function validateDAG(items) {
+    const errors = [];
+    // Collect all IDs, detect duplicates
+    const seenIds = new Map();
+    for (const { item } of walkTree(items)) {
+        const count = seenIds.get(item.id) ?? 0;
+        seenIds.set(item.id, count + 1);
+    }
+    for (const [id, count] of seenIds) {
+        if (count > 1) {
+            errors.push(`Duplicate ID: "${id}" appears ${count} times`);
+        }
+    }
+    const allIds = collectAllIds(items);
+    // Check blockedBy references and self-references
+    for (const { item } of walkTree(items)) {
+        if (item.blockedBy) {
+            for (const dep of item.blockedBy) {
+                if (dep === item.id) {
+                    errors.push(`Self-reference: "${item.id}" blocks itself`);
+                }
+                else if (!allIds.has(dep)) {
+                    errors.push(`Orphan reference: "${item.id}" blocked by unknown "${dep}"`);
+                }
+            }
+        }
+    }
+    // DFS cycle detection on the blockedBy graph
+    const adjacency = new Map();
+    for (const { item } of walkTree(items)) {
+        if (item.blockedBy && item.blockedBy.length > 0) {
+            adjacency.set(item.id, item.blockedBy.filter((d) => allIds.has(d)));
+        }
+    }
+    const visited = new Set();
+    const inStack = new Set();
+    function dfs(node, path) {
+        if (inStack.has(node)) {
+            const cycleStart = path.indexOf(node);
+            const cycle = path.slice(cycleStart).concat(node);
+            errors.push(`Cycle detected: ${cycle.join(" → ")}`);
+            return true;
+        }
+        if (visited.has(node))
+            return false;
+        visited.add(node);
+        inStack.add(node);
+        const deps = adjacency.get(node) ?? [];
+        for (const dep of deps) {
+            if (dfs(dep, [...path, node]))
+                return true;
+        }
+        inStack.delete(node);
+        return false;
+    }
+    for (const id of allIds) {
+        if (!visited.has(id)) {
+            dfs(id, []);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+//# sourceMappingURL=dag.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dag.js","sourceRoot":"","sources":["../../src/core/dag.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,10 @@
+import type { PRDItem } from "../schema/index.js";
+/**
+ * Delete an item and all its descendants from the tree.
+ * Returns the list of all deleted item IDs.
+ */
+export declare function deleteItem(items: PRDItem[], id: string): string[];
+/**
+ * Remove deleted IDs from all items' `blockedBy` arrays.
+ */
+export declare function cleanBlockedByRefs(items: PRDItem[], deletedIds: Set<string>): void;

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

@@ -0,0 +1,38 @@
+import { findItem, removeFromTree, walkTree } from "./tree.js";
+/**
+ * Delete an item and all its descendants from the tree.
+ * Returns the list of all deleted item IDs.
+ */
+export function deleteItem(items, id) {
+    const entry = findItem(items, id);
+    if (!entry)
+        return [];
+    // Collect all IDs that will be deleted (the item + all descendants)
+    const deletedIds = [];
+    function collectIds(item) {
+        deletedIds.push(item.id);
+        if (item.children) {
+            for (const child of item.children) {
+                collectIds(child);
+            }
+        }
+    }
+    collectIds(entry.item);
+    // Remove from tree
+    removeFromTree(items, id);
+    return deletedIds;
+}
+/**
+ * Remove deleted IDs from all items' `blockedBy` arrays.
+ */
+export function cleanBlockedByRefs(items, deletedIds) {
+    for (const { item } of walkTree(items)) {
+        if (item.blockedBy && item.blockedBy.length > 0) {
+            item.blockedBy = item.blockedBy.filter((ref) => !deletedIds.has(ref));
+            if (item.blockedBy.length === 0) {
+                delete item.blockedBy;
+            }
+        }
+    }
+}
+//# sourceMappingURL=delete.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delete.js","sourceRoot":"","sources":["../../src/core/delete.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE/D;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB,EAAE,EAAU;IACrD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,oEAAoE;IACpE,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,SAAS,UAAU,CAAC,IAAa;QAC/B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClC,UAAU,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IACD,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEvB,mBAAmB;IACnB,cAAc,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAE1B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAgB,EAAE,UAAuB;IAC1E,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YACtE,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAChC,OAAO,IAAI,CAAC,SAAS,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,94 @@
+/**
+ * Epic correlation recovery — suggests parent epics for orphaned features.
+ *
+ * Analyzes epicless features and ranks available epics by semantic similarity,
+ * enabling automated reparenting with user approval. Combines multiple signals:
+ *
+ * 1. Title similarity (bigram Dice + word overlap via dedupe.similarity)
+ * 2. Description similarity when both feature and epic have descriptions
+ * 3. Tag overlap bonus for shared tags
+ * 4. Child-content signal: similarity between feature children titles and epic children titles
+ *
+ * @module core/epic-correlation
+ */
+import type { PRDItem } from "../schema/index.js";
+import type { EpiclessFeature } from "./structural.js";
+export interface EpicCandidate {
+    /** The epic's ID. */
+    epicId: string;
+    /** The epic's title. */
+    epicTitle: string;
+    /** Combined similarity score (0.0–1.0). */
+    score: number;
+    /** Breakdown of individual signal scores for transparency. */
+    signals: CorrelationSignals;
+}
+export interface CorrelationSignals {
+    /** Title similarity between feature and epic (0.0–1.0). */
+    titleSimilarity: number;
+    /** Description similarity, or 0 if either lacks a description. */
+    descriptionSimilarity: number;
+    /** Fraction of shared tags (0.0–1.0), or 0 if no tags on either side. */
+    tagOverlap: number;
+    /** Similarity of child content (aggregated child titles), or 0 if insufficient data. */
+    childContentSimilarity: number;
+}
+export interface CorrelationResult {
+    /** The orphaned feature being analyzed. */
+    featureId: string;
+    featureTitle: string;
+    /** Ranked candidate epics, best match first. */
+    candidates: EpicCandidate[];
+    /** Whether a high-confidence match was found (score >= highConfidenceThreshold). */
+    hasHighConfidence: boolean;
+}
+export interface CorrelationOptions {
+    /** Minimum score to include a candidate. Default: 0.15 */
+    minScore?: number;
+    /** Score threshold for "high confidence" flag. Default: 0.5 */
+    highConfidenceThreshold?: number;
+    /** Maximum number of candidates to return per feature. Default: 5 */
+    maxCandidates?: number;
+}
+/**
+ * Compute tag overlap ratio between two sets of tags.
+ * Returns 0.0 when either side has no tags, 1.0 when identical.
+ */
+export declare function computeTagOverlap(tagsA: string[] | undefined, tagsB: string[] | undefined): number;
+/**
+ * Compute all correlation signals between a feature and an epic.
+ */
+export declare function computeCorrelationSignals(feature: PRDItem, epic: PRDItem): CorrelationSignals;
+/**
+ * Compute the combined score from individual signals.
+ *
+ * When description data is missing, its weight is redistributed to title
+ * to avoid penalizing items that simply lack descriptions.
+ */
+export declare function computeCombinedScore(signals: CorrelationSignals): number;
+/**
+ * Score and rank all available epics for a single orphaned feature.
+ *
+ * Returns candidates sorted by score descending, filtered by minScore
+ * and capped at maxCandidates.
+ */
+export declare function rankEpicsForFeature(feature: PRDItem, availableEpics: PRDItem[], options?: CorrelationOptions): EpicCandidate[];
+/**
+ * Analyze all epicless features and produce correlation results.
+ *
+ * This is the main entry point for the correlation recovery workflow.
+ * For each orphaned feature detected by structural validation, it:
+ * 1. Finds the full PRDItem from the document items
+ * 2. Scores all available epics using multi-signal similarity
+ * 3. Returns ranked candidates with a high-confidence flag
+ *
+ * @param items       Full PRD items array (for resolving features and epics)
+ * @param epicless    Epicless features detected by findEpiclessFeatures()
+ * @param options     Scoring configuration
+ * @returns One CorrelationResult per epicless feature, in input order
+ */
+export declare function correlateEpiclessFeatures(items: PRDItem[], epicless: EpiclessFeature[], options?: CorrelationOptions): CorrelationResult[];
+/**
+ * Format a score as a percentage string (e.g. "73%").
+ */
+export declare function formatScore(score: number): string;

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

@@ -0,0 +1,179 @@
+/**
+ * Epic correlation recovery — suggests parent epics for orphaned features.
+ *
+ * Analyzes epicless features and ranks available epics by semantic similarity,
+ * enabling automated reparenting with user approval. Combines multiple signals:
+ *
+ * 1. Title similarity (bigram Dice + word overlap via dedupe.similarity)
+ * 2. Description similarity when both feature and epic have descriptions
+ * 3. Tag overlap bonus for shared tags
+ * 4. Child-content signal: similarity between feature children titles and epic children titles
+ *
+ * @module core/epic-correlation
+ */
+import { isRootLevel } from "../schema/index.js";
+import { similarity } from "../analyze/dedupe.js";
+// ── Signal weights ───────────────────────────────────────────────────────────
+/**
+ * Weights for combining individual signals into a final score.
+ * Title similarity is the strongest signal; tag overlap and child content
+ * provide supporting evidence.
+ */
+const WEIGHTS = {
+    title: 0.45,
+    description: 0.25,
+    tags: 0.10,
+    childContent: 0.20,
+};
+// ── Defaults ─────────────────────────────────────────────────────────────────
+const DEFAULT_MIN_SCORE = 0.15;
+const DEFAULT_HIGH_CONFIDENCE = 0.5;
+const DEFAULT_MAX_CANDIDATES = 5;
+// ── Core logic ───────────────────────────────────────────────────────────────
+/**
+ * Compute tag overlap ratio between two sets of tags.
+ * Returns 0.0 when either side has no tags, 1.0 when identical.
+ */
+export function computeTagOverlap(tagsA, tagsB) {
+    if (!tagsA?.length || !tagsB?.length)
+        return 0;
+    const setA = new Set(tagsA.map((t) => t.toLowerCase()));
+    const setB = new Set(tagsB.map((t) => t.toLowerCase()));
+    let intersection = 0;
+    for (const tag of setA) {
+        if (setB.has(tag))
+            intersection++;
+    }
+    const union = new Set([...setA, ...setB]).size;
+    return union > 0 ? intersection / union : 0;
+}
+/**
+ * Build an aggregated content string from an item's children titles.
+ * Used to compare what a feature/epic "contains" at a topical level.
+ */
+function aggregateChildContent(item) {
+    const children = (item.children ?? []).filter((c) => c.status !== "deleted");
+    if (children.length === 0)
+        return "";
+    return children.map((c) => c.title).join(" ");
+}
+/**
+ * Compute all correlation signals between a feature and an epic.
+ */
+export function computeCorrelationSignals(feature, epic) {
+    // 1. Title similarity
+    const titleSimilarity = similarity(feature.title, epic.title);
+    // 2. Description similarity
+    let descriptionSimilarity = 0;
+    if (feature.description && epic.description) {
+        descriptionSimilarity = similarity(feature.description, epic.description);
+    }
+    // 3. Tag overlap
+    const tagOverlap = computeTagOverlap(feature.tags, epic.tags);
+    // 4. Child content similarity
+    let childContentSimilarity = 0;
+    const featureContent = aggregateChildContent(feature);
+    const epicContent = aggregateChildContent(epic);
+    if (featureContent.length > 0 && epicContent.length > 0) {
+        childContentSimilarity = similarity(featureContent, epicContent);
+    }
+    return {
+        titleSimilarity,
+        descriptionSimilarity,
+        tagOverlap,
+        childContentSimilarity,
+    };
+}
+/**
+ * Compute the combined score from individual signals.
+ *
+ * When description data is missing, its weight is redistributed to title
+ * to avoid penalizing items that simply lack descriptions.
+ */
+export function computeCombinedScore(signals) {
+    const hasDescription = signals.descriptionSimilarity > 0;
+    // Redistribute description weight to title when no description data
+    const titleWeight = hasDescription
+        ? WEIGHTS.title
+        : WEIGHTS.title + WEIGHTS.description;
+    const descWeight = hasDescription ? WEIGHTS.description : 0;
+    return (signals.titleSimilarity * titleWeight +
+        signals.descriptionSimilarity * descWeight +
+        signals.tagOverlap * WEIGHTS.tags +
+        signals.childContentSimilarity * WEIGHTS.childContent);
+}
+/**
+ * Score and rank all available epics for a single orphaned feature.
+ *
+ * Returns candidates sorted by score descending, filtered by minScore
+ * and capped at maxCandidates.
+ */
+export function rankEpicsForFeature(feature, availableEpics, options = {}) {
+    const minScore = options.minScore ?? DEFAULT_MIN_SCORE;
+    const maxCandidates = options.maxCandidates ?? DEFAULT_MAX_CANDIDATES;
+    const candidates = [];
+    for (const epic of availableEpics) {
+        const signals = computeCorrelationSignals(feature, epic);
+        const score = computeCombinedScore(signals);
+        if (score >= minScore) {
+            candidates.push({
+                epicId: epic.id,
+                epicTitle: epic.title,
+                score,
+                signals,
+            });
+        }
+    }
+    // Sort by score descending
+    candidates.sort((a, b) => b.score - a.score);
+    return candidates.slice(0, maxCandidates);
+}
+/**
+ * Analyze all epicless features and produce correlation results.
+ *
+ * This is the main entry point for the correlation recovery workflow.
+ * For each orphaned feature detected by structural validation, it:
+ * 1. Finds the full PRDItem from the document items
+ * 2. Scores all available epics using multi-signal similarity
+ * 3. Returns ranked candidates with a high-confidence flag
+ *
+ * @param items       Full PRD items array (for resolving features and epics)
+ * @param epicless    Epicless features detected by findEpiclessFeatures()
+ * @param options     Scoring configuration
+ * @returns One CorrelationResult per epicless feature, in input order
+ */
+export function correlateEpiclessFeatures(items, epicless, options = {}) {
+    const highConfidence = options.highConfidenceThreshold ?? DEFAULT_HIGH_CONFIDENCE;
+    // Collect available epics (non-deleted root-level epics)
+    const availableEpics = items.filter((item) => isRootLevel(item.level) && item.status !== "deleted");
+    const results = [];
+    for (const ef of epicless) {
+        // Find the full PRDItem for this epicless feature
+        const featureItem = items.find((i) => i.id === ef.itemId);
+        if (!featureItem) {
+            // Feature was removed between detection and correlation — skip
+            results.push({
+                featureId: ef.itemId,
+                featureTitle: ef.title,
+                candidates: [],
+                hasHighConfidence: false,
+            });
+            continue;
+        }
+        const candidates = rankEpicsForFeature(featureItem, availableEpics, options);
+        results.push({
+            featureId: ef.itemId,
+            featureTitle: ef.title,
+            candidates,
+            hasHighConfidence: candidates.length > 0 && candidates[0].score >= highConfidence,
+        });
+    }
+    return results;
+}
+/**
+ * Format a score as a percentage string (e.g. "73%").
+ */
+export function formatScore(score) {
+    return `${Math.round(score * 100)}%`;
+}
+//# sourceMappingURL=epic-correlation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"epic-correlation.js","sourceRoot":"","sources":["../../src/core/epic-correlation.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,54 @@
+/**
+ * Faceted classification for PRD items.
+ *
+ * Facets are stored as prefixed tags on items: `component:auth`, `concern:security`.
+ * This module provides helpers to read, write, and query facet values without
+ * requiring schema changes to PRDItem — facets piggyback on the existing `tags` array.
+ *
+ * @module rex/core/facets
+ */
+import type { PRDItem } from "../schema/index.js";
+/** Check whether a tag string is a facet tag (contains exactly one `:`). */
+export declare function isFacetTag(tag: string): boolean;
+/** Parse a facet tag into key/value, or return null if not a facet. */
+export declare function parseFacetTag(tag: string): {
+    key: string;
+    value: string;
+} | null;
+/** Get the facet value for a given key on an item, or undefined if not set. */
+export declare function getFacetValue(item: PRDItem, key: string): string | undefined;
+/**
+ * Set a facet value on an item (mutates `item.tags`).
+ * Replaces an existing value for the same key, or appends if new.
+ */
+export declare function setFacetValue(item: PRDItem, key: string, value: string): void;
+/** Remove a facet key from an item (mutates `item.tags`). Returns true if removed. */
+export declare function removeFacet(item: PRDItem, key: string): boolean;
+/** Get all facets on an item as a key→value record. */
+export declare function getItemFacets(item: PRDItem): Record<string, string>;
+/** Find all items (flattened from tree) matching a facet key/value. */
+export declare function getItemsByFacet(items: PRDItem[], key: string, value: string): PRDItem[];
+/** Group all items (flattened) by the value of a facet key. Items without the facet are excluded. */
+export declare function groupByFacet(items: PRDItem[], key: string): Map<string, PRDItem[]>;
+/** Configuration for a single facet dimension. */
+export interface FacetConfig {
+    label: string;
+    values: string[];
+    required?: boolean;
+}
+/** A suggested facet value for an item. */
+export interface FacetSuggestion {
+    key: string;
+    value: string;
+    reason: string;
+}
+/**
+ * Suggest facets for an item based on keyword matching and parent inheritance.
+ *
+ * Returns suggestions only — does not mutate the item.
+ */
+export declare function suggestFacets(item: PRDItem, facetConfig: Record<string, FacetConfig>, parent?: PRDItem): FacetSuggestion[];
+/**
+ * Compute facet distribution: for each configured facet, count items per value.
+ */
+export declare function computeFacetDistribution(items: PRDItem[], facetConfig: Record<string, FacetConfig>): Record<string, Record<string, number>>;