@phren/cli 0.1.42 → 0.1.45

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 (97) hide show
  1. package/dist/capabilities/cli.js +1 -1
  2. package/dist/capabilities/mcp.js +1 -1
  3. package/dist/capabilities/vscode.js +3 -3
  4. package/dist/capabilities/web-ui.js +29 -29
  5. package/dist/cli/actions.d.ts +1 -1
  6. package/dist/cli/actions.js +7 -2
  7. package/dist/cli/config-proactivity.d.ts +6 -6
  8. package/dist/cli/hooks-output.js +15 -6
  9. package/dist/cli/hooks.d.ts +1 -1
  10. package/dist/cli/hooks.js +16 -5
  11. package/dist/cli/session-stop.d.ts +1 -1
  12. package/dist/cli/session-tool-hook.d.ts +1 -1
  13. package/dist/cli-registry.js +1 -1
  14. package/dist/data/access.js +2 -1
  15. package/dist/generated/memory-ui-graph.browser.js +481 -318
  16. package/dist/governance/locks.js +6 -0
  17. package/dist/governance/scores.d.ts +9 -1
  18. package/dist/governance/scores.js +12 -1
  19. package/dist/graph-core/index.d.ts +2 -0
  20. package/dist/graph-core/index.js +2 -0
  21. package/dist/graph-core/model.d.ts +84 -0
  22. package/dist/graph-core/model.js +355 -0
  23. package/dist/graph-core/types.d.ts +110 -0
  24. package/dist/graph-core/types.js +43 -0
  25. package/dist/index.js +4 -1
  26. package/dist/init/init-uninstall.d.ts +1 -0
  27. package/dist/init/init-uninstall.js +13 -3
  28. package/dist/init/setup.js +11 -4
  29. package/dist/link/context.js +2 -1
  30. package/dist/link/link.js +3 -2
  31. package/dist/link/skills.js +2 -1
  32. package/dist/memory-ui-graph.runtime.js +481 -318
  33. package/dist/phren-core.d.ts +16 -0
  34. package/dist/phren-core.js +21 -0
  35. package/dist/phren-paths.js +8 -4
  36. package/dist/profile-store.d.ts +2 -0
  37. package/dist/profile-store.js +16 -19
  38. package/dist/project-config.js +2 -1
  39. package/dist/shared/fragment-graph.js +7 -2
  40. package/dist/shared/index.js +1 -1
  41. package/dist/shared/retrieval.d.ts +38 -0
  42. package/dist/shared/retrieval.js +62 -4
  43. package/dist/shell/entry.d.ts +10 -2
  44. package/dist/shell/entry.js +128 -97
  45. package/dist/shell/graph/canvas.d.ts +64 -0
  46. package/dist/shell/graph/canvas.js +256 -0
  47. package/dist/shell/graph/controller.d.ts +164 -0
  48. package/dist/shell/graph/controller.js +645 -0
  49. package/dist/shell/graph/glyphs.d.ts +12 -0
  50. package/dist/shell/graph/glyphs.js +31 -0
  51. package/dist/shell/graph/graph-view.d.ts +12 -0
  52. package/dist/shell/graph/graph-view.js +408 -0
  53. package/dist/shell/graph/layout.d.ts +68 -0
  54. package/dist/shell/graph/layout.js +267 -0
  55. package/dist/shell/input.d.ts +4 -1
  56. package/dist/shell/input.js +28 -5
  57. package/dist/shell/intro.d.ts +37 -0
  58. package/dist/shell/intro.js +82 -0
  59. package/dist/shell/keys.d.ts +36 -0
  60. package/dist/shell/keys.js +107 -0
  61. package/dist/shell/logo-fx.d.ts +35 -0
  62. package/dist/shell/logo-fx.js +128 -0
  63. package/dist/shell/render.d.ts +34 -1
  64. package/dist/shell/render.js +220 -66
  65. package/dist/shell/shell.d.ts +13 -1
  66. package/dist/shell/shell.js +61 -10
  67. package/dist/shell/startup.d.ts +37 -0
  68. package/dist/shell/startup.js +105 -0
  69. package/dist/shell/state-store.d.ts +1 -1
  70. package/dist/shell/state-store.js +1 -1
  71. package/dist/shell/types.js +1 -0
  72. package/dist/shell/view.d.ts +3 -0
  73. package/dist/shell/view.js +26 -4
  74. package/dist/store-registry.d.ts +13 -0
  75. package/dist/store-registry.js +109 -37
  76. package/dist/test-global-setup.d.ts +1 -0
  77. package/dist/test-global-setup.js +22 -0
  78. package/dist/tool-registry.js +1 -0
  79. package/dist/tools/memory.js +12 -5
  80. package/dist/tools/ops.js +1 -1
  81. package/dist/ui/data.d.ts +15 -7
  82. package/dist/ui/data.js +102 -3
  83. package/dist/utils-fts.js +2 -1
  84. package/dist/utils-helpers.d.ts +1 -0
  85. package/dist/utils-helpers.js +6 -0
  86. package/dist/utils.d.ts +1 -1
  87. package/dist/utils.js +1 -1
  88. package/package.json +38 -7
  89. package/starter/global/skills/phren-consolidate/SKILL.md +152 -0
  90. package/starter/global/skills/phren-discover/SKILL.md +175 -0
  91. package/starter/global/skills/phren-init/SKILL.md +216 -0
  92. package/starter/global/skills/phren-profiles/SKILL.md +121 -0
  93. package/starter/global/skills/phren-sync/SKILL.md +261 -0
  94. package/dist/init-uninstall.d.ts +0 -3
  95. package/dist/init-uninstall.js +0 -514
  96. package/dist/init-walkthrough.d.ts +0 -55
  97. package/dist/init-walkthrough.js +0 -524
