@phren/cli 0.0.57 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ala Arab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/capabilities/cli.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityManifest } from "./types.js";
+export declare const cliManifest: CapabilityManifest;

package/dist/capabilities/index.d.ts

@@ -0,0 +1,7 @@
+export { ACTION_KEYS, type ActionKey, type CapabilityEntry, type CapabilityManifest } from "./types.js";
+export { cliManifest } from "./cli.js";
+export { mcpManifest } from "./mcp.js";
+export { vscodeManifest } from "./vscode.js";
+export { webUiManifest } from "./web-ui.js";
+import type { CapabilityManifest } from "./types.js";
+export declare const ALL_MANIFESTS: CapabilityManifest[];

package/dist/capabilities/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityManifest } from "./types.js";
+export declare const mcpManifest: CapabilityManifest;

package/dist/capabilities/types.d.ts

@@ -0,0 +1,12 @@
+export declare const ACTION_KEYS: readonly ["finding.add", "finding.remove", "finding.list", "finding.filter_by_date", "finding.pin", "task.add", "task.complete", "task.remove", "task.update", "task.list", "task.pin", "task.github_link", "hook.list", "hook.toggle", "hook.toggle_per_project", "hook.custom_crud", "hook.errors", "search.fts", "search.fragment", "search.related_docs", "search.history", "graph.read", "graph.visualize", "graph.link_findings", "config.get", "config.set", "health.check", "health.doctor_fix", "health.sync", "session.start", "session.end", "skill.list", "skill.read", "skill.enable", "skill.write", "project.list", "project.manage", "project.summary", "export.project", "import.project", "profile.switch", "profile.list"];
+export type ActionKey = typeof ACTION_KEYS[number];
+export interface CapabilityEntry {
+    implemented: boolean;
+    handler?: string;
+    reason?: string;
+}
+export interface CapabilityManifest {
+    surface: "cli" | "mcp" | "vscode" | "web-ui";
+    version: string;
+    actions: Record<ActionKey, CapabilityEntry>;
+}

package/dist/capabilities/vscode.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityManifest } from "./types.js";
+export declare const vscodeManifest: CapabilityManifest;

package/dist/capabilities/web-ui.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityManifest } from "./types.js";
+export declare const webUiManifest: CapabilityManifest;

package/dist/cli/actions.d.ts

@@ -0,0 +1,16 @@
+import { type SearchOptions } from "./search.js";
+export declare function handleSearch(opts: SearchOptions, profile: string): Promise<void>;
+export declare function handleFragmentSearch(args: string[], profile: string): Promise<void>;
+export declare function handleRelatedDocs(args: string[], profile: string): Promise<void>;
+export declare function handleAddFinding(project: string, learning: string): Promise<void>;
+export declare function handlePinCanonical(project: string, memory: string): Promise<void>;
+export declare function handleTruths(project: string): Promise<void>;
+export declare function handleDoctor(args: string[]): Promise<void>;
+export declare function handleStatus(): Promise<void>;
+export declare function handleQualityFeedback(args: string[]): Promise<void>;
+export declare function handleMemoryUi(args: string[]): Promise<void>;
+export declare function handleShell(args: string[], profile: string): Promise<void>;
+export declare function handleUpdate(args: string[]): Promise<void>;
+export declare function handleReview(args: string[]): Promise<void>;
+export declare function handleConsolidationStatus(args: string[]): Promise<void>;
+export declare function handleSessionContext(): void;

package/dist/cli/cli.d.ts

@@ -0,0 +1,3 @@
+export { detectTaskIntent, parseHookInput, applyTrustFilter, rankResults, selectSnippets, buildHookOutput, trackSessionMetrics, filterTaskByPriority, parseCitations, validateCitation, annotateStale, getProjectGlobBoost, clearProjectGlobCache, clearCitationValidCache, filterConversationInsightsForProactivity, extractToolFindings, filterToolFindingsForProactivity, type HookPromptInput, type SelectedSnippet, } from "./hooks.js";
+export { scoreFindingCandidate } from "./extract.js";
+export declare function runCliCommand(command: string, args: string[]): Promise<void | import("./govern.js").GovernanceSummary>;

