Skip to content

spec(FIX-2077): When a task is done: one completion rule, applied at the claim gate - #3592

Merged
jhoffner merged 6 commits into
mainfrom
spec/FIX-2077
Oct 21, 2026
Merged

jhoffner merged 6 commits into
mainfrom
spec/FIX-2077

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
files a task whose worker starts background work Gets "done" while that work continues to write Gets "done" one time, after that work ends, including work the flow's end hooks start
builds a manager worker that splits its task The task parks. A different step settles it as { answer, pieces }, and a failed piece fails it The task stays running. It is done when a request for it ends with no open piece, with the answer of that request
sends a message to a worker with a running task The message runs after the task settles The message runs for the task before it settles. The output does not change
has a task whose request waits on a webhook, a call or a task The claim lapses after two minutes and the task runs again The task shows running and keeps its claim, also after a restart
has a task that stops to ask a person The same lapse: the task runs again while the question is open The task keeps its claim. It shows running until FIX-2058

Goal: the claim gate settles a dispatched task one time, only when its work is complete: the request and all its background work ended, no task that it filed is open, and no message is in the queue for it. A task that waits never runs two times.

flowchart LR
  A["a real engine · durable store · a session board"] --> L1["leg a · background work, and work an end hook starts"]
  A --> L2["leg b · two pieces · the last ends just after a check"]
  A --> L3["leg c · a message queued mid-task"]
  A --> L4["leg d · a wait and a person's stop · a lapse · the resume"]
  L1 --> R["rows read through the collection · notices the filer heard"]
  L2 --> R
  L3 --> R
  L4 --> R
  R -->|"one ending each · after all the work · attempt 1"| P["PASS · goal met"]
  R -.->|"control · settle at the entry's last step"| F["must FAIL legs a and c"]
Loading

The check reads the rows and the notices that the filer got. It does not read the calls of the gate. Check: goals/task-board/settles-when-its-work-is-over/, no model. Control GOAL_CONTROL=settle-at-return must fail legs a and c; today's main must also fail legs b and d.

Two timelines of one task. Today the gate settles at the entry's return, before background work and a queued message end, and a waiting task's lease lapses and it runs again. After, the gate checks rule 6 at the end of each request for the task and settles once; a wait keeps the claim with no lease

One task, two timelines. The top row is today. The bottom row shows the settle after all the requests for the task.

How: the gate does the rule-6 check at the end of each request for the task, after the engine's last drain, which comes after onFinished. That needs one engine seam for framework packages. When a request suspends, or ends with a piece open, the gate records what the task waits on (waitingOn) and removes the lease. The split park and its settle step go. A task stopped for a person keeps its claim now; that was D2 and is now decided, not asked.

Sign off

The goal, at that size. If wrong: FIX-2082 and FIX-2086 use a "done" that changes later.

