Skip to content

spec(FIX-1629): amend BR-25 and C1 — the displaced worker's settlement declines terminal - #2355

Merged
jhoffner merged 3 commits into
mainfrom
claude/fix-1629-spec-amend-br25
Sep 29, 2026
Merged

jhoffner merged 3 commits into
mainfrom
claude/fix-1629-spec-amend-br25

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

This amends the merged FIX-1629 spec, following orchestration.md "Merging and amending a spec". The implementation is #2347.

What changes

BR-25, PLAN C1 and the matching DECISIONS bullet said that when a row action settles a task a worker is still running, the worker's own result is later refused as lost-claim. That is not the whole story. The task substrate gives a reason that depends on what the action did to the row:

  • terminal when the action finished the row (complete, cancel, or a fail with no retries left). The substrate checks whether the row is settled before it checks the claim, and that order is deliberate.
  • lost-claim when a failTask with retries left returned the row to pending.

BR-25 now names only completeTask, failTask and cancelTask. A blockTask on a held row is an illegal move, so it belongs to BR-18, and C1 cites it there.

Scope

This corrects a fact; it does not change direction. The behaviour is the same: the action lands, and the worker's result is refused and dropped.

Evidence

Both tests are in packages/orchestration/test/task-board/task-tool-actions.test.ts on #2347:

  • completeTask_x on a held row, followed by the worker's settlement, produces exactly { outcome: "declined", reason: "terminal", status: "completed" }.
  • blockTask_x on a held row is refused as illegal_status_transition.

The soft-fail route (failTask back to pending while retries remain) is in task-tools-capability.ts, where it goes through shouldRetryOnFail.

🤖 Generated with Claude Code

https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N

…t declines terminal

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

vercel Bot commented Sep 29, 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 Sep 29, 2026 12:43am UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 29, 2026 12:43am UTC
flow-state-dev-ui Ignored Ignored Preview Sep 29, 2026 12:43am UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 29, 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-09-29T00:49:12.784566Z 30cbd42 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.

@linear-code

linear-code Bot commented Sep 29, 2026

Copy link
Copy Markdown

FIX-1629

Copy link
Copy Markdown
Collaborator Author

Second-look / architecture review

Spec-only, 3-line amendment. The core correction holds up against the code: transitionDeclineReason (packages/orchestration/src/tasks/collection/internal.ts) checks terminal before lost-claim, and blocked is reachable only from pending, so blockTask on a held row is an illegal transition. No better approach and no refactor opportunity here. It's a doc-accuracy fix.

One thing to fix before this merges: the "today the reason is terminal" claim (BR-25, C1) is wider than the code supports.

  • terminal only fires when the action leaves the row in a terminal status.
  • failTask on a row with retries left re-queues it to pending. It is not terminal, and the worker's later result would then fail the attempt/ownership arm, giving lost-claim.
  • cancelTask and completeTask finish the row, so terminal is right for those two.
  • The BR-25 sentence already says "terminal when the action finished the row, lost-claim otherwise", which is correct. The trailing "so today the reason is terminal" contradicts it for the retry case.
  • Suggest either scoping it ("for completeTask/cancelTask, and failTask with no retries left") or dropping the closing clause.
  • C1 only asserts the completeTask_x case, so the test is fine. Only the prose over-claims (BR-25 and the DECISIONS line).

Nit: DECISIONS.md line 77 now runs well past the wrap width of the surrounding bullet. Re-wrap it.


Generated by Claude Code

@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

Verdict: The direction is right and I’m approving. The old text was wrong: when a coordinator-style action finishes a held row, the worker’s late fenced settlement declines with reason terminal, not lost-claim — that matches transitionDeclineReason / advisory-write behavior in orchestration today. PLAN C1 and DECISIONS are the right places to pin the held-row proof and the “action overrides claim” intent.

Where this went a bit far: BR-25’s Then cell is doing three jobs at once — correct terminal vs lost-claim split, a blockTask legality aside, and a “so today the reason is terminal” implementer note. That makes the WHEN row (blockTask listed among verbs that “run” on a held row) fight the THEN footnote. A cleaner spec change (same behavior, less table prose) would be:

  1. Narrow BR-25 WHEN to completeTask, failTask, or cancelTask on a row a live worker holds (drop blockTask; illegal moves stay BR-18 only — C1 already tests blockTask_x as illegal transition).
  2. Shorten BR-25 THEN to: action runs unguarded (no claim); worker’s later claim-fenced settlement is declined and dropped with reason per existing task-substrate precedence (terminal if the row is already terminal; else lost-claim when the ticket no longer owns the attempt). Avoid re-defining reasons in the epic table — point at published substrate docs / transitionDeclineReason instead of “today …”.
  3. Keep the two-reason split in DECISIONS (and optional PLAN note); if CI only exercises completeTask_x → terminal, that’s fine — mention soft failTask → worker lost-claim in C1 only if you want CI to prove the “otherwise” branch.

Skipped (not worth blocking): collapsing duplicate DECISIONS + BR-25 prose; adding a second C1 case for soft-fail lost-claim; terminology pass on “declines terminal” vs “declined/ok:false”.

Performance / reuse: N/A for this markdown-only diff; substrate already owns the vocabulary — reuse it rather than growing BR-25.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1629/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1629/PLAN.md Resolved
Comment thread specs/issues/FIX-1629/DECISIONS.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: 1e71a47797

ℹ️ 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-1629/BUSINESS-RULES.md Resolved
…es lost-claim

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N
…ains the retryable failTask leg

After a retrying failTask re-queues a held row, the displaced worker's
completion declines `disallowed` and its failure `lost-claim`, neither
writing (task-tool-actions.test.ts on #2347).

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

Copy link
Copy Markdown
Collaborator Author

@codex review


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 30cbd42315

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

@jhoffner
jhoffner merged commit 466143f into main Sep 29, 2026
12 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