@phren/cli 0.0.57 → 0.0.58

package/dist/content/metadata.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+export declare const METADATA_REGEX: {
+    /** Matches `<!-- phren:status "active" -->` or `<!-- phren:status "superseded" -->` etc. */
+    readonly status: RegExp;
+    /** Matches `<!-- phren:status_updated "2025-01-01" -->` */
+    readonly statusUpdated: RegExp;
+    /** Matches `<!-- phren:status_reason "superseded_by" -->` */
+    readonly statusReason: RegExp;
+    /** Matches `<!-- phren:status_ref "some ref" -->` */
+    readonly statusRef: RegExp;
+    /** Generic field matcher factory for status_updated / status_reason / status_ref. */
+    readonly statusField: (field: string) => RegExp;
+    /** Raw (unquoted) fallback for status fields: `<!-- phren:status_ref some text -->` */
+    readonly statusFieldRaw: (field: string) => RegExp;
+    /** Matches `<!-- phren:superseded_by "text" 2025-01-01 -->` */
+    readonly supersededBy: RegExp;
+    /** Legacy `<!-- superseded_by: "text" -->` */
+    readonly supersededByLegacy: RegExp;
+    /** Matches `<!-- phren:supersedes "text" -->` */
+    readonly supersedes: RegExp;
+    /** Matches `<!-- phren:contradicts "text" -->` */
+    readonly contradicts: RegExp;
+    /** Global version for matchAll */
+    readonly contradictsAll: RegExp;
+    /** Legacy `<!-- conflicts_with: "text" -->` or `<!-- conflicts_with: "text" (from project: foo) -->` */
+    readonly conflictsWith: RegExp;
+    /** Global version for matchAll on conflicts_with */
+    readonly conflictsWithAll: RegExp;
+    /** Matches `<!-- phren:cite {...} -->` or `<!-- phren:cite {...} -->` on a full line. */
+    readonly citation: RegExp;
+    /** Matches the opening marker (not line-anchored) for extracting JSON payload. */
+    readonly citationMarker: RegExp;
+    /** Matches `<!-- phren:archive:start -->` or `<!-- phren:archive:start -->` */
+    readonly archiveStart: RegExp;
+    /** Matches `<!-- phren:archive:end -->` or `<!-- phren:archive:end -->` */
+    readonly archiveEnd: RegExp;
+    /** Matches `<!-- fid:abcd1234 -->` */
+    readonly findingId: RegExp;
+    /** Matches `<!-- created: 2025-01-01 -->` */
+    readonly createdDate: RegExp;
+    /** Matches any lifecycle annotation: status, status_updated, status_reason, status_ref */
+    readonly lifecycleAnnotation: RegExp;
+    /** Matches `<!-- source:... -->` */
+    readonly source: RegExp;
+    /** Matches any HTML comment `<!-- ... -->` (non-greedy). */
+    readonly anyComment: RegExp;
+    /** Strip status comment */
+    readonly stripStatus: RegExp;
+    /** Strip status_updated comment */
+    readonly stripStatusUpdated: RegExp;
+    /** Strip status_reason comment */
+    readonly stripStatusReason: RegExp;
+    /** Strip status_ref comment */
+    readonly stripStatusRef: RegExp;
+    /** Strip legacy `<!-- superseded_by: "..." -->` */
+    readonly stripSupersededByLegacy: RegExp;
+    /** Strip `<!-- phren:superseded_by "..." ... -->` */
+    readonly stripSupersededBy: RegExp;
+    /** Strip `<!-- phren:supersedes "..." -->` */
+    readonly stripSupersedes: RegExp;
+    /** Strip legacy `<!-- conflicts_with: "..." -->` */
+    readonly stripConflictsWith: RegExp;
+    /** Strip `<!-- phren:contradicts "..." -->` */
+    readonly stripContradicts: RegExp;
+};
+/** Parse `<!-- phren:status "active" -->` from a line. Returns the status string or undefined. */
+export declare function parseStatus(line: string): string | undefined;
+/** Parse a quoted status field (status_updated, status_reason, status_ref) from a line. */
+export declare function parseStatusField(line: string, field: string): string | undefined;
+/** Parse supersession metadata: returns `{ ref, date }` or null. Checks both prefixed and legacy forms. */
+export declare function parseSupersession(line: string): {
+    ref: string;
+    date?: string;
+} | null;
+/** Parse `<!-- phren:supersedes "..." -->` from a line. Returns the ref or undefined. */
+export declare function parseSupersedesRef(line: string): string | undefined;
+/** Parse contradiction metadata. Checks both prefixed `contradicts` and legacy `conflicts_with`. */
+export declare function parseContradiction(line: string): string | null;
+/** Parse all contradiction refs from a line using matchAll. */
+export declare function parseAllContradictions(line: string): string[];
+/** Parse `<!-- fid:XXXXXXXX -->` from a line. Returns the 8-char hex ID or undefined. */
+export declare function parseFindingId(line: string): string | undefined;
+/** Parse `<!-- created: YYYY-MM-DD -->` from a line. Returns the date string or undefined. */
+export declare function parseCreatedDate(line: string): string | undefined;
+/** Check if a line (or next line) contains a citation comment. */
+export declare function isCitationLine(line: string): boolean;
+/** Check if a line marks the start of an archive block. */
+export declare function isArchiveStart(line: string): boolean;
+/** Check if a line marks the end of an archive block. */
+export declare function isArchiveEnd(line: string): boolean;
+/** Strip all lifecycle status comments (status, status_updated, status_reason, status_ref). */
+export declare function stripLifecycleMetadata(line: string): string;
+/** Strip all relation comments (superseded_by, supersedes, conflicts_with, contradicts). */
+export declare function stripRelationMetadata(line: string): string;
+/** Strip all phren/phren metadata comments from a line. */
+export declare function stripAllMetadata(line: string): string;
+/** Strip all HTML comments from text. */
+export declare function stripComments(text: string): string;
+/** Normalize finding text for comparison: strips bullet prefix, HTML comments, confidence tags, normalizes whitespace, lowercases. */
+export declare function normalizeFindingText(raw: string): string;
+/** Build a metadata comment string. */
+export declare function addMetadata(type: string, value: string, extra?: string): string;

