@phren/cli 0.1.40 → 0.1.41

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 (105) hide show
  1. package/dist/auth/profiles.js +59 -5
  2. package/dist/cli/actions.js +11 -3
  3. package/dist/cli/config-access.js +8 -1
  4. package/dist/cli/extract.d.ts +27 -1
  5. package/dist/cli/extract.js +243 -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/session-git.d.ts +18 -0
  11. package/dist/cli/session-git.js +47 -0
  12. package/dist/cli/session-start.js +2 -2
  13. package/dist/cli/session-stop.d.ts +11 -0
  14. package/dist/cli/session-stop.js +141 -33
  15. package/dist/cli/session-tool-hook.js +17 -5
  16. package/dist/cli-registry.d.ts +1 -1
  17. package/dist/cli-registry.js +1 -0
  18. package/dist/content/dedup.d.ts +1 -4
  19. package/dist/content/dedup.js +7 -63
  20. package/dist/content/learning.d.ts +20 -2
  21. package/dist/content/learning.js +21 -3
  22. package/dist/content/quality.d.ts +23 -0
  23. package/dist/content/quality.js +123 -0
  24. package/dist/content/secrets.d.ts +52 -0
  25. package/dist/content/secrets.js +193 -0
  26. package/dist/data/access.d.ts +56 -2
  27. package/dist/data/access.js +246 -24
  28. package/dist/entrypoint.js +5 -1
  29. package/dist/finding/impact.js +170 -43
  30. package/dist/finding/lifecycle.d.ts +19 -2
  31. package/dist/finding/lifecycle.js +15 -3
  32. package/dist/git-worktree.d.ts +19 -0
  33. package/dist/git-worktree.js +117 -0
  34. package/dist/governance/policy.d.ts +84 -4
  35. package/dist/governance/policy.js +209 -14
  36. package/dist/governance/rbac.d.ts +8 -0
  37. package/dist/governance/rbac.js +26 -0
  38. package/dist/hooks.d.ts +20 -0
  39. package/dist/hooks.js +113 -3
  40. package/dist/index.js +5 -1
  41. package/dist/init/guard-globals.d.ts +20 -0
  42. package/dist/init/guard-globals.js +72 -6
  43. package/dist/init/init-configure.js +6 -6
  44. package/dist/init/init.js +10 -6
  45. package/dist/init/setup.d.ts +4 -3
  46. package/dist/init/setup.js +120 -16
  47. package/dist/init/store-gitignore.d.ts +29 -0
  48. package/dist/init/store-gitignore.js +48 -0
  49. package/dist/link/doctor.js +86 -20
  50. package/dist/phren-core.d.ts +35 -8
  51. package/dist/phren-core.js +35 -8
  52. package/dist/phren-paths.d.ts +90 -1
  53. package/dist/phren-paths.js +150 -5
  54. package/dist/proactivity.js +1 -1
  55. package/dist/shared/embedding-cache.d.ts +16 -0
  56. package/dist/shared/embedding-cache.js +24 -0
  57. package/dist/shared/fragment-graph.js +10 -0
  58. package/dist/shared/index.d.ts +6 -0
  59. package/dist/shared/index.js +523 -138
  60. package/dist/shared/ollama.d.ts +14 -2
  61. package/dist/shared/ollama.js +84 -5
  62. package/dist/shared/retrieval.d.ts +22 -1
  63. package/dist/shared/retrieval.js +30 -1
  64. package/dist/shared/search-fallback.js +15 -3
  65. package/dist/shared/vector-index.d.ts +20 -1
  66. package/dist/shared/vector-index.js +18 -4
  67. package/dist/shared.d.ts +1 -1
  68. package/dist/shared.js +1 -1
  69. package/dist/status.js +18 -1
  70. package/dist/store-registry.d.ts +22 -0
  71. package/dist/store-registry.js +36 -3
  72. package/dist/task/lifecycle.js +31 -0
  73. package/dist/tools/config.js +16 -7
  74. package/dist/tools/data.js +1 -1
  75. package/dist/tools/extract.js +2 -2
  76. package/dist/tools/finding.js +14 -3
  77. package/dist/tools/graph.js +9 -1
  78. package/dist/tools/memory.js +1 -1
  79. package/dist/tools/notes.js +3 -3
  80. package/dist/tools/ops.js +19 -18
  81. package/dist/tools/search.js +2 -2
  82. package/dist/tools/session.js +2 -2
  83. package/dist/tools/tasks.js +2 -2
  84. package/dist/tools/types.d.ts +32 -2
  85. package/dist/tools/types.js +41 -8
  86. package/dist/ui/scripts.js +2 -2
  87. package/dist/ui/server.js +5 -0
  88. package/package.json +1 -1
  89. package/dist/cli-hooks-git.d.ts +0 -50
  90. package/dist/cli-hooks-git.js +0 -288
  91. package/starter/my-api/.claude/skills/README.md +0 -7
  92. package/starter/my-api/CLAUDE.md +0 -33
  93. package/starter/my-api/FINDINGS.md +0 -9
  94. package/starter/my-api/summary.md +0 -7
  95. package/starter/my-api/tasks.md +0 -7
  96. package/starter/my-first-project/.claude/skills/README.md +0 -7
  97. package/starter/my-first-project/CLAUDE.md +0 -49
  98. package/starter/my-first-project/FINDINGS.md +0 -24
  99. package/starter/my-first-project/summary.md +0 -11
  100. package/starter/my-first-project/tasks.md +0 -25
  101. package/starter/my-frontend/.claude/skills/README.md +0 -7
  102. package/starter/my-frontend/CLAUDE.md +0 -33
  103. package/starter/my-frontend/FINDINGS.md +0 -9
  104. package/starter/my-frontend/summary.md +0 -7
  105. 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
  }
@@ -298,13 +298,21 @@ export async function handleQualityFeedback(args) {
298
298
  console.log(`Recorded feedback: ${feedback} for ${key}`);
299
299
  }
300
300
  export async function handleMemoryUi(args) {
301
- const portArg = args.find((arg) => arg.startsWith("--port="));
301
+ // Accept both `--port=N` and `--port N`. The registry documents the
302
+ // space-separated form (`phren web-ui [--port <n>]`), which silently fell
303
+ // through to the default before — the flag looked accepted and was ignored.
304
+ const eqArg = args.find((arg) => arg.startsWith("--port="));
305
+ const spaceIdx = args.indexOf("--port");
306
+ const rawPort = eqArg
307
+ ? eqArg.slice("--port=".length)
308
+ : (spaceIdx !== -1 ? args[spaceIdx + 1] : undefined);
309
+ const portRequested = rawPort !== undefined;
302
310
  const noOpen = args.includes("--no-open");
303
- const port = portArg ? Number.parseInt(portArg.slice("--port=".length), 10) : 3499;
311
+ const port = portRequested ? Number.parseInt(rawPort, 10) : 3499;
304
312
  const safePort = Number.isNaN(port) ? 3499 : port;
305
313
  await startWebUi(getPhrenPath(), safePort, resolveRuntimeProfile(getPhrenPath()), {
306
314
  autoOpen: !noOpen,
307
- allowPortFallback: !portArg,
315
+ allowPortFallback: !portRequested,
308
316
  });
309
317
  }
310
318
  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,10 @@
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, safeProjectPath } from "../utils.js";
6
6
  import { appendFindingJournal, compactFindingJournals } from "../finding/journal.js";
7
+ import { findingQualityReason } from "../content/quality.js";
7
8
  import { FINDINGS_FILENAME } from "../data/access.js";
8
9
  import { getProactivityLevelForTask, getProactivityLevelForFindings, shouldAutoCaptureFindingsForLevel } from "../proactivity.js";
9
10
  import * as fs from "fs";
@@ -12,6 +13,7 @@ import * as path from "path";
12
13
  import * as crypto from "crypto";
13
14
  import { execFileSync } from "child_process";
14
15
  import { resolveRuntimeProfile } from "../runtime-profile.js";
16
+ import { buildCitationComment, buildSourceComment, } from "../content/citation.js";
15
17
  function runGit(cwd, args) {
16
18
  return runGitShared(cwd, args, EXEC_TIMEOUT_MS, debugLog);
17
19
  }
