@phren/cli 0.0.4 → 0.0.6

package/mcp/dist/shared-index.js

@@ -6,12 +6,13 @@ import { globSync } from "glob";
 import { debugLog, appendIndexEvent, getProjectDirs, collectNativeMemoryFiles, runtimeFile, homeDir, readRootManifest, } from "./shared.js";
 import { getIndexPolicy, withFileLock } from "./shared-governance.js";
 import { stripTaskDoneSection } from "./shared-content.js";
+import { isInactiveFindingLine } from "./finding-lifecycle.js";
 import { invalidateDfCache } from "./shared-search-fallback.js";
 import { errorMessage } from "./utils.js";
 import { beginUserFragmentBuildCache, endUserFragmentBuildCache, extractAndLinkFragments, ensureGlobalEntitiesTable, } from "./shared-fragment-graph.js";
 import { bootstrapSqlJs } from "./shared-sqljs.js";
 import { getProjectOwnershipMode, getProjectSourcePath, readProjectConfig } from "./project-config.js";
-import { buildSourceDocKey, queryDocRows, queryRows, } from "./index-query.js";
+import { buildSourceDocKey, queryDocBySourceKey, queryDocRows, } from "./index-query.js";
 import { classifyTopicForText, readProjectTopics, } from "./project-topics.js";
 export { porterStem } from "./shared-stemmer.js";
 export { cosineFallback } from "./shared-search-fallback.js";
