@phren/cli 0.2.15 → 0.3.0

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 (392) hide show
  1. package/README.md +2 -2
  2. package/dist/agent-instructions.d.ts +12 -0
  3. package/dist/agent-instructions.js +52 -0
  4. package/dist/bridge/agent-hook-stores.d.ts +32 -0
  5. package/dist/bridge/agent-hook-stores.js +67 -0
  6. package/dist/bridge/agent-hooks.d.ts +195 -2
  7. package/dist/bridge/agent-hooks.js +1049 -38
  8. package/dist/bridge/canary.d.ts +27 -0
  9. package/dist/bridge/canary.js +189 -0
  10. package/dist/bridge/changes.d.ts +57 -0
  11. package/dist/bridge/changes.js +403 -0
  12. package/dist/bridge/client.d.ts +3 -0
  13. package/dist/bridge/client.js +36 -0
  14. package/dist/bridge/code-note.d.ts +23 -0
  15. package/dist/bridge/code-note.js +51 -0
  16. package/dist/bridge/code-routes.d.ts +151 -0
  17. package/dist/bridge/code-routes.js +442 -0
  18. package/dist/bridge/codex-threads.d.ts +27 -0
  19. package/dist/bridge/codex-threads.js +442 -0
  20. package/dist/bridge/command.d.ts +7 -0
  21. package/dist/bridge/command.js +50 -5
  22. package/dist/bridge/computer-names.d.ts +4 -0
  23. package/dist/bridge/computer-names.js +16 -0
  24. package/dist/bridge/computers.d.ts +9 -0
  25. package/dist/bridge/computers.js +111 -0
  26. package/dist/bridge/context.d.ts +14 -0
  27. package/dist/bridge/context.js +149 -0
  28. package/dist/bridge/dispatch-command.d.ts +3 -0
  29. package/dist/bridge/dispatch-command.js +93 -0
  30. package/dist/bridge/dispatch-hosts.d.ts +23 -0
  31. package/dist/bridge/dispatch-hosts.js +25 -0
  32. package/dist/bridge/dispatch-returns.d.ts +125 -0
  33. package/dist/bridge/dispatch-returns.js +283 -0
  34. package/dist/bridge/dispatch-tree.d.ts +54 -0
  35. package/dist/bridge/dispatch-tree.js +198 -0
  36. package/dist/bridge/dispatch.d.ts +210 -0
  37. package/dist/bridge/dispatch.js +286 -0
  38. package/dist/bridge/enroll.d.ts +31 -0
  39. package/dist/bridge/enroll.js +236 -0
  40. package/dist/bridge/fanout-messages.d.ts +74 -0
  41. package/dist/bridge/fanout-messages.js +230 -0
  42. package/dist/bridge/fanouts.d.ts +160 -0
  43. package/dist/bridge/fanouts.js +702 -0
  44. package/dist/bridge/file-range.d.ts +16 -0
  45. package/dist/bridge/file-range.js +90 -0
  46. package/dist/bridge/files.d.ts +20 -0
  47. package/dist/bridge/files.js +54 -0
  48. package/dist/bridge/git-publish.d.ts +23 -0
  49. package/dist/bridge/git-publish.js +145 -0
  50. package/dist/bridge/git-worktrees.d.ts +21 -0
  51. package/dist/bridge/git-worktrees.js +150 -0
  52. package/dist/bridge/git.d.ts +54 -0
  53. package/dist/bridge/git.js +552 -0
  54. package/dist/bridge/grants.d.ts +31 -0
  55. package/dist/bridge/grants.js +181 -0
  56. package/dist/bridge/hand-off.d.ts +79 -0
  57. package/dist/bridge/hand-off.js +151 -0
  58. package/dist/bridge/health.d.ts +128 -0
  59. package/dist/bridge/health.js +260 -0
  60. package/dist/bridge/herdr.d.ts +79 -6
  61. package/dist/bridge/herdr.js +292 -27
  62. package/dist/bridge/hook-main.js +2 -0
  63. package/dist/bridge/install.d.ts +28 -1
  64. package/dist/bridge/install.js +225 -38
  65. package/dist/bridge/launch-worktree.d.ts +21 -0
  66. package/dist/bridge/launch-worktree.js +70 -0
  67. package/dist/bridge/limits.d.ts +20 -0
  68. package/dist/bridge/limits.js +65 -0
  69. package/dist/bridge/locate.d.ts +16 -0
  70. package/dist/bridge/locate.js +75 -0
  71. package/dist/bridge/metrics.d.ts +29 -0
  72. package/dist/bridge/metrics.js +71 -0
  73. package/dist/bridge/model-switch.d.ts +35 -0
  74. package/dist/bridge/model-switch.js +250 -0
  75. package/dist/bridge/models.d.ts +46 -0
  76. package/dist/bridge/models.js +257 -0
  77. package/dist/bridge/opencode-approvals.d.ts +6 -0
  78. package/dist/bridge/opencode-approvals.js +60 -0
  79. package/dist/bridge/pane-text.d.ts +15 -0
  80. package/dist/bridge/pane-text.js +23 -0
  81. package/dist/bridge/peers.d.ts +27 -0
  82. package/dist/bridge/peers.js +130 -0
  83. package/dist/bridge/projects.d.ts +12 -1
  84. package/dist/bridge/projects.js +268 -20
  85. package/dist/bridge/protocol.d.ts +35 -2
  86. package/dist/bridge/protocol.js +61 -7
  87. package/dist/bridge/push.d.ts +83 -0
  88. package/dist/bridge/push.js +199 -0
  89. package/dist/bridge/questions.d.ts +38 -0
  90. package/dist/bridge/questions.js +205 -0
  91. package/dist/bridge/schedule-format.d.ts +103 -0
  92. package/dist/bridge/schedule-format.js +266 -0
  93. package/dist/bridge/schedule-launch.d.ts +11 -0
  94. package/dist/bridge/schedule-launch.js +169 -0
  95. package/dist/bridge/schedule-watch.d.ts +54 -0
  96. package/dist/bridge/schedule-watch.js +255 -0
  97. package/dist/bridge/schedules.d.ts +48 -0
  98. package/dist/bridge/schedules.js +205 -0
  99. package/dist/bridge/server-launch.d.ts +14 -0
  100. package/dist/bridge/server-launch.js +218 -0
  101. package/dist/bridge/server-overview.d.ts +45 -0
  102. package/dist/bridge/server-overview.js +102 -0
  103. package/dist/bridge/server-pane-routes.d.ts +36 -0
  104. package/dist/bridge/server-pane-routes.js +479 -0
  105. package/dist/bridge/server-routes.d.ts +108 -0
  106. package/dist/bridge/server-routes.js +556 -0
  107. package/dist/bridge/server-stream.d.ts +46 -0
  108. package/dist/bridge/server-stream.js +253 -0
  109. package/dist/bridge/server.d.ts +3 -15
  110. package/dist/bridge/server.js +162 -264
  111. package/dist/bridge/session-servers.d.ts +24 -0
  112. package/dist/bridge/session-servers.js +136 -0
  113. package/dist/bridge/side-questions.d.ts +74 -0
  114. package/dist/bridge/side-questions.js +252 -0
  115. package/dist/bridge/simulators.d.ts +28 -0
  116. package/dist/bridge/simulators.js +198 -0
  117. package/dist/bridge/speech-transcribe.d.ts +24 -0
  118. package/dist/bridge/speech-transcribe.js +124 -0
  119. package/dist/bridge/speech.d.ts +35 -0
  120. package/dist/bridge/speech.js +98 -0
  121. package/dist/bridge/steps.d.ts +13 -0
  122. package/dist/bridge/steps.js +222 -0
  123. package/dist/bridge/tab-activity.d.ts +18 -0
  124. package/dist/bridge/tab-activity.js +99 -0
  125. package/dist/bridge/terminal-choice.d.ts +64 -0
  126. package/dist/bridge/terminal-choice.js +281 -0
  127. package/dist/bridge/transcript-claude.d.ts +22 -0
  128. package/dist/bridge/transcript-claude.js +353 -0
  129. package/dist/bridge/transcript-codex.d.ts +30 -0
  130. package/dist/bridge/transcript-codex.js +282 -0
  131. package/dist/bridge/transcript-copilot.d.ts +4 -0
  132. package/dist/bridge/transcript-copilot.js +14 -0
  133. package/dist/bridge/transcript-opencode.d.ts +5 -0
  134. package/dist/bridge/transcript-opencode.js +26 -0
  135. package/dist/bridge/transcript-preview.d.ts +96 -0
  136. package/dist/bridge/transcript-preview.js +491 -0
  137. package/dist/bridge/transcripts.d.ts +81 -4
  138. package/dist/bridge/transcripts.js +332 -67
  139. package/dist/bridge/transport.d.ts +3 -0
  140. package/dist/bridge/transport.js +96 -15
  141. package/dist/bridge/uploads.d.ts +15 -0
  142. package/dist/bridge/uploads.js +44 -2
  143. package/dist/bridge/usage.d.ts +124 -0
  144. package/dist/bridge/usage.js +859 -0
  145. package/dist/bridge-hook.mjs +46545 -21051
  146. package/dist/cli/actions.js +14 -1
  147. package/dist/cli/config-policy.js +25 -0
  148. package/dist/cli/config-proactivity.d.ts +3 -1
  149. package/dist/cli/config-proactivity.js +35 -3
  150. package/dist/cli/config.js +4 -1
  151. package/dist/cli/extract.d.ts +0 -8
  152. package/dist/cli/extract.js +4 -7
  153. package/dist/cli/govern.js +5 -2
  154. package/dist/cli/hooks-globs.js +1 -1
  155. package/dist/cli/hooks.d.ts +1 -1
  156. package/dist/cli/hooks.js +9 -7
  157. package/dist/cli/namespaces-projects.js +12 -6
  158. package/dist/cli/namespaces-store.js +37 -6
  159. package/dist/cli/namespaces-tasks.js +1 -1
  160. package/dist/cli/schedules.d.ts +1 -0
  161. package/dist/cli/schedules.js +164 -0
  162. package/dist/cli/session-background.js +1 -1
  163. package/dist/cli/session-git.d.ts +8 -5
  164. package/dist/cli/session-git.js +45 -120
  165. package/dist/cli/session-start.js +3 -1
  166. package/dist/cli/session-stop.js +19 -8
  167. package/dist/cli/team.js +13 -10
  168. package/dist/cli-handlers.d.ts +1 -1
  169. package/dist/cli-handlers.js +8 -4
  170. package/dist/cli-help.d.ts +5 -4
  171. package/dist/cli-help.js +15 -15
  172. package/dist/cli-registry.d.ts +4 -1
  173. package/dist/cli-registry.js +119 -6
  174. package/dist/content/archive.js +2 -2
  175. package/dist/content/citation.d.ts +11 -0
  176. package/dist/content/citation.js +18 -0
  177. package/dist/content/learning.js +2 -0
  178. package/dist/content/summarize.d.ts +14 -15
  179. package/dist/content/summarize.js +60 -5
  180. package/dist/content/validate.d.ts +17 -4
  181. package/dist/content/validate.js +200 -122
  182. package/dist/core/project-registry.d.ts +26 -0
  183. package/dist/core/project-registry.js +573 -0
  184. package/dist/core/project.js +2 -3
  185. package/dist/data/access.d.ts +16 -1
  186. package/dist/data/access.js +31 -3
  187. package/dist/data/tasks.d.ts +18 -3
  188. package/dist/data/tasks.js +8 -7
  189. package/dist/entrypoint.js +44 -10
  190. package/dist/fanout/adapters/claude.d.ts +2 -0
  191. package/dist/fanout/adapters/claude.js +7 -0
  192. package/dist/fanout/adapters/codex.d.ts +2 -0
  193. package/dist/fanout/adapters/codex.js +9 -0
  194. package/dist/fanout/adapters/opencode.d.ts +4 -0
  195. package/dist/fanout/adapters/opencode.js +9 -0
  196. package/dist/fanout/adapters/types.d.ts +21 -0
  197. package/dist/fanout/adapters/types.js +3 -0
  198. package/dist/fanout/command.d.ts +2 -0
  199. package/dist/fanout/command.js +78 -0
  200. package/dist/fanout/launcher.d.ts +27 -0
  201. package/dist/fanout/launcher.js +156 -0
  202. package/dist/fanout/opencode-serve.d.ts +24 -0
  203. package/dist/fanout/opencode-serve.js +191 -0
  204. package/dist/fanout/picker.d.ts +91 -0
  205. package/dist/fanout/picker.js +51 -0
  206. package/dist/fanout/usage.d.ts +5 -0
  207. package/dist/fanout/usage.js +51 -0
  208. package/dist/fanout/watchdog.d.ts +10 -0
  209. package/dist/fanout/watchdog.js +27 -0
  210. package/dist/filenames.d.ts +9 -0
  211. package/dist/filenames.js +11 -0
  212. package/dist/finding/context.js +4 -22
  213. package/dist/generated/memory-ui-graph.browser.js +525 -419
  214. package/dist/governance/policy-constants.d.ts +11 -0
  215. package/dist/governance/policy-constants.js +9 -0
  216. package/dist/governance/policy.d.ts +5 -8
  217. package/dist/governance/policy.js +11 -8
  218. package/dist/graph-core/camera.d.ts +24 -0
  219. package/dist/graph-core/camera.js +18 -0
  220. package/dist/graph-core/index.d.ts +2 -0
  221. package/dist/graph-core/index.js +2 -0
  222. package/dist/graph-core/labels.d.ts +77 -0
  223. package/dist/graph-core/labels.js +124 -0
  224. package/dist/graph-core/model.d.ts +13 -0
  225. package/dist/graph-core/model.js +33 -0
  226. package/dist/graph-core/types.d.ts +2 -0
  227. package/dist/home-paths.d.ts +7 -0
  228. package/dist/home-paths.js +21 -0
  229. package/dist/hooks.d.ts +3 -15
  230. package/dist/hooks.js +14 -1
  231. package/dist/index.js +24 -2
  232. package/dist/init/guard-globals.d.ts +1 -1
  233. package/dist/init/guard-globals.js +4 -4
  234. package/dist/init/init-configure.js +3 -3
  235. package/dist/init/init-uninstall.js +15 -5
  236. package/dist/init/init-walkthrough.js +1 -1
  237. package/dist/init/init.js +26 -6
  238. package/dist/init/management-preset.d.ts +1 -1
  239. package/dist/init/management-preset.js +2 -2
  240. package/dist/init/preferences.js +1 -1
  241. package/dist/init/self-wiring.js +1 -1
  242. package/dist/init/setup.d.ts +3 -26
  243. package/dist/init/setup.js +68 -593
  244. package/dist/init/shared.js +2 -0
  245. package/dist/init/store-gitignore.d.ts +1 -6
  246. package/dist/init/store-gitignore.js +2 -8
  247. package/dist/init/teardown.d.ts +1 -1
  248. package/dist/init/teardown.js +2 -2
  249. package/dist/link/context-imports.d.ts +15 -0
  250. package/dist/link/context-imports.js +101 -0
  251. package/dist/link/context.js +1 -1
  252. package/dist/link/doctor.d.ts +22 -1
  253. package/dist/link/doctor.js +128 -58
  254. package/dist/link/link.js +29 -61
  255. package/dist/link/refresh.js +2 -2
  256. package/dist/link/skills.js +26 -5
  257. package/dist/machine-identity.d.ts +3 -0
  258. package/dist/machine-identity.js +6 -0
  259. package/dist/mcp/profile.d.ts +2 -19
  260. package/dist/mcp/profile.js +64 -22
  261. package/dist/memory-ui-graph.runtime.js +525 -419
  262. package/dist/modules/code-package.d.ts +16 -0
  263. package/dist/modules/code-package.js +160 -0
  264. package/dist/modules/command.d.ts +2 -0
  265. package/dist/modules/command.js +67 -0
  266. package/dist/modules/config.d.ts +4 -0
  267. package/dist/modules/config.js +70 -0
  268. package/dist/modules/manifest.d.ts +41 -0
  269. package/dist/modules/manifest.js +1 -0
  270. package/dist/modules/provision.d.ts +3 -0
  271. package/dist/modules/provision.js +84 -0
  272. package/dist/modules/registry.d.ts +16 -0
  273. package/dist/modules/registry.js +250 -0
  274. package/dist/modules/runtime.d.ts +15 -0
  275. package/dist/modules/runtime.js +59 -0
  276. package/dist/package-metadata.js +10 -2
  277. package/dist/phren-dotenv.js +4 -2
  278. package/dist/phren-paths.d.ts +3 -2
  279. package/dist/phren-paths.js +4 -5
  280. package/dist/profile-store.js +43 -8
  281. package/dist/project-config.d.ts +19 -1
  282. package/dist/project-config.js +29 -3
  283. package/dist/project-topics.d.ts +1 -0
  284. package/dist/project-topics.js +13 -10
  285. package/dist/provider-adapters.js +1 -4
  286. package/dist/query-correlation.js +6 -6
  287. package/dist/session/artifacts.js +5 -5
  288. package/dist/session/checkpoints.js +5 -0
  289. package/dist/session/utils.d.ts +2 -2
  290. package/dist/session/utils.js +6 -6
  291. package/dist/shared/content.d.ts +1 -1
  292. package/dist/shared/content.js +1 -1
  293. package/dist/shared/data-utils.js +1 -1
  294. package/dist/shared/fragment-graph.d.ts +1 -1
  295. package/dist/shared/fragment-graph.js +5 -5
  296. package/dist/shared/index.js +48 -7
  297. package/dist/shared/retrieval.d.ts +18 -3
  298. package/dist/shared/retrieval.js +101 -12
  299. package/dist/shared/search-fallback.js +4 -6
  300. package/dist/shared/sqljs.d.ts +2 -0
  301. package/dist/shared/sqljs.js +4 -2
  302. package/dist/shared.d.ts +0 -1
  303. package/dist/shared.js +0 -1
  304. package/dist/shell/input.d.ts +1 -5
  305. package/dist/shell/input.js +16 -10
  306. package/dist/shell/palette.d.ts +2 -2
  307. package/dist/shell/palette.js +3 -7
  308. package/dist/shell/render.d.ts +3 -1
  309. package/dist/shell/render.js +4 -4
  310. package/dist/shell/shell.js +4 -1
  311. package/dist/shell/types.d.ts +1 -0
  312. package/dist/shell/types.js +4 -0
  313. package/dist/shell/view.d.ts +0 -4
  314. package/dist/shell/view.js +19 -27
  315. package/dist/skill/registry.js +25 -17
  316. package/dist/skill/state.d.ts +3 -0
  317. package/dist/skill/state.js +13 -7
  318. package/dist/status.js +38 -17
  319. package/dist/store-registry.d.ts +44 -18
  320. package/dist/store-registry.js +169 -60
  321. package/dist/store-weight.d.ts +1 -6
  322. package/dist/store-weight.js +4 -2
  323. package/dist/sync/auth-doctor.d.ts +8 -0
  324. package/dist/sync/auth-doctor.js +27 -0
  325. package/dist/sync/auth.d.ts +27 -0
  326. package/dist/sync/auth.js +114 -0
  327. package/dist/sync/conflict-resolve.d.ts +9 -0
  328. package/dist/sync/conflict-resolve.js +146 -0
  329. package/dist/sync/git-state.d.ts +4 -0
  330. package/dist/sync/git-state.js +49 -0
  331. package/dist/sync/outcome.d.ts +34 -0
  332. package/dist/sync/outcome.js +57 -0
  333. package/dist/sync/pull.d.ts +15 -7
  334. package/dist/sync/pull.js +84 -35
  335. package/dist/sync/store-merge.d.ts +29 -0
  336. package/dist/sync/store-merge.js +137 -0
  337. package/dist/sync/task-merge.d.ts +22 -0
  338. package/dist/sync/task-merge.js +158 -0
  339. package/dist/task/github.js +1 -1
  340. package/dist/task/lifecycle.d.ts +5 -0
  341. package/dist/task/lifecycle.js +67 -23
  342. package/dist/terminal-text.d.ts +5 -0
  343. package/dist/terminal-text.js +11 -0
  344. package/dist/test-global-setup.js +7 -0
  345. package/dist/tool-registry.d.ts +1 -1
  346. package/dist/tool-registry.js +3 -1
  347. package/dist/tools/code.d.ts +3 -0
  348. package/dist/tools/code.js +186 -0
  349. package/dist/tools/config.js +8 -0
  350. package/dist/tools/data.js +14 -7
  351. package/dist/tools/dispatch.d.ts +2 -0
  352. package/dist/tools/dispatch.js +66 -0
  353. package/dist/tools/finding.d.ts +11 -0
  354. package/dist/tools/finding.js +180 -123
  355. package/dist/tools/ops.js +5 -2
  356. package/dist/tools/search.js +21 -8
  357. package/dist/tools/session.js +21 -22
  358. package/dist/tools/tasks.js +8 -2
  359. package/dist/tools/types.d.ts +2 -2
  360. package/dist/tools/types.js +2 -2
  361. package/dist/ui/assets.js +1 -1
  362. package/dist/ui/data.js +14 -15
  363. package/dist/ui/deep-void.d.ts +1 -1
  364. package/dist/ui/deep-void.js +0 -1
  365. package/dist/ui/graph-chrome.d.ts +1 -1
  366. package/dist/ui/graph-chrome.js +51 -0
  367. package/dist/ui/page.js +5 -5
  368. package/dist/ui/scripts.js +67 -30
  369. package/dist/ui/server.js +52 -7
  370. package/dist/update.js +22 -11
  371. package/dist/utils-fts.js +1 -0
  372. package/dist/utils-helpers.d.ts +7 -0
  373. package/dist/utils-helpers.js +17 -0
  374. package/dist/utils.d.ts +1 -1
  375. package/dist/utils.js +1 -1
  376. package/package.json +49 -7
  377. package/plugins/opencode/phren-transcript.js +340 -0
  378. package/starter/README.md +4 -4
  379. package/starter/global/{CLAUDE.md → AGENTS.md} +2 -2
  380. package/starter/global/skills/conductor/SKILL.md +106 -0
  381. package/starter/global/skills/fanout/SKILL.md +20 -0
  382. package/starter/global/skills/phren-discover/SKILL.md +6 -6
  383. package/starter/global/skills/phren-init/SKILL.md +4 -4
  384. package/starter/global/skills/phren-sync/SKILL.md +3 -3
  385. package/starter/templates/frontend/reference/README.md +1 -1
  386. package/starter/templates/library/reference/README.md +1 -1
  387. package/starter/templates/monorepo/reference/README.md +1 -1
  388. package/starter/templates/python-project/reference/README.md +1 -1
  389. /package/starter/templates/frontend/{CLAUDE.md → AGENTS.md} +0 -0
  390. /package/starter/templates/library/{CLAUDE.md → AGENTS.md} +0 -0
  391. /package/starter/templates/monorepo/{CLAUDE.md → AGENTS.md} +0 -0
  392. /package/starter/templates/python-project/{CLAUDE.md → AGENTS.md} +0 -0
@@ -1,3 +1,6 @@
1
+ import { nonInteractiveGitEnv } from "../utils-helpers.js";
2
+ import { moduleEnabled, moduleSnapshot } from "../modules/runtime.js";
3
+ import { skillEnabled, reconcileStarterSkills, starterInstructions } from "../modules/provision.js";
1
4
  /**
2
5
  * Governance files, root file migration, verification, starter templates, bootstrap.
3
6
  */
@@ -6,34 +9,42 @@ import * as path from "path";
6
9
  import * as os from "os";
7
10
  import * as yaml from "js-yaml";
8
11
  import { loadYamlDocument } from "../phren-core.js";
9
- import { atomicWriteText, debugLog, findProjectNameCaseInsensitive, findProjectNamesByCanonicalKey, projectSlugFromPath, hookConfigPath, EXEC_TIMEOUT_QUICK_MS, readRootManifest, sessionsDir, runtimeHealthFile, isRecord, } from "../shared.js";
12
+ import { atomicWriteText, debugLog, hookConfigPath, EXEC_TIMEOUT_QUICK_MS, readRootManifest, sessionsDir, runtimeHealthFile, isRecord, } from "../shared.js";
10
13
  import { ensurePrivateDir, homePath } from "../phren-paths.js";
11
14
  import { isLiveForeignPhrenRoot, phrenRootFromGlobalClaudeLink } from "./guard-globals.js";
12
15
  import { resolveWorktreeParent } from "../git-worktree.js";
13
- import { addProjectToProfile, listProfiles, resolveActiveProfile, setMachineProfile } from "../profile-store.js";
16
+ import { listProfiles, resolveActiveProfile, setMachineProfile } from "../profile-store.js";
14
17
  import { getMachineName } from "../machine-identity.js";
15
18
  import { execFileSync } from "child_process";
16
19
  import { GOVERNANCE_SCHEMA_VERSION, } from "../shared/governance.js";
17
- import { STOP_WORDS, errorMessage } from "../utils.js";
20
+ import { errorMessage } from "../utils.js";
18
21
  import { ROOT, STARTER_DIR, VERSION, resolveEntryScript, commandVersion, versionAtLeast, nearestWritableTarget } from "./shared.js";
19
22
  import { readInstallPreferences } from "./preferences.js";
20
23
  import { getManagementPreset, resolveManagementCapabilities, } from "./management-preset.js";
21
24
  import { TASKS_FILENAME } from "../data/tasks.js";
22
- import { FINDINGS_FILENAME } from "../data/access.js";
23
- import { getProjectOwnershipDefault, parseProjectOwnershipMode, readProjectConfig, writeProjectConfig, } from "../project-config.js";
24
- import { getBuiltinTopicConfig, normalizeBuiltinTopicDomain } from "../project-topics.js";
25
25
  import { writeSkillMd } from "../link/skills.js";
26
26
  import { syncScopeSkillsToDir } from "../skill/files.js";
27
27
  import { detectInstalledTools } from "../hooks.js";
28
28
  import { logger } from "../logger.js";
29
+ import { migrateStoreAgentInstructions } from "../agent-instructions.js";
30
+ import { bootstrapFromExisting, ensureProjectScaffold, inferInitScaffoldFromRepo, } from "../core/project-registry.js";
31
+ export { bootstrapFromExisting, ensureProjectScaffold, inferInitScaffoldFromRepo, };
29
32
  const LEGACY_SAMPLE_PROJECTS = new Set(["my-api", "my-frontend"]);
30
33
  function normalizeProjects(raw) {
31
34
  if (!Array.isArray(raw))
32
35
  return [];
33
36
  return raw.map((entry) => String(entry));
34
37
  }
35
- function profileLooksRealProject(project) {
36
- return project === "global" || !LEGACY_SAMPLE_PROJECTS.has(project);
38
+ /**
39
+ * The sample names are also ordinary repo names, so the name alone is not
40
+ * evidence. phren stopped shipping the sample directories: an entry with no
41
+ * project directory in the store is the leftover sample, one with a directory
42
+ * is a real project.
43
+ */
44
+ function profileLooksRealProject(phrenPath, project) {
45
+ if (project === "global" || !LEGACY_SAMPLE_PROJECTS.has(project))
46
+ return true;
47
+ return fs.existsSync(path.join(phrenPath, project));
37
48
  }
38
49
  function pruneLegacySampleProjectsFromProfiles(phrenPath) {
39
50
  const profilesDir = path.join(phrenPath, "profiles");
@@ -50,7 +61,7 @@ function pruneLegacySampleProjectsFromProfiles(phrenPath) {
50
61
  if (!isRecord(parsed))
51
62
  continue;
52
63
  const originalProjects = normalizeProjects(parsed.projects);
53
- const nextProjects = originalProjects.filter(profileLooksRealProject);
64
+ const nextProjects = originalProjects.filter((project) => profileLooksRealProject(phrenPath, project));
54
65
  if (nextProjects.length === originalProjects.length)
55
66
  continue;
56
67
  removed += originalProjects.length - nextProjects.length;
@@ -158,17 +169,19 @@ function ensureGlobalStarterAssets(phrenPath) {
158
169
  return created;
159
170
  const targetGlobalDir = path.join(phrenPath, "global");
160
171
  fs.mkdirSync(targetGlobalDir, { recursive: true });
161
- const starterClaude = path.join(starterGlobal, "CLAUDE.md");
162
- const targetClaude = path.join(targetGlobalDir, "CLAUDE.md");
172
+ const starterClaude = path.join(starterGlobal, "AGENTS.md");
173
+ const targetClaude = path.join(targetGlobalDir, "AGENTS.md");
163
174
  if (fs.existsSync(starterClaude) && !fs.existsSync(targetClaude)) {
164
175
  fs.copyFileSync(starterClaude, targetClaude);
165
- created.push("global/CLAUDE.md");
176
+ created.push("global/AGENTS.md");
166
177
  }
167
178
  const starterSkillsDir = path.join(starterGlobal, "skills");
168
179
  const targetSkillsDir = path.join(targetGlobalDir, "skills");
169
180
  fs.mkdirSync(targetSkillsDir, { recursive: true });
170
181
  if (fs.existsSync(starterSkillsDir)) {
171
182
  for (const entry of fs.readdirSync(starterSkillsDir, { withFileTypes: true })) {
183
+ if (!skillEnabled(phrenPath, entry.name))
184
+ continue;
172
185
  const source = path.join(starterSkillsDir, entry.name);
173
186
  const target = path.join(targetSkillsDir, entry.name);
174
187
  if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -269,15 +282,14 @@ function ensureGeneratedSkillArtifacts(phrenPath, preferredHome) {
269
282
  }
270
283
  }
271
284
  const skillMdPath = path.join(phrenPath, "phren.SKILL.md");
272
- if (!fs.existsSync(skillMdPath)) {
273
- try {
274
- writeSkillMd(phrenPath);
275
- if (fs.existsSync(skillMdPath))
276
- created.push("phren.SKILL.md");
277
- }
278
- catch (err) {
279
- debugLog(`ensureGeneratedSkillArtifacts: writeSkillMd failed: ${errorMessage(err)}`);
280
- }
285
+ const hadSkillMd = fs.existsSync(skillMdPath);
286
+ try {
287
+ writeSkillMd(phrenPath);
288
+ if (!hadSkillMd && fs.existsSync(skillMdPath))
289
+ created.push("phren.SKILL.md");
290
+ }
291
+ catch (err) {
292
+ debugLog(`ensureGeneratedSkillArtifacts: writeSkillMd failed: ${errorMessage(err)}`);
281
293
  }
282
294
  return created;
283
295
  }
@@ -323,8 +335,11 @@ export function repairPreexistingInstall(phrenPath, opts) {
323
335
  // self-heal path resolves from stored preferences.
324
336
  const caps = opts?.caps ?? resolveManagementCapabilities(phrenPath);
325
337
  const preset = opts?.preset ?? getManagementPreset(phrenPath);
338
+ moduleSnapshot(phrenPath);
339
+ reconcileStarterSkills(phrenPath, STARTER_DIR);
326
340
  const createdGovernanceAssets = ensureGovernanceFiles(phrenPath);
327
- const createdGlobalAssets = ensureGlobalStarterAssets(phrenPath);
341
+ const migratedInstructions = migrateStoreAgentInstructions(phrenPath);
342
+ const createdGlobalAssets = [...migratedInstructions, ...ensureGlobalStarterAssets(phrenPath)];
328
343
  const createdRuntimeAssets = [...createdGovernanceAssets, ...ensureRuntimeAssets(phrenPath)];
329
344
  const createdFeatureDefaults = ensureDefaultFeatureFlags(phrenPath, preset);
330
345
  const profileRepair = pruneLegacySampleProjectsFromProfiles(phrenPath);
@@ -338,8 +353,10 @@ export function repairPreexistingInstall(phrenPath, opts) {
338
353
  return {
339
354
  profileFilesUpdated: profileRepair.filesUpdated,
340
355
  removedLegacyProjects: profileRepair.removed,
341
- createdContextFile: ensureGeneratedContextFile(preferredHome),
342
- createdRootMemory: ensureGeneratedRootMemory(preferredHome),
356
+ // Both live in the user's home, so they are self-heal surfaces: `assisted`
357
+ // and `manual` do not re-create them.
358
+ createdContextFile: caps.selfHeal ? ensureGeneratedContextFile(preferredHome) : false,
359
+ createdRootMemory: caps.selfHeal ? ensureGeneratedRootMemory(preferredHome) : false,
343
360
  createdGlobalAssets,
344
361
  createdRuntimeAssets,
345
362
  createdFeatureDefaults,
@@ -352,7 +369,7 @@ export function repairPreexistingInstall(phrenPath, opts) {
352
369
  * is missing or broken.
353
370
  *
354
371
  * The ownership test used to be `target.includes(".phren") ||
355
- * target.endsWith("global/CLAUDE.md")`, which treats *any* live phren root's
372
+ * target.endsWith("global/AGENTS.md")`, which treats *any* live phren root's
356
373
  * global file as fair game to unlink. That is how a run with
357
374
  * `PHREN_PATH=/tmp/…` — a smoke test, or phren's own web UI — leaves the
358
375
  * user's real `~/.claude/CLAUDE.md` pointing into a temp directory that then
@@ -369,7 +386,7 @@ export function repairPreexistingInstall(phrenPath, opts) {
369
386
  * repaired, which is the case this function exists for.
370
387
  */
371
388
  function repairGlobalClaudeSymlink(phrenPath) {
372
- const src = path.join(phrenPath, "global", "CLAUDE.md");
389
+ const src = path.join(phrenPath, "global", "AGENTS.md");
373
390
  if (!fs.existsSync(src))
374
391
  return false;
375
392
  const dest = homePath(".claude", "CLAUDE.md");
@@ -385,7 +402,7 @@ function repairGlobalClaudeSymlink(phrenPath) {
385
402
  return false;
386
403
  }
387
404
  // Stale phren wiring — safe to replace. `.includes(".phren")` stays for
388
- // links that are not shaped like <root>/global/CLAUDE.md.
405
+ // links that are not shaped like <root>/global/AGENTS.md.
389
406
  if (owningRoot || target.includes(".phren"))
390
407
  fs.unlinkSync(dest);
391
408
  else
@@ -402,11 +419,11 @@ function repairGlobalClaudeSymlink(phrenPath) {
402
419
  try {
403
420
  fs.mkdirSync(path.dirname(dest), { recursive: true });
404
421
  fs.symlinkSync(src, dest);
405
- debugLog(`repaired global CLAUDE.md symlink: ${dest} -> ${src}`);
422
+ debugLog(`repaired global AGENTS.md symlink: ${dest} -> ${src}`);
406
423
  return true;
407
424
  }
408
425
  catch (err) {
409
- debugLog(`failed to repair global CLAUDE.md symlink: ${errorMessage(err)}`);
426
+ debugLog(`failed to repair global AGENTS.md symlink: ${errorMessage(err)}`);
410
427
  return false;
411
428
  }
412
429
  }
@@ -456,6 +473,7 @@ export function getHookEntrypointCheck(deps = {}) {
456
473
  function gitRemoteStatus(phrenPath) {
457
474
  try {
458
475
  execFileSync("git", ["-C", phrenPath, "rev-parse", "--is-inside-work-tree"], {
476
+ env: nonInteractiveGitEnv(),
459
477
  stdio: ["ignore", "ignore", "ignore"],
460
478
  timeout: EXEC_TIMEOUT_QUICK_MS,
461
479
  });
@@ -466,6 +484,7 @@ function gitRemoteStatus(phrenPath) {
466
484
  let remote;
467
485
  try {
468
486
  remote = execFileSync("git", ["-C", phrenPath, "remote", "get-url", "origin"], {
487
+ env: nonInteractiveGitEnv(),
469
488
  encoding: "utf8",
470
489
  stdio: ["ignore", "pipe", "ignore"],
471
490
  timeout: EXEC_TIMEOUT_QUICK_MS,
@@ -479,6 +498,7 @@ function gitRemoteStatus(phrenPath) {
479
498
  // Connectivity test: verify the remote is reachable (10s timeout)
480
499
  try {
481
500
  execFileSync("git", ["-C", phrenPath, "ls-remote", "--exit-code", "origin"], {
501
+ env: nonInteractiveGitEnv(),
482
502
  stdio: ["ignore", "ignore", "ignore"],
483
503
  timeout: 10_000,
484
504
  });
@@ -513,8 +533,8 @@ export function applyStarterTemplateUpdates(phrenPath) {
513
533
  const starterGlobal = path.join(STARTER_DIR, "global");
514
534
  if (!fs.existsSync(starterGlobal))
515
535
  return updates;
516
- const starterClaude = path.join(starterGlobal, "CLAUDE.md");
517
- const targetClaude = path.join(phrenPath, "global", "CLAUDE.md");
536
+ const starterClaude = path.join(starterGlobal, "AGENTS.md");
537
+ const targetClaude = path.join(phrenPath, "global", "AGENTS.md");
518
538
  if (fs.existsSync(starterClaude)) {
519
539
  const written = copyStarterFile(phrenPath, starterClaude, targetClaude);
520
540
  if (written)
@@ -525,6 +545,8 @@ export function applyStarterTemplateUpdates(phrenPath) {
525
545
  if (fs.existsSync(starterSkillsDir)) {
526
546
  fs.mkdirSync(targetSkillsDir, { recursive: true });
527
547
  for (const f of fs.readdirSync(starterSkillsDir, { withFileTypes: true })) {
548
+ if (!skillEnabled(phrenPath, f.name))
549
+ continue;
528
550
  const src = path.join(starterSkillsDir, f.name);
529
551
  const dest = path.join(targetSkillsDir, f.name);
530
552
  if (f.isFile() && f.name.endsWith(".md")) {
@@ -632,6 +654,8 @@ export function applyTemplate(projectDir, templateName, projectName) {
632
654
  function copyTemplateDir(srcDir, destDir) {
633
655
  fs.mkdirSync(destDir, { recursive: true });
634
656
  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
657
+ if (entry.name === TASKS_FILENAME && !moduleEnabled(path.dirname(projectDir), "tasks"))
658
+ continue;
635
659
  const src = path.join(srcDir, entry.name);
636
660
  const dest = path.join(destDir, entry.name);
637
661
  if (entry.isDirectory()) {
@@ -639,6 +663,8 @@ export function applyTemplate(projectDir, templateName, projectName) {
639
663
  }
640
664
  else {
641
665
  let content = fs.readFileSync(src, "utf8");
666
+ if (entry.name === "AGENTS.md")
667
+ content = starterInstructions(path.dirname(projectDir), content);
642
668
  content = content.replace(/\{\{project\}\}/g, projectName);
643
669
  content = content.replace(/\{\{date\}\}/g, new Date().toISOString().slice(0, 10));
644
670
  atomicWriteText(dest, content);
@@ -648,387 +674,11 @@ export function applyTemplate(projectDir, templateName, projectName) {
648
674
  copyTemplateDir(templateDir, projectDir);
649
675
  return true;
650
676
  }
651
- const DOMAIN_KEYWORD_HINTS = {
652
- software: [
653
- "api", "backend", "frontend", "typescript", "javascript", "python", "rust", "golang", "cli", "sdk", "library", "service",
654
- "server", "database", "auth", "module", "package", "build", "test", "deploy",
655
- ],
656
- music: [
657
- "music", "audio", "mix", "master", "track", "daw", "synth", "midi", "song", "composition", "arrangement", "producer",
658
- ],
659
- game: [
660
- "game", "gameplay", "level", "shader", "physics", "npc", "engine", "unity", "godot", "unreal", "sprite", "multiplayer",
661
- ],
662
- research: [
663
- "research", "paper", "study", "experiment", "dataset", "analysis", "methodology", "hypothesis", "results", "evaluation",
664
- ],
665
- writing: [
666
- "writing", "manuscript", "chapter", "outline", "narrative", "character", "plot", "draft", "editorial",
667
- ],
668
- creative: [
669
- "creative", "story", "design", "worldbuilding", "script", "concept", "illustration", "art direction",
670
- ],
671
- };
672
- const DOMAIN_CONFIG_HINTS = {
673
- "package.json": { software: 3 },
674
- "tsconfig.json": { software: 3 },
675
- "Cargo.toml": { software: 4, game: 1 },
676
- "pyproject.toml": { software: 3, research: 1 },
677
- "requirements.txt": { software: 2, research: 1 },
678
- "go.mod": { software: 3 },
679
- "CMakeLists.txt": { software: 3, game: 1 },
680
- "pom.xml": { software: 3 },
681
- "build.gradle": { software: 3 },
682
- "project.godot": { game: 5 },
683
- ".uproject": { game: 5 },
684
- "paper.tex": { research: 4, writing: 1 },
685
- "references.bib": { research: 4 },
686
- };
687
- const EXTENSION_DOMAIN_HINTS = {
688
- ".ts": { software: 1 },
689
- ".tsx": { software: 1, game: 1 },
690
- ".js": { software: 1 },
691
- ".jsx": { software: 1 },
692
- ".py": { software: 1, research: 1 },
693
- ".rs": { software: 1, game: 1 },
694
- ".go": { software: 1 },
695
- ".java": { software: 1 },
696
- ".kt": { software: 1 },
697
- ".swift": { software: 1 },
698
- ".c": { software: 1, game: 1 },
699
- ".cc": { software: 1, game: 1 },
700
- ".cpp": { software: 1, game: 1 },
701
- ".h": { software: 1, game: 1 },
702
- ".hpp": { software: 1, game: 1 },
703
- ".cs": { software: 1, game: 1 },
704
- ".ipynb": { research: 2 },
705
- ".tex": { research: 2, writing: 1 },
706
- ".bib": { research: 2 },
707
- ".wav": { music: 2 },
708
- ".mp3": { music: 2 },
709
- ".flac": { music: 2 },
710
- ".mid": { music: 2 },
711
- ".midi": { music: 2 },
712
- ".als": { music: 2 },
713
- ".logicx": { music: 2 },
714
- ".unity": { game: 2 },
715
- ".gd": { game: 2 },
716
- ".glsl": { game: 2 },
717
- };
718
- function titleCase(text) {
719
- return text
720
- .split(/[\s_-]+/)
721
- .filter(Boolean)
722
- .map((token) => token.slice(0, 1).toUpperCase() + token.slice(1))
723
- .join(" ");
724
- }
725
- function addTermCount(terms, rawText, weight = 1) {
726
- const tokens = rawText
727
- .toLowerCase()
728
- .replace(/[^\w\s-]/g, " ")
729
- .split(/\s+/)
730
- .map((token) => token.trim())
731
- .filter((token) => token.length >= 3 && token.length <= 48 && !STOP_WORDS.has(token));
732
- for (const token of tokens) {
733
- terms.set(token, (terms.get(token) ?? 0) + weight);
734
- }
735
- }
736
- function maybeReadUtf8(filePath, maxBytes = 256_000) {
737
- try {
738
- const stat = fs.statSync(filePath);
739
- if (!stat.isFile() || stat.size > maxBytes)
740
- return "";
741
- return fs.readFileSync(filePath, "utf8");
742
- }
743
- catch {
744
- return "";
745
- }
746
- }
747
- function addDomainScores(target, patch, weight = 1) {
748
- for (const [domain, score] of Object.entries(patch)) {
749
- const typedDomain = domain;
750
- target[typedDomain] += (score ?? 0) * weight;
751
- }
752
- }
753
- function scoreTopicsFromTerms(domain, terms, docsText) {
754
- const baseTopics = getBuiltinTopicConfig(domain);
755
- const scored = baseTopics
756
- .filter((topic) => topic.name.toLowerCase() !== "general")
757
- .map((topic) => {
758
- const baseTerm = topic.name.toLowerCase();
759
- let score = terms.get(baseTerm) ?? 0;
760
- for (const keyword of topic.keywords) {
761
- const normalized = keyword.toLowerCase().trim();
762
- if (!normalized)
763
- continue;
764
- score += terms.get(normalized) ?? 0;
765
- if (normalized.includes(" ") && docsText.includes(normalized))
766
- score += 1;
767
- }
768
- return { topic, score };
769
- });
770
- const ranked = scored
771
- .filter((entry) => entry.score > 0)
772
- .sort((a, b) => b.score - a.score || a.topic.name.localeCompare(b.topic.name));
773
- const takenNames = new Set(baseTopics.map((topic) => topic.name.toLowerCase()));
774
- const customTopics = [];
775
- for (const [term, count] of [...terms.entries()].sort((a, b) => b[1] - a[1])) {
776
- if (customTopics.length >= 4)
777
- break;
778
- if (count < 3)
779
- break;
780
- if (term.includes("_"))
781
- continue;
782
- const topicName = titleCase(term);
783
- const normalizedName = topicName.toLowerCase();
784
- if (takenNames.has(normalizedName))
785
- continue;
786
- if (DOMAIN_KEYWORD_HINTS.software.includes(term) || DOMAIN_KEYWORD_HINTS.music.includes(term) || DOMAIN_KEYWORD_HINTS.game.includes(term)) {
787
- continue;
788
- }
789
- takenNames.add(normalizedName);
790
- customTopics.push({
791
- name: topicName,
792
- description: "Suggested from repeated terminology in project docs.",
793
- keywords: [term],
794
- });
795
- }
796
- if (ranked.length === 0 && customTopics.length === 0)
797
- return baseTopics;
798
- const orderedBase = [
799
- ...ranked.map((entry) => entry.topic),
800
- ...baseTopics.filter((topic) => topic.name.toLowerCase() !== "general"
801
- && !ranked.some((entry) => entry.topic.name === topic.name)),
802
- ];
803
- const topics = [...orderedBase.slice(0, 8), ...customTopics];
804
- if (!topics.some((topic) => topic.name.toLowerCase() === "general")) {
805
- topics.push({ name: "General", description: "Fallback bucket for uncategorized findings.", keywords: [] });
806
- }
807
- return topics;
808
- }
809
- export function inferInitScaffoldFromRepo(repoRoot, fallbackDomain = "software") {
810
- const resolvedRoot = path.resolve(repoRoot);
811
- if (!fs.existsSync(resolvedRoot))
812
- return null;
813
- const signal = {
814
- domainScores: { software: 0, music: 0, game: 0, research: 0, writing: 0, creative: 0, other: 0 },
815
- terms: new Map(),
816
- docsText: "",
817
- referenceHints: [],
818
- commandHints: [],
819
- usefulSignals: 0,
820
- };
821
- const skipDirs = new Set([".git", ".phren", "node_modules", "dist", "build", "coverage", ".next", ".turbo", "target"]);
822
- const packageJsonPath = path.join(resolvedRoot, "package.json");
823
- if (fs.existsSync(packageJsonPath)) {
824
- signal.usefulSignals++;
825
- addDomainScores(signal.domainScores, DOMAIN_CONFIG_HINTS["package.json"]);
826
- try {
827
- const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
828
- if (typeof parsed.description === "string") {
829
- addTermCount(signal.terms, parsed.description, 3);
830
- signal.docsText += ` ${parsed.description.toLowerCase()}`;
831
- }
832
- if (Array.isArray(parsed.keywords)) {
833
- for (const keyword of parsed.keywords) {
834
- if (typeof keyword === "string") {
835
- addTermCount(signal.terms, keyword, 3);
836
- signal.docsText += ` ${keyword.toLowerCase()}`;
837
- }
838
- }
839
- }
840
- if (parsed.scripts && typeof parsed.scripts === "object" && !Array.isArray(parsed.scripts)) {
841
- const scriptObject = parsed.scripts;
842
- for (const scriptName of ["dev", "start", "build", "test", "lint"]) {
843
- if (typeof scriptObject[scriptName] === "string") {
844
- signal.commandHints.push(`npm run ${scriptName}`);
845
- }
846
- }
847
- }
848
- }
849
- catch (err) {
850
- debugLog(`inferInitScaffoldFromRepo package.json parse failed: ${errorMessage(err)}`);
851
- }
852
- }
853
- const topLevelConfigs = Object.keys(DOMAIN_CONFIG_HINTS)
854
- .filter((fileName) => fs.existsSync(path.join(resolvedRoot, fileName)));
855
- for (const configName of topLevelConfigs) {
856
- signal.usefulSignals++;
857
- const configScore = DOMAIN_CONFIG_HINTS[configName];
858
- if (configScore)
859
- addDomainScores(signal.domainScores, configScore);
860
- }
861
- const readmeCandidates = [
862
- path.join(resolvedRoot, "README.md"),
863
- path.join(resolvedRoot, "readme.md"),
864
- ];
865
- for (const readmePath of readmeCandidates) {
866
- if (!fs.existsSync(readmePath))
867
- continue;
868
- const content = maybeReadUtf8(readmePath);
869
- if (!content)
870
- continue;
871
- signal.usefulSignals++;
872
- signal.referenceHints.push(path.relative(resolvedRoot, readmePath));
873
- addTermCount(signal.terms, content, 2);
874
- signal.docsText += ` ${content.toLowerCase()}`;
875
- break;
876
- }
877
- const docsDir = path.join(resolvedRoot, "docs");
878
- if (fs.existsSync(docsDir) && fs.statSync(docsDir).isDirectory()) {
879
- signal.referenceHints.push("docs/");
880
- for (const entry of fs.readdirSync(docsDir, { withFileTypes: true })) {
881
- if (!entry.isFile())
882
- continue;
883
- if (!/\.(md|txt|rst)$/i.test(entry.name))
884
- continue;
885
- const docsContent = maybeReadUtf8(path.join(docsDir, entry.name));
886
- if (!docsContent)
887
- continue;
888
- signal.usefulSignals++;
889
- addTermCount(signal.terms, docsContent, 1);
890
- signal.docsText += ` ${docsContent.toLowerCase()}`;
891
- }
892
- }
893
- for (const folderName of ["reference", "specs", "design", "architecture", "src", "packages", "apps"]) {
894
- const fullPath = path.join(resolvedRoot, folderName);
895
- if (fs.existsSync(fullPath)) {
896
- signal.referenceHints.push(`${folderName}/`);
897
- }
898
- }
899
- let scannedFiles = 0;
900
- const maxFiles = 3000;
901
- const walk = (dir) => {
902
- if (scannedFiles >= maxFiles)
903
- return;
904
- for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
905
- if (scannedFiles >= maxFiles)
906
- return;
907
- const fullPath = path.join(dir, entry.name);
908
- if (entry.isDirectory()) {
909
- if (skipDirs.has(entry.name))
910
- continue;
911
- walk(fullPath);
912
- continue;
913
- }
914
- scannedFiles++;
915
- const ext = path.extname(entry.name).toLowerCase();
916
- if (!ext)
917
- continue;
918
- const extScore = EXTENSION_DOMAIN_HINTS[ext];
919
- if (extScore) {
920
- addDomainScores(signal.domainScores, extScore);
921
- signal.usefulSignals++;
922
- }
923
- }
924
- };
925
- walk(resolvedRoot);
926
- for (const [domain, hints] of Object.entries(DOMAIN_KEYWORD_HINTS)) {
927
- for (const hint of hints) {
928
- const hitCount = signal.terms.get(hint) ?? 0;
929
- if (hitCount > 0) {
930
- signal.domainScores[domain] += Math.min(4, hitCount);
931
- signal.usefulSignals++;
932
- }
933
- }
934
- }
935
- const rankedDomains = Object.entries(signal.domainScores)
936
- .sort((a, b) => b[1] - a[1]);
937
- const [bestDomain, bestScore] = rankedDomains[0] ?? [fallbackDomain, 0];
938
- const secondScore = rankedDomains[1]?.[1] ?? 0;
939
- const inferredDomain = bestScore >= 2 ? bestDomain : fallbackDomain;
940
- const confidence = bestScore <= 0
941
- ? 0
942
- : Math.max(0.15, Math.min(0.98, (bestScore - secondScore + 1) / (bestScore + 2)));
943
- const topics = scoreTopicsFromTerms(inferredDomain, signal.terms, signal.docsText);
944
- const references = Array.from(new Set(signal.referenceHints)).slice(0, 8);
945
- const commands = Array.from(new Set(signal.commandHints)).slice(0, 5);
946
- const reason = bestScore > 0
947
- ? `inferred from repo files, config, and docs terminology (score ${bestScore})`
948
- : "fallback defaults";
949
- if (signal.usefulSignals === 0)
950
- return null;
951
- return {
952
- domain: inferredDomain,
953
- topics: topics.length > 0 ? topics : getBuiltinTopicConfig(inferredDomain),
954
- referenceHints: references,
955
- commandHints: commands,
956
- confidence: Number(confidence.toFixed(2)),
957
- reason,
958
- };
959
- }
960
- function appendInferredSections(base, inference) {
961
- if (!inference)
962
- return base;
963
- const lines = [];
964
- if (inference.referenceHints.length > 0) {
965
- lines.push("## Reference Structure");
966
- for (const hint of inference.referenceHints) {
967
- lines.push(`- ${hint}`);
968
- }
969
- lines.push("");
970
- }
971
- if (inference.topics.length > 0) {
972
- lines.push("## Initial Focus Topics");
973
- for (const topic of inference.topics.slice(0, 6)) {
974
- lines.push(`- ${topic.name}: ${topic.description}`);
975
- }
976
- lines.push("");
977
- }
978
- if (inference.commandHints.length > 0) {
979
- lines.push("## Commands");
980
- lines.push("```bash");
981
- for (const cmd of inference.commandHints)
982
- lines.push(cmd);
983
- lines.push("```");
984
- lines.push("");
985
- }
986
- return lines.length > 0 ? `${base.trimEnd()}\n\n${lines.join("\n")}` : base;
987
- }
988
- function getDomainClaudeTemplate(projectName, domain, inference) {
989
- if (domain === "software") {
990
- return appendInferredSections(`# ${projectName}\n\nOne paragraph about what this project is.\n\n## Commands\n\n\`\`\`bash\n# Install:\n# Run:\n# Test:\n\`\`\`\n`, inference);
991
- }
992
- if (domain === "music") {
993
- return appendInferredSections(`# ${projectName}\n\nThis is a music project. Keep notes on composition intent, arrangement choices, production workflow, and mixing/mastering decisions.\n\n## Session Focus\n\n- Capture creative intent before technical tweaks\n- Track instrument/sound-design decisions and why\n- Log mix/master changes with listening context\n`, inference);
994
- }
995
- if (domain === "game") {
996
- return appendInferredSections(`# ${projectName}\n\nThis is a game project. Prioritize clear notes on mechanics, rendering/performance tradeoffs, level and UI decisions, and iteration outcomes.\n\n## Development Focus\n\n- Record gameplay/mechanics decisions with player impact\n- Track rendering/physics/AI issues with repro context\n- Note level-design and networking constraints early\n`, inference);
997
- }
998
- if (domain === "research") {
999
- return appendInferredSections(`# ${projectName}\n\nThis is a research project. Focus on methodology, source quality, analysis assumptions, and review feedback loops.\n\n## Working Approach\n\n- Document hypotheses and evaluation criteria explicitly\n- Track source provenance and confidence level\n- Record analysis decisions and revision rationale\n`, inference);
1000
- }
1001
- if (domain === "writing" || domain === "creative") {
1002
- return appendInferredSections(`# ${projectName}\n\nThis is a creative writing project. Track worldbuilding rules, character arcs, plot structure, style constraints, and revision decisions.\n\n## Writing Workflow\n\n- Keep narrative intent and tone constraints visible\n- Capture character/plot changes with consequences\n- Log revision notes and unresolved questions\n`, inference);
1003
- }
1004
- return appendInferredSections(`# ${projectName}\n\nThis project is not software-first. Keep practical notes, references, and task decisions so future sessions can resume quickly.\n\n## Workflow\n\n- Capture non-obvious lessons and reusable patterns\n- Keep references curated and current\n- Track active tasks and follow-ups\n`, inference);
1005
- }
1006
- export function ensureProjectScaffold(projectDir, projectName, domain = "software", inference) {
1007
- const normalizedDomain = normalizeBuiltinTopicDomain(inference?.domain ?? domain);
1008
- const inferredTopics = Array.isArray(inference?.topics) && inference.topics.length > 0
1009
- ? inference.topics
1010
- : getBuiltinTopicConfig(normalizedDomain);
1011
- fs.mkdirSync(projectDir, { recursive: true });
1012
- if (!fs.existsSync(path.join(projectDir, "summary.md"))) {
1013
- atomicWriteText(path.join(projectDir, "summary.md"), `# ${projectName}\n\n**What:** Replace this with one sentence about what the project does\n**Stack:** The key tech\n**Status:** active\n**Run:** the command you use most\n**Watch out:** the one thing that will bite you if you forget\n`);
1014
- }
1015
- if (!fs.existsSync(path.join(projectDir, "CLAUDE.md"))) {
1016
- atomicWriteText(path.join(projectDir, "CLAUDE.md"), getDomainClaudeTemplate(projectName, inference?.domain ?? domain, inference));
1017
- }
1018
- if (!fs.existsSync(path.join(projectDir, "topic-config.json"))) {
1019
- atomicWriteText(path.join(projectDir, "topic-config.json"), JSON.stringify({ version: 1, domain: normalizedDomain, topics: inferredTopics }, null, 2) + "\n");
1020
- }
1021
- if (!fs.existsSync(path.join(projectDir, FINDINGS_FILENAME))) {
1022
- atomicWriteText(path.join(projectDir, FINDINGS_FILENAME), `# ${projectName} FINDINGS\n\n<!-- Findings are captured automatically during sessions and committed on exit -->\n`);
1023
- }
1024
- if (!fs.existsSync(path.join(projectDir, TASKS_FILENAME))) {
1025
- atomicWriteText(path.join(projectDir, TASKS_FILENAME), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
1026
- }
1027
- }
1028
677
  export function ensureLocalGitRepo(phrenPath) {
1029
678
  // Check if phrenPath already has its own git repo (not just being inside a parent)
1030
679
  try {
1031
680
  const topLevel = execFileSync("git", ["-C", phrenPath, "rev-parse", "--show-toplevel"], {
681
+ env: nonInteractiveGitEnv(),
1032
682
  encoding: "utf8",
1033
683
  stdio: ["ignore", "pipe", "ignore"],
1034
684
  timeout: EXEC_TIMEOUT_QUICK_MS,
@@ -1056,17 +706,20 @@ export function ensureLocalGitRepo(phrenPath) {
1056
706
  try {
1057
707
  try {
1058
708
  execFileSync("git", ["-C", phrenPath, "init", "--initial-branch=main"], {
709
+ env: nonInteractiveGitEnv(),
1059
710
  stdio: ["ignore", "ignore", "ignore"],
1060
711
  timeout: EXEC_TIMEOUT_QUICK_MS,
1061
712
  });
1062
713
  }
1063
714
  catch {
1064
715
  execFileSync("git", ["-C", phrenPath, "init"], {
716
+ env: nonInteractiveGitEnv(),
1065
717
  stdio: ["ignore", "ignore", "ignore"],
1066
718
  timeout: EXEC_TIMEOUT_QUICK_MS,
1067
719
  });
1068
720
  try {
1069
721
  execFileSync("git", ["-C", phrenPath, "branch", "-M", "main"], {
722
+ env: nonInteractiveGitEnv(),
1070
723
  stdio: ["ignore", "ignore", "ignore"],
1071
724
  timeout: EXEC_TIMEOUT_QUICK_MS,
1072
725
  });
@@ -1081,188 +734,6 @@ export function ensureLocalGitRepo(phrenPath) {
1081
734
  return { ok: false, initialized: false, detail: `git init failed: ${errorMessage(err)}` };
1082
735
  }
1083
736
  }
1084
- /** Bootstrap a phren project from an existing project directory with CLAUDE.md.
1085
- * @param profile - if provided, only this profile YAML is updated (avoids leaking project to unrelated profiles).
1086
- */
1087
- /**
1088
- * Find an already-registered project that `sourceRoot` should reuse rather than
1089
- * getting a near-duplicate directory of its own. Two signals, strongest first:
1090
- *
1091
- * 1. **Same source path.** Another project already points at this exact
1092
- * directory — unambiguous, reuse it whatever it is called.
1093
- * 2. **Same canonical slug.** `max4liveplugins` vs `max4live-plugins`: the same
1094
- * repo spelled two ways. Only reused when the existing project has no source
1095
- * path recorded, or records this one — if it points somewhere else it is a
1096
- * genuinely different project that merely slugs alike, and both are kept.
1097
- *
1098
- * Returns `null` when nothing matches, i.e. create the project normally.
1099
- */
1100
- function findExistingProjectForSource(phrenPath, sourceRoot, derivedName) {
1101
- let candidates;
1102
- try {
1103
- candidates = fs.readdirSync(phrenPath, { withFileTypes: true })
1104
- .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
1105
- .map((entry) => entry.name);
1106
- }
1107
- catch (err) {
1108
- debugLog(`findExistingProjectForSource readdir: ${errorMessage(err)}`);
1109
- return null;
1110
- }
1111
- const sourceOf = (project) => {
1112
- try {
1113
- return readProjectConfig(phrenPath, project).sourcePath
1114
- ? path.resolve(String(readProjectConfig(phrenPath, project).sourcePath))
1115
- : null;
1116
- }
1117
- catch (err) {
1118
- debugLog(`findExistingProjectForSource config ${project}: ${errorMessage(err)}`);
1119
- return null;
1120
- }
1121
- };
1122
- const resolvedSource = path.resolve(sourceRoot);
1123
- for (const project of candidates) {
1124
- if (sourceOf(project) === resolvedSource)
1125
- return project;
1126
- }
1127
- for (const project of findProjectNamesByCanonicalKey(phrenPath, derivedName)) {
1128
- if (project === derivedName)
1129
- return project; // exact match; nothing to reconcile
1130
- const existingSource = sourceOf(project);
1131
- if (existingSource === null || existingSource === resolvedSource)
1132
- return project;
1133
- }
1134
- return null;
1135
- }
1136
- export function bootstrapFromExisting(phrenPath, projectPath, opts = {}) {
1137
- const profile = typeof opts === "string" ? opts : opts.profile;
1138
- const profilePhrenPath = typeof opts === "string" ? phrenPath : (opts.profilePhrenPath ?? phrenPath);
1139
- const resolvedPath = path.resolve(projectPath);
1140
- if (!fs.existsSync(resolvedPath)) {
1141
- throw new Error(`Path does not exist: ${resolvedPath}`);
1142
- }
1143
- const manifest = readRootManifest(phrenPath);
1144
- const isProjectLocal = manifest?.installMode === "project-local";
1145
- // A git worktree — notably the agent-managed ones under `.claude/worktrees/`
1146
- // — is a checkout of a repository we may already track. Attribute it to that
1147
- // repository instead of registering the worktree's throwaway codename as a
1148
- // brand-new top-level project.
1149
- const worktree = isProjectLocal ? null : resolveWorktreeParent(resolvedPath);
1150
- const worktreeRepoRoot = worktree && fs.existsSync(worktree.repoRoot) ? worktree.repoRoot : null;
1151
- if (worktreeRepoRoot) {
1152
- debugLog(`bootstrapFromExisting: ${resolvedPath} is a ${worktree.reason}; attributing to ${worktreeRepoRoot}`);
1153
- }
1154
- const sourceRoot = isProjectLocal
1155
- ? path.resolve(manifest.workspaceRoot || resolvedPath)
1156
- : (worktreeRepoRoot ?? resolvedPath);
1157
- if (isProjectLocal) {
1158
- const matchesWorkspace = resolvedPath === sourceRoot || resolvedPath.startsWith(sourceRoot + path.sep);
1159
- if (!matchesWorkspace) {
1160
- throw new Error(`Project-local phren can only enroll the owning workspace: ${sourceRoot}`);
1161
- }
1162
- }
1163
- let claudeMdPath = null;
1164
- const candidates = [
1165
- path.join(sourceRoot, "CLAUDE.md"),
1166
- path.join(sourceRoot, ".claude", "CLAUDE.md"),
1167
- ];
1168
- for (const c of candidates) {
1169
- if (fs.existsSync(c)) {
1170
- claudeMdPath = c;
1171
- break;
1172
- }
1173
- }
1174
- const claudeContent = claudeMdPath ? fs.readFileSync(claudeMdPath, "utf8") : null;
1175
- const derivedName = isProjectLocal
1176
- ? String(manifest?.primaryProject)
1177
- : projectSlugFromPath(sourceRoot);
1178
- const projectName = isProjectLocal
1179
- ? derivedName
1180
- : (findExistingProjectForSource(phrenPath, sourceRoot, derivedName) ?? derivedName);
1181
- if (projectName !== derivedName) {
1182
- debugLog(`bootstrapFromExisting: reusing existing project "${projectName}" for ${sourceRoot} (derived "${derivedName}")`);
1183
- }
1184
- const existingProject = findProjectNameCaseInsensitive(phrenPath, projectName);
1185
- if (existingProject && existingProject !== projectName) {
1186
- throw new Error(`Project "${existingProject}" already exists with different casing. Refusing to bootstrap "${projectName}" because it would split the same project on case-sensitive filesystems.`);
1187
- }
1188
- const projDir = path.join(phrenPath, projectName);
1189
- fs.mkdirSync(projDir, { recursive: true });
1190
- const inferredScaffold = inferInitScaffoldFromRepo(sourceRoot);
1191
- const existingConfig = readProjectConfig(phrenPath, projectName);
1192
- const ownership = typeof opts === "string"
1193
- ? (parseProjectOwnershipMode(existingConfig.ownership) ?? getProjectOwnershipDefault(phrenPath))
1194
- : (opts.ownership ?? parseProjectOwnershipMode(existingConfig.ownership) ?? getProjectOwnershipDefault(phrenPath));
1195
- const claudePath = path.join(projDir, "CLAUDE.md");
1196
- if (ownership !== "repo-managed") {
1197
- if (claudeContent) {
1198
- if (!fs.existsSync(claudePath)) {
1199
- atomicWriteText(claudePath, claudeContent);
1200
- }
1201
- }
1202
- else {
1203
- // No CLAUDE.md found — create a starter one
1204
- if (!fs.existsSync(claudePath)) {
1205
- atomicWriteText(claudePath, getDomainClaudeTemplate(projectName, inferredScaffold?.domain ?? "software", inferredScaffold));
1206
- }
1207
- }
1208
- }
1209
- const summaryLines = [];
1210
- if (claudeContent) {
1211
- const lines = claudeContent.split("\n");
1212
- let foundHeading = false;
1213
- for (const line of lines) {
1214
- if (line.startsWith("# ") && !foundHeading) {
1215
- foundHeading = true;
1216
- summaryLines.push(line);
1217
- continue;
1218
- }
1219
- if (foundHeading && line.trim() === "") {
1220
- if (summaryLines.length > 1)
1221
- break;
1222
- continue;
1223
- }
1224
- if (foundHeading && summaryLines.length < 10) {
1225
- summaryLines.push(line);
1226
- }
1227
- }
1228
- }
1229
- const sourceInfo = claudeMdPath ? `**Source CLAUDE.md:** ${claudeMdPath}` : `**Source:** ${sourceRoot}`;
1230
- const summaryPath = path.join(projDir, "summary.md");
1231
- if (!fs.existsSync(summaryPath)) {
1232
- atomicWriteText(summaryPath, `# ${projectName}\n\n**What:** Bootstrapped from ${sourceRoot}\n${sourceInfo}\n\n${summaryLines.length > 1 ? summaryLines.slice(1).join("\n") : ""}\n`);
1233
- }
1234
- if (!fs.existsSync(path.join(projDir, FINDINGS_FILENAME))) {
1235
- atomicWriteText(path.join(projDir, FINDINGS_FILENAME), `# ${projectName} FINDINGS\n\n<!-- Bootstrapped from ${sourceRoot} -->\n`);
1236
- }
1237
- if (!fs.existsSync(path.join(projDir, TASKS_FILENAME))) {
1238
- atomicWriteText(path.join(projDir, TASKS_FILENAME), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
1239
- }
1240
- if (!fs.existsSync(path.join(projDir, "topic-config.json"))) {
1241
- const inferredDomain = normalizeBuiltinTopicDomain(inferredScaffold?.domain ?? "software");
1242
- const inferredTopics = inferredScaffold?.topics?.length
1243
- ? inferredScaffold.topics
1244
- : getBuiltinTopicConfig(inferredDomain);
1245
- atomicWriteText(path.join(projDir, "topic-config.json"), JSON.stringify({ version: 1, domain: inferredDomain, topics: inferredTopics }, null, 2) + "\n");
1246
- }
1247
- const activeProfile = resolveActiveProfile(profilePhrenPath, profile);
1248
- if (activeProfile.ok && activeProfile.data) {
1249
- const addResult = addProjectToProfile(profilePhrenPath, activeProfile.data, projectName);
1250
- if (!addResult.ok) {
1251
- throw new Error(addResult.error);
1252
- }
1253
- }
1254
- else if (!activeProfile.ok && activeProfile.code !== "FILE_NOT_FOUND") {
1255
- throw new Error(activeProfile.error);
1256
- }
1257
- writeProjectConfig(phrenPath, projectName, { ownership, sourcePath: sourceRoot });
1258
- return {
1259
- project: projectName,
1260
- ownership,
1261
- claudePath: ownership === "repo-managed"
1262
- ? (claudeMdPath ?? null)
1263
- : (fs.existsSync(claudePath) ? claudePath : null),
1264
- };
1265
- }
1266
737
  export function updateMachinesYaml(phrenPath, machine, profile) {
1267
738
  const machinesFile = path.join(phrenPath, "machines.yaml");
1268
739
  if (!fs.existsSync(machinesFile))
@@ -1280,7 +751,11 @@ export function updateMachinesYaml(phrenPath, machine, profile) {
1280
751
  }
1281
752
  }
1282
753
  catch (err) {
754
+ // Not "no existing mapping": setMachineProfile refuses to rewrite the file,
755
+ // and the user needs to hear why the mapping did not change.
1283
756
  logger.debug("setup", `updateMachinesYaml parse: ${errorMessage(err)}`);
757
+ console.warn(` ${machinesFile} could not be parsed; machine mappings left unchanged. Fix it by hand (check for git conflict markers), then run 'phren init' again.`);
758
+ return;
1284
759
  }
1285
760
  // Passive init/link refreshes should keep an existing mapping; explicit overrides can remap.
1286
761
  if (hasExistingMapping && !machine && !profile)
@@ -1294,7 +769,7 @@ export function updateMachinesYaml(phrenPath, machine, profile) {
1294
769
  * Returns the path if it qualifies, null otherwise.
1295
770
  * A directory qualifies if it:
1296
771
  * - Is not the home directory or phren directory
1297
- * - Has a CLAUDE.md, AGENTS.md, .claude/CLAUDE.md, or .git directory
772
+ * - Has an AGENTS.md, legacy CLAUDE.md, .claude/CLAUDE.md, or .git directory
1298
773
  *
1299
774
  * A git worktree resolves to the repository it belongs to. Without this a
1300
775
  * throwaway agent worktree under `.claude/worktrees/<codename>` looks like its
@@ -1468,12 +943,12 @@ export function runPostInitVerify(phrenPath) {
1468
943
  : "Run `phren init` to install or refresh hooks",
1469
944
  });
1470
945
  }
1471
- const globalClaude = path.join(phrenPath, "global", "CLAUDE.md");
946
+ const globalClaude = path.join(phrenPath, "global", "AGENTS.md");
1472
947
  const globalOk = fs.existsSync(globalClaude);
1473
948
  checks.push({
1474
949
  name: "global-claude",
1475
950
  ok: globalOk,
1476
- detail: globalOk ? "global/CLAUDE.md exists" : "global/CLAUDE.md missing",
951
+ detail: globalOk ? "global/AGENTS.md exists" : "global/AGENTS.md missing",
1477
952
  fix: globalOk ? undefined : "Run `phren init` to create starter files",
1478
953
  });
1479
954
  const govDir = path.join(phrenPath, ".config");