|
1 | 1 | # codeboost architecture: a high-level overview |
2 | 2 |
|
3 | | -Status: current as of `main` at `7edf36d` (2026-10-04). Open work is listed in **Build status and roadmap**. |
| 3 | +Status: current as of `main` at `10c7c5e` (2026-10-04). Open work is listed in **Build status and roadmap**. |
4 | 4 | Writing standard: plain language, ISO 24495-1:2023 |
5 | 5 |
|
6 | 6 | ## About this document |
@@ -42,8 +42,8 @@ Writing standard: plain language, ISO 24495-1:2023 |
42 | 42 | - **Build state.** Three levels: |
43 | 43 | - **In use:** plan and linking library, SQLite store, review screen, Ask (questions to a Claude agent), guarded merge with merge-queue support, ranked Issues screen, agent isolation boundary, and the single-runner lock. |
44 | 44 | - **In use for a non-demo review with a `github` block:** planning. `/api/plan/suggestions` and `/api/plan/drafts` ask Claude, through lane D, for suggestion cards or a whole next plan revision (#117, #124). Nothing becomes a revision until you apply it. |
45 | | - - **In use with an opt-in `runner` block in `review.json`:** the whole loop after planning. `start` and `resume` on `/api/runner` run a task's plan item by item with a Claude agent (#91). When a run ends, codeboost publishes the task's pull request, a draft if the task needs a person (#103). Approve & merge merges that pull request (#121). Cancelling a task closes its pull requests (#111). These are API actions; the screen has no buttons for them yet. |
46 | | - - **Not built:** the "trust this issue" action and its runner guard (#108), screens for planning and the runner actions, rebasing, running `cmd:` checks, review rounds, continuing after a scope pause (#88), and the Planning, Queue and Learning screens. |
| 45 | + - **In use with an opt-in `runner` block in `review.json`:** the whole loop after planning. `start` and `resume` on `/api/runner` run a task's plan item by item with a Claude agent (#91). They require current plan-item approvals, bind both the task state and review version, recheck approvals before each later item, and refuse when a completed prefix no longer ends at the task's current head (#107). When a run ends, codeboost publishes the task's pull request, a draft if the task needs a person (#103). Approve & merge merges that pull request (#121). Cancelling a task closes its pull requests (#111). These are API actions; the screen has no buttons for them yet. |
| 46 | + - **Not built:** the "trust this issue" action and its runner guard (#108), screens for planning and the runner actions, rebasing, running `cmd:` checks, review rounds, continuing after a scope pause (#88, in review as PR #134), and the Planning, Queue and Learning screens. |
47 | 47 |
|
48 | 48 | ## Terms used |
49 | 49 |
|
@@ -169,7 +169,7 @@ Dependencies point downward only. `core/` imports nothing that does input or out |
169 | 169 | | Merge coordinator | `runner/merge.ts` | Runs the full merge gate twice, re-reads the local generation, then merges the exact reviewed head. Tracks merge-queue attempts. For a runner task it inspects and merges the task's own published pull request; a configured `github.pullRequest` that differs is refused (#121). | In use | |
170 | 170 | | Planning agent | `runner/planning.ts`, `web/planning.ts`, `runner/planning-provider.ts` | Runs plan suggestions and drafts with Claude in lane D's planning phase, on a read-only copy of the current head, in its own worker with its own leftovers ledger and owner token. The request and its timer share one 10-minute budget. Issue text is read with collaborators' comments only. | In use for a non-demo review with a `github` block | |
171 | 171 | | Runner coordinator | `runner/coordinator.ts`, `runner/lifecycle.ts` | Attempt admission, concurrency slots, compare-and-swap on results, retries, shutdown order. A stop made inside a user action takes effect only after that action's transaction commits (`Store.afterCommit`, #96). | In use with the opt-in `runner` block (#91) | |
172 | | -| Execution | `runner/execution.ts` | Runs plan items in order: fresh workspace, prompt, agent, post-run audit, then the runner's own commit and ledger entry. Before launch, D's tree check (`checkTaskTree`) must pass. Pauses in needs amendment on an out-of-scope edit. A safety violation is saved on the attempt before its terminal write, and the task moves to needs human in that same transaction; a failed run is audited too. | In use with the opt-in `runner` block; started by `start` and `resume` on `/api/runner` (#91, PR #105) | |
| 172 | +| Execution | `runner/execution.ts` | Runs plan items in order: fresh workspace, prompt, agent, post-run audit, then the runner's own commit and ledger entry. Before launch, D's tree check (`checkTaskTree`) must pass. Start and resume require current approvals, own the review version across the run, recheck approvals before later items, and verify that a completed prefix still ends at the current head (#107). Pauses in needs amendment on an out-of-scope edit. A safety violation is saved before its terminal write and remains durably owed when a human gate delays escalation; a failed run is audited too. | In use with the opt-in `runner` block; started by `start` and `resume` on `/api/runner` (#91, #107, PRs #105 and #130) | |
173 | 173 | | Workspace | `runner/workspace.ts`, `runner/runner-repository.ts` | The real lane D workspace. A runner-owned bare repository (owner-only directories) fetches base commits by ID and takes in each verified commit bundle under a per-attempt ref. Review and Ask read a task with runner commits from there, at the head the Store recorded. | In use with the opt-in `runner` block (#91) | |
174 | 174 | | Diagnostics | `runner/diagnostics.ts` | Saves the partial diff of a writable attempt that did not complete, owner-only, and keeps the folder under a size cap (256 MiB by default). | In use with the opt-in `runner` block (#91) | |
175 | 175 | | Publishing | `runner/publish.ts`, `runner/publishing.ts`, `runner/branch-push.ts` | Runs the already-fixed check, pushes the task head, then opens or reuses the task's pull request (a draft when the task needs a person). Records each opening before calling GitHub, so a lost outcome can be found again by a marker. `GitBranchPusher` pushes from the runner-owned repository through `gh auth git-credential`, only to `codeboost/` branches, and overwrites only a branch head the task's ledger owns (`--force-with-lease`). `TaskPublishing` (#103) publishes when a run ends, on the `publish` runner action, and once at startup, and records the last outcome. On cancel it closes the task's PRs (#111). | In use with the opt-in `runner` block (needs `github.baseBranch`); never in a demo | |
@@ -356,7 +356,7 @@ The diagram shows the designed transitions. With the `runner` block, running, ne |
356 | 356 |
|
357 | 357 | ### Stored data |
358 | 358 |
|
359 | | -All state is in one SQLite file, opened with WAL and full synchronization. Each write takes an immediate write lock. The schema version is `PRAGMA user_version`, and migrations run in explicit steps (version 11 today); an unknown version fails. |
| 359 | +All state is in one SQLite file, opened with WAL and full synchronization. Each write takes an immediate write lock. The schema version is `PRAGMA user_version`, and migrations run in explicit steps (version 13 today); an unknown version fails. |
360 | 360 |
|
361 | 361 | | Group | Tables | Notes | |
362 | 362 | |---|---|---| |
@@ -409,11 +409,11 @@ These are the decisions that shape the structure. The full list, with the reason |
409 | 409 | | C, K | Guarded merge, merge queue | Done | |
410 | 410 | | D | Agent isolation boundary | Done. Since the isolation gate: bounded diff export (#76), task-change inspection and the runner's commit as a bounded `git bundle` (#66, PRs #85 and #90), owner-scoped recovery for Ask (#95), the plan schema for Claude (#97), gitlink mounts and the pre-launch tree check (#81, #99, PR #100), and Codex refused in every phase (#93, PR #106). The runner-contract follow-ups (#51) are closed: the last one tests export and removal through a recovery handle after a real restart (PR #109). | |
411 | 411 | | E | Planning library and suggestions | Done. E4 (PR #45) added the acceptance fixtures and recorded Claude output that replays through validation and the Store. | |
412 | | -| F | Runner | Merged: F1 (lifecycle store, coordinator, shutdown wiring, startup recovery and the lock, planning API, feedback events, and stops that wait for their commit: #53, #74, #57, #59, #60, #96); F2a–F2b (execute prompts, audit, per-item execution, real workspace, durable safety findings: #67, #68, #92, #94, #128); F2d (already-fixed check, PR opening, branch pusher, production publishing, closing PRs on cancel: #84, #101, #110, #115, #116, #119, #123); production wiring and `start`/`resume` (#91, PRs #102, #105); planning through lane D (#117, #124, PRs #118, #120, #125); merging the task's own PR (#121, PR #126); part of F6 (#89). In review: guards for `start` and `resume` (#107, PR #130: approvals required, review version checked, earlier-commit check). Next: continue after a scope pause (#88), then rebasing and `cmd:` checks (#22). | |
| 412 | +| F | Runner | Merged: F1 (lifecycle store, coordinator, shutdown wiring, startup recovery and the lock, planning API, feedback events, and stops that wait for their commit: #53, #74, #57, #59, #60, #96); F2a–F2b (execute prompts, audit, per-item execution, real workspace, durable safety findings: #67, #68, #92, #94, #128); F2d (already-fixed check, PR opening, branch pusher, production publishing, closing PRs on cancel: #84, #101, #110, #115, #116, #119, #123); production wiring and `start`/`resume` (#91, PRs #102, #105); planning through lane D (#117, #124, PRs #118, #120, #125); merging the task's own PR (#121, PR #126); start/resume approval, review-version, recovery and completed-prefix guards (#107, PR #130); part of F6 (#89). In review: continue after a scope pause (#88, PR #134). Next after #88: rebasing and `cmd:` checks (#22). | |
413 | 413 | | Hardening | Allowlisted subprocess environments | Done: every Git command (#82, #83) and every `gh` runner (#84, #86). | |
414 | | -| Tests | Test suite reliability | Open: make the full suite end reliably under Docker load (#129). | |
| 414 | +| Tests | Test suite reliability | Done. The full suite runs ordinary tests first and Docker-backed files serially; CI and the real-Docker gate passed on PR #132 (#129). | |
415 | 415 | | G | Planning screen | Not started. Unblocked: E4 is done and the planning API runs Claude in production. | |
416 | | -| H | Issue ranking and Issues screen | Done except H4b (#108): the "trust this issue" action, plus a runner guard that refuses issues from non-collaborators that nobody trusted. Build it after #130, because both edit `runChoice` in `web/server.ts`. | |
| 416 | +| H | Issue ranking and Issues screen | Done except H4b (#108): the "trust this issue" action, plus a runner guard that refuses issues from non-collaborators that nobody trusted. It is unblocked now that #130 has merged. | |
417 | 417 | | I, J | Queue and run windows; learning from feedback | Not started (after F) | |
418 | 418 |
|
419 | 419 | ## Known limits |
|
0 commit comments