@phren/cli 0.1.14 → 0.1.16
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.
- package/README.md +1 -1
- package/dist/capabilities/cli.js +1 -1
- package/dist/capabilities/mcp.js +1 -1
- package/dist/capabilities/vscode.js +1 -1
- package/dist/capabilities/web-ui.js +1 -1
- package/dist/cli/extract.js +2 -1
- package/dist/cli/govern.js +3 -2
- package/dist/cli/namespaces-projects.js +7 -6
- package/dist/cli/ops.js +2 -2
- package/dist/cli/session-start.js +2 -1
- package/dist/cli/team.js +7 -5
- package/dist/cli-hooks-session-handlers.js +2 -1
- package/dist/content/archive.js +2 -1
- package/dist/content/citation.d.ts +4 -0
- package/dist/content/citation.js +14 -5
- package/dist/content/dedup.js +6 -5
- package/dist/content/learning.d.ts +1 -3
- package/dist/content/learning.js +17 -62
- package/dist/content/validate.js +2 -1
- package/dist/core/project.js +2 -1
- package/dist/data/access.d.ts +2 -7
- package/dist/data/access.js +14 -20
- package/dist/finding/journal.js +2 -2
- package/dist/finding/lifecycle.js +2 -1
- package/dist/governance/policy.d.ts +2 -0
- package/dist/governance/policy.js +2 -2
- package/dist/hooks.js +38 -2
- package/dist/init/init-uninstall.js +2 -1
- package/dist/init/setup.js +5 -4
- package/dist/init-uninstall.js +2 -1
- package/dist/link/checksums.js +2 -1
- package/dist/link/context.js +2 -1
- package/dist/link/doctor.js +4 -3
- package/dist/link/link.js +2 -1
- package/dist/phren-paths.js +3 -2
- package/dist/profile-store.d.ts +1 -0
- package/dist/profile-store.js +15 -16
- package/dist/project-topics.js +4 -3
- package/dist/shell/input.js +3 -3
- package/dist/status.js +2 -2
- package/dist/tools/data.js +4 -4
- package/dist/tools/extract.js +3 -2
- package/dist/tools/finding.js +10 -15
- package/dist/tools/search.js +5 -14
- package/dist/tools/session.js +2 -16
- package/dist/ui/data.js +6 -5
- package/dist/ui/server.js +3 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ MCP server that indexes your personal phren and exposes it to AI agents via full
|
|
|
4
4
|
|
|
5
5
|
On startup it walks your phren directory, reads all `.md` files, and builds an in-memory SQLite FTS5 index.
|
|
6
6
|
|
|
7
|
-
Public surface:
|
|
7
|
+
Public surface: 54 MCP tools across 12 modules (search, tasks, findings, memory, data, graph, sessions, ops/review, skills, hooks, config, extraction).
|
|
8
8
|
|
|
9
9
|
Notable shipped capabilities:
|
|
10
10
|
- finding lifecycle tools: `supersede_finding`, `retract_finding`, `resolve_contradiction`, `get_contradictions`
|
package/dist/capabilities/cli.js
CHANGED
package/dist/capabilities/mcp.js
CHANGED
package/dist/cli/extract.js
CHANGED
|
@@ -4,6 +4,7 @@ import { detectProject } from "../shared/index.js";
|
|
|
4
4
|
import { commandExists } from "../hooks.js";
|
|
5
5
|
import { runGit as runGitShared, isFeatureEnabled, clampInt, errorMessage, resolveExecCommand } from "../utils.js";
|
|
6
6
|
import { appendFindingJournal, compactFindingJournals } from "../finding/journal.js";
|
|
7
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
7
8
|
import { getProactivityLevelForTask, getProactivityLevelForFindings, shouldAutoCaptureFindingsForLevel } from "../proactivity.js";
|
|
8
9
|
import * as fs from "fs";
|
|
9
10
|
import * as os from "os";
|
|
@@ -276,7 +277,7 @@ export async function handleExtractMemories(projectArg, cwdArg, silent = false,
|
|
|
276
277
|
continue;
|
|
277
278
|
const line = `${c.text}${c.commit ? ` (source commit ${c.commit.slice(0, 8)})` : ""}`;
|
|
278
279
|
if (c.text.startsWith("CI failure pattern:")) {
|
|
279
|
-
const key = entryScoreKey(project,
|
|
280
|
+
const key = entryScoreKey(project, FINDINGS_FILENAME, line);
|
|
280
281
|
recordFeedback(getPhrenPath(), key, "regression");
|
|
281
282
|
}
|
|
282
283
|
if (c.score >= threshold) {
|
package/dist/cli/govern.js
CHANGED
|
@@ -5,6 +5,7 @@ import * as fs from "fs";
|
|
|
5
5
|
import * as path from "path";
|
|
6
6
|
import { handleExtractMemories } from "./extract.js";
|
|
7
7
|
import { errorMessage } from "../utils.js";
|
|
8
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
8
9
|
import { logger } from "../logger.js";
|
|
9
10
|
import { compactFindingJournals } from "../finding/journal.js";
|
|
10
11
|
import { resolveRuntimeProfile } from "../runtime-profile.js";
|
|
@@ -72,7 +73,7 @@ export async function handleGovernMemories(projectArg, silent = false, dryRun =
|
|
|
72
73
|
let conflictCount = 0;
|
|
73
74
|
let reviewCount = 0;
|
|
74
75
|
for (const project of projects) {
|
|
75
|
-
const learningsPath = path.join(getPhrenPath(), project,
|
|
76
|
+
const learningsPath = path.join(getPhrenPath(), project, FINDINGS_FILENAME);
|
|
76
77
|
if (!fs.existsSync(learningsPath))
|
|
77
78
|
continue;
|
|
78
79
|
const content = fs.readFileSync(learningsPath, "utf8");
|
|
@@ -162,7 +163,7 @@ export async function handlePruneMemories(args = []) {
|
|
|
162
163
|
}
|
|
163
164
|
let ttlExpired = 0;
|
|
164
165
|
for (const project of projects) {
|
|
165
|
-
const learningsPath = path.join(getPhrenPath(), project,
|
|
166
|
+
const learningsPath = path.join(getPhrenPath(), project, FINDINGS_FILENAME);
|
|
166
167
|
if (!fs.existsSync(learningsPath))
|
|
167
168
|
continue;
|
|
168
169
|
const content = fs.readFileSync(learningsPath, "utf8");
|
|
@@ -4,6 +4,7 @@ import { expandHomePath, findArchivedProjectNameCaseInsensitive, findProjectName
|
|
|
4
4
|
import { isValidProjectName, errorMessage } from "../utils.js";
|
|
5
5
|
import { logger } from "../logger.js";
|
|
6
6
|
import { TASK_FILE_ALIASES } from "../data/tasks.js";
|
|
7
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
7
8
|
import { PROJECT_OWNERSHIP_MODES, parseProjectOwnershipMode, writeProjectConfig, writeProjectHookConfig, } from "../project-config.js";
|
|
8
9
|
import { resolveProjectStorePath, parseMcpToggle } from "./namespaces-utils.js";
|
|
9
10
|
export async function handleProjectsNamespace(args, profile) {
|
|
@@ -108,7 +109,7 @@ export async function handleProjectsNamespace(args, profile) {
|
|
|
108
109
|
const learningsResult = readFindings(storePath, name);
|
|
109
110
|
if (learningsResult.ok)
|
|
110
111
|
exported.learnings = learningsResult.data;
|
|
111
|
-
const findingsPath = path.join(projectDir,
|
|
112
|
+
const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
|
|
112
113
|
if (fs.existsSync(findingsPath))
|
|
113
114
|
exported.findingsRaw = fs.readFileSync(findingsPath, "utf8");
|
|
114
115
|
const taskResult = readTasks(storePath, name);
|
|
@@ -186,8 +187,8 @@ export async function handleProjectsNamespace(args, profile) {
|
|
|
186
187
|
imported.push("CLAUDE.md");
|
|
187
188
|
}
|
|
188
189
|
if (typeof decoded.findingsRaw === "string") {
|
|
189
|
-
fs.writeFileSync(path.join(stagedProjectDir,
|
|
190
|
-
imported.push(
|
|
190
|
+
fs.writeFileSync(path.join(stagedProjectDir, FINDINGS_FILENAME), decoded.findingsRaw);
|
|
191
|
+
imported.push(FINDINGS_FILENAME);
|
|
191
192
|
}
|
|
192
193
|
else if (Array.isArray(decoded.learnings) && decoded.learnings.length > 0) {
|
|
193
194
|
const date = new Date().toISOString().slice(0, 10);
|
|
@@ -197,8 +198,8 @@ export async function handleProjectsNamespace(args, profile) {
|
|
|
197
198
|
lines.push(`- ${item.text}`);
|
|
198
199
|
}
|
|
199
200
|
lines.push("");
|
|
200
|
-
fs.writeFileSync(path.join(stagedProjectDir,
|
|
201
|
-
imported.push(
|
|
201
|
+
fs.writeFileSync(path.join(stagedProjectDir, FINDINGS_FILENAME), lines.join("\n"));
|
|
202
|
+
imported.push(FINDINGS_FILENAME);
|
|
202
203
|
}
|
|
203
204
|
if (typeof decoded.taskRaw === "string") {
|
|
204
205
|
fs.writeFileSync(path.join(stagedProjectDir, TASKS_FILENAME), decoded.taskRaw);
|
|
@@ -314,7 +315,7 @@ function handleProjectsList(profile) {
|
|
|
314
315
|
dirFiles = new Set();
|
|
315
316
|
}
|
|
316
317
|
const tags = [];
|
|
317
|
-
if (dirFiles.has(
|
|
318
|
+
if (dirFiles.has(FINDINGS_FILENAME))
|
|
318
319
|
tags.push("findings");
|
|
319
320
|
if (TASK_FILE_ALIASES.some((filename) => dirFiles.has(filename)))
|
|
320
321
|
tags.push("tasks");
|
package/dist/cli/ops.js
CHANGED
|
@@ -3,7 +3,7 @@ import * as path from "path";
|
|
|
3
3
|
import { execFileSync } from "child_process";
|
|
4
4
|
import { EXEC_TIMEOUT_MS, findProjectNameCaseInsensitive, getPhrenPath, normalizeProjectNameForCreate, } from "../shared.js";
|
|
5
5
|
import { isValidProjectName, errorMessage } from "../utils.js";
|
|
6
|
-
import { readTasksAcrossProjects, TASKS_FILENAME } from "../data/access.js";
|
|
6
|
+
import { readTasksAcrossProjects, TASKS_FILENAME, FINDINGS_FILENAME } from "../data/access.js";
|
|
7
7
|
import { applyGravity } from "../data/tasks.js";
|
|
8
8
|
import { buildIndex, queryRows } from "../shared/index.js";
|
|
9
9
|
import { resolveSubprocessArgs } from "./hooks.js";
|
|
@@ -128,7 +128,7 @@ export async function handleQuickstart() {
|
|
|
128
128
|
const projectDir = path.join(phrenPath, normalizedProjectName);
|
|
129
129
|
if (!fs.existsSync(projectDir)) {
|
|
130
130
|
fs.mkdirSync(projectDir, { recursive: true });
|
|
131
|
-
fs.writeFileSync(path.join(projectDir,
|
|
131
|
+
fs.writeFileSync(path.join(projectDir, FINDINGS_FILENAME), `# ${normalizedProjectName} Findings\n`);
|
|
132
132
|
fs.writeFileSync(path.join(projectDir, TASKS_FILENAME), `# ${normalizedProjectName} Tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
|
|
133
133
|
}
|
|
134
134
|
console.log(`\n\u2713 phren ready. Project: ${normalizedProjectName}. Try: phren search 'your query'`);
|
|
@@ -7,6 +7,7 @@ import * as path from "path";
|
|
|
7
7
|
import * as crypto from "crypto";
|
|
8
8
|
import { buildHookContext, handleGuardSkip, debugLog, appendAuditLog, runtimeFile, sessionMarker, getProjectDirs, findProjectNameCaseInsensitive, updateRuntimeHealth, withFileLock, detectProject, isProjectHookEnabled, readProjectConfig, getProjectSourcePath, detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, errorMessage, resolveRuntimeProfile, } from "./hooks-context.js";
|
|
9
9
|
import { TASKS_FILENAME } from "../data/tasks.js";
|
|
10
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
10
11
|
import { readInstallPreferences } from "../init/preferences.js";
|
|
11
12
|
import { logger } from "../logger.js";
|
|
12
13
|
import { sessionFileForId, readSessionStateFile, writeSessionStateFile, } from "../session/utils.js";
|
|
@@ -17,7 +18,7 @@ const SESSION_START_ONBOARDING_MARKER = "session-start-onboarding-v1";
|
|
|
17
18
|
const SYNC_WARN_MARKER = "sync-broken-warned-v1";
|
|
18
19
|
function projectHasBootstrapSignals(phrenPath, project) {
|
|
19
20
|
const projectDir = path.join(phrenPath, project);
|
|
20
|
-
const findingsPath = path.join(projectDir,
|
|
21
|
+
const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
|
|
21
22
|
if (fs.existsSync(findingsPath)) {
|
|
22
23
|
const findings = fs.readFileSync(findingsPath, "utf8");
|
|
23
24
|
if (/^-\s+/m.test(findings))
|
package/dist/cli/team.js
CHANGED
|
@@ -6,6 +6,8 @@ import * as fs from "fs";
|
|
|
6
6
|
import * as path from "path";
|
|
7
7
|
import { execFileSync } from "child_process";
|
|
8
8
|
import { getPhrenPath } from "../shared.js";
|
|
9
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
10
|
+
import { TASKS_FILENAME } from "../data/tasks.js";
|
|
9
11
|
import { isValidProjectName } from "../utils.js";
|
|
10
12
|
import { addProjectToProfile, resolveActiveProfile } from "../profile-store.js";
|
|
11
13
|
import { addStoreToRegistry, findStoreByName, generateStoreId, readTeamBootstrap, updateStoreProjects, } from "../store-registry.js";
|
|
@@ -81,7 +83,7 @@ async function handleTeamInit(args) {
|
|
|
81
83
|
const globalDir = path.join(storePath, "global");
|
|
82
84
|
fs.mkdirSync(globalDir, { recursive: true });
|
|
83
85
|
atomicWriteText(path.join(globalDir, "CLAUDE.md"), `# ${name} Team Store\n\nShared knowledge for the ${name} team.\n`);
|
|
84
|
-
atomicWriteText(path.join(globalDir,
|
|
86
|
+
atomicWriteText(path.join(globalDir, FINDINGS_FILENAME), `# global findings\n`);
|
|
85
87
|
// Initialize git repo
|
|
86
88
|
execFileSync("git", ["init"], {
|
|
87
89
|
cwd: storePath,
|
|
@@ -230,11 +232,11 @@ async function handleTeamAddProject(args) {
|
|
|
230
232
|
const journalDir = path.join(projectDir, "journal");
|
|
231
233
|
fs.mkdirSync(journalDir, { recursive: true });
|
|
232
234
|
// Scaffold project files
|
|
233
|
-
if (!fs.existsSync(path.join(projectDir,
|
|
234
|
-
atomicWriteText(path.join(projectDir,
|
|
235
|
+
if (!fs.existsSync(path.join(projectDir, FINDINGS_FILENAME))) {
|
|
236
|
+
atomicWriteText(path.join(projectDir, FINDINGS_FILENAME), `# ${projectName} findings\n`);
|
|
235
237
|
}
|
|
236
|
-
if (!fs.existsSync(path.join(projectDir,
|
|
237
|
-
atomicWriteText(path.join(projectDir,
|
|
238
|
+
if (!fs.existsSync(path.join(projectDir, TASKS_FILENAME))) {
|
|
239
|
+
atomicWriteText(path.join(projectDir, TASKS_FILENAME), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
|
|
238
240
|
}
|
|
239
241
|
if (!fs.existsSync(path.join(projectDir, "summary.md"))) {
|
|
240
242
|
atomicWriteText(path.join(projectDir, "summary.md"), `# ${projectName}\n**What:** \n`);
|
|
@@ -10,12 +10,13 @@ import * as fs from "fs";
|
|
|
10
10
|
import * as path from "path";
|
|
11
11
|
import { spawnDetachedChild } from "./shared/process.js";
|
|
12
12
|
import { TASKS_FILENAME } from "./data/tasks.js";
|
|
13
|
+
import { FINDINGS_FILENAME } from "./data/access.js";
|
|
13
14
|
import { resolveSubprocessArgs as _resolveSubprocessArgs, runBestEffortGit, countUnsyncedCommits, } from "./cli-hooks-git.js";
|
|
14
15
|
const SESSION_START_ONBOARDING_MARKER = "session-start-onboarding-v1";
|
|
15
16
|
const SYNC_WARN_MARKER = "sync-broken-warned-v1";
|
|
16
17
|
function projectHasBootstrapSignals(phrenPath, project) {
|
|
17
18
|
const projectDir = path.join(phrenPath, project);
|
|
18
|
-
const findingsPath = path.join(projectDir,
|
|
19
|
+
const findingsPath = path.join(projectDir, FINDINGS_FILENAME);
|
|
19
20
|
if (fs.existsSync(findingsPath)) {
|
|
20
21
|
const findings = fs.readFileSync(findingsPath, "utf8");
|
|
21
22
|
if (/^-\s+/m.test(findings))
|
package/dist/content/archive.js
CHANGED
|
@@ -8,6 +8,7 @@ import { walkDirectory } from "../shared/data-utils.js";
|
|
|
8
8
|
import { appendArchivedEntriesToTopicDoc, classifyTopicForText, readProjectTopics, topicReferencePath } from "../project-topics.js";
|
|
9
9
|
import { isCitationLine, isArchiveStart, isArchiveEnd, stripComments } from "./metadata.js";
|
|
10
10
|
import { logger } from "../logger.js";
|
|
11
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
11
12
|
/**
|
|
12
13
|
* Count active (non-archived) finding entries in FINDINGS.md content.
|
|
13
14
|
* Entries inside archive blocks are considered archived.
|
|
@@ -116,7 +117,7 @@ export function autoArchiveToReference(phrenPath, project, keepCount) {
|
|
|
116
117
|
const resolvedDir = safeProjectPath(phrenPath, project);
|
|
117
118
|
if (!resolvedDir || !fs.existsSync(resolvedDir))
|
|
118
119
|
return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
|
|
119
|
-
const learningsPath = path.join(resolvedDir,
|
|
120
|
+
const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
|
|
120
121
|
if (!fs.existsSync(learningsPath))
|
|
121
122
|
return phrenOk(0);
|
|
122
123
|
// Consolidation lock to prevent concurrent runs for the same project (atomic create via wx flag).
|
|
@@ -40,6 +40,10 @@ export declare function inferCitationLocation(repoPath: string, commit: string):
|
|
|
40
40
|
};
|
|
41
41
|
export declare function buildCitationComment(citation: FindingCitation): string;
|
|
42
42
|
export declare function buildSourceComment(source: FindingProvenance): string;
|
|
43
|
+
/** Build a standalone scope comment. Returns empty string if scope is unset or "shared". */
|
|
44
|
+
export declare function buildScopeComment(scope: string | undefined): string;
|
|
45
|
+
/** Parse a standalone `<!-- scope:VALUE -->` comment. */
|
|
46
|
+
export declare function parseScopeComment(line: string): string | undefined;
|
|
43
47
|
export declare function parseSourceComment(line: string): FindingProvenance | null;
|
|
44
48
|
export declare function parseCitationComment(line: string): FindingCitation | null;
|
|
45
49
|
export declare function validateFindingCitation(citation: FindingCitation): boolean;
|
package/dist/content/citation.js
CHANGED
|
@@ -90,6 +90,20 @@ export function buildSourceComment(source) {
|
|
|
90
90
|
parts.push(`scope:${source.scope}`);
|
|
91
91
|
return parts.length > 0 ? `<!-- source:${parts.join(" ")} -->` : "";
|
|
92
92
|
}
|
|
93
|
+
/** Build a standalone scope comment. Returns empty string if scope is unset or "shared". */
|
|
94
|
+
export function buildScopeComment(scope) {
|
|
95
|
+
if (!scope || scope === "shared")
|
|
96
|
+
return "";
|
|
97
|
+
return `<!-- scope:${scope} -->`;
|
|
98
|
+
}
|
|
99
|
+
/** Parse a standalone `<!-- scope:VALUE -->` comment. */
|
|
100
|
+
export function parseScopeComment(line) {
|
|
101
|
+
const m = line.match(/<!--\s*scope:(".*?"|\S+)\s*-->/);
|
|
102
|
+
if (!m)
|
|
103
|
+
return undefined;
|
|
104
|
+
const raw = m[1].replace(/^"|"$/g, "").trim();
|
|
105
|
+
return raw || undefined;
|
|
106
|
+
}
|
|
93
107
|
export function parseSourceComment(line) {
|
|
94
108
|
const sourceMatch = line.match(METADATA_REGEX.source);
|
|
95
109
|
if (!sourceMatch)
|
|
@@ -416,11 +430,6 @@ export function filterTrustedFindingsDetailed(content, opts) {
|
|
|
416
430
|
}
|
|
417
431
|
if (!citation)
|
|
418
432
|
confidence *= 0.8;
|
|
419
|
-
const provenance = parseSourceComment(line)?.source ?? "unknown";
|
|
420
|
-
if (provenance === "human")
|
|
421
|
-
confidence *= 1.1;
|
|
422
|
-
if (provenance === "extract")
|
|
423
|
-
confidence *= 0.9;
|
|
424
433
|
if (project && highImpactFindingIds?.size) {
|
|
425
434
|
const findingId = findingIdFromLine(line);
|
|
426
435
|
if (highImpactFindingIds.has(findingId))
|
package/dist/content/dedup.js
CHANGED
|
@@ -6,6 +6,7 @@ import { isFeatureEnabled, safeProjectPath, errorMessage } from "../utils.js";
|
|
|
6
6
|
import { UNIVERSAL_TECH_TERMS_RE, EXTRA_ENTITY_PATTERNS } from "../phren-core.js";
|
|
7
7
|
import { isInactiveFindingLine } from "../finding/lifecycle.js";
|
|
8
8
|
import { logger } from "../logger.js";
|
|
9
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
9
10
|
// ── LLM provider abstraction ────────────────────────────────────────────────
|
|
10
11
|
const MAX_CACHE_ENTRIES = 500;
|
|
11
12
|
function loadCache(cachePath) {
|
|
@@ -200,7 +201,7 @@ const DYNAMIC_ENTITY_RE = /\b(?:[A-Z][a-z]+(?:[A-Z][a-z]*)+|[A-Z]{2,8}|[A-Z][a-z
|
|
|
200
201
|
*/
|
|
201
202
|
export function extractDynamicEntities(phrenPath, project) {
|
|
202
203
|
try {
|
|
203
|
-
const findingsPath = path.join(phrenPath, project,
|
|
204
|
+
const findingsPath = path.join(phrenPath, project, FINDINGS_FILENAME);
|
|
204
205
|
if (!fs.existsSync(findingsPath))
|
|
205
206
|
return new Set();
|
|
206
207
|
const findingsStat = fs.statSync(findingsPath);
|
|
@@ -479,7 +480,7 @@ export async function checkSemanticDedup(phrenPath, project, newLearning, signal
|
|
|
479
480
|
const resolvedDir = safeProjectPath(phrenPath, project);
|
|
480
481
|
if (!resolvedDir)
|
|
481
482
|
return false;
|
|
482
|
-
const findingsPath = path.join(resolvedDir,
|
|
483
|
+
const findingsPath = path.join(resolvedDir, FINDINGS_FILENAME);
|
|
483
484
|
if (!fs.existsSync(findingsPath))
|
|
484
485
|
return false;
|
|
485
486
|
const existingContent = fs.readFileSync(findingsPath, "utf8");
|
|
@@ -537,13 +538,13 @@ export async function checkSemanticConflicts(phrenPath, project, newFinding, sig
|
|
|
537
538
|
// Collect bullet sources: { bullets, sourceProject } pairs
|
|
538
539
|
const sources = [];
|
|
539
540
|
// Current project
|
|
540
|
-
const findingsPath = path.join(resolvedDir,
|
|
541
|
+
const findingsPath = path.join(resolvedDir, FINDINGS_FILENAME);
|
|
541
542
|
if (fs.existsSync(findingsPath)) {
|
|
542
543
|
const content = fs.readFileSync(findingsPath, "utf8");
|
|
543
544
|
sources.push({ bullets: content.split("\n").filter((l) => l.startsWith("- ")), sourceProject: null });
|
|
544
545
|
}
|
|
545
546
|
// Global project findings
|
|
546
|
-
const globalFindingsPath = path.join(phrenPath, "global",
|
|
547
|
+
const globalFindingsPath = path.join(phrenPath, "global", FINDINGS_FILENAME);
|
|
547
548
|
if (fs.existsSync(globalFindingsPath)) {
|
|
548
549
|
const content = fs.readFileSync(globalFindingsPath, "utf8");
|
|
549
550
|
const bullets = content.split("\n").filter((l) => l.startsWith("- "));
|
|
@@ -557,7 +558,7 @@ export async function checkSemanticConflicts(phrenPath, project, newFinding, sig
|
|
|
557
558
|
const otherProjects = entries
|
|
558
559
|
.filter((e) => e.isDirectory() && e.name !== project && e.name !== "global" && !e.name.startsWith("."))
|
|
559
560
|
.map((e) => {
|
|
560
|
-
const fp = path.join(phrenPath, e.name,
|
|
561
|
+
const fp = path.join(phrenPath, e.name, FINDINGS_FILENAME);
|
|
561
562
|
if (!fs.existsSync(fp))
|
|
562
563
|
return null;
|
|
563
564
|
try {
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
import { type PhrenResult } from "../shared.js";
|
|
2
|
-
import { type FindingCitation
|
|
2
|
+
import { type FindingCitation } from "./citation.js";
|
|
3
3
|
interface AddFindingOptions {
|
|
4
4
|
extraAnnotations?: string[];
|
|
5
5
|
sessionId?: string;
|
|
6
|
-
source?: FindingProvenanceSource;
|
|
7
6
|
scope?: string;
|
|
8
7
|
}
|
|
9
8
|
export interface AddFindingResult {
|
|
@@ -16,7 +15,6 @@ export declare function addFindingToFile(phrenPath: string, project: string, lea
|
|
|
16
15
|
export declare function addFindingsToFile(phrenPath: string, project: string, learnings: string[], opts?: {
|
|
17
16
|
extraAnnotationsByFinding?: string[][];
|
|
18
17
|
sessionId?: string;
|
|
19
|
-
source?: FindingProvenanceSource;
|
|
20
18
|
scope?: string;
|
|
21
19
|
}): PhrenResult<{
|
|
22
20
|
added: string[];
|
package/dist/content/learning.js
CHANGED
|
@@ -5,14 +5,14 @@ import { debugLog, appendAuditLog, phrenOk, phrenErr, PhrenError } from "../shar
|
|
|
5
5
|
import { normalizeMemoryScope } from "../shared.js";
|
|
6
6
|
import { withFileLock } from "../shared/governance.js";
|
|
7
7
|
import { isValidProjectName, safeProjectPath } from "../utils.js";
|
|
8
|
-
import {
|
|
9
|
-
import { buildCitationComment, buildSourceComment, getHeadCommit, getRepoRoot, inferCitationLocation, isFindingProvenanceSource, } from "./citation.js";
|
|
8
|
+
import { buildCitationComment, buildScopeComment, getHeadCommit, getRepoRoot, inferCitationLocation, } from "./citation.js";
|
|
10
9
|
import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCoref, detectConflicts, extractDynamicEntities } from "./dedup.js";
|
|
11
10
|
import { validateFindingsFormat, validateFinding } from "./validate.js";
|
|
12
11
|
import { countActiveFindings, autoArchiveToReference } from "./archive.js";
|
|
13
|
-
import { resolveAutoFindingTaskItem, resolveFindingTaskReference,
|
|
12
|
+
import { resolveAutoFindingTaskItem, resolveFindingTaskReference, } from "../finding/context.js";
|
|
14
13
|
import { buildLifecycleComments, extractFindingType, parseFindingLifecycle, stripLifecycleComments, } from "../finding/lifecycle.js";
|
|
15
14
|
import { METADATA_REGEX, } from "./metadata.js";
|
|
15
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
16
16
|
/** Default cap for active findings before auto-archiving is triggered. */
|
|
17
17
|
const DEFAULT_FINDINGS_CAP = 20;
|
|
18
18
|
const LIFECYCLE_ANNOTATION_RE = METADATA_REGEX.lifecycleAnnotation;
|
|
@@ -42,51 +42,8 @@ function resolveInferredCitationRepo(citationInput) {
|
|
|
42
42
|
}
|
|
43
43
|
return undefined;
|
|
44
44
|
}
|
|
45
|
-
function
|
|
46
|
-
|
|
47
|
-
(process.env.PHREN_MODEL),
|
|
48
|
-
process.env.OPENAI_MODEL,
|
|
49
|
-
process.env.CLAUDE_MODEL,
|
|
50
|
-
(process.env.PHREN_LLM_MODEL),
|
|
51
|
-
process.env.MODEL,
|
|
52
|
-
];
|
|
53
|
-
return candidates.find((value) => typeof value === "string" && value.trim())?.trim();
|
|
54
|
-
}
|
|
55
|
-
function detectFindingTool() {
|
|
56
|
-
const candidates = [
|
|
57
|
-
(process.env.PHREN_TOOL),
|
|
58
|
-
(process.env.PHREN_HOOK_TOOL),
|
|
59
|
-
];
|
|
60
|
-
return candidates.find((value) => typeof value === "string" && value.trim())?.trim();
|
|
61
|
-
}
|
|
62
|
-
function detectFindingProvenanceSource(explicitSource) {
|
|
63
|
-
if (explicitSource)
|
|
64
|
-
return explicitSource;
|
|
65
|
-
const envSource = (process.env.PHREN_FINDING_SOURCE)?.trim().toLowerCase();
|
|
66
|
-
if (isFindingProvenanceSource(envSource))
|
|
67
|
-
return envSource;
|
|
68
|
-
if ((process.env.PHREN_CONSOLIDATION) === "1")
|
|
69
|
-
return "consolidation";
|
|
70
|
-
if ((process.env.PHREN_AUTO_EXTRACT) === "1")
|
|
71
|
-
return "extract";
|
|
72
|
-
if ((process.env.PHREN_HOOK_TOOL))
|
|
73
|
-
return "hook";
|
|
74
|
-
if (process.env.PHREN_ACTOR?.trim())
|
|
75
|
-
return "agent";
|
|
76
|
-
return "human";
|
|
77
|
-
}
|
|
78
|
-
function buildFindingSource(sessionId, explicitSource, scope) {
|
|
79
|
-
const actor = process.env.PHREN_ACTOR?.trim() || undefined;
|
|
80
|
-
const source = {
|
|
81
|
-
source: detectFindingProvenanceSource(explicitSource),
|
|
82
|
-
machine: getMachineName(),
|
|
83
|
-
actor,
|
|
84
|
-
tool: detectFindingTool(),
|
|
85
|
-
model: detectFindingModel(),
|
|
86
|
-
session_id: sessionId,
|
|
87
|
-
scope: normalizeMemoryScope(scope),
|
|
88
|
-
};
|
|
89
|
-
return source;
|
|
45
|
+
function buildFindingScope(scope) {
|
|
46
|
+
return normalizeMemoryScope(scope) || undefined;
|
|
90
47
|
}
|
|
91
48
|
function resolveFindingCitationInput(phrenPath, project, citationInput) {
|
|
92
49
|
const resolved = citationInput ? { ...citationInput } : {};
|
|
@@ -124,7 +81,7 @@ export function autoDetectFindingType(text) {
|
|
|
124
81
|
return null;
|
|
125
82
|
}
|
|
126
83
|
function prepareFinding(opts) {
|
|
127
|
-
const { finding: learning, project, fullHistory, extraAnnotations, citationInput,
|
|
84
|
+
const { finding: learning, project, fullHistory, extraAnnotations, citationInput, scope, nowIso, inferredRepo, headCommit, phrenPath } = opts;
|
|
128
85
|
const secretType = scanForSecrets(learning);
|
|
129
86
|
if (secretType) {
|
|
130
87
|
return { status: "rejected", reason: `Contains ${secretType}` };
|
|
@@ -145,11 +102,11 @@ function prepareFinding(opts) {
|
|
|
145
102
|
const fid = crypto.randomBytes(4).toString("hex");
|
|
146
103
|
const fidComment = `<!-- fid:${fid} -->`;
|
|
147
104
|
const createdComment = `<!-- created: ${today} -->`;
|
|
148
|
-
const
|
|
105
|
+
const scopeComment = buildScopeComment(scope);
|
|
149
106
|
let lifecycle = { status: "active", status_updated: today };
|
|
150
107
|
let bullet = `${normalizedLearning.startsWith("- ") ? normalizedLearning : `- ${normalizedLearning}`} ${fidComment} ${createdComment}`;
|
|
151
|
-
if (
|
|
152
|
-
bullet += ` ${
|
|
108
|
+
if (scopeComment)
|
|
109
|
+
bullet += ` ${scopeComment}`;
|
|
153
110
|
if (isDuplicateFinding(fullHistory, bullet)) {
|
|
154
111
|
return { status: "duplicate" };
|
|
155
112
|
}
|
|
@@ -265,7 +222,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
|
|
|
265
222
|
const resolvedDir = safeProjectPath(phrenPath, project);
|
|
266
223
|
if (!resolvedDir)
|
|
267
224
|
return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
|
|
268
|
-
const learningsPath = path.join(resolvedDir,
|
|
225
|
+
const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
|
|
269
226
|
// Secret/PII scan — reject before anything else (before existence check, before lock)
|
|
270
227
|
const nowIso = new Date().toISOString();
|
|
271
228
|
const today = nowIso.slice(0, 10);
|
|
@@ -273,8 +230,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
|
|
|
273
230
|
if (!resolvedCitationInputResult.ok)
|
|
274
231
|
return resolvedCitationInputResult;
|
|
275
232
|
const resolvedCitationInput = resolvedCitationInputResult.data;
|
|
276
|
-
const
|
|
277
|
-
const source = buildFindingSource(effectiveSessionId, opts?.source, opts?.scope);
|
|
233
|
+
const scope = buildFindingScope(opts?.scope);
|
|
278
234
|
const inferredRepo = resolveInferredCitationRepo(resolvedCitationInput);
|
|
279
235
|
const headCommit = inferredRepo ? getHeadCommit(inferredRepo) : undefined;
|
|
280
236
|
const supersedesText = resolvedCitationInput?.supersedes;
|
|
@@ -295,7 +251,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
|
|
|
295
251
|
const result = withFileLock(learningsPath, () => {
|
|
296
252
|
const preparedForNewFile = prepareFinding({
|
|
297
253
|
finding: learning, project, fullHistory: "", extraAnnotations: opts?.extraAnnotations,
|
|
298
|
-
citationInput: resolvedCitationInput,
|
|
254
|
+
citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
|
|
299
255
|
});
|
|
300
256
|
if (!fs.existsSync(learningsPath)) {
|
|
301
257
|
if (preparedForNewFile.status === "rejected") {
|
|
@@ -328,7 +284,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
|
|
|
328
284
|
: content;
|
|
329
285
|
const prepared = prepareFinding({
|
|
330
286
|
finding: learning, project, fullHistory: historyForDedup, extraAnnotations: opts?.extraAnnotations,
|
|
331
|
-
citationInput: resolvedCitationInput,
|
|
287
|
+
citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
|
|
332
288
|
});
|
|
333
289
|
if (prepared.status === "rejected") {
|
|
334
290
|
return phrenErr(`Rejected: finding appears to contain a secret (${prepared.reason.replace(/^Contains /, "")}). Strip credentials before saving.`, PhrenError.VALIDATION_ERROR);
|
|
@@ -416,15 +372,14 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
|
|
|
416
372
|
const resolvedDir = safeProjectPath(phrenPath, project);
|
|
417
373
|
if (!resolvedDir)
|
|
418
374
|
return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
|
|
419
|
-
const learningsPath = path.join(resolvedDir,
|
|
375
|
+
const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
|
|
420
376
|
const nowIso = new Date().toISOString();
|
|
421
377
|
const today = nowIso.slice(0, 10);
|
|
422
378
|
const resolvedCitationInputResult = resolveFindingCitationInput(phrenPath, project);
|
|
423
379
|
if (!resolvedCitationInputResult.ok)
|
|
424
380
|
return resolvedCitationInputResult;
|
|
425
381
|
const resolvedCitationInput = resolvedCitationInputResult.data;
|
|
426
|
-
const
|
|
427
|
-
const source = buildFindingSource(effectiveSessionId, opts?.source, opts?.scope);
|
|
382
|
+
const scope = buildFindingScope(opts?.scope);
|
|
428
383
|
const inferredRepo = resolveInferredCitationRepo(resolvedCitationInput);
|
|
429
384
|
const headCommit = inferredRepo ? getHeadCommit(inferredRepo) : undefined;
|
|
430
385
|
const added = [];
|
|
@@ -445,7 +400,7 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
|
|
|
445
400
|
}
|
|
446
401
|
const prepared = prepareFinding({
|
|
447
402
|
finding: learning, project, fullHistory: content, extraAnnotations,
|
|
448
|
-
citationInput: resolvedCitationInput,
|
|
403
|
+
citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
|
|
449
404
|
});
|
|
450
405
|
if (prepared.status === "rejected") {
|
|
451
406
|
rejected.push({ text: learning, reason: prepared.reason });
|
|
@@ -480,7 +435,7 @@ export function addFindingsToFile(phrenPath, project, learnings, opts) {
|
|
|
480
435
|
}
|
|
481
436
|
const prepared = prepareFinding({
|
|
482
437
|
finding: learning, project, fullHistory: content, extraAnnotations,
|
|
483
|
-
citationInput: resolvedCitationInput,
|
|
438
|
+
citationInput: resolvedCitationInput, scope, nowIso, inferredRepo, headCommit, phrenPath,
|
|
484
439
|
});
|
|
485
440
|
if (prepared.status === "rejected") {
|
|
486
441
|
rejected.push({ text: learning, reason: prepared.reason });
|
package/dist/content/validate.js
CHANGED
|
@@ -8,6 +8,7 @@ import { countActiveFindings } from "./archive.js";
|
|
|
8
8
|
import { isTaskFileName } from "../data/tasks.js";
|
|
9
9
|
import { METADATA_REGEX } from "./metadata.js";
|
|
10
10
|
import { getNonPrimaryStores, getStoreProjectDirs } from "../store-registry.js";
|
|
11
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
11
12
|
/** Maximum allowed length for a single finding entry (token budget protection). */
|
|
12
13
|
export const MAX_FINDING_LENGTH = 2000;
|
|
13
14
|
function safeParseDate(s) {
|
|
@@ -34,7 +35,7 @@ export function validateFinding(text) {
|
|
|
34
35
|
* Returns null if the project has no FINDINGS.md.
|
|
35
36
|
*/
|
|
36
37
|
export function getProjectConsolidationStatus(dir) {
|
|
37
|
-
const learningsPath = path.join(dir,
|
|
38
|
+
const learningsPath = path.join(dir, FINDINGS_FILENAME);
|
|
38
39
|
if (!fs.existsSync(learningsPath))
|
|
39
40
|
return null;
|
|
40
41
|
const content = fs.readFileSync(learningsPath, "utf8");
|
package/dist/core/project.js
CHANGED
|
@@ -3,6 +3,7 @@ import { phrenErr, phrenOk, readRootManifest } from "../shared.js";
|
|
|
3
3
|
import { bootstrapFromExisting } from "../init/setup.js";
|
|
4
4
|
import { resolveActiveProfile } from "../profile-store.js";
|
|
5
5
|
import { TASKS_FILENAME } from "../data/tasks.js";
|
|
6
|
+
import { FINDINGS_FILENAME } from "../data/access.js";
|
|
6
7
|
export function addProjectFromPath(phrenPath, targetPath, requestedProfile, ownership) {
|
|
7
8
|
if (!targetPath) {
|
|
8
9
|
return phrenErr("Path is required. Pass the current project directory explicitly to avoid adding the wrong working directory.");
|
|
@@ -29,7 +30,7 @@ export function addProjectFromPath(phrenPath, targetPath, requestedProfile, owne
|
|
|
29
30
|
files: {
|
|
30
31
|
claude: added.claudePath,
|
|
31
32
|
summary: path.join(phrenPath, added.project, "summary.md"),
|
|
32
|
-
findings: path.join(phrenPath, added.project,
|
|
33
|
+
findings: path.join(phrenPath, added.project, FINDINGS_FILENAME),
|
|
33
34
|
task: path.join(phrenPath, added.project, TASKS_FILENAME),
|
|
34
35
|
},
|
|
35
36
|
});
|
package/dist/data/access.d.ts
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
import { type PhrenResult } from "../shared.js";
|
|
2
2
|
import { type AddFindingResult } from "../shared/content.js";
|
|
3
|
-
import { type FindingCitation
|
|
3
|
+
import { type FindingCitation } from "../content/citation.js";
|
|
4
4
|
import { type FindingLifecycleStatus } from "../finding/lifecycle.js";
|
|
5
5
|
export type { TaskSection, TaskItem, TaskDoc } from "./tasks.js";
|
|
6
6
|
export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks, completeTasks, completeTask, removeTask, removeTasks, updateTask, linkTaskIssue, pinTask, unpinTask, workNextTask, tidyDoneTasks, taskMarkdown, appendChildFinding, promoteTask, TASKS_FILENAME, TASK_FILE_ALIASES, canonicalTaskFilePath, resolveTaskFilePath, isTaskFileName, type AddTaskOptions, } from "./tasks.js";
|
|
7
7
|
export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, type ProfileInfo, type ProjectCard, } from "../profile-store.js";
|
|
8
8
|
export { loadShellState, resetShellState, saveShellState, type ShellState, } from "../shell/state-store.js";
|
|
9
9
|
export { getRuntimeHealth as readRuntimeHealth } from "../shared/governance.js";
|
|
10
|
+
export declare const FINDINGS_FILENAME = "FINDINGS.md";
|
|
10
11
|
export interface FindingItem {
|
|
11
12
|
id: string;
|
|
12
13
|
/** Stable 8-char hex ID embedded as `<!-- fid:XXXXXXXX -->`. Survives reordering and consolidation. */
|
|
@@ -17,12 +18,6 @@ export interface FindingItem {
|
|
|
17
18
|
citationData?: FindingCitation;
|
|
18
19
|
taskItem?: string;
|
|
19
20
|
confidence?: number;
|
|
20
|
-
source: FindingProvenanceSource;
|
|
21
|
-
machine?: string;
|
|
22
|
-
actor?: string;
|
|
23
|
-
tool?: string;
|
|
24
|
-
model?: string;
|
|
25
|
-
sessionId?: string;
|
|
26
21
|
scope?: string;
|
|
27
22
|
/** First 60 chars of the newer finding that supersedes this one. Set when this finding is stale. */
|
|
28
23
|
supersededBy?: string;
|