@phren/cli 0.0.1

package/mcp/dist/content-learning.js

@@ -0,0 +1,472 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { debugLog, appendAuditLog, phrenOk, phrenErr, PhrenError } from "./shared.js";
+import { normalizeMemoryScope } from "./shared.js";
+import { withFileLock } from "./shared-governance.js";
+import { isValidProjectName, safeProjectPath } from "./utils.js";
+import { getMachineName } from "./machine-identity.js";
+import { buildCitationComment, buildSourceComment, getHeadCommit, getRepoRoot, inferCitationLocation, isFindingProvenanceSource, } from "./content-citation.js";
+import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCoref, detectConflicts, extractDynamicEntities } from "./content-dedup.js";
+import { validateFindingsFormat, validateFinding } from "./content-validate.js";
+import { countActiveFindings, autoArchiveToReference } from "./content-archive.js";
+import { resolveAutoFindingTaskItem, resolveFindingTaskReference, resolveFindingSessionId, } from "./finding-context.js";
+import { buildLifecycleComments, parseFindingLifecycle, stripLifecycleComments, } from "./finding-lifecycle.js";
+import { METADATA_REGEX, } from "./content-metadata.js";
+/** Default cap for active findings before auto-archiving is triggered. */
+const DEFAULT_FINDINGS_CAP = 20;
+const LIFECYCLE_ANNOTATION_RE = METADATA_REGEX.lifecycleAnnotation;
+function buildFindingCitation(citationInput, nowIso, inferredRepo, headCommit) {
+    const citation = {
+        created_at: nowIso ?? new Date().toISOString(),
+        repo: citationInput?.repo || inferredRepo,
+        file: citationInput?.file,
+        line: citationInput?.line,
+        commit: citationInput?.commit || (citationInput?.repo || inferredRepo ? headCommit ?? getHeadCommit(citationInput?.repo || inferredRepo || "") : undefined),
+        supersedes: citationInput?.supersedes,
+        task_item: citationInput?.task_item,
+    };
+    if (citation.repo && citation.commit && (!citation.file || !citation.line)) {
+        const inferred = inferCitationLocation(citation.repo, citation.commit);
+        citation.file = citation.file || inferred.file;
+        citation.line = citation.line || inferred.line;
+    }
+    return citation;
+}
+function resolveInferredCitationRepo(citationInput) {
+    if (citationInput?.repo)
+        return citationInput.repo;
+    if (citationInput?.file) {
+        const fileDir = path.dirname(citationInput.file);
+        return getRepoRoot(fileDir);
+    }
+    return undefined;
+}
+function detectFindingModel() {
+    const candidates = [
+        (process.env.PHREN_MODEL),
+        process.env.OPENAI_MODEL,
+        process.env.CLAUDE_MODEL,
+        (process.env.PHREN_LLM_MODEL),
+        process.env.MODEL,
+    ];
+    return candidates.find((value) => typeof value === "string" && value.trim())?.trim();
+}
+function detectFindingTool() {
+    const candidates = [
+        (process.env.PHREN_TOOL),
+        (process.env.PHREN_HOOK_TOOL),
+    ];
+    return candidates.find((value) => typeof value === "string" && value.trim())?.trim();
+}
+function detectFindingProvenanceSource(explicitSource) {
+    if (explicitSource)
+        return explicitSource;
+    const envSource = (process.env.PHREN_FINDING_SOURCE)?.trim().toLowerCase();
+    if (isFindingProvenanceSource(envSource))
+        return envSource;
+    if ((process.env.PHREN_CONSOLIDATION) === "1")
+        return "consolidation";
+    if ((process.env.PHREN_AUTO_EXTRACT) === "1")
+        return "extract";
+    if ((process.env.PHREN_HOOK_TOOL))
+        return "hook";
+    if ((process.env.PHREN_ACTOR || process.env.PHREN_ACTOR)?.trim())
+        return "agent";
+    return "human";
+}
+function buildFindingSource(sessionId, explicitSource, scope) {
+    const actor = (process.env.PHREN_ACTOR || process.env.PHREN_ACTOR)?.trim() || undefined;
+    const source = {
+        source: detectFindingProvenanceSource(explicitSource),
+        machine: getMachineName(),
+        actor,
+        tool: detectFindingTool(),
+        model: detectFindingModel(),
+        session_id: sessionId,
+        scope: normalizeMemoryScope(scope),
+    };
+    return source;
+}
+function resolveFindingCitationInput(phrenPath, project, citationInput) {
+    const resolved = citationInput ? { ...citationInput } : {};
+    if (citationInput?.task_item) {
+        const taskResolution = resolveFindingTaskReference(phrenPath, project, citationInput.task_item);
+        if (taskResolution.error) {
+            return phrenErr(taskResolution.error, PhrenError.VALIDATION_ERROR);
+        }
+        if (taskResolution.stableId) {
+            resolved.task_item = taskResolution.stableId;
+        }
+    }
+    else {
+        const taskItem = resolveAutoFindingTaskItem(phrenPath, project);
+        if (taskItem) {
+            resolved.task_item = taskItem;
+        }
+    }
+    return phrenOk(Object.keys(resolved).length > 0 ? resolved : undefined);
+}
+function prepareFinding(learning, project, fullHistory, extraAnnotations, citationInput, source, nowIso, inferredRepo, headCommit, phrenPath) {
+    const secretType = scanForSecrets(learning);
+    if (secretType) {
+        return { status: "rejected", reason: `Contains ${secretType}` };
+    }
+    const today = (nowIso ?? new Date().toISOString()).slice(0, 10);
+    const { text: tagNormalized, warning: tagWarning } = normalizeObservationTags(learning);
+    const normalizedLearning = resolveCoref(tagNormalized, {
+        project,
+        file: citationInput?.file,
+    });
+    const fid = crypto.randomBytes(4).toString("hex");
+    const fidComment = `<!-- fid:${fid} -->`;
+    const createdComment = `<!-- created: ${today} -->`;
+    const sourceComment = source ? buildSourceComment(source) : "";
+    let lifecycle = { status: "active", status_updated: today };
+    let bullet = `${normalizedLearning.startsWith("- ") ? normalizedLearning : `- ${normalizedLearning}`} ${fidComment} ${createdComment}`;
+    if (sourceComment)
+        bullet += ` ${sourceComment}`;
+    if (isDuplicateFinding(fullHistory, bullet)) {
+        return { status: "duplicate" };
+    }
+    const existingBullets = fullHistory.split("\n").filter((l) => l.startsWith("- "));
+    const dynamicEntities = phrenPath ? extractDynamicEntities(phrenPath, project) : undefined;
+    const conflicts = detectConflicts(normalizedLearning, existingBullets, dynamicEntities);
+    if (conflicts.length > 0) {
+        const snippet = conflicts[0].replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().slice(0, 80);
+        lifecycle = {
+            status: "contradicted",
+            status_updated: today,
+            status_reason: "conflicts_with",
+            status_ref: snippet,
+        };
+        bullet += ` <!-- conflicts_with: "${snippet}" --> <!-- phren:contradicts "${snippet}" -->`;
+        debugLog(`add_finding: conflict detected for "${project}": ${snippet}`);
+    }
+    if (extraAnnotations && extraAnnotations.length > 0) {
+        const lifecycleFromExtra = parseFindingLifecycle(`- lifecycle ${extraAnnotations.join(" ")}`);
+        if (lifecycleFromExtra.status !== "active" ||
+            lifecycleFromExtra.status_reason ||
+            lifecycleFromExtra.status_ref ||
+            lifecycleFromExtra.status_updated) {
+            lifecycle = {
+                ...lifecycle,
+                ...lifecycleFromExtra,
+                status_updated: lifecycleFromExtra.status_updated ?? lifecycle.status_updated ?? today,
+            };
+        }
+        const existing = new Set([...bullet.matchAll(METADATA_REGEX.conflictsWithAll)].map((m) => m[0]));
+        for (const annotation of extraAnnotations) {
+            if (!annotation.startsWith("<!--"))
+                continue;
+            if (LIFECYCLE_ANNOTATION_RE.test(annotation))
+                continue;
+            if (existing.has(annotation))
+                continue;
+            bullet += ` ${annotation}`;
+            existing.add(annotation);
+        }
+    }
+    bullet += ` ${buildLifecycleComments(lifecycle, today)}`;
+    const citation = buildFindingCitation(citationInput, nowIso, inferredRepo, headCommit);
+    return {
+        status: "added",
+        finding: {
+            original: learning,
+            normalized: normalizedLearning,
+            bullet,
+            citationComment: `  ${buildCitationComment(citation)}`,
+            tagWarning,
+        },
+    };
+}
+function insertFindingIntoContent(content, today, bullet, citationComment) {
+    const todayHeader = `## ${today}`;
+    // Use positional insertion (not String.replace) to avoid: (1) special $& replacement patterns
+    // if bullet contains $ chars, and (2) inserting inside an archived <details> block when a
+    // duplicate date header exists from a prior consolidation run.
+    const idx = content.indexOf(todayHeader);
+    if (idx !== -1) {
+        const insertAt = idx + todayHeader.length;
+        return content.slice(0, insertAt) + `\n\n${bullet}\n${citationComment}` + content.slice(insertAt);
+    }
+    const firstHeadingMatch = content.match(/^## \d{4}-\d{2}-\d{2}/m);
+    if (firstHeadingMatch?.index != null) {
+        return (content.slice(0, firstHeadingMatch.index) +
+            `${todayHeader}\n\n${bullet}\n${citationComment}\n\n` +
+            content.slice(firstHeadingMatch.index));
+    }
+    return content.trimEnd() + `\n\n## ${today}\n\n${bullet}\n${citationComment}\n`;
+}
+export function upsertCanonical(phrenPath, project, memory) {
+    if (!isValidProjectName(project))
+        return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
+    const resolvedDir = safeProjectPath(phrenPath, project);
+    if (!resolvedDir || !fs.existsSync(resolvedDir))
+        return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
+    const canonicalPath = path.join(resolvedDir, "CANONICAL_MEMORIES.md");
+    const today = new Date().toISOString().slice(0, 10);
+    const bullet = memory.startsWith("- ") ? memory : `- ${memory}`;
+    withFileLock(canonicalPath, () => {
+        if (!fs.existsSync(canonicalPath)) {
+            fs.writeFileSync(canonicalPath, `# ${project} Canonical Memories\n\n## Pinned\n\n${bullet} _(pinned ${today})_\n`);
+        }
+        else {
+            const existing = fs.readFileSync(canonicalPath, "utf8");
+            const line = `${bullet} _(pinned ${today})_`;
+            if (!existing.includes(bullet)) {
+                const updated = existing.includes("## Pinned")
+                    ? existing.replace("## Pinned", `## Pinned\n\n${line}`)
+                    : `${existing.trimEnd()}\n\n## Pinned\n\n${line}\n`;
+                const content = updated.endsWith("\n") ? updated : updated + "\n";
+                const tmpPath = canonicalPath + `.tmp-${crypto.randomUUID()}`;
+                fs.writeFileSync(tmpPath, content);
+                fs.renameSync(tmpPath, canonicalPath);
+            }
+        }
+    });
+    appendAuditLog(phrenPath, "pin_memory", `project=${project} memory=${JSON.stringify(memory)}`);
+    return phrenOk(`Pinned canonical memory in ${project}.`);
+}
+export function addFindingToFile(phrenPath, project, learning, citationInput, opts) {
+    const findingError = validateFinding(learning);
+    if (findingError)
+        return phrenErr(findingError, PhrenError.EMPTY_INPUT);
+    if (!isValidProjectName(project))
+        return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
+    const resolvedDir = safeProjectPath(phrenPath, project);
+    if (!resolvedDir)
+        return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
+    const learningsPath = path.join(resolvedDir, "FINDINGS.md");
+    // Secret/PII scan — reject before anything else (before existence check, before lock)
+    const nowIso = new Date().toISOString();
+    const today = nowIso.slice(0, 10);
+    const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project, citationInput);
+    if (!resolvedCitationInputResult.ok)
+        return resolvedCitationInputResult;
+    const resolvedCitationInput = resolvedCitationInputResult.data;
+    const effectiveSessionId = resolveFindingSessionId(phrenPath, project, opts?.sessionId);
+    const source = buildFindingSource(effectiveSessionId, opts?.source, opts?.scope);
+    const inferredRepo = resolveInferredCitationRepo(resolvedCitationInput);
+    const headCommit = inferredRepo ? getHeadCommit(inferredRepo) : undefined;
+    const supersedesText = resolvedCitationInput?.supersedes;
+    const normalizedForSupersedes = supersedesText
+        ? resolveCoref(normalizeObservationTags(learning).text, {
+            project,
+            file: resolvedCitationInput?.file,
+        })
+        : undefined;
+    // Reject secrets before anything else — even if project doesn't exist yet
+    const earlySecretType = scanForSecrets(learning);
+    if (earlySecretType) {
+        return phrenErr(`Rejected: finding appears to contain a secret (${earlySecretType}). Strip credentials before saving.`, PhrenError.VALIDATION_ERROR);
+    }
+    // Check project dir existence before withFileLock (which would create the dir via mkdirSync)
+    if (!fs.existsSync(resolvedDir))
+        return phrenErr(`Project "${project}" does not exist.`, PhrenError.INVALID_PROJECT_NAME);
+    const result = withFileLock(learningsPath, () => {
+        const preparedForNewFile = prepareFinding(learning, project, "", opts?.extraAnnotations, resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath);
+        if (!fs.existsSync(learningsPath)) {
+            if (preparedForNewFile.status === "rejected") {
+                return phrenErr(`Rejected: finding appears to contain a secret (${preparedForNewFile.reason.replace(/^Contains /, "")}). Strip credentials before saving.`, PhrenError.VALIDATION_ERROR);
+            }
+            if (preparedForNewFile.status === "duplicate") {
+                return phrenOk(`Skipped duplicate finding for "${project}": already exists with similar wording.`);
+            }
+            const newContent = `# ${project} Findings\n\n## ${today}\n\n${preparedForNewFile.finding.bullet}\n${preparedForNewFile.finding.citationComment}\n`;
+            fs.writeFileSync(learningsPath, newContent);
+            return phrenOk({
+                content: newContent,
+                citation: buildFindingCitation(resolvedCitationInput, nowIso, inferredRepo, headCommit),
+                tagWarning: preparedForNewFile.finding.tagWarning,
+                created: true,
+                bullet: preparedForNewFile.finding.bullet,
+            });
+        }
+        const content = fs.readFileSync(learningsPath, "utf8");
+        // When superseding, strip the old finding from history so dedup doesn't block the intentionally similar replacement.
+        // Skip the strip if new finding is identical to the superseded one (self-supersession should still be blocked by dedup).
+        const isSelfSupersession = supersedesText &&
+            learning.trim().toLowerCase().slice(0, 60) === supersedesText.trim().toLowerCase().slice(0, 60);
+        const historyForDedup = (supersedesText && !isSelfSupersession)
+            ? content.split("\n")
+                .filter(line => !line.startsWith("- ") || !line.toLowerCase().includes(supersedesText.slice(0, 40).toLowerCase()))
+                .join("\n")
+            : content;
+        const prepared = prepareFinding(learning, project, historyForDedup, opts?.extraAnnotations, resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath);
+        if (prepared.status === "rejected") {
+            return phrenErr(`Rejected: finding appears to contain a secret (${prepared.reason.replace(/^Contains /, "")}). Strip credentials before saving.`, PhrenError.VALIDATION_ERROR);
+        }
+        if (prepared.status === "duplicate") {
+            debugLog(`add_finding: skipped duplicate for "${project}": ${learning.slice(0, 80)}`);
+            return phrenOk(`Skipped duplicate finding for "${project}": already exists with similar wording.`);
+        }
+        const issues = validateFindingsFormat(content);
+        if (issues.length > 0) {
+            debugLog(`FINDINGS.md format warnings for "${project}": ${issues.join("; ")}`);
+        }
+        let updated = insertFindingIntoContent(content, today, prepared.finding.bullet, prepared.finding.citationComment);
+        if (supersedesText && normalizedForSupersedes) {
+            const lines = updated.split("\n");
+            const needle = supersedesText.slice(0, 60).toLowerCase().replace(/\s+/g, " ").trim();
+            for (let i = 0; i < lines.length; i++) {
+                if (!lines[i].startsWith("- "))
+                    continue;
+                const lineText = lines[i].replace(/<!--.*?-->/g, "").replace(/^-\s+/, "").replace(/^\[[^\]]+\]\s+/, "").slice(0, 60).toLowerCase().replace(/\s+/g, " ").trim();
+                if (lineText === needle) {
+                    // Remove any legacy and normalized lifecycle supersession metadata before re-appending.
+                    lines[i] = lines[i].replace(METADATA_REGEX.stripSupersededByLegacy, "");
+                    lines[i] = lines[i].replace(METADATA_REGEX.stripSupersededBy, "");
+                    lines[i] = stripLifecycleComments(lines[i]);
+                    const newFirst60 = normalizedForSupersedes.replace(/^-\s+/, "").slice(0, 60);
+                    lines[i] =
+                        `${lines[i]} <!-- phren:superseded_by "${newFirst60}" ${today} --> ` +
+                            `${buildLifecycleComments({ status: "superseded", status_updated: today, status_reason: "superseded_by", status_ref: newFirst60 }, today)}`;
+                    updated = lines.join("\n");
+                    break;
+                }
+            }
+            // Also annotate the new finding bullet with phren:supersedes
+            const newLines = updated.split("\n");
+            for (let i = 0; i < newLines.length; i++) {
+                if (!newLines[i].startsWith("- "))
+                    continue;
+                if (newLines[i].includes(prepared.finding.bullet.slice(0, 40))) {
+                    if (!newLines[i].includes("phren:supersedes") && !newLines[i].includes("phren:supersedes")) {
+                        const supersedesFirst60 = supersedesText.slice(0, 60);
+                        newLines[i] = `${newLines[i]} <!-- phren:supersedes "${supersedesFirst60}" -->`;
+                    }
+                    updated = newLines.join("\n");
+                    break;
+                }
+            }
+        }
+        const tmpPath = learningsPath + `.tmp-${crypto.randomUUID()}`;
+        fs.writeFileSync(tmpPath, updated);
+        fs.renameSync(tmpPath, learningsPath);
+        return phrenOk({
+            content: updated,
+            citation: buildFindingCitation(resolvedCitationInput, nowIso, inferredRepo, headCommit),
+            tagWarning: prepared.finding.tagWarning,
+            created: false,
+            bullet: prepared.finding.bullet,
+        });
+    });
+    if (!result.ok)
+        return result;
+    if (typeof result.data === "string")
+        return phrenOk(result.data);
+    appendAuditLog(phrenPath, "add_finding", `project=${project}${result.data.created ? " created=true" : ""} citation_commit=${result.data.citation.commit ?? "none"} citation_file=${result.data.citation.file ?? "none"}`);
+    const cap = Number.parseInt((process.env.PHREN_FINDINGS_CAP) || "", 10) || DEFAULT_FINDINGS_CAP;
+    const activeCount = countActiveFindings(result.data.content);
+    if (activeCount > cap) {
+        const archiveResult = autoArchiveToReference(phrenPath, project, cap);
+        if (archiveResult.ok && archiveResult.data > 0) {
+            debugLog(`Size cap: archived ${archiveResult.data} oldest entries for "${project}" (cap=${cap})`);
+        }
+    }
+    if (result.data.created) {
+        const createdMsg = `Created FINDINGS.md for "${project}" and added insight.`;
+        return phrenOk(result.data.tagWarning ? `${createdMsg} Warning: ${result.data.tagWarning}` : createdMsg);
+    }
+    const addedMsg = `Added finding to ${project}: ${result.data.bullet} (with citation metadata)`;
+    return phrenOk(result.data.tagWarning ? `${addedMsg} Warning: ${result.data.tagWarning}` : addedMsg);
+}
+export function addFindingsToFile(phrenPath, project, learnings, opts) {
+    if (!isValidProjectName(project))
+        return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
+    const resolvedDir = safeProjectPath(phrenPath, project);
+    if (!resolvedDir)
+        return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
+    const learningsPath = path.join(resolvedDir, "FINDINGS.md");
+    const today = new Date().toISOString().slice(0, 10);
+    const nowIso = new Date().toISOString();
+    const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project);
+    if (!resolvedCitationInputResult.ok)
+        return resolvedCitationInputResult;
+    const resolvedCitationInput = resolvedCitationInputResult.data;
+    const effectiveSessionId = resolveFindingSessionId(phrenPath, project, opts?.sessionId);
+    const source = buildFindingSource(effectiveSessionId, opts?.source, opts?.scope);
+    const inferredRepo = resolveInferredCitationRepo(resolvedCitationInput);
+    const headCommit = inferredRepo ? getHeadCommit(inferredRepo) : undefined;
+    const added = [];
+    const skipped = [];
+    const rejected = [];
+    // Check project dir existence before withFileLock (which would create the dir via mkdirSync)
+    if (!fs.existsSync(resolvedDir))
+        return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
+    const contentResult = withFileLock(learningsPath, () => {
+        if (!fs.existsSync(learningsPath)) {
+            let content = `# ${project} Findings\n\n## ${today}\n`;
+            for (const [index, learning] of learnings.entries()) {
+                const extraAnnotations = opts?.extraAnnotationsByFinding?.[index];
+                const lengthError = validateFinding(learning);
+                if (lengthError) {
+                    rejected.push({ text: learning, reason: lengthError });
+                    continue;
+                }
+                const prepared = prepareFinding(learning, project, content, extraAnnotations, resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath);
+                if (prepared.status === "rejected") {
+                    rejected.push({ text: learning, reason: prepared.reason });
+                    continue;
+                }
+                if (prepared.status === "duplicate") {
+                    skipped.push(learning);
+                    continue;
+                }
+                content = insertFindingIntoContent(content, today, prepared.finding.bullet, prepared.finding.citationComment);
+                if (prepared.finding.tagWarning)
+                    debugLog(`add_findings: ${prepared.finding.tagWarning}`);
+                added.push(learning);
+            }
+            if (added.length > 0) {
+                fs.writeFileSync(learningsPath, content.endsWith("\n") ? content : `${content}\n`);
+            }
+            return phrenOk({ content, wrote: added.length > 0 });
+        }
+        let content = fs.readFileSync(learningsPath, "utf8");
+        const issues = validateFindingsFormat(content);
+        if (issues.length > 0)
+            debugLog(`FINDINGS.md format warnings for "${project}": ${issues.join("; ")}`);
+        for (const [index, learning] of learnings.entries()) {
+            const extraAnnotations = opts?.extraAnnotationsByFinding?.[index];
+            const lengthError = validateFinding(learning);
+            if (lengthError) {
+                rejected.push({ text: learning, reason: lengthError });
+                continue;
+            }
+            const prepared = prepareFinding(learning, project, content, extraAnnotations, resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath);
+            if (prepared.status === "rejected") {
+                rejected.push({ text: learning, reason: prepared.reason });
+                continue;
+            }
+            if (prepared.status === "duplicate") {
+                skipped.push(learning);
+                continue;
+            }
+            content = insertFindingIntoContent(content, today, prepared.finding.bullet, prepared.finding.citationComment);
+            if (prepared.finding.tagWarning)
+                debugLog(`add_findings: ${prepared.finding.tagWarning}`);
+            added.push(learning);
+        }
+        if (added.length > 0) {
+            const tmpPath = learningsPath + `.tmp-${crypto.randomUUID()}`;
+            fs.writeFileSync(tmpPath, content);
+            fs.renameSync(tmpPath, learningsPath);
+        }
+        return phrenOk({ content, wrote: added.length > 0 });
+    });
+    if (!contentResult.ok)
+        return contentResult;
+    if (contentResult.data.wrote) {
+        appendAuditLog(phrenPath, "add_finding", `project=${project} count=${added.length} batch=true`);
+        const cap = Number.parseInt((process.env.PHREN_FINDINGS_CAP) || "", 10) || DEFAULT_FINDINGS_CAP;
+        if (countActiveFindings(contentResult.data.content) > cap) {
+            const archiveResult = autoArchiveToReference(phrenPath, project, cap);
+            if (archiveResult.ok && archiveResult.data > 0) {
+                debugLog(`Size cap: archived ${archiveResult.data} oldest entries for "${project}" (cap=${cap})`);
+            }
+        }
+    }
+    return phrenOk({ added, skipped, rejected });
+}