package/dist/content/validate.d.ts

@@ -0,0 +1,70 @@
+/** Maximum allowed length for a single finding entry (token budget protection). */
+export declare const MAX_FINDING_LENGTH = 2000;
+export interface ConsolidationNeeded {
+    project: string;
+    entriesSince: number;
+    daysSince: number | null;
+    lastConsolidated: string | null;
+}
+export interface ConsolidationStatus extends ConsolidationNeeded {
+    recommended: boolean;
+}
+/** Thresholds used for consolidation recommendations. */
+export declare const CONSOLIDATION_ENTRY_THRESHOLD = 25;
+/**
+ * Validate a single finding text before it is persisted.
+ * Returns null if valid, or an error message string if invalid.
+ */
+export declare function validateFinding(text: string): string | null;
+/**
+ * Compute consolidation status for a single project directory.
+ * Returns null if the project has no FINDINGS.md.
+ */
+export declare function getProjectConsolidationStatus(dir: string): ConsolidationStatus | null;
+/**
+ * Check which projects have enough new findings to warrant consolidation.
+ * Returns projects that exceed the entry or time thresholds.
+ */
+export declare function checkConsolidationNeeded(phrenPath: string, profile?: string): ConsolidationNeeded[];
+/**
+ * Validate FINDINGS.md format and structure.
+ * Returns an array of issue description strings (empty array means valid).
+ */
+export declare function validateFindingsFormat(content: string): string[];
+/**
+ * Strip the ## Done section (and equivalents) from task content to reduce index bloat.
+ * Keeps the title, Active, and Queue sections which are the actionable parts.
+ * Handles: Done, Completed, Archived, Finished, Complete.
+ */
+export declare function stripTaskDoneSection(content: string): string;
+/**
+ * Validate tasks.md format and structure.
+ * Returns an array of issue description strings (empty array means valid).
+ */
+export declare function validateTaskFormat(content: string): string[];
+/**
+ * Extract ours/theirs versions from a file containing git conflict markers.
+ * Returns null if no conflict markers are found.
+ */
+export declare function extractConflictVersions(content: string): {
+    ours: string;
+    theirs: string;
+} | null;
+/**
+ * Merge two FINDINGS.md versions: union entries per date, newest date first.
+ * Deduplicates by bullet text only, keeping comment lines from whichever
+ * version is kept (ours takes priority).
+ * Preserves preamble content (consolidated markers) and postamble (archive blocks).
+ */
+export declare function mergeFindings(ours: string, theirs: string): string;
+/**
+ * Merge two tasks.md versions: union items per section, deduplicated by stable ID when
+ * present or by normalised bullet text otherwise. Context/continuation lines are preserved.
+ * Ours wins on conflict. Section order follows Active > Queue > Done.
+ */
+export declare function mergeTask(ours: string, theirs: string): string;
+/**
+ * Attempt to auto-resolve git conflicts in FINDINGS.md and tasks.md files.
+ * Returns true if all conflicts were resolved, false if any remain.
+ */
+export declare function autoMergeConflicts(phrenPath: string): boolean;

package/dist/core/finding.d.ts

@@ -0,0 +1,25 @@
+interface FindingResult {
+    ok: boolean;
+    message: string;
+    data?: unknown;
+}
+/**
+ * Validate and add a single finding. Shared validation logic used by
+ * both CLI `phren add-finding` and MCP `add_finding` tool.
+ */
+export declare function addFinding(phrenPath: string, project: string, finding: string, citation?: {
+    file?: string;
+    line?: number;
+    repo?: string;
+    commit?: string;
+    supersedes?: string;
+}, findingType?: string): FindingResult;
+/**
+ * Remove a finding by partial text match.
+ */
+export declare function removeFinding(phrenPath: string, project: string, finding: string): FindingResult;
+/**
+ * Remove multiple findings by partial text match.
+ */
+export declare function removeFindings(phrenPath: string, project: string, findings: string[]): FindingResult;
+export {};

package/dist/core/project.d.ts

@@ -0,0 +1,16 @@
+import { type PhrenResult } from "../shared.js";
+import type { ProjectOwnershipMode } from "../project-config.js";
+interface AddedProjectData {
+    project: string;
+    path: string;
+    profile: string | null;
+    ownership: ProjectOwnershipMode;
+    files: {
+        claude: string | null;
+        summary: string;
+        findings: string;
+        task: string;
+    };
+}
+export declare function addProjectFromPath(phrenPath: string, targetPath: string | undefined, requestedProfile?: string, ownership?: ProjectOwnershipMode): PhrenResult<AddedProjectData>;
+export {};

package/dist/core/search.d.ts

@@ -0,0 +1,13 @@
+import type { DocRow, SqlJsDatabase } from "../shared/index.js";
+/**
+ * Keyword overlap fallback for when FTS5 returns no results.
+ * Scans all docs (optionally filtered by project/type), scores each by
+ * how many query terms appear in its content, and returns top matches.
+ *
+ * Shared between the MCP search tool and CLI `phren search`.
+ */
+export declare function keywordFallbackSearch(db: SqlJsDatabase, query: string, opts: {
+    project?: string;
+    type?: string;
+    limit: number;
+}): DocRow[] | null;

package/dist/data/access.d.ts

