@moretea-labs/forge 1.5.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (903) hide show
  1. package/AGENTS.md +120 -0
  2. package/CHANGELOG.md +36 -0
  3. package/CLAUDE.md +120 -0
  4. package/CODE_OF_CONDUCT.md +23 -0
  5. package/CONTRIBUTING.md +77 -0
  6. package/LICENSE +22 -0
  7. package/NOTICE +9 -0
  8. package/README.en.md +5 -0
  9. package/README.es.md +12 -0
  10. package/README.fr.md +12 -0
  11. package/README.ja.md +12 -0
  12. package/README.md +132 -0
  13. package/README.zh-CN.md +84 -0
  14. package/SECURITY.md +50 -0
  15. package/SKILL.md +431 -0
  16. package/SUPPORT.md +31 -0
  17. package/THIRD_PARTY_NOTICES.md +18 -0
  18. package/agents/openai.yaml +4 -0
  19. package/assets/AGENTS.md +68 -0
  20. package/assets/CLAUDE.md +68 -0
  21. package/assets/branding/README.md +10 -0
  22. package/assets/branding/forge-controller-flow.mmd +8 -0
  23. package/assets/hooks/AGENTS.md +75 -0
  24. package/assets/hooks/CLAUDE.md +75 -0
  25. package/assets/hooks/anti-simplification.sh +12 -0
  26. package/assets/hooks/changelog-guard.sh +80 -0
  27. package/assets/hooks/codex.hooks.template.json +60 -0
  28. package/assets/hooks/first-principles-guard.sh +72 -0
  29. package/assets/hooks/hook-input.sh +618 -0
  30. package/assets/hooks/lib/session-state.sh +106 -0
  31. package/assets/hooks/lib/workflow-state.sh +1730 -0
  32. package/assets/hooks/post-bash.sh +215 -0
  33. package/assets/hooks/post-edit-guard.sh +256 -0
  34. package/assets/hooks/post-tool-observer.sh +99 -0
  35. package/assets/hooks/pre-edit-guard.sh +240 -0
  36. package/assets/hooks/prompt-guard.sh +1077 -0
  37. package/assets/hooks/run-hook.sh +67 -0
  38. package/assets/hooks/security-sentinel.sh +115 -0
  39. package/assets/hooks/session-start-context.sh +593 -0
  40. package/assets/hooks/settings.template.json +60 -0
  41. package/assets/hooks/stop-orchestrator.sh +171 -0
  42. package/assets/hooks/subagent-return-channel-guard.sh +107 -0
  43. package/assets/hooks/worktree-guard.sh +39 -0
  44. package/assets/initializer-question-pack.v1.json +132 -0
  45. package/assets/initializer-question-pack.v1.schema.json +46 -0
  46. package/assets/initializer-question-pack.v2.json +174 -0
  47. package/assets/initializer-question-pack.v3.json +206 -0
  48. package/assets/initializer-question-pack.v3.schema.json +92 -0
  49. package/assets/initializer-question-pack.v4.json +557 -0
  50. package/assets/initializer-question-pack.v4.schema.json +169 -0
  51. package/assets/partials/01-header.partial.md +10 -0
  52. package/assets/partials/02-iron-rules.partial.md +30 -0
  53. package/assets/partials/03-philosophy.partial.md +32 -0
  54. package/assets/partials/04-project-structure.partial.md +56 -0
  55. package/assets/partials/05-workflow.partial.md +79 -0
  56. package/assets/partials/06-cloudflare.partial.md +20 -0
  57. package/assets/partials/07-footer.partial.md +38 -0
  58. package/assets/partials/08-orchestration.partial.md +49 -0
  59. package/assets/partials/09-compact-instructions.partial.md +11 -0
  60. package/assets/partials/_assembly-order.md +40 -0
  61. package/assets/partials-agents/01-header.partial.md +8 -0
  62. package/assets/partials-agents/02-operating-mode.partial.md +44 -0
  63. package/assets/partials-agents/03-orchestration.partial.md +45 -0
  64. package/assets/partials-agents/04-task-protocol.partial.md +69 -0
  65. package/assets/partials-agents/05-coding-constraints.partial.md +20 -0
  66. package/assets/partials-agents/06-quality-safety.partial.md +23 -0
  67. package/assets/partials-agents/07-cloudflare.partial.md +9 -0
  68. package/assets/partials-agents/08-deep-docs.partial.md +32 -0
  69. package/assets/plan-map.json +301 -0
  70. package/assets/plugin-registry.v1.json +8 -0
  71. package/assets/project-structures/ai-native-collaborative-editor.txt +25 -0
  72. package/assets/project-structures/ai-native-product-copilot.txt +21 -0
  73. package/assets/project-structures/ai-native-runtime-console.txt +25 -0
  74. package/assets/project-structures/ai-native-sidecar-kernel.txt +19 -0
  75. package/assets/project-structures/astro-ssr.txt +25 -0
  76. package/assets/project-structures/expo-nativewind.txt +52 -0
  77. package/assets/project-structures/monorepo.txt +63 -0
  78. package/assets/project-structures/remix.txt +50 -0
  79. package/assets/project-structures/tanstack-start-workers.txt +51 -0
  80. package/assets/project-structures/vite-tanstack.txt +58 -0
  81. package/assets/reference-configs/AGENTS.md +13 -0
  82. package/assets/reference-configs/CLAUDE.md +13 -0
  83. package/assets/reference-configs/agentic-development-flow.md +94 -0
  84. package/assets/reference-configs/ai-workflows.md +14 -0
  85. package/assets/reference-configs/changelog-versioning.md +13 -0
  86. package/assets/reference-configs/coding-standards.md +14 -0
  87. package/assets/reference-configs/development-protocol.md +21 -0
  88. package/assets/reference-configs/document-generation.md +38 -0
  89. package/assets/reference-configs/evaluator-rubric.md +19 -0
  90. package/assets/reference-configs/external-tooling.md +374 -0
  91. package/assets/reference-configs/git-strategy.md +14 -0
  92. package/assets/reference-configs/global-working-rules.md +64 -0
  93. package/assets/reference-configs/handoff-protocol.md +38 -0
  94. package/assets/reference-configs/harness-overview.md +124 -0
  95. package/assets/reference-configs/heartbeat-triage.md +57 -0
  96. package/assets/reference-configs/hook-operations.md +96 -0
  97. package/assets/reference-configs/release-deploy.md +40 -0
  98. package/assets/reference-configs/spa-day-protocol.md +14 -0
  99. package/assets/reference-configs/sprint-contracts.md +89 -0
  100. package/assets/reference-configs/workflow-orchestration.md +14 -0
  101. package/assets/skill-hooks.json +41 -0
  102. package/assets/skill-version.json +189 -0
  103. package/assets/skills/claude-review/SKILL.md +231 -0
  104. package/assets/skills/codex-review/SKILL.md +103 -0
  105. package/assets/templates/AGENTS.md +13 -0
  106. package/assets/templates/CLAUDE.md +13 -0
  107. package/assets/templates/architecture.template.md +80 -0
  108. package/assets/templates/brief.template.md +38 -0
  109. package/assets/templates/contract.template.md +104 -0
  110. package/assets/templates/decisions.template.md +85 -0
  111. package/assets/templates/factor-factory/factor-backtest-report.template.md +36 -0
  112. package/assets/templates/factor-factory/factor-hypothesis.template.md +30 -0
  113. package/assets/templates/factor-factory/factor-registry.template.json +5 -0
  114. package/assets/templates/gitignore.template +53 -0
  115. package/assets/templates/guides/metro-esm-gotchas.template.md +46 -0
  116. package/assets/templates/helpers/architecture-event.ts +822 -0
  117. package/assets/templates/helpers/architecture-queue.sh +647 -0
  118. package/assets/templates/helpers/archive-architecture-request.sh +244 -0
  119. package/assets/templates/helpers/archive-workflow.sh +295 -0
  120. package/assets/templates/helpers/capability-config.ts +394 -0
  121. package/assets/templates/helpers/capability-resolver.ts +505 -0
  122. package/assets/templates/helpers/capture-plan.sh +335 -0
  123. package/assets/templates/helpers/check-agent-tooling.sh +1533 -0
  124. package/assets/templates/helpers/check-architecture-sync.sh +287 -0
  125. package/assets/templates/helpers/check-brain-manifest.sh +255 -0
  126. package/assets/templates/helpers/check-context-files.sh +49 -0
  127. package/assets/templates/helpers/check-deploy-sql-order.sh +117 -0
  128. package/assets/templates/helpers/check-skill-version.ts +193 -0
  129. package/assets/templates/helpers/check-task-sync.sh +65 -0
  130. package/assets/templates/helpers/check-task-workflow.sh +1002 -0
  131. package/assets/templates/helpers/codex-handoff-resume.sh +269 -0
  132. package/assets/templates/helpers/context-contract-sync.sh +516 -0
  133. package/assets/templates/helpers/contract-run.ts +465 -0
  134. package/assets/templates/helpers/contract-worktree.sh +725 -0
  135. package/assets/templates/helpers/ensure-task-workflow.sh +1218 -0
  136. package/assets/templates/helpers/harness-trace-grade.sh +150 -0
  137. package/assets/templates/helpers/heartbeat-triage.sh +361 -0
  138. package/assets/templates/helpers/inspect-project-state.ts +280 -0
  139. package/assets/templates/helpers/maintenance-triage.sh +167 -0
  140. package/assets/templates/helpers/migrate-project-template.sh +54 -0
  141. package/assets/templates/helpers/migrate-workflow-docs.ts +413 -0
  142. package/assets/templates/helpers/new-plan.sh +183 -0
  143. package/assets/templates/helpers/new-spec.sh +50 -0
  144. package/assets/templates/helpers/new-sprint.sh +49 -0
  145. package/assets/templates/helpers/plan-to-todo.sh +799 -0
  146. package/assets/templates/helpers/prepare-codex-handoff.sh +203 -0
  147. package/assets/templates/helpers/prepare-handoff.sh +81 -0
  148. package/assets/templates/helpers/refresh-current-status.sh +469 -0
  149. package/assets/templates/helpers/select-agent-context-blocks.sh +66 -0
  150. package/assets/templates/helpers/ship-worktrees.sh +561 -0
  151. package/assets/templates/helpers/sprint-backlog.sh +837 -0
  152. package/assets/templates/helpers/summarize-failures.sh +125 -0
  153. package/assets/templates/helpers/switch-plan.sh +153 -0
  154. package/assets/templates/helpers/sync-brain-docs.sh +381 -0
  155. package/assets/templates/helpers/verify-contract.sh +705 -0
  156. package/assets/templates/helpers/verify-sprint.sh +680 -0
  157. package/assets/templates/helpers/workflow-contract.ts +202 -0
  158. package/assets/templates/helpers/workstream-sync.sh +263 -0
  159. package/assets/templates/implementation-notes.template.md +37 -0
  160. package/assets/templates/packages.template.md +45 -0
  161. package/assets/templates/plan.template.md +77 -0
  162. package/assets/templates/prd.template.md +165 -0
  163. package/assets/templates/research.template.md +25 -0
  164. package/assets/templates/review.template.md +78 -0
  165. package/assets/templates/spec.template.md +31 -0
  166. package/assets/templates/sprint.template.md +69 -0
  167. package/assets/templates/tech-stack.template.md +57 -0
  168. package/assets/versions.json +77 -0
  169. package/assets/workflow-contract.v1.json +671 -0
  170. package/bin/forge-desktop-helper.mjs +204 -0
  171. package/bin/forge-hook.mjs +32 -0
  172. package/bin/forge-runtime-service.mjs +34 -0
  173. package/bin/forge-runtime.mjs +30 -0
  174. package/bin/forge.mjs +32 -0
  175. package/docs/CHANGELOG.md +978 -0
  176. package/docs/README.md +72 -0
  177. package/docs/README.zh-CN.md +58 -0
  178. package/docs/architecture/chatgpt-handoff-facade.md +393 -0
  179. package/docs/architecture/current/README.md +158 -0
  180. package/docs/architecture/current/approved-target-architecture.zh-CN.md +1501 -0
  181. package/docs/architecture/current/architecture-invariants.md +331 -0
  182. package/docs/architecture/current/automation-and-schedule-engine.md +453 -0
  183. package/docs/architecture/current/codegraph-context-provider.md +226 -0
  184. package/docs/architecture/current/control-plane-authority-inventory.md +82 -0
  185. package/docs/architecture/current/controller-repository-decoupling.md +148 -0
  186. package/docs/architecture/current/dispatch-and-agent-strategy.md +354 -0
  187. package/docs/architecture/current/entity-model.md +619 -0
  188. package/docs/architecture/current/external-plugin-governance.md +396 -0
  189. package/docs/architecture/current/failure-recovery.md +471 -0
  190. package/docs/architecture/current/governance.md +213 -0
  191. package/docs/architecture/current/human-interaction-plane.md +87 -0
  192. package/docs/architecture/current/implementation-status.md +128 -0
  193. package/docs/architecture/current/job-and-run-lifecycle.md +413 -0
  194. package/docs/architecture/current/local-workspace-target-grants.md +70 -0
  195. package/docs/architecture/current/migration-roadmap.md +105 -0
  196. package/docs/architecture/current/multi-repository-execution.md +371 -0
  197. package/docs/architecture/current/operations-runbook.md +45 -0
  198. package/docs/architecture/current/peer-supercontroller-runtime.md +32 -0
  199. package/docs/architecture/current/personal-assistant-plugin-baseline.md +207 -0
  200. package/docs/architecture/current/repository-access-modes.md +102 -0
  201. package/docs/architecture/current/route-policy.md +15 -0
  202. package/docs/architecture/current/route-session-concurrency.md +85 -0
  203. package/docs/architecture/current/runtime-architecture-simplification.md +214 -0
  204. package/docs/architecture/current/runtime-directory-map.md +49 -0
  205. package/docs/architecture/current/runtime-health-and-resource-lifecycle.md +85 -0
  206. package/docs/architecture/current/scheduler-and-resource-claims.md +432 -0
  207. package/docs/architecture/current/session-aware-execution-and-authorization.md +77 -0
  208. package/docs/architecture/current/system-overview.md +144 -0
  209. package/docs/architecture/current/target-requirements-traceability.md +202 -0
  210. package/docs/architecture/current/thin-harness-governance-policy.md +32 -0
  211. package/docs/architecture/current/thin-harness-v1.md +313 -0
  212. package/docs/architecture/current/verification-and-release-gates.md +391 -0
  213. package/docs/architecture/decisions/20260801-controller-home-sqlite-state.md +100 -0
  214. package/docs/architecture/decisions/20260803-canonical-skill-surface.md +40 -0
  215. package/docs/architecture/decisions/20260803-release-identity-binding-and-exit-policy.md +53 -0
  216. package/docs/architecture/diagrams/.gitkeep +1 -0
  217. package/docs/architecture/diagrams/agentic-dev-plugin-architecture.html +186 -0
  218. package/docs/architecture/domains/.gitkeep +0 -0
  219. package/docs/architecture/domains/public-surface.md +30 -0
  220. package/docs/architecture/domains/runtime-harness.md +33 -0
  221. package/docs/architecture/domains/verification.md +33 -0
  222. package/docs/architecture/domains/workflow-engine.md +30 -0
  223. package/docs/architecture/global-hook-runtime.md +162 -0
  224. package/docs/architecture/history.md +38 -0
  225. package/docs/architecture/index.md +114 -0
  226. package/docs/architecture/ios-semantic-automation-provider-v2.md +166 -0
  227. package/docs/architecture/modules/.gitkeep +0 -0
  228. package/docs/architecture/modules/controller-runtime/transport-lifecycle.md +24 -0
  229. package/docs/architecture/requests/.gitkeep +1 -0
  230. package/docs/architecture/requests/archive/2026/20260528-154740-ai-hooks-ai-hooks-hook-input-sh.md +59 -0
  231. package/docs/architecture/requests/archive/2026/20260528-154816-assets-hooks-assets-hooks-hook-input-sh.md +59 -0
  232. package/docs/architecture/requests/archive/2026/20260528-161851-ai-harness-workflow-contract-json-ai-harness-workflow-contract-json.md +59 -0
  233. package/docs/architecture/requests/archive/2026/20260528-161853-scripts-check-task-workflow-sh-scripts-check-task-workflow-sh.md +59 -0
  234. package/docs/architecture/requests/archive/2026/20260528-161911-assets-workflow-contract-v1-json-assets-workflow-contract-v1-json.md +59 -0
  235. package/docs/architecture/requests/archive/2026/20260528-222416-ai-hooks-ai-hooks-hook-input-sh.md +59 -0
  236. package/docs/architecture/requests/archive/2026/20260528-222444-ai-hooks-ai-hooks-pre-edit-guard-sh.md +59 -0
  237. package/docs/architecture/requests/archive/2026/20260528-222457-ai-hooks-ai-hooks-pre-edit-guard-sh.md +59 -0
  238. package/docs/architecture/requests/archive/2026/20260528-222648-ai-hooks-ai-hooks-pre-edit-guard-sh.md +59 -0
  239. package/docs/architecture/requests/archive/2026/20260528-222705-ai-hooks-ai-hooks-worktree-guard-sh.md +59 -0
  240. package/docs/architecture/requests/archive/2026/20260528-222726-ai-hooks-ai-hooks-prompt-guard-sh.md +59 -0
  241. package/docs/architecture/requests/archive/2026/20260528-222727-ai-hooks-ai-hooks-prompt-guard-sh.md +59 -0
  242. package/docs/architecture/requests/archive/2026/20260528-224736-ai-hooks-ai-hooks-hook-input-sh.md +59 -0
  243. package/docs/architecture/requests/archive/2026/20260528-233259-ai-hooks-ai-hooks-prompt-guard-sh.md +59 -0
  244. package/docs/architecture/requests/archive/2026/20260528-233335-assets-hooks-assets-hooks-prompt-guard-sh.md +59 -0
  245. package/docs/architecture/requests/archive/2026/20260528-233456-ai-hooks-ai-hooks-prompt-guard-sh.md +59 -0
  246. package/docs/architecture/requests/archive/2026/20260528-233457-assets-hooks-assets-hooks-prompt-guard-sh.md +59 -0
  247. package/docs/architecture/requests/archive/2026/20260528-233637-ai-hooks-ai-hooks-prompt-guard-sh.md +59 -0
  248. package/docs/architecture/requests/archive/2026/20260528-233638-assets-hooks-assets-hooks-prompt-guard-sh.md +59 -0
  249. package/docs/architecture/requests/archive/2026/20260529-000322-root-package-json.md +59 -0
  250. package/docs/architecture/requests/archive/2026/20260529-004238-ai-hooks-ai-hooks-lib-workflow-state-sh.md +59 -0
  251. package/docs/architecture/requests/archive/2026/20260529-020654-ai-harness-policy-json-ai-harness-policy-json.md +63 -0
  252. package/docs/architecture/requests/archive/2026/20260529-094236-ai-hooks-ai-hooks-prompt-guard-sh.md +60 -0
  253. package/docs/architecture/requests/archive/2026/20260529-094323-assets-hooks-assets-hooks-prompt-guard-sh.md +60 -0
  254. package/docs/architecture/requests/archive/2026/20260529-094331-ai-hooks-ai-hooks-prompt-guard-sh.md +60 -0
  255. package/docs/architecture/requests/archive/2026/20260529-094339-assets-hooks-assets-hooks-prompt-guard-sh.md +60 -0
  256. package/docs/architecture/requests/archive/2026/20260529-094430-assets-hooks-assets-hooks-session-start-context-sh.md +60 -0
  257. package/docs/architecture/requests/archive/2026/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md +60 -0
  258. package/docs/architecture/requests/archive/2026/20260613-002040-runtime-harness-hook-adapters.md +68 -0
  259. package/docs/architecture/requests/archive/2026/root.md +68 -0
  260. package/docs/architecture/requests/archive/2026/runtime-harness-hook-adapters.md +76 -0
  261. package/docs/architecture/requests/archive/2026/verification-evals-checks.md +68 -0
  262. package/docs/architecture/requests/archive/2026/workflow-engine-contract-assets.md +69 -0
  263. package/docs/architecture/reviews/2026-07-11-access-surface-review.md +99 -0
  264. package/docs/architecture/snapshots/.gitkeep +1 -0
  265. package/docs/forge-autonomous-goal-loop.md +7 -0
  266. package/docs/forge-chatgpt-browser-engine.md +11 -0
  267. package/docs/forge-chatgpt-mcp-setup.md +239 -0
  268. package/docs/forge-chatgpt-supervised-automation.md +11 -0
  269. package/docs/forge-github-issue-launcher.md +7 -0
  270. package/docs/forge-plugin-management.md +95 -0
  271. package/docs/forge-provider-configuration.md +7 -0
  272. package/docs/forge-runtime-self-healing-loop.md +7 -0
  273. package/docs/images/forge-banner-cn.svg +1 -0
  274. package/docs/images/forge-banner.svg +1 -0
  275. package/docs/images/forge-controller-flow.svg +1 -0
  276. package/docs/images/image.png +0 -0
  277. package/docs/images/repo-harness-gptpro-cn.png +0 -0
  278. package/docs/images/repo-harness-gptpro.png +0 -0
  279. package/docs/images/repo-harness-hook-carrot.png +0 -0
  280. package/docs/operations/chatgpt-personal-assistant-runtime.md +83 -0
  281. package/docs/operations/checkout-route-integrity.md +22 -0
  282. package/docs/operations/controller-browser-plugin.md +299 -0
  283. package/docs/operations/controller-desktop-plugin.md +112 -0
  284. package/docs/operations/controller-performance-and-502.md +126 -0
  285. package/docs/operations/controller-reliability-runbook.md +134 -0
  286. package/docs/operations/environment-hardening.md +50 -0
  287. package/docs/operations/features.md +45 -0
  288. package/docs/operations/features.zh-CN.md +45 -0
  289. package/docs/operations/github-repository.md +60 -0
  290. package/docs/operations/gmail-assistant-routines.md +186 -0
  291. package/docs/operations/homebrew.md +26 -0
  292. package/docs/operations/local-system-assistant.md +46 -0
  293. package/docs/operations/local-system-assistant.zh-CN.md +46 -0
  294. package/docs/operations/mcp-tool-exposure.md +58 -0
  295. package/docs/operations/mobile-intents-shortcuts.md +117 -0
  296. package/docs/operations/open-source-release-hygiene.md +31 -0
  297. package/docs/operations/personal-assistant-operator-guide.md +61 -0
  298. package/docs/operations/platform-support.md +62 -0
  299. package/docs/operations/platform-support.zh-CN.md +61 -0
  300. package/docs/operations/provider-configuration.md +31 -0
  301. package/docs/operations/releasing.md +86 -0
  302. package/docs/operations/releasing.zh-CN.md +86 -0
  303. package/docs/operations/route-session-concurrency-baseline.json +893 -0
  304. package/docs/operations/route-session-concurrency-baseline.md +94 -0
  305. package/docs/operations/runtime-performance-diagnostics.md +14 -0
  306. package/docs/operations/sqlite-control-plane-recovery.md +65 -0
  307. package/docs/operations/standalone-disaster-recovery.md +136 -0
  308. package/docs/operations/troubleshooting.md +72 -0
  309. package/docs/operations/troubleshooting.zh-CN.md +70 -0
  310. package/docs/public-usage-guide.md +33 -0
  311. package/docs/public-usage-guide.zh-CN.md +33 -0
  312. package/docs/tutorials/01-install-and-start.md +93 -0
  313. package/docs/tutorials/01-install-and-start.zh-CN.md +93 -0
  314. package/docs/tutorials/02-connect-chatgpt.md +82 -0
  315. package/docs/tutorials/02-connect-chatgpt.zh-CN.md +80 -0
  316. package/docs/tutorials/03-first-repository-task.md +57 -0
  317. package/docs/tutorials/03-first-repository-task.zh-CN.md +57 -0
  318. package/docs/tutorials/README.md +13 -0
  319. package/docs/tutorials/README.zh-CN.md +13 -0
  320. package/docs/wiki/Architecture.md +85 -0
  321. package/docs/wiki/Core-Concepts.md +27 -0
  322. package/docs/wiki/Home.md +36 -0
  323. package/docs/wiki/Implementation.md +172 -0
  324. package/docs/wiki/Installation.md +50 -0
  325. package/docs/wiki/Integrations.md +29 -0
  326. package/docs/wiki/Operations.md +26 -0
  327. package/docs/wiki/Quick-Start.md +46 -0
  328. package/docs/wiki/Releases-and-Upgrades.md +34 -0
  329. package/docs/wiki/Runtime-Architecture.md +50 -0
  330. package/docs/wiki/Security-Model.md +31 -0
  331. package/docs/wiki/Troubleshooting.md +38 -0
  332. package/docs/wiki/Work-Lifecycle.md +31 -0
  333. package/docs/wiki/_Sidebar.md +21 -0
  334. package/install.ps1 +48 -0
  335. package/install.sh +66 -0
  336. package/package.json +156 -0
  337. package/scripts/activate-source-baseline.ts +335 -0
  338. package/scripts/architecture-event.ts +822 -0
  339. package/scripts/architecture-queue.sh +647 -0
  340. package/scripts/archive-architecture-request.sh +244 -0
  341. package/scripts/archive-workflow.sh +295 -0
  342. package/scripts/assemble-template.ts +1172 -0
  343. package/scripts/benchmark-controller-hotpath.ts +212 -0
  344. package/scripts/benchmark-controller-round2.ts +139 -0
  345. package/scripts/benchmark-ios-agent-device.ts +514 -0
  346. package/scripts/benchmark-route-session-concurrency.ts +714 -0
  347. package/scripts/benchmark-thin-harness-gateway-ab.ts +632 -0
  348. package/scripts/benchmark-thin-harness-mcp-e2e.ts +479 -0
  349. package/scripts/benchmark-thin-harness.ts +251 -0
  350. package/scripts/bootstrap-runtime-maintenance-recovery.sh +183 -0
  351. package/scripts/canary-global-hook.sh +263 -0
  352. package/scripts/capability-config.ts +394 -0
  353. package/scripts/capability-resolver.ts +505 -0
  354. package/scripts/capture-plan.sh +335 -0
  355. package/scripts/check-agent-tooling.sh +1549 -0
  356. package/scripts/check-architecture-sync.sh +373 -0
  357. package/scripts/check-brain-manifest.sh +255 -0
  358. package/scripts/check-ci.sh +16 -0
  359. package/scripts/check-context-files.sh +49 -0
  360. package/scripts/check-deploy-sql-order.sh +117 -0
  361. package/scripts/check-mcp-compatibility.ts +93 -0
  362. package/scripts/check-npm-release.sh +32 -0
  363. package/scripts/check-open-source-tracked-surface.sh +146 -0
  364. package/scripts/check-package-identity.mjs +117 -0
  365. package/scripts/check-platform-support.mjs +79 -0
  366. package/scripts/check-public-docs.sh +105 -0
  367. package/scripts/check-public-release-surface.sh +19 -0
  368. package/scripts/check-release-published.sh +57 -0
  369. package/scripts/check-release-readiness.sh +43 -0
  370. package/scripts/check-release-version.mjs +74 -0
  371. package/scripts/check-runtime-architecture.mjs +593 -0
  372. package/scripts/check-runtime-env.mjs +89 -0
  373. package/scripts/check-skill-version.ts +193 -0
  374. package/scripts/check-tarball-install-smoke.sh +66 -0
  375. package/scripts/check-task-sync.sh +65 -0
  376. package/scripts/check-task-workflow.sh +1002 -0
  377. package/scripts/check-third-party-notices.mjs +36 -0
  378. package/scripts/codex-handoff-resume.sh +269 -0
  379. package/scripts/complete-control-plane-cutover.ts +126 -0
  380. package/scripts/context-contract-sync.sh +516 -0
  381. package/scripts/contract-run.ts +465 -0
  382. package/scripts/contract-worktree.sh +725 -0
  383. package/scripts/controller-ngrok-rotation.sh +678 -0
  384. package/scripts/create-project-dirs.sh +282 -0
  385. package/scripts/ensure-codegraph.sh +16 -0
  386. package/scripts/ensure-task-workflow.sh +1218 -0
  387. package/scripts/export-requirement-portfolio.ts +28 -0
  388. package/scripts/factor-lab-check.sh +73 -0
  389. package/scripts/factor-lab-new.sh +96 -0
  390. package/scripts/factor-lab-promote.sh +86 -0
  391. package/scripts/factor-lab-reject.sh +68 -0
  392. package/scripts/harness-trace-grade.sh +150 -0
  393. package/scripts/heartbeat-triage.sh +361 -0
  394. package/scripts/hook-dispatch-diet-report.ts +234 -0
  395. package/scripts/hook-shim.sh +93 -0
  396. package/scripts/init-project.sh +505 -0
  397. package/scripts/initializer-question-pack.ts +200 -0
  398. package/scripts/inspect-project-state.ts +280 -0
  399. package/scripts/install-desktop-operator-registration.ts +45 -0
  400. package/scripts/install-standalone-recovery.ts +74 -0
  401. package/scripts/lib/AGENTS.md +13 -0
  402. package/scripts/lib/CLAUDE.md +13 -0
  403. package/scripts/lib/controller-home-env.sh +69 -0
  404. package/scripts/lib/project-init-lib.sh +2759 -0
  405. package/scripts/load-standalone-recovery.sh +17 -0
  406. package/scripts/loop-engine-cutover-gate.ts +324 -0
  407. package/scripts/maintenance-triage.sh +167 -0
  408. package/scripts/migrate-project-template.sh +1189 -0
  409. package/scripts/migrate-requirement-portfolio.ts +86 -0
  410. package/scripts/migrate-workflow-docs.ts +413 -0
  411. package/scripts/new-plan.sh +183 -0
  412. package/scripts/new-spec.sh +50 -0
  413. package/scripts/new-sprint.sh +49 -0
  414. package/scripts/open-source-audit-allowlist.txt +46 -0
  415. package/scripts/package-source-archive.sh +147 -0
  416. package/scripts/plan-to-todo.sh +799 -0
  417. package/scripts/prepare-codex-handoff.sh +203 -0
  418. package/scripts/prepare-handoff.sh +81 -0
  419. package/scripts/public-release-files.txt +39 -0
  420. package/scripts/public-release.ts +174 -0
  421. package/scripts/publish-release-tarball.sh +27 -0
  422. package/scripts/refresh-current-status.sh +469 -0
  423. package/scripts/refresh-ios-physical-runtime.ts +196 -0
  424. package/scripts/repair-executable-modes.ts +8 -0
  425. package/scripts/rollout-all-registered-repos.sh +7 -0
  426. package/scripts/route-nl-vs-ts-eval.ts +679 -0
  427. package/scripts/run-bun-test-file.ts +182 -0
  428. package/scripts/run-governed-gate.ts +140 -0
  429. package/scripts/run-mobile-monitor-bridge.ts +71 -0
  430. package/scripts/run-skill-evals.ts +1022 -0
  431. package/scripts/run-skill-hook.ts +244 -0
  432. package/scripts/run-supervised-command.ts +24 -0
  433. package/scripts/run-tests-portable.sh +20 -0
  434. package/scripts/select-agent-context-blocks.sh +66 -0
  435. package/scripts/setup-plugins.sh +43 -0
  436. package/scripts/ship-worktrees.sh +561 -0
  437. package/scripts/smoke-browser-cdp-bridge.ts +93 -0
  438. package/scripts/smoke-chatgpt-supervised-automation.ts +208 -0
  439. package/scripts/smoke-ios-physical-device.ts +114 -0
  440. package/scripts/smoke-mcp-http-runtime.ts +216 -0
  441. package/scripts/smoke-mcp-tool-surface.ts +117 -0
  442. package/scripts/smoke-runtime-recovery.ts +220 -0
  443. package/scripts/smoke-schedule-engine.ts +283 -0
  444. package/scripts/sprint-backlog.sh +837 -0
  445. package/scripts/stage-runtime-release.ts +38 -0
  446. package/scripts/summarize-failures.sh +125 -0
  447. package/scripts/switch-plan.sh +153 -0
  448. package/scripts/sync-brain-docs.sh +381 -0
  449. package/scripts/sync-codex-installed-copies.sh +183 -0
  450. package/scripts/test-governance.ts +75 -0
  451. package/scripts/verify-contract.sh +705 -0
  452. package/scripts/verify-forge-runtime.sh +31 -0
  453. package/scripts/verify-sprint.sh +680 -0
  454. package/scripts/windows-paths.d.mts +7 -0
  455. package/scripts/windows-paths.mjs +28 -0
  456. package/scripts/workflow-contract.ts +206 -0
  457. package/scripts/workstream-sync.sh +263 -0
  458. package/src/cli/agent-jobs/executable-resolver.ts +289 -0
  459. package/src/cli/agent-jobs/executor-health.ts +252 -0
  460. package/src/cli/agent-jobs/integration.ts +963 -0
  461. package/src/cli/agent-jobs/job-manager.ts +2030 -0
  462. package/src/cli/agent-jobs/types.ts +219 -0
  463. package/src/cli/agent-jobs/worker-lifecycle.ts +288 -0
  464. package/src/cli/chatgpt-browser/bind-server.ts +504 -0
  465. package/src/cli/chatgpt-browser/binding.ts +140 -0
  466. package/src/cli/chatgpt-browser/bridge-extension.ts +221 -0
  467. package/src/cli/chatgpt-browser/bridge-provider.ts +268 -0
  468. package/src/cli/chatgpt-browser/engine.ts +569 -0
  469. package/src/cli/chatgpt-browser/file-policy.ts +158 -0
  470. package/src/cli/chatgpt-browser/native-provider.ts +553 -0
  471. package/src/cli/chatgpt-browser/oracle-provider.ts +437 -0
  472. package/src/cli/chatgpt-browser/prompt-assembler.ts +29 -0
  473. package/src/cli/chatgpt-browser/session-store.ts +301 -0
  474. package/src/cli/chatgpt-browser/types.ts +172 -0
  475. package/src/cli/commands/adopt-plan.ts +186 -0
  476. package/src/cli/commands/brain-root.ts +132 -0
  477. package/src/cli/commands/brain.ts +609 -0
  478. package/src/cli/commands/capability-context.ts +613 -0
  479. package/src/cli/commands/chatgpt.ts +424 -0
  480. package/src/cli/commands/controller.ts +680 -0
  481. package/src/cli/commands/docs.ts +103 -0
  482. package/src/cli/commands/doctor.ts +476 -0
  483. package/src/cli/commands/global-runtime.ts +323 -0
  484. package/src/cli/commands/hook.ts +34 -0
  485. package/src/cli/commands/init-hook.ts +870 -0
  486. package/src/cli/commands/init.ts +829 -0
  487. package/src/cli/commands/install.ts +86 -0
  488. package/src/cli/commands/mcp.ts +315 -0
  489. package/src/cli/commands/migrate.ts +154 -0
  490. package/src/cli/commands/plugin.ts +74 -0
  491. package/src/cli/commands/prompt-guard-decision.ts +238 -0
  492. package/src/cli/commands/recovery.ts +667 -0
  493. package/src/cli/commands/repository.ts +224 -0
  494. package/src/cli/commands/run.ts +23 -0
  495. package/src/cli/commands/runtime.ts +191 -0
  496. package/src/cli/commands/security.ts +440 -0
  497. package/src/cli/commands/status.ts +137 -0
  498. package/src/cli/commands/tools.ts +167 -0
  499. package/src/cli/controller/check-runner.ts +1022 -0
  500. package/src/cli/controller/codex-continuation.ts +153 -0
  501. package/src/cli/controller/completion-backlog.ts +380 -0
  502. package/src/cli/controller/completion-orchestrator.ts +1807 -0
  503. package/src/cli/controller/completion-target.ts +96 -0
  504. package/src/cli/controller/composite-operations.ts +196 -0
  505. package/src/cli/controller/composite-result.ts +130 -0
  506. package/src/cli/controller/context-pack.ts +652 -0
  507. package/src/cli/controller/execution-completion.ts +175 -0
  508. package/src/cli/controller/execution-policy.ts +392 -0
  509. package/src/cli/controller/governance.ts +594 -0
  510. package/src/cli/controller/issue-store.ts +1421 -0
  511. package/src/cli/controller/launch-agents.ts +410 -0
  512. package/src/cli/controller/legacy-issue-cutover.ts +415 -0
  513. package/src/cli/controller/lifecycle-authority.ts +16 -0
  514. package/src/cli/controller/migrated-issue-decision.ts +237 -0
  515. package/src/cli/controller/operational-plan.ts +226 -0
  516. package/src/cli/controller/postcondition.ts +134 -0
  517. package/src/cli/controller/progress.ts +656 -0
  518. package/src/cli/controller/project-state.ts +147 -0
  519. package/src/cli/controller/requirement-portfolio-export.ts +146 -0
  520. package/src/cli/controller/requirement-portfolio-migration.ts +613 -0
  521. package/src/cli/controller/run-evidence.ts +43 -0
  522. package/src/cli/controller/runtime-config.ts +92 -0
  523. package/src/cli/controller/stuck-state-migration.ts +396 -0
  524. package/src/cli/controller/task-ledger.ts +632 -0
  525. package/src/cli/controller/task-status-resolver.ts +403 -0
  526. package/src/cli/controller/types.ts +273 -0
  527. package/src/cli/controller/work-mode.ts +186 -0
  528. package/src/cli/controller/worklog.ts +201 -0
  529. package/src/cli/diagnostic-entry.ts +39 -0
  530. package/src/cli/editing/edit-session.ts +1606 -0
  531. package/src/cli/editing/executable-modes.ts +70 -0
  532. package/src/cli/github/github.ts +274 -0
  533. package/src/cli/github/plugin.ts +345 -0
  534. package/src/cli/github/session.ts +104 -0
  535. package/src/cli/hook/prompt-guard-decision.ts +238 -0
  536. package/src/cli/hook/prompt-intents.ts +534 -0
  537. package/src/cli/hook/route-registry.ts +107 -0
  538. package/src/cli/hook/runtime.ts +303 -0
  539. package/src/cli/hook/state-snapshot.ts +388 -0
  540. package/src/cli/hook-entry.ts +51 -0
  541. package/src/cli/index.ts +574 -0
  542. package/src/cli/installer/managed-entries.ts +78 -0
  543. package/src/cli/installer/shared.ts +65 -0
  544. package/src/cli/installer/targets/claude.ts +136 -0
  545. package/src/cli/installer/targets/codex.ts +174 -0
  546. package/src/cli/installer/targets/registry.ts +28 -0
  547. package/src/cli/installer/types.ts +72 -0
  548. package/src/cli/local-bridge/connector-freshness.ts +529 -0
  549. package/src/cli/local-bridge/console-view-models.ts +324 -0
  550. package/src/cli/local-bridge/dashboard.ts +1312 -0
  551. package/src/cli/local-bridge/facade-api.ts +1877 -0
  552. package/src/cli/local-bridge/job-store.ts +1451 -0
  553. package/src/cli/local-bridge/mobile-intents.ts +344 -0
  554. package/src/cli/local-bridge/mobile-monitor.ts +209 -0
  555. package/src/cli/local-bridge/server.ts +3183 -0
  556. package/src/cli/local-bridge/types.ts +176 -0
  557. package/src/cli/mcp/access-mode.ts +132 -0
  558. package/src/cli/mcp/access-tools.ts +387 -0
  559. package/src/cli/mcp/audit.ts +32 -0
  560. package/src/cli/mcp/auth.ts +402 -0
  561. package/src/cli/mcp/instructions.ts +33 -0
  562. package/src/cli/mcp/legacy-context.ts +16 -0
  563. package/src/cli/mcp/legacy-tool-service.ts +5516 -0
  564. package/src/cli/mcp/multi-repository.ts +423 -0
  565. package/src/cli/mcp/oauth.ts +226 -0
  566. package/src/cli/mcp/paths.ts +134 -0
  567. package/src/cli/mcp/policy.ts +230 -0
  568. package/src/cli/mcp/proxy-env.ts +62 -0
  569. package/src/cli/mcp/readiness-projection.ts +24 -0
  570. package/src/cli/mcp/redaction.ts +21 -0
  571. package/src/cli/mcp/repo.ts +24 -0
  572. package/src/cli/mcp/repository-tools.ts +1295 -0
  573. package/src/cli/mcp/server.ts +341 -0
  574. package/src/cli/mcp/setup.ts +793 -0
  575. package/src/cli/mcp/tool-capability-cache.ts +87 -0
  576. package/src/cli/mcp/tools.ts +9 -0
  577. package/src/cli/mcp/toolset-names.ts +70 -0
  578. package/src/cli/mcp/toolset-selection.ts +41 -0
  579. package/src/cli/mcp/toolset.ts +300 -0
  580. package/src/cli/mcp/transports/AGENTS.md +39 -0
  581. package/src/cli/mcp/transports/CLAUDE.md +39 -0
  582. package/src/cli/mcp/transports/http.ts +1234 -0
  583. package/src/cli/mcp/transports/session-registry.ts +428 -0
  584. package/src/cli/mcp/transports/stdio.ts +8 -0
  585. package/src/cli/mcp/types.ts +41 -0
  586. package/src/cli/mcp/umbrella-tools.ts +117 -0
  587. package/src/cli/repo-adoption/reclaim-runtime.ts +681 -0
  588. package/src/cli/repositories/branch-name-policy.ts +57 -0
  589. package/src/cli/repositories/command-classifier.ts +600 -0
  590. package/src/cli/repositories/command-executor.ts +1066 -0
  591. package/src/cli/repositories/command-normalization.ts +53 -0
  592. package/src/cli/repositories/command-scope.ts +264 -0
  593. package/src/cli/repositories/controller-home.ts +88 -0
  594. package/src/cli/repositories/entity-migration.ts +199 -0
  595. package/src/cli/repositories/ephemeral-workspace.ts +62 -0
  596. package/src/cli/repositories/git-command-executor.ts +301 -0
  597. package/src/cli/repositories/goal-registry.ts +239 -0
  598. package/src/cli/repositories/identity.ts +64 -0
  599. package/src/cli/repositories/local-project-onboarding.ts +539 -0
  600. package/src/cli/repositories/locks.ts +262 -0
  601. package/src/cli/repositories/registry.ts +1057 -0
  602. package/src/cli/repositories/runtime-storage.ts +411 -0
  603. package/src/cli/repositories/safe-patch.ts +421 -0
  604. package/src/cli/repositories/selected-path-actions.ts +341 -0
  605. package/src/cli/repositories/structured-git.ts +257 -0
  606. package/src/cli/repositories/types.ts +155 -0
  607. package/src/cli/repositories/umbrella.ts +134 -0
  608. package/src/cli/repositories/workbench.ts +140 -0
  609. package/src/cli/repositories/worktree-storage.ts +137 -0
  610. package/src/cli/repository/inspector.ts +637 -0
  611. package/src/cli/repository/session-cache.ts +453 -0
  612. package/src/cli/runtime/helper-runner.ts +172 -0
  613. package/src/cli/runtime-invocation.ts +318 -0
  614. package/src/cli/tools/codegraph.ts +676 -0
  615. package/src/cli/v81-entry.ts +29 -0
  616. package/src/core/adoption/gitignore-plan.ts +127 -0
  617. package/src/core/adoption/helper-wrapper-plan.ts +159 -0
  618. package/src/core/adoption/manifest-templates.ts +60 -0
  619. package/src/core/adoption/modes.ts +7 -0
  620. package/src/core/adoption/operations.ts +126 -0
  621. package/src/core/adoption/plan.ts +149 -0
  622. package/src/core/adoption/render.ts +70 -0
  623. package/src/core/adoption/rollback.ts +62 -0
  624. package/src/core/adoption/summary.ts +43 -0
  625. package/src/core/adoption/workflow-contract-asset.ts +14 -0
  626. package/src/core/adoption/workflow-contract-plan.ts +31 -0
  627. package/src/effects/fs-transaction.ts +540 -0
  628. package/src/effects/git-executable.ts +59 -0
  629. package/src/effects/managed-block.ts +86 -0
  630. package/src/effects/path-safety.ts +47 -0
  631. package/src/effects/process-runner.ts +192 -0
  632. package/src/runtime/assistant/action-proposals.ts +279 -0
  633. package/src/runtime/assistant/intent.ts +395 -0
  634. package/src/runtime/assistant/model-provider.ts +460 -0
  635. package/src/runtime/assistant/openapi.ts +223 -0
  636. package/src/runtime/assistant/policy.ts +89 -0
  637. package/src/runtime/assistant/readiness.ts +258 -0
  638. package/src/runtime/assistant/routine-runtime.ts +477 -0
  639. package/src/runtime/assistant/schedule-binding.ts +171 -0
  640. package/src/runtime/assistant/standing-grants.ts +375 -0
  641. package/src/runtime/assistant/store.ts +243 -0
  642. package/src/runtime/assistant/types.ts +135 -0
  643. package/src/runtime/context/codegraph-read-provider.ts +347 -0
  644. package/src/runtime/context/codegraph-sidecar.cjs +207 -0
  645. package/src/runtime/control-plane/dispatch-priority.ts +67 -0
  646. package/src/runtime/control-plane/execution/direct-edit-work-completion.ts +151 -0
  647. package/src/runtime/control-plane/execution/execution-identity.ts +456 -0
  648. package/src/runtime/control-plane/execution/session-store.ts +175 -0
  649. package/src/runtime/control-plane/execution/validation.ts +117 -0
  650. package/src/runtime/control-plane/execution/verification-evidence.ts +191 -0
  651. package/src/runtime/control-plane/execution/work-handle-store.ts +225 -0
  652. package/src/runtime/control-plane/execution/work-prepare-request-store.ts +159 -0
  653. package/src/runtime/control-plane/execution/work-task-receipt.ts +445 -0
  654. package/src/runtime/control-plane/execution/work-terminal-cleanup.ts +821 -0
  655. package/src/runtime/control-plane/facade/capability-registry.ts +279 -0
  656. package/src/runtime/control-plane/facade/check-normalization.ts +233 -0
  657. package/src/runtime/control-plane/facade/codex-delegation.ts +196 -0
  658. package/src/runtime/control-plane/facade/controller-session-store.ts +199 -0
  659. package/src/runtime/control-plane/facade/facade-result.ts +41 -0
  660. package/src/runtime/control-plane/facade/goal-workloop-access.ts +177 -0
  661. package/src/runtime/control-plane/facade/goal-workloop.ts +1216 -0
  662. package/src/runtime/control-plane/facade/handoff-inbox-store.ts +221 -0
  663. package/src/runtime/control-plane/facade/index.ts +16 -0
  664. package/src/runtime/control-plane/facade/operation-digest.ts +528 -0
  665. package/src/runtime/control-plane/facade/plan-contract-store.ts +403 -0
  666. package/src/runtime/control-plane/facade/policy-gate.ts +149 -0
  667. package/src/runtime/control-plane/facade/requirement-board.ts +280 -0
  668. package/src/runtime/control-plane/facade/self-healing-loop.ts +555 -0
  669. package/src/runtime/control-plane/facade/suggested-actions.ts +108 -0
  670. package/src/runtime/control-plane/facade/types.ts +729 -0
  671. package/src/runtime/control-plane/facade/work-admission-policy.ts +93 -0
  672. package/src/runtime/control-plane/facade/work-continuation.ts +104 -0
  673. package/src/runtime/control-plane/facade/work-contract-store.ts +1118 -0
  674. package/src/runtime/control-plane/facade/work-task-projection.ts +66 -0
  675. package/src/runtime/control-plane/global-scheduler/reconciliation.ts +365 -0
  676. package/src/runtime/control-plane/global-scheduler/scheduler.ts +920 -0
  677. package/src/runtime/control-plane/global-scheduler/wake-signal.ts +89 -0
  678. package/src/runtime/control-plane/goal-loop/config-facade.ts +700 -0
  679. package/src/runtime/control-plane/goal-loop/config-store.ts +570 -0
  680. package/src/runtime/control-plane/goal-loop/config-types.ts +213 -0
  681. package/src/runtime/control-plane/goal-loop/executor-router.ts +109 -0
  682. package/src/runtime/control-plane/goal-loop/failure-taxonomy.ts +149 -0
  683. package/src/runtime/control-plane/goal-loop/goal-contract-store.ts +304 -0
  684. package/src/runtime/control-plane/goal-loop/goal-loop-engine.ts +1001 -0
  685. package/src/runtime/control-plane/goal-loop/handoff-packet.ts +160 -0
  686. package/src/runtime/control-plane/goal-loop/index.ts +13 -0
  687. package/src/runtime/control-plane/goal-loop/local-tools.ts +290 -0
  688. package/src/runtime/control-plane/goal-loop/policy-gates.ts +203 -0
  689. package/src/runtime/control-plane/goal-loop/provider-dispatch.ts +93 -0
  690. package/src/runtime/control-plane/goal-loop/provider-registry.ts +545 -0
  691. package/src/runtime/control-plane/goal-loop/types.ts +378 -0
  692. package/src/runtime/control-plane/governance/access-policy.ts +147 -0
  693. package/src/runtime/control-plane/governance/authorization.ts +195 -0
  694. package/src/runtime/control-plane/governance/external-effects.ts +43 -0
  695. package/src/runtime/control-plane/launcher/thin-launcher.ts +97 -0
  696. package/src/runtime/control-plane/persistence/metadata-payload-policy.ts +53 -0
  697. package/src/runtime/control-plane/persistence/requirement-store.ts +241 -0
  698. package/src/runtime/control-plane/persistence/sqlite-store.ts +539 -0
  699. package/src/runtime/control-plane/release-retention.ts +447 -0
  700. package/src/runtime/control-plane/repo-actor/actor.ts +181 -0
  701. package/src/runtime/control-plane/repo-actor/registry.ts +20 -0
  702. package/src/runtime/control-plane/routing/index.ts +1 -0
  703. package/src/runtime/control-plane/routing/route-policy.ts +379 -0
  704. package/src/runtime/control-plane/runtime-cleanup.ts +727 -0
  705. package/src/runtime/control-plane/runtime-generation.ts +509 -0
  706. package/src/runtime/control-plane/runtime-pid-ownership.ts +11 -0
  707. package/src/runtime/control-plane/runtime-status-client.ts +90 -0
  708. package/src/runtime/control-plane/startup-recovery.ts +198 -0
  709. package/src/runtime/diagnostics/connectivity-observability.ts +475 -0
  710. package/src/runtime/diagnostics/mcp-timing.ts +64 -0
  711. package/src/runtime/diagnostics/performance.ts +379 -0
  712. package/src/runtime/diagnostics/process-facade.ts +350 -0
  713. package/src/runtime/diagnostics/read-only-tool.ts +226 -0
  714. package/src/runtime/evidence/artifact-store.ts +154 -0
  715. package/src/runtime/evidence/event-ledger.ts +80 -0
  716. package/src/runtime/evidence/evidence-store.ts +68 -0
  717. package/src/runtime/evidence/process-check-receipt.ts +43 -0
  718. package/src/runtime/evidence/result-store.ts +209 -0
  719. package/src/runtime/evidence/sensitive-output.ts +353 -0
  720. package/src/runtime/execution/jobs/child-reference.ts +124 -0
  721. package/src/runtime/execution/jobs/legacy-adapter.ts +22 -0
  722. package/src/runtime/execution/jobs/receipt-recovery.ts +119 -0
  723. package/src/runtime/execution/jobs/receipt-store.ts +243 -0
  724. package/src/runtime/execution/jobs/store.ts +737 -0
  725. package/src/runtime/execution/jobs/timeouts.ts +109 -0
  726. package/src/runtime/execution/jobs/types.ts +230 -0
  727. package/src/runtime/execution/jobs/wait.ts +45 -0
  728. package/src/runtime/execution/process-runtime/canary.ts +26 -0
  729. package/src/runtime/execution/process-runtime/check-facade.ts +272 -0
  730. package/src/runtime/execution/process-runtime/check-receipt.ts +185 -0
  731. package/src/runtime/execution/process-runtime/check-runner-sidecar.ts +60 -0
  732. package/src/runtime/execution/process-runtime/command-facade.ts +321 -0
  733. package/src/runtime/execution/process-runtime/gc.ts +171 -0
  734. package/src/runtime/execution/process-runtime/index.ts +9 -0
  735. package/src/runtime/execution/process-runtime/interactive-admission.ts +23 -0
  736. package/src/runtime/execution/process-runtime/process-runner-entry.ts +466 -0
  737. package/src/runtime/execution/process-runtime/resource-claims.ts +440 -0
  738. package/src/runtime/execution/process-runtime/runtime.ts +1816 -0
  739. package/src/runtime/execution/process-runtime/store.ts +687 -0
  740. package/src/runtime/execution/process-runtime/types.ts +352 -0
  741. package/src/runtime/execution/thin-harness/async-process.ts +181 -0
  742. package/src/runtime/execution/thin-harness/batch-executor.ts +671 -0
  743. package/src/runtime/execution/thin-harness/execution-router.ts +700 -0
  744. package/src/runtime/execution/thin-harness/fast-executor.ts +1263 -0
  745. package/src/runtime/execution/thin-harness/fast-receipt.ts +235 -0
  746. package/src/runtime/execution/thin-harness/fingerprint-worker.ts +191 -0
  747. package/src/runtime/execution/thin-harness/index.ts +13 -0
  748. package/src/runtime/execution/thin-harness/latency-trace.ts +107 -0
  749. package/src/runtime/execution/thin-harness/lightweight-lanes.ts +745 -0
  750. package/src/runtime/execution/thin-harness/mutation-gate.ts +578 -0
  751. package/src/runtime/execution/thin-harness/proposal-store.ts +409 -0
  752. package/src/runtime/execution/thin-harness/request-ledger.ts +595 -0
  753. package/src/runtime/execution/thin-harness/search-worker.ts +114 -0
  754. package/src/runtime/execution/thin-harness/types.ts +313 -0
  755. package/src/runtime/execution/thin-harness/workspace-savepoint.ts +333 -0
  756. package/src/runtime/execution/workers/executor.ts +687 -0
  757. package/src/runtime/execution/workers/ownership.ts +94 -0
  758. package/src/runtime/execution/workers/worker-entry.ts +277 -0
  759. package/src/runtime/gateway/mcp/execution-tools.ts +2009 -0
  760. package/src/runtime/gateway/mcp/persisted-check-process.ts +255 -0
  761. package/src/runtime/gateway/mcp/process-tools.ts +230 -0
  762. package/src/runtime/gateway/mcp/resource-policy.ts +195 -0
  763. package/src/runtime/gateway/mcp/router.ts +1088 -0
  764. package/src/runtime/gateway/mcp/runtime-tools.ts +5994 -0
  765. package/src/runtime/gateway/mcp/work-validation-reconciler.ts +219 -0
  766. package/src/runtime/health/evaluator.ts +474 -0
  767. package/src/runtime/health/index.ts +2 -0
  768. package/src/runtime/health/operational-view.ts +198 -0
  769. package/src/runtime/maintenance/cleanup.ts +419 -0
  770. package/src/runtime/model-clients/deepseek-adapter.ts +312 -0
  771. package/src/runtime/model-clients/index.ts +2 -0
  772. package/src/runtime/model-clients/types.ts +101 -0
  773. package/src/runtime/observability/gateway-contention-metrics.ts +129 -0
  774. package/src/runtime/observability/route-session-benchmark.ts +110 -0
  775. package/src/runtime/personal-assistant/gmail-triage-manager.ts +231 -0
  776. package/src/runtime/personal-assistant/reporting-runtime.ts +344 -0
  777. package/src/runtime/personal-assistant/triage-runtime.ts +748 -0
  778. package/src/runtime/plugins/app-store-connect-adapter.ts +868 -0
  779. package/src/runtime/plugins/browser-adapter.ts +2812 -0
  780. package/src/runtime/plugins/browser-automation-service.ts +46 -0
  781. package/src/runtime/plugins/browser-handoff-host.ts +304 -0
  782. package/src/runtime/plugins/browser-handoff.ts +371 -0
  783. package/src/runtime/plugins/browser-macos-bridge.ts +865 -0
  784. package/src/runtime/plugins/browser-node-bridge-host.ts +64 -0
  785. package/src/runtime/plugins/browser-node-bridge.ts +249 -0
  786. package/src/runtime/plugins/desktop-adapter.ts +374 -0
  787. package/src/runtime/plugins/desktop-operator-registration.ts +418 -0
  788. package/src/runtime/plugins/errors.ts +39 -0
  789. package/src/runtime/plugins/execution-origin.ts +26 -0
  790. package/src/runtime/plugins/external-adapter.ts +322 -0
  791. package/src/runtime/plugins/external-registration.ts +308 -0
  792. package/src/runtime/plugins/external-unix-socket-probe.cjs +79 -0
  793. package/src/runtime/plugins/external-unix-socket.ts +238 -0
  794. package/src/runtime/plugins/first-party-registry.ts +37 -0
  795. package/src/runtime/plugins/github-adapter.ts +266 -0
  796. package/src/runtime/plugins/gmail-adapter.ts +729 -0
  797. package/src/runtime/plugins/google-calendar-adapter.ts +468 -0
  798. package/src/runtime/plugins/google-shared.ts +578 -0
  799. package/src/runtime/plugins/google-tasks-adapter.ts +535 -0
  800. package/src/runtime/plugins/interaction-session.ts +252 -0
  801. package/src/runtime/plugins/ios/agent-device-capabilities.ts +258 -0
  802. package/src/runtime/plugins/ios/agent-device-failures.ts +95 -0
  803. package/src/runtime/plugins/ios/agent-device-provider.ts +63 -0
  804. package/src/runtime/plugins/ios/agent-device-typed-provider.ts +268 -0
  805. package/src/runtime/plugins/ios/app-adapters.ts +122 -0
  806. package/src/runtime/plugins/ios-adapter.ts +509 -0
  807. package/src/runtime/plugins/ios-agent-device.ts +2311 -0
  808. package/src/runtime/plugins/ios-physical-device.ts +955 -0
  809. package/src/runtime/plugins/local-system-adapter.ts +1016 -0
  810. package/src/runtime/plugins/macos-capability-broker.ts +73 -0
  811. package/src/runtime/plugins/managed-process-adapter.ts +366 -0
  812. package/src/runtime/plugins/resend-adapter.ts +506 -0
  813. package/src/runtime/plugins/store.ts +1025 -0
  814. package/src/runtime/plugins/types.ts +138 -0
  815. package/src/runtime/projections/controller-context.ts +596 -0
  816. package/src/runtime/projections/git-status-sampler.ts +84 -0
  817. package/src/runtime/projections/invalidation.ts +250 -0
  818. package/src/runtime/projections/materialized-view.ts +694 -0
  819. package/src/runtime/recovery/actions.ts +158 -0
  820. package/src/runtime/recovery/audit.ts +38 -0
  821. package/src/runtime/recovery/classifier.ts +163 -0
  822. package/src/runtime/recovery/index.ts +9 -0
  823. package/src/runtime/recovery/local-jobs-repair.ts +393 -0
  824. package/src/runtime/recovery/maintenance-executor.ts +822 -0
  825. package/src/runtime/recovery/patch-handoff.ts +50 -0
  826. package/src/runtime/recovery/probe.ts +308 -0
  827. package/src/runtime/recovery/store.ts +35 -0
  828. package/src/runtime/recovery/types.ts +175 -0
  829. package/src/runtime/release/identity.ts +101 -0
  830. package/src/runtime/release/release-gate.ts +137 -0
  831. package/src/runtime/resources/claims/conflicts.ts +205 -0
  832. package/src/runtime/resources/index.ts +1 -0
  833. package/src/runtime/resources/leases/store.ts +539 -0
  834. package/src/runtime/resources/leases/types.ts +50 -0
  835. package/src/runtime/resources/ownership.ts +72 -0
  836. package/src/runtime/root/controller-services.ts +42 -0
  837. package/src/runtime/root/entry.ts +70 -0
  838. package/src/runtime/root/gateway-adapter.ts +46 -0
  839. package/src/runtime/root/local-bridge.ts +72 -0
  840. package/src/runtime/root/mcp-transport.ts +198 -0
  841. package/src/runtime/root/ownership.ts +94 -0
  842. package/src/runtime/root/readiness.ts +69 -0
  843. package/src/runtime/root/release-manifest.ts +147 -0
  844. package/src/runtime/root/release-materialize.ts +509 -0
  845. package/src/runtime/root/release-store.ts +236 -0
  846. package/src/runtime/root/runtime.ts +318 -0
  847. package/src/runtime/root/scheduler.ts +58 -0
  848. package/src/runtime/root/service-runner-entry.ts +20 -0
  849. package/src/runtime/root/service-runner.ts +69 -0
  850. package/src/runtime/root/service.ts +291 -0
  851. package/src/runtime/root/status.ts +127 -0
  852. package/src/runtime/root/types.ts +112 -0
  853. package/src/runtime/root/write-fence.ts +309 -0
  854. package/src/runtime/safe-tooling/browser-safe.ts +133 -0
  855. package/src/runtime/safe-tooling/external-filesystem.ts +304 -0
  856. package/src/runtime/safe-tooling/google-credential-store.ts +95 -0
  857. package/src/runtime/safe-tooling/google-oauth-broker.ts +286 -0
  858. package/src/runtime/safe-tooling/index.ts +11 -0
  859. package/src/runtime/safe-tooling/ios-development.ts +1039 -0
  860. package/src/runtime/safe-tooling/job-summary.ts +361 -0
  861. package/src/runtime/safe-tooling/plugin-summary.ts +53 -0
  862. package/src/runtime/safe-tooling/resend-oauth.ts +387 -0
  863. package/src/runtime/safe-tooling/review-artifacts.ts +133 -0
  864. package/src/runtime/safe-tooling/types.ts +103 -0
  865. package/src/runtime/safe-tooling/workspace-auth.ts +116 -0
  866. package/src/runtime/shared/bounded-child-supervisor.ts +235 -0
  867. package/src/runtime/shared/idempotent-retry.ts +128 -0
  868. package/src/runtime/shared/json-files.ts +43 -0
  869. package/src/runtime/shared/local-bridge-surface.ts +231 -0
  870. package/src/runtime/shared/managed-env.ts +154 -0
  871. package/src/runtime/shared/node-ts-loader.mjs +50 -0
  872. package/src/runtime/shared/process-environment.ts +97 -0
  873. package/src/runtime/shared/process-identity.ts +72 -0
  874. package/src/runtime/shared/process-tree.ts +227 -0
  875. package/src/runtime/shared/response-budget.ts +246 -0
  876. package/src/runtime/standalone-recovery/core.ts +2275 -0
  877. package/src/runtime/standalone-recovery/entry.ts +686 -0
  878. package/src/runtime/standalone-recovery/http-transport.ts +317 -0
  879. package/src/runtime/standalone-recovery/installer.ts +747 -0
  880. package/src/runtime/standalone-recovery/release.ts +241 -0
  881. package/src/runtime/watchdog/workflow-watchdog.ts +118 -0
  882. package/src/runtime/workflow/campaigns/cleanup.ts +263 -0
  883. package/src/runtime/workflow/campaigns/engine.ts +112 -0
  884. package/src/runtime/workflow/campaigns/normalize.ts +100 -0
  885. package/src/runtime/workflow/campaigns/review.ts +315 -0
  886. package/src/runtime/workflow/campaigns/store.ts +526 -0
  887. package/src/runtime/workflow/campaigns/supervisor.ts +112 -0
  888. package/src/runtime/workflow/campaigns/types.ts +290 -0
  889. package/src/runtime/workflow/campaigns/workspace-agent.ts +155 -0
  890. package/src/runtime/workflow/campaigns/workspace.ts +200 -0
  891. package/src/runtime/workflow/findings/store.ts +165 -0
  892. package/src/runtime/workflow/findings/types.ts +36 -0
  893. package/src/runtime/workflow/portfolio/engine.ts +20 -0
  894. package/src/runtime/workflow/portfolio/store.ts +185 -0
  895. package/src/runtime/workflow/portfolio/types.ts +29 -0
  896. package/src/runtime/workflow/schedules/engine.ts +620 -0
  897. package/src/runtime/workflow/schedules/settlement.ts +144 -0
  898. package/src/runtime/workflow/schedules/store.ts +417 -0
  899. package/src/runtime/workflow/schedules/types.ts +124 -0
  900. package/src/runtime/workspace-targets/index.ts +24 -0
  901. package/src/runtime/workspace-targets/target-grant.ts +721 -0
  902. package/src/testing/test-governance.ts +626 -0
  903. package/src/version.ts +21 -0
package/docs/architecture/diagrams/agentic-dev-plugin-architecture.html ADDED
@@ -0,0 +1,186 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Forge Plugin Architecture</title>
7
+ <meta name="architecture-source-md" content="docs/architecture/snapshots/2026-05-25-agentic-dev-plugin-review.md#semantic-diagram">
8
+ <style>
9
+ :root {
10
+ color-scheme: light;
11
+ --paper: #f6f7f2;
12
+ --ink: #1f2933;
13
+ --muted: #5d6673;
14
+ --rule: #c9d1d9;
15
+ --accent: #b9502a;
16
+ --blue: #2f5f8f;
17
+ --green: #4f7f55;
18
+ --font: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
19
+ --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
20
+ }
21
+ body {
22
+ margin: 0;
23
+ background: var(--paper);
24
+ color: var(--ink);
25
+ font-family: var(--font);
26
+ padding: 40px 28px;
27
+ }
28
+ main {
29
+ max-width: 1180px;
30
+ margin: 0 auto;
31
+ }
32
+ .eyebrow {
33
+ color: var(--muted);
34
+ font-family: var(--mono);
35
+ font-size: 11px;
36
+ letter-spacing: 0;
37
+ margin: 0 0 8px;
38
+ text-transform: uppercase;
39
+ }
40
+ h1 {
41
+ font-size: 34px;
42
+ line-height: 1.1;
43
+ margin: 0 0 8px;
44
+ letter-spacing: 0;
45
+ }
46
+ .subtitle {
47
+ color: var(--muted);
48
+ font-size: 15px;
49
+ line-height: 1.5;
50
+ margin: 0 0 28px;
51
+ max-width: 820px;
52
+ }
53
+ .diagram {
54
+ overflow-x: auto;
55
+ border-top: 1px solid var(--rule);
56
+ border-bottom: 1px solid var(--rule);
57
+ padding: 24px 0;
58
+ }
59
+ svg {
60
+ display: block;
61
+ min-width: 1060px;
62
+ width: 100%;
63
+ height: auto;
64
+ }
65
+ .box {
66
+ fill: #ffffff;
67
+ stroke: var(--rule);
68
+ stroke-width: 1.2;
69
+ rx: 8;
70
+ }
71
+ .source {
72
+ fill: #fff6ed;
73
+ stroke: #e3b18d;
74
+ }
75
+ .runtime {
76
+ fill: #eef7ff;
77
+ stroke: #9bbfdd;
78
+ }
79
+ .verify {
80
+ fill: #eef8ef;
81
+ stroke: #a8c9ad;
82
+ }
83
+ .label {
84
+ fill: var(--ink);
85
+ font-size: 15px;
86
+ font-weight: 700;
87
+ }
88
+ .small {
89
+ fill: var(--muted);
90
+ font-family: var(--mono);
91
+ font-size: 11px;
92
+ }
93
+ .arrow {
94
+ fill: none;
95
+ stroke: var(--muted);
96
+ stroke-width: 1.5;
97
+ marker-end: url(#arrow);
98
+ }
99
+ .accent {
100
+ stroke: var(--accent);
101
+ }
102
+ .footer {
103
+ color: var(--muted);
104
+ font-family: var(--mono);
105
+ font-size: 11px;
106
+ margin-top: 18px;
107
+ }
108
+ </style>
109
+ </head>
110
+ <body>
111
+ <main>
112
+ <p class="eyebrow">Architecture - mermaid compatible standalone HTML</p>
113
+ <h1>Forge Plugin Architecture</h1>
114
+ <p class="subtitle">Inspection-first public skill router over a contract-backed workflow engine. The source repo owns contracts, templates, helpers, hooks, command facades, and tests; generated repos receive the runtime harness.</p>
115
+ <div class="diagram">
116
+ <svg viewBox="0 0 1120 620" role="img" aria-labelledby="title desc" xmlns="http://www.w3.org/2000/svg">
117
+ <title id="title">Forge plugin architecture</title>
118
+ <desc id="desc">Request flow from public router through inspection, migration engine, contract assets, target runtime harness, and verification.</desc>
119
+ <defs>
120
+ <marker id="arrow" markerWidth="10" markerHeight="8" refX="9" refY="4" orient="auto">
121
+ <path d="M0,0 L10,4 L0,8 Z" fill="#5d6673"/>
122
+ </marker>
123
+ </defs>
124
+
125
+ <rect x="20" y="40" width="190" height="96" class="box"/>
126
+ <text x="44" y="76" class="label">User / Agent Intent</text>
127
+ <text x="44" y="102" class="small">init, scaffold, migrate</text>
128
+ <text x="44" y="120" class="small">upgrade, repair, check</text>
129
+
130
+ <rect x="260" y="40" width="230" height="116" class="box source"/>
131
+ <text x="286" y="76" class="label">Public Surface</text>
132
+ <text x="286" y="102" class="small">SKILL.md + README</text>
133
+ <text x="286" y="120" class="small">AGENTS.md / CLAUDE.md</text>
134
+ <text x="286" y="138" class="small">agentic-dev-* commands</text>
135
+
136
+ <rect x="540" y="40" width="230" height="116" class="box source"/>
137
+ <text x="566" y="76" class="label">Inspector</text>
138
+ <text x="566" y="102" class="small">inspect-project-state.ts</text>
139
+ <text x="566" y="120" class="small">mode + drift signals</text>
140
+ <text x="566" y="138" class="small">upgrade_plan</text>
141
+
142
+ <rect x="820" y="40" width="250" height="116" class="box source"/>
143
+ <text x="846" y="76" class="label">Migration Engine</text>
144
+ <text x="846" y="102" class="small">migrate-project-template.sh</text>
145
+ <text x="846" y="120" class="small">migrate-workflow-docs.ts</text>
146
+ <text x="846" y="138" class="small">project-init-lib.sh</text>
147
+
148
+ <path d="M210 88 H260" class="arrow"/>
149
+ <path d="M490 98 H540" class="arrow"/>
150
+ <path d="M770 98 H820" class="arrow"/>
151
+
152
+ <rect x="120" y="240" width="250" height="132" class="box"/>
153
+ <text x="146" y="274" class="label">Contract Assets</text>
154
+ <text x="146" y="300" class="small">workflow-contract.v1.json</text>
155
+ <text x="146" y="318" class="small">policy.json</text>
156
+ <text x="146" y="336" class="small">context-map + capabilities</text>
157
+ <text x="146" y="354" class="small">templates + reference configs</text>
158
+
159
+ <rect x="436" y="240" width="250" height="132" class="box runtime"/>
160
+ <text x="462" y="274" class="label">Target Runtime Harness</text>
161
+ <text x="462" y="300" class="small">.ai/hooks shared impl</text>
162
+ <text x="462" y="318" class="small">.claude/settings adapter</text>
163
+ <text x="462" y="336" class="small">tasks, plans, handoff</text>
164
+ <text x="462" y="354" class="small">ignored .ai/harness state</text>
165
+
166
+ <rect x="752" y="240" width="250" height="132" class="box verify"/>
167
+ <text x="778" y="274" class="label">Verification</text>
168
+ <text x="778" y="300" class="small">bun test</text>
169
+ <text x="778" y="318" class="small">check-task-workflow --strict</text>
170
+ <text x="778" y="336" class="small">migration dry-run</text>
171
+ <text x="778" y="354" class="small">eval fixtures</text>
172
+
173
+ <path d="M945 156 C945 198 245 198 245 240" class="arrow accent"/>
174
+ <path d="M370 306 H436" class="arrow"/>
175
+ <path d="M686 306 H752" class="arrow"/>
176
+ <path d="M877 372 C877 464 374 464 374 156" class="arrow"/>
177
+
178
+ <rect x="120" y="470" width="882" height="86" class="box"/>
179
+ <text x="146" y="506" class="label">Compatibility Boundary</text>
180
+ <text x="146" y="532" class="small">Canonical name: agentic-dev. Compatibility alias: agentic-dev-skill. Retired project-initializer install paths are cleanup targets. CodeGraph is required readiness.</text>
181
+ </svg>
182
+ </div>
183
+ <p class="footer">Generated 2026-05-25. Standalone HTML with inline SVG; no JavaScript. Semantic source: docs/architecture/snapshots/2026-05-25-agentic-dev-plugin-review.md#semantic-diagram.</p>
184
+ </main>
185
+ </body>
186
+ </html>
package/docs/architecture/domains/.gitkeep ADDED
File without changes
package/docs/architecture/domains/public-surface.md ADDED
@@ -0,0 +1,30 @@
1
+ # Architecture Domain: Public Surface
2
+
3
+ > **Source**: `.ai/context/capabilities.json`
4
+ > **Owner**: Root router and command facade docs.
5
+
6
+ ## Purpose
7
+
8
+ The public surface turns user intent into one of the supported CLI+hooks harness
9
+ actions without duplicating engine policy in prose. It includes the root skill
10
+ compatibility router, README, root agent docs, the `forge` CLI, and thin
11
+ `forge-*` command facades.
12
+
13
+ ## Capabilities
14
+
15
+ - `public-surface-root-router` -> `docs/architecture/modules/public-surface/root-router.md`
16
+ - `public-surface-action-commands` -> `docs/architecture/modules/public-surface/action-commands.md`
17
+
18
+ ## Stable Rules
19
+
20
+ - Root `SKILL.md` stays short and router-oriented.
21
+ - Root `AGENTS.md` and `CLAUDE.md` stay concise; detailed operating rules live in `docs/reference-configs/`.
22
+ - Public commands are CLI-backed facades. Internal steps such as `hooks-init`, `docs-init`, and `create-project-dirs` stay behind `init`, `scaffold`, `migrate`, and `upgrade`.
23
+ - `forge-skill` remains a compatibility trigger, not the canonical name.
24
+ - The former `project-initializer` install paths have been fully removed; no tooling recognizes, syncs, or cleans them up.
25
+
26
+ ## Verification Surface
27
+
28
+ - `bun test tests/action-command-skills.test.ts`
29
+ - `bun scripts/inspect-project-state.ts --repo . --format text`
30
+ - `bash scripts/migrate-project-template.sh --repo . --dry-run`
package/docs/architecture/domains/runtime-harness.md ADDED
@@ -0,0 +1,33 @@
1
+ # Architecture Domain: Runtime Harness
2
+
3
+ > **Source**: `.ai/context/capabilities.json`
4
+ > **Owner**: Hook implementation, user-level adapter settings, runtime event files, and handoff state.
5
+
6
+ ## Purpose
7
+
8
+ The runtime harness gives Claude and Codex a file-backed workflow shell. The
9
+ shared implementation lives under `.ai/hooks/`; adapters point into that layer
10
+ instead of becoming separate hook sources of truth.
11
+
12
+ ## Capabilities
13
+
14
+ - `runtime-harness-hook-adapters` -> `docs/architecture/modules/runtime-harness/hook-adapters.md`
15
+
16
+ ## Stable Rules
17
+
18
+ - `.ai/hooks/` is the shared hook implementation.
19
+ - User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapter surfaces.
20
+ - Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are retired legacy config, not required contract files.
21
+ - Other repo-local `.codex/*` files are runtime residue unless promoted by an explicit contract change.
22
+ - Runtime files under `.ai/harness/checks`, `.ai/harness/handoff`, `.ai/harness/failures`, `.ai/harness/architecture/events.jsonl`, `.ai/harness/worktrees`, and `.ai/harness/runs` are ignored state, not durable deliverables.
23
+
24
+ ## Verification Surface
25
+
26
+ - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
27
+ - `bash scripts/check-task-workflow.sh --strict`
28
+
29
+
30
+ ## Local execution bridge
31
+
32
+ The localhost-only Local Controller stores approval-aware Job Tickets under `.ai/harness/local-jobs/`. These Jobs are runtime state, are ignored by Git, and dispatch into the same durable Issue, Task, Run, diff, and verification flow used by MCP.
33
+
package/docs/architecture/domains/verification.md ADDED
@@ -0,0 +1,33 @@
1
+ # Architecture Domain: Verification
2
+
3
+ > **Source**: `.ai/context/capabilities.json`
4
+ > **Owner**: Regression tests, workflow gates, eval harness, CodeGraph readiness, and advisory tooling checks.
5
+
6
+ ## Purpose
7
+
8
+ Verification protects the contract from drifting across self-host, generated
9
+ repos, command facades, hooks, migration helpers, and installed runtime copies.
10
+
11
+ ## Capabilities
12
+
13
+ - `verification-codegraph-readiness` -> `docs/architecture/modules/verification/codegraph-readiness.md`
14
+ - `verification-evals-checks` -> `docs/architecture/modules/verification/evals-checks.md`
15
+
16
+ ## Stable Rules
17
+
18
+ - Self-host and generated behavior must be checked together when shared assets change.
19
+ - `bun test` is the broad regression gate.
20
+ - `check-task-sync.sh` enforces that substantive repo changes update `tasks/`.
21
+ - `check-task-workflow.sh --strict` is the repo-local harness readiness gate.
22
+ - `sync-brain-docs.sh --check` verifies manifest-controlled repo-to-brain mirrors without making gbrain or MCP part of hook correctness.
23
+ - External tooling probes remain read-only by default; CodeGraph readiness is required for agent code navigation, while other external tooling remains advisory.
24
+ - This self-host repo may use a vendored CodeGraph dev dependency; generated downstream repos keep global CodeGraph MCP setup explicit unless policy opts in.
25
+
26
+ ## Verification Surface
27
+
28
+ - `bun test`
29
+ - `bash scripts/check-task-sync.sh`
30
+ - `bash scripts/check-task-workflow.sh --strict`
31
+ - `bash scripts/ensure-codegraph.sh --check --json`
32
+ - `bun scripts/inspect-project-state.ts --repo . --format text`
33
+ - `bash scripts/migrate-project-template.sh --repo . --dry-run`
package/docs/architecture/domains/workflow-engine.md ADDED
@@ -0,0 +1,30 @@
1
+ # Architecture Domain: Workflow Engine
2
+
3
+ > **Source**: `.ai/context/capabilities.json`
4
+ > **Owner**: Inspection, migration, contract, template, and policy generation.
5
+
6
+ ## Purpose
7
+
8
+ The workflow engine is the repo mutation layer. It classifies the target repo,
9
+ archives or preserves legacy workflow surfaces, installs the tasks-first
10
+ contract, and writes the minimal file-backed harness that downstream repos can
11
+ verify without a live service.
12
+
13
+ ## Capabilities
14
+
15
+ - `workflow-engine-inspection-migration` -> `docs/architecture/modules/workflow-engine/inspection-migration.md`
16
+ - `workflow-engine-contract-assets` -> `docs/architecture/modules/workflow-engine/contract-assets.md`
17
+
18
+ ## Stable Rules
19
+
20
+ - `assets/workflow-contract.v1.json` is the canonical contract asset.
21
+ - `.ai/harness/workflow-contract.json` is the installed runtime copy.
22
+ - Migration deletes only manifest-owned `known_generated` surfaces.
23
+ - User-authored legacy docs are preserved or archived before template refresh.
24
+ - `_ref/`, `_ops/`, secrets, local env, and custom hooks are not product migration surfaces.
25
+
26
+ ## Verification Surface
27
+
28
+ - `bun test tests/migration-script.test.ts tests/create-project-dirs.runtime.test.ts tests/workflow-contract.test.ts`
29
+ - `bash scripts/migrate-project-template.sh --repo . --dry-run`
30
+ - `bash scripts/check-task-workflow.sh --strict`
package/docs/architecture/global-hook-runtime.md ADDED
@@ -0,0 +1,162 @@
1
+ # Global Hook Runtime
2
+
3
+ > **Status**: Phase 0 — Operational Smoke (data filled 2026-05-28; manual-only items still pending)
4
+ > **Plan**: `plans/plan-20260528-1436-hook-global-runtime.md`
5
+ > **Contract**: `tasks/contracts/hook-global-runtime.contract.md`
6
+ > **Notes**: `tasks/notes/hook-global-runtime.notes.md`
7
+ > **Canary**: `scripts/canary-global-hook.sh`
8
+ > **Generated**: 2026-05-28, operator: ancienttwo (canary log 711 lines, time window 15:23–17:04 +08:00; includes post-Codex-restart trust observations at 17:03)
9
+ > **Repo set used for canary**: `/Users/ancienttwo/Projects/forge` (opt-in, this repo), `/Users/ancienttwo/Astrozi` (opt-in). **Gap**: no non-opt-in repo yet — pending manual run to confirm dual-fire vs single-fire branching.
10
+
11
+ ## Purpose
12
+
13
+ Document the operational behavior of `forge` global hook runtime when
14
+ installed at the host level (Codex `~/.codex/hooks.json` + Claude
15
+ `~/.claude/settings.json`). Phase 0 fills the Host Operational Matrix and the
16
+ Trust UX sections from real host smoke; Phase 1 fills Migration Guide and
17
+ Failure Mode from the CLI implementation.
18
+
19
+ This document is **not** a substitute for the plan or contract. The plan owns
20
+ strategy; the contract owns scope and exit criteria; this document owns
21
+ observed runtime behavior of the two hosts under user-level hook installation.
22
+
23
+ ## Phase 0 Verification Setup
24
+
25
+ - Canary script: `scripts/canary-global-hook.sh`
26
+ - Events instrumented: `SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`
27
+ - Per-fire side effect: append one line to `~/.forge-canary.log`
28
+ - Format: `[forge-canary] host=<codex|claude> event=<name> repo=<path> ts=<iso>`
29
+ - Host slots written:
30
+ - `~/.codex/hooks.json` (Codex global)
31
+ - `~/.claude/settings.json` (Claude user-level)
32
+ - Backups (first install only): `<file>.forge-canary-backup`
33
+ - Trust registration surface to grep: `~/.codex/config.toml [hooks.state]` (user-level path keys only)
34
+
35
+ Procedure:
36
+
37
+ 1. `bash scripts/canary-global-hook.sh install`
38
+ 2. Restart Codex; observe trust prompt UX; accept or decline (test both)
39
+ 3. Restart Claude Code, or rely on `ConfigChange` auto-reload
40
+ 4. Trigger each instrumented event in 2-3 repos (mix: opt-in + non-opt-in)
41
+ 5. `bash scripts/canary-global-hook.sh status` — tagged entry count per host + Codex user-level hash count
42
+ 6. `bash scripts/canary-global-hook.sh tail` — live log
43
+ 7. Record observations in this document
44
+ 8. `bash scripts/canary-global-hook.sh uninstall`
45
+
46
+ ## Host Operational Matrix
47
+
48
+ | # | Observation | Codex (`~/.codex/hooks.json`) | Claude (`~/.claude/settings.json`) |
49
+ |---|-------------|-------------------------------|------------------------------------|
50
+ | 1 | **加载** — global hook 是否被 host 调度层 fire（在任意 repo 触发对应 event 时 canary log 是否出现 `host=<X>` 行） | ✅ **522 + 2 fires** across both repos. Pre-restart per event: SessionStart=6, UserPromptSubmit=6, PreToolUse=254, PostToolUse=252, Stop=4. **Post-restart (17:03:44 Astrozi)**: SessionStart=1, UserPromptSubmit=1 confirming reload + new-entry trust. First fire: `2026-05-28T15:35:05` (forge). Last fire: `2026-05-28T17:03:44` (Astrozi). Source: `~/.forge-canary.log` lines tagged `host=codex`. | ✅ **169+ fires** across both repos (continuing live). Per event (pre-17:04 sample): SessionStart=3, UserPromptSubmit=10, PreToolUse=74, PostToolUse=72, Stop=10. First fire: `2026-05-28T15:23:01`. Most recent: `2026-05-28T17:04:12` (this session). Source: same log, `host=claude`. |
51
+ | 2 | **Trust prompt UX** — 首次安装后启动 host 是否弹 trust prompt？形态如何（CLI 提示 / Settings UI / 静默接受）？拒绝路径是什么？ | ✅ **Per-new-entry prompt confirmed** (2026-05-28T17:03 manual restart). User reports: "已重启授权 5 个新 HOOK" — Codex 对 5 个新 canary entries 分别弹了 5 个独立 trust prompt; 已存在的 11 条 shim hash 静默通过未 re-prompt. Hash count 立即 11 → 16. **Still manual-only**: prompt 文案 / UI surface (CLI 提示 vs Settings UI) / 拒绝路径行为. To capture: edit one canary `echo` command string in `~/.codex/hooks.json`, restart Codex, screenshot the prompt; decline branch separately. | N/A — Claude 文档明确无 trust re-prompt 机制 (`code.claude.com/docs/en/settings.md`); 169 silent fires confirm. |
52
+ | 3 | **Hash 注册** — 接受 trust 后是否在 `~/.codex/config.toml [hooks.state]` 下出现 user-level path key (`/Users/<user>/.codex/hooks.json:<event>:<i>:<j>`)？hash 命中时是否跳过重复 prompt？ | ✅ **16 entries observed** (post-canary-restart, lines 498–543 in `config.toml`). Key format confirmed: `<absolute-path>:<event-snake-case>:<i>:<j>` where `i` = index into `hooks[<event>]` array, `j` = index into `hooks[<event>][i].hooks[]` nested array. **Pre-canary** entries (11, from Phase 0.5 shim): `pre_tool_use:0:0`, `pre_tool_use:0:1`, `post_tool_use:0:0`/`0:1`/`1:0`/`2:0`/`3:0`, `session_start:0:0`, `user_prompt_submit:0:0`/`0:1`, `stop:0:0`. **New canary** entries (5, appended at i=N+1): `pre_tool_use:1:0`, `post_tool_use:4:0`, `session_start:1:0`, `user_prompt_submit:1:0`, `stop:1:0`. ✅ **Hash-skip confirmed**: 重启 Codex 后 11 条 shim hash 全部静默通过, only the 5 new canary entries triggered fresh trust prompts. Key takeaway: Codex hashes `(canonical command string, event-key-with-indices)` and only prompts on new combinations. | N/A |
53
+ | 4 | **Auto-reload** — 修改 hook config 文件后是否需要重启 host，还是 host 自动 pickup？Claude 是否触发 `ConfigChange` event？ | ✅ **Restart-time reload confirmed** (17:03:44 Astrozi: post-canary-install Codex restart → SessionStart + UserPromptSubmit canary fires immediately). 🔶 **Mid-session reload untested**. To test: edit one canary `echo` text in `~/.codex/hooks.json` while Codex session is live, trigger PreToolUse without restart, check log for updated text. | ✅ **Auto-reload confirmed at install time**: 16:51:47 PreToolUse canary fire happened seconds after I wrote `~/.claude/settings.json` (no Claude restart between write and fire). ConfigChange auto-pickup verified. 🔶 **Time-from-write delta** (秒级 vs reload-on-next-event) still needs explicit measurement via mtime delta. |
54
+ | 5 | **拒绝 trust 后行为** — 用户拒绝 trust 时 host 行为：silent skip / 报错 / 阻塞 event？后续如何重新启用？ | **Manual-only**: never refused. To test: temporarily edit one command string, restart Codex, decline trust prompt (if it appears), observe behavior. Note for safety: do this in a scratch hook entry, not on the real PreToolUse guard. | N/A |
55
+
56
+ Fill rule: rows 1 and 3 are evidence-driven (canary log + config.toml). Rows
57
+ 2/4/5 still carry `Manual-only` markers because they require interactive UX
58
+ observation that the canary log cannot capture (trust prompt text, reject
59
+ flow, reload timing). Address these by running the 4 micro-tests listed
60
+ inline above before declaring Phase 0 fully closed.
61
+
62
+ ## Dual-Fire Note (Design Expected, Not Anomaly)
63
+
64
+ During Phase 0, opt-in repos (including this self-host repo) still carry a
65
+ project-level `.codex/hooks.json` and a project-level `.claude/settings.json`
66
+ hooks segment that dispatch the real `.ai/hooks/run-hook.sh` guards. When the
67
+ canary is installed globally **and** the user triggers an event inside an
68
+ opt-in repo, both fire:
69
+
70
+ - Project-level hook → real guard (writes `.ai/harness/*`, etc.)
71
+ - Global canary → echo into `~/.forge-canary.log`
72
+
73
+ This is the expected Phase 0 state, not a regression. Claude documents this
74
+ as "merging, not overriding" across scopes
75
+ (`code.claude.com/docs/en/hooks.md`). To observe a clean global-only fire,
76
+ trigger events in a **non-opt-in repo** (any repo without
77
+ `.ai/harness/workflow-contract.json`).
78
+
79
+ Phase 1 reframes this: project-level adapters become deprecated fallback
80
+ shims, and the `forge hook` dispatcher (called from the global slot)
81
+ becomes the single canonical entrypoint.
82
+
83
+ ## Trust UX — Codex
84
+
85
+ Partially observed from canary install; manual UX-only items remain.
86
+
87
+ **Confirmed (data-driven):**
88
+
89
+ - ✅ `[hooks.state]` key format: `<absolute-path>:<event-snake-case>:<i>:<j>` where `i` indexes the per-event hooks array and `j` indexes the nested `hooks[].hooks[]` array. Same format applies to user-level and project-level paths (compare `~/.codex/hooks.json:...` entries to existing project-level entries in the same `config.toml`).
90
+ - ✅ User-level hash registration works: **16 entries** under `[hooks.state."/Users/ancienttwo/.codex/hooks.json:..."]` after canary install + Codex restart + user trust acceptance (was 11 pre-canary, +5 for new canary entries).
91
+ - ✅ Once trust is registered, fires happen silently (522+ codex fires without UX interruption in the canary window; post-restart fires at 17:03:44 Astrozi also silent).
92
+ - ✅ **Per-new-entry trust prompt**: Codex restart after canary install showed 5 distinct trust prompts (one per new `(command, key)` combination); the 11 preexisting shim hashes silently passed without re-prompt. User reported manual acceptance: "已重启授权 5 个新 HOOK" (2026-05-28T17:03).
93
+ - ✅ **Hash sensitivity to (command, key) tuple confirmed**: appending new entries to existing event arrays produced new `i` indices (`pre_tool_use:1:0`, `post_tool_use:4:0`, `session_start:1:0`, `user_prompt_submit:1:0`, `stop:1:0`), each triggering its own prompt. Implication: any change to either the command string or the array position will re-trust-prompt.
94
+ - ✅ **Uninstall does not GC `[hooks.state]` residual hashes** (2026-05-28T17:11 confirmed): `bash scripts/canary-global-hook.sh uninstall` removed all 5 canary entries from `~/.codex/hooks.json` (verified canary status `installed: 0/5`), but `[hooks.state]` retained all 16 user-level entries (lines 498–543). Implication: re-installing identical canary commands at identical `(event, i, j)` positions should hash-match and skip prompt. Operator must manually edit `config.toml` to revoke stale trust.
95
+
96
+ **Still manual-only — answer by running the micro-tests below:**
97
+
98
+ - 提示文案 + UI surface（CLI 内 prompt 还是 Settings UI 入口）
99
+ - **Micro-test**: 下次 install canary 前先 `canary uninstall`，再 install，restart Codex，截屏/抄录 prompt 文案和出现位置；本次实测仅有"5 个新 HOOK 授权"的口头描述，没有原始 prompt 文本。
100
+ - 拒绝路径：之后还能重新启用吗？需要重启 Codex 还是改 config.toml？
101
+ - **Micro-test**: 临时编辑一条 canary entry 的 echo 字符串（不影响真 shim），restart Codex，在 prompt 弹出时 decline；触发 event 看 canary log 是否新增行；grep `config.toml [hooks.state]` 看 decline 是否被记录。
102
+ - Command 字符串内部小改是否触发新 prompt？（已知 append 新 entry 会触发；同一 (i,j) 改 command 待测）
103
+ - **Micro-test**: 编辑 `~/.codex/hooks.json` 中现存某 canary entry 的 echo 文本（加尾随空格即可），restart Codex，看是否对该 `:<i>:<j>` key 弹新 prompt。
104
+
105
+ ## Trust UX — Claude
106
+
107
+ Claude Code user-level hooks 不使用 trust 机制：
108
+
109
+ - `~/.claude/settings.json` 是 documented user-level config，所有 event
110
+ types（PreToolUse / PostToolUse / SessionStart / UserPromptSubmit / Stop /
111
+ Notification / SubagentStart / Stop / FileChanged / ConfigChange）在 user
112
+ 级都支持。
113
+ - Merging precedence: `managed > local (.claude/settings.local.json) > project (.claude/settings.json) > user (~/.claude/settings.json)`。
114
+ 同一 event 在多个 scope 都有 hook 时，**所有 scope 的 hook 都 fire**
115
+ (merging, not override)。
116
+ - 配置变更**自动 reload**，触发 `ConfigChange` event，无需重启 Claude
117
+ Code。
118
+ - 引用：`code.claude.com/docs/en/settings.md`, `code.claude.com/docs/en/hooks.md`
119
+ (verified 2026-05-28 via `claude-code-guide` subagent)。
120
+
121
+ Phase 0 观察结果：
122
+
123
+ - ✅ **Merging precedence verified at user level**: 169 user-level canary fires happened alongside project-level real-guard fires in opt-in repos (forge + Astrozi). Same event triggers both. This confirms `user > project` merging works as documented (not override).
124
+ - 🔶 **ConfigChange 秒级触发**: still **manual-only**. Implied by 169 fires over 1h36m with no obvious restart, but not measured.
125
+ - **Micro-test**: write a no-op change to `~/.claude/settings.json` (e.g. reorder a JSON key without changing semantics), then immediately trigger a `PreToolUse` event, measure delta between file mtime and next canary log line.
126
+
127
+ ## Migration Guide
128
+
129
+ (Phase 1 填入: `forge install` / `forge migrate <repo>` 行为说明)
130
+
131
+ 预期覆盖:
132
+
133
+ - 新 repo init: 不再写项目级 `.codex/hooks.json` 或 `.claude/settings.json` hooks 段
134
+ - 老 repo 升级: `forge migrate <repo>` 把旧 hook 段降级为 fallback shim 或删除
135
+ - Contract bump: `hookRuntime: { mode: 'global-cli' | 'project-adapter', minCliVersion }` 字段语义
136
+ - 自迁移 forge 自身的步骤与验证
137
+
138
+ ## Failure Mode
139
+
140
+ (Phase 1 填入: 各失败路径与诊断命令)
141
+
142
+ 预期覆盖:
143
+
144
+ - CLI 未安装时全局 adapter 行为
145
+ - 用户拒绝 trust 后的降级路径
146
+ - repo 缺 opt-in marker 时的 silent exit 0 验证
147
+ - `forge doctor` 输出格式与检测维度
148
+ - PATH 问题（CLI 不在 PATH 上）与 host 报错形态
149
+ - 两 host 仅装其一时的 install/status 一致性
150
+
151
+ ## References
152
+
153
+ - 上游设计参考: `_ref/codegraph` @ commit `02935d77`
154
+ (`src/installer/targets/registry.ts:20-29`, `src/installer/targets/codex.ts:40,46,57-59`,
155
+ `src/installer/targets/types.ts:15,51-62`, `install.sh`, `install.ps1`)
156
+ - Codex hooks 文档与实证: `~/.codex/config.toml` `[features] hooks = true` (lines 23/138/171),
157
+ `[hooks.state]` (lines 404+), Codex CLI 0.130.0
158
+ - Claude hooks 文档: `code.claude.com/docs/en/settings.md`, `code.claude.com/docs/en/hooks.md`
159
+ - 项目内相关 module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
160
+ - 项目内相关 domain: `docs/architecture/domains/runtime-harness.md`
161
+ - 历史决策: `tasks/notes/codex-hook-adapter.notes.md`,
162
+ `tasks/notes/hook-global-runtime.notes.md`
package/docs/architecture/history.md ADDED
@@ -0,0 +1,38 @@
1
+ # Architecture Evolution History
2
+
3
+ > **Historical Design — Not Runtime Authority**
4
+ >
5
+ > Current architecture: [`docs/architecture/current/README.md`](current/README.md).
6
+
7
+ This document is the compact history of the Controller Runtime architecture. Detailed superseded V5–V8 design and verification documents were removed from the current tree after their useful decisions were consolidated here. Their exact contents remain recoverable from Git history.
8
+
9
+ ## V5 — Durable execution and closure
10
+
11
+ V5 separated durable Issue and Task intent from individual Run attempts. It introduced explicit run failure semantics, evidence-gated progress, direct local execution, governance diagnostics, and terminal Issue archiving. The lasting rule is that a failed attempt must not silently cancel the underlying task and that completion must be supported by durable evidence.
12
+
13
+ ## V6 — Direct change first
14
+
15
+ V6 made bounded Direct Edit the default for known, low-to-medium-risk changes. It added stale-write guards, explicit allowed paths, atomic patch operations, persisted diffs, targeted checks, rollback, and finalization. The lasting rule is that a small change should not require an agent worktree when a transactional edit can prove exactly what changed.
16
+
17
+ ## V7 — Execution first and task-local policy
18
+
19
+ V7 classified execution by task scope and risk, selected workspace or worktree isolation deliberately, and tightened task-local verification and lifecycle handling. The lasting rule is that execution mode is chosen from current task evidence rather than from a global one-size-fits-all workflow.
20
+
21
+ ## V8 — ChatGPT facade and visual controller
22
+
23
+ V8 established the compact ChatGPT-facing facade, Direct Edit as the common path, optional agent execution, recovery projections, and a visual Local Controller. Later revisions moved heavy reads off the Gateway hot path, bounded default responses, and retained atomic typed tools behind the facade.
24
+
25
+ ## Legacy ChatGPT Controller and Local Bridge
26
+
27
+ The earlier Controller and Local Bridge documents described recovery projections, compact MCP capabilities, Local Job tickets, visual review, diagnostics, and optional Codex or Claude sessions. Their current contracts now live in executable code, `docs/architecture/current/`, and `docs/operations/`; these older documents are no longer separate product surfaces.
28
+
29
+ ## Verification records
30
+
31
+ V5, V6, and V8 verification files were snapshots of checks performed against specific historical revisions and environments. They are not current release evidence. Current verification is produced by repository checks, durable Evidence records, and exact-revision test output.
32
+
33
+ ## Preservation policy
34
+
35
+ - Current architecture belongs only in `docs/architecture/current/`.
36
+ - Important superseded decisions are summarized here instead of keeping many competing design documents.
37
+ - Detailed removed documents remain available in Git history.
38
+ - Historical text never overrides executable behavior, persisted schemas, accepted ADRs, or the current architecture set.
package/docs/architecture/index.md ADDED
@@ -0,0 +1,114 @@
1
+ # Architecture Index
2
+
3
+ > Controller Runtime architecture entry point.
4
+
5
+ ## Runtime Authority
6
+
7
+ **`docs/architecture/current/` is the only Runtime Authority for the current and target Forge Controller Runtime architecture.**
8
+
9
+ Start here:
10
+
11
+ - [Current architecture map and reading order](current/README.md)
12
+ - [Architecture governance contract](current/governance.md)
13
+
14
+ When current implementation, the consolidated architecture history, a research note, and a document under `current/` disagree, the following precedence applies:
15
+
16
+ 1. executable code and persisted schemas describe **Current Implementation** facts;
17
+ 2. `docs/architecture/current/` defines the approved **Target Architecture** and mandatory **Migration Rules**;
18
+ 3. accepted ADRs may amend the target architecture until their conclusions are merged into `current/`;
19
+ 4. the consolidated history, snapshots, plans, research reports, and diagrams are historical or exploratory evidence only.
20
+
21
+ A target rule is not evidence that the implementation already satisfies it. Every current architecture document must distinguish:
22
+
23
+ - **Current Implementation** — behavior verified in code, tests, or persisted schemas;
24
+ - **Target Architecture** — the approved end state that future work must converge toward;
25
+ - **Migration Rule** — constraints that apply while moving from the current implementation to the target.
26
+
27
+ ## Current Controller Runtime Scope
28
+
29
+ Forge is a repository engineering control plane. It includes:
30
+
31
+ - MCP and local UI entry points;
32
+ - a multi-repository registry and per-repository runtime storage;
33
+ - Issue, Task, Job, Run, Direct Edit, Verification, and evidence lifecycles;
34
+ - optional Codex, Claude, and GitHub Copilot execution;
35
+ - workspace and worktree isolation, integration, checks, recovery, and governance;
36
+ - future schedule-driven bounded occurrences and cross-repository orchestration.
37
+
38
+ It is not the product runtime of the repositories it manages. It must not replace repository-owned build, test, deployment, or release systems as the final authority.
39
+
40
+ ## Architecture Document Classes
41
+
42
+ | Class | Location | Authority |
43
+ | --- | --- | --- |
44
+ | Current architecture | `docs/architecture/current/` | Runtime Authority |
45
+ | Architecture decisions | `docs/architecture/decisions/` | Binding until merged or superseded |
46
+ | Pending drift requests | `docs/architecture/requests/` | Proposed change only |
47
+ | Architecture snapshots | `docs/architecture/snapshots/` | Historical evidence |
48
+ | Consolidated architecture history | `docs/architecture/history.md` | Historical Design / Not Runtime Authority |
49
+ | Research reports | `docs/researches/` | Hypothesis and supporting evidence |
50
+ | Plans and task records | `plans/`, `tasks/` | Execution intent and progress, not architecture authority |
51
+ | Diagrams | `docs/architecture/diagrams/` | Explanatory projection; semantic Markdown source wins |
52
+
53
+ ## Current Architecture Set
54
+
55
+ The maintained current architecture set contains:
56
+
57
+ - `README.md` — map, status labels, and reading order;
58
+ - `governance.md` — authority, ownership, ADR, and drift rules;
59
+ - `system-overview.md` — system boundary and process topology;
60
+ - `personal-assistant-plugin-baseline.md` — concrete assistant/plugin/provider boundary, threat model, capability matrix, and migration baseline;
61
+ - `architecture-invariants.md` — rules implementations must not violate;
62
+ - `entity-model.md` — Issue, Task, Job, Run, Edit Session, Verification, Schedule, Occurrence, Claim, and Lease semantics;
63
+ - `job-and-run-lifecycle.md` — durable execution and retry state machines;
64
+ - `dispatch-and-agent-strategy.md` — Direct Edit, Quick Agent, durable Task, and role selection;
65
+ - `scheduler-and-resource-claims.md` — repository actors, resource claims, leases, and conflict behavior;
66
+ - `multi-repository-execution.md` — quotas, fairness, failure isolation, and portfolio workflows;
67
+ - `automation-and-schedule-engine.md` — bounded occurrences, budgets, backoff, deduplication, and stop conditions;
68
+ - `failure-recovery.md` — process boundaries, orphan handling, reconciliation, and fencing;
69
+ - `verification-and-release-gates.md` — exact-revision evidence, integration gates, release freeze, and human authorization;
70
+ - `implementation-status.md` — verified implementation coverage and explicit migration gaps;
71
+ - `migration-roadmap.md` — evidence-driven implementation convergence order;
72
+ - `runtime-architecture-simplification.md` — single-owner services, canonical authority/config, immutable activation, Recovery boundary, invariants, and deletion map;
73
+ - ADR [`decisions/20260803-release-identity-binding-and-exit-policy.md`](decisions/20260803-release-identity-binding-and-exit-policy.md) — captured release identity binding for managed children and Supervisor vs launchd failure domains.
74
+
75
+ A missing or proposed rule must be recorded in an accepted architecture request or ADR and must not be inferred from historical material.
76
+
77
+ ## Architecture Change Flow
78
+
79
+ 1. Identify whether the proposed change alters a boundary, entity semantic, lifecycle, resource rule, safety invariant, or public execution contract.
80
+ 2. Record the change as an architecture request or ADR before implementation when the answer is yes.
81
+ 3. Update the affected `current/` documents in the same change or explicitly record the temporary drift and its owner.
82
+ 4. Update tests and architecture checks that enforce the changed rule.
83
+ 5. Consolidate useful superseded decisions in `history.md`, then remove duplicate detailed documents from the current tree while preserving them in Git history.
84
+ 6. Close the request only after the current architecture and executable behavior no longer contradict each other, or the difference is explicitly labeled as a migration gap.
85
+
86
+ See [Architecture governance contract](current/governance.md) for the full rule.
87
+
88
+ ## Existing Domain Documentation
89
+
90
+ The following domain pages describe the earlier repo-local workflow-harness architecture. They remain useful implementation history but are not the current Controller Runtime authority:
91
+
92
+ - [Public Surface](domains/public-surface.md)
93
+ - [Workflow Engine](domains/workflow-engine.md)
94
+ - [Runtime Harness](domains/runtime-harness.md)
95
+ - [Verification](domains/verification.md)
96
+ - [Transactional Adoption Planner](transactional-adoption-planner.md)
97
+ - [Global Hook Runtime](global-hook-runtime.md)
98
+
99
+ ## Pending Architecture Requests
100
+
101
+ <!-- BEGIN ARCHITECTURE PENDING REQUESTS -->
102
+ - (none)
103
+ <!-- END ARCHITECTURE PENDING REQUESTS -->
104
+
105
+ ## Accepted Architecture Decisions
106
+
107
+ - [Controller-home SQLite state authority](decisions/20260801-controller-home-sqlite-state.md) — versioned controller-owned runtime facts, one-way JSON import, audit records, and phased migration.
108
+ - [MCP Session Lifecycle and Stable Ingress Isolation](decisions/20260718-mcp-session-lifecycle-and-ingress-isolation.md) — one global transport-capacity authority, bounded stream leases, capacity-aware `/ready`, and a supervised ingress child process.
109
+
110
+ ## Review Backlog
111
+
112
+ - Continue converging P0 runtime behavior with the gaps recorded in `current/implementation-status.md`.
113
+ - Add link validation and exact-revision release-manifest checks to the final release gate.
114
+ - Keep diagrams as projections of the Markdown semantic source; a diagram must not introduce architecture rules absent from `current/`.