@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
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.15",
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.15",
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.15",
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.15",
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).
@@ -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 {
@@ -13,6 +13,7 @@ import { countActiveFindings, autoArchiveToReference } from "./archive.js";
13
13
  import { resolveAutoFindingTaskItem, resolveFindingTaskReference, resolveFindingSessionId, } from "../finding/context.js";
14
14
  import { buildLifecycleComments, extractFindingType, parseFindingLifecycle, stripLifecycleComments, } from "../finding/lifecycle.js";
15
15
  import { METADATA_REGEX, } from "./metadata.js";
16
+ import { FINDINGS_FILENAME } from "../data/access.js";
16
17
  /** Default cap for active findings before auto-archiving is triggered. */
17
18
  const DEFAULT_FINDINGS_CAP = 20;
18
19
  const LIFECYCLE_ANNOTATION_RE = METADATA_REGEX.lifecycleAnnotation;
@@ -265,7 +266,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
265
266
  const resolvedDir = safeProjectPath(phrenPath, project);
266
267
  if (!resolvedDir)
267
268
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
268
- const learningsPath = path.join(resolvedDir, "FINDINGS.md");
269
+ const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
269
270
  // Secret/PII scan — reject before anything else (before existence check, before lock)
270
271
  const nowIso = new Date().toISOString();
271
272
  const today = nowIso.slice(0, 10);
@@ -416,7 +417,7 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
416
417
  const resolvedDir = safeProjectPath(phrenPath, project);
417
418
  if (!resolvedDir)
418
419
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
419
- const learningsPath = path.join(resolvedDir, "FINDINGS.md");
420
+ const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
420
421
  const nowIso = new Date().toISOString();
421
422
  const today = nowIso.slice(0, 10);
422
423
  const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project);
@@ -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
  });
@@ -7,6 +7,7 @@ export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks,
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,6 +17,7 @@ export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks,
17
17
  export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, } from "../profile-store.js";
18
18
  export { loadShellState, resetShellState, saveShellState, } from "../shell/state-store.js";
19
19
  export { getRuntimeHealth as readRuntimeHealth } from "../shared/governance.js";
