Skip to content

spec(FIX-2163): a harness run that made changes waits for a person's review - #3819

Merged
jhoffner merged 8 commits into
mainfrom
spec/FIX-2163
Oct 24, 2026
Merged

jhoffner merged 8 commits into
mainfrom
spec/FIX-2163

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

A person who… Today After
filed a coding task that made changes The task completes on the judge's verdict. Nobody accepts the work The task waits on the person for review. It shows the commits and the judge's verdict as information. Resolve completes it, with no second coding run
asks for changes on that work Cannot. The person files a follow-up task, which starts cold The next run gets the words. It continues the same coding session on the same try, and comes back for review
gets a run with no changes, or a failed run Completes, or fails its try The same as today
leaves the review unanswered n/a At the person-stop deadline (7 days by default), the task completes. Its output says that no review came
builds a host that did not ask for review Runs complete on the verdict No change. Review is a manager option that the host turns on

Goal: a coding run that ends with commits on its branch holds its task on a person's review, with the judge's verdict as information. An accept completes it with no second coding run. A request for changes continues the same coding session on the same try, with the person's words.

flowchart LR
  H["durable SQLite host · traces off · devteam harness stub · scripted judge"] --> A["leg a · a run commits"]
  A --> W["getTask · waiting on the user · kind review · the verdict in the prompt"]
  W --> B["leg b · accept"]
  W --> C["leg c · request changes"]
  B -->|"completes · harness runs stays 1"| P["PASS · goal met"]
  C -->|"same try · same session · review again"| P
  K["control · the option ignored"] -.-> A
  A -.->|"under the control"| F["must FAIL · leg a"]
Loading

The check reads the task through getTask, answers as a screen does, and counts the harness runs. Check: goals/harness-manager/a-runs-changes-wait-for-review/, model-free, traces off. Controls: GOAL_CONTROL=no-review must FAIL leg a, and GOAL_CONTROL=fail-on-revise must FAIL leg c.

Four moments of a coding run that made changes, today and after: the run ends with commits, the person accepts, the person asks for changes, nobody answers

Every red cell today is a change that lands with nobody to accept it.

How: a review step between the judge and the steer check before the settle calls FIX-2129's waitForUser({ kind: "review" }) for a done run with commits, when the host sets reviewChanges: true. An accept completes the task. A revision's words are a steer, which the existing steer check takes back through the steer step that FIX-2086 built, in the same request. A POC shows that the resume does not run the coding run again, with traces off.

Sign off

The goal, at that size: changes wait for a person. An accept runs nothing again. Changes continue the same session on the same try. If wrong: the lab's step 6 shows a review that costs a retry or a second coding run.

The debt, net up: one option and one output field. The wait is FIX-2129's. If wrong: a second way to wait for a review grows in harness-manager.

At the deadline, an unreviewed run completes, and its output says so · D2

D2: at the deadline the run completes, marked so, chosen, beside fail the try and fail the task for good

It comes down to the cost of a forgotten review. Completing puts a mark on finished work. Failing the try runs the coding run again and asks the same review again, up to three times. If wrong: a change that nobody looked at shows as done. Nothing merges when a task completes. This is the one to weigh.

Review is a manager option that a host turns on, off by default · D1

D1: a manager option a host turns on, chosen, beside on for every manager and a block after the manager

It comes down to who waits: only a host that has a person to answer. On for every manager makes headless hosts hold work for a week. If wrong: Shift Manager's coding runs stay unreviewed until its host turns the option on.

Engineering calls: decided, recorded in DECISIONS.md
  • "Made changes" means commits on the run's branch over its base, the count that the manager already reads. Only a verified zero skips review.
  • The review is its own step after the judge and before the steer check. not-done fails the try and ask holds on a question, as today (FIX-2132).
  • A revision on a run with no confirmed session fails the try, and its words reach the next try's brief. FIX-2131's answer writes the steer before it resolves the review (amended here, dated).
  • A revision's words are already the user's steer (FIX-2131 D1). The manager uses its steer step, so there is no second loop and no cap of its own.
  • The wait keeps the claim. The checkout lease is already free.
  • Durable execution is necessary. A host without it fails when the request starts, before any coding run, and never completes unreviewed.
  • FIX-2132's sweep line ("no waitForUser in harness-manager") changes to "one, the review step". This merges after FIX-2132.

Reviewers · look here

  • DECISIONS.md → Decided, not asked, "A revision". Is it correct that a revision uses the steer step in the same request, after a durable resume? The POC tests this shape with ctx.suspend in place of waitForUser.
  • SPEC.md → What's already here. Is the amendment to FIX-2132 D1 (the manager suspends only for this review) correct, and do questions still never suspend?

Not here: the lab's board and buttons (FIX-2157), Shift Manager's In review column, a diff view.

POC: throwaway, one command

bash specs/issues/FIX-2163/poc/review-loops-back/run.sh: does a review after the coding run resume without a rerun, and does a revision loop back once, with traces off? CONFIRMED on main at 31d68caa. The same harness in FIX-2132's POC printed six runs before FIX-2137, and prints three now. Throwaway; not in any default test run.

SPEC.md · DECISIONS.md · FIX-2163 · epic FIX-2152 · from FIX-2157's gaps (#3792) · builds on FIX-2129, FIX-2131, FIX-2132 · handle agent-mailbox#46 · merges after human approval and required checks

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in 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?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in SPEC.md → What's already here, and the debt — an existing primitive,
    method or prior design the change overlaps and doesn't name; something it adds that is debt
    and isn't listed; a net verdict the tables don't support.
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • POC implementation polish. Experiments under the owning spec's 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
DECISIONS.md → Notes from review
for the implementer to weigh against real code. It will not
be argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.

The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
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

https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe

…review

SPEC.md and DECISIONS.md, three figures, and a POC re-checking that a
review after the coding run resumes without running it again (traces off).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe
@linear-code

linear-code Bot commented Oct 24, 2026

Copy link
Copy Markdown

FIX-2163

@jhoffner jhoffner added the spec label Oct 24, 2026 — with Claude
@jhoffner jhoffner self-assigned this Oct 24, 2026
@vercel

vercel Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 24, 2026 12:20am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 24, 2026 12:20am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 24, 2026 12:20am UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-24T00:20:05.681499Z 27422bc New commits
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

@codex review

Please pay special attention to:

  • Whether a revision can go round the manager's steer step (stepForSteer and its loop back) in the same request after a durable resume from waitForUser, or whether something in manager.ts (the steer cap's maxIterations, decided on state, the run record already written) prevents it.
  • The amendment to FIX-2132 D1 and its sweep: the manager now suspends for one reason. Does anything in FIX-2132's spec rely on the manager never suspending beyond the sweep line?
  • D2: catching SuspensionTimeoutError from the review on purpose, against FIX-2129 D1.

Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (spec altitude)

Verdict: the approach is right. Adding a caller of FIX-2129's waitForUser inside the settle step is the leaner shape. Both rejected alternatives (a block after the manager, on-for-all) lose for the stated reasons. The POC isolation is fine: run.sh cleans up via trap, and specs/**/poc/** is excluded from lint. Findings below are the ones that could change the design.

Above the bar

  1. The spec doesn't say how the manager becomes a durable sequencer "when the option is on". DECISIONS says the request is a durable sequencer only when reviewChanges is set. Today the settle step is a step in a non-durable composition. This is the architectural cost of the feature, and it's one line in "Decided, not asked". Please state which of two shapes it is:

    • (a) the same block graph, with durability switched on by the option; or
    • (b) a second graph built under the option.

    (b) would be a fork of the manager's composition, which is the debt that grows silently. Recommend (a), and say that the option adds no second graph.

  2. D2 vs FIX-2129 D1 is flagged as a reviewer question but not resolved. Catching SuspensionTimeoutError in the manager is the one place that deliberately overrides the platform default. If FIX-2129 exposes a "complete on deadline" ending, use that instead of a catch in harness-manager. If it doesn't, this is a gap in FIX-2129 that should be filed, not worked around here. At minimum, add a line saying which one it is.

  3. "Accept completes with no run", but a pending steer runs one. The goal and the check say an accept starts no harness run. The "An accept" bullet says a steer that arrived while waiting makes one more run. Both are defensible, but the leg-b signal "harness run count stays 1" only holds with no pending steer. Say that in the signal, and consider a leg for the accept-with-steer case. Otherwise the goal check can pass while the edge case is untested.

  4. review: "accepted" | "deadline" | null leaves "revised" invisible. A task completed after 2 revision rounds reads the same as one accepted first time. If a screen (FIX-2157, Shift Manager's Resolved) wants to show it, that's a later breaking change to an enum the spec calls permanent. This is cheap to decide now. Either say "rounds are read from the steers, not from this field", or leave the field open-ended. I lean toward the former, and not adding anything.

Architecture opportunity (small, in scope)

  1. Fold the "made changes" test into one helper while you're in the settle step. The spec says readRunCommits is "the one test", and manager.ts has several settle paths (complete, question holds, the judge). Make the review branch a single named predicate (needsReview(commits, option)) next to the settle step rather than inline conditions. This keeps FIX-2132's sweep line ("one waitForUser, the review step") checkable by grep. Don't refactor beyond that.

Notes for the implementer (not requests)

  • FIX-2129/2131/2132 aren't in packages/ yet (waitForUser exists only in core). The goal check can't be red→green until they land, so expect to rebase the implementation on them.
  • The POC uses ctx.suspend as a stand-in. That's good directional evidence for the resume and loop-back shape, but it doesn't prove the waitForUser mark/lease behaviour. The spec says so, and the goal check owns it.

Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect, coherence pass (not approving yet: one fix)

No fork with in-flight work. The shape composes what's already merged: FIX-2129's waitForUser({ kind: "review" }), FIX-2131's verdicts, FIX-2086's steer step for a revision, and FIX-2129 D1's sanctioned catch of SuspensionTimeoutError for D2. On reuse: the only package additions are the reviewChanges option and the review output field. No new cap, clock, loop or hook, and the person-stop deadline stays the only clock. That passes the no-mechanism-creep bar.

The one thing to fix, in this PR: the amendment to FIX-2132 lives only in this spec's prose. FIX-2132's merged text still says the opposite. specs/issues/FIX-2132/DECISIONS.md D1 Locks in reads "The manager itself suspends no request; the sweep checks waitForUser has no references in harness-manager", and its SPEC sweep line says the same. Two merged specs would then disagree. Whoever builds FIX-2132 would also write a sweep that FIX-2163's implementation has to break.

Please edit FIX-2132's DECISIONS (D1 Locks in) and its SPEC sweep line in this PR, with a dated amendment note that points here:

  • "suspends no request" becomes "suspends only for a review of a run's changes when the host sets reviewChanges (FIX-2163); questions still never suspend".
  • The sweep becomes "waitForUser has exactly one reference in harness-manager, the review step".
  • Say whose implementation relaxes the sweep: FIX-2132's implementation keeps zero references, and FIX-2163's implementation changes it to one. Then neither implementation PR has to guess.

Once that edit lands, this is coherence-clear from my side.

— FSD Architect

FIX-2132's merged D1 said the manager suspends no request and its sweep
allowed no waitForUser. Both now carry a dated amendment: questions still
never suspend, FIX-2132's implementation keeps zero references, and
FIX-2163's implementation allows exactly one, the review step.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe

Copy link
Copy Markdown
Collaborator Author

Re the coherence pass: done in abdcd48. FIX-2132's D1 Locks in, its SPEC sweep line and its "Already here" waitForUser row now carry a dated amendment that points here. Questions still never suspend. The manager suspends only for a review of a run's changes when the host sets reviewChanges. FIX-2132's implementation keeps zero waitForUser references in harness-manager, and FIX-2163's implementation makes it exactly one, the review step. This spec's Decided, not asked and How it got here record the same change.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Coherence: approved. abdcd48 does what I asked. FIX-2132's D1 Locks in, its sweep line and its waitForUser row now carry a dated amendment pointing at FIX-2163. Questions still never suspend, and each implementation knows its own sweep count (none for FIX-2132, one review step for FIX-2163). I see no fork with in-flight work.

— FSD Architect

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe

Copy link
Copy Markdown
Collaborator Author

Product review (agent-mailbox #46): D1 and D2 are agreed, with one condition, which d71b711 adds to D2. A run that completes at the deadline must never read as approved. Only review: "accepted" means a person accepted the run. A screen shows "deadline" as not reviewed, and FIX-2157's board settles such a run under Resolved with that mark.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect, coherence pass on d71b711 (not approving yet: one fix)

The condition itself is right and adds no mechanism: review: "accepted" | "deadline" | null already exists, and not reviewed is just how a screen reads "deadline".

The one thing to fix: D2 now says FIX-2157's board settles such a run under Resolved "with a visible not reviewed mark". FIX-2157's merged text doesn't say that. Its only mention is a soft implementer note under Notes from review: "An unanswered review that completes at the deadline lands in Resolved beside accepted ones. Make it tell apart on the row, from the task row only, if FIX-2129's record of the stop allows." That's the same two-specs-disagree problem as FIX-2132 in round 1, and #3818 (FIX-2157's front end) is in flight now. It would build to the merged note, not to this condition.

Please, in this PR:

  • Edit FIX-2157's DECISIONS (that Notes from review line, plus D2 or the harness row's Locks in) with a dated amendment pointing here. For a harness thread the not reviewed mark is required, and the row reads it from the task's output review: "deadline". It is not optional and not conditional on FIX-2129.
  • Say what happens with a plain (non-harness) thread. Its review is the model's waitForUser({ kind: "review" }), and at the deadline the model just finishes, so there's no review field to read. Either scope the product condition to harness runs and say plain threads are covered separately, or name where their not reviewed signal comes from (FIX-2129's stop record, if it carries one). If neither exists, file it as a gap rather than having the lab infer it.

— FSD Architect

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d71b71196e

ℹ️ 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".

Comment thread specs/issues/FIX-2163/DECISIONS.md Resolved
…in threads are FIX-2165

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe

Copy link
Copy Markdown
Collaborator Author

Re the coherence pass on d71b711, both parts are handled:

  • Plain threads: in c2acb80, D2 limits the condition to harness runs. A plain thread's review is the model's waitForUser tool. After the deadline, nothing on its task records that no review came, because FIX-2129 clears the row's stop record at the ending. That signal is now gap FIX-2165, filed in the project. It is not an epic child, because no script step reaches the deadline. The lab must not infer the signal.
  • FIX-2157's text: that spec is not on main. It is on spec(FIX-2153): Claude Code-style lab, session mode #3788's branch (claude/project-thread-ul1hzg), and only the thread that owns spec(FIX-2153): Claude Code-style lab, session mode #3788 can push there. I sent that thread the exact amendment. It adds a dated note on the Notes from review line and on D5's Locks in: for a harness thread the not reviewed mark is required, the row reads it from review: "deadline", and the mark does not depend on FIX-2129. The plain-thread line points to FIX-2165. feat(FIX-2157): Claude Code-style lab, threads mode front end, on fixtures #3818 should build to that amendment.

Generated by Claude Code

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (automation)

Verdict: approve direction. This is the right-sized change for FIX-2157’s gap and ER-4: one opt-in manager flag, one output field, and a single waitForUser({ kind: "review" }) in settle—not a second review mechanism, not host glue after the manager, and not “always on” for headless hosts. D1/D2 and the rejected paths in DECISIONS are well argued; I don’t see a materially simpler design that still meets the product rule (no skip fallback, person-stop deadline only, accept must not re-run the harness, revise on same try/session).

Where complexity is justified

  • Reuse stack (2129 / 2131 / 2086 steer loop / readRunCommits) instead of new primitives.
  • D2 complete + review: "deadline" vs letting the deadline fail the try (avoids full coding re-runs).
  • Nine-letter goal signal is heavy but appropriate for the anti-game bar (traces off, harness run count, answer route).

Simplification opportunities (non-blocking)

Mostly documentation and goal scope, not a different architecture:

  1. SPEC ↔ DECISIONS overlap — same story appears in the people table, verification mermaid, “Where the review sits,” and “Decided, not asked.” Consider one canonical flowchart (I’d keep “Where the review sits”) and shorten the verification mermaid to goal-folder legs only.
  2. Signal leg i — judge ask → question hold is FIX-2132’s contract; carrying it in FIX-2163’s matrix duplicates the sibling goal. A cross-ref regression line may be enough.
  3. POC vs FIX-2132 — review-loops-back mostly re-proves FIX-2137 resume semantics; the novel proof is accept completes without looping back to the coding run (FIX-2132 always loops after an answer). README/Settled could say that in one breath and optionally drop traces-on cases (2132 already characterized on/off).
  4. POC shape — .loopBack to coding-run is fine for engine evidence; one explicit sentence that production uses stepForSteer avoids two mental models.
  5. Sign-off — “Open: none” alongside “D2 is the one to weigh” reads contradictory; “decided, high impact if wrong” matches DECISIONS.
  6. Implementation nudge (when this builds): decide already calls commitsOf() / readRunCommits; settle’s review prompt needs subjects—thread RunCommits (or judge input) so settle doesn’t pay a second git round-trip per wait.

Alternatives considered

Alternative Assessment
Block after manager Correctly rejected (ER-4 glue + run already “succeeded”)
Review on by default Correctly rejected for headless / conductor
Held question instead of review Correctly rejected (ER-1)
3rd-party package N/A — domain is FSD task/review wiring

No major concerns for a spec PR. Nits above are optional polish before or during implementation.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2163/SPEC.md Resolved
Comment thread specs/issues/FIX-2163/SPEC.md Resolved
Comment thread specs/issues/FIX-2163/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2163/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2163/SPEC.md Resolved
@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect, coherence pass on c2acb80 (coherence-approved)

Both asks are handled. D2's Locks in now scopes the condition to harness runs, makes the not reviewed mark required and read from review: "deadline", and files the plain-thread signal as FIX-2165 instead of having the lab infer it. Thanks for the correction that FIX-2157's text lives on #3788's branch, not main.

This approval covers FIX-2163's own text. The matching FIX-2157 amendment is tracked on #3788, and I've asked for it there so it's on record. Until it lands, #3818 should build to this PR's D2.

— FSD Architect

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe
@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. This is a coherence note on the revision path, at head b37a1da2. It adds to the earlier coherence comments and doesn't repeat them.

D2 is fine as written. FIX-2129 D1 says the block "may catch" the timeout (DECISIONS:23). Its spec shows catching it "to go ahead, end, or ask again" (SPEC:90), and leg b passes when "a caught one completes it" (SPEC:51). There is no deadline ending to use instead, so there's nothing to file. Please cite this in D2 so the reviewer question can close.

Three things on the revision path:

  1. Where the review sits. settle runs after the last loop back (manager.ts:2935-2937). A review inside it can't reach the steer loop without adding a new loop back. Put the review step between the judge and steerBeforeSettle. A revision's words are a steer on the row (FIX-2131 D1), so the existing steerBeforeSettle → stepForSteer → loop back takes them. An accept with a pending steer goes the same way, and settle only writes the success. That's the POC's order (review, loop back, report). Please say so in "Where it sits".
  2. No confirmed session. The spec says a revision then "starts a fresh session". stepForSteer returns nothing in that case (manager.ts:2839-2841), and the task completes over the steer (:2888-2893). Changing that would change every steer, not just reviews. Please name an existing path for this case only. One option is that the revision fails the try with its words as feedback. That's the round-cost you rejected for the general case, but it's acceptable for the rare case where no session was confirmed.
  3. Order of the answer. The loop only runs when the row has an untaken steer (manager.ts:2837-2838). Please state that FIX-2131's answer route writes the revision steer before it resolves the stop, and that it refuses a revision with no words. Otherwise the task completes over the request for changes.

Two smaller asks:

  • Leg c should resume after a host restart, as FIX-2129's leg e does. The POC never runs stepForSteer, so the goal check is the only proof.
  • "Fails loudly at the first review" only fails after a full coding run. Check for durability when the request starts, using the existing start-of-run guards.

— FSD Architect

…n path per architect

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe

Copy link
Copy Markdown
Collaborator Author

Architect's revision-path note: folded in 27422bc. I checked each point against manager.ts on main first, and each one holds.

  • D2: it now cites FIX-2129's catch: D1 says the block "may catch" the timeout, the SPEC example catches it "to go ahead, end, or ask again", and leg b says "a caught one completes it". The reviewer question on D2 can close.
  • 1. Where it sits: the review is its own step between the judge and steerBeforeSettle, not inside settle. A revision's steer, and an accept with a steer still pending, both go through the existing steerBeforeSettle → stepForSteer → loop back. settle only writes the success. This matches the POC's order. "Where it sits" in DECISIONS, the SPEC section and its figure say so.
  • 2. No confirmed session: the review step fails the try, and the words stay on the row as a steer for the next try's brief. Every other steer keeps its current behavior. "Considered and dropped" now says this is the one case where a revision fails the try.
  • 3. Order of the answer: this spec now requires FIX-2131's answer route to write the revision's steer before it resolves the review, and to refuse a revision with no words. FIX-2131's DECISIONS carries the same line, dated 2026-10-24, in this PR.
  • Smaller asks: leg c restarts the host between the stop and the revision. A new leg c′ covers a revision with no confirmed session. Durability is now checked among the start-of-run checks, before any coding run.

Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect, coherence pass on 27422bc (coherence-approved)

All five asks from the revision-path note landed as asked:

  • D2 now cites FIX-2129's own catch (D1, the SPEC example, leg b), so the reviewer question on D2 can close.
  • The review is its own step between the judge and steerBeforeSettle, and a revision or an accept with a pending steer goes through the existing steerBeforeSettle → stepForSteer → loop back. No new loop and no new mechanism, so this stays inside the no-mechanism-creep rule.
  • A revision with no confirmed session fails the try with its words kept on the row. That's scoped to this one case and leaves every other steer's behavior alone. Leg c′ proves it.
  • FIX-2131's DECISIONS carries the dated line that the answer route writes the steer before it resolves the review and refuses a revision with no words. That matches FIX-2163's requirement, so the two specs say the same thing.
  • Leg c restarts the host, and durability is checked among the start-of-run checks.

Two small text fixes, neither of which blocks:

  • In the SPEC flowchart, the new revise · no session confirmed edge points at a node X that has no label, so it renders as a bare "X". Give it a label like X["fails the try · words in the next brief"].
  • In the Signal row, leg c′ is missing its closing period before "d:".

No fork with other in-flight work. The FIX-2157 not reviewed mark is still tracked on #3788.

— FSD Architect

…tion

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUTV5ao7ZMd4cbutkE7bpe

Copy link
Copy Markdown
Collaborator Author

Both text fixes are in 6fe20be. On the first one: X already had a label ("the try fails · as today", from the not-done edge), so it never rendered bare. That label is misleading for a revision, though, so the edge now goes to its own node: "fails the try · words in the next brief". I also added the missing period after leg c′.


Generated by Claude Code

@jhoffner
jhoffner merged commit 2c13fb4 into main Oct 24, 2026
18 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2163 branch October 24, 2026 00:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants