@phren/cli 0.0.10 → 0.0.11

package/mcp/dist/entrypoint.js

@@ -5,110 +5,124 @@ import { errorMessage } from "./utils.js";
 import { defaultPhrenPath, findPhrenPath } from "./shared.js";
 import { addProjectFromPath } from "./core-project.js";
 import { PROJECT_OWNERSHIP_MODES, getProjectOwnershipDefault, parseProjectOwnershipMode, } from "./project-config.js";
-const HELP_TEXT = `phren - He remembers so your agent doesn't have to
+const HELP_TEXT = `phren - persistent knowledge for your agents
 
-Usage:
-  phren                                 Open interactive shell
-  phren quickstart                      Quick setup: init + project scaffold
-  phren add [path] [--ownership <mode>] Add current directory (or path) as a project
-  phren init [--mode shared|project-local] [--machine <n>] [--profile <n>] [--mcp on|off] [--template <t>] [--dry-run] [-y]
-                                         Set up phren and offer to add the current project directory
-  phren projects list                   List all tracked projects
+  phren                     Interactive shell
+  phren init                Set up phren
+  phren add [path]          Register a project
+  phren search <query>      Search what phren knows
+  phren status              Health check
+  phren doctor [--fix]      Diagnose and repair
+  phren web-ui              Open the knowledge graph
+  phren tasks               Cross-project task view
+  phren graph               Fragment knowledge graph
+
+  phren help <topic>        Detailed help for a topic
+
+Topics: projects, skills, hooks, config, maintain, setup, env, all
+`;
+const HELP_TOPICS = {
+    projects: `Projects:
+  phren add [path] [--ownership <mode>]   Register a project
+  phren projects list                     List all tracked projects
   phren projects configure <name> [--ownership <mode>] [--hooks on|off]
-                                         Update per-project enrollment and hook settings
-  phren projects remove <name>          Remove a project (asks for confirmation)
-  phren detect-skills [--import]        Find untracked skills in ~/.claude/skills/
-  phren skills list                     List installed skills
-  phren skills add <project> <path>    Link or copy a skill file into one project
-  phren skills resolve <project|global> Print the resolved skill manifest for one scope
-  phren skills doctor <project|global> Diagnose resolved skill visibility + mirror state
-  phren skills sync <project|global>   Regenerate the resolved mirror for one scope
-  phren skills remove <project> <name> Remove a project skill by name
-  phren hooks list [--project <name>]   Show hook tool preferences and optional project overrides
-  phren hooks enable <tool>             Enable hooks for one tool
-  phren hooks disable <tool>            Disable hooks for one tool
-  phren status                          Health, active project, stats
-  phren review [project]               Show review queue items with date, confidence, text
-  phren consolidation-status [project] Check if findings need consolidation
-  phren session-context                Show current session state (project, duration, findings)
-  phren search <query> [--project <n>] [--type <t>] [--limit <n>]
-                                         Search what phren remembers
-  phren add-finding <project> "..."     Tell phren what you learned
-  phren pin <project> "..."             Save a truth
-  phren tasks                           Cross-project task view
-  phren skill-list                      List installed skills
-  phren doctor [--fix] [--check-data] [--agents]
-                                         Health check and self-heal (--agents: show agent integrations only)
-  phren web-ui [--port=3499] [--no-open]     Memory web UI
-  phren debug-injection --prompt "..."  Preview hook-prompt injection output
-  phren inspect-index [--project <n>]   Inspect FTS index contents for debugging
-  phren update [--refresh-starter]      Update to latest version
-  phren graph [--project <n>] [--limit <n>]
-                                         Show the fragment knowledge graph
-  phren graph link <project> "finding" "fragment"
-                                         Link a finding to a fragment manually
+                                           Update per-project settings
+  phren projects remove <name>            Remove a project
+`,
+    skills: `Skills:
+  phren skills list                       List installed skills
+  phren skills add <project> <path>       Link a skill into a project
+  phren skills show <name>                Show skill content
+  phren skills resolve <project|global>   Print resolved skill manifest
+  phren skills doctor <project|global>    Diagnose skill visibility
+  phren skills sync <project|global>      Regenerate skill mirror
+  phren skills remove <project> <name>    Remove a skill
+  phren detect-skills [--import]          Find untracked skills in ~/.claude/skills/
+`,
+    hooks: `Hooks:
+  phren hooks list [--project <name>]     Show hook status per tool
+  phren hooks enable <tool>               Enable hooks for a tool
+  phren hooks disable <tool>              Disable hooks for a tool
+  phren hooks add-custom <event> <cmd>    Add a custom hook
+  phren hooks remove-custom <event>       Remove custom hooks
+  phren hooks errors [--limit <n>]        Show recent hook errors
+`,
+    config: `Configuration:
+  phren config show [--project <name>]    Show current config
+  phren config policy [get|set ...]       Retention, TTL, confidence, decay
+  phren config workflow [get|set ...]     Risky-memory thresholds
+  phren config proactivity [level]        Set proactivity level
+  phren config task-mode [mode]           Set task automation mode
+  phren config finding-sensitivity [lvl]  Set finding capture sensitivity
+  phren config index [get|set ...]        Indexer include/exclude globs
+  phren config synonyms [list|add|remove] Manage learned synonyms
+  phren config project-ownership [mode]   Default ownership for new projects
+  phren config machines                   Registered machines
+  phren config profiles                   Profiles and projects
+  phren config telemetry [on|off]         Opt-in usage telemetry
 