@@ -48,6 +48,22 @@ export declare function phrenErr<T>(error: string, code?: PhrenErrorCode): Phren
48
48
  export declare function forwardErr<T>(result: PhrenResult<unknown>): PhrenResult<T>;
49
49
  export declare function parsePhrenErrorCode(msg: string): PhrenErrorCode | undefined;
50
50
  export declare function isRecord(value: unknown): value is Record<string, unknown>;
51
+ /**
52
+ * `yaml.load` with js-yaml 4's empty-document behaviour.
53
+ *
54
+ * js-yaml 5 throws YAMLException("expected a document, but the input is empty")
55
+ * for input that is blank, whitespace, or comments only — where 4 returned
56
+ * `undefined`. phren's config files legitimately look like that: a freshly
57
+ * scaffolded `machines.yaml` is a single header comment, and an untouched
58
+ * profile can be empty. Every caller already handles `undefined`, but a throw
59
+ * is read as a parse failure, which would report those files as malformed —
60
+ * and `stores.yaml` refuses to write back over a file it could not parse, so
61
+ * an empty registry would have become unrepairable by the CLI.
62
+ *
63
+ * Only genuinely empty documents are absorbed. `---`, `null` and real syntax
64
+ * errors reach js-yaml exactly as before.
65
+ */
66
+ export declare function loadYamlDocument<T = unknown>(source: string, load: (source: string) => unknown): T | undefined;
51
67
  /** Shallow-merge data onto defaults so missing keys get filled in. */
52
68
  export declare function withDefaults<T extends object>(data: Partial<T>, defaults: T): T;