package/mcp/dist/content-metadata.js

@@ -0,0 +1,186 @@
+/**
+ * Consolidated metadata regex patterns and parsing helpers for HTML comment
+ * metadata embedded in FINDINGS.md and related files.
+ *
+ * `phren:` prefixes are used for HTML comment metadata.
+ */
+// ---------------------------------------------------------------------------
+// Prefix pattern (shared across all metadata types)
+// ---------------------------------------------------------------------------
+/** Matches `phren` as a comment prefix. */
+const PREFIX = `phren`;
+// ---------------------------------------------------------------------------
+// Raw regex patterns — exported for direct use when the helpers don't fit
+// ---------------------------------------------------------------------------
+export const METADATA_REGEX = {
+    /** Matches `<!-- phren:status "active" -->` or `<!-- phren:status "superseded" -->` etc. */
+    status: new RegExp(`<!--\\s*${PREFIX}:status\\s+"?(active|superseded|contradicted|stale|invalid_citation|retracted)"?\\s*-->`, "i"),
+    /** Matches `<!-- phren:status_updated "2025-01-01" -->` */
+    statusUpdated: new RegExp(`<!--\\s*${PREFIX}:status_updated\\s+"([^"]+)"\\s*-->`, "i"),
+    /** Matches `<!-- phren:status_reason "superseded_by" -->` */
+    statusReason: new RegExp(`<!--\\s*${PREFIX}:status_reason\\s+"([^"]+)"\\s*-->`, "i"),
+    /** Matches `<!-- phren:status_ref "some ref" -->` */
+    statusRef: new RegExp(`<!--\\s*${PREFIX}:status_ref\\s+"([^"]+)"\\s*-->`, "i"),
+    /** Generic field matcher factory for status_updated / status_reason / status_ref. */
+    statusField(field) {
+        return new RegExp(`<!--\\s*${PREFIX}:${field}\\s+"([^"]+)"\\s*-->`, "i");
+    },
+    /** Raw (unquoted) fallback for status fields: `<!-- phren:status_ref some text -->` */
+    statusFieldRaw(field) {
+        return new RegExp(`<!--\\s*${PREFIX}:${field}\\s+([^>]+?)\\s*-->`, "i");
+    },
+    /** Matches `<!-- phren:superseded_by "text" 2025-01-01 -->` */
+    supersededBy: new RegExp(`<!--\\s*${PREFIX}:superseded_by\\s+"([^"]+)"(?:\\s+([0-9]{4}-[0-9]{2}-[0-9]{2}))?\\s*-->`, "i"),
+    /** Legacy `<!-- superseded_by: "text" -->` */
+    supersededByLegacy: /<!--\s*superseded_by:\s*"([^"]+)"\s*-->/i,
+    /** Matches `<!-- phren:supersedes "text" -->` */
+    supersedes: new RegExp(`<!--\\s*${PREFIX}:supersedes\\s+"([^"]+)"\\s*-->`, "i"),
+    /** Matches `<!-- phren:contradicts "text" -->` */
+    contradicts: new RegExp(`<!--\\s*${PREFIX}:contradicts\\s+"([^"]+)"\\s*-->`, "i"),
+    /** Global version for matchAll */
+    contradictsAll: new RegExp(`<!--\\s*phren:contradicts\\s+"([^"]+)"\\s*-->`, "g"),
+    /** Legacy `<!-- conflicts_with: "text" -->` or `<!-- conflicts_with: "text" (from project: foo) -->` */
+    conflictsWith: /<!--\s*conflicts_with:\s*"([^"]+)"(?:\s*\(from project:\s*[^)]+\))?\s*-->/i,
+    /** Global version for matchAll on conflicts_with */
+    conflictsWithAll: /<!--\s*conflicts_with:\s*"([^"]+)"(?:\s*\(from project:\s*[^)]+\))?\s*-->/g,
+    /** Matches `<!-- phren:cite {...} -->` or `<!-- phren:cite {...} -->` on a full line. */
+    citation: /^\s*<!--\s*phren:cite\s+\{.*\}\s*-->\s*$/,
+    /** Matches the opening marker (not line-anchored) for extracting JSON payload. */
+    citationMarker: /<!--\s*phren:cite\s+/,
+    /** Matches `<!-- phren:archive:start -->` or `<!-- phren:archive:start -->` */
+    archiveStart: new RegExp(`<!--\\s*${PREFIX}:archive:start\\s*-->`),
+    /** Matches `<!-- phren:archive:end -->` or `<!-- phren:archive:end -->` */
+    archiveEnd: new RegExp(`<!--\\s*${PREFIX}:archive:end\\s*-->`),
+    /** Matches `<!-- fid:abcd1234 -->` */
+    findingId: /<!--\s*fid:([a-z0-9]{8})\s*-->/i,
+    /** Matches `<!-- created: 2025-01-01 -->` */
+    createdDate: /<!--\s*created:\s*([0-9]{4}-[0-9]{2}-[0-9]{2})\s*-->/i,
+    /** Matches any lifecycle annotation: status, status_updated, status_reason, status_ref */
+    lifecycleAnnotation: new RegExp(`<!--\\s*${PREFIX}:status(?:_updated|_reason|_ref)?\\b[^>]*-->`, "i"),
+    /** Matches `<!-- source:... -->` */
+    source: /<!--\s*source:\s*(.*?)\s*-->/,
+    /** Matches any HTML comment `<!-- ... -->` (non-greedy). */
+    anyComment: /<!--.*?-->/g,
+    // Strip patterns (with leading optional whitespace for clean removal)
+    /** Strip status comment */
+    stripStatus: new RegExp(`\\s*<!--\\s*${PREFIX}:status\\s+"?(?:active|superseded|contradicted|stale|invalid_citation|retracted)"?\\s*-->`, "gi"),
+    /** Strip status_updated comment */
+    stripStatusUpdated: new RegExp(`\\s*<!--\\s*${PREFIX}:status_updated\\s+"[^"]+"\\s*-->`, "gi"),
+    /** Strip status_reason comment */
+    stripStatusReason: new RegExp(`\\s*<!--\\s*${PREFIX}:status_reason\\s+"[^"]+"\\s*-->`, "gi"),
+    /** Strip status_ref comment */
+    stripStatusRef: new RegExp(`\\s*<!--\\s*${PREFIX}:status_ref\\s+"[^"]+"\\s*-->`, "gi"),
+    /** Strip legacy `<!-- superseded_by: "..." -->` */
+    stripSupersededByLegacy: /\s*<!--\s*superseded_by:\s*"[^"]+"\s*-->/gi,
+    /** Strip `<!-- phren:superseded_by "..." ... -->` */
+    stripSupersededBy: new RegExp(`\\s*<!--\\s*${PREFIX}:superseded_by\\s+"[^"]+"(?:\\s+[0-9]{4}-[0-9]{2}-[0-9]{2})?\\s*-->`, "gi"),
+    /** Strip `<!-- phren:supersedes "..." -->` */
+    stripSupersedes: new RegExp(`\\s*<!--\\s*${PREFIX}:supersedes\\s+"[^"]+"\\s*-->`, "gi"),
+    /** Strip legacy `<!-- conflicts_with: "..." -->` */
+    stripConflictsWith: /\s*<!--\s*conflicts_with:\s*"[^"]+"(?:\s*\(from project:\s*[^)]+\))?\s*-->/gi,
+    /** Strip `<!-- phren:contradicts "..." -->` */
+    stripContradicts: new RegExp(`\\s*<!--\\s*${PREFIX}:contradicts\\s+"[^"]+"\\s*-->`, "gi"),
+};
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+/** Parse `<!-- phren:status "active" -->` from a line. Returns the status string or undefined. */
+export function parseStatus(line) {
+    return line.match(METADATA_REGEX.status)?.[1]?.toLowerCase();
+}
+/** Parse a quoted status field (status_updated, status_reason, status_ref) from a line. */
+export function parseStatusField(line, field) {
+    const quoted = line.match(METADATA_REGEX.statusField(field))?.[1];
+    if (quoted)
+        return quoted.replace(/\s+/g, " ").trim();
+    const raw = line.match(METADATA_REGEX.statusFieldRaw(field))?.[1];
+    return raw ? raw.replace(/\s+/g, " ").trim() : undefined;
+}
+/** Parse supersession metadata: returns `{ ref, date }` or null. Checks both prefixed and legacy forms. */
+export function parseSupersession(line) {
+    const prefixed = line.match(METADATA_REGEX.supersededBy);
+    if (prefixed)
+        return { ref: prefixed[1], date: prefixed[2] };
+    const legacy = line.match(METADATA_REGEX.supersededByLegacy);
+    if (legacy)
+        return { ref: legacy[1] };
+    return null;
+}
+/** Parse `<!-- phren:supersedes "..." -->` from a line. Returns the ref or undefined. */
+export function parseSupersedesRef(line) {
+    return line.match(METADATA_REGEX.supersedes)?.[1];
+}
+/** Parse contradiction metadata. Checks both prefixed `contradicts` and legacy `conflicts_with`. */
+export function parseContradiction(line) {
+    const prefixed = line.match(METADATA_REGEX.contradicts);
+    if (prefixed)
+        return prefixed[1];
+    const legacy = line.match(METADATA_REGEX.conflictsWith);
+    if (legacy)
+        return legacy[1];
+    return null;
+}
+/** Parse all contradiction refs from a line using matchAll. */
+export function parseAllContradictions(line) {
+    return [...line.matchAll(METADATA_REGEX.contradictsAll)].map((m) => m[1]);
+}
+/** Parse `<!-- fid:XXXXXXXX -->` from a line. Returns the 8-char hex ID or undefined. */
+export function parseFindingId(line) {
+    return line.match(METADATA_REGEX.findingId)?.[1];
+}
+/** Parse `<!-- created: YYYY-MM-DD -->` from a line. Returns the date string or undefined. */
+export function parseCreatedDate(line) {
+    return line.match(METADATA_REGEX.createdDate)?.[1];
+}
+/** Check if a line (or next line) contains a citation comment. */
+export function isCitationLine(line) {
+    return METADATA_REGEX.citation.test(line.trim());
+}
+/** Check if a line marks the start of an archive block. */
+export function isArchiveStart(line) {
+    return METADATA_REGEX.archiveStart.test(line) || /^<details(?:\s|>)/i.test(line.trim());
+}
+/** Check if a line marks the end of an archive block. */
+export function isArchiveEnd(line) {
+    return METADATA_REGEX.archiveEnd.test(line) || /^<\/details>/i.test(line.trim());
+}
+// ---------------------------------------------------------------------------
+// Strip helpers — remove metadata comments from a line
+// ---------------------------------------------------------------------------
+/** Strip all lifecycle status comments (status, status_updated, status_reason, status_ref). */
+export function stripLifecycleMetadata(line) {
+    return line
+        .replace(METADATA_REGEX.stripStatus, "")
+        .replace(METADATA_REGEX.stripStatusUpdated, "")
+        .replace(METADATA_REGEX.stripStatusReason, "")
+        .replace(METADATA_REGEX.stripStatusRef, "");
+}
+/** Strip all relation comments (superseded_by, supersedes, conflicts_with, contradicts). */
+export function stripRelationMetadata(line) {
+    return line
+        .replace(METADATA_REGEX.stripSupersededByLegacy, "")
+        .replace(METADATA_REGEX.stripSupersededBy, "")
+        .replace(METADATA_REGEX.stripSupersedes, "")
+        .replace(METADATA_REGEX.stripConflictsWith, "")
+        .replace(METADATA_REGEX.stripContradicts, "");
+}
+/** Strip all phren/phren metadata comments from a line. */
+export function stripAllMetadata(line) {
+    return stripRelationMetadata(stripLifecycleMetadata(line));
+}
+/** Strip all HTML comments from text. */
+export function stripComments(text) {
+    return text.replace(METADATA_REGEX.anyComment, "").trim();
+}
+// ---------------------------------------------------------------------------
+// Add helpers — append metadata comments to a line
+// ---------------------------------------------------------------------------
+/** Build a metadata comment string. */
+export function addMetadata(type, value, extra) {
+    const prefix = "phren";
+    const escaped = value.replace(/"/g, "'");
+    if (extra) {
+        return `<!-- ${prefix}:${type} "${escaped}" ${extra} -->`;
+    }
+    return `<!-- ${prefix}:${type} "${escaped}" -->`;
+}