-Configuration:
-  phren config policy [get|set ...]     Retention, TTL, confidence, decay
-  phren config workflow [get|set ...]   Risky-memory thresholds
-  phren config index [get|set ...]      Indexer include/exclude globs
-  phren config synonyms [list|add|remove] ...
-                                         Manage project learned synonyms
-  phren config project-ownership [mode] Default ownership for future project enrollments
-  phren config machines                 Registered machines
-  phren config profiles                 Profiles and projects
+  All config subcommands accept --project <name> for per-project overrides.
+`,
+    maintain: `Maintenance:
+  phren maintain govern [project]         Queue stale memories for review
+  phren maintain prune [project]          Delete expired entries
+  phren maintain consolidate [project]    Deduplicate findings
+  phren maintain extract [project]        Mine git/GitHub signals
+`,
+    setup: `Setup:
+  phren init [--mode shared|project-local] [--machine <n>] [--profile <n>] [--dry-run] [-y]
+  phren quickstart                        Quick setup: init + project scaffold
+  phren mcp-mode [on|off|status]          Toggle MCP integration
+  phren hooks-mode [on|off|status]        Toggle hook execution
+  phren verify                            Check init completed OK
+  phren uninstall                         Remove phren config and hooks
+  phren update [--refresh-starter]        Update to latest version
+`,
+    env: `Environment variables:
+  PHREN_PATH                  Override phren directory (default: ~/.phren)
+  PHREN_PROFILE               Active profile name
+  PHREN_DEBUG                 Enable debug logging (set to 1)
 