@@ -0,0 +1,83 @@
+import { type PhrenResult } from "../shared.js";
+import { type AddFindingResult } from "../shared/content.js";
+import { type FindingCitation, type FindingProvenanceSource } from "../content/citation.js";
+import { type FindingLifecycleStatus } from "../finding/lifecycle.js";
+export type { TaskSection, TaskItem, TaskDoc } from "./tasks.js";
+export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks, completeTasks, completeTask, removeTask, removeTasks, updateTask, linkTaskIssue, pinTask, unpinTask, workNextTask, tidyDoneTasks, taskMarkdown, appendChildFinding, promoteTask, TASKS_FILENAME, TASK_FILE_ALIASES, canonicalTaskFilePath, resolveTaskFilePath, isTaskFileName, type AddTaskOptions, } from "./tasks.js";
+export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, type ProfileInfo, type ProjectCard, } from "../profile-store.js";
+export { loadShellState, resetShellState, saveShellState, type ShellState, } from "../shell/state-store.js";
+export { getRuntimeHealth as readRuntimeHealth } from "../shared/governance.js";
+export interface FindingItem {
+    id: string;
+    /** Stable 8-char hex ID embedded as `<!-- fid:XXXXXXXX -->`. Survives reordering and consolidation. */
+    stableId?: string;
+    date: string;
+    text: string;
+    citation?: string;
+    citationData?: FindingCitation;
+    taskItem?: string;
+    confidence?: number;
+    source: FindingProvenanceSource;
+    machine?: string;
+    actor?: string;
+    tool?: string;
+    model?: string;
+    sessionId?: string;
+    scope?: string;
+    /** First 60 chars of the newer finding that supersedes this one. Set when this finding is stale. */
+    supersededBy?: string;
+    /** First 60 chars of the older finding this one replaces. */
+    supersedes?: string;
+    /** Snippets of findings this one contradicts. */
+    contradicts?: string[];
+    status: FindingLifecycleStatus;
+    status_updated?: string;
+    status_reason?: string;
+    status_ref?: string;
+    /** Indicates whether this item comes from archived history blocks (<details> / phren:archive). */
+    archived?: boolean;
+    /** Tier marker used to distinguish current truth vs archived history. */
+    tier?: "current" | "archived";
+}
+export interface ReadFindingsOptions {
+    includeArchived?: boolean;
+}
+export interface FindingHistoryEntry {
+    id: string;
+    stableId?: string;
+    text: string;
+    timeline: FindingItem[];
+    current?: FindingItem;
+    archivedCount: number;
+}
+export interface QueueItem {
+    id: string;
+    section: "Review" | "Stale" | "Conflicts";
+    date: string;
+    text: string;
+    line: string;
+    confidence?: number;
+    risky: boolean;
+    machine?: string;
+    model?: string;
+}
+export interface ProjectQueueItem extends QueueItem {
+    project: string;
+}
+export declare function readFindings(phrenPath: string, project: string, opts?: ReadFindingsOptions): PhrenResult<FindingItem[]>;
+export declare function readFindingHistory(phrenPath: string, project: string, findingId?: string): PhrenResult<FindingHistoryEntry[]>;
+export declare function addFinding(phrenPath: string, project: string, learning: string): PhrenResult<AddFindingResult>;
+export declare function removeFinding(phrenPath: string, project: string, match: string): PhrenResult<string>;
+export declare function removeFindings(phrenPath: string, project: string, matches: string[]): PhrenResult<{
+    removed: string[];
+    errors: string[];
+}>;
+export declare function editFinding(phrenPath: string, project: string, oldText: string, newText: string): PhrenResult<string>;
+export declare function readReviewQueue(phrenPath: string, project: string): PhrenResult<QueueItem[]>;
+/** Remove a queue item's line from review.md (finding stays in FINDINGS.md). */
+export declare function approveQueueItem(phrenPath: string, project: string, lineText: string): PhrenResult<string>;
+/** Remove a queue item from review.md AND remove the corresponding finding from FINDINGS.md. */
+export declare function rejectQueueItem(phrenPath: string, project: string, lineText: string): PhrenResult<string>;
+/** Edit a queue item's text in review.md and the corresponding finding in FINDINGS.md. */
+export declare function editQueueItem(phrenPath: string, project: string, lineText: string, newText: string): PhrenResult<string>;
+export declare function readReviewQueueAcrossProjects(phrenPath: string, profile?: string): PhrenResult<ProjectQueueItem[]>;

package/dist/data/tasks.d.ts

@@ -0,0 +1,89 @@
+import { type PhrenResult } from "../shared.js";
+export type TaskSection = "Active" | "Queue" | "Done";
+export declare const TASKS_FILENAME = "tasks.md";
+export declare const TASK_FILE_ALIASES: readonly ["tasks.md"];
+export interface TaskItem {
+    /** Positional ID for display (e.g. "A1", "Q3"). Recomputed on every read — use stableId for persistent references. */
+    id: string;
+    /** Content-addressed stable ID embedded in the file as `<!-- bid:HASH -->`. Survives reordering and completions. */
+    stableId?: string;
+    section: TaskSection;
+    line: string;
+    checked: boolean;
+    priority?: "high" | "medium" | "low";
+    context?: string;
+    pinned?: boolean;
+    githubIssue?: number;
+    githubUrl?: string;
+    rank?: number;
+    lastActivity?: string;
+    createdAt?: string;
+    sessionId?: string;
+    scope?: string;
+    childFindings?: string[];
+    speculative?: boolean;
+    parentFinding?: string;
+}
+export interface TaskDoc {
+    project: string;
+    title: string;
+    items: Record<TaskSection, TaskItem[]>;
+    issues: string[];
+    path: string;
+}
+/**
+ * Apply gravity to tasks: items with stale lastActivity drift toward higher rank numbers.
+ * Only affects display order — does not mutate the file.
+ */
+export declare function applyGravity(items: TaskItem[]): TaskItem[];
+export declare function canonicalTaskFilePath(phrenPath: string, project: string): string | null;
+export declare function isTaskFileName(filename: string): boolean;
+export declare function resolveTaskFilePath(phrenPath: string, project: string): string | null;
+export declare function readTasks(phrenPath: string, project: string): PhrenResult<TaskDoc>;
+export declare function readTasksAcrossProjects(phrenPath: string, profile?: string): TaskDoc[];
+export declare function resolveTaskItem(phrenPath: string, project: string, match: string): PhrenResult<TaskItem>;
+export interface AddTaskOptions {
+    createdAt?: string;
+    sessionId?: string;
+    scope?: string;
+    speculative?: boolean;
+    parentFinding?: string;
+}
+export declare function addTask(phrenPath: string, project: string, item: string, opts?: AddTaskOptions): PhrenResult<TaskItem>;
+export declare function addTasks(phrenPath: string, project: string, items: string[], opts?: Pick<AddTaskOptions, "scope">): PhrenResult<{
+    added: string[];
+    errors: string[];
+}>;
+export declare function completeTasks(phrenPath: string, project: string, matches: string[]): PhrenResult<{
+    completed: string[];
+    errors: string[];
+}>;
+export declare function completeTask(phrenPath: string, project: string, match: string): PhrenResult<string>;
+export declare function removeTask(phrenPath: string, project: string, match: string): PhrenResult<string>;
+export declare function removeTasks(phrenPath: string, project: string, matches: string[]): PhrenResult<{
+    removed: string[];
+    errors: string[];
+}>;
+export declare function updateTask(phrenPath: string, project: string, match: string, updates: {
+    text?: string;
+    priority?: string;
+    context?: string;
+    replace_context?: boolean;
+    section?: string;
+    github_issue?: number | string;
+    github_url?: string;
+    unlink_github?: boolean;
+}): PhrenResult<string>;
+export declare function pinTask(phrenPath: string, project: string, match: string): PhrenResult<string>;
+export declare function unpinTask(phrenPath: string, project: string, match: string): PhrenResult<string>;
+export declare function reorderTask(phrenPath: string, project: string, match: string, targetRank: number): PhrenResult<string>;
+export declare function appendChildFinding(phrenPath: string, project: string, match: string, findingId: string): PhrenResult<string>;
+export declare function promoteTask(phrenPath: string, project: string, match: string, moveToActive: boolean): PhrenResult<TaskItem>;
+export declare function workNextTask(phrenPath: string, project: string): PhrenResult<string>;
+export declare function tidyDoneTasks(phrenPath: string, project: string, keep?: number, dryRun?: boolean): PhrenResult<string>;
+export declare function taskMarkdown(doc: TaskDoc): string;
+export declare function linkTaskIssue(phrenPath: string, project: string, match: string, link: {
+    github_issue?: number | string;
+    github_url?: string;
+    unlink?: boolean;
+}): PhrenResult<TaskItem>;

package/dist/embedding.d.ts

