@phren/cli 0.1.39 → 0.1.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/dist/auth/profiles.js +59 -5
  2. package/dist/cli/actions.js +11 -3
  3. package/dist/cli/config-access.js +8 -1
  4. package/dist/cli/extract.d.ts +27 -1
  5. package/dist/cli/extract.js +243 -9
  6. package/dist/cli/govern.js +6 -87
  7. package/dist/cli/hooks-context.d.ts +1 -1
  8. package/dist/cli/hooks-context.js +1 -1
  9. package/dist/cli/namespaces-review.js +14 -1
  10. package/dist/cli/session-background.js +4 -0
  11. package/dist/cli/session-git.d.ts +18 -0
  12. package/dist/cli/session-git.js +47 -0
  13. package/dist/cli/session-start.js +2 -2
  14. package/dist/cli/session-stop.d.ts +11 -0
  15. package/dist/cli/session-stop.js +157 -33
  16. package/dist/cli/session-tool-hook.js +17 -5
  17. package/dist/cli-handlers.d.ts +2 -0
  18. package/dist/cli-handlers.js +40 -0
  19. package/dist/cli-registry.d.ts +1 -1
  20. package/dist/cli-registry.js +16 -1
  21. package/dist/content/dedup.d.ts +1 -4
  22. package/dist/content/dedup.js +7 -63
  23. package/dist/content/learning.d.ts +20 -2
  24. package/dist/content/learning.js +21 -3
  25. package/dist/content/quality.d.ts +23 -0
  26. package/dist/content/quality.js +123 -0
  27. package/dist/content/secrets.d.ts +52 -0
  28. package/dist/content/secrets.js +193 -0
  29. package/dist/data/access.d.ts +56 -2
  30. package/dist/data/access.js +246 -24
  31. package/dist/entrypoint.js +5 -1
  32. package/dist/finding/impact.js +170 -43
  33. package/dist/finding/lifecycle.d.ts +19 -2
  34. package/dist/finding/lifecycle.js +15 -3
  35. package/dist/git-worktree.d.ts +19 -0
  36. package/dist/git-worktree.js +117 -0
  37. package/dist/governance/policy.d.ts +84 -4
  38. package/dist/governance/policy.js +209 -14
  39. package/dist/governance/rbac.d.ts +8 -0
  40. package/dist/governance/rbac.js +26 -0
  41. package/dist/hooks.d.ts +26 -0
  42. package/dist/hooks.js +119 -6
  43. package/dist/index.js +5 -1
  44. package/dist/init/guard-globals.d.ts +20 -0
  45. package/dist/init/guard-globals.js +72 -6
  46. package/dist/init/init-configure.d.ts +7 -2
  47. package/dist/init/init-configure.js +42 -16
  48. package/dist/init/init-preset.d.ts +3 -0
  49. package/dist/init/init-preset.js +122 -0
  50. package/dist/init/init-uninstall.js +9 -0
  51. package/dist/init/init-walkthrough.d.ts +2 -0
  52. package/dist/init/init-walkthrough.js +42 -17
  53. package/dist/init/init.d.ts +5 -0
  54. package/dist/init/init.js +71 -19
  55. package/dist/init/management-preset.d.ts +42 -0
  56. package/dist/init/management-preset.js +122 -0
  57. package/dist/init/preferences.d.ts +17 -0
  58. package/dist/init/preferences.js +3 -0
  59. package/dist/init/self-wiring.d.ts +5 -0
  60. package/dist/init/self-wiring.js +52 -0
  61. package/dist/init/setup.d.ts +9 -4
  62. package/dist/init/setup.js +139 -23
  63. package/dist/init/store-gitignore.d.ts +29 -0
  64. package/dist/init/store-gitignore.js +48 -0
  65. package/dist/init/teardown.d.ts +15 -0
  66. package/dist/init/teardown.js +241 -0
  67. package/dist/link/doctor.js +127 -34
  68. package/dist/link/link.js +49 -26
  69. package/dist/phren-core.d.ts +35 -8
  70. package/dist/phren-core.js +35 -8
  71. package/dist/phren-paths.d.ts +90 -1
  72. package/dist/phren-paths.js +150 -5
  73. package/dist/proactivity.js +1 -1
  74. package/dist/shared/embedding-cache.d.ts +16 -0
  75. package/dist/shared/embedding-cache.js +24 -0
  76. package/dist/shared/fragment-graph.js +10 -0
  77. package/dist/shared/index.d.ts +6 -0
  78. package/dist/shared/index.js +523 -138
  79. package/dist/shared/ollama.d.ts +14 -2
  80. package/dist/shared/ollama.js +84 -5
  81. package/dist/shared/retrieval.d.ts +22 -1
  82. package/dist/shared/retrieval.js +30 -1
  83. package/dist/shared/search-fallback.js +15 -3
  84. package/dist/shared/vector-index.d.ts +20 -1
  85. package/dist/shared/vector-index.js +18 -4
  86. package/dist/shared.d.ts +1 -1
  87. package/dist/shared.js +1 -1
  88. package/dist/status.js +31 -2
  89. package/dist/store-registry.d.ts +22 -0
  90. package/dist/store-registry.js +36 -3
  91. package/dist/task/lifecycle.js +31 -0
  92. package/dist/tools/config.js +16 -7
  93. package/dist/tools/data.js +1 -1
  94. package/dist/tools/extract.js +2 -2
  95. package/dist/tools/finding.js +14 -3
  96. package/dist/tools/graph.js +9 -1
  97. package/dist/tools/memory.js +1 -1
  98. package/dist/tools/notes.js +3 -3
  99. package/dist/tools/ops.js +19 -18
  100. package/dist/tools/search.js +2 -2
  101. package/dist/tools/session.js +2 -2
  102. package/dist/tools/tasks.js +2 -2
  103. package/dist/tools/types.d.ts +32 -2
  104. package/dist/tools/types.js +41 -8
  105. package/dist/ui/scripts.js +2 -2
  106. package/dist/ui/server.js +5 -0
  107. package/package.json +1 -1
  108. package/dist/cli-hooks-git.d.ts +0 -50
  109. package/dist/cli-hooks-git.js +0 -288
  110. package/starter/my-api/.claude/skills/README.md +0 -7
  111. package/starter/my-api/CLAUDE.md +0 -33
  112. package/starter/my-api/FINDINGS.md +0 -9
  113. package/starter/my-api/summary.md +0 -7
  114. package/starter/my-api/tasks.md +0 -7
  115. package/starter/my-first-project/.claude/skills/README.md +0 -7
  116. package/starter/my-first-project/CLAUDE.md +0 -49
  117. package/starter/my-first-project/FINDINGS.md +0 -24
  118. package/starter/my-first-project/summary.md +0 -11
  119. package/starter/my-first-project/tasks.md +0 -25
  120. package/starter/my-frontend/.claude/skills/README.md +0 -7
  121. package/starter/my-frontend/CLAUDE.md +0 -33
  122. package/starter/my-frontend/FINDINGS.md +0 -9
  123. package/starter/my-frontend/summary.md +0 -7
  124. package/starter/my-frontend/tasks.md +0 -7
@@ -73,9 +73,63 @@ export declare function removeFindings(phrenPath: string, project: string, match
73
73
  }>;
74
74
  export declare function editFinding(phrenPath: string, project: string, oldText: string, newText: string): PhrenResult<string>;
75
75
  export declare function readReviewQueue(phrenPath: string, project: string): PhrenResult<QueueItem[]>;
76
- /** Remove a queue item's line from review.md (finding stays in FINDINGS.md). */
76
+ export type QueueApproveOutcome = "promoted" | "already_present" | "already_archived";
77
+ export interface QueueApproveResult {
78
+ outcome: QueueApproveOutcome;
79
+ message: string;
80
+ /** Canonical finding text the verb acted on (confidence marker stripped, type tag kept). */
81
+ text: string;
82
+ }
83
+ export type QueueRejectOutcome =
84
+ /** Removed from the live FINDINGS.md tier. */
85
+ "removed"
86
+ /** Removed from reference/topics/*.md, where auto-archive had moved it. */
87
+ | "removed_from_archive"
88
+ /** Nothing to remove: the candidate was never written anywhere. Dequeuing *is* the rejection. */
89
+ | "discarded";
90
+ export interface QueueRejectResult {
91
+ outcome: QueueRejectOutcome;
92
+ message: string;
93
+ text: string;
94
+ }
95
+ /**
96
+ * Approve a queue item: make it real, then dequeue.
97
+ *
98
+ * Three outcomes, because a queue line can point at three different realities:
99
+ *
100
+ * - `promoted` — the text is not in FINDINGS.md, so approving *writes* it. This is the
101
+ * case for every extraction candidate that scored below `autoAcceptThreshold`:
102
+ * extraction queues those without ever adding them, so the old "just splice the line
103
+ * out" behaviour silently discarded them. Promotion goes through `addFindingToFile`,
104
+ * the same path a direct add uses, so dedup, fid assignment, citation metadata, and
105
+ * the findings-cap auto-archive all behave identically.
106
+ * - `already_present` — the text is already a live finding (govern queues existing
107
+ * findings for Stale/Conflicts review). Approving means "keep it"; just dequeue.
108
+ * - `already_archived` — the content only exists in `reference/topics/`, because
109
+ * auto-archive moved it after it was queued. It is still live for retrieval, so the
110
+ * archive is left untouched and the item is dequeued.
111
+ */
112
+ export declare function approveQueueItemDetailed(phrenPath: string, project: string, lineText: string): PhrenResult<QueueApproveResult>;
113
+ /** Remove a queue item's line from review.md, promoting it to a finding when needed. */
77
114
  export declare function approveQueueItem(phrenPath: string, project: string, lineText: string): PhrenResult<string>;
78
- /** Remove a queue item from review.md AND remove the corresponding finding from FINDINGS.md. */
115
+ /**
116
+ * Reject a queue item: destroy the content wherever it actually lives, then dequeue.
117
+ *
118
+ * Rejection removes from the live FINDINGS.md tier *and* from `reference/topics/*.md`,
119
+ * because auto-archive moves findings there without reconciling their queue lines and
120
+ * archived content is still injected into agent prompts. Leaving it would make reject a
121
+ * lie — the hosts tell users rejection removes the finding permanently.
122
+ *
123
+ * Two situations deliberately do NOT succeed quietly:
124
+ * - the content sits in a FINDINGS.md archive block (`<details>` / `phren:archive`),
125
+ * which the rest of the codebase treats as read-only history; and
126
+ * - several *different* bullets match, so deleting one would be a guess.
127
+ *
128
+ * Both return an error and leave the queue line in place, so the user sees the problem
129
+ * instead of a success message over undeleted content.
130
+ */
131
+ export declare function rejectQueueItemDetailed(phrenPath: string, project: string, lineText: string): PhrenResult<QueueRejectResult>;
132
+ /** Remove a queue item from review.md AND the corresponding finding wherever it lives. */
79
133
  export declare function rejectQueueItem(phrenPath: string, project: string, lineText: string): PhrenResult<string>;
80
134
  /** Edit a queue item's text in review.md and the corresponding finding in FINDINGS.md. */
81
135
  export declare function editQueueItem(phrenPath: string, project: string, lineText: string, newText: string): PhrenResult<string>;
@@ -4,14 +4,14 @@
4
4
  import * as fs from "fs";
5
5
  import * as path from "path";
6
6
  import * as yaml from "js-yaml";
7
- import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "../shared.js";
7
+ import { appendAuditLog, phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "../shared.js";
8
8
  import { normalizeQueueEntryText, } from "../shared/governance.js";
9
9
  import { addFindingToFile, } from "../shared/content.js";
10
10
  import { isValidProjectName, queueFilePath, safeProjectPath } from "../utils.js";
11
11
  import { parseCitationComment, parseScopeComment, parseSourceComment, } from "../content/citation.js";
12
12
  import { parseFindingLifecycle, } from "../finding/lifecycle.js";
13
13
  import { METADATA_REGEX, isCitationLine, isArchiveStart, isArchiveEnd, parseFindingId, parseAllContradictions, stripComments, normalizeFindingText, } from "../content/metadata.js";
14
- import { withSafeLock, ensureProject } from "../shared/data-utils.js";
14
+ import { withSafeLock, ensureProject, walkDirectory } from "../shared/data-utils.js";
15
15
  import { getNonPrimaryStores, getStoreProjectDirs } from "../store-registry.js";
16
16
  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, } from "./tasks.js";
17
17
  export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, } from "../profile-store.js";
@@ -439,8 +439,7 @@ function parseQueueLine(line) {
439
439
  const rawText = parsed ? parsed[2] : line.replace(/^-\s+/, "").trim();
440
440
  const confidence = rawText.match(/\[confidence\s+([01](?:\.\d+)?)\]/i);
441
441
  const source = parseSourceComment(line);
442
- let machine = source?.machine;
443
- let model = source?.model;
442
+ const citation = parseCitationComment(line);
444
443
  // Strip the confidence marker from the canonical text so it doesn't pollute FINDINGS.md
445
444
  const sanitized = normalizeQueueEntryText(rawText.replace(/\s*\[confidence\s+[01](?:\.\d+)?\]/gi, "").trim(), { truncate: true });
446
445
  const text = sanitized.ok ? sanitized.data.text : "";
@@ -448,8 +447,10 @@ function parseQueueLine(line) {
448
447
  date: parsed?.[1],
449
448
  text,
450
449
  confidence: confidence ? Number.parseFloat(confidence[1]) : undefined,
451
- machine,
452
- model,
450
+ machine: source?.machine,
451
+ model: source?.model,
452
+ provenance: source ?? undefined,
453
+ citation: citation ?? undefined,
453
454
  };
454
455
  }
455
456
  export function readReviewQueue(phrenPath, project) {
@@ -522,31 +523,252 @@ function writeQueueLines(file, lines) {
522
523
  fs.writeFileSync(tmp, content);
523
524
  fs.renameSync(tmp, file);
524
525
  }
525
- /** Remove a queue item's line from review.md (finding stays in FINDINGS.md). */
526
- export function approveQueueItem(phrenPath, project, lineText) {
526
+ /**
527
+ * Read-only lookup of a queue line. Returns the *stored* line (not the caller's
528
+ * approximation of it) so callers can read metadata comments the caller never had.
529
+ *
530
+ * Approve and reject both resolve the line first, act on FINDINGS.md second, and
531
+ * dequeue last. Dequeuing first — the old order — meant a failed content operation
532
+ * still destroyed the queue entry, which is how "approve" became a silent discard.
533
+ */
534
+ function locateQueueLine(phrenPath, project, lineText) {
535
+ const ensured = ensureProject(phrenPath, project);
536
+ if (!ensured.ok)
537
+ return forwardErr(ensured);
538
+ const file = queuePath(phrenPath, project);
539
+ if (!fs.existsSync(file))
540
+ return phrenErr(`No review queue found for "${project}".`, PhrenError.FILE_NOT_FOUND);
541
+ const lines = fs.readFileSync(file, "utf8").split("\n");
542
+ const idx = lines.findIndex((l) => l.trim() === lineText.trim());
543
+ if (idx === -1)
544
+ return phrenErr(`Queue item not found in "${project}".`, PhrenError.NOT_FOUND);
545
+ return phrenOk(lines[idx]);
546
+ }
547
+ /** Drop a queue line from review.md. */
548
+ function dequeueLine(phrenPath, project, lineText) {
527
549
  return withQueueLineOp(phrenPath, project, lineText, (lines, idx, file) => {
528
550
  lines.splice(idx, 1);
529
551
  writeQueueLines(file, lines);
530
- return phrenOk(`Approved queue item in ${project}`);
552
+ return phrenOk(undefined);
531
553
  });
532
554
  }
533
- /** Remove a queue item from review.md AND remove the corresponding finding from FINDINGS.md. */
534
- export function rejectQueueItem(phrenPath, project, lineText) {
535
- const lockResult = withQueueLineOp(phrenPath, project, lineText, (lines, idx, file) => {
536
- lines.splice(idx, 1);
537
- writeQueueLines(file, lines);
538
- return phrenOk("ok");
539
- });
540
- if (!lockResult.ok)
541
- return lockResult;
542
- const parsed = parseQueueLine(lineText);
543
- if (parsed.text) {
544
- const removeResult = removeFinding(phrenPath, project, parsed.text);
545
- if (!removeResult.ok) {
546
- return phrenOk(`Rejected queue item from ${project} (note: finding not found in FINDINGS.md — may have already been removed)`);
555
+ /** Does this text already exist as a live (non-archived) bullet in FINDINGS.md? */
556
+ function existsAsLiveFinding(phrenPath, project, text) {
557
+ const dir = safeProjectPath(phrenPath, project);
558
+ if (!dir)
559
+ return false;
560
+ const findingsPath = path.join(dir, FINDINGS_FILENAME);
561
+ if (!fs.existsSync(findingsPath))
562
+ return false;
563
+ const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
564
+ const active = collectFindingBulletLines(lines).filter(({ archived }) => !archived);
565
+ const match = findMatchingFindingBullet(active, normalizeFindingText(text), text);
566
+ // "ambiguous" means several bullets matched — it is still present, just not uniquely
567
+ // addressable, so approve must not write yet another copy.
568
+ return match.kind === "found" || match.kind === "ambiguous";
569
+ }
570
+ /**
571
+ * Find a queue item's content in the project's `reference/` tier.
572
+ *
573
+ * `autoArchiveToReference` moves findings out of FINDINGS.md into
574
+ * `reference/topics/*.md` once a project exceeds the findings cap, without touching
575
+ * the review queue lines that point at them. Those queue items are the reason
576
+ * approve and reject used to be no-ops, so both verbs have to look here.
577
+ */
578
+ function findArchivedReferenceMatches(phrenPath, project, text) {
579
+ const referenceDir = safeProjectPath(phrenPath, project, "reference");
580
+ if (!referenceDir || !fs.existsSync(referenceDir))
581
+ return [];
582
+ const needle = normalizeFindingText(text);
583
+ if (!needle)
584
+ return [];
585
+ const topicsDir = path.join(referenceDir, "topics") + path.sep;
586
+ const exact = [];
587
+ const partial = [];
588
+ for (const filePath of walkDirectory(referenceDir)) {
589
+ const lines = fs.readFileSync(filePath, "utf8").split("\n");
590
+ for (let i = 0; i < lines.length; i++) {
591
+ if (!lines[i].startsWith("- "))
592
+ continue;
593
+ const normalized = normalizeFindingText(lines[i]);
594
+ if (!normalized)
595
+ continue;
596
+ const hit = {
597
+ file: filePath,
598
+ autoArchived: filePath.startsWith(topicsDir),
599
+ idx: i,
600
+ line: lines[i],
601
+ };
602
+ if (normalized === needle)
603
+ exact.push(hit);
604
+ else if (normalized.includes(needle))
605
+ partial.push(hit);
606
+ }
607
+ }
608
+ return exact.length > 0 ? exact : partial;
609
+ }
610
+ /** Bullet content of archived matches, ignoring metadata — used to detect true ambiguity. */
611
+ function archivedMatchesAreIdentical(matches) {
612
+ const first = bulletContentKey(matches[0].line);
613
+ return matches.every(({ line }) => bulletContentKey(line) === first);
614
+ }
615
+ /**
616
+ * Approve a queue item: make it real, then dequeue.
617
+ *
618
+ * Three outcomes, because a queue line can point at three different realities:
619
+ *
620
+ * - `promoted` — the text is not in FINDINGS.md, so approving *writes* it. This is the
621
+ * case for every extraction candidate that scored below `autoAcceptThreshold`:
622
+ * extraction queues those without ever adding them, so the old "just splice the line
623
+ * out" behaviour silently discarded them. Promotion goes through `addFindingToFile`,
624
+ * the same path a direct add uses, so dedup, fid assignment, citation metadata, and
625
+ * the findings-cap auto-archive all behave identically.
626
+ * - `already_present` — the text is already a live finding (govern queues existing
627
+ * findings for Stale/Conflicts review). Approving means "keep it"; just dequeue.
628
+ * - `already_archived` — the content only exists in `reference/topics/`, because
629
+ * auto-archive moved it after it was queued. It is still live for retrieval, so the
630
+ * archive is left untouched and the item is dequeued.
631
+ */
632
+ export function approveQueueItemDetailed(phrenPath, project, lineText) {
633
+ const located = locateQueueLine(phrenPath, project, lineText);
634
+ if (!located.ok)
635
+ return forwardErr(located);
636
+ const parsed = parseQueueLine(located.data);
637
+ const text = parsed.text;
638
+ if (!text) {
639
+ // Nothing usable to promote — dequeue so the malformed line stops blocking the queue.
640
+ const dequeued = dequeueLine(phrenPath, project, lineText);
641
+ if (!dequeued.ok)
642
+ return forwardErr(dequeued);
643
+ appendAuditLog(phrenPath, "review_approve", `project=${project} outcome=empty`);
644
+ return phrenOk({
645
+ outcome: "already_present",
646
+ message: `Approved queue item in ${project} (empty entry, nothing to promote)`,
647
+ text: "",
648
+ });
649
+ }
650
+ const finish = (outcome, message) => {
651
+ const dequeued = dequeueLine(phrenPath, project, lineText);
652
+ if (!dequeued.ok)
653
+ return forwardErr(dequeued);
654
+ appendAuditLog(phrenPath, "review_approve", `project=${project} outcome=${outcome}`);
655
+ return phrenOk({ outcome, message, text });
656
+ };
657
+ if (existsAsLiveFinding(phrenPath, project, text)) {
658
+ return finish("already_present", `Approved queue item in ${project} (already in ${FINDINGS_FILENAME}; kept as-is)`);
659
+ }
660
+ const archived = findArchivedReferenceMatches(phrenPath, project, text);
661
+ if (archived.length > 0) {
662
+ return finish("already_archived", `Approved queue item in ${project} (already archived to ${path.basename(archived[0].file)}; still available for retrieval, archive left untouched)`);
663
+ }
664
+ // Not anywhere: this queue line IS the only copy. Write it as a finding, preserving
665
+ // the entry's type tag (carried in the text) and its capture provenance.
666
+ const citationInput = parsed.citation
667
+ ? {
668
+ ...(parsed.citation.repo ? { repo: parsed.citation.repo } : {}),
669
+ ...(parsed.citation.file ? { file: parsed.citation.file } : {}),
670
+ ...(parsed.citation.line !== undefined ? { line: parsed.citation.line } : {}),
671
+ ...(parsed.citation.commit ? { commit: parsed.citation.commit } : {}),
547
672
  }
673
+ : undefined;
674
+ // The queue entry's own date is the day the observation was captured; the finding is
675
+ // written today, so keep the original date as an explicit annotation rather than
676
+ // losing it.
677
+ const extraAnnotations = parsed.date ? [`<!-- phren:queued "${parsed.date}" -->`] : undefined;
678
+ const added = addFindingToFile(phrenPath, project, text, citationInput, {
679
+ ...(parsed.provenance ? { provenance: parsed.provenance } : {}),
680
+ ...(parsed.provenance?.session_id ? { sessionId: parsed.provenance.session_id } : {}),
681
+ ...(extraAnnotations ? { extraAnnotations } : {}),
682
+ });
683
+ if (!added.ok)
684
+ return forwardErr(added);
685
+ // A fuzzy-dedup skip means an equivalent finding already exists — the item is
686
+ // effectively already present, not newly promoted.
687
+ if (added.data.status === "skipped") {
688
+ return finish("already_present", `Approved queue item in ${project} (equivalent finding already in ${FINDINGS_FILENAME}; not duplicated)`);
548
689
  }
549
- return phrenOk(`Rejected and removed queue item from ${project}`);
690
+ return finish("promoted", `Approved and promoted queue item to ${FINDINGS_FILENAME} in ${project}`);
691
+ }
692
+ /** Remove a queue item's line from review.md, promoting it to a finding when needed. */
693
+ export function approveQueueItem(phrenPath, project, lineText) {
694
+ const result = approveQueueItemDetailed(phrenPath, project, lineText);
695
+ return result.ok ? phrenOk(result.data.message) : result;
696
+ }
697
+ /**
698
+ * Reject a queue item: destroy the content wherever it actually lives, then dequeue.
699
+ *
700
+ * Rejection removes from the live FINDINGS.md tier *and* from `reference/topics/*.md`,
701
+ * because auto-archive moves findings there without reconciling their queue lines and
702
+ * archived content is still injected into agent prompts. Leaving it would make reject a
703
+ * lie — the hosts tell users rejection removes the finding permanently.
704
+ *
705
+ * Two situations deliberately do NOT succeed quietly:
706
+ * - the content sits in a FINDINGS.md archive block (`<details>` / `phren:archive`),
707
+ * which the rest of the codebase treats as read-only history; and
708
+ * - several *different* bullets match, so deleting one would be a guess.
709
+ *
710
+ * Both return an error and leave the queue line in place, so the user sees the problem
711
+ * instead of a success message over undeleted content.
712
+ */
713
+ export function rejectQueueItemDetailed(phrenPath, project, lineText) {
714
+ const located = locateQueueLine(phrenPath, project, lineText);
715
+ if (!located.ok)
716
+ return forwardErr(located);
717
+ const parsed = parseQueueLine(located.data);
718
+ const text = parsed.text;
719
+ const finish = (outcome, message) => {
720
+ const dequeued = dequeueLine(phrenPath, project, lineText);
721
+ if (!dequeued.ok)
722
+ return forwardErr(dequeued);
723
+ appendAuditLog(phrenPath, "review_reject", `project=${project} outcome=${outcome}`);
724
+ return phrenOk({ outcome, message, text });
725
+ };
726
+ if (!text)
727
+ return finish("discarded", `Rejected queue item from ${project} (empty entry)`);
728
+ const removed = removeFinding(phrenPath, project, text);
729
+ if (removed.ok) {
730
+ return finish("removed", `Rejected and removed finding from ${FINDINGS_FILENAME} in ${project}`);
731
+ }
732
+ // Anything other than "it isn't there" is a real problem — an ambiguous match, a
733
+ // read-only FINDINGS.md archive block, a lock timeout. Surface it and keep the queue
734
+ // line so the user can act on it, rather than reporting success over live content.
735
+ if (removed.code !== PhrenError.NOT_FOUND && removed.code !== PhrenError.FILE_NOT_FOUND) {
736
+ return forwardErr(removed);
737
+ }
738
+ const matches = findArchivedReferenceMatches(phrenPath, project, text);
739
+ if (matches.length === 0) {
740
+ return finish("discarded", `Rejected and discarded queue item from ${project} (candidate was never added to ${FINDINGS_FILENAME}; nothing to remove)`);
741
+ }
742
+ const external = matches.filter((match) => !match.autoArchived);
743
+ if (external.length > 0) {
744
+ return phrenErr(`Cannot reject: "${text.slice(0, 60)}" lives in ${path.relative(phrenPath, external[0].file)}, which phren does not auto-manage. Remove it there, then reject again.`, PhrenError.VALIDATION_ERROR);
745
+ }
746
+ if (matches.length > 1 && !archivedMatchesAreIdentical(matches)) {
747
+ return phrenErr(`Cannot reject: "${text.slice(0, 60)}" matches ${matches.length} different archived entries. Remove the right one manually, then reject again.`, PhrenError.AMBIGUOUS_MATCH);
748
+ }
749
+ const target = matches[0];
750
+ const purge = withSafeLock(target.file, () => {
751
+ const lines = fs.readFileSync(target.file, "utf8").split("\n");
752
+ // Re-resolve under the lock — the file may have moved since the scan.
753
+ const idx = lines[target.idx] === target.line ? target.idx : lines.indexOf(target.line);
754
+ if (idx === -1)
755
+ return phrenErr(`Archived entry vanished from ${path.basename(target.file)} before it could be removed.`, PhrenError.NOT_FOUND);
756
+ const removeCount = isCitationLine(lines[idx + 1] || "") ? 2 : 1;
757
+ lines.splice(idx, removeCount);
758
+ const normalized = lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
759
+ const tmp = `${target.file}.tmp.${process.pid}`;
760
+ fs.writeFileSync(tmp, normalized);
761
+ fs.renameSync(tmp, target.file);
762
+ return phrenOk(undefined);
763
+ });
764
+ if (!purge.ok)
765
+ return forwardErr(purge);
766
+ return finish("removed_from_archive", `Rejected and removed archived finding from reference/topics/${path.basename(target.file)} in ${project}`);
767
+ }
768
+ /** Remove a queue item from review.md AND the corresponding finding wherever it lives. */
769
+ export function rejectQueueItem(phrenPath, project, lineText) {
770
+ const result = rejectQueueItemDetailed(phrenPath, project, lineText);
771
+ return result.ok ? phrenOk(result.data.message) : result;
550
772
  }
551
773
  /** Edit a queue item's text in review.md and the corresponding finding in FINDINGS.md. */
552
774
  export function editQueueItem(phrenPath, project, lineText, newText) {
@@ -2,7 +2,7 @@ import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import { errorMessage } from "./utils.js";
4
4
  import { logger } from "./logger.js";
5
- import { defaultPhrenPath, expandHomePath, getPhrenPath, readRootManifest, } from "./shared.js";
5
+ import { defaultPhrenPath, ensureFtsCacheRootPrivate, expandHomePath, getPhrenPath, readRootManifest, } from "./shared.js";
6
6
  import { resolveRuntimeProfile } from "./runtime-profile.js";
7
7
  import { VERSION } from "./package-metadata.js";
8
8
  import { TOPIC_ORDER, helpTopicNames, lookupCommand, } from "./cli-registry.js";
@@ -127,6 +127,10 @@ export async function runTopLevelCommand(argv, opts = {}) {
127
127
  const cmd = lookupCommand(argvCommand);
128
128
  if (!cmd)
129
129
  return false;
130
+ // Any command can end up building or reading the FTS snapshot cache, which
131
+ // is a SQLite export of the whole store landing in os.tmpdir() — /tmp (1777)
132
+ // on Linux and WSL. Harden the per-user cache root before the command runs.
133
+ ensureFtsCacheRootPrivate();
130
134
  // Intercept before any handler runs - in particular before namespace
131
135
  // handlers that used to print their own per-subcommand help text.
132
136
  if (argv.includes("--help") || argv.includes("-h")) {