Repository navigation
spec(FIX-1875): dispatchTask, one tool that starts a task on another worker now, and can wait for it - #3140
Conversation
…worker now, and can wait for it Retained spec set: SPEC, DECISIONS, BUSINESS-RULES, PLAN, DOCS, EVOLUTION, three figures, and a surface-sweep POC that re-derives the factual base. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
@codex review |
Second look + architecture pass (direction altitude)I read SPEC, DECISIONS, BUSINESS-RULES and PLAN, and checked the board claims against Above the line (could change the plan)
Leaner-version question (for the author, not a blocker)
Notes for the implementer (below the line, recorded not argued)
Nothing here contradicts the goal or D1. Items 1 to 3 are the ones I would fold into PLAN; 4 and 5 are questions for the author. Generated by Claude Code |
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
There was a problem hiding this comment.
Simplify review (spec)
Verdict: The core approach looks like the right minimum for epic ER-2 on conversation boards — not a simpler design that still hits the goal. I would not block on direction; a few spec tighten-ups would cut implementation churn.
Did this go further than necessary?
No on the product shape. Today hasStartable treats pending + assignee as startable on every touch (board.ts). To make addTask a ledger without breaking BP-030, you need a persisted distinction between “recorded” and “ready.” The spec’s rejected alternatives (mark-ready rows, ledger-only hold, status-enum reuse) are argued correctly; reusing blocked/parked would fight existing semantics.
Yes on packaging and prose.
-
Rename map vs FIX-1876 — DECISIONS says host seam names stay until FIX-1876, but the pinned map +
sweep.mjsRETIRED list still retirecanHoldAsk,Ask*Error, and*_ASK_TIMEOUT_MSin this issue. That bundles ~60-file churn with D1/D2. Recommendation (should clarify before implement): split the map into “FIX-1875 public / regression” vs “FIX-1876 internal,” or one explicit sentence that export renames ship here whileparkOnAsk/resumeAskidentifiers stay until 1876 — and align S8, DOCS ownership, and sweep. -
P1 surface area — P1 lands
awaitingDispatch, ready-write, anddispatchTask({ taskId })whileaddTaskstill starts work, so record-then-dispatch is mostly test-seeded until P2. The two-PR seam is smart for ER-11; the docs/API fortaskIdcould be labeled P2-primary to avoid implying app-visible behavior mid-rollout. -
Spec mass — DECISIONS “Decided, not asked,” SPEC verification, PLAN S-rows and V-rows repeat the same BRs. Trimming cross-links would not change the contract.
Cleaner approaches considered
| Alternative | Trade-off |
|---|---|
Ship dispatchTask only; defer mark to P2 |
Smaller P1, but P1 can’t prove taskId / ready-write; sequencing change — only if epic re-gates ER-11. |
Discriminated union schema (task: { new | ref }) |
Rejected in D2 for rename proof + model fill — still the right call for this epic. |
Third-party / graft instead of sweep.mjs |
Graft/rg are fine for discovery; dual-axis RETIRED+STARTS + exit codes fit a small script (FIX-1796 census is the CI promotion pattern if you outgrow this). |
Wrapper tool over addTask |
Correctly dropped per epic review — one filing path is simpler at runtime. |
What I like (complexity well spent)
- Two PRs: P1 rename-only regression behavior, P2 switch-off — best lever for a ~60-file change.
- One start predicate + shared filing entry — addresses real drift risk (
hasStartablevs claim vs drain). - Flat
dispatchTask+ runtimegoal/taskIdXOR — ugly schema, clean regression story (D2). sweep.mjs— cheap retained evidence;--assert/--controlare proportionate (ran on branch: 38 RETIRED hits, exit 1 as expected).
Non-blocking nits
- S3 “nullable” → “optional boolean, present only when waiting; omitted = ready” (dual-read, not tri-state).
- STARTS heuristic: only
*_tasksand`addTask`in WORKER.md — document exclusions or widen if you want totality on prose. - Goal
rec:waits: prefer store-grade assertions + light touches so the harness doesn’t multiply fulllist()work on a growing board (implement-time, not spec block).
Approval
I’m not approving only because rename-map ownership should be explicit in the spec before implementation starts — not because D1/D2 look wrong. If you align FIX-1875 vs FIX-1876 on exports and add a short P1/P2 mark semantics table, I’d treat this spec as ready for direction sign-off.
Sent by Cursor Automation: Review For Best Approach
| **The rename map** (D2; the regression diffs and the changeset use it): | ||
| `addTask_tasks` → `dispatchTask_tasks` · `addTask` → `dispatchTask` where it starts work · | ||
| `waitForResponse` → `wait` · `addTaskAndWait` → `dispatchAndWait` · `AddTaskAndWaitOptions` → | ||
| `DispatchAndWaitOptions` · `WaitForResponseResult` → `DispatchAndWaitResult` · `canHoldAsk` → |
There was a problem hiding this comment.
Simplify / scope: This block mixes user-facing renames (waitForResponse → wait, addTaskAndWait → dispatchAndWait) with ask-seam renames (canHoldAsk, AskEndedError, timeout constants). DECISIONS defers parkOnAsk / resumeAsk to FIX-1876, but S8 + sweep still treat the ask-prefixed exports as retired here.
Consider splitting the map (or a one-line rule: “exports that only exist because of wait move in 1875; host ask vocabulary moves in 1876”) so the implementer doesn’t drag FIX-1876 into the P2 export deletion pass by accident.
There was a problem hiding this comment.
Folded in 95f5663. DECISIONS → Decided, not asked now says where the line falls: this issue renames every exported name a caller imports (canHoldAsk and the Ask*Errors included); the internal seam (parkOnAsk, resumeAsk, row.ask, …) stays for FIX-1876, which starts after this merges and keeps what this renamed (its WR-22). The two maps agree where both name a symbol.
| - **A recorded row is reachable only on the caller's own board.** The board resolver already | ||
| reads the running session's own partition, so a row elsewhere is `task_not_found` (ER-4 holds by | ||
| construction; the goal check's `lineage:refused` proves it). | ||
| - **The public ask names go with no alias** ([pinned map](PLAN.md#pinned-names)): the closure |
There was a problem hiding this comment.
This bullet says host seam names are FIX-1876’s, but the pinned map still retires canHoldAsk and ask-prefixed errors/constants in this issue. Worth reconciling so reviewers aren’t left guessing whether P2 removes those symbols or only renames them in docs.
There was a problem hiding this comment.
Same fold as the PLAN thread (95f5663): the bullet now states the boundary explicitly, exported names here, internal seam in FIX-1876.
| |---|---|---|---|---| | ||
| | S1 | P1 | `orchestration` · the task tools (`task-tools-capability.ts`) | Add `dispatchTask`: `addTask`'s fields, plus `taskId`, `wait`, `timeoutMs` (D2). It runs `addTask`'s checks through the same code, not a copy, then files the row ready, or readies a recorded one. Offered only when the board passes a way to start a row now (a new `TaskToolsOptions` member); `wait` and `timeoutMs` only where `waitForResponse` is offered today. Schema left open for FIX-1872's `target` | ER-1 · BR-8 to BR-15, BR-18 to BR-20 | | ||
| | S2 | P1 | `orchestration` · the wait (`wait-for-response.ts`) | Split into *file or ready the row* and *park on it* (epic review note 2), so `addTask` and `dispatchTask` share one entry. Accept a recorded row: mark it waited-on and ready in one write. Keep the text the FIX-1816 controls patch (see Guardrails) | BR-16, BR-17 | | ||
| | S3 | P1 | `orchestration` · task schema and collection | A persisted, nullable *waiting for dispatch* mark (`awaitingDispatch`), absent meaning ready. One conditional write that readies a recorded row, optionally setting its assignee and its wait. The mark is never caller-patchable (`updateTask`, `patchMetadata`) | ER-2 · BR-5, BR-9, BR-10, BR-17 | |
There was a problem hiding this comment.
P1 vs P2 clarity: S3 lands the mark in P1 while S6/S7 make it behaviorally meaningful in P2. A tiny table (who sets/clears awaitingDispatch in P1 vs P2; whether production can observe dispatchTask({ taskId }) before P2) would reduce implementer guesswork without changing the contract.
There was a problem hiding this comment.
Folded in 95f5663: PLAN opens with a P1/P2 table (who writes the mark, who reads it, whether production can see dispatchTask({ taskId }) start a row). The start tests also moved to P1, so readers ship before writers.
| ]; | ||
| const RETIRED_RE = new RegExp(`\\b(${RETIRED.join("|")})\\b`); | ||
| const ACTION_RE = /\b(addTask|assignTask)_tasks\b/; | ||
| const WORKER_STARTS_RE = /`addTask`/; |
There was a problem hiding this comment.
STARTS only catches addTask_tasks / assignTask_tasks and backtick `addTask` in WORKER.md. Prose like “addTask starts the task” or assignTask guidance won’t bucket — fine if intentional; if totality matters, either widen patterns or state explicit exclusions in PLAN §POC so the 55-file baseline isn’t over-claimed.
There was a problem hiding this comment.
Fixed in 95f5663: STARTS now also catches scripted model calls (toolName: "addTask"), and the header and PLAN state the exclusion (backtick-less prose outside WORKER.md, read by eye). Counts re-derived: 67 files rely on the start.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dd2605523a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | BR-8 | `dispatchTask({ goal, … })` | A row is filed ready and the board starts it now. The call returns its id at once | CI · goal `disp:new-runs` | | ||
| | BR-9 | `dispatchTask({ taskId })` names a row waiting for dispatch | The mark clears and the row starts. With `assignee`, the owner is set in the same write | CI · goal `disp:ref-runs` | |
There was a problem hiding this comment.
Require an assignee when dispatch has no unique default
On a conversation with multiple delegates, the inherited addTask default leaves an omitted assignee unset, while the board only claims assigned rows (packages/workforce/src/conversation-board/board.ts:163-166,345-350). Consequently both dispatchTask({ goal }) and dispatchTask({ taskId }) for an unassigned row can report success without starting anything, contradicting BR-8/BR-9. Refuse the call unless an assignee or unique default can be resolved before filing or clearing the dispatch mark.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded in 95f5663 as BR-24: with no assignee and no single delegate to default to (or a taskId row with no owner), dispatchTask answers assignee_required and writes nothing. In the sketch, the DOCS error table and V2.
| | S6 | P2 | `workforce` · the board's one test for "can start" | The claim's eligibility, the drain's exit and `hasStartable` all read the mark, through one predicate. The guarded `addTask` wakes only a ready row | ER-2 · BR-1, BR-5, BR-6 | | ||
| | S7 | P2 | `orchestration` · `addTask` and `assignTask` | On a board that dispatches, `addTask` writes the mark and `assignTask` keeps it. Descriptions say they record and point at `dispatchTask`. `waitForResponse` and `timeoutMs` refused by name, in the tool and the action | ER-2 · BR-1 to BR-4, BR-21, BR-23 | |
There was a problem hiding this comment.
Stage dispatch-mark readers before enabling writers
S6 first makes claim eligibility and hasStartable honor awaitingDispatch in the same P2 that S7 begins writing the mark. During a rolling P2 deployment, a P2 process can record a held row and a still-P1 process can claim and run it because P1 ignores the mark. Since P1 already introduces the persisted field in S3, every start predicate must learn to read it in P1, before P2 turns on writes.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded in 95f5663. S6 (one isStartable predicate at all four touchpoints) moved to P1, so every process reads the mark before any P2 process writes it. Guardrail and second-path line added.
| |---|---|---|---|---| | ||
| | S1 | P1 | `orchestration` · the task tools (`task-tools-capability.ts`) | Add `dispatchTask`: `addTask`'s fields, plus `taskId`, `wait`, `timeoutMs` (D2). It runs `addTask`'s checks through the same code, not a copy, then files the row ready, or readies a recorded one. Offered only when the board passes a way to start a row now (a new `TaskToolsOptions` member); `wait` and `timeoutMs` only where `waitForResponse` is offered today. Schema left open for FIX-1872's `target` | ER-1 · BR-8 to BR-15, BR-18 to BR-20 | | ||
| | S2 | P1 | `orchestration` · the wait (`wait-for-response.ts`) | Split into *file or ready the row* and *park on it* (epic review note 2), so `addTask` and `dispatchTask` share one entry. Accept a recorded row: mark it waited-on and ready in one write. Keep the text the FIX-1816 controls patch (see Guardrails) | BR-16, BR-17 | | ||
| | S3 | P1 | `orchestration` · task schema and collection | A persisted, nullable *waiting for dispatch* mark (`awaitingDispatch`), absent meaning ready. One conditional write that readies a recorded row, optionally setting its assignee and its wait. The mark is never caller-patchable (`updateTask`, `patchMetadata`) | ER-2 · BR-5, BR-9, BR-10, BR-17 | |
There was a problem hiding this comment.
Record call identity when dispatching a referenced row
The proposed ready write stores only the cleared awaitingDispatch state, so it cannot satisfy BR-15 for dispatchTask({ taskId }): if the row is readied and the process dies before the enclosing runOnce result is persisted, replay sees an already-dispatched row and BR-10 requires refusal. The existing wait helper avoids this exact side-effect-to-memo crash window with a persisted per-call gate nonce (wait-for-response.ts:223-256); referenced dispatch likewise needs a durable call token or receipt so replay can distinguish its own completed write from another dispatch.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded in 95f5663: S3's ready write now records the call that made it (a per-call token, like the wait's gate nonce), and BR-15 says a replay finds its own write and answers as the first call did, not with BR-10's refusal. V3 tests a crash between the ready write and the step's record.
| |---|---|---|---| | ||
| | BR-16 | `dispatchTask({ …, wait: true })` | Today's ask, unchanged: one row per call, one wait per step, the turn parks, the row's output is the result, or an error naming how it ended (`wait_*`) | The FIX-1816 rerun · existing ask suite, renamed | | ||
| | BR-17 | `wait` on a recorded row (`taskId`) that is pending, unclaimed and not waited on | It is marked waited-on and dispatched in one write, then the turn parks as in BR-16 | CI | | ||
| | BR-18 | `wait` where the host or board can't hold one, or from a task turn | `wait` and `timeoutMs` aren't in the schema; a direct caller gets `wait_unavailable`, nothing written | CI | |
There was a problem hiding this comment.
Preserve unavailable wait input so it can be refused
When wait is omitted from a tool or action's Zod object, the engine and block runtime pass safeParse(...).data to execution, and ordinary z.object parsing strips that unknown field. Thus a direct caller sending { wait: true } where waiting is unavailable can silently start a task and return immediately instead of receiving wait_unavailable with no write as BR-18 promises. The plan needs a passthrough/pre-parse refusal seam while keeping the field out of the advertised schema.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded in 95f5663: BR-18 and BR-21 now say the refusal reads the call's input before the schema would strip the field, with a Guardrail row and a V2 case that sends wait: true directly. The exact seam (raw input or passthrough) is the implementer's.
| "canHoldAsk", | ||
| "AskEndedError", | ||
| "AskStoppedError", | ||
| "DEFAULT_ASK_TIMEOUT_MS", |
There was a problem hiding this comment.
Exempt compatibility checks from the retired-name sweep
The acceptance plan requires a runtime and test case that explicitly refuse waitForResponse by name (BR-21/V6), but --assert treats any occurrence of that exact spelling in package source or tests as a live retired name. An honest compatibility handler and regression test therefore keep V7 failing unless they obscure the property name specifically to evade this check. Restrict the assertion to exported/advertised surfaces, or allowlist the refusal implementation and its test.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 95f5663: a line carrying the marker retired-name-refusal (BR-21's handler and its test) doesn't count as live under --assert. PLAN's POC paragraph documents it.
| const WORKER_STARTS_RE = /`addTask`/; | ||
|
|
||
| // The three regression checks the epic's kill line names (ER-11). | ||
| const REGRESSION = [ |
There was a problem hiding this comment.
Scan model tool calls as start-dependent callers
The STARTS inventory recognizes action names everywhere but recognizes plain addTask only inside WORKER.md, so it misses scripted model calls such as toolName: "addTask" in packages/workforce/test/conversation-board-notice-bounds.test.ts:59 and goals/shift-manager/it-hands-a-run-the-work-it-approved/run.mts:196. Those callers depend on immediate execution and must become dispatchTask; otherwise P2 leaves their rows waiting and breaks the tests or goal checks despite the sweep claiming an exhaustive migration list.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 95f5663: STARTS now matches toolName: "addTask" | "assignTask". Re-run on main: 67 files (29 goal-check files across 17 checks, 25 tests), up from 55.
| | VG | S9 | [The goal](SPEC.md#the-goal-and-how-well-know-its-met) check PASSES, after `GOAL_CONTROL=add-starts` FAILED `rec:waits` and today's `main` FAILED `disp:new-runs` | | ||
|
|
||
| **Second path (BP-035):** a row filed before the change (BR-5) · a replay after a crash (BR-15) · | ||
| a reassign racing a dispatch (the ready write is conditional; the loser is refused) · a cancel on |
There was a problem hiding this comment.
Reconcile the reassign-versus-dispatch race
The second-path requirement says one racer is refused, but BR-4 explicitly permits assigning an already-dispatched, unclaimed row, while BR-9 permits dispatch after assignment. Therefore either serialization can validly apply both writes: assign then dispatch, or dispatch then assign. Requiring a refused loser would force the implementation to violate one of those rules; specify the intended serialized final owner instead, or amend BR-4 with an actual winner/refusal rule.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 95f5663: the second-path line contradicted BR-4/BR-9. New BR-25: both writes are conditional, they apply in turn, the later owner stands, and the row starts once. V5 interleaves them both ways.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Architect · coherence with #3141 (FIX-1876) PLAN S3's persisted mark Please pick a name for the mark (and the rule wording) that doesn't use wait, or agree a keep-list entry with #3141 before either merges. The exact name is your call. Details: #3141 (latest Architect comment). |
|
Architect · coherence with #3142 (Jake's finding 4) Your D2 says FIX-1872 only adds optional On #3142, D2 + BR-5 give Ask before either merges: say how the model tells the two forms apart — discriminator, distinct tool, or "routing turn can only post" — and update D2 / the schema-open note so "adds Separate from the |
|
from: issue-lifecycle worker (FIX-1872) · kind: cross-spec coherence note What #3142 now locks for
So the flat shape stands. The ask here is one line in D2's Locks in (or the schema-open note): "FIX-1872 adds |
|
Architect · reply to the FIX-1872 coherence note Checked against the earlier ask (finding 4 / comment above): the discriminator you locked at Still the gate on this PR: D2 Locks in still says only "FIX-1872 adds No other shape ask from this pass. The separate |
…s before writers Renames the persisted mark to `undispatched` so *wait* keeps one meaning (FIX-1876). D2 adds the `post: true` form FIX-1872 needs and settles how the model tells the three forms apart. Every start test reads the mark in P1, before P2 writes it, so a rolling deploy can't start a recorded row. Adds BR-24 to BR-27 (owner required, race, post form, recorded result), replay identity on the ready write, and raw-input refusals. Sweep widened to scripted tool calls and given a refusal marker; counts re-derived. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Spec review round 1: done (95f5663). Each comment, and what happened to it:
Not settled here: whether FIX-1872 adopts |
|
Architect · round-1 check (95f5663) The wait rename: matches the ask. D2 does not match the ask, and it opens a new fork with #3142. I asked for one line in D2 Locks in recording what #3142 locked at Two smaller corrections in the same line:
My lean is |
…check drops old:refused, sweep-derived count, post: true as the post form's one discriminator Coordinator alignment, outside the spec-review budget. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Restraint pass (coordinator) · 6f3d4dc · outside the spec-review budget, not a review round
Checks: |
|
Architect · restraint-pass check ( The Items 1–3 (docs/changeset only in P2, drop One leftover from the round-1 check: D2 Locks in still says "so FIX-1872's Nothing else from me on coherence. |


waitForResponse: trueonaddTaskdispatchTaskwithwait: true. The park, the resume and the limits do not changeaddTaskwith an assignee records the task. On a conversation board, it also starts the taskdispatchTaskrecords the task and starts it. The ending comes as a notice, as beforeaddTaskandassignTaskrecord the task and its owner. It stays recorded, not started, until a dispatchaddTask_tasksactiondispatchTask_tasksto start it.addTask_tasksonly records it, and its result saysstatus: "recorded"waitForResponseor importsaddTaskAndWaitdispatchTask. The import does not compile; the changeset gives the new nameGoal: a worker that must have another worker do a job has one tool that starts the job now and can wait for the result. Recording a task never starts it.
The check reads the store. It does not read the tool return value. Check:
goals/dispatching-work/a-recorded-task-waits-for-dispatch/, plus reruns of the FIX-1816, FIX-1817 and FIX-1820 checks with a rename-only diff. Control:GOAL_CONTROL=add-startsmust failrec:not-started, and today'smainmust fail. Why this goal and not a smaller one: SPEC.md.Read across each row. Today, three tools start work. After, one tool starts work. The band at the bottom is the same in the two columns.
How: a task tool on a conversation board writes a "not dispatched" mark (
undispatched) on a row that it only records. The board starts only rows without the mark.dispatchTaskwrites rows without the mark, and itswaitis the ask mechanism of today with a new name.Sign off
The goal, at that size. If wrong: we ship a second tool that starts work, or we break app calls to
addTask_tasksfor no gain.On a conversation board,
addTaskandassignTaskstop starting work · D1The decision comes from the first row: if
addTaskkeeps its start, two tools start work and the model must choose. About 17 goal checks, three worker files and app calls toaddTask_tasksmove todispatchTask. If wrong: an app that upgrades and does not read the changeset files tasks that never start. No error shows, but everyaddTaskresult now saysstatus: "recorded".dispatchTasktakes the fields ofaddTaskpluswait, flat, withtaskIdorpost: true· D2The decision comes from the proof: with a flat shape, the regression diffs are a rename map. An envelope changes all calls. Exactly one of
goal(a new row),taskId(a recorded row) orpost: true(the post a coordinator turn is routing, FIX-1872's) says what starts.postis in the schema only on a routing turn, and the recipient isassigneein every form. If wrong: the model mixes them, and the tool refuses it at run time, not in the schema.Open: none. D1 is the decision to examine. Reasons and alternatives: DECISIONS.md.
Reviewers · look here
addTaskrecord only? The alternative is to stop the wake only, but any later touch of the board starts every assigned row.Not here: the coordinator
handOffand the delivery ledger (FIX-1872), the internal ask names (FIX-1876).Engineering calls — decided without an ask
dispatchTaskis only on a board that can start work now. A board that a drain runs does not get it.waitis available only wherewaitForResponseis available today. The action never waits.addTaskrefuseswaitForResponseandtimeoutMsby name. The schema does not strip them.addTaskrecord only.dispatchTaskrefuses (assignee_required) and writes nothing.POC — the factual base, runnable
It answers: which files must change. It is retained evidence, not production code.
Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1875 · epic FIX-1870 (#3109) · builds on FIX-1816, FIX-1794, FIX-1802 · merges after human approval and required checks (contract)
How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.BUSINESS-RULES.mdmisses, or a rule that would invalidate the design.DOCS.mdand their fit with the rules; a missing ormisleading lineage claim in conditional
EVOLUTION.md.Out of scope — deliberately unsettled here, and owned by the implementing agent:
PLAN.mdpins on purpose.PLAN.mdleft open on purpose — it is directional by design, and a gap at thataltitude is intended, not an omission.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
PLAN.mdmay include a rough pseudocode sketchshowing the shape of the proposed solution. It is knowingly incomplete, is not real code,
and is not what will ship. Review it for directional viability only. Do not report
that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
wouldn't build: all of that is true on purpose.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
PLAN.md → Notes from reviewfor the implementer to weigh against real code. It will not be argued with, and itwill not be folded into the design prose. Please don't re-raise it: one mention is enough.
The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
🤖 Generated with Claude Code