@@ -212,6 +214,191 @@ export function scoreFindingCandidate(subject, body) {
212
214
  const text = cleaned ? cleaned[0].toUpperCase() + cleaned.slice(1) : subject;
213
215
  return { score: Math.min(score, 0.99), text };
214
216
  }
217
+ // ── Extraction idempotency ───────────────────────────────────────────────────
218
+ // Every extracted candidate is rendered with a `(source commit <hash>)` marker. Without a
219
+ // dedup key on that hash, each sync run re-queued the same commits: one real store had 224
220
+ // review items from only 84 distinct hashes (twenty of them appended eight times each).
221
+ // appendReviewQueue's text dedup does not catch this because the rendered line drifts.
222
+ const SOURCE_COMMIT_MARKER = /\(source commit ([0-9a-f]{7,40})\)/i;
223
+ /** Cap on remembered commits per project so the state file cannot grow without bound. */
224
+ const PROCESSED_MEMORY_LIMIT = 5000;
225
+ const EXTRACT_STATE_SCHEMA_VERSION = 1;
226
+ function shortHash(hash) {
227
+ return hash.slice(0, 8).toLowerCase();
228
+ }
229
+ /**
230
+ * Dedup key for the human-readable part of a candidate.
231
+ *
232
+ * Hash dedup alone is necessary but not sufficient: rebased history re-scrapes an identical
233
+ * commit message under a new hash (observed pairs 0a918619/c55f38fa and 6b9a2ab9/9479d2ad),
234
+ * so the same finding still arrives twice.
235
+ */
236
+ export function extractSubjectKey(text) {
237
+ return text
238
+ .replace(/<!--[\s\S]*?-->/g, " ")
239
+ .replace(new RegExp(SOURCE_COMMIT_MARKER.source, "gi"), " ")
240
+ .replace(/^\s*\[confidence\s+[\d.]+\]\s*/i, "")
241
+ .toLowerCase()
242
+ .replace(/[^a-z0-9]+/g, " ")
243
+ .trim();
244
+ }
245
+ function extractStateFile(phrenPath, project) {
246
+ if (!isValidProjectName(project))
247
+ return null;
248
+ try {
249
+ return runtimeFile(phrenPath, `extract-state-${project}.json`);
250
+ }
251
+ catch (err) {
252
+ debugLog(`extract-memories: no extract state file for ${project}: ${errorMessage(err)}`);
253
+ return null;
254
+ }
255
+ }
256
+ function addMarkersFromContent(content, into) {
257
+ const pattern = new RegExp(SOURCE_COMMIT_MARKER.source, "gi");
258
+ for (const line of content.split("\n")) {
259
+ const matches = [...line.matchAll(pattern)];
260
+ if (!matches.length)
261
+ continue;
262
+ for (const match of matches)
263
+ into.commits.add(shortHash(match[1]));
264
+ // Only lines carrying a marker are extraction output; hand-written findings must not
265
+ // suppress future extraction.
266
+ const key = extractSubjectKey(line.replace(/^\s*-\s*(\[\d{4}-\d{2}-\d{2}\]\s*)?/, ""));
267
+ if (key)
268
+ into.subjects.add(key);
269
+ }
270
+ }
271
+ function addMarkersFromFile(file, into) {
272
+ try {
273
+ if (!fs.existsSync(file))
274
+ return;
275
+ addMarkersFromContent(fs.readFileSync(file, "utf8"), into);
276
+ }
277
+ catch (err) {
278
+ debugLog(`extract-memories: unreadable ${file}: ${errorMessage(err)}`);
279
+ }
280
+ }
281
+ function addMarkersFromJournal(file, into) {
282
+ try {
283
+ if (!fs.existsSync(file))
284
+ return;
285
+ for (const line of fs.readFileSync(file, "utf8").split("\n")) {
286
+ if (!line.trim())
287
+ continue;
288
+ let entry;
289
+ try {
290
+ entry = JSON.parse(line);
291
+ }
292
+ catch {
293
+ continue; // A partially-written journal line is not worth failing extraction over.
294
+ }
295
+ if (typeof entry.commit === "string" && entry.commit)
296
+ into.commits.add(shortHash(entry.commit));
297
+ if (typeof entry.text !== "string")
298
+ continue;
299
+ addMarkersFromContent(entry.text, into);
300
+ }
301
+ }
302
+ catch (err) {
303
+ debugLog(`extract-memories: unreadable journal ${file}: ${errorMessage(err)}`);
304
+ }
305
+ }
306
+ /**
307
+ * Everything this project has already extracted: queued in review.md, promoted into
308
+ * FINDINGS.md, still sitting in the finding journal, or recorded in the state file (which
309
+ * also covers items a human has since approved or rejected out of review.md).
310
+ */
311
+ function readProcessedMemory(phrenPath, project) {
312
+ const memory = { commits: new Set(), subjects: new Set() };
313
+ const projectDir = safeProjectPath(phrenPath, project);
314
+ if (!projectDir)
315
+ return memory;
316
+ addMarkersFromFile(path.join(projectDir, "review.md"), memory);
317
+ addMarkersFromFile(path.join(projectDir, FINDINGS_FILENAME), memory);
318
+ // Accepted candidates land in the journal first and only reach FINDINGS.md on the next
319
+ // compaction, so the journal has to be read too or they come back on the very next run.
320
+ const journalDir = path.join(runtimeDir(phrenPath), "finding-journal", project);
321
+ try {
322
+ if (fs.existsSync(journalDir)) {
323
+ for (const entry of fs.readdirSync(journalDir)) {
324
+ if (entry.endsWith(".jsonl"))
325
+ addMarkersFromJournal(path.join(journalDir, entry), memory);
326
+ }
327
+ }
328
+ }
329
+ catch (err) {
330
+ debugLog(`extract-memories: unreadable journal dir ${journalDir}: ${errorMessage(err)}`);
331
+ }
332
+ const stateFile = extractStateFile(phrenPath, project);
333
+ if (stateFile) {
334
+ try {
335
+ if (fs.existsSync(stateFile)) {
336
+ const parsed = JSON.parse(fs.readFileSync(stateFile, "utf8"));
337
+ if (Array.isArray(parsed.commits)) {
338
+ for (const c of parsed.commits)
339
+ if (typeof c === "string")
340
+ memory.commits.add(shortHash(c));
341
+ }
342
+ if (Array.isArray(parsed.subjects)) {
343
+ for (const s of parsed.subjects)
344
+ if (typeof s === "string" && s)
345
+ memory.subjects.add(s);
346
+ }
347
+ }
348
+ }
349
+ catch (err) {
350
+ debugLog(`extract-memories: unreadable extract state ${stateFile}: ${errorMessage(err)}`);
351
+ }
352
+ }
353
+ return memory;
354
+ }
355
+ function writeProcessedMemory(phrenPath, project, memory) {
356
+ const stateFile = extractStateFile(phrenPath, project);
357
+ if (!stateFile)
358
+ return;
359
+ // Sets keep insertion order, so the tail holds the most recently seen entries.
360
+ const trim = (values) => [...values].slice(-PROCESSED_MEMORY_LIMIT);
361
+ try {
362
+ atomicWriteText(stateFile, JSON.stringify({
363
+ schemaVersion: EXTRACT_STATE_SCHEMA_VERSION,
364
+ updatedAt: new Date().toISOString(),
365
+ commits: trim(memory.commits),
366
+ subjects: trim(memory.subjects),
367
+ }) + "\n");
368
+ }
369
+ catch (err) {
370
+ debugLog(`extract-memories: could not persist extract state for ${project}: ${errorMessage(err)}`);
371
+ }
372
+ }
373
+ /**
374
+ * Render the provenance a queued candidate needs to stay promotable.
375
+ *
376
+ * A candidate below `autoAcceptThreshold` never reaches FINDINGS.md — approving it
377
+ * is what writes it. For the promoted finding to be indistinguishable from an
378
+ * auto-accepted one, the queue line has to carry the same provenance the journal
379
+ * path passes to `addFindingToFile`: source/session plus repo/commit/file. Both are
380
+ * emitted as HTML comments, invisible in rendered markdown and stripped from the
381
+ * queue item's display text.
382
+ */
383
+ export function buildQueueProvenanceMeta(opts) {
384
+ const parts = [];
385
+ const sourceComment = buildSourceComment({
386
+ ...(opts.source ? { source: opts.source } : {}),
387
+ ...(opts.sessionId ? { session_id: opts.sessionId } : {}),
388
+ });
389
+ if (sourceComment)
390
+ parts.push(sourceComment);
391
+ if (opts.repo || opts.commit || opts.file) {
392
+ const citation = {
393
+ created_at: opts.capturedAt ?? new Date().toISOString(),
394
+ ...(opts.repo ? { repo: opts.repo } : {}),
395
+ ...(opts.commit ? { commit: opts.commit } : {}),
396
+ ...(opts.file ? { file: opts.file } : {}),
397
+ };
398
+ parts.push(buildCitationComment(citation));
399
+ }
400
+ return parts.join(" ");
401
+ }
215
402
  // ── handleExtractMemories ────────────────────────────────────────────────────
216
403
  export async function handleExtractMemories(projectArg, cwdArg, silent = false, sessionId, source = "extract") {
217
404
  const project = inferProject(projectArg);
@@ -248,15 +435,39 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
248
435
  const ghCandidates = isFeatureEnabled("PHREN_FEATURE_GH_MINING", false)
249
436
  ? await mineGithubCandidates(repoRoot)
250
437
  : [];
438
+ const processed = readProcessedMemory(getPhrenPath(), project);
251
439
  let accepted = 0;
252
440
  let queued = 0;
441
+ let duplicates = 0;
442
+ let rejected = 0;
443
+ /** True when this commit/subject pair has already been extracted in an earlier run. */
444
+ const alreadyExtracted = (commitKey, subjectKey) => (commitKey !== "" && processed.commits.has(commitKey)) || (subjectKey !== "" && processed.subjects.has(subjectKey));
445
+ const remember = (commitKey, subjectKey) => {
446
+ if (commitKey)
447
+ processed.commits.add(commitKey);
448
+ if (subjectKey)
449
+ processed.subjects.add(subjectKey);
450
+ };
253
451
  for (const rec of records) {
254
452
  if (!shouldAutoCaptureFindingsForLevel(findingsLevel, rec.subject, rec.body))
255
453
  continue;
256
454
  const candidate = scoreFindingCandidate(rec.subject, rec.body);
257
455
  if (!candidate)
258
456
  continue;
259
- const line = `${candidate.text} (source commit ${rec.hash.slice(0, 8)})`;
457
+ const quality = findingQualityReason(candidate.text);
458
+ if (quality) {
459
+ debugLog(`extract-memories: rejected commit ${rec.hash.slice(0, 8)} (${quality}): ${candidate.text.slice(0, 80)}`);
460
+ rejected++;
461
+ continue;
462
+ }
463
+ const commitKey = shortHash(rec.hash);
464
+ const subjectKey = extractSubjectKey(candidate.text);
465
+ if (alreadyExtracted(commitKey, subjectKey)) {
466
+ duplicates++;
467
+ continue;
468
+ }
469
+ remember(commitKey, subjectKey);
470
+ const line = `${candidate.text} (source commit ${commitKey})`;
260
471
  if (candidate.score >= threshold) {
261
472
  appendFindingJournal(getPhrenPath(), project, line, {
262
473
  source,
@@ -267,7 +478,12 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
267
478
  accepted++;
268
479
  }
269
480
  else {
270
- const qr1 = appendReviewQueue(getPhrenPath(), project, "Review", [`[confidence ${candidate.score.toFixed(2)}] ${line}`]);
481
+ // Queued candidates are NOT written to FINDINGS.md — approving one is what
482
+ // creates the finding, so the line must carry everything promotion needs.
483
+ const qr1 = appendReviewQueue(getPhrenPath(), project, "Review", [{
484
+ text: `[confidence ${candidate.score.toFixed(2)}] ${line}`,
485
+ meta: buildQueueProvenanceMeta({ source, sessionId, repo: repoRoot, commit: rec.hash }),
486
+ }]);
271
487
  if (qr1.ok)
272
488
  queued += qr1.data;
273
489
  }
@@ -275,7 +491,20 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
275
491
  for (const c of ghCandidates) {
276
492
  if (!shouldAutoCaptureFindingsForLevel(findingsLevel, c.sourceText ?? c.text))
277
493
  continue;
278
- const line = `${c.text}${c.commit ? ` (source commit ${c.commit.slice(0, 8)})` : ""}`;
494
+ const quality = findingQualityReason(c.text);
495
+ if (quality) {
496
+ debugLog(`extract-memories: rejected github candidate (${quality}): ${c.text.slice(0, 80)}`);
497
+ rejected++;
498
+ continue;
499
+ }
500
+ const commitKey = c.commit ? shortHash(c.commit) : "";
501
+ const subjectKey = extractSubjectKey(c.text);
502
+ if (alreadyExtracted(commitKey, subjectKey)) {
503
+ duplicates++;
504
+ continue;
505
+ }
506
+ remember(commitKey, subjectKey);
507
+ const line = `${c.text}${commitKey ? ` (source commit ${commitKey})` : ""}`;
279
508
  if (c.text.startsWith("CI failure pattern:")) {
280
509
  const key = entryScoreKey(project, FINDINGS_FILENAME, line);
281
510
  recordFeedback(getPhrenPath(), key, "regression");
@@ -291,7 +520,10 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
291
520
  accepted++;
292
521
  }
293
522
  else {
294
- const qr2 = appendReviewQueue(getPhrenPath(), project, "Review", [`[confidence ${c.score.toFixed(2)}] ${line}`]);
523
+ const qr2 = appendReviewQueue(getPhrenPath(), project, "Review", [{
524
+ text: `[confidence ${c.score.toFixed(2)}] ${line}`,
525
+ meta: buildQueueProvenanceMeta({ source, sessionId, repo: repoRoot, commit: c.commit, file: c.file }),
526
+ }]);
295
527
  if (qr2.ok)
296
528
  queued += qr2.data;
297
529
  }
@@ -300,8 +532,10 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
300
532
  const compacted = compactFindingJournals(getPhrenPath(), project);
301
533
  debugLog(`extract-memories compacted journals for ${project}: added=${compacted.added} skipped=${compacted.skipped} failed=${compacted.failed}`);
302
534
  }
535
+ writeProcessedMemory(getPhrenPath(), project, processed);
303
536
  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`);
537
+ appendAuditLog(getPhrenPath(), "extract_memories", `project=${project} accepted=${accepted} queued=${queued} duplicates=${duplicates} rejected=${rejected} window_days=${days}`);
538
+ if (!silent) {
539
+ console.log(`Extracted memory candidates for ${project}: accepted=${accepted}, queued=${queued}, duplicates=${duplicates}, rejected=${rejected}, window=${days}d`);
540
+ }
307
541
  }
@@ -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";
@@ -36,7 +36,20 @@ export async function handleReviewNamespace(args) {
36
36
  console.error(`Failed to ${action} item: ${result.error ?? "Unknown error"}`);
37
37
  process.exit(1);
38
38
  }
39
- console.log(`${action === "approve" ? "✓ Approved" : "✗ Rejected"}: ${lineText.slice(0, 100)}${lineText.length > 100 ? "..." : ""}`);
39
+ // Print the data layer's own message rather than a generic one. approve
40
+ // and reject each have several distinct outcomes — promoted, already
41
+ // present, already archived, removed from the archive, discarded — and
42
+ // collapsing them into "Approved" hides the difference that matters most:
43
+ // on a store whose findings have aged into reference/topics/, most
44
+ // approvals dequeue without promoting anything.
45
+ const summary = lineText.slice(0, 100) + (lineText.length > 100 ? "..." : "");
46
+ const mark = action === "approve" ? "✓" : "✗";
47
+ const payload = result.data;
48
+ const detail = typeof payload === "string"
49
+ ? payload
50
+ : payload?.message;
51
+ console.log(`${mark} ${detail ?? (action === "approve" ? "Approved" : "Rejected")}`);
52
+ console.log(` ${summary}`);
40
53
  return;
41
54
  }
42
55
  // Default: show review queue (first arg is project name if not a subcommand)