package/dist/cli/config.d.ts

@@ -0,0 +1,24 @@
+import { type FindingSensitivityLevel } from "../shared/governance.js";
+export declare function checkProjectInProfile(phrenPath: string, project: string): string | null;
+export declare function buildProactivitySnapshot(phrenPath: string): {
+    path: string;
+    configured: {
+        proactivity: "high" | "medium" | "low" | null;
+        proactivityFindings: "high" | "medium" | "low" | null;
+        proactivityTask: "high" | "medium" | "low" | null;
+    };
+    effective: {
+        proactivity: "high" | "medium" | "low";
+        proactivityFindings: "high" | "medium" | "low";
+        proactivityTask: "high" | "medium" | "low";
+    };
+};
+export declare function handleConfig(args: string[]): Promise<void>;
+export declare const FINDING_SENSITIVITY_CONFIG: Record<FindingSensitivityLevel, {
+    sessionCap: number;
+    proactivityFindings: string;
+    agentInstruction: string;
+}>;
+export declare function handleIndexPolicy(args: string[]): Promise<void>;
+export declare function handleRetentionPolicy(args: string[]): Promise<void>;
+export declare function handleWorkflowPolicy(args: string[]): Promise<void>;

package/dist/cli/extract.d.ts

@@ -0,0 +1,22 @@
+import type { FindingProvenanceSource } from "../content/citation.js";
+export declare function parseGitLogRecords(cwd: string, days: number): Array<{
+    hash: string;
+    subject: string;
+    body: string;
+}>;
+interface Candidate {
+    text: string;
+    score: number;
+    commit?: string;
+    file?: string;
+    sourceText?: string;
+}
+export declare function runGhJson<T>(cwd: string, args: string[]): Promise<T | null>;
+export declare function ghCachePath(repoRoot: string): string;
+export declare function mineGithubCandidates(repoRoot: string): Promise<Candidate[]>;
+export declare function scoreFindingCandidate(subject: string, body: string): {
+    score: number;
+    text: string;
+} | null;
+export declare function handleExtractMemories(projectArg?: string, cwdArg?: string, silent?: boolean, sessionId?: string, source?: FindingProvenanceSource): Promise<void>;
+export {};

package/dist/cli/govern.d.ts

@@ -0,0 +1,11 @@
+export interface GovernanceSummary {
+    projects: number;
+    staleCount: number;
+    conflictCount: number;
+    reviewCount: number;
+}
+export declare function handleGovernMemories(projectArg?: string, silent?: boolean, dryRun?: boolean): Promise<GovernanceSummary>;
+export declare function handlePruneMemories(args?: string[]): Promise<void>;
+export declare function handleConsolidateMemories(args?: string[]): Promise<void>;
+export declare function handleMaintain(args: string[]): Promise<void | GovernanceSummary>;
+export declare function handleBackgroundMaintenance(projectArg?: string): Promise<void>;

package/dist/cli/graph.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CLI: phren graph [--project <name>] [--limit <n>]
+ * Displays the fragment knowledge graph as a table.
+ */
+export declare function handleGraphRead(args: string[]): Promise<void>;
+/**
+ * CLI: phren graph link <project> <finding_text> <fragment_name>
+ * Links a finding to a fragment manually.
+ */
+export declare function handleGraphLink(args: string[]): Promise<void>;
+/**
+ * CLI: phren graph <subcommand>
+ * Routes graph subcommands.
+ */
+export declare function handleGraphNamespace(args: string[]): Promise<void>;

package/dist/cli/hooks-citations.d.ts

@@ -0,0 +1,8 @@
+import { type FindingCitation } from "../content/citation.js";
+export declare function clearCitationValidCache(): void;
+export interface ParsedCitation {
+    citation?: FindingCitation;
+}
+export declare function parseCitations(text: string): ParsedCitation[];
+export declare function validateCitation(citation: ParsedCitation): boolean;
+export declare function annotateStale(snippet: string): string;

package/dist/cli/hooks-context.d.ts

@@ -0,0 +1,34 @@
+import { readRootManifest } from "../shared.js";
+export interface HookContext {
+    phrenPath: string;
+    profile: string;
+    cwd: string;
+    hookTool: string;
+    activeProject: string | null;
+    hooksEnabled: boolean;
+    toolHookEnabled: boolean;
+    manifest: ReturnType<typeof readRootManifest>;
+}
+/** Build a HookContext from the current process environment. */
+export declare function buildHookContext(): HookContext;
+export type HookEvent = "SessionStart" | "Stop" | "UserPromptSubmit" | "PostToolUse";
+/** Check common hook guards. Returns a reason string if the hook should NOT run, null if OK. */
+export declare function checkHookGuard(ctx: HookContext, event: HookEvent): string | null;
+/** Log a guard skip and optionally update runtime health. */
+export declare function handleGuardSkip(ctx: HookContext, hookName: string, reason: string, healthUpdate?: Record<string, unknown>): void;
+export { debugLog, appendAuditLog, getPhrenPath, readRootManifest, sessionMarker, runtimeFile, EXEC_TIMEOUT_MS, getProjectDirs, findProjectNameCaseInsensitive, homePath, } from "../shared.js";
+export { updateRuntimeHealth, buildSyncStatus, getWorkflowPolicy, withFileLock, appendReviewQueue, recordFeedback, getQualityMultiplier, } from "../shared/governance.js";
+export { detectProject } from "../shared/index.js";
+export { isProjectHookEnabled, readProjectConfig, getProjectSourcePath } from "../project-config.js";
+export { resolveRuntimeProfile } from "../runtime-profile.js";
+export { detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, } from "../init/setup.js";
+export { getProactivityLevelForTask, getProactivityLevelForFindings } from "../proactivity.js";
+export { hasExplicitFindingSignal, shouldAutoCaptureFindingsForLevel } from "../proactivity.js";
+export { FINDING_SENSITIVITY_CONFIG } from "./config.js";
+export { isFeatureEnabled, errorMessage } from "../utils.js";
+export { bootstrapPhrenDotEnv } from "../phren-dotenv.js";
+export { finalizeTaskSession } from "../task/lifecycle.js";
+export { appendFindingJournal } from "../finding/journal.js";
+export { getHooksEnabledPreference } from "../init/init.js";
+export { isToolHookEnabled } from "../hooks.js";
+export { runDoctor } from "../link/link.js";

package/dist/cli/hooks-globs.d.ts

@@ -0,0 +1,2 @@
+export declare function clearProjectGlobCache(): void;
+export declare function getProjectGlobBoost(phrenPathLocal: string, project: string, cwd: string | undefined, changedFiles: Set<string> | undefined): number;

package/dist/cli/hooks-output.d.ts

@@ -0,0 +1,2 @@
+import type { SelectedSnippet, GitContext } from "../shared/retrieval.js";
+export declare function buildHookOutput(selected: SelectedSnippet[], usedTokens: number, intent: string, gitCtx: GitContext | null, detectedProject: string | null, stage: Record<string, number>, tokenBudget: number, phrenPathLocal: string, sessionId?: string): string[];

package/dist/cli/hooks-session.d.ts