-Maintenance:
-  phren maintain govern [project]       Queue stale/low-value memories for review
-  phren maintain prune [project]        Delete expired entries
-  phren maintain consolidate [project]  Deduplicate FINDINGS.md
-  phren maintain extract [project]      Mine git/GitHub signals
+  Embeddings:
+  PHREN_OLLAMA_URL            Ollama base URL (default: http://localhost:11434, 'off' to disable)
+  PHREN_EMBEDDING_API_URL     OpenAI-compatible /embeddings endpoint
+  PHREN_EMBEDDING_API_KEY     API key for embedding endpoint
+  PHREN_EMBEDDING_MODEL       Embedding model (default: nomic-embed-text)
 
-Setup:
-  phren mcp-mode [on|off|status]        Toggle MCP integration
-  phren hooks-mode [on|off|status]      Toggle hook execution
-  phren verify                          Check init completed OK
-  phren uninstall                       Remove phren config and hooks
+  Context injection:
+  PHREN_CONTEXT_TOKEN_BUDGET  Max tokens injected per prompt (default: 550)
+  PHREN_MAX_INJECT_TOKENS     Hard cap on total injected tokens (default: 2000)
+  PHREN_HOOK_TIMEOUT_MS       Hook subprocess timeout in ms (default: 14000)
 
-Environment:
-  PHREN_PATH                Override phren directory (default: ~/.phren)
-  PHREN_PROFILE             Active profile name (otherwise phren uses machines.yaml when available)
-  PHREN_DEBUG               Enable debug logging (set to 1)
-  PHREN_OLLAMA_URL          Ollama base URL (default: http://localhost:11434; set to 'off' to disable)
-  PHREN_EMBEDDING_API_URL   OpenAI-compatible /embeddings endpoint (cloud alternative to Ollama)
-  PHREN_EMBEDDING_API_KEY   API key for PHREN_EMBEDDING_API_URL
-  PHREN_EMBEDDING_MODEL     Embedding model (default: nomic-embed-text)
-  PHREN_EXTRACT_MODEL       Ollama model for memory extraction (default: llama3.2)
-  PHREN_EMBEDDING_PROVIDER  Set to 'api' to use OpenAI API for search_knowledge embeddings
-  PHREN_FEATURE_AUTO_CAPTURE=1      Extract insights from conversations at session end
-  PHREN_FEATURE_SEMANTIC_DEDUP=1    LLM-based dedup on add_finding
-  PHREN_FEATURE_SEMANTIC_CONFLICT=1 LLM-based conflict detection on add_finding
-  PHREN_FEATURE_HYBRID_SEARCH=0     Disable TF-IDF cosine fallback in search_knowledge
-  PHREN_FEATURE_AUTO_EXTRACT=0      Disable automatic memory extraction on each prompt
-  PHREN_FEATURE_PROGRESSIVE_DISCLOSURE=1  Compact memory index injection
-  PHREN_LLM_MODEL           LLM model for semantic dedup/conflict (default: gpt-4o-mini)
-  PHREN_LLM_ENDPOINT        OpenAI-compatible /chat/completions base URL for dedup/conflict
-  PHREN_LLM_KEY             API key for PHREN_LLM_ENDPOINT
-  PHREN_CONTEXT_TOKEN_BUDGET    Max tokens injected per hook-prompt (default: 550)
-  PHREN_CONTEXT_SNIPPET_LINES   Max lines per injected snippet (default: 6)
-  PHREN_CONTEXT_SNIPPET_CHARS   Max chars per injected snippet (default: 520)
-  PHREN_MAX_INJECT_TOKENS       Hard cap on total injected tokens (default: 2000)
-  PHREN_TASK_PRIORITY        Priorities to include in task injection: high,medium,low (default: high,medium)
-  PHREN_MEMORY_TTL_DAYS         Override memory TTL for trust filtering
-  PHREN_HOOK_TIMEOUT_MS         Hook subprocess timeout in ms (default: 14000)
-  PHREN_FINDINGS_CAP            Max findings per date section before consolidation (default: 20)
-  PHREN_GH_PR_LIMIT/RUN_LIMIT/ISSUE_LIMIT  GitHub extraction limits (defaults: 40/25/25)
+  Feature flags:
+  PHREN_FEATURE_AUTO_EXTRACT=0       Disable auto memory extraction
+  PHREN_FEATURE_AUTO_CAPTURE=1       Extract insights from conversations
+  PHREN_FEATURE_SEMANTIC_DEDUP=1     LLM-based dedup on add_finding
+  PHREN_FEATURE_HYBRID_SEARCH=0      Disable TF-IDF cosine fallback
 
-Examples:
-  phren search "rate limiting"          Search across all projects
-  phren search "auth" --project my-api  Search within one project
-  phren add-finding my-app "Redis connections need explicit close in finally blocks"
-  phren doctor --fix                    Fix common config issues
-  phren config policy set --ttlDays=90  Change memory retention to 90 days
-  phren config project-ownership detached
-  phren maintain govern my-app          Queue stale memories for review
-  phren status                          Quick health check
-`;
+  Run 'phren help all' to see everything.
+`,
+};
+function buildFullHelp() {
+    return `phren - persistent knowledge for your agents
+
+Usage:
+  phren                     Interactive shell
+  phren init                Set up phren
+  phren add [path]          Register a project
+  phren search <query>      Search what phren knows
+  phren status              Health check
+  phren doctor [--fix]      Diagnose and repair
+  phren web-ui              Open the knowledge graph
+  phren tasks               Cross-project task view
+  phren graph               Fragment knowledge graph
+  phren add-finding <p> "." Tell phren what you learned
+  phren pin <p> "..."       Save a truth
+  phren review [project]    Show review queue
+  phren session-context     Current session state
+
+${Object.values(HELP_TOPICS).join("\n")}`;
+}
 const CLI_COMMANDS = [
     "search",
     "shell",
@@ -216,7 +230,19 @@ async function promptProjectOwnership(phrenPath, fallback) {
 export async function runTopLevelCommand(argv) {
     const argvCommand = argv[0];
     if (argvCommand === "--help" || argvCommand === "-h" || argvCommand === "help") {
-        console.log(HELP_TEXT);
+        const topic = argv[1]?.toLowerCase();
+        if (topic === "all") {
+            console.log(buildFullHelp());
+        }
+        else if (topic && HELP_TOPICS[topic]) {
+            console.log(HELP_TOPICS[topic]);
+        }
+        else if (topic) {
+            console.log(`Unknown topic: ${topic}\nAvailable: ${Object.keys(HELP_TOPICS).join(", ")}, all`);
+        }
+        else {
+            console.log(HELP_TEXT);
+        }
         return finish();
     }
     if (argvCommand === "add") {
@@ -313,7 +339,8 @@ export async function runTopLevelCommand(argv) {
     }
     if (argvCommand === "uninstall") {
         const { runUninstall } = await import("./init.js");
-        await runUninstall();
+        const skipConfirm = argv.includes("--yes") || argv.includes("-y");
+        await runUninstall({ yes: skipConfirm });
         return finish();
     }
     if (argvCommand === "status") {
@@ -349,7 +376,7 @@ export async function runTopLevelCommand(argv) {
             return finish();
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(errorMessage(err));
             return finish(1);
         }
     }
@@ -360,7 +387,7 @@ export async function runTopLevelCommand(argv) {
             return finish();
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(errorMessage(err));
             return finish(1);
         }
     }
@@ -383,7 +410,7 @@ export async function runTopLevelCommand(argv) {
             trackCliCommand(defaultPhrenPath(), argvCommand);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] cli trackCliCommand: ${errorMessage(err)}\n`);
         }
         await runCliCommand(argvCommand, argv.slice(1));

package/mcp/dist/governance-locks.js

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { debugLog } from "./shared.js";
+import { errorMessage } from "./utils.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;
@@ -18,8 +19,8 @@ function acquireFileLock(lockPath) {
             break;
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] acquireFileLock lockWrite: ${err instanceof Error ? err.message : String(err)}\n`);
+            if ((process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] acquireFileLock lockWrite: ${errorMessage(err)}\n`);
             try {
                 const stat = fs.statSync(lockPath);
                 if (Date.now() - stat.mtimeMs > staleThreshold) {
@@ -53,7 +54,7 @@ function acquireFileLock(lockPath) {
                 }
             }
             catch (statErr) {
-                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                if ((process.env.PHREN_DEBUG))
                     process.stderr.write(`[phren] acquireFileLock staleStat: ${statErr instanceof Error ? statErr.message : String(statErr)}\n`);
                 sleep(pollInterval);
                 waited += pollInterval;
@@ -74,8 +75,8 @@ function releaseFileLock(lockPath) {
         fs.unlinkSync(lockPath);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] releaseFileLock: ${err instanceof Error ? err.message : String(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] releaseFileLock: ${errorMessage(err)}\n`);
     }
 }
 // Q10: withFileLock now accepts both sync and async callbacks.

package/mcp/dist/governance-policy.js

@@ -4,6 +4,7 @@ import * as path from "path";
 import { appendAuditLog, debugLog, getProjectDirs, isRecord, runtimeHealthFile, withDefaults, phrenErr, PhrenError, phrenOk, resolveFindingsPath } from "./shared.js";
 import { withFileLock } from "./governance-locks.js";
 import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
+import { readProjectConfig } from "./project-config.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;
@@ -212,6 +213,148 @@ function normalizeIndexPolicy(data) {
         includeHidden: pickBoolean(data.includeHidden, DEFAULT_INDEX_POLICY.includeHidden),
     };
 }
