@phren/cli 0.1.53 → 0.2.1

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.
@@ -1,6 +1,8 @@
1
1
  import { getPhrenPath, readRootManifest } from "../shared.js";
2
2
  import { listMachines as listMachinesStore, listProfiles as listProfilesStore } from "../data/access.js";
3
3
  import { setTelemetryEnabled, getTelemetrySummary, resetTelemetry } from "../telemetry.js";
4
+ import { readInstallPreferences, updateInstallPreferences } from "../init/preferences.js";
5
+ import { resolveMcpProfile } from "../mcp/profile.js";
4
6
  import * as path from "path";
5
7
  import { buildConfigView } from "../config/resolve.js";
6
8
  import { CONFIG_DOMAINS } from "../config/schema.js";
@@ -115,6 +117,8 @@ export async function handleConfig(args) {
115
117
  return handleConfigProfiles();
116
118
  case "telemetry":
117
119
  return handleConfigTelemetry(rest);
120
+ case "mcp-profile":
121
+ return handleConfigMcpProfile(rest);
118
122
  case "proactivity":
119
123
  case "proactivity.findings":
120
124
  case "proactivity.tasks":
@@ -201,6 +205,30 @@ function handleConfigProfiles() {
201
205
  console.log(" (no projects)");
202
206
  }
203
207
  }