@@ -0,0 +1,38 @@
+import type { SelectedSnippet } from "../shared/retrieval.js";
+export type { HookContext } from "./hooks-context.js";
+export { buildHookContext, handleGuardSkip } from "./hooks-context.js";
+export declare function getUntrackedProjectNotice(phrenPath: string, cwd: string): string | null;
+export declare function getSessionStartOnboardingNotice(phrenPath: string, cwd: string, activeProject: string | null): string | null;
+export interface GitContext {
+    branch: string;
+    changedFiles: Set<string>;
+}
+export declare function getGitContext(cwd?: string): GitContext | null;
+export declare function trackSessionMetrics(phrenPathLocal: string, sessionId: string, selected: SelectedSnippet[]): void;
+export declare function resolveSubprocessArgs(command: string): string[] | null;
+export declare function handleHookSessionStart(): Promise<void>;
+/**
+ * Extract potential insights from conversation text using keyword heuristics.
+ * Returns lines that contain insight-signal words and look like actionable knowledge.
+ */
+export declare function extractConversationInsights(text: string): string[];
+export declare function filterConversationInsightsForProactivity(insights: string[], level?: "high" | "medium" | "low"): string[];
+export declare function handleHookStop(): Promise<void>;
+export declare function handleBackgroundSync(): Promise<void>;
+export declare function handleHookContext(): Promise<void>;
+export declare function handleHookTool(): Promise<void>;
+interface LearningCandidate {
+    text: string;
+    confidence: number;
+    explicit?: boolean;
+}
+export declare function filterToolFindingsForProactivity(candidates: Array<{
+    text: string;
+    confidence: number;
+    explicit?: boolean;
+}>, level?: "high" | "medium" | "low"): Array<{
+    text: string;
+    confidence: number;
+    explicit?: boolean;
+}>;
+export declare function extractToolFindings(toolName: string, input: Record<string, unknown>, responseStr: string): LearningCandidate[];

package/dist/cli/hooks.d.ts

@@ -0,0 +1,12 @@
+export { parseCitations, validateCitation, annotateStale, clearCitationValidCache, type ParsedCitation, } from "./hooks-citations.js";
+export { getProjectGlobBoost, clearProjectGlobCache, } from "./hooks-globs.js";
+export { detectTaskIntent, filterTaskByPriority, searchDocuments, applyTrustFilter, rankResults, selectSnippets, type SelectedSnippet, } from "../shared/retrieval.js";
+export { buildHookOutput, } from "./hooks-output.js";
+export { handleHookSessionStart, handleHookStop, handleBackgroundSync, handleHookContext, handleHookTool, trackSessionMetrics, filterConversationInsightsForProactivity, extractToolFindings, filterToolFindingsForProactivity, resolveSubprocessArgs, } from "./hooks-session.js";
+export interface HookPromptInput {
+    prompt: string;
+    cwd?: string;
+    sessionId?: string;
+}
+export declare function parseHookInput(raw: string): HookPromptInput | null;
+export declare function handleHookPrompt(): Promise<void>;

package/dist/cli/namespaces.d.ts

@@ -0,0 +1,11 @@
+export declare function handleSkillsNamespace(args: string[], profile: string): void;
+export declare function handleHooksNamespace(args: string[]): void;
+export declare function handleSkillList(profile: string, project?: string): void;
+export declare function handleDetectSkills(args: string[], profile: string): void;
+export declare function handleProjectsNamespace(args: string[], profile: string): Promise<void>;
+export declare function handleTaskNamespace(args: string[]): Promise<void>;
+export declare function handleFindingNamespace(args: string[]): Promise<void>;
+export declare function handleStoreNamespace(args: string[]): Promise<void>;
+export declare function handleProfileNamespace(args: string[]): void;
+export declare function handlePromoteNamespace(args: string[]): Promise<void>;
+export declare function handleReviewNamespace(args: string[]): Promise<void>;

package/dist/cli/ops.d.ts

@@ -0,0 +1,5 @@
+export declare function handleTaskView(profile: string): void;
+export declare function handleSessionsView(args: string[]): Promise<void>;
+export declare function handleQuickstart(): Promise<void>;
+export declare function handleDebugInjection(args: string[], profile: string): Promise<void>;
+export declare function handleInspectIndex(args: string[], profile: string): Promise<void>;

package/dist/cli/search.d.ts

