@phren/cli 0.1.13 → 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 (75) 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/hooks-session.d.ts +18 -36
  9. package/dist/cli/hooks-session.js +21 -1482
  10. package/dist/cli/namespaces-findings.d.ts +1 -0
  11. package/dist/cli/namespaces-findings.js +208 -0
  12. package/dist/cli/namespaces-profile.d.ts +1 -0
  13. package/dist/cli/namespaces-profile.js +76 -0
  14. package/dist/cli/namespaces-projects.d.ts +1 -0
  15. package/dist/cli/namespaces-projects.js +371 -0
  16. package/dist/cli/namespaces-review.d.ts +1 -0
  17. package/dist/cli/namespaces-review.js +45 -0
  18. package/dist/cli/namespaces-skills.d.ts +4 -0
  19. package/dist/cli/namespaces-skills.js +550 -0
  20. package/dist/cli/namespaces-store.d.ts +2 -0
  21. package/dist/cli/namespaces-store.js +367 -0
  22. package/dist/cli/namespaces-tasks.d.ts +1 -0
  23. package/dist/cli/namespaces-tasks.js +369 -0
  24. package/dist/cli/namespaces-utils.d.ts +4 -0
  25. package/dist/cli/namespaces-utils.js +47 -0
  26. package/dist/cli/namespaces.d.ts +7 -11
  27. package/dist/cli/namespaces.js +8 -2011
  28. package/dist/cli/ops.js +2 -2
  29. package/dist/cli/session-background.d.ts +3 -0
  30. package/dist/cli/session-background.js +176 -0
  31. package/dist/cli/session-git.d.ts +17 -0
  32. package/dist/cli/session-git.js +181 -0
  33. package/dist/cli/session-metrics.d.ts +2 -0
  34. package/dist/cli/session-metrics.js +67 -0
  35. package/dist/cli/session-start.d.ts +3 -0
  36. package/dist/cli/session-start.js +290 -0
  37. package/dist/cli/session-stop.d.ts +8 -0
  38. package/dist/cli/session-stop.js +468 -0
  39. package/dist/cli/session-tool-hook.d.ts +18 -0
  40. package/dist/cli/session-tool-hook.js +376 -0
  41. package/dist/cli/team.js +7 -5
  42. package/dist/cli-hooks-session-handlers.js +2 -1
  43. package/dist/content/archive.js +2 -1
  44. package/dist/content/dedup.js +6 -5
  45. package/dist/content/learning.js +3 -2
  46. package/dist/content/validate.js +2 -1
  47. package/dist/core/project.js +2 -1
  48. package/dist/data/access.d.ts +1 -0
  49. package/dist/data/access.js +11 -10
  50. package/dist/finding/journal.js +2 -1
  51. package/dist/finding/lifecycle.js +2 -1
  52. package/dist/governance/policy.d.ts +2 -0
  53. package/dist/governance/policy.js +2 -2
  54. package/dist/hooks.js +38 -2
  55. package/dist/init/init-uninstall.js +2 -1
  56. package/dist/init/setup.js +5 -4
  57. package/dist/init-uninstall.js +2 -1
  58. package/dist/link/checksums.js +2 -1
  59. package/dist/link/context.js +2 -1
  60. package/dist/link/doctor.js +4 -3
  61. package/dist/link/link.js +2 -1
  62. package/dist/phren-paths.js +3 -2
  63. package/dist/profile-store.d.ts +1 -0
  64. package/dist/profile-store.js +15 -16
  65. package/dist/project-topics.js +4 -3
  66. package/dist/shell/input.js +3 -3
  67. package/dist/status.js +2 -2
  68. package/dist/tools/data.js +4 -4
  69. package/dist/tools/extract.js +2 -1
  70. package/dist/tools/finding.js +9 -9
  71. package/dist/tools/search.js +4 -4
  72. package/dist/tools/session.js +2 -2
  73. package/dist/ui/data.js +6 -5
  74. package/dist/ui/server.js +3 -3
  75. package/package.json +1 -1
@@ -6,6 +6,7 @@ const LIFECYCLE_PREFIX = "phren";
6
6
  import { withFileLock } from "../shared/governance.js";
7
7
  import { isValidProjectName, safeProjectPath } from "../utils.js";
8
8
  import { isArchiveEnd, isArchiveStart, parseCreatedDate as parseCreatedDateMeta, parseStatusField, parseStatus, parseSupersession, parseContradiction, parseFindingId as parseFindingIdMeta, stripLifecycleMetadata, stripRelationMetadata, normalizeFindingText, } from "../content/metadata.js";
9
+ import { FINDINGS_FILENAME } from "../data/access.js";
9
10
  export const FINDING_TYPE_DECAY = {
10
11
  'pattern': { maxAgeDays: 365, decayMultiplier: 1.0 }, // Slow decay, long-lived
11
12
  'decision': { maxAgeDays: Infinity, decayMultiplier: 1.0 }, // Never decays
@@ -198,7 +199,7 @@ function findingsPathForProject(phrenPath, project) {
198
199
  return phrenErr(`Invalid project name: "${project}"`, PhrenError.INVALID_PROJECT_NAME);
199
200
  if (!fs.existsSync(projectDir))
200
201
  return phrenErr(`Project "${project}" not found.`, PhrenError.PROJECT_NOT_FOUND);
201
- const findingsPath = path.join(projectDir, "FINDINGS.md");
202
+ const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
202
203
  if (!fs.existsSync(findingsPath))
203
204
  return phrenErr(`No FINDINGS.md found for "${project}".`, PhrenError.FILE_NOT_FOUND);
204
205
  return phrenOk(findingsPath);
@@ -83,10 +83,12 @@ export interface ResolvedConfig {
83
83
  retentionPolicy: RetentionPolicy;
84
84
  workflowPolicy: WorkflowPolicy;
85
85
  }
86
+ export declare const VALID_PROACTIVITY_LEVELS: readonly ["high", "medium", "low"];
86
87
  export declare const VALID_TASK_MODES: readonly ["off", "manual", "suggest", "auto"];
87
88
  export type TaskMode = typeof VALID_TASK_MODES[number];
88
89
  export declare const VALID_FINDING_SENSITIVITY: readonly ["minimal", "conservative", "balanced", "aggressive"];
89
90
  export type FindingSensitivityLevel = typeof VALID_FINDING_SENSITIVITY[number];
91
+ export declare const VALID_RISKY_SECTIONS: readonly ["Review", "Stale", "Conflicts"];
90
92
  export declare function getProjectConfigOverrides(phrenPath: string, projectName: string): ProjectConfigOverrides | null;
91
93
  export declare function mergeConfig(phrenPath: string, projectName?: string, profile?: string): ResolvedConfig;
92
94
  export declare function getRetentionPolicy(phrenPath: string, projectName?: string): RetentionPolicy;
@@ -221,10 +221,10 @@ function normalizeIndexPolicy(data) {
221
221
  includeHidden: pickBoolean(data.includeHidden, DEFAULT_INDEX_POLICY.includeHidden),
222
222
  };
223
223
  }
224
- const VALID_PROACTIVITY_LEVELS = ["high", "medium", "low"];
224
+ export const VALID_PROACTIVITY_LEVELS = ["high", "medium", "low"];
225
225
  export const VALID_TASK_MODES = ["off", "manual", "suggest", "auto"];
226
226
  export const VALID_FINDING_SENSITIVITY = ["minimal", "conservative", "balanced", "aggressive"];
227
- const VALID_RISKY_SECTIONS = ["Review", "Stale", "Conflicts"];
227
+ export const VALID_RISKY_SECTIONS = ["Review", "Stale", "Conflicts"];
228
228
  function pickEnum(value, allowed) {
229
229
  return typeof value === "string" && allowed.includes(value) ? value : undefined;
230
230
  }
package/dist/hooks.js CHANGED
@@ -83,6 +83,36 @@ export function buildLifecycleCommands(phrenPath) {
83
83
  const isWindows = process.platform === "win32";
84
84
  const escapedPhren = phrenPath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
85
85
  const quotedPhren = shellEscape(phrenPath);
86
+ // Prefer the stable wrapper at ~/.local/bin/phren — it survives nvm switches
87
+ // and npx cache clears because it has a built-in npx fallback.
88
+ const localBinDir = homePath(".local", "bin");
89
+ const wrapperPath = path.join(localBinDir, isWindows ? "phren.cmd" : "phren");
90
+ const wrapperExists = fs.existsSync(wrapperPath) && (() => {
91
+ try {
92
+ return fs.readFileSync(wrapperPath, "utf8").includes("PHREN_CLI_WRAPPER");
93
+ }
94
+ catch {
95
+ return false;
96
+ }
97
+ })();
98
+ if (wrapperExists) {
99
+ if (isWindows) {
100
+ return {
101
+ sessionStart: `set "PHREN_PATH=${escapedPhren}" && "${wrapperPath}" hook-session-start`,
102
+ userPromptSubmit: `set "PHREN_PATH=${escapedPhren}" && "${wrapperPath}" hook-prompt`,
103
+ stop: `set "PHREN_PATH=${escapedPhren}" && "${wrapperPath}" hook-stop`,
104
+ hookTool: `set "PHREN_PATH=${escapedPhren}" && "${wrapperPath}" hook-tool`,
105
+ };
106
+ }
107
+ const quotedWrapper = shellEscape(wrapperPath);
108
+ return {
109
+ sessionStart: `PHREN_PATH=${quotedPhren} ${quotedWrapper} hook-session-start`,
110
+ userPromptSubmit: `PHREN_PATH=${quotedPhren} ${quotedWrapper} hook-prompt`,
111
+ stop: `PHREN_PATH=${quotedPhren} ${quotedWrapper} hook-stop`,
112
+ hookTool: `PHREN_PATH=${quotedPhren} ${quotedWrapper} hook-tool`,
113
+ };
114
+ }
115
+ // Direct node path — used when wrapper hasn't been installed yet
86
116
  if (entry) {
87
117
  const escapedEntry = entry.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
88
118
  const quotedEntry = shellEscape(entry);
@@ -101,6 +131,7 @@ export function buildLifecycleCommands(phrenPath) {
101
131
  hookTool: `PHREN_PATH=${quotedPhren} node ${quotedEntry} hook-tool`,
102
132
  };
103
133
  }
134
+ // Last resort — npx
104
135
  const packageSpec = phrenPackageSpec();
105
136
  if (isWindows) {
106
137
  return {
@@ -265,14 +296,19 @@ export function installPhrenCliWrapper(phrenPath) {
265
296
  return false;
266
297
  }
267
298
  }
299
+ const packageSpec = phrenPackageSpec();
268
300
  const content = isWindows
269
- ? `@echo off\r\nrem PHREN_CLI_WRAPPER — managed by phren init; safe to delete\r\nif not defined PHREN_PATH set "PHREN_PATH=${phrenPath}"\r\nnode "${entry}" %*\r\n`
301
+ ? `@echo off\r\nrem PHREN_CLI_WRAPPER — managed by phren init; safe to delete\r\nif not defined PHREN_PATH set "PHREN_PATH=${phrenPath}"\r\nif exist "${entry}" (node "${entry}" %*) else (npx -y ${packageSpec} %*)\r\n`
270
302
  : `#!/bin/sh
271
303
  # PHREN_CLI_WRAPPER — managed by phren init; safe to delete
272
304
  set -u
273
305
  PHREN_PATH="\${PHREN_PATH:-${phrenPath}}"
274
306
  export PHREN_PATH
275
- exec node ${shellEscape(entry)} "$@"
307
+ if [ -f ${shellEscape(entry)} ]; then
308
+ exec node ${shellEscape(entry)} "$@"
309
+ else
310
+ exec npx -y ${packageSpec} "$@"
311
+ fi
276
312
  `;
277
313
  try {
278
314
  fs.mkdirSync(localBinDir, { recursive: true });
@@ -6,6 +6,7 @@ import * as path from "path";
6
6
  import { execFileSync, spawnSync } from "child_process";
7
7
  import { atomicWriteText, debugLog, isRecord, hookConfigPath, homeDir, homePath, findPhrenPath, getProjectDirs, readRootManifest, } from "../shared.js";
8
8
  import { errorMessage } from "../utils.js";
9
+ import { FINDINGS_FILENAME } from "../data/access.js";
9
10
  import { codexJsonCandidates, copilotMcpCandidates, cursorMcpCandidates, vscodeMcpCandidates, } from "../provider-adapters.js";
10
11
  import { removeMcpServerAtPath, removeTomlMcpServer, isPhrenCommand, patchJsonFile, } from "./config.js";
11
12
  import { DEFAULT_PHREN_PATH, log } from "./shared.js";
@@ -171,7 +172,7 @@ async function promptUninstallConfirm(phrenPath) {
171
172
  const projectCount = projectDirs.length;
172
173
  let findingCount = 0;
173
174
  for (const dir of projectDirs) {
174
- const findingsFile = path.join(dir, "FINDINGS.md");
175
+ const findingsFile = path.join(dir, FINDINGS_FILENAME);
175
176
  if (fs.existsSync(findingsFile)) {
176
177
  const content = fs.readFileSync(findingsFile, "utf8");
177
178
  findingCount += content.split("\n").filter((l) => l.startsWith("- ")).length;
@@ -15,6 +15,7 @@ import { STOP_WORDS, errorMessage } from "../utils.js";
15
15
  import { ROOT, STARTER_DIR, VERSION, resolveEntryScript, commandVersion, versionAtLeast, nearestWritableTarget } from "./shared.js";
16
16
  import { readInstallPreferences } from "./preferences.js";
17
17
  import { TASKS_FILENAME } from "../data/tasks.js";
18
+ import { FINDINGS_FILENAME } from "../data/access.js";
18
19
  import { getProjectOwnershipDefault, parseProjectOwnershipMode, readProjectConfig, writeProjectConfig, } from "../project-config.js";
19
20
  import { getBuiltinTopicConfig, normalizeBuiltinTopicDomain } from "../project-topics.js";
20
21
  import { writeSkillMd } from "../link/skills.js";
@@ -916,8 +917,8 @@ export function ensureProjectScaffold(projectDir, projectName, domain = "softwar
916
917
  if (!fs.existsSync(path.join(projectDir, "topic-config.json"))) {
917
918
  atomicWriteText(path.join(projectDir, "topic-config.json"), JSON.stringify({ version: 1, domain: normalizedDomain, topics: inferredTopics }, null, 2) + "\n");
918
919
  }
919
- if (!fs.existsSync(path.join(projectDir, "FINDINGS.md"))) {
920
- atomicWriteText(path.join(projectDir, "FINDINGS.md"), `# ${projectName} FINDINGS\n\n<!-- Findings are captured automatically during sessions and committed on exit -->\n`);
920
+ if (!fs.existsSync(path.join(projectDir, FINDINGS_FILENAME))) {
921
+ atomicWriteText(path.join(projectDir, FINDINGS_FILENAME), `# ${projectName} FINDINGS\n\n<!-- Findings are captured automatically during sessions and committed on exit -->\n`);
921
922
  }
922
923
  if (!fs.existsSync(path.join(projectDir, TASKS_FILENAME))) {
923
924
  atomicWriteText(path.join(projectDir, TASKS_FILENAME), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
@@ -1062,8 +1063,8 @@ export function bootstrapFromExisting(phrenPath, projectPath, opts = {}) {
1062
1063
  if (!fs.existsSync(summaryPath)) {
1063
1064
  atomicWriteText(summaryPath, `# ${projectName}\n\n**What:** Bootstrapped from ${sourceRoot}\n${sourceInfo}\n\n${summaryLines.length > 1 ? summaryLines.slice(1).join("\n") : ""}\n`);
1064
1065
  }
1065
- if (!fs.existsSync(path.join(projDir, "FINDINGS.md"))) {
1066
- atomicWriteText(path.join(projDir, "FINDINGS.md"), `# ${projectName} FINDINGS\n\n<!-- Bootstrapped from ${sourceRoot} -->\n`);
1066
+ if (!fs.existsSync(path.join(projDir, FINDINGS_FILENAME))) {
1067
+ atomicWriteText(path.join(projDir, FINDINGS_FILENAME), `# ${projectName} FINDINGS\n\n<!-- Bootstrapped from ${sourceRoot} -->\n`);
1067
1068
  }
1068
1069
  if (!fs.existsSync(path.join(projDir, TASKS_FILENAME))) {
1069
1070
  atomicWriteText(path.join(projDir, TASKS_FILENAME), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
@@ -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
  }