@phren/cli 0.0.1

package/mcp/dist/cli-extract.js

@@ -0,0 +1,305 @@
+import { debugLog, appendAuditLog, EXEC_TIMEOUT_MS, getPhrenPath, } from "./shared.js";
+import { appendReviewQueue, getRetentionPolicy, recordFeedback, flushEntryScores, entryScoreKey, } from "./shared-governance.js";
+import { detectProject } from "./shared-index.js";
+import { commandExists } from "./hooks.js";
+import { runGit as runGitShared, isFeatureEnabled, clampInt, errorMessage, resolveExecCommand } from "./utils.js";
+import { appendFindingJournal, compactFindingJournals } from "./finding-journal.js";
+import { getProactivityLevelForTask, getProactivityLevelForFindings, shouldAutoCaptureFindingsForLevel } from "./proactivity.js";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as crypto from "crypto";
+import { execFileSync } from "child_process";
+import { resolveRuntimeProfile } from "./runtime-profile.js";
+function runGit(cwd, args) {
+    return runGitShared(cwd, args, EXEC_TIMEOUT_MS, debugLog);
+}
+function shouldRetryGh(err) {
+    const message = err instanceof Error
+        ? err.message
+        : (typeof err === "object" && err !== null && "message" in err && typeof err.message === "string")
+            ? err.message
+            : String(err ?? "");
+    const msg = String(message);
+    return /(rate limit|secondary rate limit|timed out|ecconn|network|502|503|504|bad gateway|service unavailable)/i.test(msg);
+}
+function inferProject(arg) {
+    if (arg)
+        return arg;
+    return detectProject(getPhrenPath(), process.cwd(), resolveRuntimeProfile(getPhrenPath()));
+}
+// ── Git log parsing ──────────────────────────────────────────────────────────
+export function parseGitLogRecords(cwd, days) {
+    const fmt = "%H%x1f%s%x1f%b%x1e";
+    const raw = runGit(cwd, ["log", `--since=${days} days ago`, "--first-parent", `--pretty=format:${fmt}`]) || "";
+    const records = [];
+    for (const rec of raw.split("\x1e")) {
+        const trimmed = rec.trim();
+        if (!trimmed)
+            continue;
+        const [hash, subject, body] = trimmed.split("\x1f");
+        if (!hash || !subject)
+            continue;
+        records.push({ hash, subject, body: body || "" });
+    }
+    return records;
+}
+export async function runGhJson(cwd, args) {
+    if (!commandExists("gh"))
+        return null;
+    const retries = clampInt((process.env.PHREN_GH_RETRIES), 2, 0, 5);
+    const timeoutMs = clampInt((process.env.PHREN_GH_TIMEOUT_MS), 10000, 1000, 60000);
+    const ghExec = resolveExecCommand("gh");
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const out = execFileSync(ghExec.command, args, {
+                cwd,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                shell: ghExec.shell,
+                timeout: timeoutMs,
+                maxBuffer: 4 * 1024 * 1024,
+            }).trim();
+            if (!out)
+                return null;
+            return JSON.parse(out);
+        }
+        catch (err) {
+            if (attempt >= retries || !shouldRetryGh(err))
+                return null;
+            const backoffMs = 750 * (attempt + 1);
+            await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        }
+    }
+    return null;
+}
+export function ghCachePath(repoRoot) {
+    const absPath = path.resolve(repoRoot);
+    const repoHash = crypto.createHash("sha1").update(absPath).digest("hex").slice(0, 12);
+    const dateKey = new Date().toISOString().slice(0, 10);
+    return path.join(os.tmpdir(), `phren-gh-cache-${repoHash}-${dateKey}.json`);
+}
+const GH_CACHE_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+export async function mineGithubCandidates(repoRoot) {
+    const cacheFile = ghCachePath(repoRoot);
+    try {
+        const stat = fs.statSync(cacheFile);
+        if (Date.now() - stat.mtimeMs < GH_CACHE_MAX_AGE_MS) {
+            return JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+        }
+    }
+    catch (err) {
+        debugLog(`mineGithubCandidates: cache read failed for ${cacheFile}: ${errorMessage(err)}`);
+    }
+    const candidates = [];
+    const prLimit = clampInt((process.env.PHREN_GH_PR_LIMIT), 40, 5, 200);
+    const runLimit = clampInt((process.env.PHREN_GH_RUN_LIMIT), 25, 5, 200);
+    const issueLimit = clampInt((process.env.PHREN_GH_ISSUE_LIMIT), 25, 5, 200);
+    const prs = await runGhJson(repoRoot, [
+        "pr",
+        "list",
+        "--state",
+        "merged",
+        "--limit",
+        String(prLimit),
+        "--json",
+        "number,title,body,mergeCommit,files,comments,reviews",
+    ]) || [];
+    for (const pr of prs) {
+        const text = `PR #${pr.number}: ${pr.title}`;
+        const body = (pr.body || "").toLowerCase();
+        const commentBlob = [
+            ...(pr.comments || []).map((c) => c.body || ""),
+            ...(pr.reviews || []).map((r) => r.body || ""),
+        ].join("\n").toLowerCase();
+        let score = 0.65;
+        if (/(fix|workaround|must|avoid|regression|incident|root cause|migration)/.test(body))
+            score += 0.2;
+        if (/(review|comment|nit|requested changes)/.test(body + "\n" + commentBlob))
+            score += 0.1;
+        if (/(must|should|avoid|required|don't|do not)/.test(commentBlob))
+            score += 0.08;
+        candidates.push({
+            text,
+            score: Math.min(0.98, score),
+            commit: pr.mergeCommit?.oid,
+            file: pr.files?.find((f) => f.path)?.path,
+            sourceText: [pr.title, pr.body || "", commentBlob].filter(Boolean).join("\n"),
+        });
+    }
+    const runs = await runGhJson(repoRoot, [
+        "run",
+        "list",
+        "--status",
+        "failure",
+        "--limit",
+        String(runLimit),
+        "--json",
+        "databaseId,displayTitle,workflowName,headSha",
+    ]) || [];
+    for (const run of runs) {
+        const title = run.displayTitle || run.workflowName || "CI failure";
+        const text = `CI failure pattern: ${title}`;
+        candidates.push({
+            text,
+            score: 0.62,
+            commit: run.headSha,
+            sourceText: title,
+        });
+    }
+    const issues = await runGhJson(repoRoot, [
+        "issue",
+        "list",
+        "--state",
+        "all",
+        "--limit",
+        String(issueLimit),
+        "--json",
+        "number,title,body",
+    ]) || [];
+    for (const issue of issues) {
+        const body = (issue.body || "").toLowerCase();
+        if (!/(bug|regression|incident|outage|postmortem|fix)/.test(body) && !/(bug|regression|incident)/.test(issue.title.toLowerCase())) {
+            continue;
+        }
+        const text = `Issue #${issue.number}: ${issue.title}`;
+        candidates.push({ text, score: 0.58, sourceText: [issue.title, issue.body || ""].join("\n") });
+    }
+    try {
+        fs.writeFileSync(cacheFile, JSON.stringify(candidates));
+    }
+    catch (err) {
+        debugLog(`mineGithubCandidates: cache write failed for ${cacheFile}: ${errorMessage(err)}`);
+    }
+    return candidates;
+}
+// ── Memory candidate scoring ─────────────────────────────────────────────────
+// Reject commit-message-style subjects that lack real insight.
+// Matches patterns like "Fix typo", "Add tests", "Update README", etc.
+const COMMIT_MSG_PREFIX = /^(fix|add|update|remove|delete|rename|move|bump|revert|merge|chore|refactor|style|docs|test|ci|build|release|wip)\b/i;
+// Insight keywords that indicate the entry has learning value even if short.
+const INSIGHT_KEYWORDS = /\b(workaround|must|avoid|regression|root cause|postmortem|incident|retry|timeout|pitfall|caveat|breaking|migration|order matters|race condition|deadlock|flaky)\b/i;
+export function scoreFindingCandidate(subject, body) {
+    const s = `${subject}\n${body}`.toLowerCase();
+    // Reject short commit-message-style entries unless they contain insight keywords
+    const combined = `${subject} ${body}`.trim();
+    if (combined.length < 50 && !INSIGHT_KEYWORDS.test(combined))
+        return null;
+    if (COMMIT_MSG_PREFIX.test(subject.trim()) && !INSIGHT_KEYWORDS.test(combined))
+        return null;
+    const mergedPr = /merge pull request #\d+/.test(s);
+    const ci = /(ci|workflow|pipeline|flake|test fail|build fail)/.test(s);
+    const review = /(review|requested changes|address comments|nit|follow-up)/.test(s);
+    const learningSignal = INSIGHT_KEYWORDS.test(s);
+    let score = 0.35;
+    if (mergedPr)
+        score += 0.2;
+    if (ci)
+        score += 0.2;
+    if (review)
+        score += 0.1;
+    if (learningSignal)
+        score += 0.25;
+    if (subject.length > 20)
+        score += 0.05;
+    if (score < 0.5)
+        return null;
+    const cleaned = subject
+        .replace(/^merge pull request #\d+\s*from\s+\S+\s*/i, "")
+        .replace(/^fix:\s*/i, "")
+        .trim();
+    const text = cleaned ? cleaned[0].toUpperCase() + cleaned.slice(1) : subject;
+    return { score: Math.min(score, 0.99), text };
+}
+// ── handleExtractMemories ────────────────────────────────────────────────────
+export async function handleExtractMemories(projectArg, cwdArg, silent = false, sessionId, source = "extract") {
+    const project = inferProject(projectArg);
+    if (!project) {
+        if (!silent)
+            console.error("Usage: phren extract-memories <project>");
+        if (!silent)
+            process.exit(1);
+        return;
+    }
+    const repoRoot = runGit(cwdArg || process.cwd(), ["rev-parse", "--show-toplevel"]);
+    if (!repoRoot) {
+        if (!silent)
+            console.error("extract-memories must run from inside a git repository.");
+        if (!silent)
+            process.exit(1);
+        return;
+    }
+    const findingsLevel = getProactivityLevelForFindings(getPhrenPath());
+    const taskLevel = getProactivityLevelForTask(getPhrenPath());
+    if (taskLevel !== "high") {
+        debugLog(`extract-memories task proactivity=${taskLevel}`);
+    }
+    if (findingsLevel === "low") {
+        appendAuditLog(getPhrenPath(), "extract_memories", `project=${project} skipped=proactivity_low`);
+        if (!silent)
+            console.log(`Skipped memory extraction for ${project}: findings proactivity is low.`);
+        return;
+    }
+    const days = Number.parseInt((process.env.PHREN_MEMORY_EXTRACT_WINDOW_DAYS) || "30", 10);
+    const threshold = Number.parseFloat((process.env.PHREN_MEMORY_AUTO_ACCEPT) || String(getRetentionPolicy(getPhrenPath()).autoAcceptThreshold));
+    const records = parseGitLogRecords(repoRoot, Number.isNaN(days) ? 30 : days);
+    const ghCandidates = isFeatureEnabled("PHREN_FEATURE_GH_MINING", false)
+        ? await mineGithubCandidates(repoRoot)
+        : [];
+    let accepted = 0;
+    let queued = 0;
+    for (const rec of records) {
+        if (!shouldAutoCaptureFindingsForLevel(findingsLevel, rec.subject, rec.body))
+            continue;
+        const candidate = scoreFindingCandidate(rec.subject, rec.body);
+        if (!candidate)
+            continue;
+        const line = `${candidate.text} (source commit ${rec.hash.slice(0, 8)})`;
+        if (candidate.score >= threshold) {
+            appendFindingJournal(getPhrenPath(), project, line, {
+                source,
+                sessionId,
+                repo: repoRoot,
+                commit: rec.hash,
+            });
+            accepted++;
+        }
+        else {
+            const qr1 = appendReviewQueue(getPhrenPath(), project, "Review", [`[confidence ${candidate.score.toFixed(2)}] ${line}`]);
+            if (qr1.ok)
+                queued += qr1.data;
+        }
+    }
+    for (const c of ghCandidates) {
+        if (!shouldAutoCaptureFindingsForLevel(findingsLevel, c.sourceText ?? c.text))
+            continue;
+        const line = `${c.text}${c.commit ? ` (source commit ${c.commit.slice(0, 8)})` : ""}`;
+        if (c.text.startsWith("CI failure pattern:")) {
+            const key = entryScoreKey(project, "FINDINGS.md", line);
+            recordFeedback(getPhrenPath(), key, "regression");
+        }
+        if (c.score >= threshold) {
+            appendFindingJournal(getPhrenPath(), project, line, {
+                source,
+                sessionId,
+                repo: repoRoot,
+                commit: c.commit,
+                file: c.file,
+            });
+            accepted++;
+        }
+        else {
+            const qr2 = appendReviewQueue(getPhrenPath(), project, "Review", [`[confidence ${c.score.toFixed(2)}] ${line}`]);
+            if (qr2.ok)
+                queued += qr2.data;
+        }
+    }
+    if (!silent) {
+        const compacted = compactFindingJournals(getPhrenPath(), project);
+        debugLog(`extract-memories compacted journals for ${project}: added=${compacted.added} skipped=${compacted.skipped} failed=${compacted.failed}`);
+    }
+    flushEntryScores(getPhrenPath());
+    appendAuditLog(getPhrenPath(), "extract_memories", `project=${project} accepted=${accepted} queued=${queued} window_days=${days}`);
+    if (!silent)
+        console.log(`Extracted memory candidates for ${project}: accepted=${accepted}, queued=${queued}, window=${days}d`);
+}

package/mcp/dist/cli-govern.js

@@ -0,0 +1,371 @@
+import { appendAuditLog, qualityMarkers, getProjectDirs, getPhrenPath, } from "./shared.js";
+import { appendReviewQueue, getRetentionPolicy, consolidateProjectFindings, updateRuntimeHealth, pruneDeadMemories, } from "./shared-governance.js";
+import { filterTrustedFindingsDetailed, } from "./shared-content.js";
+import * as fs from "fs";
+import * as path from "path";
+import { handleExtractMemories } from "./cli-extract.js";
+import { errorMessage } from "./utils.js";
+import { compactFindingJournals } from "./finding-journal.js";
+import { resolveRuntimeProfile } from "./runtime-profile.js";
+// ── Shared helpers ───────────────────────────────────────────────────────────
+function targetProjects(projectArg) {
+    const profile = resolveRuntimeProfile(getPhrenPath());
+    return projectArg
+        ? [projectArg]
+        : getProjectDirs(getPhrenPath(), profile).map((p) => path.basename(p)).filter((p) => p !== "global");
+}
+function parseProjectDryRunArgs(args, command, usage) {
+    let projectArg;
+    let dryRun = false;
+    for (const arg of args) {
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            console.error(`Unknown ${command} flag: ${arg}`);
+            console.error(usage);
+            process.exit(1);
+        }
+        if (projectArg) {
+            console.error(`Usage: ${usage}`);
+            process.exit(1);
+        }
+        projectArg = arg;
+    }
+    return { projectArg, dryRun };
+}
+function captureFindingBackups(projects) {
+    const snapshots = new Map();
+    for (const project of projects) {
+        const backup = path.join(getPhrenPath(), project, "FINDINGS.md.bak");
+        if (!fs.existsSync(backup))
+            continue;
+        snapshots.set(backup, fs.statSync(backup).mtimeMs);
+    }
+    return snapshots;
+}
+function summarizeBackupChanges(before, projects) {
+    const changed = [];
+    for (const project of projects) {
+        const backup = path.join(getPhrenPath(), project, "FINDINGS.md.bak");
+        if (!fs.existsSync(backup))
+            continue;
+        const current = fs.statSync(backup).mtimeMs;
+        const previous = before.get(backup);
+        if (previous === undefined || current !== previous) {
+            // Normalize to forward slashes for consistent output across platforms
+            changed.push(path.relative(getPhrenPath(), backup).replace(/\\/g, "/"));
+        }
+    }
+    return changed.sort();
+}
+export async function handleGovernMemories(projectArg, silent = false, dryRun = false) {
+    const profile = resolveRuntimeProfile(getPhrenPath());
+    const policy = getRetentionPolicy(getPhrenPath());
+    const ttlDays = Number.parseInt((process.env.PHREN_MEMORY_TTL_DAYS) || String(policy.ttlDays), 10);
+    const projects = projectArg
+        ? [projectArg]
+        : getProjectDirs(getPhrenPath(), profile).map((p) => path.basename(p)).filter((p) => p !== "global");
+    let staleCount = 0;
+    let conflictCount = 0;
+    let reviewCount = 0;
+    for (const project of projects) {
+        const learningsPath = path.join(getPhrenPath(), project, "FINDINGS.md");
+        if (!fs.existsSync(learningsPath))
+            continue;
+        const content = fs.readFileSync(learningsPath, "utf8");
+        const trust = filterTrustedFindingsDetailed(content, {
+            ttlDays: Number.isNaN(ttlDays) ? policy.ttlDays : ttlDays,
+            minConfidence: policy.minInjectConfidence,
+            decay: policy.decay,
+        });
+        const stale = trust.issues.filter((i) => i.reason === "stale").map((i) => i.bullet);
+        const conflicts = trust.issues.filter((i) => i.reason === "invalid_citation").map((i) => i.bullet);
+        staleCount += stale.length;
+        conflictCount += conflicts.length;
+        const lowValue = content.split("\n")
+            .filter((l) => l.startsWith("- "))
+            .filter((l) => /(fixed stuff|updated things|misc|temp|wip|quick note)/i.test(l) || l.length < 16);
+        reviewCount += lowValue.length;
+        if (!dryRun) {
+            appendReviewQueue(getPhrenPath(), project, "Stale", stale);
+            appendReviewQueue(getPhrenPath(), project, "Conflicts", conflicts);
+            appendReviewQueue(getPhrenPath(), project, "Review", lowValue);
+        }
+    }
+    if (!dryRun) {
+        appendAuditLog(getPhrenPath(), "govern_memories", `projects=${projects.length} stale=${staleCount} conflicts=${conflictCount} review=${reviewCount}`);
+        for (const project of projects) {
+            consolidateProjectFindings(getPhrenPath(), project);
+        }
+    }
+    if (!silent) {
+        const prefix = dryRun ? "[dry-run] Would govern" : "Governed";
+        console.log(`${prefix} memories: stale=${staleCount}, conflicts=${conflictCount}, review=${reviewCount}`);
+    }
+    return {
+        projects: projects.length,
+        staleCount,
+        conflictCount,
+        reviewCount,
+    };
+}
+export async function handlePruneMemories(args = []) {
+    const usage = "phren prune-memories [project] [--dry-run]";
+    const { projectArg, dryRun } = parseProjectDryRunArgs(args, "prune-memories", usage);
+    const projects = targetProjects(projectArg);
+    const beforeBackups = dryRun ? new Map() : captureFindingBackups(projects);
+    const result = pruneDeadMemories(getPhrenPath(), projectArg, dryRun);
+    if (!result.ok) {
+        console.log(result.error);
+        return;
+    }
+    console.log(result.data);
+    // TTL enforcement: move entries older than ttlDays that haven't been retrieved recently
+    const policy = getRetentionPolicy(getPhrenPath());
+    const ttlDays = policy.ttlDays;
+    const retrievalGraceDays = Math.floor(ttlDays / 2);
+    const now = Date.now();
+    // Load retrieval log once for all projects
+    const retrievalLogPath = path.join(getPhrenPath(), ".runtime", "retrieval-log.jsonl");
+    let retrievalEntries = [];
+    if (fs.existsSync(retrievalLogPath)) {
+        try {
+            retrievalEntries = fs.readFileSync(retrievalLogPath, "utf8")
+                .split("\n")
+                .filter(Boolean)
+                .map(line => { try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            } }) // null filtered below
+                .filter((e) => e !== null);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] cli-govern retrievalLog readParse: ${errorMessage(err)}\n`);
+        }
+    }
+    // Build map of last retrieval date by file+bullet key
+    const lastRetrievalByKey = new Map();
+    for (const entry of retrievalEntries) {
+        const key = `${entry.file}:${entry.section}`;
+        const ts = Date.parse(entry.retrievedAt);
+        if (!Number.isNaN(ts)) {
+            const existing = lastRetrievalByKey.get(key) || 0;
+            if (ts > existing)
+                lastRetrievalByKey.set(key, ts);
+        }
+    }
+    let ttlExpired = 0;
+    for (const project of projects) {
+        const learningsPath = path.join(getPhrenPath(), project, "FINDINGS.md");
+        if (!fs.existsSync(learningsPath))
+            continue;
+        const content = fs.readFileSync(learningsPath, "utf8");
+        const lines = content.split("\n");
+        const expiredEntries = [];
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // Look for entries with <!-- created: YYYY-MM-DD --> timestamps
+            if (!line.startsWith("- "))
+                continue;
+            const createdMatch = line.match(/<!--\s*created:\s*(\d{4}-\d{2}-\d{2})\s*-->/);
+            if (!createdMatch)
+                continue; // No timestamp, skip defensively
+            const createdDate = createdMatch[1];
+            const createdMs = Date.parse(`${createdDate}T00:00:00Z`);
+            if (Number.isNaN(createdMs))
+                continue;
+            const ageDays = Math.floor((now - createdMs) / 86400000);
+            if (ageDays <= ttlDays)
+                continue;
+            // Check if retrieved within the grace period.
+            // Retrieval is logged at document level (project/FINDINGS.md + doc.type), so look up
+            // by the document-level key to match the format written by cli-hooks-output recordRetrieval.
+            const retrievalKey = `${project}/FINDINGS.md:findings`;
+            const lastRetrieval = lastRetrievalByKey.get(retrievalKey) || 0;
+            const daysSinceRetrieval = lastRetrieval ? Math.floor((now - lastRetrieval) / 86400000) : Infinity;
+            if (daysSinceRetrieval <= retrievalGraceDays)
+                continue;
+            expiredEntries.push(`[ttl-expired: ${createdDate}] ${line.slice(2).trim()}`);
+            ttlExpired++;
+        }
+        if (expiredEntries.length > 0 && !dryRun) {
+            appendReviewQueue(getPhrenPath(), project, "Stale", expiredEntries);
+        }
+        if (expiredEntries.length > 0 && dryRun) {
+            for (const entry of expiredEntries) {
+                console.log(`[dry-run] [${project}] Would move to MEMORY_QUEUE: ${entry.slice(0, 120)}`);
+            }
+        }
+    }
+    if (ttlExpired > 0) {
+        const verb = dryRun ? "Would move" : "Moved";
+        console.log(`${verb} ${ttlExpired} TTL-expired entr${ttlExpired === 1 ? "y" : "ies"} to MEMORY_QUEUE.md`);
+    }
+    if (dryRun)
+        return;
+    const backups = summarizeBackupChanges(beforeBackups, projects);
+    if (!backups.length)
+        return;
+    console.log(`Updated backups (${backups.length}): ${backups.join(", ")}`);
+}
+export async function handleConsolidateMemories(args = []) {
+    const usage = "phren consolidate-memories [project] [--dry-run]";
+    const { projectArg, dryRun } = parseProjectDryRunArgs(args, "consolidate-memories", usage);
+    const projects = targetProjects(projectArg);
+    const beforeBackups = dryRun ? new Map() : captureFindingBackups(projects);
+    const results = projects.map((p) => consolidateProjectFindings(getPhrenPath(), p, dryRun));
+    console.log(results.map((r) => r.ok ? r.data : r.error).join("\n"));
+    if (dryRun)
+        return;
+    const backups = summarizeBackupChanges(beforeBackups, projects);
+    if (!backups.length)
+        return;
+    console.log(`Updated backups (${backups.length}): ${backups.join(", ")}`);
+}
+// ── Maintain router ──────────────────────────────────────────────────────────
+export async function handleMaintain(args) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case "govern": {
+            const governDryRun = rest.includes("--dry-run");
+            const governProject = rest.find((a) => !a.startsWith("-"));
+            return handleGovernMemories(governProject, false, governDryRun);
+        }
+        case "prune":
+            return handlePruneMemories(rest);
+        case "consolidate":
+            return handleConsolidateMemories(rest);
+        case "extract":
+            return handleExtractMemories(rest[0]);
+        case "restore":
+            return handleRestoreBackup(rest);
+        default:
+            console.log(`phren maintain - memory maintenance and governance
+
+Subcommands:
+  phren maintain govern [project] [--dry-run]
+                                         Queue stale/conflicting/low-value memories for review.
+                                         Run when search results feel noisy or after a long break.
+  phren maintain prune [project] [--dry-run]
+                                         Delete expired entries by retention policy
+  phren maintain consolidate [project] [--dry-run]
+                                         Deduplicate FINDINGS.md bullets. Run after a burst of work
+                                         when findings feel repetitive, or monthly to keep things clean.
+  phren maintain extract [project]      Mine git/GitHub signals into memory candidates
+  phren maintain restore [project]      List and restore from .bak files`);
+            if (sub) {
+                console.error(`\nUnknown maintain subcommand: "${sub}"`);
+                process.exit(1);
+            }
+    }
+}
+// ── Restore from backup ──────────────────────────────────────────────────────
+function findBackups(projects) {
+    const results = [];
+    const now = Date.now();
+    for (const project of projects) {
+        const dir = path.join(getPhrenPath(), project);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const f of fs.readdirSync(dir)) {
+            if (!f.endsWith(".bak"))
+                continue;
+            const fullPath = path.join(dir, f);
+            const stat = fs.statSync(fullPath);
+            const ageMs = now - stat.mtimeMs;
+            const ageHours = Math.floor(ageMs / 3600000);
+            const age = ageHours < 24 ? `${ageHours}h ago` : `${Math.floor(ageHours / 24)}d ago`;
+            results.push({ project, file: f, fullPath, age });
+        }
+    }
+    return results.sort((a, b) => a.project.localeCompare(b.project) || a.file.localeCompare(b.file));
+}
+async function handleRestoreBackup(args) {
+    const projectArg = args.find((a) => !a.startsWith("-"));
+    const projects = targetProjects(projectArg);
+    const backups = findBackups(projects);
+    if (!backups.length) {
+        console.log("No backup files found.");
+        return;
+    }
+    if (args.includes("--list") || !args.includes("--apply")) {
+        console.log("Available backups:");
+        for (const b of backups) {
+            console.log(`  ${b.project}/${b.file}  (${b.age})`);
+        }
+        console.log("\nTo restore, run: phren maintain restore <project> --apply");
+        return;
+    }
+    if (!projectArg) {
+        console.error("Specify a project to restore: phren maintain restore <project> --apply");
+        process.exit(1);
+    }
+    const projectBackups = backups.filter((b) => b.project === projectArg);
+    if (!projectBackups.length) {
+        console.log(`No backup files found for "${projectArg}".`);
+        return;
+    }
+    for (const b of projectBackups) {
+        const target = b.fullPath.replace(/\.bak$/, "");
+        fs.copyFileSync(b.fullPath, target);
+        console.log(`Restored ${b.project}/${b.file.replace(/\.bak$/, "")} from backup`);
+    }
+    appendAuditLog(getPhrenPath(), "restore_backup", `project=${projectArg} files=${projectBackups.length}`);
+}
+// ── Background maintenance ───────────────────────────────────────────────────
+export async function handleBackgroundMaintenance(projectArg) {
+    const markers = qualityMarkers(getPhrenPath());
+    const startedAt = new Date().toISOString();
+    try {
+        const compacted = compactFindingJournals(getPhrenPath(), projectArg);
+        const governance = await handleGovernMemories(projectArg, true);
+        const pruneResult = pruneDeadMemories(getPhrenPath(), projectArg);
+        const pruneMsg = pruneResult.ok ? pruneResult.data : pruneResult.error;
+        if (!pruneResult.ok) {
+            updateRuntimeHealth(getPhrenPath(), {
+                lastGovernance: {
+                    at: startedAt,
+                    status: "error",
+                    detail: `prune failed: ${pruneMsg}`,
+                },
+            });
+            appendAuditLog(getPhrenPath(), "background_maintenance_failed", `error=prune_failed: ${pruneMsg}`);
+            return;
+        }
+        fs.writeFileSync(markers.done, new Date().toISOString() + "\n");
+        updateRuntimeHealth(getPhrenPath(), {
+            lastGovernance: {
+                at: startedAt,
+                status: "ok",
+                detail: `journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed}; projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}; ${pruneMsg}`,
+            },
+        });
+        appendAuditLog(getPhrenPath(), "background_maintenance", `status=ok journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed} projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}`);
+    }
+    catch (err) {
+        const errMsg = errorMessage(err);
+        updateRuntimeHealth(getPhrenPath(), {
+            lastGovernance: {
+                at: startedAt,
+                status: "error",
+                detail: errMsg,
+            },
+        });
+        appendAuditLog(getPhrenPath(), "background_maintenance_failed", `error=${errMsg}`);
+    }
+    finally {
+        try {
+            fs.unlinkSync(markers.lock);
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] cli-govern backgroundMaintenance unlockFinal: ${errorMessage(err)}\n`);
+        }
+    }
+}