@@ -0,0 +1,38 @@
+export interface SearchOptions {
+    query: string;
+    limit: number;
+    project?: string;
+    type?: string;
+    showHistory?: boolean;
+    fromHistory?: number;
+    searchAll?: boolean;
+}
+export declare function parseSearchArgs(phrenPath: string, args: string[]): SearchOptions | null;
+export declare function runSearch(opts: SearchOptions, phrenPath: string, profile: string): Promise<{
+    lines: string[];
+    exitCode: number;
+}>;
+export declare function runFragmentSearch(query: string, phrenPath: string, profile: string, opts: {
+    project?: string;
+    limit?: number;
+}): Promise<{
+    lines: string[];
+    exitCode: number;
+}>;
+export declare function parseFragmentSearchArgs(args: string[]): {
+    query: string;
+    project?: string;
+    limit?: number;
+} | null;
+export declare function runRelatedDocs(entity: string, phrenPath: string, profile: string, opts: {
+    project?: string;
+    limit?: number;
+}): Promise<{
+    lines: string[];
+    exitCode: number;
+}>;
+export declare function parseRelatedDocsArgs(args: string[]): {
+    entity: string;
+    project?: string;
+    limit?: number;
+} | null;

package/dist/cli/team.d.ts

@@ -0,0 +1 @@
+export declare function handleTeamNamespace(args: string[]): Promise<void>;

package/dist/cli-hooks-git.d.ts

@@ -0,0 +1,35 @@
+import type { SelectedSnippet } from "./shared/retrieval.js";
+export interface GitContext {
+    branch: string;
+    changedFiles: Set<string>;
+}
+export declare function getGitContext(cwd?: string): GitContext | null;
+export interface SessionMetric {
+    prompts: number;
+    keys: Record<string, number>;
+    lastChangedCount: number;
+    lastKeys: string[];
+    lastSeen?: string;
+}
+export declare function parseSessionMetrics(phrenPathLocal: string): Record<string, SessionMetric>;
+export declare function writeSessionMetrics(phrenPathLocal: string, data: Record<string, SessionMetric>): void;
+export declare function updateSessionMetrics(phrenPathLocal: string, updater: (data: Record<string, SessionMetric>) => void): void;
+export declare function trackSessionMetrics(phrenPathLocal: string, sessionId: string, selected: SelectedSnippet[]): void;
+export declare function isTransientGitError(message: string): boolean;
+export declare function shouldRetryGitCommand(args: string[]): boolean;
+export declare function runBestEffortGit(args: string[], cwd: string): Promise<{
+    ok: boolean;
+    output?: string;
+    error?: string;
+}>;
+export declare function countUnsyncedCommits(cwd: string): Promise<number>;
+export declare function isMergeableMarkdown(relPath: string): boolean;
+export declare function snapshotLocalMergeableFiles(cwd: string): Promise<Map<string, string>>;
+export declare function reconcileMergeableFiles(cwd: string, snapshots: Map<string, string>): Promise<boolean>;
+export declare function recoverPushConflict(cwd: string): Promise<{
+    ok: boolean;
+    detail: string;
+    pullStatus: "ok" | "error";
+    pullDetail: string;
+}>;
+export declare function resolveSubprocessArgs(command: string): string[] | null;

package/dist/cli-hooks-prompt.d.ts

@@ -0,0 +1,18 @@
+export declare function handleHookContext(): Promise<void>;
+export declare function handleHookTool(): Promise<void>;
+interface LearningCandidate {
+    text: string;
+    confidence: number;
+    explicit?: boolean;
+}
+export declare function filterToolFindingsForProactivity(candidates: Array<{
+    text: string;
+    confidence: number;
+    explicit?: boolean;
+}>, level?: "high" | "medium" | "low"): Array<{
+    text: string;
+    confidence: number;
+    explicit?: boolean;
+}>;
+export declare function extractToolFindings(toolName: string, input: Record<string, unknown>, responseStr: string): LearningCandidate[];
+export {};

package/dist/cli-hooks-session-handlers.d.ts

@@ -0,0 +1,3 @@
+export declare function getUntrackedProjectNotice(phrenPath: string, cwd: string): string | null;
+export declare function getSessionStartOnboardingNotice(phrenPath: string, cwd: string, activeProject: string | null): string | null;
+export declare function handleHookSessionStart(): Promise<void>;

package/dist/cli-hooks-stop.d.ts

@@ -0,0 +1,11 @@
+/** Read JSON from stdin if it's not a TTY. Returns null if stdin is a TTY or parsing fails. */
+export declare function readStdinJson<T>(): T | null;
+/**
+ * Extract potential insights from conversation text using keyword heuristics.
+ * Returns lines that contain insight-signal words and look like actionable knowledge.
+ */
+export declare function extractConversationInsights(text: string): string[];
+export declare function filterConversationInsightsForProactivity(insights: string[], level?: "high" | "medium" | "low"): string[];
+export declare function getSessionCap(): number;
+export declare function handleHookStop(): Promise<void>;
+export declare function handleBackgroundSync(): Promise<void>;

package/dist/content/archive.d.ts

@@ -0,0 +1,13 @@
+import { type PhrenResult } from "../shared.js";
+/**
+ * Count active (non-archived) finding entries in FINDINGS.md content.
+ * Entries inside archive blocks are considered archived.
+ * Supports structured archive markers and HTML details blocks.
+ */
+export declare function countActiveFindings(content: string): number;
+/**
+ * Archive the oldest entries from FINDINGS.md into reference/{topic}.md files.
+ * Keeps `keepCount` most recent entries, archives the rest grouped by topic.
+ * Returns the number of entries archived.
+ */
+export declare function autoArchiveToReference(phrenPath: string, project: string, keepCount: number): PhrenResult<number>;

package/dist/content/citation.d.ts

@@ -0,0 +1,50 @@
+import type { RetentionPolicy } from "../shared/governance.js";
+export interface FindingCitation {
+    created_at: string;
+    repo?: string;
+    file?: string;
+    line?: number;
+    commit?: string;
+    supersedes?: string;
+    task_item?: string;
+}
+export declare const FINDING_PROVENANCE_SOURCES: readonly ["human", "agent", "hook", "extract", "consolidation", "unknown"];
+export type FindingProvenanceSource = (typeof FINDING_PROVENANCE_SOURCES)[number];
+export declare function isFindingProvenanceSource(value: string | undefined): value is FindingProvenanceSource;
+export interface FindingProvenance {
+    source?: FindingProvenanceSource;
+    machine?: string;
+    actor?: string;
+    tool?: string;
+    model?: string;
+    session_id?: string;
+    scope?: string;
+}
+export interface FindingTrustIssue {
+    date: string;
+    bullet: string;
+    reason: "stale" | "invalid_citation";
+}
+export interface TrustFilterOptions {
+    ttlDays?: number;
+    minConfidence?: number;
+    decay?: Partial<RetentionPolicy["decay"]>;
+    project?: string;
+    highImpactFindingIds?: Set<string>;
+}
+export declare function getHeadCommit(cwd: string): string | undefined;
+export declare function getRepoRoot(cwd: string): string | undefined;
+export declare function inferCitationLocation(repoPath: string, commit: string): {
+    file?: string;
+    line?: number;
+};
+export declare function buildCitationComment(citation: FindingCitation): string;
+export declare function buildSourceComment(source: FindingProvenance): string;
+export declare function parseSourceComment(line: string): FindingProvenance | null;
+export declare function parseCitationComment(line: string): FindingCitation | null;
+export declare function validateFindingCitation(citation: FindingCitation): boolean;
+export declare function filterTrustedFindings(content: string, ttlDays: number): string;
+export declare function filterTrustedFindingsDetailed(content: string, opts: number | TrustFilterOptions): {
+    content: string;
+    issues: FindingTrustIssue[];
+};

package/dist/content/dedup.d.ts

