@phren/cli 0.0.28 → 0.0.32

package/mcp/dist/{content-learning.js → content/learning.js}

@@ -1,18 +1,18 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
-import { debugLog, appendAuditLog, phrenOk, phrenErr, PhrenError } from "./shared.js";
-import { normalizeMemoryScope } from "./shared.js";
-import { withFileLock } from "./shared-governance.js";
-import { isValidProjectName, safeProjectPath } from "./utils.js";
-import { getMachineName } from "./machine-identity.js";
-import { buildCitationComment, buildSourceComment, getHeadCommit, getRepoRoot, inferCitationLocation, isFindingProvenanceSource, } from "./content-citation.js";
-import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCoref, detectConflicts, extractDynamicEntities } from "./content-dedup.js";
-import { validateFindingsFormat, validateFinding } from "./content-validate.js";
-import { countActiveFindings, autoArchiveToReference } from "./content-archive.js";
-import { resolveAutoFindingTaskItem, resolveFindingTaskReference, resolveFindingSessionId, } from "./finding-context.js";
-import { buildLifecycleComments, extractFindingType, parseFindingLifecycle, stripLifecycleComments, } from "./finding-lifecycle.js";
-import { METADATA_REGEX, } from "./content-metadata.js";
+import { debugLog, appendAuditLog, phrenOk, phrenErr, PhrenError } from "../shared.js";
+import { normalizeMemoryScope } from "../shared.js";
+import { withFileLock } from "../shared/governance.js";
+import { isValidProjectName, safeProjectPath } from "../utils.js";
+import { getMachineName } from "../machine-identity.js";
+import { buildCitationComment, buildSourceComment, getHeadCommit, getRepoRoot, inferCitationLocation, isFindingProvenanceSource, } from "./citation.js";
+import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCoref, detectConflicts, extractDynamicEntities } from "./dedup.js";
+import { validateFindingsFormat, validateFinding } from "./validate.js";
+import { countActiveFindings, autoArchiveToReference } from "./archive.js";
+import { resolveAutoFindingTaskItem, resolveFindingTaskReference, resolveFindingSessionId, } from "../finding/context.js";
+import { buildLifecycleComments, extractFindingType, parseFindingLifecycle, stripLifecycleComments, } from "../finding/lifecycle.js";
+import { METADATA_REGEX, } from "./metadata.js";
 /** Default cap for active findings before auto-archiving is triggered. */
 const DEFAULT_FINDINGS_CAP = 20;
 const LIFECYCLE_ANNOTATION_RE = METADATA_REGEX.lifecycleAnnotation;

package/mcp/dist/{content-validate.js → content/validate.js}

@@ -2,11 +2,11 @@ import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
 import { execFileSync } from "child_process";