+const VALID_PROACTIVITY_LEVELS = ["high", "medium", "low"];
+export const VALID_TASK_MODES = ["off", "manual", "suggest", "auto"];
+export const VALID_FINDING_SENSITIVITY = ["minimal", "conservative", "balanced", "aggressive"];
+const VALID_RISKY_SECTIONS = ["Review", "Stale", "Conflicts"];
+function pickEnum(value, allowed) {
+    return typeof value === "string" && allowed.includes(value) ? value : undefined;
+}
+function pickPositiveInt(value) {
+    return Number.isInteger(value) && typeof value === "number" && value > 0 ? value : undefined;
+}
+function pickUnitInterval(value) {
+    return isFiniteNumber(value) && value >= 0 && value <= 1 ? value : undefined;
+}
+function normalizeProjectConfigOverrides(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const retentionRaw = isRecord(raw.retentionPolicy) ? raw.retentionPolicy : undefined;
+    const decayRaw = retentionRaw && isRecord(retentionRaw.decay) ? retentionRaw.decay : undefined;
+    const retentionPolicy = retentionRaw
+        ? {
+            ttlDays: pickPositiveInt(retentionRaw.ttlDays),
+            retentionDays: pickPositiveInt(retentionRaw.retentionDays),
+            autoAcceptThreshold: pickUnitInterval(retentionRaw.autoAcceptThreshold),
+            minInjectConfidence: pickUnitInterval(retentionRaw.minInjectConfidence),
+            decay: decayRaw
+                ? {
+                    d30: pickUnitInterval(decayRaw.d30),
+                    d60: pickUnitInterval(decayRaw.d60),
+                    d90: pickUnitInterval(decayRaw.d90),
+                    d120: pickUnitInterval(decayRaw.d120),
+                }
+                : undefined,
+        }
+        : undefined;
+    if (retentionPolicy && retentionPolicy.decay && Object.values(retentionPolicy.decay).every((value) => value === undefined)) {
+        delete retentionPolicy.decay;
+    }
+    const workflowRaw = isRecord(raw.workflowPolicy) ? raw.workflowPolicy : undefined;
+    const workflowPolicy = workflowRaw
+        ? {
+            lowConfidenceThreshold: pickUnitInterval(workflowRaw.lowConfidenceThreshold),
+            riskySections: Array.isArray(workflowRaw.riskySections)
+                ? workflowRaw.riskySections.filter((section) => typeof section === "string" && VALID_RISKY_SECTIONS.includes(section))
+                : undefined,
+        }
+        : undefined;
+    if (workflowPolicy && workflowPolicy.riskySections && workflowPolicy.riskySections.length === 0) {
+        delete workflowPolicy.riskySections;
+    }
+    const overrides = {
+        findingSensitivity: pickEnum(raw.findingSensitivity, VALID_FINDING_SENSITIVITY),
+        proactivity: pickEnum(raw.proactivity, VALID_PROACTIVITY_LEVELS),
+        proactivityFindings: pickEnum(raw.proactivityFindings, VALID_PROACTIVITY_LEVELS),
+        proactivityTask: pickEnum(raw.proactivityTask, VALID_PROACTIVITY_LEVELS),
+        taskMode: pickEnum(raw.taskMode, VALID_TASK_MODES),
+        retentionPolicy: retentionPolicy && Object.values(retentionPolicy).some((value) => value !== undefined)
+            ? retentionPolicy
+            : undefined,
+        workflowPolicy: workflowPolicy && Object.values(workflowPolicy).some((value) => value !== undefined)
+            ? workflowPolicy
+            : undefined,
+    };
+    return overrides;
+}
+function readProjectConfigOverrides(phrenPath, projectName) {
+    try {
+        const config = readProjectConfig(phrenPath, projectName);
+        return normalizeProjectConfigOverrides(config.config);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function getProjectConfigOverrides(phrenPath, projectName) {
+    return readProjectConfigOverrides(phrenPath, projectName) ?? null;
+}
+export function mergeConfig(phrenPath, projectName) {
+    const globalRetention = getRetentionPolicyGlobal(phrenPath);
+    const globalWorkflow = getWorkflowPolicyGlobal(phrenPath);
+    if (projectName && !isValidProjectName(projectName)) {
+        debugLog(`mergeConfig: invalid project name "${projectName}", using global defaults`);
+        projectName = undefined;
+    }
+    if (!projectName) {
+        return {
+            findingSensitivity: globalWorkflow.findingSensitivity,
+            proactivity: {},
+            taskMode: globalWorkflow.taskMode,
+            retentionPolicy: globalRetention,
+            workflowPolicy: globalWorkflow,
+        };
+    }
+    const overrides = readProjectConfigOverrides(phrenPath, projectName);
+    if (!overrides) {
+        return {
+            findingSensitivity: globalWorkflow.findingSensitivity,
+            proactivity: {},
+            taskMode: globalWorkflow.taskMode,
+            retentionPolicy: globalRetention,
+            workflowPolicy: globalWorkflow,
+        };
+    }
+    // Merge retention policy
+    const retentionOverride = overrides.retentionPolicy;
+    const mergedRetention = retentionOverride
+        ? {
+            schemaVersion: globalRetention.schemaVersion,
+            ttlDays: retentionOverride.ttlDays ?? globalRetention.ttlDays,
+            retentionDays: retentionOverride.retentionDays ?? globalRetention.retentionDays,
+            autoAcceptThreshold: retentionOverride.autoAcceptThreshold ?? globalRetention.autoAcceptThreshold,
+            minInjectConfidence: retentionOverride.minInjectConfidence ?? globalRetention.minInjectConfidence,
+            decay: {
+                d30: retentionOverride.decay?.d30 ?? globalRetention.decay.d30,
+                d60: retentionOverride.decay?.d60 ?? globalRetention.decay.d60,
+                d90: retentionOverride.decay?.d90 ?? globalRetention.decay.d90,
+                d120: retentionOverride.decay?.d120 ?? globalRetention.decay.d120,
+            },
+        }
+        : globalRetention;
+    // Merge workflow policy
+    const workflowOverride = overrides.workflowPolicy;
+    const mergedWorkflow = {
+        schemaVersion: globalWorkflow.schemaVersion,
+        lowConfidenceThreshold: workflowOverride?.lowConfidenceThreshold ?? globalWorkflow.lowConfidenceThreshold,
+        riskySections: workflowOverride?.riskySections?.length
+            ? workflowOverride.riskySections
+            : globalWorkflow.riskySections,
+        taskMode: overrides.taskMode ?? globalWorkflow.taskMode,
+        findingSensitivity: overrides.findingSensitivity ?? globalWorkflow.findingSensitivity,
+    };
+    return {
+        findingSensitivity: mergedWorkflow.findingSensitivity,
+        proactivity: {
+            base: overrides.proactivity,
+            findings: overrides.proactivityFindings,
+            tasks: overrides.proactivityTask,
+        },
+        taskMode: mergedWorkflow.taskMode,
+        retentionPolicy: mergedRetention,
+        workflowPolicy: mergedWorkflow,
+    };
+}
 function readJsonFile(filePath, fallback) {
     try {
         if (!fs.existsSync(filePath))
@@ -246,10 +389,15 @@ function writeJsonFile(filePath, data) {
         writeJsonFileUnlocked(filePath, data);
     });
 }
-export function getRetentionPolicy(phrenPath) {
+function getRetentionPolicyGlobal(phrenPath) {
     const parsed = readJsonFile(govFile(phrenPath, "retention-policy"), {});
     return withDefaults(parsed, DEFAULT_POLICY);
 }
+export function getRetentionPolicy(phrenPath, projectName) {
+    if (projectName)
+        return mergeConfig(phrenPath, projectName).retentionPolicy;
+    return getRetentionPolicyGlobal(phrenPath);
+}
 export function updateRetentionPolicy(phrenPath, patch) {
     const current = getRetentionPolicy(phrenPath);
     const next = {
@@ -264,7 +412,7 @@ export function updateRetentionPolicy(phrenPath, patch) {
     appendAuditLog(phrenPath, "update_policy", JSON.stringify(next));
     return phrenOk(next);
 }
-export function getWorkflowPolicy(phrenPath) {
+function getWorkflowPolicyGlobal(phrenPath) {
     const parsed = readJsonFile(govFile(phrenPath, "workflow-policy"), {});
     const merged = withDefaults(parsed, DEFAULT_WORKFLOW_POLICY);
     const validSections = new Set(["Review", "Stale", "Conflicts"]);
@@ -279,6 +427,11 @@ export function getWorkflowPolicy(phrenPath) {
     }
     return merged;
 }
+export function getWorkflowPolicy(phrenPath, projectName) {
+    if (projectName)
+        return mergeConfig(phrenPath, projectName).workflowPolicy;
+    return getWorkflowPolicyGlobal(phrenPath);
+}
 export function updateWorkflowPolicy(phrenPath, patch) {
     const current = getWorkflowPolicy(phrenPath);
     const riskySections = Array.isArray(patch.riskySections)

package/mcp/dist/governance-scores.js

@@ -120,7 +120,7 @@ function readScoreJournal(phrenPath) {
                 return JSON.parse(line);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                if ((process.env.PHREN_DEBUG))
                     process.stderr.write(`[phren] readScoreJournal parseLine: ${errorMessage(err)}\n`);
                 return null;
             }
@@ -153,7 +153,7 @@ function claimScoreJournal(phrenPath) {
                 return JSON.parse(line);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                if ((process.env.PHREN_DEBUG))
                     process.stderr.write(`[phren] claimScoreJournal parseLine: ${errorMessage(err)}\n`);
                 return null;
             }
@@ -169,7 +169,7 @@ function claimScoreJournal(phrenPath) {
             fs.unlinkSync(claimedFile);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] claimScoreJournal unlinkClaim: ${errorMessage(err)}\n`);
         }
     }

package/mcp/dist/hooks.js

@@ -1,18 +1,12 @@
 import * as fs from "fs";
 import * as path from "path";
-import { createHmac, randomUUID } from "crypto";
+import { createHmac } from "crypto";
 import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
-import { EXEC_TIMEOUT_QUICK_MS, PhrenError, debugLog, runtimeFile, homePath, installPreferencesFile } from "./shared.js";
+import { EXEC_TIMEOUT_QUICK_MS, PhrenError, debugLog, runtimeFile, homePath, installPreferencesFile, atomicWriteText } from "./shared.js";
 import { errorMessage } from "./utils.js";
 import { hookConfigPath } from "./provider-adapters.js";
 import { PACKAGE_SPEC } from "./package-metadata.js";
-function atomicWriteText(filePath, content) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const tmpPath = `${filePath}.tmp-${randomUUID()}`;
-    fs.writeFileSync(tmpPath, content);
-    fs.renameSync(tmpPath, filePath);
-}
 export function commandExists(cmd) {
     try {
         const whichCmd = process.platform === "win32" ? "where.exe" : "which";
@@ -215,10 +209,34 @@ function validateCodexConfig(config) {
         Array.isArray(config.hooks?.UserPromptSubmit) &&
         Array.isArray(config.hooks?.Stop));
 }
+// ── mtime-based install-preferences cache (shared by readHookPreferences + readCustomHooks) ──
+const _installPrefsJsonCache = new Map();
+export function clearHookPrefsCache() {
+    _installPrefsJsonCache.clear();
+}
+function cachedReadInstallPrefsJson(phrenPath) {
+    const prefsPath = installPreferencesFile(phrenPath);
+    let mtimeMs;
+    try {
+        mtimeMs = fs.statSync(prefsPath).mtimeMs;
+    }
+    catch {
+        _installPrefsJsonCache.delete(prefsPath);
+        return null;
+    }
+    const cached = _installPrefsJsonCache.get(prefsPath);
+    if (cached && cached.mtimeMs === mtimeMs) {
+        return cached.parsed;
+    }
+    const parsed = JSON.parse(fs.readFileSync(prefsPath, "utf8"));
+    _installPrefsJsonCache.set(prefsPath, { mtimeMs, parsed });
+    return parsed;
+}
 function readHookPreferences(phrenPath) {
     try {
-        const prefsPath = installPreferencesFile(phrenPath);
-        const prefs = JSON.parse(fs.readFileSync(prefsPath, "utf8"));
+        const prefs = cachedReadInstallPrefsJson(phrenPath);
+        if (!prefs)
+            return { enabled: true, toolPrefs: {} };
         const enabled = prefs.hooksEnabled !== false;
         const toolPrefs = prefs.hookTools && typeof prefs.hookTools === "object"
             ? prefs.hookTools
@@ -255,15 +273,18 @@ const HOOK_TIMEOUT_MS = parseInt(process.env.PHREN_HOOK_TIMEOUT_MS || '14000', 1
 const HOOK_ERROR_LOG_MAX_LINES = 1000;
 export function readCustomHooks(phrenPath) {
     try {
-        const prefsPath = installPreferencesFile(phrenPath);
-        const prefs = JSON.parse(fs.readFileSync(prefsPath, "utf8"));
-        if (!Array.isArray(prefs.customHooks))
+        const prefs = cachedReadInstallPrefsJson(phrenPath);
+        if (!prefs || !Array.isArray(prefs.customHooks))
             return [];
-        return prefs.customHooks.filter((h) => h &&
-            typeof h.event === "string" &&
-            VALID_HOOK_EVENTS.has(h.event) &&
-            ((typeof h.command === "string" && h.command.trim().length > 0) ||
-                (typeof h.webhook === "string" && h.webhook.trim().length > 0)));
+        return prefs.customHooks.filter((h) => {
+            if (!h || typeof h !== "object")
+                return false;
+            const rec = h;
+            return (typeof rec.event === "string" &&
+                VALID_HOOK_EVENTS.has(rec.event) &&
+                ((typeof rec.command === "string" && rec.command.trim().length > 0) ||
+                    (typeof rec.webhook === "string" && rec.webhook.trim().length > 0)));
+        });
     }
     catch (err) {
         debugLog(`readCustomHooks: ${errorMessage(err)}`);