diff --git a/README.md b/README.md index d1bc2f96..55af6a7c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Review agent-made Git changes one plan item at a time. The approved plan lists each item's files and acceptance checks; the review engine shows which item produced each change and flags foreign or overlapping work. -**Status:** the plan/linking library, SQLite store, local review screen, opt-in code-writing runner, durable local rebase, and exact-head plan command checks are implemented. Run `npm run demo` and open its private local URL. Ask and the runner use Claude Code inside locked-down containers; Codex is refused because it reads code only by running commands ([why](docs/implementation/agent-isolation.md#codex-is-refused-in-every-phase)). They need Docker, plus `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`). Startup builds the agent image, which can take a few minutes. A configured GitHub review can merge only after the guarded exact-head gate passes. The agent container, vendor-only network, credential-free command-check profile, and Claude/Codex adapters are described in [agent isolation](docs/implementation/agent-isolation.md). Pushing a rebased head, waiting for its required checks, and handing that exact pair to guarded merge remain follow-up work. The paired human review experiment was cancelled before results were recorded and no longer blocks roadmap work; optional future validation is tracked in [#19](https://github.com/codeabovelab/codeboost/issues/19). +**Status:** the plan/linking library, SQLite store, local review screen, Plans screen (plan import, plus agent drafts and suggestions with revision-bound Apply; drafts and suggestions need a configured `github` review, not the demo), opt-in code-writing runner, durable local rebase, and exact-head plan command checks are implemented. Run `npm run demo` and open its private local URL. Ask, planning and the runner use Claude Code inside locked-down containers; Codex is refused because it reads code only by running commands ([why](docs/implementation/agent-isolation.md#codex-is-refused-in-every-phase)). They need Docker, plus `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`). Startup builds the agent image, which can take a few minutes. A configured GitHub review can merge only after the guarded exact-head gate passes. The agent container, vendor-only network, credential-free command-check profile, and Claude/Codex adapters are described in [agent isolation](docs/implementation/agent-isolation.md). Pushing a rebased head, waiting for its required checks, and handing that exact pair to guarded merge remain follow-up work. The paired human review experiment was cancelled before results were recorded and no longer blocks roadmap work; optional future validation is tracked in [#19](https://github.com/codeabovelab/codeboost/issues/19). ## Development diff --git a/docs/designs/codeboost-plan-indexed-review.md b/docs/designs/codeboost-plan-indexed-review.md index 5cb53ca8..f7d283bc 100644 --- a/docs/designs/codeboost-plan-indexed-review.md +++ b/docs/designs/codeboost-plan-indexed-review.md @@ -6,7 +6,7 @@ Repo: codeabovelab/codeboost Status: APPROVED Mode: Builder (open source / research) Writing standard: plain language, ISO 24495-1:2023 -Last checked against the code: 2026-09-26 (see "Lane status" under "Parallel build lanes") +Last checked against the code: 2026-09-26 (see "Lane status" under "Parallel build lanes"). The summary and build-step status were updated later as lanes merged. For the current state of each lane, see the lane table in `docs/architecture.md`. ## About this document @@ -27,7 +27,7 @@ Last checked against the code: 2026-09-26 (see "Lane status" under "Parallel bui - **How it stays trustworthy.** codeboost records commits in a trusted ledger with either an owning plan item or an explicit foreign/unowned classification. Rewriting a foreign commit never turns it into owned work. It also checks each change against the files the plan item said it would touch. One blind spot remains: an unrelated edit inside a file the plan item declared is caught only by the review agent and by you. - **How it stays safe.** Agents run inside a container that holds only the task's code and the credential for that phase, so your other files and credentials are not there. Ask, code-writing runs, and conflict resolution use provider-specific containers; exact-head `cmd:` checks use a credential-free read-only profile. codeboost needs your approval before its own dependency installation or invocation of changed scripts; containment must also cover commands the agent already ran. - **It learns from you.** After each task, codeboost turns your feedback into short lessons. You approve each lesson before agents use it, and a Learning screen shows whether you are repeating yourself less. -- **Where the build is.** Built: the plan and linking library, SQLite store, review screen with Ask and change requests, guarded merge gate with merge-queue support, agent isolation boundary, opt-in code-writing runner and publishing, durable local rebase/conflict resolution, and pre-merge base/head refresh with exact-head `cmd:` checks. Still deferred: pushing the rewritten head, waiting for its required checks, handing that exact pair to guarded merge, and the Planning, Queue, Lessons and Learning screens (the ranked Issues screen is built). Optional real-PR validation is tracked separately in #19 and is not a prerequisite. +- **Where the build is.** Built: the plan and linking library, SQLite store, review screen with Ask and change requests, guarded merge gate with merge-queue support, agent isolation boundary, Plans screen (lane G, #145; #155 lists unbuilt parts and #159 tracks suggestion-card non-conformance), opt-in code-writing runner and publishing, durable local rebase/conflict resolution, and pre-merge base/head refresh with exact-head `cmd:` checks. Still deferred: pushing the rewritten head, waiting for its required checks, handing that exact pair to guarded merge, and the Queue, Lessons and Learning screens (the ranked Issues screen is built). Optional real-PR validation is tracked separately in #19 and is not a prerequisite. ## Terms used @@ -190,6 +190,8 @@ This keeps the plan out of the code, and there is only one master copy. 4. waits for you to approve or edit the proposal on the planning screen. Your approval creates the next plan revision; 5. puts the task back in the queue at its old position, and re-runs that plan item from the start. +The runner does not yet save this proposal, and the Plans screen cannot show or edit one (#155). Today a needs-amendment pause comes from an out-of-scope edit (next paragraph), and the next revision comes from an import or an applied agent draft or suggestion. + If an invocation finishes normally and passes the safety audit but edited an undeclared regular file within the task repository, codeboost still commits the change. Unsafe path, metadata, symlink, or submodule violations instead stop the invocation before any test or commit and move it to needs human. The change shows on that plan item's row, marked out of scope. Execution deliberately pauses in **needs amendment** before any later item or check invocation. A person must approve a revised plan and continuation; the runner reconciles the already-executed prefix with the audited current head, then validates remaining operations from that actual checkpoint. Do not silently add the file to scope or erase its original out-of-scope evidence. **Checking whether the issue is already fixed.** Before it opens the PR, and again before merging, codeboost checks: @@ -567,7 +569,7 @@ The numbers below identify delivery milestones, not a requirement to implement t 3. **Optional validation.** A future real-PR comparison may test the assumptions in "How we will know it works," but it is non-blocking under the superseding decision above. 4. **Merge gate and merging** (product workflow step 9): the merge rules, the pre-merge sequence, and merging through `gh`. Increment 1 merged (PR #23), and merge-queue support merged (#38, #46, closing #24); the rest waits for the runner in build step 5. See the scope and completion criteria below. 5. **Running agents.** Per-task clones, containers, agent adapters, permissions, one invocation per plan item, review rounds, the "already fixed" check, and opening PRs (step 6). Isolation boundary merged (lane D, PRs #31, #40, #44, #47, #50); the runner (lane F) is next. -6. **Planning screen.** Writing plans with an agent, and approving plan changes (steps 2 and 3). Backend in progress (lane E); no screen yet. +6. **Planning screen.** Writing plans with an agent, and approving plan changes (steps 2 and 3). *Done for T18:* planning backend (lane E, E1–E4) and the Plans screen (lane G, G1–G4, #145; PRs #148, #150, #151, #152). Not built: paste import, in-screen editing, the amendment-proposal view, check warnings, answering questions and a whole-plan approval step (#155). The suggestion cards do not yet conform to the v1 contract (#159). 7. **Queue, schedule, and recovery** (steps 4 and 5). 8. **Issue list, sorted by how critical each issue is** (step 1). *Done:* ranking backend (H1–H3), the Issues screen (H4a, #55), and the author-bound "trust this issue" action and runner guard (H4b, #108, PR #139) have merged. 9. **Learning from your feedback** (step 10): lessons, the Lessons inbox, and the Learning screen. It needs the reject loop from steps 4 to 7. @@ -651,8 +653,8 @@ Report the declared-file catch rate for both methods, with no pass bar. It shows ## What to do next -1. Done: create the repository, README, plan/linking foundation, persistent store, and read-only review screen. Also done: the guarded merge gate (PR #23), planning audit and authoring contract (E1, E2), suggestion orchestration (E3), issue ranking backend (H1–H3), merge-queue support (K1–K3), the agent isolation boundary (D1–D5), the runner lifecycle contract (F1) and the Issues screen (H4a). -2. Finish the open lane PRs listed in "Lane status", then continue the roadmap from the current open issues; the cancelled experiment is not a prerequisite. +1. Done: create the repository, README, plan/linking foundation, persistent store, and read-only review screen. Also done: the guarded merge gate (PR #23), planning audit and authoring contract (E1, E2), suggestion orchestration (E3), issue ranking backend (H1–H3), merge-queue support (K1–K3), the agent isolation boundary (D1–D5), the runner lifecycle contract (F1), the Issues screen (H4a), planning acceptance (E4) and the Plans screen (G1–G4, #145; #155 lists unbuilt parts and #159 tracks suggestion-card non-conformance). +2. Finish the open lane work listed in the lane table in `docs/architecture.md`, then continue the roadmap from the current open issues; the cancelled experiment is not a prerequisite. 3. Optionally run the non-blocking human validation tracked in #19. 4. The engineering review (2026-09-22) settled how agents run, their container, network, and permissions. Re-run `/plan-eng-review` before implementing code-writing agents if anything in those areas changes. 5. **Test this document with a reader** (ISO 24495-1 asks for this). Ask one engineer who was not in this session to read the Summary and Terms, then explain codeboost back to you. Fix any part they misread. @@ -1892,9 +1894,11 @@ Critical gaps (no test, no handling, and silent): 0. **Scheduling decision (2026-09-24).** Run up to three implementation tasks concurrently in separate feature branches and worktrees. The foundation and review screen are the baseline, not new assignments. Recheck current main, open PRs, and existing implementations before taking a lane; unchecked historical T-items are not proof that their code is missing. These lanes authorize a development schedule, not simultaneous task execution in the shipped runner. +**Current state.** The lane plans below record the original schedule. B0 and lanes C, D, E, G, H and K are done, so their rows and handoff steps describe past work, not current owners or blockers. For the current state of each lane, see the lane table in `docs/architecture.md`. Before editing a shared file, follow "Task resumption and ownership" in `AGENTS.md`. + #### Lane status (checked 2026-09-26, after #55) -This table records merged and open PRs only. A lane is complete only when every step meets its acceptance criteria on `main`. +This table is a snapshot from 2026-09-26 and is not kept current. For the current state of each lane, see the lane table in `docs/architecture.md`. This table records merged and open PRs only. A lane is complete only when every step meets its acceptance criteria on `main`. | Lane | Merged | Open PRs | Next | |---|---|---|---| @@ -1951,10 +1955,10 @@ Read each row left to right: finish and validate step 1 before step 2 within tha | Lane | Prerequisites | Scope / ownership | Completion check | |---|---|---|---| | F — runner and pre-merge automation | C and D merged; invocation contract available | Build step 5 runner plus #22 / remaining build step 4; T3, T6, T11. Own `runner/`, rebase helpers and shared acceptance persistence during this wave. | Preserve ledger attribution through rebase; recompute approval staleness; execute and persist head-bound checks; cover timeout, cancellation, shutdown and collaborator-push races; complete #22 acceptance. | -| G — planning screen | E merged; C releases shared UI files | Build step 6 UI and T18 integration. Own `web/` and dedicated browser tests during this wave. Route persistence changes through F. UI work can use controlled provider fixtures until D is available. | Import, generation and Apply preserve user drafts and attachments and reject stale/replayed suggestions. Final completion requires real D-backed invocation and integration with F/store, not fixtures alone. | +| G — planning screen | Done: G1–G4 (#145; PRs #148, #150, #151, #152) | Build step 6 UI and T18 integration. During this wave G owned the shared screen files `web/public/index.html`, `app.js` and `style.css` and the Plans browser tests, and released them after G4. `web/server.ts` is F's server contract; G3 changed it once (PR #151) (see `docs/implementation/planning-screen.md`). | Done. Import, generation and Apply preserve user drafts and attachments and reject stale/replayed suggestions. G4 (PR #152) met the final condition: real D-backed invocation and integration with F/store, not fixtures alone. | | H — issue prioritization | Done: access contract and ranking policy (H1); retrieval/ranking (#39, #42); Issues screen (#55); author-bound trust, runner/publish guards, prompt comment evidence, and trust controls (#108, PR #139) | Build step 8: issue retrieval, normalization, ranking, and trust enforcement with dedicated unit, integration, and browser tests. | Done. Stable ranking has visible reasons and explicit unavailable/stale states; H4b persists trust, fails closed at runner and publishing boundaries, controls comment inclusion, records delivered comment evidence, and works in demo mode. | -F, G and H can proceed together within these ownership boundaries. If F and G need an incompatible shared storage/API change, land that small prerequisite first; neither edits the other's files in parallel. Merge independent backend modules first, then their shared integration, and rerun checks on the combined head. +F, G and H ran together within these ownership boundaries. G and H are done; for the current state of each lane, see `docs/architecture.md`. If two lanes need an incompatible shared storage/API change, land that small prerequisite first; neither edits the other's files in parallel. Merge independent backend modules first, then their shared integration, and rerun checks on the combined head. #### Wave 3: lifecycle features and learning @@ -1967,7 +1971,7 @@ F, G and H can proceed together within these ownership boundaries. If F and G ne #### Ownership and integration rules 1. Each task uses its own branch/worktree from current remote main or a documented prerequisite branch. Record its issue, milestone, T-IDs, dependencies, owner and exact files in the PR. Delegated reviewers report findings; the implementation task's main agent owns its writes. -2. One integration owner controls `runner/store.ts`, shared runner/review wiring, `web/server.ts`, `web/cli.ts`, `web/public/app.js`, `web/public/index.html`, `web/public/style.css`, shared browser fixtures, package manifests/lockfiles, schema registry and common CI configuration. C holds this ownership first; in wave 2 F owns runner/storage and G owns web. C owns common configuration in wave 1 and hands it to F before F1; D exclusively owns the new `.github/workflows/agent-isolation.yml`. D must route changes to existing `.github/workflows/ci.yml`, package scripts or lockfiles through the common-configuration owner. Separate worktrees do not remove this constraint. +2. One integration owner controls `runner/store.ts`, shared runner/review wiring, `web/server.ts`, `web/cli.ts`, `web/public/app.js`, `web/public/index.html`, `web/public/style.css`, shared browser fixtures, package manifests/lockfiles, schema registry and common CI configuration. C held this ownership first. In wave 2, lanes F, G and H each held parts of it; G released its shared screen files after G4 (#145). Before editing any of these files now, check open PRs, branches and worktrees, and name one integration owner for any overlap, as "Task resumption and ownership" in `AGENTS.md` requires. The wave 1 plan gave C common configuration, to hand to F before F1, and gave D exclusive ownership of the new `.github/workflows/agent-isolation.yml`, with D's changes to existing `.github/workflows/ci.yml`, package scripts or lockfiles routed through the common-configuration owner. C and D are done. Separate worktrees do not remove this constraint. 3. Keep this plan under one documentation owner. Lane owners record detailed progress and review rounds in their own issues/PRs; the documentation owner updates milestone status after integration. Never check off a milestone because only one parallel increment landed. 4. A blocked integration does not block disjoint modules or fixture work, but those tasks must report the missing production integration. No stub provider, skipped Docker test or mocked merge outcome counts as completed production behavior. 5. Every lane runs its targeted acceptance checks and required regressions. After its final integration change, rerun typecheck, unit/integration tests and applicable browser/Docker checks against the exact pushed head. Complete automated review and the review-lesson audit before an authorized merge. Revalidate downstream work after prerequisite changes. @@ -2134,7 +2138,7 @@ Overall (the lowest pass): **1 → 8**. D22 is complete: DESIGN.md defines the r ### Not in scope - **Phone and tablet layouts.** codeboost is a desktop tool (D25). -- **Queue, Plans, Issues, and Settings screens.** Not reviewed here. Review them before build steps 6 to 8. +- **Queue, Plans, Issues, and Settings screens.** Not reviewed here. The Plans screen (build step 6) and the Issues screen (build step 8) were built without this review; review the Queue screen and the full Settings screen (today a question-agent dialog) before they are built. - **Motion design.** None is needed for this tool. ### What already exists @@ -2161,9 +2165,9 @@ None proposed. Every fix is in the plan and in the tasks below. Built from this review's decisions. Tick each one as you ship it. -**Status (checked against `main` on 2026-09-26).** Only DT1 is complete. Most DTs are partly built. Do not tick one until its Verify line passes. +**Status (checked against `main` on 2026-09-26; Plans entries updated after G4, PR #152).** Only DT1 is complete. Most DTs are partly built. Do not tick one until its Verify line passes. - Built: two-tab composer and "n pending changes" tags (part of DT4); the notice below 1280px (part of DT13); the `?` shortcut help (part of DT12); a blocker list from the guarded merge gate (part of DT7). -- Missing: "Send N change requests" and the reject flow (DT4, needs build step 5's reject loop); the merge step list (D16, DT7); menu links for Plans, Queue, Lessons and Learning, which are plain text until their screens exist (DT8, build steps 6 to 9; Issues became a link in #55); Lessons inbox and Learning screen (DT14, DT15, build step 9). +- Missing: "Send N change requests" and the reject flow (DT4, needs build step 5's reject loop); the merge step list (D16, DT7); menu links for Queue, Lessons and Learning, which are plain text until their screens exist (DT8, build steps 7 to 9; Issues became a link in #55 and Plans in G1, #148); the approved Plans mockup's expandable row editing (not built, #155) and bottom-drawer plan assistant (the built screen puts the assistant in a side panel); Lessons inbox and Learning screen (DT14, DT15, build step 9). - Not yet audited against their Verify lines: DT2, DT3, DT5, DT6, DT9, DT10, DT11. - File paths in the DTs (`web/review`, `web/shell` and others) are proposed names. Today all UI code is in `web/public/`. diff --git a/docs/implementation/issue-prioritization.md b/docs/implementation/issue-prioritization.md index 596b2f09..e94840b5 100644 --- a/docs/implementation/issue-prioritization.md +++ b/docs/implementation/issue-prioritization.md @@ -73,22 +73,25 @@ dedicated read-only gateway with these boundaries: ## Ownership and staged delivery -H1-H3 own dedicated issue retrieval, normalization and ranking modules plus -their tests and this document. They do not edit the Store, runner, shared web -shell, package files or CI. +Lane H is done. H1-H3 owned dedicated issue retrieval, normalization and +ranking modules plus their tests and this document. They did not edit the +Store, runner, shared web shell, package files or CI. **Schedule change (2026-09-25, approved by the product owner).** H4 was planned -to wait for G4 to release the shared web files. G cannot start until E4 merges, -and E4 waits for D5, so the web files had no active owner. H4 therefore takes -them now, split in two: +to wait for G4 to release the shared web files. G could not start until E4 +merged, and E4 waited for D5, so the web files had no active owner. H4 +therefore took them, split in two: -- **H4a (this change): the Issues screen.** It owns `web/server.ts`, +- **H4a (#55): the Issues screen.** It owned `web/server.ts`, `web/public/*`, a new `web/issues.ts`, the demo fixture - `scripts/demo-issues.ts` and their tests. It does not edit `runner/store.ts`. - It hands the web files to G when G1 starts. -- **H4b: the "trust this issue" action.** It records trust decisions through - the storage owner (F) after F1's Store changes land, so the two lanes do not - both bump the schema version. + `scripts/demo-issues.ts` and their tests. It did not edit `runner/store.ts`. + Its plan was to hand the web files to G when G1 started. Lane G has since + finished and released its shared screen files (see + `docs/implementation/planning-screen.md`); `web/server.ts` is lane F's + server contract. +- **H4b (#108, PR #139): the "trust this issue" action.** It was planned to + record trust decisions through the storage owner (F) after F1's Store changes + landed, so the two lanes would not both bump the schema version. H1 is complete when this policy and access inspection are committed. H2/H3 are complete when dedicated tests prove normalized retrieval, deterministic reasons, diff --git a/docs/implementation/planning-screen.md b/docs/implementation/planning-screen.md index 47a3d2b2..b256af71 100644 --- a/docs/implementation/planning-screen.md +++ b/docs/implementation/planning-screen.md @@ -6,7 +6,7 @@ G1 adds a Plans screen over the planning contracts already owned by lanes E and G2 adds browser controls for the existing draft and suggestion request lifecycles. The screen can ask for a complete next-revision draft or independent edit cards, poll the durable request, render the result and dismiss it. -G3 applies a ready draft or one suggestion card through the Store-owned revision-bound endpoint. The browser never constructs a new plan. It retains one action ID across an ambiguous Apply retry, accepts only the expected next revision, then reloads the authoritative review. Once Apply commits, a reload failure is reported separately and cannot re-enable the action or start authoring against the old revision; a manual refresh must observe the applied revision first. Applying one card consumes the response; sibling cards stay disabled and **Refresh suggestions** sends their bounded operation, item and summary descriptions in a new revision-bound request without replacing newer guidance in the textarea. +G3 applies a ready draft or one suggestion card through the Store-owned revision-bound endpoint. The browser never constructs a new plan. It retains one action ID across an ambiguous Apply retry, accepts only the expected next revision, then reloads the authoritative review. Once Apply commits, a reload failure is reported separately and cannot re-enable the action or start authoring against the old revision; a manual refresh must observe the applied revision first. Applying one card consumes the response; sibling cards lose their Apply control (the v1 contract requires a disabled one: #159) and **Refresh suggestions** sends their bounded operation, item and summary descriptions in a new revision-bound request without replacing newer guidance in the textarea. G4 connects those browser flows to the production planning setup rather than a browser-only provider stub. Its acceptance runs suggestions and whole-plan drafts through `productionPlanning`, the real `createPlanningProvider` boundary with deterministic lane D stand-ins, F's production HTTP endpoints and the SQLite Store. It applies each result in the browser, restarts the server between them and reopens SQLite after each Apply. The separate real-Docker suite remains the authority for the concrete clone, bounded storage and Claude adapter implementations. @@ -35,3 +35,11 @@ Suggestion replies render as plain text followed by one line-separated row per t `test/browser/plans-authoring.spec.ts` covers duplicate activation, focus and disabled styling, request-time guidance preservation, exact ambiguous-start replay, a start refused after an intervening import, malformed-status ownership, failed states with impossible output, consumed-result stale labeling, rejection of mismatched bindings, wrong-operation payloads, incomplete edit cards and incomplete nested draft data, hostile markup and attribute text in both result types, retained completed history and invalidated-history labeling, suggestion rows, whole-draft preview without mutation, dismissal and ambiguous-cancellation reconciliation without a revision change, an older poll returning after dismissal, the interleaving where an import advances the plan before an older ready poll returns, single-flight draft Apply with Review text and snippet preservation, committed-Apply reporting when the authoritative reload fails, and exact ambiguous Apply replay followed by sibling refresh and a second revision-bound Apply. `test/browser/plans-production.spec.ts` is G4's composed browser/adapter acceptance. It proves the production issue description, provider schema mount and read-only planning invocation feed F's durable request lifecycle; the browser can render and Apply both result types; and revisions 2 and 3 survive independent Store reopens and a server restart. `test/planning-provider.test.ts`, `test/planning-production.test.ts` and `test/planning-recorded.test.ts` retain the focused adapter, production-wiring and real recorded-output checks. `test/agent-planning.test.ts` retains the real-Docker vendor-egress and cleanup gate. + +## Handoff + +G1–G4 have merged as PRs #148, #150, #151 and #152, which completes lane G (#145). Lane G no longer owns `web/public/index.html`, `web/public/app.js`, `web/public/style.css`, `test/browser/plans.spec.ts`, `test/browser/plans-authoring.spec.ts`, `test/browser/plans-production.spec.ts` or this document. G3 also edited `web/server.ts` and `test/planning-drafts-api.test.ts`; those stay with lane F, which owns the server contract. Before the next change to any file named above, follow "Task resumption and ownership" in `AGENTS.md`: check open PRs, branches and worktrees first. + +The import size gap that G1 found (#146) was fixed by lane F in PR #158: `POST /api/plan/import` now admits every source within the parser's 1 MiB limit (see `docs/plan-format.md`). Three related issues remain open. + +#155: `docs/plan-format.md` and the design doc describe Plans screen features that were not built: paste import, in-screen plan editing, a view of the runner's amendment proposal, check warnings, answering open questions and a whole-plan approval step. #156: the runner-lifecycle decision to revisit E3's early `cancelled` write at G4 was not recorded. #159: the suggestion cards do not conform to the v1 contract, which requires a disabled sibling Apply and a Dismiss on each card. diff --git a/docs/implementation/runner-lifecycle.md b/docs/implementation/runner-lifecycle.md index dcb68072..d8211b04 100644 --- a/docs/implementation/runner-lifecycle.md +++ b/docs/implementation/runner-lifecycle.md @@ -592,7 +592,7 @@ The user approved the proposal for each of these four questions. 4. `lstat` the database path and compare it with step 1's descriptor: same device and inode, a regular file, and a link count of 1. Exit on a mismatch. Keep the lock connection, and so the OS lock, open until shutdown step 8. Renames (including moves between directories on the same filesystem), symlink aliases and relative paths therefore meet the same lock, because they reach the same device and inode. Hard-link aliases are refused. A copy is a different file with a different inode, so it is a different database with its own lock and its own runner owner token. Take the lock at startup and release it at the end of shutdown, by closing the lock connection. Lock files must be on a local filesystem, because POSIX locks are unreliable on network filesystems, so startup refuses a network mount. Do not use a lease row in the main database, because lease expiry could release a live runner. | -| 2 | Does E3 keep writing `cancelled` before the provider settles? | Yes. This exception applies only to read-only phases. | Leave E3 unchanged. New F records use "terminal only after settlement" for every phase. Revisit this when G4 wires the planning endpoints. | +| 2 | Does E3 keep writing `cancelled` before the provider settles? | Yes. This exception applies only to read-only phases. | Leave E3 unchanged. New F records use "terminal only after settlement" for every phase. Revisit this when G4 wires the planning endpoints. G4 merged (PR #152) without recording this revisit; #156 tracks it. | | 3 | Is process shutdown a hard stop? | Yes. | Stopping the process cancels the running task with the reason "Stopped by shutdown". It does not wait for the task to finish. Restart recovery requeues the task. | | 4 | Does F set its own time limit on settlement at shutdown? | No. F waits for D's forced-kill escalation. | Do not abandon a job after a timer. The D5 real-Docker suite must prove that settlement always ends, including for a child process that ignores SIGTERM. D4 does not yet prove it: its cleanup retries have no limit (see the prerequisite under "Shutdown"). If D5 cannot prove it, reopen this decision before F1 merges. | diff --git a/docs/plan-format.md b/docs/plan-format.md index 3fcac869..24bf73d3 100644 --- a/docs/plan-format.md +++ b/docs/plan-format.md @@ -156,6 +156,14 @@ Issue text and agent-produced plan fields remain untrusted. The prompt builder s codeboost keeps the master copy in its own database. The copy in the PR description is written from that master and is never read back. +### What the shipped Plans screen does today + +This guide and the v1 contract describe the full design. The Plans screen built in lane G (#145) differs from it in these ways: + +- **Not built yet (#155):** pasting a plan, editing on the Plans screen, showing check warnings, answering open questions, a whole-plan approval step, and the amendment-proposal flow (the runner does not save a plan-change proposal, and the Plans screen cannot show or edit one; see "When the plan is wrong" in the design doc). Today an import, or an applied agent draft or suggestion, creates the next revision directly. +- **Does not yet conform to the v1 suggestion-card contract (#159):** after one card is applied, the other cards lose their Apply control instead of showing it disabled. One **Dismiss suggestions** control discards the whole response; cards have no Dismiss of their own. +- **Control names:** the import button is **Import next revision**. A suggestion card's button is **Apply this edit**, and a draft's is **Apply draft**. + ## Suggested edits (plan assistant) When you ask the plan assistant on the Plans screen for changes, it answers in the shape of [`schema/plan-edit.schema.json`](../schema/plan-edit.schema.json):