@phren/cli 0.1.40 → 0.1.42

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 (119) hide show
  1. package/dist/auth/profiles.js +59 -5
  2. package/dist/cli/actions.js +12 -16
  3. package/dist/cli/config-access.js +8 -1
  4. package/dist/cli/extract.d.ts +27 -1
  5. package/dist/cli/extract.js +244 -9
  6. package/dist/cli/govern.js +6 -87
  7. package/dist/cli/hooks-context.d.ts +1 -1
  8. package/dist/cli/hooks-context.js +1 -1
  9. package/dist/cli/namespaces-review.js +14 -1
  10. package/dist/cli/namespaces-utils.js +1 -1
  11. package/dist/cli/session-git.d.ts +18 -0
  12. package/dist/cli/session-git.js +47 -0
  13. package/dist/cli/session-start.js +2 -2
  14. package/dist/cli/session-stop.d.ts +11 -0
  15. package/dist/cli/session-stop.js +141 -33
  16. package/dist/cli/session-tool-hook.js +17 -5
  17. package/dist/cli-registry.d.ts +1 -1
  18. package/dist/cli-registry.js +1 -0
  19. package/dist/content/archive.js +3 -2
  20. package/dist/content/dedup.d.ts +1 -4
  21. package/dist/content/dedup.js +11 -66
  22. package/dist/content/learning.d.ts +20 -2
  23. package/dist/content/learning.js +26 -7
  24. package/dist/content/quality.d.ts +23 -0
  25. package/dist/content/quality.js +123 -0
  26. package/dist/content/secrets.d.ts +52 -0
  27. package/dist/content/secrets.js +196 -0
  28. package/dist/data/access.d.ts +56 -2
  29. package/dist/data/access.js +255 -32
  30. package/dist/data/tasks.js +46 -6
  31. package/dist/entrypoint.js +5 -1
  32. package/dist/finding/impact.js +170 -43
  33. package/dist/finding/lifecycle.d.ts +19 -2
  34. package/dist/finding/lifecycle.js +18 -5
  35. package/dist/git-worktree.d.ts +19 -0
  36. package/dist/git-worktree.js +117 -0
  37. package/dist/governance/policy.d.ts +84 -4
  38. package/dist/governance/policy.js +213 -17
  39. package/dist/governance/rbac.d.ts +8 -0
  40. package/dist/governance/rbac.js +26 -0
  41. package/dist/hooks.d.ts +20 -0
  42. package/dist/hooks.js +113 -3
  43. package/dist/index.js +5 -1
  44. package/dist/init/guard-globals.d.ts +20 -0
  45. package/dist/init/guard-globals.js +72 -6
  46. package/dist/init/init-configure.js +6 -6
  47. package/dist/init/init.js +10 -6
  48. package/dist/init/setup.d.ts +4 -3
  49. package/dist/init/setup.js +120 -16
  50. package/dist/init/store-gitignore.d.ts +29 -0
  51. package/dist/init/store-gitignore.js +48 -0
  52. package/dist/link/doctor.js +86 -20
  53. package/dist/phren-core.d.ts +35 -8
  54. package/dist/phren-core.js +35 -8
  55. package/dist/phren-paths.d.ts +90 -1
  56. package/dist/phren-paths.js +150 -5
  57. package/dist/proactivity.js +1 -1
  58. package/dist/project-config.js +3 -2
  59. package/dist/project-topics.js +13 -12
  60. package/dist/shared/data-utils.js +13 -3
  61. package/dist/shared/embedding-cache.d.ts +16 -0
  62. package/dist/shared/embedding-cache.js +24 -0
  63. package/dist/shared/fragment-graph.js +10 -0
  64. package/dist/shared/index.d.ts +6 -0
  65. package/dist/shared/index.js +523 -138
  66. package/dist/shared/ollama.d.ts +14 -2
  67. package/dist/shared/ollama.js +84 -5
  68. package/dist/shared/retrieval.d.ts +22 -1
  69. package/dist/shared/retrieval.js +30 -1
  70. package/dist/shared/search-fallback.js +15 -3
  71. package/dist/shared/vector-index.d.ts +20 -1
  72. package/dist/shared/vector-index.js +18 -4
  73. package/dist/shared.d.ts +1 -1
  74. package/dist/shared.js +1 -1
  75. package/dist/status.js +18 -1
  76. package/dist/store-registry.d.ts +22 -0
  77. package/dist/store-registry.js +36 -3
  78. package/dist/store-routing.d.ts +8 -0
  79. package/dist/store-routing.js +23 -1
  80. package/dist/task/lifecycle.js +31 -0
  81. package/dist/tools/config.js +19 -9
  82. package/dist/tools/data.js +1 -1
  83. package/dist/tools/extract-facts.js +3 -2
  84. package/dist/tools/extract.js +2 -2
  85. package/dist/tools/finding.js +20 -8
  86. package/dist/tools/graph.js +9 -1
  87. package/dist/tools/memory.js +1 -1
  88. package/dist/tools/notes.js +3 -3
  89. package/dist/tools/ops.js +19 -18
  90. package/dist/tools/search.js +2 -2
  91. package/dist/tools/session.js +2 -2
  92. package/dist/tools/tasks.js +2 -2
  93. package/dist/tools/types.d.ts +32 -2
  94. package/dist/tools/types.js +41 -8
  95. package/dist/ui/scripts.js +2 -2
  96. package/dist/ui/server.js +7 -6
  97. package/dist/utils-fts.js +3 -2
  98. package/dist/utils-paths.d.ts +1 -0
  99. package/dist/utils-paths.js +1 -1
  100. package/dist/utils.d.ts +1 -1
  101. package/dist/utils.js +1 -1
  102. package/package.json +1 -1
  103. package/dist/cli-hooks-git.d.ts +0 -50
  104. package/dist/cli-hooks-git.js +0 -288
  105. package/starter/my-api/.claude/skills/README.md +0 -7
  106. package/starter/my-api/CLAUDE.md +0 -33
  107. package/starter/my-api/FINDINGS.md +0 -9
  108. package/starter/my-api/summary.md +0 -7
  109. package/starter/my-api/tasks.md +0 -7
  110. package/starter/my-first-project/.claude/skills/README.md +0 -7
  111. package/starter/my-first-project/CLAUDE.md +0 -49
  112. package/starter/my-first-project/FINDINGS.md +0 -24
  113. package/starter/my-first-project/summary.md +0 -11
  114. package/starter/my-first-project/tasks.md +0 -25
  115. package/starter/my-frontend/.claude/skills/README.md +0 -7
  116. package/starter/my-frontend/CLAUDE.md +0 -33
  117. package/starter/my-frontend/FINDINGS.md +0 -9
  118. package/starter/my-frontend/summary.md +0 -7
  119. package/starter/my-frontend/tasks.md +0 -7