-import { debugLog, EXEC_TIMEOUT_MS, getProjectDirs } from "./shared.js";
-import { errorMessage } from "./utils.js";
-import { countActiveFindings } from "./content-archive.js";
-import { isTaskFileName } from "./data-tasks.js";
-import { METADATA_REGEX } from "./content-metadata.js";
+import { debugLog, EXEC_TIMEOUT_MS, getProjectDirs } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { countActiveFindings } from "./archive.js";
+import { isTaskFileName } from "../data/tasks.js";
+import { METADATA_REGEX } from "./metadata.js";
 /** Maximum allowed length for a single finding entry (token budget protection). */
 export const MAX_FINDING_LENGTH = 2000;
 function safeParseDate(s) {

package/mcp/dist/{core-finding.js → core/finding.js}

@@ -1,7 +1,7 @@
-import { isValidProjectName } from "./utils.js";
-import { addFindingToFile, } from "./shared-content.js";
-import { removeFinding as removeFindingStore, } from "./data-access.js";
-import { MAX_FINDING_LENGTH } from "./content-validate.js";
+import { isValidProjectName } from "../utils.js";
+import { addFindingToFile, } from "../shared/content.js";
+import { removeFinding as removeFindingStore, } from "../data/access.js";
+import { MAX_FINDING_LENGTH } from "../content/validate.js";
 /**
  * Validate and add a single finding. Shared validation logic used by
  * both CLI `phren add-finding` and MCP `add_finding` tool.

package/mcp/dist/{core-project.js → core/project.js}

@@ -1,8 +1,8 @@
 import * as path from "path";
-import { phrenErr, phrenOk, readRootManifest } from "./shared.js";
-import { bootstrapFromExisting } from "./init-setup.js";
-import { resolveActiveProfile } from "./profile-store.js";
-import { TASKS_FILENAME } from "./data-tasks.js";
+import { phrenErr, phrenOk, readRootManifest } from "../shared.js";
+import { bootstrapFromExisting } from "../init/setup.js";
+import { resolveActiveProfile } from "../profile-store.js";
+import { TASKS_FILENAME } from "../data/tasks.js";
 export function addProjectFromPath(phrenPath, targetPath, requestedProfile, ownership) {
     if (!targetPath) {
         return phrenErr("Path is required. Pass the current project directory explicitly to avoid adding the wrong working directory.");

package/mcp/dist/{core-search.js → core/search.js}

@@ -1,5 +1,5 @@
-import { STOP_WORDS } from "./utils.js";
-import { queryDocRows } from "./shared-index.js";
+import { STOP_WORDS } from "../utils.js";
+import { queryDocRows } from "../shared/index.js";
 /**
  * Keyword overlap fallback for when FTS5 returns no results.
  * Scans all docs (optionally filtered by project/type), scores each by

package/mcp/dist/{data-access.js → data/access.js}

@@ -1,18 +1,21 @@
+// Barrel module: re-exports task, profile, and shell-state APIs from their
+// dedicated modules (data-tasks.ts, profile-store.ts, shell-state-store.ts)
+// and owns finding/queue logic directly.
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
-import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "./shared.js";
-import { normalizeQueueEntryText, } from "./shared-governance.js";
-import { addFindingToFile, } from "./shared-content.js";
-import { isValidProjectName, queueFilePath, safeProjectPath } from "./utils.js";
-import { parseCitationComment, parseSourceComment, } from "./content-citation.js";
-import { parseFindingLifecycle, } from "./finding-lifecycle.js";
-import { METADATA_REGEX, isCitationLine, isArchiveStart, isArchiveEnd, parseFindingId, parseAllContradictions, stripComments, normalizeFindingText, } from "./content-metadata.js";
-import { withSafeLock, ensureProject } from "./shared-data-utils.js";
-export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks, completeTasks, completeTask, removeTask, removeTasks, updateTask, linkTaskIssue, pinTask, unpinTask, workNextTask, tidyDoneTasks, taskMarkdown, appendChildFinding, promoteTask, TASKS_FILENAME, TASK_FILE_ALIASES, canonicalTaskFilePath, resolveTaskFilePath, isTaskFileName, } from "./data-tasks.js";
-export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, } from "./profile-store.js";
-export { loadShellState, resetShellState, saveShellState, } from "./shell-state-store.js";
-export { getRuntimeHealth as readRuntimeHealth } from "./shared-governance.js";
+import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "../shared.js";
+import { normalizeQueueEntryText, } from "../shared/governance.js";
+import { addFindingToFile, } from "../shared/content.js";
+import { isValidProjectName, queueFilePath, safeProjectPath } from "../utils.js";
+import { parseCitationComment, parseSourceComment, } from "../content/citation.js";
+import { parseFindingLifecycle, } from "../finding/lifecycle.js";
+import { METADATA_REGEX, isCitationLine, isArchiveStart, isArchiveEnd, parseFindingId, parseAllContradictions, stripComments, normalizeFindingText, } from "../content/metadata.js";
+import { withSafeLock, ensureProject } from "../shared/data-utils.js";
+export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks, completeTasks, completeTask, removeTask, removeTasks, updateTask, linkTaskIssue, pinTask, unpinTask, workNextTask, tidyDoneTasks, taskMarkdown, appendChildFinding, promoteTask, TASKS_FILENAME, TASK_FILE_ALIASES, canonicalTaskFilePath, resolveTaskFilePath, isTaskFileName, } from "./tasks.js";
+export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, } from "../profile-store.js";
+export { loadShellState, resetShellState, saveShellState, } from "../shell/state-store.js";
+export { getRuntimeHealth as readRuntimeHealth } from "../shared/governance.js";
 function extractDateHeading(line) {
     const heading = line.match(/^##\s+(.+)$/);
     if (!heading)
@@ -113,7 +116,6 @@ export function readFindings(phrenPath, project, opts = {}) {
     const includeArchived = opts.includeArchived ?? false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        const trimmed = line.trim();
         const archiveStartMatch = isArchiveStart(line);
         const archiveEnd = isArchiveEnd(line);
         if (archiveStartMatch) {
@@ -277,6 +279,55 @@ export function removeFinding(phrenPath, project, match) {
         return phrenOk(`Removed from ${project}: ${matched}`);
     });
 }
+export function removeFindings(phrenPath, project, matches) {
+    const ensured = ensureProject(phrenPath, project);
+    if (!ensured.ok)
+        return forwardErr(ensured);
+    const findingsPath = path.resolve(path.join(ensured.data, 'FINDINGS.md'));
+    if (!findingsPath.startsWith(phrenPath + path.sep) && findingsPath !== phrenPath) {
+        return phrenErr(`FINDINGS.md path escapes phren store`, PhrenError.VALIDATION_ERROR);
+    }
+    if (!fs.existsSync(findingsPath))
+        return phrenErr(`No FINDINGS.md file found for "${project}". Add a finding first with add_finding or :find add.`, PhrenError.FILE_NOT_FOUND);
+    return withSafeLock(findingsPath, () => {
+        const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
+        const removed = [];
+        const errors = [];
+        const bulletLines = collectFindingBulletLines(lines);
+        const activeBullets = bulletLines.filter(({ archived }) => !archived);
+        const archivedBullets = bulletLines.filter(({ archived }) => archived);
+        // Collect indices to remove (with citation lines) in one pass over matches
+        const indicesToRemove = new Set();
+        for (const match of matches) {
+            const needle = normalizeFindingText(match);
+            const activeMatch = findMatchingFindingBullet(activeBullets.filter(({ i }) => !indicesToRemove.has(i)), needle, match);
+            if (activeMatch.kind === "ambiguous") {
+                errors.push(match);
+                continue;
+            }
+            if (activeMatch.kind === "not_found") {
+                const archivedMatch = findMatchingFindingBullet(archivedBullets, needle, match);
+                if (archivedMatch.kind === "ambiguous" || archivedMatch.kind === "found") {
+                    errors.push(match);
+                    continue;
+                }
+                errors.push(match);
+                continue;
+            }
+            const idx = activeMatch.idx;
+            indicesToRemove.add(idx);
+            if (isCitationLine(lines[idx + 1] || ""))
+                indicesToRemove.add(idx + 1);
+            removed.push(lines[idx]);
+        }
+        if (removed.length > 0) {
+            const filtered = lines.filter((_, i) => !indicesToRemove.has(i));
+            const normalized = filtered.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+            fs.writeFileSync(findingsPath, normalized);
+        }
+        return phrenOk({ removed, errors });
+    });
+}
 export function editFinding(phrenPath, project, oldText, newText) {
     const ensured = ensureProject(phrenPath, project);
     if (!ensured.ok)
@@ -384,6 +435,73 @@ export function readReviewQueue(phrenPath, project) {
     }
     return phrenOk(items);
 }
+/** Locate a queue line and apply a mutation within a file lock. */
+function withQueueLineOp(phrenPath, project, lineText, op) {
+    const ensured = ensureProject(phrenPath, project);
+    if (!ensured.ok)
+        return forwardErr(ensured);
+    const file = queuePath(phrenPath, project);
+    if (!fs.existsSync(file))
+        return phrenErr(`No review queue found for "${project}".`, PhrenError.FILE_NOT_FOUND);
+    return withSafeLock(file, () => {
+        const lines = fs.readFileSync(file, "utf8").split("\n");
+        const idx = lines.findIndex((l) => l.trim() === lineText.trim());
+        if (idx === -1)
+            return phrenErr(`Queue item not found in "${project}".`, PhrenError.NOT_FOUND);
+        return op(lines, idx, file);
+    });
+}
+function writeQueueLines(file, lines) {
+    fs.writeFileSync(file, lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n");
+}
+/** Remove a queue item's line from review.md (finding stays in FINDINGS.md). */
+export function approveQueueItem(phrenPath, project, lineText) {
+    return withQueueLineOp(phrenPath, project, lineText, (lines, idx, file) => {
+        lines.splice(idx, 1);
+        writeQueueLines(file, lines);
+        return phrenOk(`Approved queue item in ${project}`);
+    });
+}
+/** Remove a queue item from review.md AND remove the corresponding finding from FINDINGS.md. */
+export function rejectQueueItem(phrenPath, project, lineText) {
+    const lockResult = withQueueLineOp(phrenPath, project, lineText, (lines, idx, file) => {
+        lines.splice(idx, 1);
+        writeQueueLines(file, lines);
+        return phrenOk("ok");
+    });
+    if (!lockResult.ok)
+        return lockResult;
+    const parsed = parseQueueLine(lineText);
+    if (parsed.text) {
+        const removeResult = removeFinding(phrenPath, project, parsed.text);
+        if (!removeResult.ok) {
+            return phrenOk(`Rejected queue item from ${project} (note: finding not found in FINDINGS.md — may have already been removed)`);
+        }
+    }
+    return phrenOk(`Rejected and removed queue item from ${project}`);
+}
+/** Edit a queue item's text in review.md and the corresponding finding in FINDINGS.md. */
+export function editQueueItem(phrenPath, project, lineText, newText) {
+    const trimmed = newText.replace(/[\r\n]+/g, " ").trim();
+    if (!trimmed)
+        return phrenErr("New text cannot be empty.", PhrenError.EMPTY_INPUT);
+    const parsed = parseQueueLine(lineText);
+    const lockResult = withQueueLineOp(phrenPath, project, lineText, (lines, idx, file) => {
+        const dateMatch = lines[idx].match(/^- \[(\d{4}-\d{2}-\d{2})\]\s*/);
+        lines[idx] = dateMatch ? `- [${dateMatch[1]}] ${trimmed}` : `- ${trimmed}`;
+        writeQueueLines(file, lines);
+        return phrenOk("ok");
+    });
+    if (!lockResult.ok)
+        return lockResult;
+    if (parsed.text) {
+        const editResult = editFinding(phrenPath, project, parsed.text, trimmed);
+        if (!editResult.ok) {
+            return phrenOk(`Updated queue item in ${project} (note: corresponding finding not found in FINDINGS.md)`);
+        }
+    }
+    return phrenOk(`Updated queue item in ${project}`);
+}
 export function readReviewQueueAcrossProjects(phrenPath, profile) {
     const validation = validateAggregateQueueProfile(phrenPath, profile);
     if (!validation.ok)

package/mcp/dist/{data-tasks.js → data/tasks.js}

@@ -1,10 +1,10 @@
 import * as fs from "fs";
 import * as path from "path";
 import { randomBytes, randomUUID } from "crypto";
-import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, } from "./shared.js";
-import { validateTaskFormat } from "./shared-content.js";
-import { safeProjectPath } from "./utils.js";
-import { withSafeLock, ensureProject } from "./shared-data-utils.js";
+import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, } from "../shared.js";
+import { validateTaskFormat } from "../shared/content.js";
+import { safeProjectPath } from "../utils.js";
+import { withSafeLock, ensureProject } from "../shared/data-utils.js";
 const ACTIVE_HEADINGS = new Set(["active", "in progress", "in-progress", "current", "wip"]);
 const QUEUE_HEADINGS = new Set(["queue", "queued", "task", "todo", "upcoming", "next"]);
 const DONE_HEADINGS = new Set(["done", "completed", "finished", "archived"]);
@@ -408,7 +408,7 @@ export function addTask(phrenPath, project, item, opts) {
         return phrenOk(newItem);
     });
 }
-export function addTasks(phrenPath, project, items) {
+export function addTasks(phrenPath, project, items, opts) {
     const bPath = canonicalTaskFilePath(phrenPath, project);
     if (!bPath)
         return phrenErr(`Project name "${project}" is not valid.`, PhrenError.INVALID_PROJECT_NAME);
@@ -429,10 +429,12 @@ export function addTasks(phrenPath, project, items) {
             }
             parsed.data.items.Queue.push({
                 id: `Q${parsed.data.items.Queue.length + 1}`,
+                stableId: newBid(),
                 section: "Queue",
                 line,
                 checked: false,
                 priority: normalizePriority(line),
+                scope: opts?.scope,
             });
             added.push(line);
         }

package/mcp/dist/embedding.js

@@ -2,9 +2,10 @@ import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
 import { debugLog, runtimeDir, } from "./shared.js";
-import { withFileLock } from "./shared-governance.js";
+import { withFileLock } from "./shared/governance.js";
 import { errorMessage } from "./utils.js";
-import { bootstrapSqlJs } from "./shared-sqljs.js";
+import { bootstrapSqlJs } from "./shared/sqljs.js";
+import { logger } from "./logger.js";
 let sqlJsLoader = bootstrapSqlJs;
 const EMBED_CACHE_DB = "embed-cache.db";
 function getCacheDbPath(phrenPath) {
@@ -79,8 +80,7 @@ async function openCacheDb(phrenPath) {
             db?.close();
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] embedding openCacheDb dbClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+            logger.debug("embedding", `embedding openCacheDb dbClose: ${e2 instanceof Error ? e2.message : String(e2)}`);
         }
         throw err;
     }
@@ -126,14 +126,12 @@ function persistDb(phrenPath, db) {
                 }
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] embedding persistDb onDiskLoad: ${errorMessage(err)}\n`);
+                logger.debug("embedding", `embedding persistDb onDiskLoad: ${errorMessage(err)}`);
                 try {
                     onDisk?.close();
                 }
                 catch (e2) {
-                    if ((process.env.PHREN_DEBUG))
-                        process.stderr.write(`[phren] embedding persistDb onDiskClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+                    logger.debug("embedding", `embedding persistDb onDiskClose: ${e2 instanceof Error ? e2.message : String(e2)}`);
                 }
                 onDisk = null;
             }
@@ -149,8 +147,7 @@ function persistDb(phrenPath, db) {
                         onDisk.close();
                     }
                     catch (e2) {
-                        if ((process.env.PHREN_DEBUG))
-                            process.stderr.write(`[phren] embedding persistDb onDiskCloseFinally: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+                        logger.debug("embedding", `embedding persistDb onDiskCloseFinally: ${e2 instanceof Error ? e2.message : String(e2)}`);
                     }
             }
         });
@@ -269,8 +266,7 @@ export async function getCachedEmbedding(phrenPath, text, apiKey, model) {
             db?.close();
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] embedding getCachedEmbedding dbClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+            logger.debug("embedding", `embedding getCachedEmbedding dbClose: ${e2 instanceof Error ? e2.message : String(e2)}`);
         }
     }
 }
@@ -320,8 +316,7 @@ export async function getCachedEmbeddings(phrenPath, texts, apiKey, model) {
             db?.close();
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] embedding getCachedEmbeddings dbClose: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+            logger.debug("embedding", `embedding getCachedEmbeddings dbClose: ${e2 instanceof Error ? e2.message : String(e2)}`);
         }
     }
 }

package/mcp/dist/entrypoint.js

@@ -1,9 +1,10 @@
 import * as fs from "fs";
 import * as path from "path";
-import { parseMcpMode, runInit } from "./init.js";
+import { parseMcpMode, runInit } from "./init/init.js";
 import { errorMessage } from "./utils.js";
+import { logger } from "./logger.js";
 import { defaultPhrenPath, findPhrenPath } from "./shared.js";
-import { addProjectFromPath } from "./core-project.js";
+import { addProjectFromPath } from "./core/project.js";
 import { PROJECT_OWNERSHIP_MODES, getProjectOwnershipDefault, parseProjectOwnershipMode, } from "./project-config.js";
 const HELP_TEXT = `phren - persistent knowledge for your agents
 
@@ -344,7 +345,7 @@ export async function runTopLevelCommand(argv) {
         return finish();
     }
     if (argvCommand === "uninstall") {
-        const { runUninstall } = await import("./init.js");
+        const { runUninstall } = await import("./init/init.js");
         const skipConfirm = argv.includes("--yes") || argv.includes("-y");
         await runUninstall({ yes: skipConfirm });
         return finish();
@@ -355,8 +356,8 @@ export async function runTopLevelCommand(argv) {
         return finish();
     }
     if (argvCommand === "verify") {
-        const { runPostInitVerify, getVerifyOutcomeNote } = await import("./init.js");
-        const { getWorkflowPolicy } = await import("./shared-governance.js");
+        const { runPostInitVerify, getVerifyOutcomeNote } = await import("./init/init.js");
+        const { getWorkflowPolicy } = await import("./shared/governance.js");
         const phrenPath = findPhrenPath() || defaultPhrenPath();
         const result = runPostInitVerify(phrenPath);
         console.log(`phren verify: ${result.ok ? "ok" : "issues found"}`);
@@ -376,7 +377,7 @@ export async function runTopLevelCommand(argv) {
         return finish(result.ok ? 0 : 1);
     }
     if (argvCommand === "mcp-mode") {
-        const { runMcpMode } = await import("./init.js");
+        const { runMcpMode } = await import("./init/init.js");
         try {
             await runMcpMode(argv[1]);
             return finish();
@@ -387,7 +388,7 @@ export async function runTopLevelCommand(argv) {
         }
     }
     if (argvCommand === "hooks-mode") {
-        const { runHooksMode } = await import("./init.js");
+        const { runHooksMode } = await import("./init/init.js");
         try {
             await runHooksMode(argv[1]);
             return finish();
@@ -405,19 +406,18 @@ export async function runTopLevelCommand(argv) {
         return finish();
     }
     if (!argvCommand && process.stdin.isTTY && process.stdout.isTTY) {
-        const { runCliCommand } = await import("./cli.js");
+        const { runCliCommand } = await import("./cli/cli.js");
         await runCliCommand("shell", []);
         return finish();
     }
     if (argvCommand && CLI_COMMANDS.includes(argvCommand)) {
-        const { runCliCommand } = await import("./cli.js");
+        const { runCliCommand } = await import("./cli/cli.js");
         try {
             const { trackCliCommand } = await import("./telemetry.js");
             trackCliCommand(defaultPhrenPath(), argvCommand);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] cli trackCliCommand: ${errorMessage(err)}\n`);
+            logger.debug("cli", `trackCliCommand: ${errorMessage(err)}`);
         }
         await runCliCommand(argvCommand, argv.slice(1));
         return finish();

package/mcp/dist/{finding-context.js → finding/context.js}

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
-import { safeProjectPath } from "./utils.js";
-import { resolveTaskFilePath } from "./data-tasks.js";
+import { safeProjectPath } from "../utils.js";
+import { resolveTaskFilePath } from "../data/tasks.js";
 const ACTIVE_HEADINGS = new Set(["active", "in progress", "in-progress", "current", "wip"]);
 const QUEUE_HEADINGS = new Set(["queue", "queued", "task", "todo", "upcoming", "next"]);
 const DONE_HEADINGS = new Set(["done", "completed", "finished", "archived"]);

package/mcp/dist/{finding-impact.js → finding/impact.js}

@@ -1,8 +1,8 @@
 import * as crypto from "crypto";
 import * as fs from "fs";
-import { impactLogFile } from "./shared.js";
-import { withFileLock } from "./shared-governance.js";
-import { normalizeFindingText } from "./content-metadata.js";
+import { impactLogFile } from "../shared.js";
+import { withFileLock } from "../shared/governance.js";
+import { normalizeFindingText } from "../content/metadata.js";
 let highImpactCache = null;
 function nowIso() {
     return new Date().toISOString();

package/mcp/dist/{finding-journal.js → finding/journal.js}

@@ -1,10 +1,10 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
-import { runtimeDir, phrenOk, phrenErr, PhrenError } from "./shared.js";
-import { withFileLock } from "./shared-governance.js";
-import { addFindingToFile } from "./shared-content.js";
-import { isValidProjectName, errorMessage } from "./utils.js";
+import { runtimeDir, phrenOk, phrenErr, PhrenError } from "../shared.js";
+import { withFileLock } from "../shared/governance.js";
+import { addFindingToFile } from "../shared/content.js";
+import { isValidProjectName, errorMessage } from "../utils.js";
 function journalRoot(phrenPath) {
     const dir = path.join(runtimeDir(phrenPath), "finding-journal");
     fs.mkdirSync(dir, { recursive: true });

package/mcp/dist/{finding-lifecycle.js → finding/lifecycle.js}

@@ -1,11 +1,11 @@
 import * as fs from "fs";
 import * as path from "path";
-import { PhrenError, phrenErr, phrenOk } from "./phren-core.js";
+import { PhrenError, phrenErr, phrenOk } from "../phren-core.js";
 // Phren lifecycle comment prefix. No backward compat.
 const LIFECYCLE_PREFIX = "phren";
-import { withFileLock } from "./shared-governance.js";
-import { isValidProjectName, safeProjectPath } from "./utils.js";
-import { isArchiveEnd, isArchiveStart, parseCreatedDate as parseCreatedDateMeta, parseStatusField, parseStatus, parseSupersession, parseContradiction, parseFindingId as parseFindingIdMeta, stripLifecycleMetadata, stripRelationMetadata, normalizeFindingText, } from "./content-metadata.js";
+import { withFileLock } from "../shared/governance.js";
+import { isValidProjectName, safeProjectPath } from "../utils.js";
+import { isArchiveEnd, isArchiveStart, parseCreatedDate as parseCreatedDateMeta, parseStatusField, parseStatus, parseSupersession, parseContradiction, parseFindingId as parseFindingIdMeta, stripLifecycleMetadata, stripRelationMetadata, normalizeFindingText, } from "../content/metadata.js";
 export const FINDING_TYPE_DECAY = {
     'pattern': { maxAgeDays: 365, decayMultiplier: 1.0 }, // Slow decay, long-lived
     'decision': { maxAgeDays: Infinity, decayMultiplier: 1.0 }, // Never decays

package/mcp/dist/{governance-audit.js → governance/audit.js}

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
-import { debugLog } from "./shared.js";
-import { errorMessage } from "./utils.js";
+import { debugLog } from "../shared.js";
+import { errorMessage } from "../utils.js";
 export function recordRetrieval(phrenPath, file, section) {
     const dir = path.join(phrenPath, ".runtime");
     fs.mkdirSync(dir, { recursive: true });

package/mcp/dist/{governance-locks.js → governance/locks.js}

@@ -1,7 +1,8 @@
 import * as fs from "fs";
 import * as path from "path";
-import { debugLog } from "./shared.js";
-import { errorMessage } from "./utils.js";
+import { debugLog } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { logger } from "../logger.js";
 // Acquire the file lock, returning true on success or throwing on timeout.
 function acquireFileLock(lockPath) {
     const maxWait = Number.parseInt(process.env.PHREN_FILE_LOCK_MAX_WAIT_MS || "5000", 10) || 5000;
@@ -19,8 +20,7 @@ function acquireFileLock(lockPath) {
             break;
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] acquireFileLock lockWrite: ${errorMessage(err)}\n`);
+            logger.debug("acquireFileLock", `lockWrite: ${errorMessage(err)}`);
             try {
                 const stat = fs.statSync(lockPath);
                 if (Date.now() - stat.mtimeMs > staleThreshold) {
@@ -40,7 +40,14 @@ function acquireFileLock(lockPath) {
                                 }
                             }
                             else {
-                                ownerDead = true;
+                                try {
+                                    const result = require('child_process').spawnSync('tasklist', ['/FI', `PID eq ${lockPid}`, '/NH'], { encoding: 'utf8', timeout: 2000 });
+                                    if (result.stdout && result.stdout.includes(String(lockPid)))
+                                        ownerDead = false;
+                                }
+                                catch {
+                                    ownerDead = true;
+                                }
                             }
                         }
                     }
@@ -54,8 +61,7 @@ function acquireFileLock(lockPath) {
                 }
             }
             catch (statErr) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] acquireFileLock staleStat: ${statErr instanceof Error ? statErr.message : String(statErr)}\n`);
+                logger.debug("acquireFileLock", `staleStat: ${statErr instanceof Error ? statErr.message : String(statErr)}`);
                 sleep(pollInterval);
                 waited += pollInterval;
                 continue;
@@ -75,8 +81,7 @@ function releaseFileLock(lockPath) {
         fs.unlinkSync(lockPath);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] releaseFileLock: ${errorMessage(err)}\n`);
+        logger.debug("releaseFileLock", `${errorMessage(err)}`);
     }
 }
 // Q10: withFileLock now accepts both sync and async callbacks.

package/mcp/dist/{governance-policy.js → governance/policy.js}

@@ -1,13 +1,13 @@
 import * as crypto from "crypto";
 import * as fs from "fs";
 import * as path from "path";
-import { appendAuditLog, debugLog, getProjectDirs, isRecord, runtimeHealthFile, withDefaults, phrenErr, PhrenError, phrenOk, resolveFindingsPath } from "./shared.js";
-import { withFileLock, isFiniteNumber, hasValidSchemaVersion } from "./shared-governance.js";
-import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
-import { readProjectConfig } from "./project-config.js";
-import { getActiveProfileDefaults } from "./profile-store.js";
-import { runCustomHooks } from "./hooks.js";
-import { METADATA_REGEX, isCitationLine, isArchiveStart as isArchiveStartMeta, isArchiveEnd as isArchiveEndMeta, stripLifecycleMetadata as stripLifecycleMetadataMeta, } from "./content-metadata.js";
+import { appendAuditLog, debugLog, getProjectDirs, isRecord, runtimeHealthFile, withDefaults, phrenErr, PhrenError, phrenOk, resolveFindingsPath } from "../shared.js";
+import { withFileLock, isFiniteNumber, hasValidSchemaVersion } from "../shared/governance.js";
+import { errorMessage, isValidProjectName, safeProjectPath } from "../utils.js";
+import { readProjectConfig } from "../project-config.js";
+import { getActiveProfileDefaults } from "../profile-store.js";
+import { runCustomHooks } from "../hooks.js";
+import { METADATA_REGEX, isCitationLine, isArchiveStart as isArchiveStartMeta, isArchiveEnd as isArchiveEndMeta, stripLifecycleMetadata as stripLifecycleMetadataMeta, } from "../content/metadata.js";
 export const MAX_QUEUE_ENTRY_LENGTH = 500;
 export const GOVERNANCE_SCHEMA_VERSION = 1;
 const DEFAULT_POLICY = {
@@ -641,7 +641,7 @@ export function pruneDeadMemories(phrenPath, project, dryRun) {
         const file = resolveFindingsPath(dir);
         if (!file)
             continue;
-        // Q23: wrap read-modify-write in per-file lock to prevent races with concurrent finding writers
+        // Q23: see docs/decisions/Q23-per-file-lock-concurrent-writers.md
         withFileLock(file, () => {
             const lines = fs.readFileSync(file, "utf8").split("\n");
             let currentDate = null;
@@ -723,13 +723,11 @@ export function consolidateProjectFindings(phrenPath, project, dryRun) {
     const file = resolveFindingsPath(path.join(phrenPath, project));
     if (!file)
         return phrenErr(`No FINDINGS.md found for "${project}".`, PhrenError.FILE_NOT_FOUND);
-    // Q23: wrap entire read-modify-write in per-file lock to prevent races with concurrent finding writers
+    // Q23: see docs/decisions/Q23-per-file-lock-concurrent-writers.md
     const result = withFileLock(file, () => {
         const raw = fs.readFileSync(file, "utf8");
         const lines = raw.split("\n");
-        // Q12: Separate the file into "active" lines and verbatim archive/details blocks.
-        // Archive blocks (<!-- phren:archive:start/end --> and <details>...</details>) are
-        // collected verbatim and appended unchanged after the consolidated active section.
+        // Q12: see docs/decisions/Q12-active-vs-archive-separation.md
         const archiveBlocks = [];
         const activeLines = [];
         let inArchive = false;

package/mcp/dist/{governance-rbac.js → governance/rbac.js}

@@ -18,9 +18,9 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { debugLog } from "./shared.js";
-import { errorMessage } from "./utils.js";
-import { readProjectConfig } from "./project-config.js";
+import { debugLog } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { readProjectConfig } from "../project-config.js";
 function configDir(phrenPath) {
     return path.join(phrenPath, ".config");
 }