53
69
  /**
@@ -70,6 +70,27 @@ export function parsePhrenErrorCode(msg) {
70
70
  export function isRecord(value) {
71
71
  return typeof value === "object" && value !== null && !Array.isArray(value);
72
72
  }
73
+ /**
74
+ * `yaml.load` with js-yaml 4's empty-document behaviour.
75
+ *
76
+ * js-yaml 5 throws YAMLException("expected a document, but the input is empty")
77
+ * for input that is blank, whitespace, or comments only — where 4 returned
78
+ * `undefined`. phren's config files legitimately look like that: a freshly
79
+ * scaffolded `machines.yaml` is a single header comment, and an untouched
80
+ * profile can be empty. Every caller already handles `undefined`, but a throw
81
+ * is read as a parse failure, which would report those files as malformed —
82
+ * and `stores.yaml` refuses to write back over a file it could not parse, so
83
+ * an empty registry would have become unrepairable by the CLI.
84
+ *
85
+ * Only genuinely empty documents are absorbed. `---`, `null` and real syntax
86
+ * errors reach js-yaml exactly as before.
87
+ */
88
+ export function loadYamlDocument(source, load) {
89
+ // Strip blank and comment-only lines; anything left is a document to parse.
90
+ if (!source.replace(/^\s*(#.*)?$/gm, "").trim())
91
+ return undefined;
92
+ return load(source);
93
+ }
73
94
  /** Shallow-merge data onto defaults so missing keys get filled in. */
74
95
  export function withDefaults(data, defaults) {
75
96
  const merged = { ...defaults };
@@ -4,7 +4,7 @@ import * as path from "path";
4
4
  import * as crypto from "crypto";
5
5
  import * as yaml from "js-yaml";
6
6
  import { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
7
- import { PhrenError, isRecord, RESERVED_PROJECT_DIR_NAMES } from "./phren-core.js";
7
+ import { PhrenError, isRecord, loadYamlDocument, RESERVED_PROJECT_DIR_NAMES } from "./phren-core.js";
8
8
  import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
9
9
  import { FINDINGS_FILENAME } from "./data/access.js";
10
10
  bootstrapPhrenDotEnv();
@@ -128,7 +128,7 @@ export function readRootManifest(phrenPath) {
128
128
  if (!fs.existsSync(manifestFile))
129
129
  return null;
130
130
  try {
131
- const parsed = yaml.load(fs.readFileSync(manifestFile, "utf8"), { schema: yaml.CORE_SCHEMA });
131
+ const parsed = loadYamlDocument(fs.readFileSync(manifestFile, "utf8"), (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
132
132
  return normalizeManifest(parsed);
133
133
  }
134
134
  catch (err) {
@@ -176,7 +176,11 @@ export function findNearestPhrenPath(startDir = process.cwd()) {
176
176
  let current = path.resolve(startDir);
177
177
  while (true) {
178
178
  const localCandidate = path.join(current, ".phren");
179
- if (isPhrenRootCandidate(localCandidate))
179
+ // Only a manifest counts on the cwd walk. Loose install markers are
180
+ // enough for the user's own ~/.phren or an explicit PHREN_PATH, but a
181
+ // cloned repo could ship `.phren/global/` and become the store — with
182
+ // its `.env` loaded — just by being cd'd into.
183
+ if (hasRootManifest(localCandidate))
180
184
  return localCandidate;
181
185
  const parent = path.dirname(current);
182
186
  if (parent === current)
@@ -578,7 +582,7 @@ export function getProjectDirs(phrenPath, profile) {
578
582
  return [];
579
583
  }
580
584
  try {
581
- const data = yaml.load(fs.readFileSync(profilePath, "utf-8"), { schema: yaml.CORE_SCHEMA });
585
+ const data = loadYamlDocument(fs.readFileSync(profilePath, "utf-8"), (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
582
586
  const projects = isRecord(data) ? data.projects : undefined;
583
587
  if (!Array.isArray(projects)) {
584
588
  errorLog("getProjectDirs", `${PhrenError.MALFORMED_YAML}: Profile YAML missing valid "projects" array: ${profilePath}`);
@@ -23,6 +23,8 @@ export interface ProjectCard {
23
23
  name: string;
24
24
  summary: string;
25
25
  docs: string[];
26
+ /** Name of the non-primary store this project lives in, if any. */
27
+ store?: string;
26
28
  }
27
29
  export declare function resolveActiveProfile(phrenPath: string, requestedProfile?: string): PhrenResult<string | undefined>;
28
30
  export declare function getDefaultMachineAlias(): string;
@@ -2,6 +2,7 @@ import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import * as crypto from "crypto";
4
4
  import * as yaml from "js-yaml";
5
+ import { loadYamlDocument } from "./phren-core.js";
5
6
  import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, readRootManifest, } from "./shared.js";
6
7
  import { defaultMachineName, getMachineName } from "./machine-identity.js";
7
8
  import { errorMessage, isValidProjectName } from "./utils.js";
@@ -54,7 +55,7 @@ export function listMachines(phrenPath) {
54
55
  return phrenErr(`machines.yaml not found. Run 'phren init' to set up your phren.`, PhrenError.FILE_NOT_FOUND);
55
56
  try {
56
57
  const raw = fs.readFileSync(machinesPath, "utf8");
57
- const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
58
+ const parsed = loadYamlDocument(raw, (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
58
59
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
59
60
  return phrenErr(`machines.yaml is empty or not valid YAML. Check the file format or run 'phren doctor --fix'.`, PhrenError.MALFORMED_YAML);
60
61
  const cleaned = {};
@@ -214,7 +215,7 @@ export function listProfiles(phrenPath) {
214
215
  const full = path.join(profilesDir, file);
215
216
  try {
216
217
  const raw = fs.readFileSync(full, "utf8");
217
- const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
218
+ const parsed = loadYamlDocument(raw, (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
218
219
  const data = parsed && typeof parsed === "object" && !Array.isArray(parsed)
219
220
  ? parsed
220
221
  : null;
@@ -306,22 +307,14 @@ function buildProjectCard(dir) {
306
307
  return { name, summary, docs };
307
308
  }
308
309
  export function listProjectCards(phrenPath, profile) {
309
- const dirs = getProjectDirs(phrenPath, profile).sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
310
+ const dirs = getProjectDirs(phrenPath, profile);
310
311
  const cards = dirs.map(buildProjectCard);
311
312
  const seen = new Set(dirs.map((d) => path.basename(d)));
312
- // Include projects from team stores, filtered by active profile
313
+ // Team stores carry their own subscription list (StoreEntry.projects, applied
314
+ // by getStoreProjectDirs). The profile's project list scopes the *primary*
315
+ // store, so filtering team projects through it hid every one of them — a
316
+ // profile never names projects that live in someone else's store.
313
317
  try {
314
- // Resolve the profile's project allow-list (if any)
315
- let profileProjectNames;
316
- if (profile) {
317
- const profiles = listProfiles(phrenPath);
318
- if (profiles.ok) {
319
- const active = profiles.data.find((p) => p.name === profile);
320
- if (active && active.projects.length > 0) {
321
- profileProjectNames = new Set(active.projects);
322
- }
323
- }
324
- }
325
318
  for (const store of getNonPrimaryStores(phrenPath)) {
326
319
  if (!fs.existsSync(store.path))
327
320
  continue;
@@ -329,19 +322,23 @@ export function listProjectCards(phrenPath, profile) {
329
322
  const name = path.basename(dir);
330
323
  if (seen.has(name) || name === "global")
331
324
  continue;
332
- if (profileProjectNames && !profileProjectNames.has(name))
333
- continue;
334
325
  seen.add(name);
335
- cards.push(buildProjectCard(dir));
326
+ cards.push({ ...buildProjectCard(dir), store: store.name });
336
327
  }
337
328
  }
338
329
  }
339
330
  catch {
340
331
  // store-registry not available or error loading, continue with primary only
341
332
  }
342
- // Prepend global as a pinned entry so it's always accessible from the shell
333
+ cards.sort((a, b) => a.name.localeCompare(b.name));
334
+ // Prepend global as a pinned entry so it's always accessible from the shell.
335
+ // getProjectDirs already returns it whenever the profile names it, so drop
336
+ // that copy rather than listing global twice.
343
337
  const globalDir = path.join(phrenPath, "global");
344
338
  if (fs.existsSync(globalDir)) {
339
+ const listed = cards.findIndex((card) => card.name === "global");
340
+ if (listed >= 0)
341
+ cards.splice(listed, 1);
345
342
  cards.unshift(buildProjectCard(globalDir));
346
343
  }
347
344
  return cards;
@@ -2,6 +2,7 @@ import * as crypto from "crypto";
2
2
  import * as fs from "fs";
3
3
  import * as path from "path";
4
4
  import * as yaml from "js-yaml";
5
+ import { loadYamlDocument } from "./phren-core.js";
5
6
  import { readInstallPreferences } from "./init/preferences.js";
6
7
  import { debugLog } from "./shared.js";
7
8
  import { errorMessage } from "./utils.js";
@@ -63,7 +64,7 @@ export function readProjectConfig(phrenPath, project) {
63
64
  return cached.config;
64
65
  }
65
66
  try {
66
- const parsed = yaml.load(fs.readFileSync(configPath, "utf8"), { schema: yaml.CORE_SCHEMA });
67
+ const parsed = loadYamlDocument(fs.readFileSync(configPath, "utf8"), (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA }));
67
68
  const config = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
68
69
  _projectConfigCache.set(configPath, { mtimeMs, config });
69
70
  return config;
@@ -1,5 +1,6 @@
1
1
  import { decodeStringRow } from "./index.js";
2
2
  import * as fs from "fs";
3
+ import * as path from "path";
3
4
  import { runtimeFile } from "../shared.js";
4
5
  import { logger } from "../logger.js";
5
6
  import { UNIVERSAL_TECH_TERMS_RE } from "../phren-core.js";
@@ -181,8 +182,12 @@ function readUserDefinedFragmentsFromDisk(claudeMdPath) {
181
182
  export function beginUserFragmentBuildCache(phrenPath, projects) {
182
183
  _activeBuildCacheKeyPrefix = `${phrenPath}/`;
183
184
  for (const project of projects) {
185
+ // The cache key stays a slash-joined string — it is only ever compared
186
+ // against other keys built the same way. The file path is a real path, so
187
+ // it goes through path.join: concatenating with "/" reads fine on Windows
188
+ // but produces a mixed-separator string that no other code path matches.
184
189
  const cacheKey = `${phrenPath}/${project}`;
185
- const claudeMdPath = `${phrenPath}/${project}/CLAUDE.md`;
190
+ const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
186
191
  try {
187
192
  const loaded = readUserDefinedFragmentsFromDisk(claudeMdPath);
188
193
  if (!loaded) {
@@ -209,7 +214,7 @@ export function endUserFragmentBuildCache(phrenPath) {
209
214
  _activeBuildCacheKeyPrefix = null;
210
215
  }
211
216
  function parseUserDefinedFragments(phrenPath, project) {
212
- const claudeMdPath = `${phrenPath}/${project}/CLAUDE.md`;
217
+ const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
213
218
  const cacheKey = `${phrenPath}/${project}`;
214
219
  try {
215
220
  // Active build path: no sync I/O in per-file extraction.
@@ -671,7 +671,7 @@ function endTopicBuildCache() {
671
671
  function readProjectTopicsForBuild(phrenPath, project) {
672
672
  if (!_buildTopicCacheActive)
673
673
  return readProjectTopics(phrenPath, project);
674
- const key = `${phrenPath}${project}`;
674
+ const key = `${phrenPath}\u0000${project}`;
675
675
  const hit = _buildTopicCache.get(key);
676
676
  if (hit)
677
677
  return hit;
@@ -2,6 +2,23 @@ import { type RetentionPolicy } from "./governance.js";
2
2
  import { type DocRow, type SqlJsDatabase } from "./index.js";
3
3
  import type { GitContext } from "../cli/hooks-session.js";
4
4
  export type { GitContext } from "../cli/hooks-session.js";
5
+ /**
6
+ * Per-snippet overhead charged against the token budget: the header line
7
+ * (`[<source key>] (<type>) fb:<score key>`) plus its blank separator.
8
+ *
9
+ * Selection and rendering MUST charge the same amount. When they drifted
10
+ * apart, `selectSnippets` admitted a snippet on one estimate and
11
+ * `buildHookOutput` re-checked it against a larger one, silently dropping a
12
+ * middle snippet that legitimately fit.
13
+ */
14
+ export declare const SNIPPET_OVERHEAD_TOKENS = 24;
15
+ /** Query-relevance floor (see applyRelevanceFloor). A doc with no structural
16
+ * signal must clear this query-overlap score to be worth injecting; on the
17
+ * overlapScore scale (matched / max(2, min(tokens, 10))) ~0.12 means "shares at
18
+ * least one query token" — enough to drop priors-only noise without hurting
19
+ * recall. Cross-project docs face a higher bar. Tunable via
20
+ * PHREN_MIN_QUERY_RELEVANCE (0 disables the floor). */
21
+ declare const DEFAULT_MIN_QUERY_RELEVANCE = 0.12;
5
22
  export declare function detectTaskIntent(prompt: string): "debug" | "review" | "build" | "docs" | "skill" | "general";
6
23
  export declare function fileRelevanceBoost(filePath: string, changedFiles: Set<string>): number;
7
24
  export declare function branchMatchBoost(content: string, branch: string | undefined): number;
@@ -98,6 +115,27 @@ export interface SelectedSnippet {
98
115
  /** Mark snippet lines with stale citations (cited file missing or line content changed).
99
116
  * @internal Exported for tests. */
100
117
  export declare function markStaleCitations(snippet: string): string;
118
+ export { DEFAULT_MIN_QUERY_RELEVANCE };
119
+ /**
120
+ * Relevance floor: drop ranked docs that aren't actually relevant to *this*
121
+ * prompt, so the hook injects signal or nothing — never noise to fill a quota.
122
+ *
123
+ * `rankResults` intentionally scores on priors too (intent, recency, project,
124
+ * feedback history), so a doc can rank well with zero query overlap. That's the
125
+ * right call for *ordering*, but the wrong thing to *inject*. This stage keeps a
126
+ * doc only when it has a real connection to the prompt:
127
+ * - a structural signal: it's a changed file, or matches the branch name, or
128
+ * - it's a canonical doc for the project you're actually in, or
129
+ * - its text clears a query-overlap floor (higher for cross-project docs).
130
+ *
131
+ * When there's no usable query signal (no tokens) it is a no-op. Setting the
132
+ * floor to 0 (env PHREN_MIN_QUERY_RELEVANCE=0) disables it and restores the
133
+ * previous always-fill behavior.
134
+ */
135
+ export declare function applyRelevanceFloor(rows: DocRow[], keywords: string, gitCtx: {
136
+ branch?: string;
137
+ changedFiles?: Set<string>;
138
+ } | null, detectedProject: string | null, floor?: number): DocRow[];
101
139
  export declare function selectSnippets(rows: DocRow[], keywords: string, tokenBudget: number, lineBudget: number, charBudget: number): {
102
140
  selected: SelectedSnippet[];
103
141
  usedTokens: number;
@@ -27,8 +27,26 @@ const WEAK_CROSS_PROJECT_OVERLAP_MAX = 0.18;
27
27
  const WEAK_CROSS_PROJECT_OVERLAP_PENALTY = 0.75;
28
28
  const LOW_FOCUS_SNIPPET_SCORE = 0.3;
29
29
  const VERY_LOW_FOCUS_SNIPPET_SCORE = 0.14;
30
+ /**
31
+ * Per-snippet overhead charged against the token budget: the header line
32
+ * (`[<source key>] (<type>) fb:<score key>`) plus its blank separator.
33
+ *
34
+ * Selection and rendering MUST charge the same amount. When they drifted
35
+ * apart, `selectSnippets` admitted a snippet on one estimate and
36
+ * `buildHookOutput` re-checked it against a larger one, silently dropping a
37
+ * middle snippet that legitimately fit.
38
+ */
39
+ export const SNIPPET_OVERHEAD_TOKENS = 24;
30
40
  const LOW_FOCUS_SNIPPET_LINE_CAP = 3;
31
41
  const LOW_FOCUS_SNIPPET_CHAR_FRACTION = 0.55;
42
+ /** Query-relevance floor (see applyRelevanceFloor). A doc with no structural
43
+ * signal must clear this query-overlap score to be worth injecting; on the
44
+ * overlapScore scale (matched / max(2, min(tokens, 10))) ~0.12 means "shares at
45
+ * least one query token" — enough to drop priors-only noise without hurting
46
+ * recall. Cross-project docs face a higher bar. Tunable via
47
+ * PHREN_MIN_QUERY_RELEVANCE (0 disables the floor). */
48
+ const DEFAULT_MIN_QUERY_RELEVANCE = 0.12;
49
+ const CROSS_PROJECT_MIN_QUERY_RELEVANCE = 0.25;
32
50
  const TASK_RESCUE_MIN_OVERLAP = 0.3;
33
51
  const TASK_RESCUE_OVERLAP_MARGIN = 0.12;
34
52
  const TASK_RESCUE_SCORE_MARGIN = 0.6;
@@ -555,7 +573,10 @@ export async function searchFederatedStores(localPhrenPath, options) {
555
573
  return allRows;
556
574
  }
557
575
  // ── Trust filter ─────────────────────────────────────────────────────────────
558
- const TRUST_FILTERED_TYPES = new Set(["findings", "reference", "knowledge"]);
576
+ // "knowledge" was a doc type until the 0.0.x renames; classifyFile can no
577
+ // longer produce it, so listing it here was dead weight that made the set
578
+ // read as broader than it is.
579
+ const TRUST_FILTERED_TYPES = new Set(["findings", "reference"]);
559
580
  /**
560
581
  * Doc types that must never be pushed into an agent's prompt automatically.
561
582
  *
@@ -841,6 +862,43 @@ export function markStaleCitations(snippet) {
841
862
  }
842
863
  return result.join("\n");
843
864
  }
865
+ export { DEFAULT_MIN_QUERY_RELEVANCE };
866
+ /**
867
+ * Relevance floor: drop ranked docs that aren't actually relevant to *this*
868
+ * prompt, so the hook injects signal or nothing — never noise to fill a quota.
869
+ *
870
+ * `rankResults` intentionally scores on priors too (intent, recency, project,
871
+ * feedback history), so a doc can rank well with zero query overlap. That's the
872
+ * right call for *ordering*, but the wrong thing to *inject*. This stage keeps a
873
+ * doc only when it has a real connection to the prompt:
874
+ * - a structural signal: it's a changed file, or matches the branch name, or
875
+ * - it's a canonical doc for the project you're actually in, or
876
+ * - its text clears a query-overlap floor (higher for cross-project docs).
877
+ *
878
+ * When there's no usable query signal (no tokens) it is a no-op. Setting the
879
+ * floor to 0 (env PHREN_MIN_QUERY_RELEVANCE=0) disables it and restores the
880
+ * previous always-fill behavior.
881
+ */
882
+ export function applyRelevanceFloor(rows, keywords, gitCtx, detectedProject, floor = DEFAULT_MIN_QUERY_RELEVANCE) {
883
+ if (!(floor > 0))
884
+ return rows;
885
+ const queryTokens = tokenizeForOverlap(keywords);
886
+ if (!queryTokens.length)
887
+ return rows; // no query signal to judge against
888
+ const changedFiles = gitCtx?.changedFiles ?? new Set();
889
+ const branch = gitCtx?.branch;
890
+ const crossFloor = Math.max(floor, CROSS_PROJECT_MIN_QUERY_RELEVANCE);
891
+ return rows.filter((doc) => {
892
+ if (fileRelevanceBoost(doc.path, changedFiles) > 0)
893
+ return true;
894
+ if (branchMatchBoost(doc.content, branch) > 0)
895
+ return true;
896
+ if (detectedProject && doc.project === detectedProject && doc.type === "canonical")
897
+ return true;
898
+ const isCrossProject = Boolean(detectedProject) && doc.project !== detectedProject;
899
+ return docOverlapScore(queryTokens, doc) >= (isCrossProject ? crossFloor : floor);
900
+ });
901
+ }
844
902
  export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudget) {
845
903
  const selected = [];
846
904
  let usedTokens = 36;
@@ -883,7 +941,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
883
941
  ? overlapScore(queryTokens, `${doc.filename}\n${snippet}`)
884
942
  : focusScore;
885
943
  }
886
- let est = approximateTokens(snippet) + 14;
944
+ let est = approximateTokens(snippet) + SNIPPET_OVERHEAD_TOKENS;
887
945
  if (selected.length > 0 && focusScore < VERY_LOW_FOCUS_SNIPPET_SCORE && usedTokens + est > Math.floor(tokenBudget * 0.8)) {
888
946
  continue;
889
947
  }
@@ -891,7 +949,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
891
949
  break;
892
950
  if (selected.length === 0 && usedTokens + est > tokenBudget) {
893
951
  snippet = compactSnippet(snippet, 3, Math.floor(charBudget * 0.55));
894
- est = approximateTokens(snippet) + 14;
952
+ est = approximateTokens(snippet) + SNIPPET_OVERHEAD_TOKENS;
895
953
  }
896
954
  const key = entryScoreKey(doc.project, doc.filename, doc.content);
897
955
  selected.push({ doc, snippet, key });
@@ -903,7 +961,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
903
961
  // rounding / compaction producing more tokens than estimated during selection)
904
962
  while (selected.length > 1 && usedTokens > tokenBudget) {
905
963
  const removed = selected.pop();
906
- usedTokens -= approximateTokens(removed.snippet) + 14;
964
+ usedTokens -= approximateTokens(removed.snippet) + SNIPPET_OVERHEAD_TOKENS;
907
965
  }
908
966
  return { selected, usedTokens };
909
967
  }
@@ -2,6 +2,7 @@
2
2
  * Shell entry point: wires PhrenShell to stdin/stdout.
3
3
  * Extracted from shell.ts to keep the orchestrator under 300 lines.
4
4
  */
5
+ import type { ShellStartup } from "./startup.js";
5
6
  interface LiveStateHost {
6
7
  invalidateSubsectionsCache(): void;
7
8
  setMessage(message: string): void;
@@ -13,6 +14,14 @@ interface StartupIntroPlan {
13
14
  dwellMs: number;
14
15
  markSeen: boolean;
15
16
  }
17
+ /**
18
+ * The intro used to attach its own stdin listener while the shell's key handler
19
+ * was already live, so the keypress that dismissed the splash was *also* fed to
20
+ * the shell (pressing "q" at the splash quit phren outright) and the intro's
21
+ * animation frames raced the first dashboard repaint. Key delivery is now owned
22
+ * by startShell, which hands the intro a one-shot waiter that consumes the key.
23
+ */
24
+ export type { KeypressWaiter } from "./intro.js";
16
25
  export declare function resolveStartupIntroPlan(phrenPath: string, version?: string): StartupIntroPlan;
17
26
  export declare function startLiveStatePoller({ phrenPath, shell, repaint, isExiting, intervalMs, computeToken, }: {
18
27
  phrenPath: string;
@@ -22,5 +31,4 @@ export declare function startLiveStatePoller({ phrenPath, shell, repaint, isExit
22
31
  intervalMs?: number;
23
32
  computeToken?: (phrenPath: string) => string;
24
33
  }): () => void;
25
- export declare function startShell(phrenPath: string, profile: string): Promise<void>;
26
- export {};
34
+ export declare function startShell(phrenPath: string, profile: string, startup?: ShellStartup): Promise<void>;