@phren/cli 0.1.14 → 0.1.15

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 (45) 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/dedup.js +6 -5
  15. package/dist/content/learning.js +3 -2
  16. package/dist/content/validate.js +2 -1
  17. package/dist/core/project.js +2 -1
  18. package/dist/data/access.d.ts +1 -0
  19. package/dist/data/access.js +11 -10
  20. package/dist/finding/journal.js +2 -1
  21. package/dist/finding/lifecycle.js +2 -1
  22. package/dist/governance/policy.d.ts +2 -0
  23. package/dist/governance/policy.js +2 -2
  24. package/dist/hooks.js +38 -2
  25. package/dist/init/init-uninstall.js +2 -1
  26. package/dist/init/setup.js +5 -4
  27. package/dist/init-uninstall.js +2 -1
  28. package/dist/link/checksums.js +2 -1
  29. package/dist/link/context.js +2 -1
  30. package/dist/link/doctor.js +4 -3
  31. package/dist/link/link.js +2 -1
  32. package/dist/phren-paths.js +3 -2
  33. package/dist/profile-store.d.ts +1 -0
  34. package/dist/profile-store.js +15 -16
  35. package/dist/project-topics.js +4 -3
  36. package/dist/shell/input.js +3 -3
  37. package/dist/status.js +2 -2
  38. package/dist/tools/data.js +4 -4
  39. package/dist/tools/extract.js +2 -1
  40. package/dist/tools/finding.js +9 -9
  41. package/dist/tools/search.js +3 -3
  42. package/dist/tools/session.js +2 -2
  43. package/dist/ui/data.js +6 -5
  44. package/dist/ui/server.js +3 -3
  45. package/package.json +1 -1
@@ -11,6 +11,7 @@ import { errorMessage } from "./utils.js";
11
11
  import { machineFilePath } from "./machine-identity.js";
12
12
  import { codexJsonCandidates, copilotMcpCandidates, cursorMcpCandidates, vscodeMcpCandidates, } from "./provider-adapters.js";
13
13
  import { DEFAULT_PHREN_PATH, log } from "./init/shared.js";
14
+ import { FINDINGS_FILENAME } from "./data/access.js";
14
15
  const PHREN_NPM_PACKAGE_NAME = "@phren/cli";