@@ -0,0 +1,54 @@
+import type { SqlJsDatabase } from "./index-query.js";
+interface SqlJsStatic {
+    Database: new (data?: ArrayLike<number>) => SqlJsDatabase;
+}
+/** Encode a number[] embedding into a compact binary blob (Float32Array). */
+declare function encodeEmbedding(embedding: number[]): Buffer;
+/** Decode a binary blob back to number[]. */
+declare function decodeEmbedding(blob: Uint8Array): number[];
+export declare function setSqlJsLoaderForTests(loader: () => Promise<SqlJsStatic>): void;
+export declare function resetSqlJsStateForTests(): void;
+declare function openCacheDb(phrenPath: string): Promise<SqlJsDatabase>;
+/**
+ * Q14: Persist the in-memory DB to disk under a file lock.
+ * Reads the current on-disk snapshot inside the lock, merges any entries that
+ * are in `db` but missing from disk, then writes atomically via temp-file rename.
+ * This prevents the "last writer wins" race where two concurrent processes each
+ * open the same on-disk snapshot, insert different entries, and overwrite each
+ * other's work.
+ */
+declare function persistDb(phrenPath: string, db: SqlJsDatabase): void;
+declare function lookupCache(db: SqlJsDatabase, model: string, hash: string): number[] | null;
+declare function insertCache(db: SqlJsDatabase, model: string, hash: string, embedding: number[]): void;
+/**
+ * Get embedding from OpenAI-compatible API.
+ * Calls POST https://api.openai.com/v1/embeddings (or compatible endpoint).
+ */
+declare function getApiEmbedding(text: string, apiKey: string, model?: string): Promise<number[]>;
+/**
+ * Get embeddings for multiple texts in a single API call.
+ * The OpenAI embeddings API supports array input natively.
+ */
+declare function getApiEmbeddings(texts: string[], apiKey: string, model?: string): Promise<number[][]>;
+export declare const embeddingOps: {
+    openCacheDb: typeof openCacheDb;
+    persistDb: typeof persistDb;
+    lookupCache: typeof lookupCache;
+    insertCache: typeof insertCache;
+    getApiEmbedding: typeof getApiEmbedding;
+    getApiEmbeddings: typeof getApiEmbeddings;
+};
+/**
+ * Get embedding with caching. Uses the configured provider.
+ */
+export declare function getCachedEmbedding(phrenPath: string, text: string, apiKey: string, model: string): Promise<number[]>;
+/**
+ * Get embeddings for multiple texts with caching. Batches uncached texts into single API calls.
+ */
+export declare function getCachedEmbeddings(phrenPath: string, texts: string[], apiKey: string, model: string): Promise<number[][]>;
+/**
+ * Compute cosine similarity between two vectors.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export type { SqlJsDatabase } from "./index-query.js";
+export { encodeEmbedding, decodeEmbedding, openCacheDb };

package/dist/entrypoint.d.ts

@@ -0,0 +1 @@
+export declare function runTopLevelCommand(argv: string[]): Promise<boolean>;

package/dist/finding/context.d.ts

@@ -0,0 +1,8 @@
+interface TaskReferenceResolution {
+    stableId?: string;
+    error?: string;
+}
+export declare function resolveFindingTaskReference(phrenPath: string, project: string, match: string): TaskReferenceResolution;
+export declare function resolveAutoFindingTaskItem(phrenPath: string, project: string): string | undefined;
+export declare function resolveFindingSessionId(phrenPath: string, project: string, explicitSessionId?: string): string | undefined;
+export {};

package/dist/finding/impact.d.ts

@@ -0,0 +1,11 @@
+interface ImpactLogInput {
+    findingId: string;
+    project: string;
+    sessionId: string;
+}
+export declare function findingIdFromLine(line: string): string;
+export declare function extractFindingIdsFromSnippet(snippet: string): string[];
+export declare function logImpact(phrenPath: string, entries: ImpactLogInput[]): void;
+export declare function getHighImpactFindings(phrenPath: string, minSurfaceCount?: number): Set<string>;
+export declare function markImpactEntriesCompletedForSession(phrenPath: string, sessionId: string, project?: string): number;
+export {};

package/dist/finding/journal.d.ts

@@ -0,0 +1,40 @@
+import { PhrenResult } from "../shared.js";
+import type { FindingProvenanceSource } from "../content/citation.js";
+interface FindingJournalCompactResult {
+    filesProcessed: number;
+    entriesProcessed: number;
+    added: number;
+    skipped: number;
+    failed: number;
+}
+export declare function appendFindingJournal(phrenPath: string, project: string, text: string, opts?: {
+    sessionId?: string;
+    repo?: string;
+    commit?: string;
+    file?: string;
+    source?: FindingProvenanceSource;
+}): PhrenResult<string>;
+export declare function compactFindingJournals(phrenPath: string, project?: string): FindingJournalCompactResult;
+/**
+ * Append a finding to a team store's journal.
+ * Each actor gets one file per day — no merge conflicts possible.
+ * These are markdown files committed to git (not runtime JSONL).
+ */
+export declare function appendTeamJournal(storePath: string, project: string, finding: string, actor?: string): PhrenResult<string>;
+/**
+ * Read all team journal entries for a project, newest first.
+ */
+export declare function readTeamJournalEntries(storePath: string, project: string): Array<{
+    file: string;
+    date: string;
+    actor: string;
+    entries: string[];
+}>;
+/**
+ * Materialize FINDINGS.md from team journal entries.
+ * Groups by date, includes actor attribution.
+ */
+export declare function materializeTeamFindings(storePath: string, project: string): PhrenResult<{
+    entryCount: number;
+}>;
+export {};