208
+ function handleConfigMcpProfile(args) {
209
+ const phrenPath = getPhrenPath();
210
+ const want = args[0]?.trim().toLowerCase();
211
+ if (want === "core" || want === "full") {
212
+ updateInstallPreferences(phrenPath, () => ({ mcpProfile: want }));
213
+ console.log(`MCP profile set to ${want}. Restart your MCP clients (Claude Code, Cursor, …) to pick it up.`);
214
+ if (want === "core")
215
+ console.log("Agents see 10 tools; everything else is reachable through phren_admin.");
216
+ else
217
+ console.log("Agents see every tool by name, plus the revise_finding / manage_task / session composites.");
218
+ return;
219
+ }
220
+ if (want) {
221
+ console.error(`Unknown profile "${args[0]}". Use core or full.`);
222
+ process.exitCode = 1;
223
+ return;
224
+ }
225
+ const current = resolveMcpProfile(phrenPath);
226
+ const source = process.env.PHREN_MCP_PROFILE ? "PHREN_MCP_PROFILE" : (readInstallPreferences(phrenPath).mcpProfile ? "install preferences" : "default");
227
+ console.log(`MCP profile: ${current} (${source})`);
228
+ console.log(current === "core"
229
+ ? "10 tools: search_knowledge, get_memory_detail, get_project_summary, add_finding, revise_finding, get_tasks, add_task, manage_task, session, phren_admin."
230
+ : "Every tool by name. `phren config mcp-profile core` for the compact surface.");
231
+ }
204
232
  function handleConfigTelemetry(args) {
205
233
  const action = args[0];
206
234
  switch (action) {
@@ -8,4 +8,9 @@ export declare function handleGovernMemories(projectArg?: string, silent?: boole
8
8
  export declare function handlePruneMemories(args?: string[]): Promise<void>;
9
9
  export declare function handleConsolidateMemories(args?: string[]): Promise<void>;
10
10
  export declare function handleMaintain(args: string[]): Promise<void | GovernanceSummary>;
11
+ /**
12
+ * `phren maintain summarize [project] [--llm] [--force]`: write the "## Now"
13
+ * block at the top of every topic file and "What phren knows" in summary.md.
14
+ */
15
+ export declare function handleSummarize(args: string[]): Promise<void>;
11
16
  export declare function handleBackgroundMaintenance(projectArg?: string): Promise<void>;
@@ -10,6 +10,8 @@ import { FINDINGS_FILENAME } from "../data/access.js";
10
10
  import { logger } from "../logger.js";
11
11
  import { compactFindingJournals } from "../finding/journal.js";
12
12
  import { resolveRuntimeProfile } from "../runtime-profile.js";
13
+ import { summarizeProject } from "../content/summarize.js";
14
+ import { tidyDoneTasks } from "../data/tasks.js";
13
15
  // ── Shared helpers ───────────────────────────────────────────────────────────
14
16
  function targetProjects(projectArg) {
15
17
  const profile = resolveRuntimeProfile(getPhrenPath());
@@ -303,6 +305,8 @@ export async function handleMaintain(args) {
303
305
  }
304
306
  case "prune":
305
307
  return handlePruneMemories(rest);
308
+ case "summarize":
309
+ return handleSummarize(rest);
306
310
  case "consolidate":
307
311
  return handleConsolidateMemories(rest);
308
312
  case "extract":
@@ -387,12 +391,73 @@ async function handleRestoreBackup(args) {
387
391
  appendAuditLog(getPhrenPath(), "restore_backup", `project=${projectArg} files=${projectBackups.length}`);
388
392
  }
389
393
  // ── Background maintenance ───────────────────────────────────────────────────
394
+ /**
395
+ * `phren maintain summarize [project] [--llm] [--force]`: write the "## Now"
396
+ * block at the top of every topic file and "What phren knows" in summary.md.
397
+ */
398
+ export async function handleSummarize(args) {
399
+ let projectArg;
400
+ let llm = false;
401
+ let force = false;
402
+ for (const arg of args) {
403
+ if (arg === "--llm") {
404
+ llm = true;
405
+ continue;
406
+ }
407
+ if (arg === "--force") {
408
+ force = true;
409
+ continue;
410
+ }
411
+ if (arg.startsWith("-")) {
412
+ console.error(`Unknown summarize flag: ${arg}`);
413
+ console.error("Usage: phren maintain summarize [project] [--llm] [--force]");
414
+ process.exit(1);
415
+ }
416
+ projectArg = arg;
417
+ }
418
+ const phrenPath = getPhrenPath();
419
+ const projects = targetProjects(projectArg);
420
+ let topics = 0;
421
+ let updated = 0;
422
+ for (const project of projects) {
423
+ const result = await summarizeProject(phrenPath, project, { llm, force });
424
+ topics += result.topics.length;
425
+ updated += result.topics.filter((t) => t.updated).length + (result.summaryUpdated ? 1 : 0);
426
+ const split = result.topics.filter((t) => t.split).map((t) => path.basename(t.split));
427
+ console.log(`${project}: ${result.topics.length} topic file(s), ${result.topics.filter((t) => t.updated).length} refreshed${result.summaryUpdated ? ", summary.md updated" : ""}${split.length ? `, split: ${split.join(", ")}` : ""}`);
428
+ }
429
+ console.log(`Summarized ${projects.length} project(s): ${topics} topic file(s), ${updated} file(s) written${llm ? " (LLM prose where a model answered)" : ""}.`);
430
+ appendAuditLog(phrenPath, "summarize", `projects=${projects.length} topics=${topics} updated=${updated} llm=${llm}`);
431
+ }
390
432
  export async function handleBackgroundMaintenance(projectArg) {
391
433
  const markers = qualityMarkers(getPhrenPath());
392
434
  const startedAt = new Date().toISOString();
393
435
  try {
394
436
  const compacted = compactFindingJournals(getPhrenPath(), projectArg);
395
437
  const governance = await handleGovernMemories(projectArg, true);
438
+ // Done tasks past thirty move to .config/task-archive, and topic files get
439
+ // their "## Now" block refreshed when they changed. Both structural and
440
+ // cheap; a model is only consulted from `phren maintain summarize --llm`.
441
+ let tidied = 0;
442
+ let summarized = 0;
443
+ for (const project of targetProjects(projectArg)) {
444
+ try {
445
+ const tidy = tidyDoneTasks(getPhrenPath(), project, 30);
446
+ if (tidy.ok && tidy.data.startsWith("Tidied"))
447
+ tidied++;
448
+ }
449
+ catch (err) {
450
+ logger.debug("maintenance", `tidy ${project}: ${errorMessage(err)}`);
451
+ }
452
+ try {
453
+ const summary = await summarizeProject(getPhrenPath(), project, {});
454
+ if (summary.topics.some((t) => t.updated) || summary.summaryUpdated)
455
+ summarized++;
456
+ }
457
+ catch (err) {
458
+ logger.debug("maintenance", `summarize ${project}: ${errorMessage(err)}`);
459
+ }
460
+ }
396
461
  const pruneResult = pruneDeadMemories(getPhrenPath(), projectArg);
397
462
  const pruneMsg = pruneResult.ok ? pruneResult.data.message.replace(/\n+/g, " ") : pruneResult.error;
398
463
  if (!pruneResult.ok) {
@@ -414,7 +479,7 @@ export async function handleBackgroundMaintenance(projectArg) {
414
479
  detail: `journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed}; projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}; ${pruneMsg}`,
415
480
  },
416
481
  });
417
- appendAuditLog(getPhrenPath(), "background_maintenance", `status=ok journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed} projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}`);
482
+ appendAuditLog(getPhrenPath(), "background_maintenance", `status=ok journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed} projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount} tasks_tidied=${tidied} summarized=${summarized}`);
418
483
  }
419
484
  catch (err) {
420
485
  const errMsg = errorMessage(err);
package/dist/cli/hooks.js CHANGED
@@ -31,13 +31,14 @@ export { buildHookOutput, } from "./hooks-output.js";
31
31
  // Session
32
32
  export { handleHookSessionStart, handleHookStop, handleBackgroundSync, handleHookContext, handleHookTool, trackSessionMetrics, filterConversationInsightsForProactivity, extractToolFindings, filterToolFindingsForProactivity, resolveSubprocessArgs, } from "./hooks-session.js";
33
33
  // ── Imports for the orchestrator ─────────────────────────────────────────────
34
- import { searchDocumentsAsync, applyTrustFilter, rankResults, applyRelevanceFloor, DEFAULT_MIN_QUERY_RELEVANCE, selectSnippets, detectTaskIntent, } from "../shared/retrieval.js";
34
+ import { searchDocumentsAsync, applyTrustFilter, rankResults, applyRelevanceFloor, DEFAULT_MIN_QUERY_RELEVANCE, selectSnippets, detectTaskIntent, wantsTasks } from "../shared/retrieval.js";
35
35
  import { buildHookOutput } from "./hooks-output.js";
36
36
  import { getGitContext, trackSessionMetrics, } from "./hooks-session.js";
37
37
  import { approximateTokens, SNIPPET_OVERHEAD_TOKENS } from "../shared/retrieval.js";
38
38
  import { resolveRuntimeProfile } from "../runtime-profile.js";
39
39
  import { handleTaskPromptLifecycle } from "../task/lifecycle.js";
40
40
  import { bestFindingNodeId } from "../finding-graph-id.js";
41
+ import { readKnowsBlock } from "../content/summarize.js";
41
42
  // Auto-learn from prompts was removed — it learned conversational noise ("bro", "idk", typos)
42
43
  // as synonyms for high-frequency terms. Manual `phren config synonyms add` still works.
43
44
  // Future: finding-based co-occurrence mining (phren maintain command, not live hook).
@@ -152,6 +153,9 @@ export async function handleHookPrompt() {
152
153
  // Notes are intentionally available to explicit search, but are personal scratch
153
154
  // context and should never be injected into an agent prompt automatically.
154
155
  rows = rows.filter((row) => row.type !== "notes");
156
+ // Tasks are a backlog, not memory: only when the prompt is about the work.
157
+ if (!wantsTasks(prompt, intent))
158
+ rows = rows.filter((row) => row.type !== "task");
155
159
  stage.trustMs = Date.now() - tTrust0;
156
160
  if (!rows.length)
157
161
  process.exit(0);
@@ -194,10 +198,30 @@ export async function handleHookPrompt() {
194
198
  safeTokenBudget = Math.min(Math.floor(safeTokenBudget * 1.3), parseInt(process.env.PHREN_MAX_INJECT_TOKENS ?? '2000', 10));
195
199
  }
196
200
  const tSelect0 = Date.now();
197
- const { selected, usedTokens } = selectSnippets(rows, keywords, safeTokenBudget, safeLineBudget, safeCharBudget);
201
+ let { selected, usedTokens } = selectSnippets(rows, keywords, safeTokenBudget, safeLineBudget, safeCharBudget);
198
202
  stage.selectMs = Date.now() - tSelect0;
199
203
  if (!selected.length)
200
204
  process.exit(0);
205
+ // Once per session per project: the "What phren knows" paragraph from
206
+ // summary.md, so the agent gets the shape of a project's archive before
207
+ // individual bullets. Written by `phren maintain summarize`; absent until then.
208
+ if (detectedProject && sessionId) {
209
+ const knowsMarker = sessionMarker(getPhrenPath(), `knows-${sessionId}-${detectedProject}`);
210
+ if (!fs.existsSync(knowsMarker)) {
211
+ const knows = readKnowsBlock(getPhrenPath(), detectedProject);
212
+ if (knows) {
213
+ const text = knows.text.length > 520 ? `${knows.text.slice(0, 519)}…` : knows.text;
214
+ selected = [{ doc: { project: detectedProject, filename: "summary.md", type: "summary", content: knows.text, path: knows.path }, snippet: text, key: `knows:${detectedProject}` }, ...selected.filter((s) => s.key !== `knows:${detectedProject}`)];
215
+ usedTokens += approximateTokens(text) + SNIPPET_OVERHEAD_TOKENS;
216
+ try {
217
+ fs.writeFileSync(knowsMarker, "");
218
+ }
219
+ catch (err) {
220
+ debugLog(`knows marker: ${errorMessage(err)}`);
221
+ }
222
+ }
223
+ }
224
+ }
201
225
  // Injection budget: cap total injected tokens across all content
202
226
  const maxInjectTokens = clampInt(process.env.PHREN_MAX_INJECT_TOKENS, 2000, 200, 20000);
203
227
  let budgetSelected = selected;
@@ -94,11 +94,13 @@ const CONFIG_SUBCOMMANDS = [
94
94
  { name: "machines", usage: "phren config machines", summary: "Registered machines" },
95
95
  { name: "profiles", usage: "phren config profiles", summary: "Profiles and projects" },
96
96
  { name: "telemetry", usage: "phren config telemetry [on|off]", summary: "Opt-in usage telemetry" },
97
+ { name: "mcp-profile", usage: "phren config mcp-profile [core|full]", summary: "MCP tool surface: 10 core tools or all of them" },
97
98
  ];
98
99
  const MAINTAIN_SUBCOMMANDS = [
99
100
  { name: "govern", usage: "phren maintain govern [project]", summary: "Queue stale memories for review" },
100
101
  { name: "prune", usage: "phren maintain prune [project]", summary: "Delete expired entries" },
101
102
  { name: "consolidate", usage: "phren maintain consolidate [project]", summary: "Deduplicate findings" },
103
+ { name: "summarize", usage: "phren maintain summarize [project] [--llm] [--force]", summary: "Write what each topic archive amounts to, and what phren knows per project" },
102
104
  { name: "extract", usage: "phren maintain extract [project]", summary: "Mine git/GitHub signals" },
103
105
  ];
104
106
  const STORE_SUBCOMMANDS = [
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Give the archive a shape.
3
+ *
4
+ * Findings age out of FINDINGS.md into reference/topics/<topic>.md, append-only,
5
+ * grouped under "## Archived <date>" headings. A store a year old carries
6
+ * hundreds of thousands of words there, reachable only by keyword: search finds
7
+ * bullet 312, and nothing says what the topic amounts to. This writes a "## Now"
8
+ * block at the top of each topic file — structural by default (counts, tags,
9
+ * what is mentioned most, the newest headlines), a prose paragraph when an LLM
10
+ * is configured — and a "What phren knows" block at the end of summary.md that
11
+ * the prompt hook injects once per session for the project at hand. Both live
12
+ * between markers, so re-running replaces rather than accumulates. Nothing in
13
+ * the archive itself is rewritten; a topic file past a size cap is split, oldest
14
+ * sections first, into <topic>.older.md.
15
+ */
16
+ export declare const NOW_START = "<!-- phren:now:start -->";
17
+ export declare const NOW_END = "<!-- phren:now:end -->";
18
+ export declare const KNOWS_START = "<!-- phren:knows:start -->";
19
+ export declare const KNOWS_END = "<!-- phren:knows:end -->";
20
+ /** Bullets a topic file may hold before the oldest sections move to <topic>.older.md. */
21
+ export declare const TOPIC_SPLIT_AT = 400;
22
+ export interface ArchivedBullet {
23
+ date: string;
24
+ tag: string;
25
+ text: string;
26
+ }
27
+ export interface TopicDigest {
28
+ slug: string;
29
+ file: string;
30
+ bullets: number;
31
+ tags: Record<string, number>;
32
+ first: string;
33
+ last: string;
34
+ mentioned: string[];
35
+ headlines: string[];
36
+ }
37
+ /** Every "- " bullet under an "## Archived <date>" heading (or before any heading, for legacy files). */
38
+ export declare function parseTopicBullets(content: string): ArchivedBullet[];
39
+ /** Names the bullets keep coming back to: backticked identifiers and CamelCase words. ALLCAPS is emphasis, not a name. */
40
+ export declare function mostMentioned(bullets: ArchivedBullet[], limit?: number): string[];
41
+ export declare function digestTopic(slug: string, file: string, bullets: ArchivedBullet[]): TopicDigest;
42
+ /** The paragraph that can always be written, no model required. */
43
+ export declare function structuralNow(d: TopicDigest): string;
44
+ /** A prose paragraph over the newest bullets, when a model is configured; "" otherwise. */
45
+ export declare function proseNow(d: TopicDigest, bullets: ArchivedBullet[], signal?: AbortSignal): Promise<string>;
46
+ /** Insert or replace a marked block. Topic files: before the first section; summary: at the end. */
47
+ export declare function upsertBlock(content: string, start: string, end: string, rendered: string, where: "top" | "bottom"): string;
48
+ /** The stamp inside an existing block, so unchanged files are not rewritten. */
49
+ export declare function blockStamp(content: string, start: string): string | null;
50
+ export interface SummarizeOptions {
51
+ /** Ask a configured model for prose; falls back to structural when none answers. */
52
+ llm?: boolean;
53
+ /** Re-summarize even when the file has not changed since the last block. */
54
+ force?: boolean;
55
+ now?: () => Date;
56
+ }
57
+ export interface TopicResult {
58
+ slug: string;
59
+ file: string;
60
+ bullets: number;
61
+ updated: boolean;
62
+ split?: string;
63
+ now: string;
64
+ }
65
+ /**
66
+ * Move whole "## Archived <date>" sections, oldest first, into <topic>.older.md
67
+ * until the file is under the cap. Returns the older file's path if anything moved.
68
+ */
69
+ export declare function splitTopicFile(filePath: string, maxBullets?: number): string | null;
70
+ export declare function summarizeTopicFile(filePath: string, slug: string, opts?: SummarizeOptions): Promise<TopicResult>;
71
+ export interface ProjectSummary {
72
+ project: string;
73
+ topics: TopicResult[];
74
+ summaryPath: string | null;
75
+ summaryUpdated: boolean;
76
+ }
77
+ /** Summarize every topic file of a project and refresh the "What phren knows" block in summary.md. */
78
+ export declare function summarizeProject(phrenPath: string, project: string, opts?: SummarizeOptions): Promise<ProjectSummary>;
79
+ /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
80
+ export declare function readKnowsBlock(phrenPath: string, project: string): {
81
+ path: string;
82
+ text: string;
83
+ } | null;
@@ -0,0 +1,298 @@
1
+ /**
2
+ * Give the archive a shape.
3
+ *
4
+ * Findings age out of FINDINGS.md into reference/topics/<topic>.md, append-only,
5
+ * grouped under "## Archived <date>" headings. A store a year old carries
6
+ * hundreds of thousands of words there, reachable only by keyword: search finds
7
+ * bullet 312, and nothing says what the topic amounts to. This writes a "## Now"
8
+ * block at the top of each topic file — structural by default (counts, tags,
9
+ * what is mentioned most, the newest headlines), a prose paragraph when an LLM
10
+ * is configured — and a "What phren knows" block at the end of summary.md that
11
+ * the prompt hook injects once per session for the project at hand. Both live
12
+ * between markers, so re-running replaces rather than accumulates. Nothing in
13
+ * the archive itself is rewritten; a topic file past a size cap is split, oldest
14
+ * sections first, into <topic>.older.md.
15
+ */
16
+ import * as fs from "fs";
17
+ import * as path from "path";
18
+ import { callLlm } from "./dedup.js";
19
+ import { readProjectTopics, topicReferencePath } from "../project-topics.js";
20
+ import { storeAwareProjectPath } from "../store-routing.js";
21
+ import { atomicWriteText, debugLog } from "../phren-paths.js";
22
+ import { errorMessage } from "../utils.js";
23
+ export const NOW_START = "<!-- phren:now:start -->";
24
+ export const NOW_END = "<!-- phren:now:end -->";
25
+ export const KNOWS_START = "<!-- phren:knows:start -->";
26
+ export const KNOWS_END = "<!-- phren:knows:end -->";
27
+ /** Bullets a topic file may hold before the oldest sections move to <topic>.older.md. */
28
+ export const TOPIC_SPLIT_AT = 400;
29
+ /** Every "- " bullet under an "## Archived <date>" heading (or before any heading, for legacy files). */
30
+ export function parseTopicBullets(content) {
31
+ const out = [];
32
+ let date = "";
33
+ let inNow = false;
34
+ for (const raw of content.split("\n")) {
35
+ if (raw.startsWith(NOW_START)) {
36
+ inNow = true;
37
+ continue;
38
+ }
39
+ if (raw.startsWith(NOW_END)) {
40
+ inNow = false;
41
+ continue;
42
+ }
43
+ if (inNow)
44
+ continue;
45
+ const heading = /^## Archived (\d{4}-\d{2}-\d{2})/.exec(raw);
46
+ if (heading) {
47
+ date = heading[1];
48
+ continue;
49
+ }
50
+ if (raw.startsWith("## ")) {
51
+ continue;
52
+ }
53
+ if (!raw.startsWith("- "))
54
+ continue;
55
+ const body = raw.slice(2).replace(/<!--.*?-->/g, "").trim();
56
+ const tagMatch = /^\[([a-z][a-z-]*)(?::[^\]]*)?\]\s*/.exec(body);
57
+ out.push({ date, tag: tagMatch ? tagMatch[1] : "untagged", text: tagMatch ? body.slice(tagMatch[0].length) : body });
58
+ }
59
+ return out;
60
+ }
61
+ const STOP = new Set(["The", "This", "That", "When", "Then", "There", "These", "Those", "With", "Without", "After", "Before", "Also", "Note", "Never", "Always", "Every", "Each", "Only", "Both", "Some", "Most", "Many", "Much", "More", "Less", "Use", "Used", "Using", "Run", "Runs", "Make", "Made", "Keep", "Kept", "Set", "Sets", "Got", "Get", "Gets", "Does", "Did", "Not", "For", "And", "But", "Any", "All", "Its", "Our", "Your", "Their", "One", "Two", "Three", "First", "Last", "New", "Old", "Fix", "Fixed", "Add", "Added", "Remove", "Removed", "Check", "Rails", "Node", "React", "Python", "TypeScript", "JSON", "YAML", "HTML", "CSS", "API", "URL", "ID", "OK", "TODO", "NOTE", "DO", "NOT"]);
62
+ /** Names the bullets keep coming back to: backticked identifiers and CamelCase words. ALLCAPS is emphasis, not a name. */
63
+ export function mostMentioned(bullets, limit = 6) {
64
+ const counts = new Map();
65
+ for (const b of bullets) {
66
+ const seen = new Set();
67
+ for (const m of b.text.matchAll(/`([A-Za-z_][\w./-]{2,40})`|\b([A-Z][a-z]+(?:[A-Z][a-z0-9]+)+)\b/g)) {
68
+ const term = (m[1] ?? m[2] ?? "").trim();
69
+ if (/^[A-Z0-9_]+$/.test(term))
70
+ continue;
71
+ if (!term || STOP.has(term) || seen.has(term))
72
+ continue;
73
+ seen.add(term);
74
+ counts.set(term, (counts.get(term) ?? 0) + 1);
75
+ }
76
+ }
77
+ return [...counts.entries()].filter(([, n]) => n >= 2).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, limit).map(([t]) => t);
78
+ }
79
+ function headline(text, max = 100) {
80
+ const flat = text.replace(/\s+/g, " ").trim();
81
+ const cut = flat.search(/[.;:](\s|$)/);
82
+ const s = cut > 30 && cut < max ? flat.slice(0, cut) : flat;
83
+ return s.length > max ? `${s.slice(0, max - 1)}…` : s;
84
+ }
85
+ export function digestTopic(slug, file, bullets) {
86
+ const tags = {};
87
+ for (const b of bullets)
88
+ tags[b.tag] = (tags[b.tag] ?? 0) + 1;
89
+ const dates = bullets.map((b) => b.date).filter(Boolean).sort();
90
+ const newest = [...bullets].reverse().filter((b) => b.date).slice(0, 5);
91
+ return {
92
+ slug,
93
+ file,
94
+ bullets: bullets.length,
95
+ tags,
96
+ first: dates[0] ?? "",
97
+ last: dates[dates.length - 1] ?? "",
98
+ mentioned: mostMentioned(bullets),
99
+ headlines: newest.map((b) => headline(b.text)),
100
+ };
101
+ }
102
+ function plural(n, word) {
103
+ if (word === "context")
104
+ return `${n} context note${n === 1 ? "" : "s"}`;
105
+ return `${n} ${word}${n === 1 ? "" : "s"}`;
106
+ }
107
+ /** The paragraph that can always be written, no model required. */
108
+ export function structuralNow(d) {
109
+ if (!d.bullets)
110
+ return "Nothing archived under this topic yet.";
111
+ const span = d.first && d.last ? (d.first === d.last ? `archived on ${d.first}` : `archived between ${d.first} and ${d.last}`) : "";
112
+ const tagLine = Object.entries(d.tags).filter(([t]) => t !== "untagged").sort((a, b) => b[1] - a[1]).slice(0, 4).map(([t, n]) => plural(n, t)).join(", ");
113
+ const parts = [`${plural(d.bullets, "finding")}${span ? `, ${span}` : ""}${tagLine ? `: ${tagLine}` : ""}.`];
114
+ if (d.mentioned.length)
115
+ parts.push(`Keeps coming back to ${d.mentioned.join(", ")}.`);
116
+ if (d.headlines.length)
117
+ parts.push(`Newest: ${d.headlines.map((h, i) => `(${i + 1}) ${h}`).join(" ")}`);
118
+ return parts.join(" ");
119
+ }
120
+ /** A prose paragraph over the newest bullets, when a model is configured; "" otherwise. */
121
+ export async function proseNow(d, bullets, signal) {
122
+ const newest = [...bullets].reverse().slice(0, 60).map((b) => `- [${b.tag}] ${b.text}`).join("\n");
123
+ const prompt = `These are archived engineering findings for the topic "${d.slug}" of one software project, newest first. Write one paragraph of 4 to 6 plain sentences stating what is currently known: the standing decisions, the pitfalls that still apply, and the patterns in use. Be concrete, name the components involved, no preamble, no bullet points.\n\n${newest}`;
124
+ try {
125
+ const text = (await callLlm(prompt, signal, 320)).trim();
126
+ return text.length > 40 ? text : "";
127
+ }
128
+ catch (err) {
129
+ debugLog(`summarize: llm failed: ${errorMessage(err)}`);
130
+ return "";
131
+ }
132
+ }
133
+ function block(start, end, heading, body, stamp) {
134
+ return `${start.replace("-->", `at=${stamp} -->`)}\n${heading}\n\n${body}\n${end}`;
135
+ }
136
+ /** Insert or replace a marked block. Topic files: before the first section; summary: at the end. */
137
+ export function upsertBlock(content, start, end, rendered, where) {
138
+ const startRe = new RegExp(`${start.replace("-->", "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\\n]*-->`);
139
+ const s = content.search(startRe);
140
+ const e = content.indexOf(end);
141
+ if (s !== -1 && e !== -1 && e > s) {
142
+ return `${content.slice(0, s)}${rendered}${content.slice(e + end.length)}`;
143
+ }
144
+ if (where === "top") {
145
+ const firstSection = content.search(/^## /m);
146
+ if (firstSection === -1)
147
+ return `${content.trimEnd()}\n\n${rendered}\n`;
148
+ return `${content.slice(0, firstSection).trimEnd()}\n\n${rendered}\n\n${content.slice(firstSection)}`;
149
+ }
150
+ return `${content.trimEnd()}\n\n${rendered}\n`;
151
+ }
152
+ /** The stamp inside an existing block, so unchanged files are not rewritten. */
153
+ export function blockStamp(content, start) {
154
+ const m = new RegExp(`${start.replace("-->", "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}at=([^ ]+) -->`).exec(content);
155
+ return m ? m[1] : null;
156
+ }
157
+ /**
158
+ * Move whole "## Archived <date>" sections, oldest first, into <topic>.older.md
159
+ * until the file is under the cap. Returns the older file's path if anything moved.
160
+ */
161
+ export function splitTopicFile(filePath, maxBullets = TOPIC_SPLIT_AT) {
162
+ const content = fs.readFileSync(filePath, "utf8");
163
+ if (parseTopicBullets(content).length <= maxBullets)
164
+ return null;
165
+ const lines = content.split("\n");
166
+ // Section boundaries: every "## Archived <date>" line, in file order (which is oldest first).
167
+ const starts = [];
168
+ for (let i = 0; i < lines.length; i++)
169
+ if (/^## Archived \d{4}-\d{2}-\d{2}/.test(lines[i]))
170
+ starts.push(i);
171
+ if (starts.length < 2)
172
+ return null;
173
+ const sections = starts.map((s, i) => lines.slice(s, i + 1 < starts.length ? starts[i + 1] : lines.length));
174
+ const head = lines.slice(0, starts[0]);
175
+ let keep = sections.slice();
176
+ const moved = [];
177
+ const count = (secs) => secs.reduce((n, sec) => n + sec.filter((l) => l.startsWith("- ")).length, 0);
178
+ while (keep.length > 1 && count(keep) > maxBullets)
179
+ moved.push(keep.shift());
180
+ if (!moved.length)
181
+ return null;
182
+ const olderPath = filePath.replace(/\.md$/, ".older.md");
183
+ const title = head.find((l) => l.startsWith("# ")) ?? "# archive";
184
+ const prior = fs.existsSync(olderPath) ? fs.readFileSync(olderPath, "utf8").trimEnd() + "\n\n" : `${title} (older archive)\n\nSections moved here from ${path.basename(filePath)} once it passed ${maxBullets} bullets. Still indexed; still searchable.\n\n`;
185
+ atomicWriteText(olderPath, prior + moved.map((sec) => sec.join("\n").trimEnd()).join("\n\n") + "\n");
186
+ atomicWriteText(filePath, [...head, ...keep.flat()].join("\n").trimEnd() + "\n");
187
+ return olderPath;
188
+ }
189
+ export async function summarizeTopicFile(filePath, slug, opts = {}) {
190
+ const split = splitTopicFile(filePath);
191
+ const content = fs.readFileSync(filePath, "utf8");
192
+ const stat = fs.statSync(filePath);
193
+ const stamp = (opts.now ?? (() => new Date()))().toISOString();
194
+ const prev = blockStamp(content, NOW_START);
195
+ const bullets = parseTopicBullets(content);
196
+ const digest = digestTopic(slug, filePath, bullets);
197
+ // The block records when it was written; a file untouched since then is left alone.
198
+ if (!opts.force && prev && !split && new Date(prev).getTime() >= stat.mtimeMs - 1000) {
199
+ const existing = content.slice(content.indexOf(NOW_START.replace("-->", "")), content.indexOf(NOW_END));
200
+ return { slug, file: filePath, bullets: bullets.length, updated: false, now: existing.split("\n").slice(2).join("\n").trim() };
201
+ }
202
+ let now = "";
203
+ if (opts.llm)
204
+ now = await proseNow(digest, bullets, AbortSignal.timeout(25_000));
205
+ if (!now)
206
+ now = structuralNow(digest);
207
+ const next = upsertBlock(content, NOW_START, NOW_END, block(NOW_START, NOW_END, "## Now", now, stamp), "top");
208
+ if (next !== content)
209
+ atomicWriteText(filePath, next);
210
+ return { slug, file: filePath, bullets: bullets.length, updated: next !== content, split: split ?? undefined, now };
211
+ }
212
+ function countActiveFindingsIn(findingsPath) {
213
+ try {
214
+ let inArchive = false;
215
+ let n = 0;
216
+ for (const line of fs.readFileSync(findingsPath, "utf8").split("\n")) {
217
+ if (/<!--\s*phren:archive:start/.test(line) || line.startsWith("<details"))
218
+ inArchive = true;
219
+ if (/<!--\s*phren:archive:end/.test(line) || line.startsWith("</details"))
220
+ inArchive = false;
221
+ if (!inArchive && line.startsWith("- "))
222
+ n++;
223
+ }
224
+ return n;
225
+ }
226
+ catch {
227
+ return 0;
228
+ }
229
+ }
230
+ function countOpenTasks(tasksPath) {
231
+ try {
232
+ return fs.readFileSync(tasksPath, "utf8").split("\n").filter((l) => /^- \[ \]/.test(l)).length;
233
+ }
234
+ catch {
235
+ return 0;
236
+ }
237
+ }
238
+ /** Summarize every topic file of a project and refresh the "What phren knows" block in summary.md. */
239
+ export async function summarizeProject(phrenPath, project, opts = {}) {
240
+ const topics = readProjectTopics(phrenPath, project).topics;
241
+ const results = [];
242
+ const seen = new Set();
243
+ for (const topic of topics) {
244
+ const file = topicReferencePath(phrenPath, project, topic.slug);
245
+ if (!file || seen.has(file) || !fs.existsSync(file))
246
+ continue;
247
+ seen.add(file);
248
+ results.push(await summarizeTopicFile(file, topic.slug, opts));
249
+ }
250
+ // Topic files that exist but are not in the configured topic list still count.
251
+ const topicsDir = storeAwareProjectPath(phrenPath, project, "reference", "topics");
252
+ if (topicsDir && fs.existsSync(topicsDir)) {
253
+ for (const entry of fs.readdirSync(topicsDir)) {
254
+ if (!entry.endsWith(".md") || entry.endsWith(".older.md"))
255
+ continue;
256
+ const file = path.join(topicsDir, entry);
257
+ if (seen.has(file))
258
+ continue;
259
+ seen.add(file);
260
+ results.push(await summarizeTopicFile(file, entry.replace(/\.md$/, ""), opts));
261
+ }
262
+ }
263
+ const summaryPath = storeAwareProjectPath(phrenPath, project, "summary.md");
264
+ if (!summaryPath)
265
+ return { project, topics: results, summaryPath: null, summaryUpdated: false };
266
+ const findingsPath = storeAwareProjectPath(phrenPath, project, "FINDINGS.md");
267
+ const tasksPath = storeAwareProjectPath(phrenPath, project, "tasks.md");
268
+ const active = findingsPath ? countActiveFindingsIn(findingsPath) : 0;
269
+ const archived = results.reduce((n, r) => n + r.bullets, 0);
270
+ const open = tasksPath ? countOpenTasks(tasksPath) : 0;
271
+ const lines = [`- ${plural(active, "active finding")}, ${archived} archived across ${plural(results.filter((r) => r.bullets > 0).length, "topic")}, ${plural(open, "open task")}.`];
272
+ for (const r of results.filter((r) => r.bullets > 0).sort((a, b) => b.bullets - a.bullets)) {
273
+ const first = r.now.split(/(?<=\.)\s/)[0] ?? r.now;
274
+ lines.push(`- **${r.slug}** — ${first}`);
275
+ }
276
+ const stamp = (opts.now ?? (() => new Date()))().toISOString();
277
+ const rendered = block(KNOWS_START, KNOWS_END, "## What phren knows", lines.join("\n"), stamp);
278
+ const existing = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, "utf8") : `# ${project}\n`;
279
+ const next = upsertBlock(existing, KNOWS_START, KNOWS_END, rendered, "bottom");
280
+ const stripStamp = (s) => s.replace(/ at=[^ ]+ -->/g, " -->");
281
+ const changed = stripStamp(next) !== stripStamp(existing);
282
+ if (changed)
283
+ atomicWriteText(summaryPath, next);
284
+ return { project, topics: results, summaryPath, summaryUpdated: changed };
285
+ }
286
+ /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
287
+ export function readKnowsBlock(phrenPath, project) {
288
+ const summaryPath = storeAwareProjectPath(phrenPath, project, "summary.md");
289
+ if (!summaryPath || !fs.existsSync(summaryPath))
290
+ return null;
291
+ const content = fs.readFileSync(summaryPath, "utf8");
292
+ const s = content.indexOf(KNOWS_START.replace("-->", ""));
293
+ const e = content.indexOf(KNOWS_END);
294
+ if (s === -1 || e === -1)
295
+ return null;
296
+ const inner = content.slice(s, e).split("\n").slice(1).join("\n").trim();
297
+ return inner ? { path: summaryPath, text: inner } : null;
298
+ }
@@ -101,8 +101,12 @@ export const DEFAULT_WORKFLOW_POLICY = {
101
101
  /** Default index policy. Exported so {@link config/schema} can render one source of truth. */
102
102
  export const DEFAULT_INDEX_POLICY = {
103
103
  schemaVersion: GOVERNANCE_SCHEMA_VERSION,
104
- includeGlobs: ["**/*.md", "**/skills/**/*.md", ".claude/skills/**/*.md"],
105
- excludeGlobs: ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/build/**"],
104
+ // Skills are instructions you invoke by name, not knowledge to retrieve:
105
+ // indexed, they crowd the findings out of a prompt's context budget (nine of
106
+ // twelve injections in one session were skill files). They stay reachable
107
+ // through list_skills and the global CLAUDE.md.
108
+ includeGlobs: ["**/*.md"],
109
+ excludeGlobs: ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/build/**", "**/skills/**", "**/.claude/skills/**"],
106
110
  includeHidden: false,
107
111
  };
108
112
  const DEFAULT_RUNTIME_HEALTH = {