15
16
  function getNpmCommand() {
16
17
  return process.platform === "win32" ? "npm.cmd" : "npm";
@@ -192,7 +193,7 @@ async function promptUninstallConfirm(phrenPath) {
192
193
  const projectCount = projectDirs.length;
193
194
  let findingCount = 0;
194
195
  for (const dir of projectDirs) {
195
- const findingsFile = path.join(dir, "FINDINGS.md");
196
+ const findingsFile = path.join(dir, FINDINGS_FILENAME);
196
197
  if (fs.existsSync(findingsFile)) {
197
198
  const content = fs.readFileSync(findingsFile, "utf8");
198
199
  findingCount += content.split("\n").filter((l) => l.startsWith("- ")).length;
@@ -3,6 +3,7 @@ import * as path from "path";
3
3
  import * as crypto from "crypto";
4
4
  import { getProjectDirs } from "../shared.js";
5
5
  import { TASK_FILE_ALIASES } from "../data/tasks.js";
6
+ import { FINDINGS_FILENAME } from "../data/access.js";
6
7
  import { errorMessage } from "../utils.js";
7
8
  import { logger } from "../logger.js";
8
9
  function fileChecksum(filePath) {
@@ -35,7 +36,7 @@ export function updateFileChecksums(phrenPath, profileName) {
35
36
  const tracked = [];
36
37
  const dirs = getProjectDirs(phrenPath, profileName);
37
38
  for (const dir of dirs) {
38
- for (const name of ["FINDINGS.md", ...TASK_FILE_ALIASES, "truths.md"]) {
39
+ for (const name of [FINDINGS_FILENAME, ...TASK_FILE_ALIASES, "truths.md"]) {
39
40
  const full = path.join(dir, name);
40
41
  if (!fs.existsSync(full))
41
42
  continue;
@@ -4,6 +4,7 @@ import * as yaml from "js-yaml";
4
4
  import { isValidProjectName } from "../utils.js";
5
5
  import { homeDir, homePath } from "../shared.js";
6
6
  import { resolveTaskFilePath } from "../data/tasks.js";
7
+ import { FINDINGS_FILENAME } from "../data/access.js";
7
8
  import { log } from "../init/shared.js";
8
9
  function contextFilePath() {
9
10
  return homePath(".phren-context.md");
@@ -88,7 +89,7 @@ export function writeContextDebugging(machine, profile, mcpStatus, projects, phr
88
89
  for (const project of projects) {
89
90
  if (project === "global")
90
91
  continue;
91
- const findings = path.join(phrenPath, project, "FINDINGS.md");
92
+ const findings = path.join(phrenPath, project, FINDINGS_FILENAME);
92
93
  if (fs.existsSync(findings)) {
93
94
  let body = fs.readFileSync(findings, "utf8");
94
95
  if (body.length > MAX_FILE_BYTES) {
@@ -13,6 +13,7 @@ import { verifyFileChecksums, updateFileChecksums } from "./checksums.js";
13
13
  import { buildSkillManifest } from "../skill/registry.js";
14
14
  import { inspectTaskHygiene } from "../task/hygiene.js";
15
15
  import { resolveTaskFilePath, TASK_FILE_ALIASES } from "../data/tasks.js";
16
+ import { FINDINGS_FILENAME } from "../data/access.js";
16
17
  import { repairPreexistingInstall } from "../init/setup.js";
17
18
  import { getMachineName, lookupProfile, findProfileFile, getProfileProjects, findProjectDir, } from "./link.js";
18
19
  import { claudeProjectKey } from "./context.js";
@@ -240,7 +241,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
240
241
  checks.push({ name: `project-path:${project}`, ok: false, detail: "project directory not found on disk" });
241
242
  continue;
242
243
  }
243
- for (const f of ["CLAUDE.md", "REFERENCE.md", "FINDINGS.md"]) {
244
+ for (const f of ["CLAUDE.md", "REFERENCE.md", FINDINGS_FILENAME]) {
244
245
  const src = path.join(phrenPath, project, f);
245
246
  if (!fs.existsSync(src))
246
247
  continue;
@@ -547,7 +548,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
547
548
  detail: hygiene.detail,
548
549
  });
549
550
  }
550
- const findingsPath = path.join(projectDir, "FINDINGS.md");
551
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
551
552
  if (fs.existsSync(findingsPath)) {
552
553
  const content = fs.readFileSync(findingsPath, "utf8");
553
554
  const issues = validateFindingsFormat(content);
@@ -563,7 +564,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
563
564
  const projectName = path.basename(projectDir);
564
565
  if (projectName === "global")
565
566
  continue;
566
- for (const mdFile of ["FINDINGS.md", ...TASK_FILE_ALIASES, "review.md", "CLAUDE.md", "REFERENCE.md"]) {
567
+ for (const mdFile of [FINDINGS_FILENAME, ...TASK_FILE_ALIASES, "review.md", "CLAUDE.md", "REFERENCE.md"]) {
567
568
  const filePath = path.join(projectDir, mdFile);
568
569
  if (!fs.existsSync(filePath))
569
570
  continue;
package/dist/link/link.js CHANGED
@@ -9,6 +9,7 @@ import { configureAllHooks, detectInstalledTools } from "../hooks.js";
9
9
  import { getMachineName, persistMachineName } from "../machine-identity.js";
10
10
  import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, isRecord, homePath, hookConfigPath, installPreferencesFile, atomicWriteText, } from "../shared.js";
11
11
  import { errorMessage } from "../utils.js";
12
+ import { FINDINGS_FILENAME } from "../data/access.js";
12
13
  import { log } from "../init/shared.js";
13
14
  import { listMachines as listMachinesShared, listProfiles as listProfilesShared, setMachineProfile, } from "../profile-store.js";
14
15
  import { writeSkillMd, isManagedSymlink } from "./skills.js";
@@ -300,7 +301,7 @@ function linkProject(phrenPath, project, tools) {
300
301
  return;
301
302
  log(` ${project} -> ${target}`);
302
303
  const excludeEntries = [];
303
- for (const f of ["CLAUDE.md", "REFERENCE.md", "FINDINGS.md"]) {
304
+ for (const f of ["CLAUDE.md", "REFERENCE.md", FINDINGS_FILENAME]) {
304
305
  const src = path.join(phrenPath, project, f);
305
306
  if (fs.existsSync(src)) {
306
307
  if (symlinkFile(src, path.join(target, f), phrenPath))
@@ -6,6 +6,7 @@ import * as yaml from "js-yaml";
6
6
  import { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
7
7
  import { PhrenError, isRecord, RESERVED_PROJECT_DIR_NAMES } from "./phren-core.js";
8
8
  import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
9
+ import { FINDINGS_FILENAME } from "./data/access.js";
9
10
  bootstrapPhrenDotEnv();
10
11
  function stderrLog(msg) { try {
11
12
  process.stderr.write("[phren] " + msg + "\n");
@@ -310,7 +311,7 @@ export function appendIndexEvent(phrenPath, event) {
310
311
  }
311
312
  /** Resolve the canonical findings file for a project directory. */
312
313
  export function resolveFindingsPath(projectDir) {
313
- const findingsPath = path.join(projectDir, "FINDINGS.md");
314
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
314
315
  if (fs.existsSync(findingsPath))
315
316
  return findingsPath;
316
317
  return undefined;
@@ -484,7 +485,7 @@ export function computePhrenLiveStateToken(phrenPath) {
484
485
  for (const projectDir of projectDirs) {
485
486
  const project = path.basename(projectDir);
486
487
  parts.push(`project:${project}`);
487
- for (const file of ["CLAUDE.md", "summary.md", "FINDINGS.md", "tasks.md", "review.md", "truths.md", "topic-config.json", "phren.project.yaml"]) {
488
+ for (const file of ["CLAUDE.md", "summary.md", FINDINGS_FILENAME, "tasks.md", "review.md", "truths.md", "topic-config.json", "phren.project.yaml"]) {
488
489
  pushFileToken(parts, path.join(projectDir, file));
489
490
  }
490
491
  pushDirTokens(parts, path.join(projectDir, "reference"));
@@ -14,6 +14,7 @@ export interface ProfilePolicyDefaults {
14
14
  }
15
15
  export interface ProfileInfo {
16
16
  name: string;
17
+ description?: string;
17
18
  file: string;
18
19
  projects: string[];
19
20
  defaults?: ProfilePolicyDefaults;
@@ -6,8 +6,10 @@ import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, readRootMani
6
6
  import { defaultMachineName, getMachineName } from "./machine-identity.js";
7
7
  import { errorMessage, isValidProjectName } from "./utils.js";
8
8
  import { TASK_FILE_ALIASES } from "./data/tasks.js";
9
+ import { FINDINGS_FILENAME } from "./data/access.js";
9
10
  import { withSafeLock } from "./shared/data-utils.js";
10
11
  import { logger } from "./logger.js";
12
+ import { VALID_FINDING_SENSITIVITY, VALID_PROACTIVITY_LEVELS, VALID_TASK_MODES, VALID_RISKY_SECTIONS, } from "./governance/policy.js";
11
13
  import { getNonPrimaryStores, getStoreProjectDirs } from "./store-registry.js";
12
14
  export function resolveActiveProfile(phrenPath, requestedProfile) {
13
15
  const manifest = readRootManifest(phrenPath);
@@ -108,10 +110,6 @@ export function setMachineProfile(phrenPath, machine, profile) {
108
110
  return phrenOk(`Mapped machine ${machine} -> ${profile}.`);
109
111
  });
110
112
  }
111
- const VALID_FINDING_SENSITIVITY_VALS = ["minimal", "conservative", "balanced", "aggressive"];
112
- const VALID_PROACTIVITY_VALS = ["high", "medium", "low"];
113
- const VALID_TASK_MODE_VALS = ["off", "manual", "suggest", "auto"];
114
- const VALID_RISKY_SECTION_VALS = ["Review", "Stale", "Conflicts"];
115
113
  function pickEnumVal(value, allowed) {
116
114
  return typeof value === "string" && allowed.includes(value) ? value : undefined;
117
115
  }
@@ -132,19 +130,19 @@ function parseProfilePolicyDefaults(raw) {
132
130
  ? data.workflowPolicy
133
131
  : undefined;
134
132
  const result = {};
135
- const fs_ = pickEnumVal(data.findingSensitivity, VALID_FINDING_SENSITIVITY_VALS);
133
+ const fs_ = pickEnumVal(data.findingSensitivity, VALID_FINDING_SENSITIVITY);
136
134
  if (fs_)
137
135
  result.findingSensitivity = fs_;
138
- const pr = pickEnumVal(data.proactivity, VALID_PROACTIVITY_VALS);
136
+ const pr = pickEnumVal(data.proactivity, VALID_PROACTIVITY_LEVELS);
139
137
  if (pr)
140
138
  result.proactivity = pr;
141
- const prf = pickEnumVal(data.proactivityFindings, VALID_PROACTIVITY_VALS);
139
+ const prf = pickEnumVal(data.proactivityFindings, VALID_PROACTIVITY_LEVELS);
142
140
  if (prf)
143
141
  result.proactivityFindings = prf;
144
- const prt = pickEnumVal(data.proactivityTask, VALID_PROACTIVITY_VALS);
142
+ const prt = pickEnumVal(data.proactivityTask, VALID_PROACTIVITY_LEVELS);
145
143
  if (prt)
146
144
  result.proactivityTask = prt;
147
- const tm = pickEnumVal(data.taskMode, VALID_TASK_MODE_VALS);
145
+ const tm = pickEnumVal(data.taskMode, VALID_TASK_MODES);
148
146
  if (tm)
149
147
  result.taskMode = tm;
150
148
  if (retentionRaw) {
@@ -188,7 +186,7 @@ function parseProfilePolicyDefaults(raw) {
188
186
  wf.lowConfidenceThreshold = lct;
189
187
  if (Array.isArray(workflowRaw.riskySections)) {
190
188
  const rs = workflowRaw.riskySections
191
- .filter((s) => typeof s === "string" && VALID_RISKY_SECTION_VALS.includes(s));
189
+ .filter((s) => typeof s === "string" && VALID_RISKY_SECTIONS.includes(s));
192
190
  if (rs.length > 0)
193
191
  wf.riskySections = rs;
194
192
  }
@@ -226,8 +224,9 @@ export function listProfiles(phrenPath) {
226
224
  const projects = Array.isArray(data?.projects)
227
225
  ? data.projects.map((project) => String(project)).filter(Boolean)
228
226
  : [];
227
+ const description = typeof data?.description === "string" ? data.description : undefined;
229
228
  const defaults = parseProfilePolicyDefaults(data?.defaults);
230
- profiles.push({ name, file: full, projects, ...(defaults ? { defaults } : {}) });
229
+ profiles.push({ name, ...(description ? { description } : {}), file: full, projects, ...(defaults ? { defaults } : {}) });
231
230
  }
232
231
  catch (err) {
233
232
  logger.debug("profile-store", `listProfiles yamlParse: ${errorMessage(err)}`);
@@ -236,12 +235,12 @@ export function listProfiles(phrenPath) {
236
235
  }
237
236
  return phrenOk(profiles);
238
237
  }
239
- function writeProfile(file, name, projects) {
238
+ function writeProfile(file, name, projects, description) {
240
239
  const backup = `${file}.bak`;
241
240
  if (fs.existsSync(file))
242
241
  fs.copyFileSync(file, backup);
243
242
  const normalized = [...new Set(projects)].sort();
244
- const out = yaml.dump({ name, projects: normalized }, { lineWidth: 1000 });
243
+ const out = yaml.dump({ name, ...(description ? { description } : {}), projects: normalized }, { lineWidth: 1000 });
245
244
  const tmpPath = `${file}.tmp-${crypto.randomUUID()}`;
246
245
  fs.writeFileSync(tmpPath, out);
247
246
  fs.renameSync(tmpPath, file);
@@ -263,7 +262,7 @@ export function addProjectToProfile(phrenPath, profile, project) {
263
262
  if (!latest)
264
263
  return phrenErr(`Profile "${profile}" not found.`, PhrenError.NOT_FOUND);
265
264
  const projects = latest.projects.includes(project) ? latest.projects : [...latest.projects, project];
266
- writeProfile(latest.file, latest.name, projects);
265
+ writeProfile(latest.file, latest.name, projects, latest.description);
267
266
  return phrenOk(`Added ${project} to profile ${profile}.`);
268
267
  });
269
268
  }
@@ -282,7 +281,7 @@ export function removeProjectFromProfile(phrenPath, profile, project) {
282
281
  if (!latest)
283
282
  return phrenErr(`Profile "${profile}" not found.`, PhrenError.NOT_FOUND);
284
283
  const projects = latest.projects.filter((entry) => entry !== project);
285
- writeProfile(latest.file, latest.name, projects);
284
+ writeProfile(latest.file, latest.name, projects, latest.description);
286
285
  return phrenOk(`Removed ${project} from profile ${profile}.`);
287
286
  });
288
287
  }
@@ -299,7 +298,7 @@ function buildProjectCard(dir) {
299
298
  .split("\n")
300
299
  .map((line) => line.trim())
301
300
  .find((line) => line && !line.startsWith("#")) || "";
302
- const docs = ["CLAUDE.md", "FINDINGS.md", "summary.md", "review.md"]
301
+ const docs = ["CLAUDE.md", FINDINGS_FILENAME, "summary.md", "review.md"]
303
302
  .filter((file) => fs.existsSync(path.join(dir, file)));
304
303
  const taskFile = TASK_FILE_ALIASES.find((file) => fs.existsSync(path.join(dir, file)));
305
304
  if (taskFile)
@@ -5,6 +5,7 @@ import { debugLog } from "./shared.js";
5
5
  import { withFileLock } from "./shared/governance.js";
6
6
  import { STOP_WORDS, errorMessage, extractKeywords, isValidProjectName, safeProjectPath } from "./utils.js";
7
7
  import { walkDirectory } from "./shared/data-utils.js";
8
+ import { FINDINGS_FILENAME } from "./data/access.js";
8
9
  const TOPIC_CONFIG_FILENAME = "topic-config.json";
9
10
  const AUTO_TOPIC_MARKER_RE = /^<!--\s*phren:auto-topic(?:\s+slug=([a-z0-9_-]+))?\s*-->$/;
10
11
  const ARCHIVED_SECTION_RE = /^## Archived (\d{4}-\d{2}-\d{2})$/;
@@ -410,7 +411,7 @@ function countByTerm(terms) {
410
411
  }
411
412
  function readTopicInputContent(phrenPath, project) {
412
413
  const parts = [];
413
- for (const file of ["CLAUDE.md", "FINDINGS.md"]) {
414
+ for (const file of ["CLAUDE.md", FINDINGS_FILENAME]) {
414
415
  const filePath = safeProjectPath(phrenPath, project, file);
415
416
  if (!filePath || !fs.existsSync(filePath))
416
417
  continue;
@@ -896,12 +897,12 @@ function tokenizeSuggestionTerms(text) {
896
897
  }
897
898
  function collectSuggestionCorpus(phrenPath, project) {
898
899
  const parts = [];
899
- for (const file of ["CLAUDE.md", "summary.md", "FINDINGS.md"]) {
900
+ for (const file of ["CLAUDE.md", "summary.md", FINDINGS_FILENAME]) {
900
901
  const filePath = safeProjectPath(phrenPath, project, file);
901
902
  if (!filePath || !fs.existsSync(filePath))
902
903
  continue;
903
904
  const content = fs.readFileSync(filePath, "utf8");
904
- if (file === "FINDINGS.md") {
905
+ if (file === FINDINGS_FILENAME) {
905
906
  const recentBullets = content.split("\n").filter((line) => line.startsWith("- ")).slice(-10).join("\n");
906
907
  parts.push(recentBullets);
907
908
  continue;
@@ -5,7 +5,7 @@
5
5
  import { execFileSync } from "child_process";
6
6
  import * as fs from "fs";
7
7
  import * as path from "path";
8
- import { addTask, addFinding, addProjectToProfile, completeTask, listProjectCards, pinTask, readTasks, readFindings, readReviewQueue, removeFinding, removeProjectFromProfile, resetShellState, saveShellState, setMachineProfile, tidyDoneTasks, canonicalTaskFilePath, unpinTask, updateTask, workNextTask, loadShellState, resolveTaskFilePath, } from "../data/access.js";
8
+ import { addTask, addFinding, addProjectToProfile, completeTask, listProjectCards, pinTask, readTasks, readFindings, readReviewQueue, removeFinding, removeProjectFromProfile, resetShellState, saveShellState, setMachineProfile, tidyDoneTasks, canonicalTaskFilePath, unpinTask, updateTask, workNextTask, loadShellState, resolveTaskFilePath, FINDINGS_FILENAME, } from "../data/access.js";
9
9
  import { runtimeFile } from "../shared.js";
10
10
  import { handleGovernMemories } from "../cli/govern.js";
11
11
  import { runSearch } from "../cli/search.js";
@@ -266,7 +266,7 @@ export async function executePalette(host, input) {
266
266
  return;
267
267
  }
268
268
  host.confirmThen(`Remove finding "${match}"?`, () => {
269
- const file = path.join(host.phrenPath, project, "FINDINGS.md");
269
+ const file = path.join(host.phrenPath, project, FINDINGS_FILENAME);
270
270
  host.snapshotForUndo(`find remove "${match}"`, file);
271
271
  host.setMessage(` ${resultMsg(removeFinding(host.phrenPath, project, match))}`);
272
272
  });
@@ -673,7 +673,7 @@ async function doViewAction(host, key) {
673
673
  return;
674
674
  }
675
675
  host.confirmThen(`Delete finding ${style.dim(item.id ?? "")}?`, () => {
676
- const file = path.join(host.phrenPath, project, "FINDINGS.md");
676
+ const file = path.join(host.phrenPath, project, FINDINGS_FILENAME);
677
677
  host.snapshotForUndo(`remove finding ${item.id ?? ''}`, file);
678
678
  const r = removeFinding(host.phrenPath, project, item.text);
679
679
  host.setMessage(` ${resultMsg(r)}`);
package/dist/status.js CHANGED
@@ -8,7 +8,7 @@ import { getMcpEnabledPreference, getHooksEnabledPreference } from "./init/init.
8
8
  import { getTelemetrySummary } from "./telemetry.js";
9
9
  import { runGit as runGitShared, errorMessage } from "./utils.js";
10
10
  import { logger } from "./logger.js";
11
- import { readRuntimeHealth, resolveTaskFilePath } from "./data/access.js";
11
+ import { readRuntimeHealth, resolveTaskFilePath, FINDINGS_FILENAME } from "./data/access.js";
12
12
  import { resolveRuntimeProfile } from "./runtime-profile.js";
13
13
  import { renderPhrenArt } from "./phren-art.js";
14
14
  import { RESET, BOLD, DIM, GREEN, YELLOW, RED, CYAN } from "./shell/render.js";
@@ -318,7 +318,7 @@ export async function runStatus() {
318
318
  let totalQueue = 0;
319
319
  for (const dir of projectDirs) {
320
320
  const projName = path.basename(dir);
321
- totalFindings += countBullets(path.join(phrenPath, projName, "FINDINGS.md"));
321
+ totalFindings += countBullets(path.join(phrenPath, projName, FINDINGS_FILENAME));
322
322
  const taskPath = resolveTaskFilePath(phrenPath, projName);
323
323
  if (taskPath)
324
324
  totalTask += countBullets(taskPath);
@@ -3,7 +3,7 @@ import { z } from "zod";
3
3
  import * as fs from "fs";
4
4
  import * as path from "path";
5
5
  import { isValidProjectName, errorMessage, safeProjectPath } from "../utils.js";
6
- import { readFindings, readTasks, resolveTaskFilePath, TASKS_FILENAME } from "../data/access.js";
6
+ import { readFindings, readTasks, resolveTaskFilePath, TASKS_FILENAME, FINDINGS_FILENAME } from "../data/access.js";
7
7
  import { debugLog, findArchivedProjectNameCaseInsensitive, findProjectNameCaseInsensitive, normalizeProjectNameForCreate } from "../shared.js";
8
8
  import { logger } from "../logger.js";
9
9
  const importPayloadSchema = z.object({
@@ -60,7 +60,7 @@ export function register(server, ctx) {
60
60
  const learningsResult = readFindings(resolvedPhrenPath, project);
61
61
  if (learningsResult.ok)
62
62
  exported.learnings = learningsResult.data;
63
- const findingsPath = safeProjectPath(projectDir, "FINDINGS.md");
63
+ const findingsPath = safeProjectPath(projectDir, FINDINGS_FILENAME);
64
64
  if (findingsPath && fs.existsSync(findingsPath))
65
65
  exported.findingsRaw = fs.readFileSync(findingsPath, "utf8");
66
66
  const taskResult = readTasks(resolvedPhrenPath, project);
@@ -187,8 +187,8 @@ export function register(server, ctx) {
187
187
  }
188
188
  const findingsContent = typeof parsed.findingsRaw === "string" ? parsed.findingsRaw : buildFindingsContent();
189
189
  if (findingsContent) {
190
- fs.writeFileSync(path.join(stagedProjectDir, "FINDINGS.md"), findingsContent);
191
- imported.push("FINDINGS.md");
190
+ fs.writeFileSync(path.join(stagedProjectDir, FINDINGS_FILENAME), findingsContent);
191
+ imported.push(FINDINGS_FILENAME);
192
192
  }
193
193
  const taskContent = buildTaskContent();
194
194
  if (taskContent) {
@@ -4,6 +4,7 @@ import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
4
4
  import { addFindingsToFile } from "../shared/content.js";
5
5
  import { checkOllamaAvailable, checkModelAvailable, generateText, getOllamaUrl, getExtractModel } from "../shared/ollama.js";
6
6
  import { debugLog } from "../shared.js";
7
+ import { FINDINGS_FILENAME } from "../data/access.js";
7
8
  import { getProactivityLevelForFindings, shouldAutoCaptureFindingsForLevel } from "../proactivity.js";
8
9
  import * as path from "path";
9
10
  const EXTRACT_PROMPT = `You are extracting non-obvious engineering insights from text.
@@ -124,7 +125,7 @@ export function register(server, ctx) {
124
125
  // Update index for the findings file
125
126
  const resolvedDir = safeProjectPath(targetPath, project);
126
127
  if (resolvedDir) {
127
- updateFileInIndex(path.join(resolvedDir, "FINDINGS.md"));
128
+ updateFileInIndex(path.join(resolvedDir, FINDINGS_FILENAME));
128
129
  }
129
130
  return mcpResponse({
130
131
  ok: added.length > 0,
@@ -12,7 +12,7 @@ import { runCustomHooks } from "../hooks.js";
12
12
  import { incrementSessionFindings } from "./session.js";
13
13
  import { extractFragmentNames } from "../shared/fragment-graph.js";
14
14
  import { extractFactFromFinding } from "./extract-facts.js";
15
- import { appendChildFinding, editFinding as editFindingCore, readFindings } from "../data/access.js";
15
+ import { appendChildFinding, editFinding as editFindingCore, readFindings, FINDINGS_FILENAME } from "../data/access.js";
16
16
  import { getActiveTaskForSession } from "../task/lifecycle.js";
17
17
  import { FINDING_PROVENANCE_SOURCES } from "../content/citation.js";
18
18
  import { isInactiveFindingLine, supersedeFinding, retractFinding as retractFindingLifecycle, resolveFindingContradiction, } from "../finding/lifecycle.js";
@@ -21,7 +21,7 @@ const JACCARD_MAYBE_LOW = 0.25;
21
21
  const JACCARD_MAYBE_HIGH = 0.40; // above this isDuplicateFinding already catches it
22
22
  function findJaccardCandidates(phrenPath, project, finding) {
23
23
  try {
24
- const findingsPath = path.join(phrenPath, project, "FINDINGS.md");
24
+ const findingsPath = path.join(phrenPath, project, FINDINGS_FILENAME);
25
25
  if (!fs.existsSync(findingsPath))
26
26
  return [];
27
27
  const content = fs.readFileSync(findingsPath, "utf8");
@@ -78,7 +78,7 @@ function withLifecycleMutation(phrenPath, project, writeQueue, updateIndex, hand
78
78
  return mcpResponse({ ok: false, error: result.error });
79
79
  const resolvedFindingsDir = safeProjectPath(phrenPath, project);
80
80
  if (resolvedFindingsDir)
81
- updateIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
81
+ updateIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
82
82
  const mapped = mapResponse(result.data);
83
83
  return mcpResponse({ ok: true, message: mapped.message, data: mapped.data });
84
84
  });
@@ -156,7 +156,7 @@ async function handleAddFinding(ctx, params) {
156
156
  if (added.length > 0) {
157
157
  runCustomHooks(phrenPath, "post-finding", { PHREN_PROJECT: project });
158
158
  incrementSessionFindings(phrenPath, added.length, sessionId, project);
159
- updateFileInIndex(path.join(phrenPath, project, "FINDINGS.md"));
159
+ updateFileInIndex(path.join(phrenPath, project, FINDINGS_FILENAME));
160
160
  }
161
161
  const rejectedMsg = rejected.length > 0 ? `, ${rejected.length} rejected` : "";
162
162
  return mcpResponse({
@@ -196,7 +196,7 @@ async function handleAddFinding(ctx, params) {
196
196
  if (result.data.status === "skipped") {
197
197
  return mcpResponse({ ok: true, message: result.data.message, data: { project, finding: taggedFinding, status: "skipped" } });
198
198
  }
199
- updateFileInIndex(path.join(phrenPath, project, "FINDINGS.md"));
199
+ updateFileInIndex(path.join(phrenPath, project, FINDINGS_FILENAME));
200
200
  if (result.data.status === "added" || result.data.status === "created") {
201
201
  runCustomHooks(phrenPath, "post-finding", { PHREN_PROJECT: project });
202
202
  incrementSessionFindings(phrenPath, 1, sessionId, project);
@@ -208,7 +208,7 @@ async function handleAddFinding(ctx, params) {
208
208
  const taskMatch = activeTask.stableId ? `bid:${activeTask.stableId}` : activeTask.line;
209
209
  // Extract fid from the last written line in FINDINGS.md
210
210
  try {
211
- const findingsPath = path.join(phrenPath, project, "FINDINGS.md");
211
+ const findingsPath = path.join(phrenPath, project, FINDINGS_FILENAME);
212
212
  const findingsContent = fs.readFileSync(findingsPath, "utf8");
213
213
  const lines = findingsContent.split("\n");
214
214
  const taggedText = taggedFinding.replace(/^-\s+/, "").trim().slice(0, 60).toLowerCase();
@@ -400,7 +400,7 @@ async function handleEditFinding(ctx, { project: projectInput, old_text, new_tex
400
400
  return mcpResponse({ ok: false, error: result.error });
401
401
  const resolvedFindingsDir = safeProjectPath(phrenPath, project);
402
402
  if (resolvedFindingsDir)
403
- updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
403
+ updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
404
404
  return mcpResponse({
405
405
  ok: true,
406
406
  message: result.data,
@@ -432,7 +432,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
432
432
  return mcpResponse({ ok: false, error: result.message });
433
433
  const resolvedFindingsDir = safeProjectPath(phrenPath, project);
434
434
  if (resolvedFindingsDir)
435
- updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
435
+ updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
436
436
  return mcpResponse({ ok: true, message: result.message, data: result.data });
437
437
  });
438
438
  }
@@ -442,7 +442,7 @@ async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
442
442
  return mcpResponse({ ok: false, error: result.message });
443
443
  const resolvedFindingsDir = safeProjectPath(phrenPath, project);
444
444
  if (resolvedFindingsDir)
445
- updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
445
+ updateFileInIndex(path.join(resolvedFindingsDir, FINDINGS_FILENAME));
446
446
  return mcpResponse({ ok: true, message: result.message, data: result.data });
447
447
  });
448
448
  }
@@ -6,7 +6,7 @@ import { createHash } from "crypto";
6
6
  import { execFileSync } from "child_process";
7
7
  import { isValidProjectName, errorMessage } from "../utils.js";
8
8
  import { resolveAllStores } from "../store-registry.js";
9
- import { readFindings } from "../data/access.js";
9
+ import { readFindings, FINDINGS_FILENAME } from "../data/access.js";
10
10
  import { debugLog, runtimeFile, DOC_TYPES, FINDING_TAGS, isMemoryScopeVisible, normalizeMemoryScope, } from "../shared.js";
11
11
  import { FINDING_LIFECYCLE_STATUSES, parseFindingLifecycle, } from "../shared/content.js";
12
12
  import { decodeStringRow, queryRows, queryDocRows, queryFragmentLinks, logFragmentMiss, extractSnippet, queryDocBySourceKey, normalizeMemoryId, } from "../shared/index.js";
@@ -471,7 +471,7 @@ async function handleGetProjectSummary(ctx, { name }) {
471
471
  if (store && fs.existsSync(path.join(store.path, lookupName))) {
472
472
  const projDir = path.join(store.path, lookupName);
473
473
  const fsDocs = [];
474
- for (const [file, type] of [["summary.md", "summary"], ["CLAUDE.md", "claude"], ["FINDINGS.md", "findings"], ["tasks.md", "task"], ["truths.md", "canonical"]]) {
474
+ for (const [file, type] of [["summary.md", "summary"], ["CLAUDE.md", "claude"], [FINDINGS_FILENAME, "findings"], ["tasks.md", "task"], ["truths.md", "canonical"]]) {
475
475
  const filePath = path.join(projDir, file);
476
476
  if (fs.existsSync(filePath)) {
477
477
  fsDocs.push({ project: lookupName, filename: file, type, content: fs.readFileSync(filePath, "utf8").slice(0, 8000), path: filePath });
@@ -587,7 +587,7 @@ async function handleListProjects(ctx, { page, page_size }) {
587
587
  if (projDir) {
588
588
  if (fs.existsSync(path.join(projDir, "CLAUDE.md")))
589
589
  badges.push("CLAUDE.md");
590
- if (fs.existsSync(path.join(projDir, "FINDINGS.md")))
590
+ if (fs.existsSync(path.join(projDir, FINDINGS_FILENAME)))
591
591
  badges.push("FINDINGS");
592
592
  if (fs.existsSync(path.join(projDir, "summary.md")))
593
593
  badges.push("summary");
@@ -11,7 +11,7 @@ import { runCustomHooks } from "../hooks.js";
11
11
  import { readExtractedFacts } from "./extract-facts.js";
12
12
  import { resolveFindingSessionId } from "../finding/context.js";
13
13
  import { readTasks } from "../data/tasks.js";
14
- import { readFindings } from "../data/access.js";
14
+ import { readFindings, FINDINGS_FILENAME } from "../data/access.js";
15
15
  import { getActiveTaskForSession } from "../task/lifecycle.js";
16
16
  import { listTaskCheckpoints, writeTaskCheckpoint } from "../session/checkpoints.js";
17
17
  import { findMostRecentSummaryWithProject as findMostRecentSummaryRecord, writeLastSummary as writeLastSummaryRecord, } from "../session/artifacts.js";
@@ -332,7 +332,7 @@ async function hasCompletedTasksInSession(phrenPath, sessionId, project) {
332
332
  /** Compute what changed since the last session ended. */
333
333
  function computeSessionDiff(phrenPath, project, lastSessionEnd) {
334
334
  const projectDir = path.join(phrenPath, project);
335
- const findingsPath = path.join(projectDir, "FINDINGS.md");
335
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
336
336
  if (!fs.existsSync(findingsPath))
337
337
  return { newFindings: 0, superseded: 0, tasksCompleted: 0 };
338
338
  const content = fs.readFileSync(findingsPath, "utf8");
package/dist/ui/data.js CHANGED
@@ -10,6 +10,7 @@ import { hookConfigPaths, hookConfigRoots } from "../provider-adapters.js";
10
10
  import { readProjectConfig, isProjectHookEnabled, PROJECT_HOOK_EVENTS } from "../project-config.js";
11
11
  import { getAllSkills } from "../skill/registry.js";
12
12
  import { resolveTaskFilePath, readTasks, TASKS_FILENAME } from "../data/tasks.js";
13
+ import { FINDINGS_FILENAME } from "../data/access.js";
13
14
  import { buildIndex, queryDocBySourceKey, queryRows } from "../shared/index.js";
14
15
  import { readProjectTopics, classifyTopicForText } from "../project-topics.js";
15
16
  import { entryScoreKey } from "../governance/scores.js";
@@ -190,7 +191,7 @@ export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
190
191
  topicMetaMap.set(topic.slug, { slug: topic.slug, label: topic.label });
191
192
  }
192
193
  }
193
- const findingsPath = path.join(storePath, project, "FINDINGS.md");
194
+ const findingsPath = path.join(storePath, project, FINDINGS_FILENAME);
194
195
  const storeName = storePathToName.get(storePath) || "unknown";
195
196
  if (!fs.existsSync(findingsPath)) {
196
197
  if (!addedProjectNodeIds.has(project)) {
@@ -260,7 +261,7 @@ export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
260
261
  if (taggedCount >= MAX_TAGGED)
261
262
  continue;
262
263
  const topic = classifyTopicForText(`[${currentHeadingTag}] ${text}`, projectTopics);
263
- const scoreKey = entryScoreKey(project, "FINDINGS.md", `[${currentHeadingTag}] ${text}`);
264
+ const scoreKey = entryScoreKey(project, FINDINGS_FILENAME, `[${currentHeadingTag}] ${text}`);
264
265
  const nodeId = stableId("finding", scoreKey);
265
266
  taggedCount++;
266
267
  nodes.push({
@@ -295,7 +296,7 @@ export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
295
296
  const label = text.length > 55 ? `${text.slice(0, 52)}...` : text;
296
297
  // Classify the finding using the project's topic system
297
298
  const topic = classifyTopicForText(`[${tag}] ${text}`, projectTopics);
298
- const scoreKey = entryScoreKey(project, "FINDINGS.md", `[${tag}] ${text}`);
299
+ const scoreKey = entryScoreKey(project, FINDINGS_FILENAME, `[${tag}] ${text}`);
299
300
  const nodeId = stableId("finding", scoreKey);
300
301
  taggedCount++;
301
302
  nodes.push({
@@ -330,7 +331,7 @@ export async function buildGraph(phrenPath, profile, focusProject, existingDb) {
330
331
  const label = text.length > 55 ? `${text.slice(0, 52)}...` : text;
331
332
  // Classify using dynamic topics
332
333
  const topic = classifyTopicForText(text, projectTopics);
333
- const scoreKey = entryScoreKey(project, "FINDINGS.md", text);
334
+ const scoreKey = entryScoreKey(project, FINDINGS_FILENAME, text);
334
335
  const nodeId = stableId("finding", scoreKey);
335
336
  untaggedAdded++;
336
337
  nodes.push({
@@ -566,7 +567,7 @@ export function recentAccepted(phrenPath) {
566
567
  }
567
568
  function buildProjectInfo(basePath, project, store) {
568
569
  const dir = path.join(basePath, project);
569
- const findingsPath = path.join(dir, "FINDINGS.md");
570
+ const findingsPath = path.join(dir, FINDINGS_FILENAME);
570
571
  const taskPath = resolveTaskFilePath(basePath, project);
571
572
  const claudeMdPath = path.join(dir, "CLAUDE.md");
572
573
  const summaryPath = path.join(dir, "summary.md");
package/dist/ui/server.js CHANGED
@@ -7,7 +7,7 @@ import * as querystring from "querystring";
7
7
  import { spawn, execFileSync } from "child_process";
8
8
  import { computePhrenLiveStateToken, getProjectDirs, } from "../shared.js";
9
9
  import { getNonPrimaryStores, subscribeStoreProjects, unsubscribeStoreProjects } from "../store-registry.js";
10
- import { editFinding, readReviewQueue, removeFinding, readFindings, addFinding as addFindingStore, readTasksAcrossProjects, addTask as addTaskStore, completeTask as completeTaskStore, removeTask as removeTaskStore, updateTask as updateTaskStore, TASKS_FILENAME, } from "../data/access.js";
10
+ import { editFinding, readReviewQueue, removeFinding, readFindings, addFinding as addFindingStore, readTasksAcrossProjects, addTask as addTaskStore, completeTask as completeTaskStore, removeTask as removeTaskStore, updateTask as updateTaskStore, TASKS_FILENAME, FINDINGS_FILENAME, } from "../data/access.js";
11
11
  import { isValidProjectName, errorMessage, queueFilePath, safeProjectPath } from "../utils.js";
12
12
  import { readInstallPreferences, writeInstallPreferences, writeGovernanceInstallPreferences } from "../init/preferences.js";
13
13
  import { buildGraph, collectProjectsForUI, collectSkillsForUI, getHooksData, isAllowedSkillPath, readSyncSnapshot, recentAccepted, recentUsage, } from "./data.js";
@@ -376,7 +376,7 @@ function handleGetProjectContent(res, url, ctx) {
376
376
  const file = String(qs.file || "");
377
377
  if (!project || !isValidProjectName(project) || !file)
378
378
  return jsonErr(res, "Invalid project or file", 400);
379
- const allowedFiles = ["FINDINGS.md", TASKS_FILENAME, "CLAUDE.md", "summary.md"];
379
+ const allowedFiles = [FINDINGS_FILENAME, TASKS_FILENAME, "CLAUDE.md", "summary.md"];
380
380
  if (!allowedFiles.includes(file))
381
381
  return jsonErr(res, `File not allowed: ${file}`, 400);
382
382
  const basePath = resolveProjectBasePath(ctx.phrenPath, project);
@@ -509,7 +509,7 @@ function handleGetSettings(res, url, ctx) {
509
509
  const projectDir = path.join(ctx.phrenPath, settingsProject);
510
510
  const configFile = path.join(projectDir, "phren.project.yaml");
511
511
  const projConfig = readProjectConfig(ctx.phrenPath, settingsProject);
512
- const findingsPath = path.join(projectDir, "FINDINGS.md");
512
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
513
513
  const taskPath = path.join(projectDir, "tasks.md");
514
514
  let findingCount = 0;
515
515
  if (fs.existsSync(findingsPath))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.1.14",
3
+ "version": "0.1.15",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {