@phren/cli 0.1.14 → 0.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +1 -1
  2. package/dist/capabilities/cli.js +1 -1
  3. package/dist/capabilities/mcp.js +1 -1
  4. package/dist/capabilities/vscode.js +1 -1
  5. package/dist/capabilities/web-ui.js +1 -1
  6. package/dist/cli/extract.js +2 -1
  7. package/dist/cli/govern.js +3 -2
  8. package/dist/cli/namespaces-projects.js +7 -6
  9. package/dist/cli/ops.js +2 -2
  10. package/dist/cli/session-start.js +2 -1
  11. package/dist/cli/team.js +7 -5
  12. package/dist/cli-hooks-session-handlers.js +2 -1
  13. package/dist/content/archive.js +2 -1
  14. package/dist/content/citation.d.ts +4 -0
  15. package/dist/content/citation.js +14 -5
  16. package/dist/content/dedup.js +6 -5
  17. package/dist/content/learning.d.ts +1 -3
  18. package/dist/content/learning.js +17 -62
  19. package/dist/content/validate.js +2 -1
  20. package/dist/core/project.js +2 -1
  21. package/dist/data/access.d.ts +2 -7
  22. package/dist/data/access.js +14 -20
  23. package/dist/finding/journal.js +2 -2
  24. package/dist/finding/lifecycle.js +2 -1
  25. package/dist/governance/policy.d.ts +2 -0
  26. package/dist/governance/policy.js +2 -2
  27. package/dist/hooks.js +38 -2
  28. package/dist/init/init-uninstall.js +2 -1
  29. package/dist/init/setup.js +5 -4
  30. package/dist/init-uninstall.js +2 -1
  31. package/dist/link/checksums.js +2 -1
  32. package/dist/link/context.js +2 -1
  33. package/dist/link/doctor.js +4 -3
  34. package/dist/link/link.js +2 -1
  35. package/dist/phren-paths.js +3 -2
  36. package/dist/profile-store.d.ts +1 -0
  37. package/dist/profile-store.js +15 -16
  38. package/dist/project-topics.js +4 -3
  39. package/dist/shell/input.js +3 -3
  40. package/dist/status.js +2 -2
  41. package/dist/tools/data.js +4 -4
  42. package/dist/tools/extract.js +3 -2
  43. package/dist/tools/finding.js +10 -15
  44. package/dist/tools/search.js +5 -14
  45. package/dist/tools/session.js +2 -16
  46. package/dist/ui/data.js +6 -5
  47. package/dist/ui/server.js +3 -3
  48. package/package.json +1 -1
package/README.md CHANGED
@@ -4,7 +4,7 @@ MCP server that indexes your personal phren and exposes it to AI agents via full
4
4
 
5
5
  On startup it walks your phren directory, reads all `.md` files, and builds an in-memory SQLite FTS5 index.
6
6
 
7
- Public surface: 53 MCP tools across 12 modules (search, tasks, findings, memory, data, graph, sessions, ops/review, skills, hooks, config, extraction).
7
+ Public surface: 54 MCP tools across 12 modules (search, tasks, findings, memory, data, graph, sessions, ops/review, skills, hooks, config, extraction).
8
8
 
9
9
  Notable shipped capabilities:
10
10
  - finding lifecycle tools: `supersede_finding`, `retract_finding`, `resolve_contradiction`, `get_contradictions`
@@ -1,6 +1,6 @@
1
1
  export const cliManifest = {
2
2
  surface: "cli",
3
- version: "0.0.19",
3
+ version: "0.1.16",
4
4
  actions: {
5
5
  // Finding management
6
6
  "finding.add": { implemented: true, handler: "cli-actions.ts:handleAddFinding" },
@@ -1,6 +1,6 @@
1
1
  export const mcpManifest = {
2
2
  surface: "mcp",
3
- version: "0.0.19",
3
+ version: "0.1.16",
4
4
  actions: {
5
5
  // Finding management
6
6
  "finding.add": { implemented: true, handler: "index.ts:add_finding" },
@@ -1,6 +1,6 @@
1
1
  export const vscodeManifest = {
2
2
  surface: "vscode",
3
- version: "0.0.19",
3
+ version: "0.1.16",
4
4
  actions: {
5
5
  // Finding management
6
6
  "finding.add": { implemented: true, handler: "extension.ts:phren.addFinding" },
@@ -1,6 +1,6 @@
1
1
  export const webUiManifest = {
2
2
  surface: "web-ui",
3
- version: "0.0.19",
3
+ version: "0.1.16",
4
4
  actions: {
5
5
  // Finding management
6
6
  "finding.add": { implemented: false, reason: "Web UI is read-only for findings (review queue only)" },
@@ -4,6 +4,7 @@ import { detectProject } from "../shared/index.js";
4
4
  import { commandExists } from "../hooks.js";
5
5
  import { runGit as runGitShared, isFeatureEnabled, clampInt, errorMessage, resolveExecCommand } from "../utils.js";
6
6
  import { appendFindingJournal, compactFindingJournals } from "../finding/journal.js";
7
+ import { FINDINGS_FILENAME } from "../data/access.js";
7
8
  import { getProactivityLevelForTask, getProactivityLevelForFindings, shouldAutoCaptureFindingsForLevel } from "../proactivity.js";
8
9
  import * as fs from "fs";
9
10
  import * as os from "os";
@@ -276,7 +277,7 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
276
277
  continue;
277
278
  const line = `${c.text}${c.commit ? ` (source commit ${c.commit.slice(0, 8)})` : ""}`;
278
279
  if (c.text.startsWith("CI failure pattern:")) {
279
- const key = entryScoreKey(project, "FINDINGS.md", line);
280
+ const key = entryScoreKey(project, FINDINGS_FILENAME, line);
280
281
  recordFeedback(getPhrenPath(), key, "regression");
281
282
  }
282
283
  if (c.score >= threshold) {
@@ -5,6 +5,7 @@ import * as fs from "fs";
5
5
  import * as path from "path";
6
6
  import { handleExtractMemories } from "./extract.js";
7
7
  import { errorMessage } from "../utils.js";
8
+ import { FINDINGS_FILENAME } from "../data/access.js";
8
9
  import { logger } from "../logger.js";
9
10
  import { compactFindingJournals } from "../finding/journal.js";
10
11
  import { resolveRuntimeProfile } from "../runtime-profile.js";
@@ -72,7 +73,7 @@ export async function handleGovernMemories(projectArg, silent = false, dryRun =
72
73
  let conflictCount = 0;
73
74
  let reviewCount = 0;
74
75
  for (const project of projects) {
75
- const learningsPath = path.join(getPhrenPath(), project, "FINDINGS.md");
76
+ const learningsPath = path.join(getPhrenPath(), project, FINDINGS_FILENAME);
76
77
  if (!fs.existsSync(learningsPath))
77
78
  continue;
78
79
  const content = fs.readFileSync(learningsPath, "utf8");
@@ -162,7 +163,7 @@ export async function handlePruneMemories(args = []) {
162
163
  }
163
164
  let ttlExpired = 0;
164
165
  for (const project of projects) {
165
- const learningsPath = path.join(getPhrenPath(), project, "FINDINGS.md");
166
+ const learningsPath = path.join(getPhrenPath(), project, FINDINGS_FILENAME);
166
167
  if (!fs.existsSync(learningsPath))
167
168
  continue;
168
169
  const content = fs.readFileSync(learningsPath, "utf8");
@@ -4,6 +4,7 @@ import { expandHomePath, findArchivedProjectNameCaseInsensitive, findProjectName
4
4
  import { isValidProjectName, errorMessage } from "../utils.js";
5
5
  import { logger } from "../logger.js";
6
6
  import { TASK_FILE_ALIASES } from "../data/tasks.js";
7
+ import { FINDINGS_FILENAME } from "../data/access.js";
7
8
  import { PROJECT_OWNERSHIP_MODES, parseProjectOwnershipMode, writeProjectConfig, writeProjectHookConfig, } from "../project-config.js";
8
9
  import { resolveProjectStorePath, parseMcpToggle } from "./namespaces-utils.js";
9
10
  export async function handleProjectsNamespace(args, profile) {
@@ -108,7 +109,7 @@ export async function handleProjectsNamespace(args, profile) {
108
109
  const learningsResult = readFindings(storePath, name);
109
110
  if (learningsResult.ok)
110
111
  exported.learnings = learningsResult.data;
111
- const findingsPath = path.join(projectDir, "FINDINGS.md");
112
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
112
113
  if (fs.existsSync(findingsPath))
113
114
  exported.findingsRaw = fs.readFileSync(findingsPath, "utf8");
114
115
  const taskResult = readTasks(storePath, name);
@@ -186,8 +187,8 @@ export async function handleProjectsNamespace(args, profile) {
186
187
  imported.push("CLAUDE.md");
187
188
  }
188
189
  if (typeof decoded.findingsRaw === "string") {
189
- fs.writeFileSync(path.join(stagedProjectDir, "FINDINGS.md"), decoded.findingsRaw);
190
- imported.push("FINDINGS.md");
190
+ fs.writeFileSync(path.join(stagedProjectDir, FINDINGS_FILENAME), decoded.findingsRaw);
191
+ imported.push(FINDINGS_FILENAME);
191
192
  }
192
193
  else if (Array.isArray(decoded.learnings) && decoded.learnings.length > 0) {
193
194
  const date = new Date().toISOString().slice(0, 10);
@@ -197,8 +198,8 @@ export async function handleProjectsNamespace(args, profile) {
197
198
  lines.push(`- ${item.text}`);
198
199
  }
199
200
  lines.push("");
200
- fs.writeFileSync(path.join(stagedProjectDir, "FINDINGS.md"), lines.join("\n"));
201
- imported.push("FINDINGS.md");
201
+ fs.writeFileSync(path.join(stagedProjectDir, FINDINGS_FILENAME), lines.join("\n"));
202
+ imported.push(FINDINGS_FILENAME);
202
203
  }
203
204
  if (typeof decoded.taskRaw === "string") {
204
205
  fs.writeFileSync(path.join(stagedProjectDir, TASKS_FILENAME), decoded.taskRaw);
@@ -314,7 +315,7 @@ function handleProjectsList(profile) {
314
315
  dirFiles = new Set();
315
316
  }
316
317
  const tags = [];
317
- if (dirFiles.has("FINDINGS.md"))
318
+ if (dirFiles.has(FINDINGS_FILENAME))
318
319
  tags.push("findings");
319
320
  if (TASK_FILE_ALIASES.some((filename) => dirFiles.has(filename)))
320
321
  tags.push("tasks");
package/dist/cli/ops.js CHANGED
@@ -3,7 +3,7 @@ import * as path from "path";
3
3
  import { execFileSync } from "child_process";
4
4
  import { EXEC_TIMEOUT_MS, findProjectNameCaseInsensitive, getPhrenPath, normalizeProjectNameForCreate, } from "../shared.js";
5
5
  import { isValidProjectName, errorMessage } from "../utils.js";
6
- import { readTasksAcrossProjects, TASKS_FILENAME } from "../data/access.js";
6
+ import { readTasksAcrossProjects, TASKS_FILENAME, FINDINGS_FILENAME } from "../data/access.js";
7
7
  import { applyGravity } from "../data/tasks.js";
8
8
  import { buildIndex, queryRows } from "../shared/index.js";
9
9
  import { resolveSubprocessArgs } from "./hooks.js";
@@ -128,7 +128,7 @@ export async function handleQuickstart() {
128
128
  const projectDir = path.join(phrenPath, normalizedProjectName);
129
129
  if (!fs.existsSync(projectDir)) {
130
130
  fs.mkdirSync(projectDir, { recursive: true });
131
- fs.writeFileSync(path.join(projectDir, "FINDINGS.md"), `# ${normalizedProjectName} Findings\n`);
131
+ fs.writeFileSync(path.join(projectDir, FINDINGS_FILENAME), `# ${normalizedProjectName} Findings\n`);
132
132
  fs.writeFileSync(path.join(projectDir, TASKS_FILENAME), `# ${normalizedProjectName} Tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
133
133
  }
134
134
  console.log(`\n\u2713 phren ready. Project: ${normalizedProjectName}. Try: phren search 'your query'`);
@@ -7,6 +7,7 @@ import * as path from "path";
7
7
  import * as crypto from "crypto";
8
8
  import { buildHookContext, handleGuardSkip, debugLog, appendAuditLog, runtimeFile, sessionMarker, getProjectDirs, findProjectNameCaseInsensitive, updateRuntimeHealth, withFileLock, detectProject, isProjectHookEnabled, readProjectConfig, getProjectSourcePath, detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, errorMessage, resolveRuntimeProfile, } from "./hooks-context.js";
9
9
  import { TASKS_FILENAME } from "../data/tasks.js";
10
+ import { FINDINGS_FILENAME } from "../data/access.js";
10
11
  import { readInstallPreferences } from "../init/preferences.js";
11
12
  import { logger } from "../logger.js";
12
13
  import { sessionFileForId, readSessionStateFile, writeSessionStateFile, } from "../session/utils.js";
@@ -17,7 +18,7 @@ const SESSION_START_ONBOARDING_MARKER = "session-start-onboarding-v1";
17
18
  const SYNC_WARN_MARKER = "sync-broken-warned-v1";
18
19
  function projectHasBootstrapSignals(phrenPath, project) {
19
20
  const projectDir = path.join(phrenPath, project);
20
- const findingsPath = path.join(projectDir, "FINDINGS.md");
21
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
21
22
  if (fs.existsSync(findingsPath)) {
22
23
  const findings = fs.readFileSync(findingsPath, "utf8");
23
24
  if (/^-\s+/m.test(findings))
package/dist/cli/team.js CHANGED
@@ -6,6 +6,8 @@ import * as fs from "fs";
6
6
  import * as path from "path";
7
7
  import { execFileSync } from "child_process";
8
8
  import { getPhrenPath } from "../shared.js";
9
+ import { FINDINGS_FILENAME } from "../data/access.js";
10
+ import { TASKS_FILENAME } from "../data/tasks.js";
9
11
  import { isValidProjectName } from "../utils.js";
10
12
  import { addProjectToProfile, resolveActiveProfile } from "../profile-store.js";
11
13
  import { addStoreToRegistry, findStoreByName, generateStoreId, readTeamBootstrap, updateStoreProjects, } from "../store-registry.js";
@@ -81,7 +83,7 @@ async function handleTeamInit(args) {
81
83
  const globalDir = path.join(storePath, "global");
82
84
  fs.mkdirSync(globalDir, { recursive: true });
83
85
  atomicWriteText(path.join(globalDir, "CLAUDE.md"), `# ${name} Team Store\n\nShared knowledge for the ${name} team.\n`);
84
- atomicWriteText(path.join(globalDir, "FINDINGS.md"), `# global findings\n`);
86
+ atomicWriteText(path.join(globalDir, FINDINGS_FILENAME), `# global findings\n`);
85
87
  // Initialize git repo
86
88
  execFileSync("git", ["init"], {
87
89
  cwd: storePath,
@@ -230,11 +232,11 @@ async function handleTeamAddProject(args) {
230
232
  const journalDir = path.join(projectDir, "journal");
231
233
  fs.mkdirSync(journalDir, { recursive: true });
232
234
  // Scaffold project files
233
- if (!fs.existsSync(path.join(projectDir, "FINDINGS.md"))) {
234
- atomicWriteText(path.join(projectDir, "FINDINGS.md"), `# ${projectName} findings\n`);
235
+ if (!fs.existsSync(path.join(projectDir, FINDINGS_FILENAME))) {
236
+ atomicWriteText(path.join(projectDir, FINDINGS_FILENAME), `# ${projectName} findings\n`);
235
237
  }
236
- if (!fs.existsSync(path.join(projectDir, "tasks.md"))) {
237
- atomicWriteText(path.join(projectDir, "tasks.md"), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
238
+ if (!fs.existsSync(path.join(projectDir, TASKS_FILENAME))) {
239
+ atomicWriteText(path.join(projectDir, TASKS_FILENAME), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
238
240
  }
239
241
  if (!fs.existsSync(path.join(projectDir, "summary.md"))) {
240
242
  atomicWriteText(path.join(projectDir, "summary.md"), `# ${projectName}\n**What:** \n`);
@@ -10,12 +10,13 @@ import * as fs from "fs";
10
10
  import * as path from "path";
11
11
  import { spawnDetachedChild } from "./shared/process.js";
12
12
  import { TASKS_FILENAME } from "./data/tasks.js";
13
+ import { FINDINGS_FILENAME } from "./data/access.js";
13
14
  import { resolveSubprocessArgs as _resolveSubprocessArgs, runBestEffortGit, countUnsyncedCommits, } from "./cli-hooks-git.js";
14
15
  const SESSION_START_ONBOARDING_MARKER = "session-start-onboarding-v1";
15
16
  const SYNC_WARN_MARKER = "sync-broken-warned-v1";
16
17
  function projectHasBootstrapSignals(phrenPath, project) {
17
18
  const projectDir = path.join(phrenPath, project);
18
- const findingsPath = path.join(projectDir, "FINDINGS.md");
19
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
19
20
  if (fs.existsSync(findingsPath)) {
20
21
  const findings = fs.readFileSync(findingsPath, "utf8");
21
22
  if (/^-\s+/m.test(findings))
@@ -8,6 +8,7 @@ import { walkDirectory } from "../shared/data-utils.js";
8
8
  import { appendArchivedEntriesToTopicDoc, classifyTopicForText, readProjectTopics, topicReferencePath } from "../project-topics.js";
9
9
  import { isCitationLine, isArchiveStart, isArchiveEnd, stripComments } from "./metadata.js";
10
10
  import { logger } from "../logger.js";
11
+ import { FINDINGS_FILENAME } from "../data/access.js";
11
12
  /**
12
13
  * Count active (non-archived) finding entries in FINDINGS.md content.
13
14
  * Entries inside archive blocks are considered archived.
@@ -116,7 +117,7 @@ export function autoArchiveToReference(phrenPath, project, keepCount) {
116
117
  const resolvedDir = safeProjectPath(phrenPath, project);
117
118
  if (!resolvedDir || !fs.existsSync(resolvedDir))
118
119
  return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
119
- const learningsPath = path.join(resolvedDir, "FINDINGS.md");
120
+ const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
120
121
  if (!fs.existsSync(learningsPath))
121
122
  return phrenOk(0);
122
123
  // Consolidation lock to prevent concurrent runs for the same project (atomic create via wx flag).
@@ -40,6 +40,10 @@ export declare function inferCitationLocation(repoPath: string, commit: string):
40
40
  };
41
41
  export declare function buildCitationComment(citation: FindingCitation): string;
42
42
  export declare function buildSourceComment(source: FindingProvenance): string;
43
+ /** Build a standalone scope comment. Returns empty string if scope is unset or "shared". */
44
+ export declare function buildScopeComment(scope: string | undefined): string;
45
+ /** Parse a standalone `<!-- scope:VALUE -->` comment. */
46
+ export declare function parseScopeComment(line: string): string | undefined;
43
47
  export declare function parseSourceComment(line: string): FindingProvenance | null;
44
48
  export declare function parseCitationComment(line: string): FindingCitation | null;
45
49
  export declare function validateFindingCitation(citation: FindingCitation): boolean;
@@ -90,6 +90,20 @@ export function buildSourceComment(source) {
90
90
  parts.push(`scope:${source.scope}`);
91
91
  return parts.length > 0 ? `<!-- source:${parts.join(" ")} -->` : "";
92
92
  }
93
+ /** Build a standalone scope comment. Returns empty string if scope is unset or "shared". */
94
+ export function buildScopeComment(scope) {
95
+ if (!scope || scope === "shared")
96
+ return "";
97
+ return `<!-- scope:${scope} -->`;
98
+ }
99
+ /** Parse a standalone `<!-- scope:VALUE -->` comment. */
100
+ export function parseScopeComment(line) {
101
+ const m = line.match(/<!--\s*scope:(".*?"|\S+)\s*-->/);
102
+ if (!m)
103
+ return undefined;
104
+ const raw = m[1].replace(/^"|"$/g, "").trim();
105
+ return raw || undefined;
106
+ }
93
107
  export function parseSourceComment(line) {
94
108
  const sourceMatch = line.match(METADATA_REGEX.source);
95
109
  if (!sourceMatch)
@@ -416,11 +430,6 @@ export function filterTrustedFindingsDetailed(content, opts) {
416
430
  }
417
431
  if (!citation)
418
432
  confidence *= 0.8;
419
- const provenance = parseSourceComment(line)?.source ?? "unknown";
420
- if (provenance === "human")
421
- confidence *= 1.1;
422
- if (provenance === "extract")
423
- confidence *= 0.9;
424
433
  if (project && highImpactFindingIds?.size) {
425
434
  const findingId = findingIdFromLine(line);
426
435
  if (highImpactFindingIds.has(findingId))
@@ -6,6 +6,7 @@ import { isFeatureEnabled, safeProjectPath, errorMessage } from "../utils.js";
6
6
  import { UNIVERSAL_TECH_TERMS_RE, EXTRA_ENTITY_PATTERNS } from "../phren-core.js";
7
7
  import { isInactiveFindingLine } from "../finding/lifecycle.js";
8
8
  import { logger } from "../logger.js";
9
+ import { FINDINGS_FILENAME } from "../data/access.js";
9
10
  // ── LLM provider abstraction ────────────────────────────────────────────────
10
11
  const MAX_CACHE_ENTRIES = 500;
11
12
  function loadCache(cachePath) {
@@ -200,7 +201,7 @@ const DYNAMIC_ENTITY_RE = /\b(?:[A-Z][a-z]+(?:[A-Z][a-z]*)+|[A-Z]{2,8}|[A-Z][a-z
200
201
  */
201
202
  export function extractDynamicEntities(phrenPath, project) {
202
203
  try {
203
- const findingsPath = path.join(phrenPath, project, "FINDINGS.md");
204
+ const findingsPath = path.join(phrenPath, project, FINDINGS_FILENAME);
204
205
  if (!fs.existsSync(findingsPath))
205
206
  return new Set();
206
207
  const findingsStat = fs.statSync(findingsPath);
@@ -479,7 +480,7 @@ export async function checkSemanticDedup(phrenPath, project, newLearning, signal
479
480
  const resolvedDir = safeProjectPath(phrenPath, project);
480
481
  if (!resolvedDir)
481
482
  return false;
482
- const findingsPath = path.join(resolvedDir, "FINDINGS.md");
483
+ const findingsPath = path.join(resolvedDir, FINDINGS_FILENAME);
483
484
  if (!fs.existsSync(findingsPath))
484
485
  return false;
485
486
  const existingContent = fs.readFileSync(findingsPath, "utf8");
@@ -537,13 +538,13 @@ export async function checkSemanticConflicts(phrenPath, project, newFinding, sig
537
538
  // Collect bullet sources: { bullets, sourceProject } pairs
538
539
  const sources = [];
539
540
  // Current project
540
- const findingsPath = path.join(resolvedDir, "FINDINGS.md");
541
+ const findingsPath = path.join(resolvedDir, FINDINGS_FILENAME);
541
542
  if (fs.existsSync(findingsPath)) {
542
543
  const content = fs.readFileSync(findingsPath, "utf8");
543
544
  sources.push({ bullets: content.split("\n").filter((l) => l.startsWith("- ")), sourceProject: null });
544
545
  }
545
546
  // Global project findings
546
- const globalFindingsPath = path.join(phrenPath, "global", "FINDINGS.md");
547
+ const globalFindingsPath = path.join(phrenPath, "global", FINDINGS_FILENAME);
547
548
  if (fs.existsSync(globalFindingsPath)) {
548
549
  const content = fs.readFileSync(globalFindingsPath, "utf8");
549
550
  const bullets = content.split("\n").filter((l) => l.startsWith("- "));
@@ -557,7 +558,7 @@ export async function checkSemanticConflicts(phrenPath, project, newFinding, sig
557
558
  const otherProjects = entries
558
559
  .filter((e) => e.isDirectory() && e.name !== project && e.name !== "global" && !e.name.startsWith("."))
559
560
  .map((e) => {
560
- const fp = path.join(phrenPath, e.name, "FINDINGS.md");
561
+ const fp = path.join(phrenPath, e.name, FINDINGS_FILENAME);
561
562
  if (!fs.existsSync(fp))
562
563
  return null;
563
564
  try {
@@ -1,9 +1,8 @@
1
1
  import { type PhrenResult } from "../shared.js";
2
- import { type FindingCitation, type FindingProvenanceSource } from "./citation.js";
2
+ import { type FindingCitation } from "./citation.js";
3
3
  interface AddFindingOptions {
4
4
  extraAnnotations?: string[];
5
5
  sessionId?: string;
6
- source?: FindingProvenanceSource;
7
6
  scope?: string;
8
7
  }
9
8
  export interface AddFindingResult {
@@ -16,7 +15,6 @@ export declare function addFindingToFile(phrenPath: string, project: string, lea
16
15
  export declare function addFindingsToFile(phrenPath: string, project: string, learnings: string[], opts?: {
17
16
  extraAnnotationsByFinding?: string[][];
18
17
  sessionId?: string;
19
- source?: FindingProvenanceSource;
20
18
  scope?: string;
21
19
  }): PhrenResult<{
22
20
  added: string[];
@@ -5,14 +5,14 @@ import { debugLog, appendAuditLog, phrenOk, phrenErr, PhrenError } from "../shar
5
5
  import { normalizeMemoryScope } from "../shared.js";
6
6
  import { withFileLock } from "../shared/governance.js";
7
7
  import { isValidProjectName, safeProjectPath } from "../utils.js";
8
- import { getMachineName } from "../machine-identity.js";
9
- import { buildCitationComment, buildSourceComment, getHeadCommit, getRepoRoot, inferCitationLocation, isFindingProvenanceSource, } from "./citation.js";
8
+ import { buildCitationComment, buildScopeComment, getHeadCommit, getRepoRoot, inferCitationLocation, } from "./citation.js";
10
9
  import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCoref, detectConflicts, extractDynamicEntities } from "./dedup.js";
11
10
  import { validateFindingsFormat, validateFinding } from "./validate.js";
12
11
  import { countActiveFindings, autoArchiveToReference } from "./archive.js";
13
- import { resolveAutoFindingTaskItem, resolveFindingTaskReference, resolveFindingSessionId, } from "../finding/context.js";
12
+ import { resolveAutoFindingTaskItem, resolveFindingTaskReference, } from "../finding/context.js";
14
13
  import { buildLifecycleComments, extractFindingType, parseFindingLifecycle, stripLifecycleComments, } from "../finding/lifecycle.js";
15
14
  import { METADATA_REGEX, } from "./metadata.js";
15
+ import { FINDINGS_FILENAME } from "../data/access.js";
16
16
  /** Default cap for active findings before auto-archiving is triggered. */
17
17
  const DEFAULT_FINDINGS_CAP = 20;
18
18
  const LIFECYCLE_ANNOTATION_RE = METADATA_REGEX.lifecycleAnnotation;
@@ -42,51 +42,8 @@ function resolveInferredCitationRepo(citationInput) {
42
42
  }
43
43
  return undefined;
44
44
  }
45
- function detectFindingModel() {
46
- const candidates = [
47
- (process.env.PHREN_MODEL),
48
- process.env.OPENAI_MODEL,
49
- process.env.CLAUDE_MODEL,
50
- (process.env.PHREN_LLM_MODEL),
51
- process.env.MODEL,
52
- ];
53
- return candidates.find((value) => typeof value === "string" && value.trim())?.trim();
54
- }
55
- function detectFindingTool() {
56
- const candidates = [
57
- (process.env.PHREN_TOOL),
58
- (process.env.PHREN_HOOK_TOOL),
59
- ];
60
- return candidates.find((value) => typeof value === "string" && value.trim())?.trim();
61
- }
62
- function detectFindingProvenanceSource(explicitSource) {
63
- if (explicitSource)
64
- return explicitSource;
65
- const envSource = (process.env.PHREN_FINDING_SOURCE)?.trim().toLowerCase();
66
- if (isFindingProvenanceSource(envSource))
67
- return envSource;
68
- if ((process.env.PHREN_CONSOLIDATION) === "1")
69
- return "consolidation";
70
- if ((process.env.PHREN_AUTO_EXTRACT) === "1")
71
- return "extract";
72
- if ((process.env.PHREN_HOOK_TOOL))
73
- return "hook";
74
- if (process.env.PHREN_ACTOR?.trim())
75
- return "agent";
76
- return "human";
77
- }
78
- function buildFindingSource(sessionId, explicitSource, scope) {
79
- const actor = process.env.PHREN_ACTOR?.trim() || undefined;
80
- const source = {
81
- source: detectFindingProvenanceSource(explicitSource),
82
- machine: getMachineName(),
83
- actor,
84
- tool: detectFindingTool(),
85
- model: detectFindingModel(),
86
- session_id: sessionId,
87
- scope: normalizeMemoryScope(scope),
88
- };
89
- return source;
45
+ function buildFindingScope(scope) {
46
+ return normalizeMemoryScope(scope) || undefined;
90
47
  }
91
48
  function resolveFindingCitationInput(phrenPath, project, citationInput) {
92
49
  const resolved = citationInput ? { ...citationInput } : {};
@@ -124,7 +81,7 @@ export function autoDetectFindingType(text) {
124
81
  return null;
125
82
  }
126
83
  function prepareFinding(opts) {
127
- const { finding: learning, project, fullHistory, extraAnnotations, citationInput, source, nowIso, inferredRepo, headCommit, phrenPath } = opts;
84
+ const { finding: learning, project, fullHistory, extraAnnotations, citationInput, scope, nowIso, inferredRepo, headCommit, phrenPath } = opts;
128
85
  const secretType = scanForSecrets(learning);
129
86
  if (secretType) {
130
87
  return { status: "rejected", reason: `Contains ${secretType}` };
@@ -145,11 +102,11 @@ function prepareFinding(opts) {
145
102
  const fid = crypto.randomBytes(4).toString("hex");
146
103
  const fidComment = `<!-- fid:${fid} -->`;
147
104
  const createdComment = `<!-- created: ${today} -->`;
148
- const sourceComment = source ? buildSourceComment(source) : "";
105
+ const scopeComment = buildScopeComment(scope);
149
106
  let lifecycle = { status: "active", status_updated: today };
150
107
  let bullet = `${normalizedLearning.startsWith("- ") ? normalizedLearning : `- ${normalizedLearning}`} ${fidComment} ${createdComment}`;
151
- if (sourceComment)
152
- bullet += ` ${sourceComment}`;
108
+ if (scopeComment)
109
+ bullet += ` ${scopeComment}`;
153
110
  if (isDuplicateFinding(fullHistory, bullet)) {
154
111
  return { status: "duplicate" };
155
112
  }
@@ -265,7 +222,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
265
222
  const resolvedDir = safeProjectPath(phrenPath, project);
266
223
  if (!resolvedDir)
267
224
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
268
- const learningsPath = path.join(resolvedDir, "FINDINGS.md");
225
+ const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
269
226
  // Secret/PII scan — reject before anything else (before existence check, before lock)
270
227
  const nowIso = new Date().toISOString();
271
228
  const today = nowIso.slice(0, 10);
@@ -273,8 +230,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
273
230
  if (!resolvedCitationInputResult.ok)
274
231
  return resolvedCitationInputResult;
275
232
  const resolvedCitationInput = resolvedCitationInputResult.data;
276
- const effectiveSessionId = resolveFindingSessionId(phrenPath, project, opts?.sessionId);
277
- const source = buildFindingSource(effectiveSessionId, opts?.source, opts?.scope);
233
+ const scope = buildFindingScope(opts?.scope);
278
234
  const inferredRepo = resolveInferredCitationRepo(resolvedCitationInput);
279
235
  const headCommit = inferredRepo ? getHeadCommit(inferredRepo) : undefined;
280
236
  const supersedesText = resolvedCitationInput?.supersedes;
@@ -295,7 +251,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
295
251
  const result = withFileLock(learningsPath, () => {
296
252
  const preparedForNewFile = prepareFinding({
297
253
  finding: learning, project, fullHistory: "", extraAnnotations: opts?.extraAnnotations,
298
- citationInput: resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath,
254
+ citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
299
255
  });
300
256
  if (!fs.existsSync(learningsPath)) {
301
257
  if (preparedForNewFile.status === "rejected") {
@@ -328,7 +284,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
328
284
  : content;
329
285
  const prepared = prepareFinding({
330
286
  finding: learning, project, fullHistory: historyForDedup, extraAnnotations: opts?.extraAnnotations,
331
- citationInput: resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath,
287
+ citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
332
288
  });
333
289
  if (prepared.status === "rejected") {
334
290
  return phrenErr(`Rejected: finding appears to contain a secret (${prepared.reason.replace(/^Contains /, "")}). Strip credentials before saving.`, PhrenError.VALIDATION_ERROR);
@@ -416,15 +372,14 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
416
372
  const resolvedDir = safeProjectPath(phrenPath, project);
417
373
  if (!resolvedDir)
418
374
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
419
- const learningsPath = path.join(resolvedDir, "FINDINGS.md");
375
+ const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
420
376
  const nowIso = new Date().toISOString();
421
377
  const today = nowIso.slice(0, 10);
422
378
  const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project);
423
379
  if (!resolvedCitationInputResult.ok)
424
380
  return resolvedCitationInputResult;
425
381
  const resolvedCitationInput = resolvedCitationInputResult.data;
426
- const effectiveSessionId = resolveFindingSessionId(phrenPath, project, opts?.sessionId);
427
- const source = buildFindingSource(effectiveSessionId, opts?.source, opts?.scope);
382
+ const scope = buildFindingScope(opts?.scope);
428
383
  const inferredRepo = resolveInferredCitationRepo(resolvedCitationInput);
429
384
  const headCommit = inferredRepo ? getHeadCommit(inferredRepo) : undefined;
430
385
  const added = [];
@@ -445,7 +400,7 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
445
400
  }
446
401
  const prepared = prepareFinding({
447
402
  finding: learning, project, fullHistory: content, extraAnnotations,
448
- citationInput: resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath,
403
+ citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
449
404
  });
450
405
  if (prepared.status === "rejected") {
451
406
  rejected.push({ text: learning, reason: prepared.reason });
@@ -480,7 +435,7 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
480
435
  }
481
436
  const prepared = prepareFinding({
482
437
  finding: learning, project, fullHistory: content, extraAnnotations,
483
- citationInput: resolvedCitationInput, source, nowIso, inferredRepo, headCommit, phrenPath,
438
+ citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
484
439
  });
485
440
  if (prepared.status === "rejected") {
486
441
  rejected.push({ text: learning, reason: prepared.reason });
@@ -8,6 +8,7 @@ import { countActiveFindings } from "./archive.js";
8
8
  import { isTaskFileName } from "../data/tasks.js";
9
9
  import { METADATA_REGEX } from "./metadata.js";
10
10
  import { getNonPrimaryStores, getStoreProjectDirs } from "../store-registry.js";
11
+ import { FINDINGS_FILENAME } from "../data/access.js";
11
12
  /** Maximum allowed length for a single finding entry (token budget protection). */
12
13
  export const MAX_FINDING_LENGTH = 2000;
13
14
  function safeParseDate(s) {
@@ -34,7 +35,7 @@ export function validateFinding(text) {
34
35
  * Returns null if the project has no FINDINGS.md.
35
36
  */
36
37
  export function getProjectConsolidationStatus(dir) {
37
- const learningsPath = path.join(dir, "FINDINGS.md");
38
+ const learningsPath = path.join(dir, FINDINGS_FILENAME);
38
39
  if (!fs.existsSync(learningsPath))
39
40
  return null;
40
41
  const content = fs.readFileSync(learningsPath, "utf8");
@@ -3,6 +3,7 @@ import { phrenErr, phrenOk, readRootManifest } from "../shared.js";
3
3
  import { bootstrapFromExisting } from "../init/setup.js";
4
4
  import { resolveActiveProfile } from "../profile-store.js";
5
5
  import { TASKS_FILENAME } from "../data/tasks.js";
6
+ import { FINDINGS_FILENAME } from "../data/access.js";
6
7
  export function addProjectFromPath(phrenPath, targetPath, requestedProfile, ownership) {
7
8
  if (!targetPath) {
8
9
  return phrenErr("Path is required. Pass the current project directory explicitly to avoid adding the wrong working directory.");
@@ -29,7 +30,7 @@ export function addProjectFromPath(phrenPath, targetPath, requestedProfile, owne
29
30
  files: {
30
31
  claude: added.claudePath,
31
32
  summary: path.join(phrenPath, added.project, "summary.md"),
32
- findings: path.join(phrenPath, added.project, "FINDINGS.md"),
33
+ findings: path.join(phrenPath, added.project, FINDINGS_FILENAME),
33
34
  task: path.join(phrenPath, added.project, TASKS_FILENAME),
34
35
  },
35
36
  });
@@ -1,12 +1,13 @@
1
1
  import { type PhrenResult } from "../shared.js";
2
2
  import { type AddFindingResult } from "../shared/content.js";
3
- import { type FindingCitation, type FindingProvenanceSource } from "../content/citation.js";
3
+ import { type FindingCitation } from "../content/citation.js";
4
4
  import { type FindingLifecycleStatus } from "../finding/lifecycle.js";
5
5
  export type { TaskSection, TaskItem, TaskDoc } from "./tasks.js";
6
6
  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";
7
7
  export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, type ProfileInfo, type ProjectCard, } from "../profile-store.js";
8
8
  export { loadShellState, resetShellState, saveShellState, type ShellState, } from "../shell/state-store.js";
9
9
  export { getRuntimeHealth as readRuntimeHealth } from "../shared/governance.js";
10
+ export declare const FINDINGS_FILENAME = "FINDINGS.md";
10
11
  export interface FindingItem {
11
12
  id: string;
12
13
  /** Stable 8-char hex ID embedded as `<!-- fid:XXXXXXXX -->`. Survives reordering and consolidation. */
@@ -17,12 +18,6 @@ export interface FindingItem {
17
18
  citationData?: FindingCitation;
18
19
  taskItem?: string;
19
20
  confidence?: number;
20
- source: FindingProvenanceSource;
21
- machine?: string;
22
- actor?: string;
23
- tool?: string;
24
- model?: string;
25
- sessionId?: string;
26
21
  scope?: string;
27
22
  /** First 60 chars of the newer finding that supersedes this one. Set when this finding is stale. */
28
23
  supersededBy?: string;