package/dist/finding/lifecycle.d.ts

@@ -0,0 +1,40 @@
+import { type PhrenResult } from "../phren-core.js";
+export declare const FINDING_TYPE_DECAY: Record<string, {
+    maxAgeDays: number;
+    decayMultiplier: number;
+}>;
+export declare function extractFindingType(line: string): string | null;
+export declare const FINDING_LIFECYCLE_STATUSES: readonly ["active", "superseded", "contradicted", "stale", "invalid_citation", "retracted"];
+export type FindingLifecycleStatus = typeof FINDING_LIFECYCLE_STATUSES[number];
+export interface FindingLifecycleMetadata {
+    status: FindingLifecycleStatus;
+    status_updated?: string;
+    status_reason?: string;
+    status_ref?: string;
+}
+export declare function parseFindingLifecycle(line: string): FindingLifecycleMetadata;
+export declare function buildLifecycleComments(lifecycle: Partial<FindingLifecycleMetadata> | undefined, fallbackDate?: string): string;
+export declare function stripLifecycleComments(line: string): string;
+export declare function isInactiveFindingLine(line: string): boolean;
+export type ContradictionResolution = "keep_a" | "keep_b" | "keep_both" | "retract_both";
+export declare function supersedeFinding(phrenPath: string, project: string, findingText: string, supersededBy: string): PhrenResult<{
+    finding: string;
+    superseded_by: string;
+    status: FindingLifecycleStatus;
+}>;
+export declare function retractFinding(phrenPath: string, project: string, findingText: string, reason: string): PhrenResult<{
+    finding: string;
+    reason: string;
+    status: FindingLifecycleStatus;
+}>;
+export declare function resolveFindingContradiction(phrenPath: string, project: string, findingA: string, findingB: string, resolution: ContradictionResolution): PhrenResult<{
+    resolution: ContradictionResolution;
+    finding_a: {
+        text: string;
+        status: FindingLifecycleStatus;
+    };
+    finding_b: {
+        text: string;
+        status: FindingLifecycleStatus;
+    };
+}>;

package/dist/governance/audit.d.ts

@@ -0,0 +1 @@
+export declare function recordRetrieval(phrenPath: string, file: string, section: string): void;

package/dist/governance/locks.d.ts

@@ -0,0 +1,3 @@
+export declare function withFileLock<T>(filePath: string, fn: () => T): T extends Promise<infer U> ? Promise<U> : T;
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function hasValidSchemaVersion(data: Record<string, unknown>): boolean;