@@ -0,0 +1,55 @@
+export declare function callLlm(prompt: string, signal?: AbortSignal, maxTokens?: number): Promise<string>;
+/**
+ * Strip all common finding metadata:
+ * - HTML comments: <!-- ... -->
+ * - "migrated from" annotations: (migrated from ...)
+ * - Leading bullet dash: "- " at the start of the string
+ */
+export declare function stripMetadata(s: string): string;
+export declare function jaccardTokenize(text: string): Set<string>;
+export declare function jaccardSimilarity(a: Set<string>, b: Set<string>): number;
+/**
+ * Scan existing findings for proper nouns / tool names that appear in 2+ bullets.
+ * Results are cached in .runtime/project-entities-{project}.json (1h TTL or
+ * invalidated when FINDINGS.md changes).
+ */
+export declare function extractDynamicEntities(phrenPath: string, project: string): Set<string>;
+/** Returns existing learning lines that appear to conflict with newFinding. */
+export declare function detectConflicts(newFinding: string, existingLines: string[], dynamicEntities?: Set<string>): string[];
+export declare function isDuplicateFinding(existingContent: string, newLearning: string, threshold?: number): boolean;
+/**
+ * Normalize known observation tags in learning text to lowercase.
+ * Returns the normalized text and a warning if unknown bracket tags are found.
+ */
+export declare function normalizeObservationTags(text: string): {
+    text: string;
+    warning?: string;
+};
+/**
+ * Scan text for secrets and PII patterns. Returns the type of secret found, or null if clean.
+ */
+export declare function scanForSecrets(text: string): string | null;
+/**
+ * Resolve coreferences in learning text by replacing vague pronouns with concrete names.
+ */
+export declare function resolveCoref(text: string, context: {
+    project?: string;
+    file?: string;
+}): string;
+/**
+ * LLM-based semantic dedup check. Only called when PHREN_FEATURE_SEMANTIC_DEDUP=1.
+ * Must be called before addFindingToFile() since that function is sync.
+ * Returns true if the new learning is a semantic duplicate of any existing bullet.
+ */
+export declare function checkSemanticDedup(phrenPath: string, project: string, newLearning: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * LLM-based conflict check. Only called when PHREN_FEATURE_SEMANTIC_CONFLICT=1.
+ * Call after detectConflicts() in addFindingToFile flow.
+ * Returns conflict annotations to append to the bullet.
+ * Also scans global findings and other projects for cross-project contradictions.
+ * Has a 30-second total timeout; returns partial results if the deadline is hit.
+ */
+export declare function checkSemanticConflicts(phrenPath: string, project: string, newFinding: string, signal?: AbortSignal): Promise<{
+    annotations: string[];
+    checked: boolean;
+}>;

package/dist/content/learning.d.ts

@@ -0,0 +1,29 @@
+import { type PhrenResult } from "../shared.js";
+import { type FindingCitation, type FindingProvenanceSource } from "./citation.js";
+interface AddFindingOptions {
+    extraAnnotations?: string[];
+    sessionId?: string;
+    source?: FindingProvenanceSource;
+    scope?: string;
+}
+export interface AddFindingResult {
+    message: string;
+    status: "added" | "created" | "skipped";
+}
+export declare function autoDetectFindingType(text: string): string | null;
+export declare function upsertCanonical(phrenPath: string, project: string, memory: string): PhrenResult<string>;
+export declare function addFindingToFile(phrenPath: string, project: string, learning: string, citationInput?: Partial<FindingCitation>, opts?: AddFindingOptions): PhrenResult<AddFindingResult>;
+export declare function addFindingsToFile(phrenPath: string, project: string, learnings: string[], opts?: {
+    extraAnnotationsByFinding?: string[][];
+    sessionId?: string;
+    source?: FindingProvenanceSource;
+    scope?: string;
+}): PhrenResult<{
+    added: string[];
+    skipped: string[];
+    rejected: {
+        text: string;
+        reason: string;
+    }[];
+}>;
+export {};