Skip to content

spec(FIX-1794): best fit hears its tasks by turn; leg e names both refusal codes - #3099

Merged
jhoffner merged 3 commits into
mainfrom
claude/project-thread-pzekso
Oct 12, 2026
Merged

jhoffner merged 3 commits into
mainfrom
claude/project-thread-pzekso

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Before: FIX-1794's retained spec said only a judgment coordinator hears a filed task end in its own turn, and that any other routing policy shows the ending as a line. That has been wrong since FIX-1863 (#3035). Leg e's signal named only one refusal code for a finished task.

After: the spec says a coordinator that routes by judgment or by best fit reads the result in its own turn. One that routes round robin or to everyone shows it as a line. Leg e names both codes a finished task gives: terminal_task_write_declined (assign, cancel, update, answer) and illegal_status_transition (complete, fail, block).

How: this is an after-merge amendment to specs/issues/FIX-1794/. It updates the DOCS.md draft under Hearing how it went, PLAN S7, and the leg e signal in SPEC, and adds a DECISIONS bullet. The claims were checked against coordinator-flow.ts (the board's entries: routing === "judgment" || routing === "best-fit") and task-tools-capability.ts (the two error builders). It is spec-only, with no code and no changeset. The goal itself already passes on main after #3035, so this changes no behavior. #3035's three code nits were not carried here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RZ2oPjUqz9Cuh1S9FdDWG3


Generated by Claude Code

…fusal codes

Amended after merge for FIX-1863: a best-fit coordinator hears a filed task
end in its own turn, like a judgment one; round robin and everyone keep the
line. Leg e's signal names terminal_task_write_declined and
illegal_status_transition, as task-tools-capability.ts gives them.

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

vercel Bot commented Oct 11, 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 11, 2026 9:20pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 11, 2026 9:20pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 11, 2026 9:20pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 11, 2026

Copy link
Copy Markdown

FIX-1794

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass: no changes needed.

Claims checked against code on main:

  • coordinator-flow.ts:862-865: boardEntries returns "judgment" for routing === "judgment" || routing === "best-fit", else "fixed". Matches the new DOCS.md and PLAN S7 wording.
  • task-tools-capability.ts:
    • declinedWriteToolError uses terminal_task_write_declined for a terminal row. notParkedOnQuestion (answer) does too.
    • illegalTransitionToolError uses illegal_status_transition.
    • Together these cover assign, cancel, update and answer on one code, and complete, fail and block on the other, as the leg e signal says.
  • Grep of specs/issues/FIX-1794 and specs/epics/FIX-1786 finds no remaining "only judgment hears it" wording. The epic CONCEPT.md calls best fit a "fixed policy" at a different altitude (routing, not who hears an ending), so it stays as is.

Better approach? No. A spec-only amendment is the right size for a docs-versus-behavior drift. The change follows the existing "Amended after merge" convention and adds no new surface.

Refactor opportunity? None from this PR. It touches no code, so there is nothing to deepen. The one thing worth knowing is that the "judgment or best-fit → judgment, else fixed" mapping lives in a single inline closure, which is why the spec is easy to keep true. If more routing policies are added, a named predicate there would help. That is not worth doing now.

Nits (optional, none block):

  1. The leg e signal is now a long single table cell. Fine as is, but the two error-code lists would read better as a short sentence outside the table if this signal is edited again.
  2. DECISIONS says "now hears" and ties it to FIX-1863. The wording is correct, but a future reader may not know whether "now" means "since the original spec" or "since this amendment". "Since FIX-1863" would remove the ambiguity.

I have no blocking findings and would merge as is.


Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 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-11T21:19:42.445985Z 64f2198 Manual request
ℹ️ 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.

@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 / approach review

This PR is the right kind of change for this repo: implementation already landed (#3035, FIX-1863), and FIX-1794 is catching retained intent up to main. The routing split (judgment or best fit → coordinator turn; round robin / everyone → line) reuses FIX-1791’s four policies and matches published coordinators docs — not a new design surface.

Did the approach go too far?

Mostly no on the four-file touch — DOCS draft + PLAN S7 + SPEC signal + DECISIONS timeline is the same choreography as earlier FIX-1794 post-merge amendments (#2839, cross-spec, handoff).

A bit yes in two places:

  1. One DECISIONS bullet carries two unrelated deltas — FIX-1863 (task-end routing) and leg e’s refusal-code matrix. Those have different owners in the mental model (coordinator flow vs orchestration tool contract). Splitting the timeline entry (or one short EVOLUTION.md anchor with two rows) would read cleaner than a single paragraph that also inventories sibling files and source paths.
  2. Leg e’s expanded SPEC signal documents tool error literals the goal does not grade (goal.md only checks e:refiled / e:reply-names). That’s useful for implementers, but FIX-1817 BR-26 already owns the code split; repeating the full matrix in FIX-1794’s acceptance signal adds length without changing what “pass” means. A cross-ref (“finished-row writes per FIX-1817 BR-26”) would be a smaller, equally honest amendment.

Cleaner alternative (if you were doing it again)

Piece Leaner option
FIX-1863 routing PLAN S7 inline (*amended after merge*, FIX-1863) + DOCS Hearing sync (as here); DECISIONS one-liner + link to EVOLUTION or #3035, no coordinator-flow.ts / entry names in the decision log
Leg e codes SPEC one phrase + link to FIX-1817 BR-26; omit from DECISIONS entirely
Discoverability Optional: EVOLUTION.md subsection (parity with #amendment-handoff) — nice, not required for a one-sentence S7 change
BR tables Optional: BR-22/24 footnote that turn vs line follows session routing (FIX-1791) — reduces drift for readers who start from BUSINESS-RULES

Performance / reuse (spec scope)

No runtime change here. The behavior this documents does mean best-fit coordinators can spend a model turn per settled task (same as judgment); that’s intentional product cost, not a spec smell. S7 dedup language is unchanged — implementation risk is mis-branching (wake and line), not weaker idempotency.

Verdict

Approve. Direction and file choice are sound; remaining items are consistency and signal density, not wrong intent. Inline nits below — take or leave before merge.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1794/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1794/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1794/PLAN.md Resolved
Comment thread specs/issues/FIX-1794/SPEC.md Resolved

@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: 64f2198eb1

ℹ️ 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-1794/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1794/SPEC.md Resolved
Comment thread specs/issues/FIX-1794/SPEC.md Resolved
…817 BR-26

Judgment and best fit take a turn in addition to the line, not instead of it
(task-settled.ts). Leg e no longer lists refusal codes the goal doesn't grade;
FIX-1817 BR-26 owns them. DECISIONS splits the two amendments and drops code paths.

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

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RZ2oPjUqz9Cuh1S9FdDWG3
@jhoffner
jhoffner merged commit e304a6f into main Oct 12, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants