Plan Review Operations Rollout
Move plan-review activity into a durable local service while preserving the authoritative plan source on disk.
1.1 / Review decisions
Review decisions
The remaining choices set the persistence and rollout boundaries.
This plan is approved. To choose an option, revoke the approval first.
Decision
Where should review-event persistence live?
The first release runs locally, but the storage boundary should admit shared review later.
This decision changed after you answered it. Answer it again to record your choice.
Select an option to continue.
This review is read-only, so no answer can be recorded.
Answer recorded
Noted for this reading session.
This review is read-only, so no answer can be recorded.
Not saved yet. Big Plan is retrying automatically.
This plan is approved. To choose an option, revoke the approval first.
Ship the workspace behind a local feature flag?
This decision changed after you answered it. Answer it again to record your choice.
Select an option to continue.
This review is read-only, so no answer can be recorded.
Answer recorded
Noted for this reading session.
This review is read-only, so no answer can be recorded.
Not saved yet. Big Plan is retrying automatically.
Which event store should back the first release?
The store must preserve thread order, anchor updates, and crash-safe writes.
Reversibility · somewhat hard
The repository seam contains the code change, but persisted local data still needs a migration.
2.1 / System shape
System shape
How one authoritative plan reaches the service, browser, and authoring agent.
Author
plans/review-rollout.mdxReview
src/review/service.tsConsume
Review acceptance can also cycle a plan back to its source before execution begins.
- src/
- review/
- service.ts- Coordinates plan reads and review events.
- repository.ts- Owns durable event transactions.
- anchors.ts- Reconciles selections after source edits.
- render/
- shell/
- viewer-script.ts- Sends review actions to the local service.
- src/
- review/Added
Note
New review-service vertical slice.- service.tsAdded
Note
Coordinates review workflows. - repository.tsAdded
Note
Persists ordered events.
- render/
- shell/
- viewer-script.tsModified
Note
Connect review controls.
- test/
- review-service.spec.tsAdded
Note
Exercises the durable browser journey.
- docs/
- review-workflow.mdAdded
Note
Explains the local review loop.
- src/
- render/
- shell/
- viewer-script.ts
Note
Connect review controls.
- test/
- docs/
- src/
- review/Added
Note
New review-service vertical slice.- service.tsAdded
Note
Coordinates review workflows. - repository.tsAdded
Note
Persists ordered events.
- render/
- shell/
- viewer-script.tsModified
Note
Connect review controls.
- test/
- review-service.spec.tsAdded
Note
Exercises the durable browser journey.
- docs/
- review-workflow.mdAdded
Note
Explains the local review loop.
- src/
- review/
Note
New review-service vertical slice.- service.ts
Note
Coordinates review workflows. - repository.ts
Note
Persists ordered events.
- render/
- shell/
- viewer-script.ts
Note
Connect review controls.
- test/
- review-service.spec.ts
Note
Exercises the durable browser journey.
- docs/
- review-workflow.md
Note
Explains the local review loop.
3.1 / Service contracts
Service contracts
The code, storage, and transport contracts that make review events durable.
| Column | Type | Constraints | Default | Comment |
|---|---|---|---|---|
| id | bigint | PK·Identity·not null·INDX 1 | ||
| plan_id | text | not null·INDX 1 | ||
| thread_id | text | not null·INDX 1 | ||
| kind | text | not null | comment | reply | resolve | accept | |
| body | text | nullable | ||
| anchor_json | text | nullable | ||
| created_at | timestamptz | not null | now() |
Indexes
- INDX 1review_events_thread_idx
plan_id, thread_id, id
Visible columns
Group by
| Gate | Owner | Error budget | Evidence |
|---|---|---|---|
| Event durability | Service | 0 | Crash-recovery integration test |
| Anchor reconciliation | Renderer | 1 | Edited-source replay fixture |
| Workspace rollout | Product | 2 | Maintainer dogfood sessions |
No rows match this filter.
Clear the filter to see every row again.
Persists one ordered event and its current source anchor in the same
transaction. Clients use clientEventId to retry safely after a lost response.
- planId string required
Stable identifier for the authoritative plan source.
- threadId string required
Thread receiving the event.
- clientEventId string required
Client-generated idempotency key for this append attempt.
- kind comment | reply | resolve | accept required
Review action represented by the event.
- body string optional
Comment or reply text. Omitted for resolve and accept events.
- anchor SourceAnchor optional
Source location the event refers to, captured against the current plan revision.
{
"threadId": "thr_01K1Q8WZ3B4N6M7P9R2T5V8X0Y",
"clientEventId": "evt_client_01K1Q91C8Y2F6G4H7J3M5N0PQS",
"kind": "comment",
"body": "Keep the retry budget explicit in the service contract.",
"anchor": {
"path": "src/render/shell/viewer-script.ts",
"startLine": 414,
"endLine": 417,
"planRevision": "sha256:7a1d56c4"
}
}
{
"eventId": "evt_01K1Q91DD5Z8A2B4C6E7F9G0HJ",
"threadId": "thr_01K1Q8WZ3B4N6M7P9R2T5V8X0Y",
"sequence": 7,
"status": "open",
"createdAt": "2026-08-05T19:42:11.392Z"
}
{
"error": "thread_sequence_conflict",
"expectedSequence": 6,
"currentSequence": 7
}
{
"error": "invalid_source_anchor",
"field": "anchor.startLine",
"message": "startLine must exist in plan revision sha256:7a1d56c4"
}
4.1 / Desired experience
Operator workspace
The operator opens unresolved threads, sees the selected plan excerpt, and records a resolution without leaving the review queue.
Big Plan
Local review
Plan review
Threads
- Keep the retry budget explicitCode change
- Clarify the migration ownerDecision
- Add the rollback queryRollout
The plan is ready to execute when every gate has an owner, every unresolved thread has a verdict, and the reviewer explicitly accepts the plan.