You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 5edf756
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/designs/codeboost-plan-indexed-review.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -119,7 +119,7 @@ These are proposals. The engineering review will confirm them.
119
119
-**Language:** TypeScript. A Node server and a React user interface, shipped as one npm package.
120
120
-**Storage:** SQLite. It holds tasks, plan revisions, approvals, feedback, the schedule, and a run log. **SQLite is the only master copy of each plan.**
121
121
-**Storage code:** All database access goes through one small module. It uses only Node's built-in `node:sqlite` (engineering review, R7). The minimum Node version is the oldest one that continuous integration proves loads `node:sqlite` with no warning. Node 26 is confirmed today. On an older Node, codeboost stops at start-up and tells you which version to install. The module is still a thin wrapper, so an API change touches one file.
122
-
-**Workspaces:** each task gets its own standalone clone (`git clone --local`), whose `.git` folder sits inside the task folder, so git works inside the agent's container (engineering review, O6). codeboost pushes to GitHub from outside the container. It never touches or mounts your own checkout. Elsewhere in this document, "worktree" means this per-task folder.
122
+
-**Workspaces:** each task gets its own standalone clone (`git clone --local --no-hardlinks`), whose `.git` folder sits inside the task folder, so git works inside the agent's container (engineering review, O6). Objects must be independent copies, with no hard links or alternates back to the source. codeboost pushes to GitHub from outside the container. It never touches or mounts your own checkout. Elsewhere in this document, "worktree" means this per-task folder.
123
123
-**Agents:** one small adapter per agent: `claude -p` and `codex exec`. Each takes a prompt, a worktree, and a set of permissions, and reports progress as it runs.
124
124
-**GitHub:** codeboost uses `gh` for issues, PRs, and merging. **Only codeboost runs `gh`. Agents never do.**
| What the container mounts | the worktree (git broken inside) | the task folder, including its own `.git` | the worktree | the worktree | the worktree |
1457
1457
| Who pushes to GitHub | codeboost | codeboost, from outside the container (the clone's remote is a local path, unreachable inside; the network rule R2 also blocks GitHub) | codeboost | codeboost | codeboost |
1458
1458
| Your main checkout | untouched | untouched, and never mounted | untouched | untouched | untouched |
1459
-
| Disk use | shared objects | objects hard-linked where the file system allows, else copied | shared | shared | shared |
1459
+
| Disk use | shared objects | independent object copies; no hard links or alternates | shared | shared | shared |
1460
1460
1461
1461
Question D16:
1462
1462
D16 — How should each task get a working git inside its container?
@@ -1469,7 +1469,7 @@ Net: working git and a sealed main repo (A), or broken git in the container (B,
1469
1469
Header: Container git
1470
1470
Options:
1471
1471
A) Apply this change (recommended)
1472
-
Replace per-task worktrees with a standalone per-task clone (git clone --local) that the container mounts, .git included. codeboost pushes from outside the container. ✅ Git works normally inside the container. ✅ Your main repository is never mounted or writable. ❌ Uses more disk per task when hard links are not possible. (human: ~3 hours / CC: ~15 min)
1472
+
Replace per-task worktrees with a standalone per-task clone (git clone --local --no-hardlinks) that the container mounts, .git included. codeboost pushes from outside the container. ✅ Git works normally inside the container. ✅ Your main repository is never mounted or writable. ❌ Uses more disk per task because objects are copied. (human: ~3 hours / CC: ~15 min)
1473
1473
B) Keep this row's current value
1474
1474
Keep git worktree and mount only the worktree. ✅ No change. ✅ Least disk use. ❌ Git does not work inside the container, so agents cannot inspect their own changes. (human: 0 / CC: 0)
1475
1475
C) Investigate before choosing
@@ -1479,8 +1479,8 @@ Leave this finding open. ✅ No work now. ✅ Listed as an open decision. ❌ Th
1479
1479
1480
1480
State: approved
1481
1481
Actual answer: A) Apply this change (answer to D16, 2026-09-22)
1482
-
Accepted scope: each task uses a standalone clone (`git clone --local`) with its own `.git` inside the task folder; the container mounts that folder as `/work`; codeboost pushes from outside the container; the main checkout is never mounted. Objects are hard-linked where possible, else copied. Test case: inside the container, `git status` and `git diff` work, and the main repository path is absent. Design sections amended: Tools and storage (Workspaces), Keeping unattended runs safe (container contents).
1483
-
History: none
1482
+
Accepted scope: each task uses a standalone clone (`git clone --local --no-hardlinks`) with its own `.git` inside the task folder; the container mounts that folder as `/work`; codeboost pushes from outside the container; the main checkout is never mounted. Objects are copied, never hard-linked or borrowed through alternates. Test case: inside the container, `git status` and `git diff` work, and the main repository path is absent. In disposable repositories, modifying an object in the task clone must leave the source object unchanged. Design sections amended: Tools and storage (Workspaces), Keeping unattended runs safe (container contents).
1483
+
History: PR #1 review found that `--local` alone shares object inodes with the source. The corrected command uses `--no-hardlinks`; a local probe reproduced source-object corruption without it.
1484
1484
1485
1485
### O7: Changes that have no text lines
1486
1486
Finding: outside voice 7, P1, confidence 8/10, "How codeboost links code to plan items" (segments are runs of changed lines), reviewer: Codex (outside voice), confirmed by Claude
@@ -1771,7 +1771,7 @@ Codex (outside voice, completed, 2026-09-22) raised 8 findings. Claude checked e
1771
1771
1772
1772
### What already exists
1773
1773
1774
-
- **git** already provides worktrees, `clone --local`, rebase, and per-commit diffs. The plan uses these rather than writing its own.
1774
+
- **git** already provides worktrees, `clone --local --no-hardlinks`, rebase, and per-commit diffs. The plan uses these rather than writing its own.
1775
1775
- **gh** already provides rulesets, checks, and `pr merge --match-head-commit`. The plan uses these rather than calling the API directly.
1776
1776
- **Docker** is installed on this machine. The plan runs agents in containers instead of relying on vendor sandboxes.
1777
1777
- **Claude CLI** already provides `--disallowedTools`, `--strict-mcp-config`, and `setup-token`. Used for the network and sign-in rules.
@@ -1862,7 +1862,7 @@ Built from this review's findings. Each task comes from a specific decision abov
1862
1862
- [ ] **T1 (P1, human: ~3 days / CC: ~1 hour)** — agents — Build the pinned agent container that mounts only `/work` (with its own `.git`) and the agent's sign-in
1863
1863
- Surfaced by: R1 (D2: B), O6 (D16: A)
1864
1864
- Files: agents/container/, git/clone
1865
-
- Verify: real-Docker test shows only `/work` and sign-in; `git status` works inside; the main repo path is absent
1865
+
- Verify: real-Docker test shows only `/work` and sign-in; `git status` works inside; the main repo path is absent; changing a task-clone object in disposable repos leaves the source object unchanged
1866
1866
- [ ] **T2 (P1, human: ~1 day / CC: ~30 min)** — agents — Add the vendor-only egress proxy and turn off web and MCP tools
@@ -1931,7 +1931,7 @@ Built from this review's findings. Each task comes from a specific decision abov
1931
1931
- [ ] **T18 (P2, human: ~2 days / CC: ~45 min)** — core, agents, web — Plan schema: draft plans with either agent, import YAML or JSON, apply typed suggestions
1932
1932
- Surfaced by: P1 (approved 2026-09-22)
1933
1933
- Files: schema/, docs/plan-format.md, prompts/plan-author.md, core/plan (schema and meaning checks), agents/claude, agents/codex, web/plans (Import plan, suggestion cards)
1934
-
- Verify: both examples pass and 8 broken plans fail; recorded Claude and Codex answers pass; a plan with a `..` path or a dependency loop cannot be approved; the edit schema's copied definitions match; `codex exec` runs with stdin closed
1934
+
- Verify: both examples pass and 8 broken plans fail; recorded Claude and Codex answers pass; a plan with a `..` path or a dependency loop cannot be approved; the edit schema's copied definitions match; dependent add → edit and rename → edit plans pass projected-state validation, while missing sources and occupied destinations fail; a new field requires a new schema version and old plans validate before conversion; `codex exec` runs with stdin closed
Copy file name to clipboardExpand all lines: docs/plan-format.md
+10-3Lines changed: 10 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -100,14 +100,18 @@ The schema checks the shape. codeboost then checks the meaning. A **failure** bl
100
100
| Item IDs are unique. | Failure |
101
101
| Every `depends_on` ID exists, comes earlier in the list, and there is no loop. | Failure |
102
102
| A path has no `..` part and stays inside the repo. | Failure |
103
-
| A file with kind `edit`, `delete`, or `rename` exists in the repo at the plan's base commit. For `rename`, `renamed_from` exists. For `add`, the path does not exist yet. | Failure |
103
+
| File operations are valid in the projected repo state immediately before the item runs (see below). `edit` and `delete` need an existing path; `add` needs an unused path; `rename` needs an existing `renamed_from` and an unused destination `path`. | Failure |
104
104
| `renamed_from` is set only for kind `rename`. | Failure |
105
105
| The same path is not declared twice in one item. | Failure |
106
106
| The item has at least one `cmd`. | Warning: "No test command"|
107
107
| Each `cmd` starts with a command on the repo's allowed list (Settings, Safety). | Warning; the command does not run until you add it to the list |
108
108
| A `cmd` changes a dependency or a script codeboost runs. | The task stops in "needs approval" when it runs, as for any such change |
109
109
| `questions` is not empty. | The plan shows the questions at the top; answer them or approve anyway |
110
110
111
+
**Projected file state.** Start with the paths at the plan's base commit, then walk items in their listed execution order. Check an item's file operations against the state before that item; after it passes, apply its declared additions, deletions, and renames to the projected state before checking the next item. No repo files change during validation. A path may participate in only one operation per item, counting both the source and destination of a rename. If an item uses a path created or renamed by an earlier item, it must depend on that item, directly or through other dependencies.
112
+
113
+
For example, P1 may add `src/new.go`, then P2 with `depends_on: [P1]` may edit it. Likewise, P1 may rename `src/old.go` to `src/new.go`, then P2 may edit the new path. Editing a missing path, adding an existing path, or renaming onto an occupied path blocks approval. Recompute the projected state from the base commit after each plan edit.
114
+
111
115
codeboost never treats issue text as instructions, wherever it appears. If an agent copies issue text into a plan field, the text is still just text: the agent that carries out the plan follows the plan items you approved, and nothing else.
112
116
113
117
## How a plan gets into codeboost
@@ -144,8 +148,11 @@ Fields an operation does not use are `null`. After you apply an edit, the plan r
144
148
## Versions
145
149
146
150
- Every plan carries `schema_version`. This document describes version 1.
147
-
- A change that adds an optional field, or relaxes a limit, keeps version 1.
148
-
- A change that renames, removes, or tightens a field makes version 2. codeboost keeps reading version 1 plans and converts them when it imports them.
151
+
- Wording changes that do not change accepted data keep the same version. Changes to accepted data, including adding, renaming, or removing a field or changing a limit, require the next schema version. This applies to both plan and suggested-edit schemas.
152
+
- A nullable field is still required. Adding one breaks old plans (the field is missing) and old readers (the field is unknown), so it must not be added under version 1.
153
+
- Keep released schemas unchanged. On import, read `schema_version`, validate against that version's schema, convert using an explicit version migration, then validate against the current schema and run the meaning checks. Reject unsupported versions with an explanation. Never validate an old plan against a newer schema before converting it. Suggested edits must use a supported schema version and still match the current plan revision; otherwise ask the assistant to regenerate them.
154
+
155
+
**PR #1 review decisions.** File validation uses projected state so dependent items can work on new or renamed files. Version changes are explicit because every field is required and unknown fields are rejected. T18 includes regression checks for both rules.
0 commit comments