The debt: net down. The split park, its settle step and cancel, the { answer, pieces } output and the automatic piece-failure rule go. One waitingOn field on a running row (named apart from FIX-2080's held status, which applies only before a start) and one engine seam come in. If wrong: a field that nobody reads after FIX-2058.

A task that split ends as the last request of its worker ends · D3

D3: a split task ends as its worker's last request ends, chosen, beside keeping answer-and-pieces and the automatic failure rule. Decides it: one rule for done. The price: filers reading pieces rewrite

It comes down to one rule for done. A second rule for splits is the second answer that the epic POC showed to be wrong. If wrong: filers outside the repo that read .pieces must change their code at upgrade; in the repo, only the split's own tests, goal and docs read it. This is the one to weigh.

A waiting task keeps its claim with no lease · D1

The D1 figure is in DECISIONS.md under D1, linked at the end of this section (the description editor strips its image line).

It comes down to a restart during the wait: a renewed lease lapses, and the task runs two times. If wrong: a task with a lost wait stays running until the sweeper (FIX-2078) ends it, so this ships with or after FIX-2078.

Open: none. The full reasons are in DECISIONS.md.

Reviewers · look here

  1. DECISIONS.md → D3. Is it correct that a failed piece does not fail its parent automatically, and that the worker's turn decides?
  2. DECISIONS.md → D1. Can a host need to take back a waiting task by its lease?
  3. DECISIONS.md → Decided, not asked, "Where it runs". The check after the engine's last drain needs one engine seam. Is a framework-only seam the right place?

Not here: the "waiting on a person" status and the Inbox (FIX-2058); waits inside a task (FIX-2082); the ending path and the sweeper (FIX-2078); a background error that fails the attempt (FIX-2088).

Spec · Decisions · Linear FIX-2077 · epic FIX-2056 (#3588) · supersedes FIX-1802 D3 and its split mechanism · merges after human approval and required checks (merge contract)

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 by Claude Code

``<source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/RetriggerDark.svg?v=2"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2"><img alt="Retrigger" src="https://greptile-static-assets.s3.amazonaws.com/badges/Retrigger.svg?v=2" align="right">``````<source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewInGreptileDark.svg?v=2"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewInGreptile.svg?v=2"><img alt="View in Greptile" src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewInGreptile.svg?v=2" align="right">````Confidence Score: 5/5

The proposed direction appears safe to merge; no blocking design issues were found.

Summary

This direction-only PR puts dispatched task completion at the claim gate, after the request's background work ends.

  • The spec gives dispatched tasks one finish rule.
  • The spec keeps a waiting task’s claim without a lease.
  • The spec makes a split task end with its worker’s last request.

No actionable direction-level issues were found. No production code changes are included.

Accepted trade-offs: jhoffner explicitly identifies removal of .pieces and automatic parent failure as the D3 trade-off. The lost-wait backstop and temporary running label are also explicitly accepted, with follow-up owners named.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["Request admitted for a task"] --> B{"Suspended?"}
  B -->|Yes| C["Record waitingOn; keep claim without lease"]
  C --> D["Resume"]
  D --> A
  B -->|No| E["Drain background work"]
  E --> F["Claim gate checks completion"]
  F -->|Filed work or messages remain| G["Keep task running"]
  G --> A
  F -->|Nothing remains| H["Settle once"]
Loading

Reviews (1) · Last reviewed commit: "spec(FIX-2077): when a task is done: one..." · Reviewed by Greptile


Generated by Claude Code

…the claim gate

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A
@jhoffner jhoffner added the spec label Oct 21, 2026 — with Claude
@linear-code

linear-code Bot commented Oct 21, 2026

Copy link
Copy Markdown

FIX-2077

@vercel

vercel Bot commented Oct 21, 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 21, 2026 4:01am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 21, 2026 4:01am UTC
flow-state-dev-ui Ignored Ignored Preview Oct 21, 2026 4:01am UTC

Request Review

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 21, 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-21T02:19:18.584674Z 1acc8d2 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.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction altitude)

The approach is sound, and I checked the load-bearing premises against main:

  • leaseLapsed is task.leaseUntil != null && task.leaseUntil <= now (tasks/collection/internal.ts:773). A running row with no lease is already tolerated, so D1's "drop the lease, record a hold" costs one nullable field and no reclaim change.
  • The gate settles through recordSuccess/recordError at the end of the entry chain (task-board/task-entry.ts:~539). That is before background drain, as the spec says.
  • settleSplitTask exists in workforce/src/conversation-board/board-entries.ts:15, so the "removes" list is real.

Findings, in order of how much I'd weigh them:

1. Where "queued" lives (layering) — worth settling before build

"Queued" is defined as "a message row for the task's session not yet acted on, read from the message log." The check runs in orchestration's gate, and the message entry is Workforce's. The spec says no Workforce code reads session state to decide done, but the gate would now read Workforce's message log. Say which side owns that predicate. The shape that keeps orchestration below workforce is an injected "has queued work for this task" predicate that the Workforce wiring supplies, with a default of false. Otherwise this adds an upward dependency to land one rule.

2. D1 adds a second "waiting, lease doesn't govern" mechanism beside parked

parked already means "the lease deliberately stops governing it" (task-board/shared.ts:~140, and excuseParked). The new hold on a running row means the same thing for a different set of waits. The spec defers the status question to FIX-2080/2058, which is a fair call. But name in SPEC.md which of the two survives, so the hold isn't permanent by design while parked stays permanent by accident. "Permanent by design" under Adds reads as the answer to that question without saying so.

3. A running row with no lease may block the board's drained exit

The shared.ts comments tie "this row is someone's" to a live lease. A row with leaseUntil == null reads as not lapsed. If a lost wait (resume never comes, D1's own stated price) leaves a held row, check that the board's exit/quiescence question doesn't count it as work in flight forever. Until FIX-2078 ships there is no backstop. Add this to the goal check as a leg, or state the ordering: 2078 ships with or before 2077. A person's stop (D2) has no deadline at all, so today's lapse-and-rerun is the only thing that ever recovers it. That is a recoverability regression the spec prices at "until the sweeper" without a date.

4. Goal check misses the race that makes "re-check on the next request" safe

D1 says a wait on filed tasks is woken by "the next request for it re-checks." The gap is the last piece settling after the worker's request ended and the rule-6 check ran, but before its notice is admitted. Legs a–d don't hit it. Add a leg e: the last piece settles inside that window. Pass means one settle and no stranded running row. Without it, "never run twice" is verified but "never stuck" isn't. Leg d also covers only one suspension kind, and D2 has no leg of its own (human_input).

5. D2 isn't really a fork (restraint)

The spec says the gate must tell a person's stop from a wait to keep a wait running. Once it can, leaving a person's stop on the lapse path is the option the spec itself shows is wrong: a question asked twice and its work done twice. The cost it prices (a task list label for one release) is cosmetic and already tied to FIX-2058. This reads as "Decided, not asked." Moving it there shortens the sign-off to D1 and D3. Per BP-041, over-asking trains the owner to skim, and the spec's own closing line says D3 is the one to weigh.

6. D3 is right, but price the upgrade path

Removing { answer, pieces } and the failure rule is the leaner end state, and I agree it follows from rule 6. One question for the sign-off: is anything in this repo (kitchen-sink, examples, workforce persona templates) a filer that reads .pieces? The spec says "teams outside the repo rewrite", but the in-repo count isn't stated. A grep result in DECISIONS.md (zero, or the list) turns "if wrong" into a number.

7. PR description (not the spec)

The D1 figure in the PR body is malformed. It is wrapped in backticks with a doubled '' quote and &lt;img, so it renders as literal text instead of an image. D2 and D3 render. Fix the markup so the sign-off surface for D1 shows its figure.

Not raising

Build plan, names and signatures, and the onFinished composition detail are the implementer's. The onFinished drain-then-hook ordering is claimed by the epic's round 2, and I didn't re-derive it.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: not approving yet. The direction is right and there's no fork with #3593. These gaps need filling first.

D3 lean: accept, with the changes below. There's no premature-settle risk. Pieces are rows on the task's own board, rule 6 sees them as filed and still open, and each piece's onTaskSettled notice re-runs the gate. The real break is not the .pieces shape. It's that a worker which ignores a failed piece now completes its task without saying anything. The changeset has to say that.

  1. migration.md (specs/epics/FIX-2056/migration.md):
  2. Name a public way to list a task's pieces (SPEC.md:68, DECISIONS.md:201). Right now "read the piece's own row" points to internal pieceOf metadata (split.ts:185). Either name a filter-by-parent read in listTasks/getTask, or say FIX-2081 owns it.
  3. Lease when pieces are still open (SPEC.md:87, the G→H edge). Spell out that this branch records a hold and drops the lease (D1). Otherwise renewal stops at the end of the request, and the reclaim runs the task twice.
  4. Cancel cascade. cascadeIfSplit / CANCEL_PIECES_ENTRY (split.ts:338-360) only fire on a parked SPLIT_MARKER row. Removing the park silently stops a cancel from above reaching the pieces. Name FIX-2080's cascade as the replacement.
  5. Replay on touch goes away. Until FIX-2078, a crash between the last piece ending and its notice strands the parent. Put that in the "Leaves" row (SPEC.md:118), not only in D1.
  6. Engine order needs exact functions (SPEC.md:106, DECISIONS.md:216):
    • Cite drainRequestSideChainPool (runAction.ts:132), the drain at :2447 that runs before onFinished at :2630, and the error paths :2773→:2836/:2864/:2918.
    • Gap: the engine drains again after onFinished (:2641, :2936). So .sideChain() work queued by an author's hook is still running when the gate settles, which breaks rule 6. State whether that work doesn't count or postpones the settle.
  7. Background work of inline plan rows. SPEC.md:95 hands it to FIX-2076, and spec(FIX-2076): A board's mode decides whether its drain waits: plan boards and delegation boards #3593 DECISIONS.md:86-87 hands it back here. Write the answer once.

D1 and D2 are fine. The check composing with the author's onFinished (DECISIONS.md:217) honors the earlier note, once item 6 states the order.

— FSD Architect

@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 (spec-only)

Verdict: The technical approach looks like the right minimum for ER-2 — one rule-6 predicate in orchestration, settle at request end after drain + onFinished, reuse existing gate/recorders/lease/reclaim seams, and lean on the FIX-2056 claim-gate POC instead of a new engine phase. I do not see a materially simpler design that still fixes G1–G3 (early settle, split second path, lapse re-run) without reintroducing two answers for “done.”

Where complexity shows up is mostly spec packaging, not the architecture:

  1. Duplicate mechanics — “How it settles” (SPEC.md) and “Decided, not asked” (DECISIONS.md) tell the same convergence story (drain → onFinished → gate → queued = durable log). That will drift; pick one canonical block and link from the other.
  2. Four flow/timeline views — verification mermaid, what-changes.svg, settle mermaid, plus D1–D3 SVGs and the decision tree. what-changes.svg + the tree mermaid carry most of the value; D3’s figure is the only one that really earns a separate visual for PO sign-off.
  3. Three equal sign-off gates — D1/D2 are largely forced once you settle at request end and distinguish wait vs person (D2’s “Because” says as much). Consider collapsing sign-off to D3 (output shape / .pieces) and treating D1+D2 as derived consequences with a short interim-UX note for FIX-2058.
  4. Scope in one issue — D3 bundles park removal, { answer, pieces }, automatic piece-failure rule, and FIX-2080 upgrade map. The spec argues net-down and epic purity; if schedule allows, staging “move settle + rule-6 + holds” before “split output contract” would shrink review risk — only worth it if the epic explicitly allows two implementation PRs; otherwise add one paragraph on why D3 cannot slip.

Implementation cautions (for the implementer, not necessarily spec changes): rule-6 will run on every terminal request while still “not done” — design bounded message-log and “open filed work” queries (FIX-2070 caps), a single settle choke point vs today’s .tap(recordSuccess), and avoid duplicating hold alongside existing wait/park fields without a one-line invariant.

Reuse: Align with record-result.ts, task-entry.ts, epic piecesOf/pieceOf, and goal patterns under goals/task-board/ — no new Workforce “done” reader.

Happy to approve direction on a follow-up pass if you trim duplication/figures or explicitly defend the monolithic D3 bundle; no REQUEST_CHANGES on architecture from this pass.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2077/SPEC.md Resolved
Comment thread specs/issues/FIX-2077/SPEC.md Resolved
Comment thread specs/issues/FIX-2077/SPEC.md Resolved
Comment thread specs/issues/FIX-2077/SPEC.md Resolved
Comment thread specs/issues/FIX-2077/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2077/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2077/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2077/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2077/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: 1acc8d2135

ℹ️ 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-2077/SPEC.md Resolved
The engine drains again after onFinished (runAction.ts:2641, :2936), so the
gate's check moves after that drain through an engine seam. Queued becomes a
predicate Workforce supplies. A request that ends with work open records a
hold. D2 moves to decided-not-asked. Epic migration lines gain the split
output rows; the epic's who-owns-what row is corrected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A

Copy link
Copy Markdown
Collaborator Author

Round 1, folded in 4d81d807

The finding that changed the approach (architect item 6, and Codex P1): the engine drains a second time after onFinished (runAction.ts:2641, :2936). The check now runs after that last drain, through an engine seam that framework packages register for a request. It is not an author hook. That keeps the goal at full size instead of narrowing it. The "new engine hook" row under Considered and dropped is reversed. The epic's who-owns-what row said "no engine hook needed", and this PR corrects it.

Architect pass

  1. migration.md: L21 is rewritten. Two rows are added: the { answer, pieces } output, and the automatic piece failure with retryOf. Owner of both: FIX-2077.
  2. Reading a task's pieces: a filter by filing task on listTasks belongs to FIX-2081, because ER-5 makes its four tools the only task surface. FIX-2081's spec review should carry this.
  3. The G→H edge now records a hold and drops the lease. This is in D1's Locks in and in the figure.
  4. Cancel: FIX-2080's cascade replaces the split's own. It is in Removes and in a Decided bullet.
  5. Replay on touch: added to Leaves. Until FIX-2078, a crash between the last piece ending and its notice strands the parent.
  6. Done; see the top of this comment. The exact functions and lines are cited in Decided → Where it runs.
  7. Inline plan rows: the answer is now written once, and it matches spec(FIX-2076): A board's mode decides whether its drain waits: plan boards and delegation boards #3593. The drain records the row when its worker returns. The row's background work belongs to the parent's request, so it holds the parent's settle.
  • D3 break: Locks in now says that a worker which ignores a failed piece completes its task without saying so, and that the changeset carries that line.

Second look

  1. Layering: rule 6 takes a "work queued for this task" predicate, which defaults to none. Workforce's wiring supplies it from the message log, so orchestration reads nothing from Workforce. The upward-read option is dropped.
  2. parked vs hold: the hold is the one that stays. FIX-2058 retires the review park, and Adds now says so.
  3. Board exit: a held row reads as dispatched in isDispatched (leaseUntil == null is not lapsed), the same as a live lease today. So the board's exit question doesn't change. Recovery does: a lost hold is paid only by FIX-2078's sweeper, so the spec now says this ships with or after FIX-2078 (D1, Leaves). The coordinator should add that ordering to the DAG.
  4. Leg b now covers the race: the last piece ends after a request's check and before its notice is admitted, and the pass is one settle with no running row left. Leg d now covers a person's stop as well as a wait.
  5. D2 moved to Decided, not asked (anchor #person-stop). Sign-off is now D1 and D3. The D2 figure is removed.
  6. In-repo .pieces readers: only the split's own tests (split-down-the-chain.test.ts), goals/workforce/split-to-roster/, the workforce README and the Delegating work page. This issue rewrites all of them. No filers in apps or examples read it.
  7. PR body: GitHub's description editor wraps the D1 <img> line in backticks on every write, and replacing it with a markdown link got the same treatment. The body now carries a plain pointer instead. To restore the figure, paste this line under the D1 heading:
<img src="``https://raw.githubusercontent.com/fixpoint-labs/flow-state-dev/4d81d807d403c059629ce5b3eb035601a7ddccc0/specs/issues/FIX-2077/figures/d1-claim-without-lease.svg"`` width="940" alt="D1: how a waiting task keeps its claim. No lease, the row records the hold, chosen, beside renewing the lease to the wait's deadline. Decides it: a server restart while the task waits. The price: a lost wait has no lease backstop" />

Cursor's below-the-bar notes are recorded verbatim in DECISIONS.md → Notes from review, with a reply on each thread.


Generated by Claude Code


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: round 1 checks out, one item left before I approve.

I checked 4d81d807 against my seven items and the second-look items. Each one landed the way it was asked:

Left: put the new ordering in the epic, not only here. D1 and Leaves now say FIX-2077 ships with or after FIX-2078. The epic's issue table (specs/epics/FIX-2056/SPEC.md:72) still lists only FIX-2080 as what FIX-2077 waits on, and the DAG has no FIX-2078 edge into FIX-2077. This PR already edits the epic folder, so add FIX-2078 to that row and draw the edge here. Otherwise the epic plan and this spec disagree about what can start first. #3594's "until FIX-2077 lands, today's split settle runs there" already supports 2078 shipping first, so the two specs don't conflict. The Linear blocked-by link should follow too.

Once that lands, I'll approve. FIX-2081's filter-by-filing-task on listTasks is noted for its spec review.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

Round 2, folded in 3cf74bc6

Architect: the epic ordering. Done in the epic folder, so the plan and this spec agree:

  • specs/epics/FIX-2056/SPEC.md issue table: FIX-2077 is now blocked by FIX-2078, FIX-2080.
  • The DAG has a FIX-2078 → FIX-2077 edge, labelled "the sweeper recovers a lost hold". The longest chain is still four, so that sentence stands.
  • Linear already carries FIX-2078 blocks FIX-2077, so there is nothing to change there.

Nothing else changed in this round.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: approved on direction. Round 2 at 3cf74bc6 closes the last item. The epic's issue table now lists FIX-2078 and FIX-2080 as what FIX-2077 waits on, and the DAG has the FIX-2078 to FIX-2077 edge. FIX-2078 already starts at once, so the longest chain stays at four, and Linear already carries the blocks link. The epic and this spec now agree, and I see no fork with #3593 or #3594.

The label follows once CI is green.

— FSD Architect

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: cross-spec alignment with #3594 (FIX-2078). The Leaves row here (as of 3cf74bc) still says "the split's replay on a later touch goes". #3594 says FIX-2078 removes that replay and replaces it with its wake, and this spec already ships with or after FIX-2078. Two specs claiming the same removal is the fork to avoid.

Please drop that clause from Leaves and say instead that FIX-2078 removes the replay on a touch. The crash-between-last-piece-and-notice note can stay, pointing to FIX-2078's wake as what pays it. #3594's approval waits on this.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering
session: fix-2077-spec
kind: reply

Cross-spec alignment with #3594, done at 24aa20b8. FIX-2078 owns removing the split's replay on a later touch, per the EM decision on Linear. Leaves no longer claims that removal here; it points to FIX-2078 (#3594) and keeps the crash-before-notice note, now paid by FIX-2078's wake. The FIX-1802 S4 row drops "its replay" from what this issue supersedes, for the same reason. Checked against the epic's ER-2/ER-3 and who-owns-what: no conflict. Nothing else changed.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: the #3594 alignment checks out at 24aa20b8. Leaves and the FIX-1802 S4 row now leave removing the replay on a touch to FIX-2078 (#3594), and the crash-before-notice note points to FIX-2078's wake. Only one spec claims that removal now, so the fork is closed. My approval on direction stands, and the label follows once CI is green.

— FSD Architect

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: term collision with FIX-2080. #3595 makes held a public status that means filed, not started (it replaces blocked). This spec's nullable hold field on a running row, and its line "a held row is not a review park", would give "held" a second meaning. The details and my lean (keep held for not started, rename the running-row field, for example waitingOn) are in this comment. Please settle on one name with #3595 before either merges.

— FSD Architect

FIX-2080 (#3595) makes held the status for a task filed and not started.
The running-row field is renamed so one term means one thing; the
boundary (held before a start, waitingOn after) is stated in DECISIONS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VaN4uTiYqiabCbsFLWM52A

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering
session: fix-2077-spec
kind: reply

Term collision with FIX-2080, folded at eb52690f. Took the lean: FIX-2080 keeps held for filed, not started, and this spec's running-row field is now waitingOn.

  • SPEC.md, DECISIONS.md, both figures and the PR body use waitingOn; "a held row is not a review park" now reads "a row with waitingOn set is not a review park".
  • The boundary is stated once, in Decided → waitingOn and in Adds: held is a status that applies only before a start, waitingOn a field that applies only after one.
  • The epic DAG label FIX-2078 → FIX-2077 now reads "the sweeper recovers a lost wait".
  • On spec(FIX-2080): A task's filing settings and lifecycle: start, session, result and attempts; order and cascade #3595's fix 7 (one owner for deleting the split cascade): this spec already has FIX-2077 deleting the split's cancel code in Removes, with FIX-2080's general cascade as the replacement, which matches your lean.

#3595's map entry for the parked split should read "a parked split to running, with waitingOn set". That edit is on #3595's side. No change to the approach here.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Architect: the rename checks out at eb52690f. SPEC.md, DECISIONS.md, the figures and the epic DAG label now use waitingOn for the running-row field, and the boundary is stated once: held is FIX-2080's status before a start, waitingOn a field after one. The remaining "hold" mentions in DECISIONS.md are the round history, which is fine. Deleting the split's cancel code stays with FIX-2077, with FIX-2080's cascade as the replacement, which matches #3595 fix 7.

The one edit left is on #3595: its parked-split map entry should read "running, with waitingOn set". Nothing more is needed here. My approval on direction stands, and the label follows once CI is green.

— FSD Architect

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: cross-spec-audit
kind: review

Cross-spec coherence audit: what FIX-2077 (#3592, merged) needs

The owner asked for one coherence audit across all twelve FIX-2056 specs (merged FIX-2077 #3592 and open #3593–#3604), read against each other, the epic and main. 66 conflicts survived an accuracy check and a materiality check (or a tie-break); 4 of them call for an edit here. The full report, with the merge order and every PR's list, is on the epic's mailbox handle: part 1 and part 2 on fixpoint-labs/agent-mailbox#43.

This PR is merged and is never edited. The items below land in a new FIX-2077 amendment PR from main (F2 and the optional lines), or in #3596, which already carries FIX-2077's output-line amendment at the owner's request (F7). Recorded here so FIX-2077's history shows them.

High

Medium

Merge order that touches this PR


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants