@phren/cli 0.0.10 → 0.0.12

package/mcp/dist/entrypoint.js

@@ -5,110 +5,128 @@ 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 quickstart          Quick setup: init + project scaffold
+  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 enable <project|global> <name>  Enable a disabled skill
+  phren skills disable <project|global> <name> Disable a skill without deleting
+  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 quickstart          Quick setup: init + project scaffold
+  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 +234,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 +343,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 +380,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 +391,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 +414,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/finding-impact.js

@@ -2,19 +2,11 @@ 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";
 let highImpactCache = null;
 function nowIso() {
     return new Date().toISOString();
 }
-function normalizeFindingText(raw) {
-    return raw
-        .replace(/^-\s+/, "")
-        .replace(/<!--.*?-->/g, " ")
-        .replace(/\[confidence\s+[01](?:\.\d+)?\]/gi, " ")
-        .replace(/\s+/g, " ")
-        .trim()
-        .toLowerCase();
-}
 export function findingIdFromLine(line) {
     const fid = line.match(/<!--\s*fid:([a-z0-9]{8})\s*-->/i);
     if (fid?.[1])
@@ -144,29 +136,6 @@ export function getHighImpactFindings(phrenPath, minSurfaceCount = 3) {
     };
     return new Set(ids);
 }
-export function getImpactSurfaceCounts(phrenPath, minSurfaces = 1) {
-    const file = impactLogFile(phrenPath);
-    if (!fs.existsSync(file))
-        return new Map();
-    const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
-    const counts = new Map();
-    for (const line of lines) {
-        try {
-            const entry = JSON.parse(line);
-            if (entry.findingId) {
-                counts.set(entry.findingId, (counts.get(entry.findingId) ?? 0) + 1);
-            }
-        }
-        catch { }
-    }
-    // Filter by minimum
-    const filtered = new Map();
-    for (const [id, count] of counts) {
-        if (count >= minSurfaces)
-            filtered.set(id, count);
-    }
-    return filtered;
-}
 export function markImpactEntriesCompletedForSession(phrenPath, sessionId, project) {
     if (!sessionId)
         return 0;

package/mcp/dist/finding-journal.js

@@ -105,7 +105,7 @@ export function compactFindingJournals(phrenPath, project) {
                     result.failed += 1;
                     continue;
                 }
-                if (typeof write.data === "string" && write.data.includes("Skipped duplicate"))
+                if (write.data.status === "skipped")
                     result.skipped += 1;
                 else
                     result.added += 1;

package/mcp/dist/finding-lifecycle.js

@@ -3,9 +3,9 @@ import * as path from "path";
 import { PhrenError, phrenErr, phrenOk } from "./phren-core.js";
 // Phren lifecycle comment prefix. No backward compat.
 const LIFECYCLE_PREFIX = "phren";
-import { withFileLock } from "./governance-locks.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, } from "./content-metadata.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
@@ -101,11 +101,6 @@ function findingTextFromLine(line) {
         .replace(/<!--.*?-->/g, "")
         .trim();
 }
-function normalizeFindingText(value) {
-    return findingTextFromLine(value)
-        .replace(/\s+/g, " ")
-        .toLowerCase();
-}
 function removeRelationComments(line) {
     return stripRelationMetadata(line);
 }

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.
@@ -99,3 +100,9 @@ export function withFileLock(filePath, fn) {
     releaseFileLock(lockPath);
     return result;
 }
+export function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+export function hasValidSchemaVersion(data) {
+    return !("schemaVersion" in data) || typeof data.schemaVersion === "number";
+}

package/mcp/dist/governance-policy.js

@@ -2,8 +2,9 @@ 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 } from "./governance-locks.js";
+import { withFileLock, isFiniteNumber, hasValidSchemaVersion } from "./shared-governance.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;
@@ -43,15 +44,9 @@ function governanceDir(phrenPath) {
 function govFile(phrenPath, schema) {
     return path.join(governanceDir(phrenPath), GOVERNANCE_REGISTRY[schema].file);
 }
-function hasValidSchemaVersion(data) {
-    return !("schemaVersion" in data) || typeof data.schemaVersion === "number";
-}
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
-function isFiniteNumber(value) {
-    return typeof value === "number" && Number.isFinite(value);
-}
 function pickNumber(value, fallback) {
     return isFiniteNumber(value) ? value : fallback;
 }
@@ -212,6 +207,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 +383,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 +406,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 +421,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)