@@ -81,8 +82,8 @@ const FILE_TYPE_MAP = {
     "reference.md": "reference",
     "tasks.md": "task",
     "changelog.md": "changelog",
-    "canonical_memories.md": "canonical",
-    "memory_queue.md": "memory-queue",
+    "truths.md": "canonical",
+    "review.md": "review-queue",
 };
 function pathHasSegment(relPath, segment) {
     const parts = relPath.replace(/\\/g, "/").split("/").filter(Boolean);
@@ -101,6 +102,11 @@ export function classifyFile(filename, relPath) {
 }
 const IMPORT_RE = /^@import\s+(.+)$/gm;
 const MAX_IMPORT_DEPTH = 5;
+const IMPORT_ROOT_PREFIX = "shared/";
+function isAllowedImportPath(importPath) {
+    const normalized = importPath.replace(/\\/g, "/");
+    return normalized.startsWith(IMPORT_ROOT_PREFIX) && normalized.toLowerCase().endsWith(".md");
+}
 /**
  * Internal recursive helper for resolveImports. Tracks `seen` (cycle detection) and `depth` (runaway
  * recursion guard) — callers should never pass these; use the public `resolveImports` instead.
@@ -110,6 +116,9 @@ function _resolveImportsRecursive(content, phrenPath, seen, depth) {
         return content;
     return content.replace(IMPORT_RE, (_match, importPath) => {
         const trimmed = importPath.trim();
+        if (!isAllowedImportPath(trimmed)) {
+            return "<!-- @import blocked: only shared/*.md allowed -->";
+        }
         const globalRoot = path.resolve(phrenPath, "global");
         const resolved = path.join(globalRoot, trimmed);
         // Use lexical resolution first for the prefix check
@@ -282,7 +291,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
             }
         }
     }
-    // Include manual entity links so graph changes invalidate the cache
+    // Include manual fragment links so graph changes invalidate the cache
     const manualLinksPath = runtimeFile(phrenPath, "manual-links.json");
     if (fs.existsSync(manualLinksPath)) {
         try {
@@ -464,6 +473,10 @@ export function normalizeIndexedContent(content, type, phrenPath, maxChars) {
     if (type === "task") {
         normalized = stripTaskDoneSection(normalized);
     }
+    if (type === "findings") {
+        const lines = normalized.split("\n");
+        normalized = lines.filter(line => !isInactiveFindingLine(line)).join("\n");
+    }
     if (typeof maxChars === "number" && maxChars >= 0) {
         normalized = normalized.slice(0, maxChars);
     }
@@ -598,7 +611,7 @@ export function updateFileInIndex(db, filePath, phrenPath) {
         const type = classifyFile(filename, relFile);
         const entry = { fullPath: resolvedPath, project, filename, type, relFile };
         if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
-            // Re-extract entities for finding files
+            // Re-extract fragments for finding files
             if (type === "findings") {
                 try {
                     const content = fs.readFileSync(resolvedPath, "utf-8");
@@ -687,7 +700,7 @@ function isSentinelFresh(phrenPath, sentinel) {
     return true;
 }
 /**
- * Attempt to restore the entity graph (entities, entity_links, global_entities) from a
+ * Attempt to restore the fragment graph (entities, entity_links, global_entities) from a
  * previously persisted JSON snapshot. Returns true if the graph was loaded, false if the
  * caller must run full extraction instead.
  */
@@ -723,7 +736,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
             // is not empty after a cached-graph rebuild path.
             if (Array.isArray(graph.globalEntities)) {
                 for (const [entity, project, docKey] of graph.globalEntities) {
-                    // Skip global entities whose source doc no longer exists
+                    // Skip global fragments whose source doc no longer exists
                     if (docKey && !validDocKeys.has(docKey))
                         continue;
                     try {
@@ -736,7 +749,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
                 }
             }
             else {
-                // Older cache without globalEntities: re-derive from entity_links + entities
+                // Older cache without globalEntities: re-derive from entity_links + entities tables
                 try {
                     const rows = db.exec(`SELECT e.name, el.source_doc FROM entity_links el
              JOIN entities e ON el.target_id = e.id
@@ -769,7 +782,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
     }
     return false;
 }
-/** Merge manual entity links (written by link_findings tool) into the live DB. Always runs on
+/** Merge manual fragment links (written by link_findings tool) into the live DB. Always runs on
  * every build so hand-authored links survive a full index rebuild. */
 function mergeManualLinks(db, phrenPath) {
     const manualLinksPath = runtimeFile(phrenPath, 'manual-links.json');
@@ -782,8 +795,8 @@ function mergeManualLinks(db, phrenPath) {
         for (const link of manualLinks) {
             try {
                 // Validate: skip manual links whose sourceDoc no longer exists in the index
-                const docCheck = queryRows(db, "SELECT 1 FROM docs WHERE source_key = ? LIMIT 1", [link.sourceDoc]);
-                if (!docCheck || docCheck.length === 0) {
+                const docCheck = queryDocBySourceKey(db, phrenPath, link.sourceDoc);
+                if (!docCheck) {
                     if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
                         process.stderr.write(`[phren] manualLinks: pruning stale link to "${link.sourceDoc}"\n`);
                     pruned = true;
@@ -1001,7 +1014,7 @@ async function buildIndexImpl(phrenPath, profile) {
                                             extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
                                         }
                                         catch (err) {
-                                            debugLog(`entity extraction failed: ${errorMessage(err)}`);
+                                            debugLog(`fragment extraction failed: ${errorMessage(err)}`);
                                         }
                                     }
                                 }
@@ -1063,15 +1076,15 @@ async function buildIndexImpl(phrenPath, profile) {
       tokenize = "porter unicode61"
     );
   `);
-        // Entity graph tables for lightweight reference graph
+        // Fragment graph tables for lightweight reference graph
         db.run(`CREATE TABLE IF NOT EXISTS entities (id INTEGER PRIMARY KEY, name TEXT NOT NULL, type TEXT NOT NULL, first_seen_at TEXT, UNIQUE(name, type))`);
         db.run(`CREATE TABLE IF NOT EXISTS entity_links (source_id INTEGER REFERENCES entities(id), target_id INTEGER REFERENCES entities(id), rel_type TEXT NOT NULL, source_doc TEXT, PRIMARY KEY (source_id, target_id, rel_type))`);
-        // Q20: Cross-project entity index
+        // Q20: Cross-project fragment index
         ensureGlobalEntitiesTable(db);
         const allFiles = globResult.entries;
         const newHashes = {};
         let fileCount = 0;
-        // Try loading cached entity graph
+        // Try loading cached fragment graph
         const graphPath = runtimeFile(phrenPath, 'entity-graph.json');
         const entityGraphLoaded = loadCachedEntityGraph(db, graphPath, allFiles, phrenPath);
         for (const entry of allFiles) {
@@ -1084,19 +1097,19 @@ async function buildIndexImpl(phrenPath, profile) {
             }
             if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
                 fileCount++;
-                // Extract entities from finding files (if not loaded from cache)
+                // Extract fragments from finding files (if not loaded from cache)
                 if (!entityGraphLoaded && entry.type === "findings") {
                     try {
                         const content = fs.readFileSync(entry.fullPath, "utf-8");
                         extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
                     }
                     catch (err) {
-                        debugLog(`entity extraction failed: ${errorMessage(err)}`);
+                        debugLog(`fragment extraction failed: ${errorMessage(err)}`);
                     }
                 }
             }
         }
-        // Persist entity graph for next build
+        // Persist fragment graph for next build
         if (!entityGraphLoaded) {
             try {
                 const entityRows = db.exec("SELECT id, name, type FROM entities")[0]?.values ?? [];

package/mcp/dist/shared-retrieval.js

@@ -3,7 +3,7 @@ import { getQualityMultiplier, entryScoreKey, } from "./shared-governance.js";
 import { queryDocRows, queryRows, cosineFallback, extractSnippet, getDocSourceKey, getEntityBoostDocs, decodeFiniteNumber, rowToDocWithRowid, } from "./shared-index.js";
 import { filterTrustedFindingsDetailed, } from "./shared-content.js";
 import { parseCitationComment } from "./content-citation.js";
-import { getHighImpactFindings } from "./finding-impact.js";
+import { getHighImpactFindings, getImpactSurfaceCounts } from "./finding-impact.js";
 import { buildFtsQueryVariants, buildRelaxedFtsQuery, isFeatureEnabled, STOP_WORDS } from "./utils.js";
 import * as fs from "fs";
 import * as path from "path";
@@ -36,6 +36,8 @@ const LOW_VALUE_BULLET_FRACTION = 0.5;
 // ── Intent and scoring helpers ───────────────────────────────────────────────
 export function detectTaskIntent(prompt) {
     const p = prompt.toLowerCase();
+    if (/\/\w+/.test(p) || /\b(skill|swarm|command|lineup|slash command)\b/.test(p))
+        return "skill";
     if (/(bug|error|fix|broken|regression|fail|stack trace)/.test(p))
         return "debug";
     if (/(review|audit|pr|pull request|nit|refactor)/.test(p))
@@ -47,6 +49,8 @@ export function detectTaskIntent(prompt) {
     return "general";
 }
 function intentBoost(intent, docType) {
+    if (intent === "skill" && docType === "skill")
+        return 4;
     if (intent === "debug" && (docType === "findings" || docType === "reference"))
         return 3;
     if (intent === "review" && (docType === "canonical" || docType === "changelog"))
@@ -343,10 +347,23 @@ export function searchDocuments(db, safeQuery, prompt, keywords, detectedProject
     if (ftsDocs.length === 0 && relaxedQuery && relaxedQuery !== safeQuery) {
         runScopedFtsQuery(relaxedQuery);
     }
+    // Tier 1.5: Fragment graph expansion
+    const fragmentExpansionDocs = [];
+    const queryLower = (prompt + " " + keywords).toLowerCase();
+    const fragmentBoostDocKeys = getEntityBoostDocs(db, queryLower);
+    for (const docKey of fragmentBoostDocKeys) {
+        if (ftsSeenKeys.has(docKey))
+            continue;
+        const rows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE path = ? LIMIT 1", [docKey]);
+        if (rows?.length) {
+            ftsSeenKeys.add(docKey);
+            fragmentExpansionDocs.push(rows[0]);
+        }
+    }
     // Tier 2: Token-overlap semantic — always run, scored independently
     const semanticDocs = semanticFallbackDocs(db, `${prompt}\n${keywords}`, detectedProject);
     // Merge with Reciprocal Rank Fusion so documents found by both tiers rank highest
-    const merged = rrfMerge([ftsDocs, semanticDocs]);
+    const merged = rrfMerge([ftsDocs, fragmentExpansionDocs, semanticDocs]);
     if (merged.length === 0)
         return null;
     return merged.slice(0, 12);
@@ -498,6 +515,7 @@ export function applyTrustFilter(rows, ttlDays, minConfidence, decay, phrenPath)
     const queueItems = [];
     const auditEntries = [];
     const highImpactFindingIds = phrenPath ? getHighImpactFindings(phrenPath, 3) : undefined;
+    const impactCounts = phrenPath ? getImpactSurfaceCounts(phrenPath, 1) : undefined;
     const filtered = rows
         .map((doc) => {
         if (!TRUST_FILTERED_TYPES.has(doc.type))
@@ -508,6 +526,7 @@ export function applyTrustFilter(rows, ttlDays, minConfidence, decay, phrenPath)
             decay,
             project: doc.project,
             highImpactFindingIds,
+            impactCounts,
         });
         if (trust.issues.length > 0) {
             const stale = trust.issues.filter((i) => i.reason === "stale").map((i) => i.bullet);
@@ -611,7 +630,7 @@ export function rankResults(rows, intent, gitCtx, detectedProject, phrenPathLoca
     const scored = ranked.map((doc) => {
         const globBoost = getProjectGlobBoost(phrenPathLocal, doc.project, cwd, gitCtx?.changedFiles);
         const key = entryScoreKey(doc.project, doc.filename, doc.content);
-        const entity = entityBoostPaths.has(doc.path) ? 1.3 : 1;
+        const entity = entityBoostPaths.has(doc.path) ? 1.5 : 1;
         const date = getRecentDate(doc);
         const fileRel = fileRelevanceBoost(doc.path, changedFiles);
         const branchMat = branchMatchBoost(doc.content, gitCtx?.branch);
@@ -626,7 +645,12 @@ export function rankResults(rows, intent, gitCtx, detectedProject, phrenPathLoca
             && queryOverlap < WEAK_CROSS_PROJECT_OVERLAP_MAX
             ? WEAK_CROSS_PROJECT_OVERLAP_PENALTY
             : 0;
+        // Boost skills whose filename matches a query token (e.g. "swarm" matches swarm.md)
+        const skillNameBoost = doc.type === "skill" && queryTokens.length > 0
+            ? queryTokens.some((t) => doc.filename.replace(/\.md$/i, "").toLowerCase() === t) ? 4 : 0
+            : 0;
         const score = Math.round((intentBoost(intent, doc.type) +
+            skillNameBoost +
             fileRel +
             branchMat +
             globBoost +
@@ -747,10 +771,40 @@ export function markStaleCitations(snippet) {
     }
     return result.join("\n");
 }
+function annotateContradictions(snippet) {
+    return snippet.split('\n').map(line => {
+        const conflictMatch = line.match(/<!-- conflicts_with: "(.*?)" -->/);
+        const contradictMatch = line.match(/<!-- phren:contradicts "(.*?)" -->/);
+        const statusMatch = line.match(/phren:status "contradicted"/);
+        if (conflictMatch) {
+            return line.replace(conflictMatch[0], '') + ` [CONTRADICTED — conflicts with: "${conflictMatch[1]}"]`;
+        }
+        if (contradictMatch) {
+            return line.replace(contradictMatch[0], '') + ` [CONTRADICTED — see: "${contradictMatch[1]}"]`;
+        }
+        if (statusMatch) {
+            return line + ' [CONTRADICTED]';
+        }
+        return line;
+    }).join('\n');
+}
 export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudget) {
     const selected = [];
     let usedTokens = 36;
     const queryTokens = tokenizeForOverlap(keywords);
+    const seenBullets = new Set();
+    // For each snippet being added, hash its bullet lines and skip duplicates
+    function dedupSnippetBullets(snippet) {
+        return snippet.split('\n').filter(line => {
+            if (!line.startsWith('- '))
+                return true; // Keep non-bullet lines (headers, etc)
+            const normalized = line.replace(/<!--.*?-->/g, '').trim().toLowerCase();
+            if (seenBullets.has(normalized))
+                return false;
+            seenBullets.add(normalized);
+            return true;
+        }).join('\n');
+    }
     for (const doc of rows) {
         let snippet = compactSnippet(extractSnippet(doc.content, keywords, 8), lineBudget, charBudget);
         if (!snippet.trim())
@@ -759,6 +813,10 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
         if (TRUST_FILTERED_TYPES.has(doc.type)) {
             snippet = markStaleCitations(snippet);
         }
+        snippet = annotateContradictions(snippet);
+        snippet = dedupSnippetBullets(snippet);
+        if (!snippet.trim())
+            continue;
         let focusScore = queryTokens.length > 0
             ? overlapScore(queryTokens, `${doc.filename}\n${snippet}`)
             : 1;

package/mcp/dist/shell-entry.js

@@ -3,7 +3,8 @@
  * Extracted from shell.ts to keep the orchestrator under 300 lines.
  */
 import { PhrenShell } from "./shell.js";
-import { style, clearScreen, clearToEnd, shellStartupFrames } from "./shell-render.js";
+import { style, clearScreen, clearToEnd, shellStartupFrames, gradient, badge } from "./shell-render.js";
+import { createPhrenAnimator } from "./phren-art.js";
 import { errorMessage } from "./utils.js";
 import { computePhrenLiveStateToken } from "./shared.js";
 import { VERSION } from "./init-shared.js";
@@ -59,13 +60,55 @@ async function playStartupIntro(phrenPath, plan = resolveStartupIntroPlan(phrenP
             await sleep(160);
         }
     }
-    renderIntroFrame(frames[frames.length - 1], renderHint);
+    // Start animated phren during loading
+    const animator = createPhrenAnimator({ facing: "right" });
+    animator.start();
+    const cols = process.stdout.columns || 80;
+    const tagline = style.dim("local memory for working agents");
+    const versionBadge = badge(`v${VERSION}`, style.boldBlue);
+    const logoLines = [
+        "██████╗ ██╗  ██╗██████╗ ███████╗███╗   ██╗",
+        "██╔══██╗██║  ██║██╔══██╗██╔════╝████╗  ██║",
+        "██████╔╝███████║██████╔╝█████╗  ██╔██╗ ██║",
+        "██╔═══╝ ██╔══██║██╔══██╗██╔══╝  ██║╚██╗██║",
+        "██║     ██║  ██║██║  ██║███████╗██║ ╚████║",
+        "╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝",
+    ].map(l => gradient(l));
+    const infoLine = `${gradient("◆")} ${style.bold("phren")}  ${versionBadge}  ${tagline}`;
+    function renderAnimatedFrame(hint) {
+        const phrenLines = animator.getFrame();
+        const rightSide = ["", "", ...logoLines, "", infoLine];
+        const charWidth = 26;
+        const maxLines = Math.max(phrenLines.length, rightSide.length);
+        const merged = [""];
+        for (let i = 0; i < maxLines; i++) {
+            const left = (i < phrenLines.length ? phrenLines[i] : "").padEnd(charWidth);
+            const right = i < rightSide.length ? rightSide[i] : "";
+            merged.push(left + right);
+        }
+        if (hint)
+            merged.push("", `  ${hint}`);
+        merged.push("");
+        renderIntroFrame(merged.join("\n"));
+    }
+    // Animate during dwell/loading period
     if (plan.holdForKeypress) {
+        const animInterval = setInterval(() => renderAnimatedFrame(renderHint), 200);
+        renderAnimatedFrame(renderHint);
         await waitForAnyKeypress();
+        clearInterval(animInterval);
     }
     else if (plan.dwellMs > 0) {
-        await sleep(plan.dwellMs);
+        const startTime = Date.now();
+        while (Date.now() - startTime < plan.dwellMs) {
+            renderAnimatedFrame(renderHint);
+            await sleep(200);
+        }
+    }
+    else {
+        renderAnimatedFrame(renderHint);
     }
+    animator.stop();
     if (plan.markSeen) {
         markStartupIntroSeen(phrenPath);
     }

package/mcp/dist/status.js

@@ -39,7 +39,7 @@ function countBullets(filePath) {
     return content.split("\n").filter((l) => l.startsWith("- ")).length;
 }
 function countQueueItems(phrenPath, project) {
-    const queueFile = path.join(phrenPath, project, "MEMORY_QUEUE.md");
+    const queueFile = path.join(phrenPath, project, "review.md");
     return countBullets(queueFile);
 }
 function runGit(cwd, args) {

package/mcp/dist/test-global-setup.js

@@ -1,10 +1,9 @@
 /**
  * Vitest globalSetup — runs once in the main process before any test workers spawn.
  *
- * Builds mcp/dist if it is missing or stale so every fork sees a complete,
- * consistent dist artifact. Running the build here (rather than inside each
- * fork via ensureCliBuilt) eliminates the race condition where one fork runs
- * `rm -rf mcp/dist` while another fork is checking fs.existsSync(CLI_PATH).
+ * Builds mcp/dist if it is missing so every fork sees a complete, consistent
+ * dist artifact before tests begin. Individual subprocess helpers can still
+ * repair a missing artifact later under a lock if some test mutates dist.
  *
  * `pretest` in package.json already calls `npm run build`, so in normal `npm test`
  * runs this is a fast no-op check. It is the safety net for:

package/mcp/dist/tool-registry.js

@@ -7,7 +7,7 @@ const CATEGORY_BY_MODULE = {
     "mcp-finding": "Finding capture",
     "mcp-memory": "Memory quality",
     "mcp-data": "Data management",
-    "mcp-graph": "Entities and graph",
+    "mcp-graph": "Fragments and graph",
     "mcp-session": "Session management",
     "mcp-ops": "Operations and review",
     "mcp-skills": "Skills management",

package/mcp/dist/utils.js

@@ -222,7 +222,7 @@ export function safeProjectPath(base, ...segments) {
     }
     return resolved;
 }
-const QUEUE_FILENAME = "MEMORY_QUEUE.md";
+const QUEUE_FILENAME = "review.md";
 export function queueFilePath(phrenPath, project) {
     if (!isValidProjectName(project)) {
         throw new Error(`Invalid project name: ${project}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phren/cli",
-  "version": "0.0.4",
-  "description": "Long-term memory for AI agents. Stored as markdown in a git repo you own.",
+  "version": "0.0.6",
+  "description": "Knowledge layer for AI agents. Claude remembers you. Phren remembers your work.",
   "type": "module",
   "bin": {
     "phren": "mcp/dist/index.js"
@@ -34,7 +34,7 @@
     "vitest": "^4.0.18"
   },
   "scripts": {
-    "build": "rm -rf mcp/dist && tsc -p mcp/tsconfig.json && chmod +x mcp/dist/index.js && cp mcp/src/synonyms*.json mcp/dist/",
+    "build": "node scripts/build.mjs",
     "dev": "tsx mcp/src/index.ts",
     "lint": "eslint mcp/src/ --ignore-pattern '*.test.ts'",
     "validate-docs": "bash scripts/validate-docs.sh",