@@ -1,6 +1,8 @@
1
1
  import * as fs from "fs";
2
2
  import * as path from "path";
3
- import { atomicWriteText, homePath } from "../phren-paths.js";
3
+ import { atomicWriteText, ensurePrivateDir, homePath } from "../phren-paths.js";
4
+ /** POSIX mode for every file that holds plaintext credentials. */
5
+ const CREDENTIAL_FILE_MODE = 0o600;
4
6
  const DEFAULT_PROFILE_IDS = {
5
7
  openai: "openai-default",
6
8
  openrouter: "openrouter-default",
@@ -19,24 +21,75 @@ function defaultLabel(provider) {
19
21
  return "OpenAI Codex Subscription";
20
22
  }
21
23
  }
24
+ // auth-profiles.json holds OpenAI/OpenRouter/Anthropic API keys and OpenAI
25
+ // Codex OAuth access+refresh tokens in plaintext. It used to live under
26
+ // `.config/`, which the store's .gitignore template does NOT ignore (that
27
+ // directory is meant for shared, non-secret policy JSON) — so any store
28
+ // synced to a git remote pushed every user's credentials there. `.runtime/`
29
+ // is gitignored by the store template, so credentials now live there
30
+ // instead. See migrateLegacyAuthProfilesFile() below for the one-time move.
22
31
  function authProfileDir() {
23
- return homePath(".phren", ".config");
32
+ return homePath(".phren", ".runtime");
24
33
  }
25
34
  function authProfilesFilePath() {
26
35
  return path.join(authProfileDir(), "auth-profiles.json");
27
36
  }
37
+ function legacyAuthProfileDir() {
38
+ return homePath(".phren", ".config");
39
+ }
40
+ function legacyAuthProfilesFilePath() {
41
+ return path.join(legacyAuthProfileDir(), "auth-profiles.json");
42
+ }
28
43
  function codexCliAuthPath() {
29
44
  return homePath(".codex", "auth.json");
30
45
  }
46
+ /**
47
+ * `mkdirSync(..., { mode: 0o700 })` only applies the mode to directories it
48
+ * creates. `~/.phren/.runtime` is created by `runtimeFile()` on any ordinary
49
+ * session long before the first `phren auth` call, so the mode argument was a
50
+ * no-op on every real install and the credential directory sat at 0755.
51
+ * ensurePrivateDir tightens an existing directory as well as creating one.
52
+ */
31
53
  function ensureAuthProfileDir() {
32
- fs.mkdirSync(authProfileDir(), { recursive: true, mode: 0o700 });
54
+ ensurePrivateDir(authProfileDir());
55
+ }
56
+ /**
57
+ * One-time migration off the old `.config/auth-profiles.json` location.
58
+ * Runs at the top of loadStore(), the common entry point for every read and
59
+ * write in this module, so it fires on the next `phren auth`/MCP call after
60
+ * upgrading — no separate migration command needed. Idempotent: once the
61
+ * file is moved, the legacy path no longer exists, so every later call is a
62
+ * single fs.existsSync() no-op. Best-effort: if the move fails (e.g. a
63
+ * cross-device home directory, or a permissions issue), the legacy file is
64
+ * left in place — it stays covered by the `.config/auth-profiles.json`
65
+ * .gitignore entry added alongside this migration, and every call retries.
66
+ */
67
+ function migrateLegacyAuthProfilesFile() {
68
+ const legacyPath = legacyAuthProfilesFilePath();
69
+ const currentPath = authProfilesFilePath();
70
+ if (fs.existsSync(currentPath) || !fs.existsSync(legacyPath))
71
+ return;
72
+ try {
73
+ ensureAuthProfileDir();
74
+ fs.renameSync(legacyPath, currentPath);
75
+ try {
76
+ fs.chmodSync(currentPath, CREDENTIAL_FILE_MODE);
77
+ }
78
+ catch { /* best effort */ }
79
+ }
80
+ catch { /* best effort — retried on the next call */ }
33
81
  }
34
82
  function persistProfiles(data) {
35
83
  ensureAuthProfileDir();
36
84
  const filePath = authProfilesFilePath();
37
- atomicWriteText(filePath, JSON.stringify(data, null, 2) + "\n");
85
+ // Mode goes to the temp file, before the rename. Chmod-ing after the write
86
+ // leaves the API keys and OAuth refresh tokens at 0644 for the duration of
87
+ // the write — a window any local user can poll for.
88
+ atomicWriteText(filePath, JSON.stringify(data, null, 2) + "\n", { mode: CREDENTIAL_FILE_MODE });
89
+ // Belt and braces: rename over a pre-existing 0644 file keeps the *new*
90
+ // inode's mode, but an interrupted upgrade could leave the old one behind.
38
91
  try {
39
- fs.chmodSync(filePath, 0o600);
92
+ fs.chmodSync(filePath, CREDENTIAL_FILE_MODE);
40
93
  }
41
94
  catch { /* best effort */ }
42
95
  }
@@ -59,6 +112,7 @@ function normalizeStore(raw) {
59
112
  };
60
113
  }
61
114
  function loadStore() {
115
+ migrateLegacyAuthProfilesFile();
62
116
  try {
63
117
  return normalizeStore(JSON.parse(fs.readFileSync(authProfilesFilePath(), "utf8")));
64
118
  }
@@ -15,19 +15,7 @@ import { runSearch, runFragmentSearch, parseFragmentSearchArgs, runRelatedDocs,
15
15
  import { resolveRuntimeProfile } from "../runtime-profile.js";
16
16
  import { getProjectConsolidationStatus, CONSOLIDATION_ENTRY_THRESHOLD } from "../content/validate.js";
17
17
  import { listAllSessions } from "../tools/session.js";
18
- function resolveProjectStorePath(phrenPath, project) {
19
- try {
20
- const { getNonPrimaryStores } = require("../store-registry.js");
21
- if (fs.existsSync(path.join(phrenPath, project)))
22
- return phrenPath;
23
- for (const store of getNonPrimaryStores(phrenPath)) {
24
- if (fs.existsSync(path.join(store.path, project)))
25
- return store.path;
26
- }
27
- }
28
- catch { /* fall through */ }
29
- return phrenPath;
30
- }
18
+ import { resolveProjectStorePath } from "./namespaces-utils.js";
31
19
  async function runAndPrint(fn) {
32
20
  const result = await fn();
33
21
  if (result.lines.length > 0)
@@ -298,13 +286,21 @@ export async function handleQualityFeedback(args) {
298
286
  console.log(`Recorded feedback: ${feedback} for ${key}`);
299
287
  }
300
288
  export async function handleMemoryUi(args) {
301
- const portArg = args.find((arg) => arg.startsWith("--port="));
289
+ // Accept both `--port=N` and `--port N`. The registry documents the
290
+ // space-separated form (`phren web-ui [--port <n>]`), which silently fell
291
+ // through to the default before — the flag looked accepted and was ignored.
292
+ const eqArg = args.find((arg) => arg.startsWith("--port="));
293
+ const spaceIdx = args.indexOf("--port");
294
+ const rawPort = eqArg
295
+ ? eqArg.slice("--port=".length)
296
+ : (spaceIdx !== -1 ? args[spaceIdx + 1] : undefined);
297
+ const portRequested = rawPort !== undefined;
302
298
  const noOpen = args.includes("--no-open");
303
- const port = portArg ? Number.parseInt(portArg.slice("--port=".length), 10) : 3499;
299
+ const port = portRequested ? Number.parseInt(rawPort, 10) : 3499;
304
300
  const safePort = Number.isNaN(port) ? 3499 : port;
305
301
  await startWebUi(getPhrenPath(), safePort, resolveRuntimeProfile(getPhrenPath()), {
306
302
  autoOpen: !noOpen,
307
- allowPortFallback: !portArg,
303
+ allowPortFallback: !portRequested,
308
304
  });
309
305
  }
310
306
  export async function handleShell(_args, profile) {
@@ -1,7 +1,7 @@
1
1
  import { getPhrenPath } from "../shared.js";
2
2
  import { buildConfigView } from "../config/resolve.js";
3
3
  import { isValidProjectName } from "../utils.js";
4
- import { ACCESS_ROLE_KEYS, setAccessRoles } from "../governance/rbac.js";
4
+ import { ACCESS_ROLE_KEYS, ACL_LOCKOUT_HINT, permissionDeniedError, setAccessRoles } from "../governance/rbac.js";
5
5
  import { parseProjectArg, warnIfUnregistered } from "./config-shared.js";
6
6
  // ── Access control ───────────────────────────────────────────────────────────
7
7
  function parseRoleList(raw) {
@@ -50,6 +50,13 @@ export function handleConfigAccess(args) {
50
50
  if (projectArg) {
51
51
  warnIfUnregistered(phrenPath, projectArg);
52
52
  }
53
+ // Rewriting the ACL is admin-only. Open mode (no ACL configured anywhere)
54
+ // is still permitted, so the first `phren config access set` bootstraps.
55
+ const denied = permissionDeniedError(phrenPath, "manage_config", projectArg);
56
+ if (denied) {
57
+ console.error(`${denied} ${ACL_LOCKOUT_HINT}`);
58
+ process.exit(1);
59
+ }
53
60
  setAccessRoles(phrenPath, patch, projectArg);
54
61
  printAccessSnapshot(phrenPath, projectArg);
55
62
  return;
@@ -1,4 +1,4 @@
1
- import type { FindingProvenanceSource } from "../content/citation.js";
1
+ import { type FindingProvenanceSource } from "../content/citation.js";
2
2
  export declare function parseGitLogRecords(cwd: string, days: number): Array<{
3
3
  hash: string;
4
4
  subject: string;
@@ -18,5 +18,31 @@ export declare function scoreFindingCandidate(subject: string, body: string): {
18
18
  score: number;
19
19
  text: string;
20
20
  } | null;
21
+ /**
22
+ * Dedup key for the human-readable part of a candidate.
23
+ *
24
+ * Hash dedup alone is necessary but not sufficient: rebased history re-scrapes an identical
25
+ * commit message under a new hash (observed pairs 0a918619/c55f38fa and 6b9a2ab9/9479d2ad),
26
+ * so the same finding still arrives twice.
27
+ */
28
+ export declare function extractSubjectKey(text: string): string;
29
+ /**
30
+ * Render the provenance a queued candidate needs to stay promotable.
31
+ *
32
+ * A candidate below `autoAcceptThreshold` never reaches FINDINGS.md — approving it
33
+ * is what writes it. For the promoted finding to be indistinguishable from an
34
+ * auto-accepted one, the queue line has to carry the same provenance the journal
35
+ * path passes to `addFindingToFile`: source/session plus repo/commit/file. Both are
36
+ * emitted as HTML comments, invisible in rendered markdown and stripped from the
37
+ * queue item's display text.
38
+ */
39
+ export declare function buildQueueProvenanceMeta(opts: {
40
+ source?: FindingProvenanceSource;
41
+ sessionId?: string;
42
+ repo?: string;
43
+ commit?: string;
44
+ file?: string;
45
+ capturedAt?: string;
46
+ }): string;
21
47
  export declare function handleExtractMemories(projectArg?: string, cwdArg?: string, silent?: boolean, sessionId?: string, source?: FindingProvenanceSource): Promise<void>;
22
48
  export {};
@@ -1,9 +1,11 @@
1
- import { debugLog, appendAuditLog, EXEC_TIMEOUT_MS, getPhrenPath, } from "../shared.js";
1
+ import { debugLog, appendAuditLog, atomicWriteText, EXEC_TIMEOUT_MS, getPhrenPath, runtimeDir, runtimeFile, } from "../shared.js";
2
2
  import { appendReviewQueue, getRetentionPolicy, recordFeedback, flushEntryScores, entryScoreKey, } from "../shared/governance.js";
3
3
  import { detectProject } from "../shared/index.js";
4
4
  import { commandExists } from "../hooks.js";
5
- import { runGit as runGitShared, isFeatureEnabled, clampInt, errorMessage, resolveExecCommand } from "../utils.js";
5
+ import { runGit as runGitShared, isFeatureEnabled, clampInt, errorMessage, isValidProjectName, resolveExecCommand } from "../utils.js";
6
+ import { storeAwareProjectPath } from "../store-routing.js";
6
7
  import { appendFindingJournal, compactFindingJournals } from "../finding/journal.js";
8
+ import { findingQualityReason } from "../content/quality.js";
7
9
  import { FINDINGS_FILENAME } from "../data/access.js";
8
10
  import { getProactivityLevelForTask, getProactivityLevelForFindings, shouldAutoCaptureFindingsForLevel } from "../proactivity.js";
9
11
  import * as fs from "fs";
@@ -12,6 +14,7 @@ import * as path from "path";
12
14
  import * as crypto from "crypto";
13
15
  import { execFileSync } from "child_process";
14
16
  import { resolveRuntimeProfile } from "../runtime-profile.js";
17
+ import { buildCitationComment, buildSourceComment, } from "../content/citation.js";
15
18
  function runGit(cwd, args) {
16
19
  return runGitShared(cwd, args, EXEC_TIMEOUT_MS, debugLog);
17
20
  }
@@ -212,6 +215,191 @@ export function scoreFindingCandidate(subject, body) {
212
215
  const text = cleaned ? cleaned[0].toUpperCase() + cleaned.slice(1) : subject;
213
216
  return { score: Math.min(score, 0.99), text };
214
217
  }
218
+ // ── Extraction idempotency ───────────────────────────────────────────────────
219
+ // Every extracted candidate is rendered with a `(source commit <hash>)` marker. Without a
220
+ // dedup key on that hash, each sync run re-queued the same commits: one real store had 224
221
+ // review items from only 84 distinct hashes (twenty of them appended eight times each).
222
+ // appendReviewQueue's text dedup does not catch this because the rendered line drifts.
223
+ const SOURCE_COMMIT_MARKER = /\(source commit ([0-9a-f]{7,40})\)/i;
224
+ /** Cap on remembered commits per project so the state file cannot grow without bound. */
225
+ const PROCESSED_MEMORY_LIMIT = 5000;
226
+ const EXTRACT_STATE_SCHEMA_VERSION = 1;
227
+ function shortHash(hash) {
228
+ return hash.slice(0, 8).toLowerCase();
229
+ }
230
+ /**
231
+ * Dedup key for the human-readable part of a candidate.
232
+ *
233
+ * Hash dedup alone is necessary but not sufficient: rebased history re-scrapes an identical
234
+ * commit message under a new hash (observed pairs 0a918619/c55f38fa and 6b9a2ab9/9479d2ad),
235
+ * so the same finding still arrives twice.
236
+ */
237
+ export function extractSubjectKey(text) {
238
+ return text
239
+ .replace(/<!--[\s\S]*?-->/g, " ")
240
+ .replace(new RegExp(SOURCE_COMMIT_MARKER.source, "gi"), " ")
241
+ .replace(/^\s*\[confidence\s+[\d.]+\]\s*/i, "")
242
+ .toLowerCase()
243
+ .replace(/[^a-z0-9]+/g, " ")
244
+ .trim();
245
+ }
246
+ function extractStateFile(phrenPath, project) {
247
+ if (!isValidProjectName(project))
248
+ return null;
249
+ try {
250
+ return runtimeFile(phrenPath, `extract-state-${project}.json`);
251
+ }
252
+ catch (err) {
253
+ debugLog(`extract-memories: no extract state file for ${project}: ${errorMessage(err)}`);
254
+ return null;
255
+ }
256
+ }
257
+ function addMarkersFromContent(content, into) {
258
+ const pattern = new RegExp(SOURCE_COMMIT_MARKER.source, "gi");
259
+ for (const line of content.split("\n")) {
260
+ const matches = [...line.matchAll(pattern)];
261
+ if (!matches.length)
262
+ continue;
263
+ for (const match of matches)
264
+ into.commits.add(shortHash(match[1]));
265
+ // Only lines carrying a marker are extraction output; hand-written findings must not
266
+ // suppress future extraction.
267
+ const key = extractSubjectKey(line.replace(/^\s*-\s*(\[\d{4}-\d{2}-\d{2}\]\s*)?/, ""));
268
+ if (key)
269
+ into.subjects.add(key);
270
+ }
271
+ }
272
+ function addMarkersFromFile(file, into) {
273
+ try {
274
+ if (!fs.existsSync(file))
275
+ return;
276
+ addMarkersFromContent(fs.readFileSync(file, "utf8"), into);
277
+ }
278
+ catch (err) {
279
+ debugLog(`extract-memories: unreadable ${file}: ${errorMessage(err)}`);
280
+ }
281
+ }
282
+ function addMarkersFromJournal(file, into) {
283
+ try {
284
+ if (!fs.existsSync(file))
285
+ return;
286
+ for (const line of fs.readFileSync(file, "utf8").split("\n")) {
287
+ if (!line.trim())
288
+ continue;
289
+ let entry;
290
+ try {
291
+ entry = JSON.parse(line);
292
+ }
293
+ catch {
294
+ continue; // A partially-written journal line is not worth failing extraction over.
295
+ }
296
+ if (typeof entry.commit === "string" && entry.commit)
297
+ into.commits.add(shortHash(entry.commit));
298
+ if (typeof entry.text !== "string")
299
+ continue;
300
+ addMarkersFromContent(entry.text, into);
301
+ }
302
+ }
303
+ catch (err) {
304
+ debugLog(`extract-memories: unreadable journal ${file}: ${errorMessage(err)}`);
305
+ }
306
+ }
307
+ /**
308
+ * Everything this project has already extracted: queued in review.md, promoted into
309
+ * FINDINGS.md, still sitting in the finding journal, or recorded in the state file (which
310
+ * also covers items a human has since approved or rejected out of review.md).
311
+ */
312
+ function readProcessedMemory(phrenPath, project) {
313
+ const memory = { commits: new Set(), subjects: new Set() };
314
+ const projectDir = storeAwareProjectPath(phrenPath, project);
315
+ if (!projectDir)
316
+ return memory;
317
+ addMarkersFromFile(path.join(projectDir, "review.md"), memory);
318
+ addMarkersFromFile(path.join(projectDir, FINDINGS_FILENAME), memory);
319
+ // Accepted candidates land in the journal first and only reach FINDINGS.md on the next
320
+ // compaction, so the journal has to be read too or they come back on the very next run.
321
+ const journalDir = path.join(runtimeDir(phrenPath), "finding-journal", project);
322
+ try {
323
+ if (fs.existsSync(journalDir)) {
324
+ for (const entry of fs.readdirSync(journalDir)) {
325
+ if (entry.endsWith(".jsonl"))
326
+ addMarkersFromJournal(path.join(journalDir, entry), memory);
327
+ }
328
+ }
329
+ }
330
+ catch (err) {
331
+ debugLog(`extract-memories: unreadable journal dir ${journalDir}: ${errorMessage(err)}`);
332
+ }
333
+ const stateFile = extractStateFile(phrenPath, project);
334
+ if (stateFile) {
335
+ try {
336
+ if (fs.existsSync(stateFile)) {
337
+ const parsed = JSON.parse(fs.readFileSync(stateFile, "utf8"));
338
+ if (Array.isArray(parsed.commits)) {
339
+ for (const c of parsed.commits)
340
+ if (typeof c === "string")
341
+ memory.commits.add(shortHash(c));
342
+ }
343
+ if (Array.isArray(parsed.subjects)) {
344
+ for (const s of parsed.subjects)
345
+ if (typeof s === "string" && s)
346
+ memory.subjects.add(s);
347
+ }
348
+ }
349
+ }
350
+ catch (err) {
351
+ debugLog(`extract-memories: unreadable extract state ${stateFile}: ${errorMessage(err)}`);
352
+ }
353
+ }
354
+ return memory;
355
+ }
356
+ function writeProcessedMemory(phrenPath, project, memory) {
357
+ const stateFile = extractStateFile(phrenPath, project);
358
+ if (!stateFile)
359
+ return;
360
+ // Sets keep insertion order, so the tail holds the most recently seen entries.
361
+ const trim = (values) => [...values].slice(-PROCESSED_MEMORY_LIMIT);
362
+ try {
363
+ atomicWriteText(stateFile, JSON.stringify({
364
+ schemaVersion: EXTRACT_STATE_SCHEMA_VERSION,
365
+ updatedAt: new Date().toISOString(),
366
+ commits: trim(memory.commits),
367
+ subjects: trim(memory.subjects),
368
+ }) + "\n");
369
+ }
370
+ catch (err) {
371
+ debugLog(`extract-memories: could not persist extract state for ${project}: ${errorMessage(err)}`);
372
+ }
373
+ }
374
+ /**
375
+ * Render the provenance a queued candidate needs to stay promotable.
376
+ *
377
+ * A candidate below `autoAcceptThreshold` never reaches FINDINGS.md — approving it
378
+ * is what writes it. For the promoted finding to be indistinguishable from an
379
+ * auto-accepted one, the queue line has to carry the same provenance the journal
380
+ * path passes to `addFindingToFile`: source/session plus repo/commit/file. Both are
381
+ * emitted as HTML comments, invisible in rendered markdown and stripped from the
382
+ * queue item's display text.
383
+ */
384
+ export function buildQueueProvenanceMeta(opts) {
385
+ const parts = [];
386
+ const sourceComment = buildSourceComment({
387
+ ...(opts.source ? { source: opts.source } : {}),
388
+ ...(opts.sessionId ? { session_id: opts.sessionId } : {}),
389
+ });
390
+ if (sourceComment)
391
+ parts.push(sourceComment);
392
+ if (opts.repo || opts.commit || opts.file) {
393
+ const citation = {
394
+ created_at: opts.capturedAt ?? new Date().toISOString(),
395
+ ...(opts.repo ? { repo: opts.repo } : {}),
396
+ ...(opts.commit ? { commit: opts.commit } : {}),
397
+ ...(opts.file ? { file: opts.file } : {}),
398
+ };
399
+ parts.push(buildCitationComment(citation));
400
+ }
401
+ return parts.join(" ");
402
+ }
215
403
  // ── handleExtractMemories ────────────────────────────────────────────────────
216
404
  export async function handleExtractMemories(projectArg, cwdArg, silent = false, sessionId, source = "extract") {
217
405
  const project = inferProject(projectArg);
@@ -248,15 +436,39 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
248
436
  const ghCandidates = isFeatureEnabled("PHREN_FEATURE_GH_MINING", false)
249
437
  ? await mineGithubCandidates(repoRoot)
250
438
  : [];
439
+ const processed = readProcessedMemory(getPhrenPath(), project);
251
440
  let accepted = 0;
252
441
  let queued = 0;
442
+ let duplicates = 0;
443
+ let rejected = 0;
444
+ /** True when this commit/subject pair has already been extracted in an earlier run. */
445
+ const alreadyExtracted = (commitKey, subjectKey) => (commitKey !== "" && processed.commits.has(commitKey)) || (subjectKey !== "" && processed.subjects.has(subjectKey));
446
+ const remember = (commitKey, subjectKey) => {
447
+ if (commitKey)
448
+ processed.commits.add(commitKey);
449
+ if (subjectKey)
450
+ processed.subjects.add(subjectKey);
451
+ };
253
452
  for (const rec of records) {
254
453
  if (!shouldAutoCaptureFindingsForLevel(findingsLevel, rec.subject, rec.body))
255
454
  continue;
256
455
  const candidate = scoreFindingCandidate(rec.subject, rec.body);
257
456
  if (!candidate)
258
457
  continue;
259
- const line = `${candidate.text} (source commit ${rec.hash.slice(0, 8)})`;
458
+ const quality = findingQualityReason(candidate.text);
459
+ if (quality) {
460
+ debugLog(`extract-memories: rejected commit ${rec.hash.slice(0, 8)} (${quality}): ${candidate.text.slice(0, 80)}`);
461
+ rejected++;
462
+ continue;
463
+ }
464
+ const commitKey = shortHash(rec.hash);
465
+ const subjectKey = extractSubjectKey(candidate.text);
466
+ if (alreadyExtracted(commitKey, subjectKey)) {
467
+ duplicates++;
468
+ continue;
469
+ }
470
+ remember(commitKey, subjectKey);
471
+ const line = `${candidate.text} (source commit ${commitKey})`;
260
472
  if (candidate.score >= threshold) {
261
473
  appendFindingJournal(getPhrenPath(), project, line, {
262
474
  source,
@@ -267,7 +479,12 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
267
479
  accepted++;
268
480
  }
269
481
  else {
270
- const qr1 = appendReviewQueue(getPhrenPath(), project, "Review", [`[confidence ${candidate.score.toFixed(2)}] ${line}`]);
482
+ // Queued candidates are NOT written to FINDINGS.md — approving one is what
483
+ // creates the finding, so the line must carry everything promotion needs.
484
+ const qr1 = appendReviewQueue(getPhrenPath(), project, "Review", [{
485
+ text: `[confidence ${candidate.score.toFixed(2)}] ${line}`,
486
+ meta: buildQueueProvenanceMeta({ source, sessionId, repo: repoRoot, commit: rec.hash }),
487
+ }]);
271
488
  if (qr1.ok)
272
489
  queued += qr1.data;
273
490
  }
@@ -275,7 +492,20 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
275
492
  for (const c of ghCandidates) {
276
493
  if (!shouldAutoCaptureFindingsForLevel(findingsLevel, c.sourceText ?? c.text))
277
494
  continue;
278
- const line = `${c.text}${c.commit ? ` (source commit ${c.commit.slice(0, 8)})` : ""}`;
495
+ const quality = findingQualityReason(c.text);
496
+ if (quality) {
497
+ debugLog(`extract-memories: rejected github candidate (${quality}): ${c.text.slice(0, 80)}`);
498
+ rejected++;
499
+ continue;
500
+ }
501
+ const commitKey = c.commit ? shortHash(c.commit) : "";
502
+ const subjectKey = extractSubjectKey(c.text);
503
+ if (alreadyExtracted(commitKey, subjectKey)) {
504
+ duplicates++;
505
+ continue;
506
+ }
507
+ remember(commitKey, subjectKey);
508
+ const line = `${c.text}${commitKey ? ` (source commit ${commitKey})` : ""}`;
279
509
  if (c.text.startsWith("CI failure pattern:")) {
280
510
  const key = entryScoreKey(project, FINDINGS_FILENAME, line);
281
511
  recordFeedback(getPhrenPath(), key, "regression");
@@ -291,7 +521,10 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
291
521
  accepted++;
292
522
  }
293
523
  else {
294
- const qr2 = appendReviewQueue(getPhrenPath(), project, "Review", [`[confidence ${c.score.toFixed(2)}] ${line}`]);
524
+ const qr2 = appendReviewQueue(getPhrenPath(), project, "Review", [{
525
+ text: `[confidence ${c.score.toFixed(2)}] ${line}`,
526
+ meta: buildQueueProvenanceMeta({ source, sessionId, repo: repoRoot, commit: c.commit, file: c.file }),
527
+ }]);
295
528
  if (qr2.ok)
296
529
  queued += qr2.data;
297
530
  }
@@ -300,8 +533,10 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
300
533
  const compacted = compactFindingJournals(getPhrenPath(), project);
301
534
  debugLog(`extract-memories compacted journals for ${project}: added=${compacted.added} skipped=${compacted.skipped} failed=${compacted.failed}`);
302
535
  }
536
+ writeProcessedMemory(getPhrenPath(), project, processed);
303
537
  flushEntryScores(getPhrenPath());
304
- appendAuditLog(getPhrenPath(), "extract_memories", `project=${project} accepted=${accepted} queued=${queued} window_days=${days}`);
305
- if (!silent)
306
- console.log(`Extracted memory candidates for ${project}: accepted=${accepted}, queued=${queued}, window=${days}d`);
538
+ appendAuditLog(getPhrenPath(), "extract_memories", `project=${project} accepted=${accepted} queued=${queued} duplicates=${duplicates} rejected=${rejected} window_days=${days}`);
539
+ if (!silent) {
540
+ console.log(`Extracted memory candidates for ${project}: accepted=${accepted}, queued=${queued}, duplicates=${duplicates}, rejected=${rejected}, window=${days}d`);
541
+ }
307
542
  }
@@ -1,6 +1,7 @@
1
1
  import { appendAuditLog, qualityMarkers, getProjectDirs, getPhrenPath, } from "../shared.js";
2
2
  import { appendReviewQueue, getRetentionPolicy, consolidateProjectFindings, updateRuntimeHealth, pruneDeadMemories, } from "../shared/governance.js";
3
3
  import { filterTrustedFindingsDetailed, } from "../shared/content.js";
4
+ import { isLowValueFinding } from "../content/quality.js";
4
5
  import * as fs from "fs";
5
6
  import * as path from "path";
6
7
  import { handleExtractMemories } from "./extract.js";
@@ -88,7 +89,7 @@ export async function handleGovernMemories(projectArg, silent = false, dryRun =
88
89
  conflictCount += conflicts.length;
89
90
  const lowValue = content.split("\n")
90
91
  .filter((l) => l.startsWith("- "))
91
- .filter((l) => /(fixed stuff|updated things|misc|temp|wip|quick note)/i.test(l) || l.length < 16);
92
+ .filter((l) => isLowValueFinding(l));
92
93
  reviewCount += lowValue.length;
93
94
  if (!dryRun) {
94
95
  appendReviewQueue(getPhrenPath(), project, "Stale", stale);
@@ -123,91 +124,9 @@ export async function handlePruneMemories(args = []) {
123
124
  console.log(result.error);
124
125
  return;
125
126
  }
126
- console.log(result.data);
127
- // TTL enforcement: move entries older than ttlDays that haven't been retrieved recently
128
- const policy = getRetentionPolicy(getPhrenPath());
129
- const ttlDays = policy.ttlDays;
130
- const retrievalGraceDays = Math.floor(ttlDays / 2);
131
- const now = Date.now();
132
- // Load retrieval log once for all projects
133
- const retrievalLogPath = path.join(getPhrenPath(), ".runtime", "retrieval-log.jsonl");
134
- let retrievalEntries = [];
135
- if (fs.existsSync(retrievalLogPath)) {
136
- try {
137
- retrievalEntries = fs.readFileSync(retrievalLogPath, "utf8")
138
- .split("\n")
139
- .filter(Boolean)
140
- .map(line => { try {
141
- return JSON.parse(line);
142
- }
143
- catch {
144
- return null;
145
- } }) // null filtered below
146
- .filter((e) => e !== null);
147
- }
148
- catch (err) {
149
- if ((process.env.PHREN_DEBUG))
150
- logger.debug("cli-govern", `retrievalLog readParse: ${errorMessage(err)}`);
151
- }
152
- }
153
- // Build map of last retrieval date by file+bullet key
154
- const lastRetrievalByKey = new Map();
155
- for (const entry of retrievalEntries) {
156
- const key = `${entry.file}:${entry.section}`;
157
- const ts = Date.parse(entry.retrievedAt);
158
- if (!Number.isNaN(ts)) {
159
- const existing = lastRetrievalByKey.get(key) || 0;
160
- if (ts > existing)
161
- lastRetrievalByKey.set(key, ts);
162
- }
163
- }
164
- let ttlExpired = 0;
165
- for (const project of projects) {
166
- const learningsPath = path.join(getPhrenPath(), project, FINDINGS_FILENAME);
167
- if (!fs.existsSync(learningsPath))
168
- continue;
169
- const content = fs.readFileSync(learningsPath, "utf8");
170
- const lines = content.split("\n");
171
- const expiredEntries = [];
172
- for (let i = 0; i < lines.length; i++) {
173
- const line = lines[i];
174
- // Look for entries with <!-- created: YYYY-MM-DD --> timestamps
175
- if (!line.startsWith("- "))
176
- continue;
177
- const createdMatch = line.match(/<!--\s*created:\s*(\d{4}-\d{2}-\d{2})\s*-->/);
178
- if (!createdMatch)
179
- continue; // No timestamp, skip defensively
180
- const createdDate = createdMatch[1];
181
- const createdMs = Date.parse(`${createdDate}T00:00:00Z`);
182
- if (Number.isNaN(createdMs))
183
- continue;
184
- const ageDays = Math.floor((now - createdMs) / 86400000);
185
- if (ageDays <= ttlDays)
186
- continue;
187
- // Check if retrieved within the grace period.
188
- // Retrieval is logged at document level (project/FINDINGS.md + doc.type), so look up
189
- // by the document-level key to match the format written by cli-hooks-output recordRetrieval.
190
- const retrievalKey = `${project}/FINDINGS.md:findings`;
191
- const lastRetrieval = lastRetrievalByKey.get(retrievalKey) || 0;
192
- const daysSinceRetrieval = lastRetrieval ? Math.floor((now - lastRetrieval) / 86400000) : Infinity;
193
- if (daysSinceRetrieval <= retrievalGraceDays)
194
- continue;
195
- expiredEntries.push(`[ttl-expired: ${createdDate}] ${line.slice(2).trim()}`);
196
- ttlExpired++;
197
- }
198
- if (expiredEntries.length > 0 && !dryRun) {
199
- appendReviewQueue(getPhrenPath(), project, "Stale", expiredEntries);
200
- }
201
- if (expiredEntries.length > 0 && dryRun) {
202
- for (const entry of expiredEntries) {
203
- console.log(`[dry-run] [${project}] Would move to review queue: ${entry.slice(0, 120)}`);
204
- }
205
- }
206
- }
207
- if (ttlExpired > 0) {
208
- const verb = dryRun ? "Would move" : "Moved";
209
- console.log(`${verb} ${ttlExpired} TTL-expired entr${ttlExpired === 1 ? "y" : "ies"} to review.md`);
210
- }
127
+ // pruneDeadMemories owns TTL -> Stale promotion so nightly maintenance gets it too;
128
+ // its message already reports how many entries moved.
129
+ console.log(result.data.message);
211
130
  if (dryRun)
212
131
  return;
213
132
  const backups = summarizeBackupChanges(beforeBackups, projects);
@@ -475,7 +394,7 @@ export async function handleBackgroundMaintenance(projectArg) {
475
394
  const compacted = compactFindingJournals(getPhrenPath(), projectArg);
476
395
  const governance = await handleGovernMemories(projectArg, true);
477
396
  const pruneResult = pruneDeadMemories(getPhrenPath(), projectArg);
478
- const pruneMsg = pruneResult.ok ? pruneResult.data : pruneResult.error;
397
+ const pruneMsg = pruneResult.ok ? pruneResult.data.message.replace(/\n+/g, " ") : pruneResult.error;
479
398
  if (!pruneResult.ok) {
480
399
  updateRuntimeHealth(getPhrenPath(), {
481
400
  lastGovernance: {
@@ -16,7 +16,7 @@ export type HookEvent = "SessionStart" | "Stop" | "UserPromptSubmit" | "PostTool
16
16
  export declare function checkHookGuard(ctx: HookContext, event: HookEvent): string | null;
17
17
  /** Log a guard skip and optionally update runtime health. */
18
18
  export declare function handleGuardSkip(ctx: HookContext, hookName: string, reason: string, healthUpdate?: Record<string, unknown>): void;
19
- export { debugLog, appendAuditLog, getPhrenPath, readRootManifest, sessionMarker, runtimeFile, EXEC_TIMEOUT_MS, getProjectDirs, findProjectNameCaseInsensitive, homePath, } from "../shared.js";
19
+ export { debugLog, appendAuditLog, getPhrenPath, readRootManifest, sessionMarker, runtimeFile, EXEC_TIMEOUT_MS, getProjectDirs, findProjectNameCaseInsensitive, projectSlugFromPath, homePath, } from "../shared.js";
20
20
  export { updateRuntimeHealth, buildSyncStatus, getWorkflowPolicy, withFileLock, appendReviewQueue, recordFeedback, getQualityMultiplier, } from "../shared/governance.js";
21
21
  export { detectProject } from "../shared/index.js";
22
22
  export { isProjectHookEnabled, readProjectConfig, getProjectSourcePath } from "../project-config.js";
@@ -38,7 +38,7 @@ export function handleGuardSkip(ctx, hookName, reason, healthUpdate) {
38
38
  appendAuditLog(ctx.phrenPath, hookName, `status=${reason}`);
39
39
  }
40
40
  // Re-export frequently used functions so hook handlers can import from one place
41
- export { debugLog, appendAuditLog, getPhrenPath, readRootManifest, sessionMarker, runtimeFile, EXEC_TIMEOUT_MS, getProjectDirs, findProjectNameCaseInsensitive, homePath, } from "../shared.js";
41
+ export { debugLog, appendAuditLog, getPhrenPath, readRootManifest, sessionMarker, runtimeFile, EXEC_TIMEOUT_MS, getProjectDirs, findProjectNameCaseInsensitive, projectSlugFromPath, homePath, } from "../shared.js";
42
42
  export { updateRuntimeHealth, buildSyncStatus, getWorkflowPolicy, withFileLock, appendReviewQueue, recordFeedback, getQualityMultiplier, } from "../shared/governance.js";
43
43
  export { detectProject } from "../shared/index.js";
44
44
  export { isProjectHookEnabled, readProjectConfig, getProjectSourcePath } from "../project-config.js";