20
+ export const FINDINGS_FILENAME = "FINDINGS.md";
20
21
  function extractDateHeading(line) {
21
22
  const heading = line.match(/^##\s+(.+)$/);
22
23
  if (!heading)
@@ -105,7 +106,7 @@ export function readFindings(phrenPath, project, opts = {}) {
105
106
  const ensured = ensureProject(phrenPath, project);
106
107
  if (!ensured.ok)
107
108
  return forwardErr(ensured);
108
- const findingsPath = path.join(ensured.data, 'FINDINGS.md');
109
+ const findingsPath = path.join(ensured.data, FINDINGS_FILENAME);
109
110
  const file = findingsPath;
110
111
  if (!fs.existsSync(file))
111
112
  return phrenOk([]);
@@ -283,13 +284,13 @@ export function removeFinding(phrenPath, project, match) {
283
284
  const ensured = ensureProject(phrenPath, project);
284
285
  if (!ensured.ok)
285
286
  return forwardErr(ensured);
286
- const findingsPath = path.resolve(path.join(ensured.data, 'FINDINGS.md'));
287
+ const findingsPath = path.resolve(path.join(ensured.data, FINDINGS_FILENAME));
287
288
  if (!findingsPath.startsWith(phrenPath + path.sep) && findingsPath !== phrenPath) {
288
- return phrenErr(`FINDINGS.md path escapes phren store`, PhrenError.VALIDATION_ERROR);
289
+ return phrenErr(`${FINDINGS_FILENAME} path escapes phren store`, PhrenError.VALIDATION_ERROR);
289
290
  }
290
291
  const filePath = findingsPath;
291
292
  if (!fs.existsSync(filePath))
292
- return phrenErr(`No FINDINGS.md file found for "${project}". Add a finding first with add_finding or :find add.`, PhrenError.FILE_NOT_FOUND);
293
+ return phrenErr(`No ${FINDINGS_FILENAME} file found for "${project}". Add a finding first with add_finding or :find add.`, PhrenError.FILE_NOT_FOUND);
293
294
  return withSafeLock(filePath, () => {
294
295
  const lines = fs.readFileSync(filePath, "utf8").split("\n");
295
296
  const needle = normalizeFindingText(match);
@@ -320,12 +321,12 @@ export function removeFindings(phrenPath, project, matches) {
320
321
  const ensured = ensureProject(phrenPath, project);
321
322
  if (!ensured.ok)
322
323
  return forwardErr(ensured);
323
- const findingsPath = path.resolve(path.join(ensured.data, 'FINDINGS.md'));
324
+ const findingsPath = path.resolve(path.join(ensured.data, FINDINGS_FILENAME));
324
325
  if (!findingsPath.startsWith(phrenPath + path.sep) && findingsPath !== phrenPath) {
325
- return phrenErr(`FINDINGS.md path escapes phren store`, PhrenError.VALIDATION_ERROR);
326
+ return phrenErr(`${FINDINGS_FILENAME} path escapes phren store`, PhrenError.VALIDATION_ERROR);
326
327
  }
327
328
  if (!fs.existsSync(findingsPath))
328
- return phrenErr(`No FINDINGS.md file found for "${project}". Add a finding first with add_finding or :find add.`, PhrenError.FILE_NOT_FOUND);
329
+ return phrenErr(`No ${FINDINGS_FILENAME} file found for "${project}". Add a finding first with add_finding or :find add.`, PhrenError.FILE_NOT_FOUND);
329
330
  return withSafeLock(findingsPath, () => {
330
331
  const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
331
332
  const removed = [];
@@ -374,12 +375,12 @@ export function editFinding(phrenPath, project, oldText, newText) {
374
375
  const newTextTrimmed = newText.trim();
375
376
  if (!newTextTrimmed)
376
377
  return phrenErr("New finding text cannot be empty.", PhrenError.EMPTY_INPUT);
377
- const findingsPath = path.resolve(path.join(ensured.data, "FINDINGS.md"));
378
+ const findingsPath = path.resolve(path.join(ensured.data, FINDINGS_FILENAME));
378
379
  if (!findingsPath.startsWith(phrenPath + path.sep) && findingsPath !== phrenPath) {
379
- return phrenErr(`FINDINGS.md path escapes phren store`, PhrenError.VALIDATION_ERROR);
380
+ return phrenErr(`${FINDINGS_FILENAME} path escapes phren store`, PhrenError.VALIDATION_ERROR);
380
381
  }
381
382
  if (!fs.existsSync(findingsPath))
382
- return phrenErr(`No FINDINGS.md file found for "${project}".`, PhrenError.FILE_NOT_FOUND);
383
+ return phrenErr(`No ${FINDINGS_FILENAME} file found for "${project}".`, PhrenError.FILE_NOT_FOUND);
383
384
  return withSafeLock(findingsPath, () => {
384
385
  const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
385
386
  const needle = normalizeFindingText(oldText);
@@ -5,6 +5,7 @@ import { runtimeDir, phrenOk, phrenErr, PhrenError, atomicWriteText } from "../s
5
5
  import { withFileLock } from "../shared/governance.js";
6
6
  import { addFindingToFile } from "../shared/content.js";
7
7
  import { isValidProjectName, errorMessage } from "../utils.js";
8
+ import { FINDINGS_FILENAME } from "../data/access.js";
8
9
  function journalRoot(phrenPath) {
9
10
  const dir = path.join(runtimeDir(phrenPath), "finding-journal");
10
11
  fs.mkdirSync(dir, { recursive: true });
@@ -198,7 +199,7 @@ export function materializeTeamFindings(storePath, project) {
198
199
  }
199
200
  lines.push("");
200
201
  }
201
- const findingsPath = path.join(storePath, project, "FINDINGS.md");
202
+ const findingsPath = path.join(storePath, project, FINDINGS_FILENAME);
202
203
  try {
203
204
  atomicWriteText(findingsPath, lines.join("\n"));
204
205
  return phrenOk({ entryCount: count });
@@ -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`);