Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 26 additions & 12 deletions specs/epics/FIX-2056/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ flowchart TD
| **Locks in** | FIX-2058 and FIX-2070 wait for FIX-2086 too |
| **FIX-2086 does not, until FIX-2058** | Answer a question a task stopped on with a steer · retire `answerTask` or the parks · mark a task waiting on a person ([D2](#d2)) |

**Confirmed by the owner** (2026-10-21, [(b)](#b)): FIX-2086 lands in this epic.

**What would change my mind:** FIX-2058 or FIX-2070 finding it can start without FIX-2086. Then
FIX-2086 leaves the set and those epics start one issue earlier.

Expand Down Expand Up @@ -78,7 +80,7 @@ FIX-2081's own scope.
|---|---|---|---|
| ER-1 | Only the claim gate (a dispatched row) or the drain (an inline row) records a row's ending. No tool, worker block, wait or Workforce path does (rule 18) | FIX-2076 | Every spec review; the closure sweep |
| ER-2 | One predicate for done (rule 6), in orchestration, checked after the request's background work and when a task it filed ends. Every wait, a plan board's drain included, wakes on the ending the gate writes; a deadline writes none. No Workforce code re-derives a request's kind from session state | FIX-2077 | FIX-2078's, FIX-2082's, FIX-2083's and FIX-2086's spec review |
| ER-3 | Every ending of a delegated task reaches its filer once, through one path, and every debt has a due time with the sweeper as backstop | FIX-2078 | FIX-2083's and FIX-2085's spec review; legs b and c |
| ER-3 | Every ending of a delegated task reaches its filer once, through one path, and every debt has a due time with the sweeper as backstop. Shift Manager's error report rides that path, not a second one ([f](#f)) | FIX-2078 | FIX-2083's and FIX-2085's spec review; legs b and c |
| ER-4 | Four filing settings. Start and attempts editable until a task starts; session and result never change | FIX-2080 | FIX-2081's, FIX-2083's and FIX-2086's spec review |
| ER-5 | The four task tools are the only task surface, for models and screens, with identity from the server (BP-031) | FIX-2081 | Every later spec review; the closure sweep |
| ER-6 | A retired row shape is read through FIX-2080's one map, never a child's own ([D3](#d3)) | FIX-2080 | FIX-2077's, FIX-2083's and FIX-2086's spec review |
Expand All @@ -91,7 +93,7 @@ FIX-2081's own scope.
| The claim gate (`task-board/task-entry.ts`, `blocks/record-result.ts`) and the request's end | FIX-2077 owns the predicate and where it runs: the request's `onFinished`, run after background work drains on every terminal path (`engine/src/execution/runAction.ts:2447`→`:2630`, `:2773`→`:2918`). No engine hook needed. FIX-2082's waits wake on its ending; FIX-2078 calls it when a filed task ends |
| The wait (`tasks/helpers/wait-for-response.ts`) and its limits | FIX-2082 owns it and its limits: 5 waits deep; a tree 5 deep, 100 under its top task. FIX-2076 only sets which boards wait. A board's dispatch rides the row's wait. A bare `dispatcher({ wait: true })` has no row, and the engine awaits acceptance only (`core/src/blocks/dispatcher.ts:169-171`, `engine/src/context/dispatch-operation.ts:273-280`): FIX-2082 adds an engine wait that returns the result |
| The sweeper (`engine/src/durability/durability-sweeper.ts:40-50`), re-armed only from wait gates | FIX-2078 adds a due-time source the re-arm reads and a step that pays board debts |
| `afterRun`, the notice and `runTaskBoard` (`workforce/src/conversation-board/board.ts`) | FIX-2078 moves the notice, replaces resends with due times and removes the automatic error routes ([f](#open)); FIX-2077 removes the split settle; FIX-2084 renames the entry `dispatch` |
| `afterRun`, the notice and `runTaskBoard` (`workforce/src/conversation-board/board.ts`) | FIX-2078 moves the notice, replaces resends with due times, removes the `reportOwed` marker and keeps Shift Manager's error route on the ending path ([f](#f)); FIX-2077 removes the split settle; FIX-2084 renames the entry `dispatch` |
| The collection read (`tasks/collection/`) | FIX-2080 owns the map; the retiring children turn entries on |
| Queued messages | FIX-2077 runs them through today's message entry; FIX-2070 makes it `receive` |

Expand All @@ -111,6 +113,24 @@ FIX-2081's own scope.
- **Round 2 (architect):** FIX-2062 (#3538) is built on: every resume waits its session's turn.
FIX-1637, the keep-alive docs epic, is related: its guide picks up FIX-2085's schedules and
FIX-2082's waits.
- <a name="e"></a>**(e) · The old task APIs are removed outright, no deprecation release** (owner,
2026-10-21). Every surface in [`migration.md`](migration.md) goes in the owning child's PR, in a

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Exclude the pending error route from blanket removal

When FIX-2078 follows this retained spec, “Every surface in migration.md goes” also directs it to remove errorCapture, even though migration.md:22 and DECISIONS.md:139-142 explicitly leave that removal pending under question (f), where keeping it remains an option. Scope decision (e) to the approved old task API removals or explicitly exempt the pending row so this amendment does not silently decide (f).

AGENTS.md reference: AGENTS.md:L52-L52

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

from: epic-agent
session: FIX-2056
kind: reply

Resolved in d95ab2d by the owner's answer to (f): the error route is kept, so the errorCapture row leaves migration.md and (e)'s blanket removal no longer reaches it. FIX-2078 re-expresses it on the ending path (DECISIONS.md#f).


Generated by Claude Code

minor bump (pre-1.0). That child's changeset carries the removal's one line from `migration.md`.
Comment on lines +117 to +118

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.

P2 Removal instructions conflict

DECISIONS.md now requires removing every surface in migration.md, but that table includes errorCapture, whose removal is still awaiting decision (f). The new opening in migration.md repeats this instruction. Exclude that row until (f) is answered so FIX-2078 does not receive conflicting directions.

Fix in Cursor

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

from: epic-agent
session: FIX-2056
kind: reply

Resolved in d95ab2d by the owner's answer to (f): the error route is kept, so the errorCapture row leaves migration.md and (e)'s blanket removal no longer reaches it. FIX-2078 re-expresses it on the ending path (DECISIONS.md#f).


Generated by Claude Code

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 (optional): This bullet carries a lot of mechanics (minor bump, changeset ↔ row, no wrapper, closure sweep, D2 carve-out) that largely duplicate migration.md’s intro. Consider trimming to the owner decision + link to migration.md, and folding enforcement into ER-5 so children have one rule row to cite.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

from: epic-agent
session: FIX-2056
kind: reply

Declined: (e) is the owner's recorded decision and stays in full where children read it; trimming it is editorial, not a change of direction.


Generated by Claude Code

No child ships a deprecated alias, wrapper or warning, and the closure's tool sweep allows none:
the only task tool besides the four is `answerTask` ([D2](#d2)). The cost, accepted: teams
outside the repo calling them rewrite at upgrade.
- <a name="f"></a>**(f) · Shift Manager's automatic error route is kept** (owner, 2026-10-21).
FIX-2078 owns it: `errorCapture` into the Error Reporter
(`packages/shift-manager/teams/devteam/host.mts:1194`) is preserved, re-expressed on the new
ending and notice path, not removed. Hosts wiring `errorCapture` keep getting error reports and
get no migration line. The `reportOwed` marker and its resends still go (ER-3). The gaps row
*a failure is an ending delivered to the filer* is met by the filer hearing it once; its
"Error Reporter hears only what a filer messages" half does not gate the closure.
- <a name="a"></a>**(a) · One epic, not two** (owner, 2026-10-21). Board modes (FIX-2076) and the
waited dispatch (FIX-2082) stay in this set: the claim-gate POC showed FIX-2076, FIX-2077 and
FIX-2082 must share one answer for done.
- <a name="b"></a>**(b) · D1 kept** (owner, 2026-10-21): steer and follow-ups, phase 3 and
FIX-2086, land in this epic ([D1](#d1)).

## What the end-state POC showed

Expand All @@ -125,16 +145,10 @@ FIX-2081's own scope.
- **Round 1** — FIX-2079 merged into FIX-2078; D3 became one map in FIX-2080.
- **POC** — the waited dispatch moved to FIX-2082.
- **Round 2** — sources agree with D2; engine prerequisites named; (e), (f) opened.
- **Amendment** — the owner answered (e): remove outright, no deprecation release; then (f): keep
the error route; (a): one epic; (b): D1 kept.

<a name="open"></a>
## Open · pending the owner's answer

**(e) · Old task APIs: warn for a release, then remove, or remove now?** Teams outside the repo
calling them break at upgrade. Warning keeps both shapes a release, which the closure's tool sweep
must allow; removing now makes them rewrite at once. Replacements and owners:
[`migration.md`](migration.md). **Pending.**
## Open

**(f) · Shift Manager's automatic error route: drop it, or keep it?** Every failed request reaches
the Error Reporter today (`errorCapture`, `packages/shift-manager/teams/devteam/host.mts:1194`).
Dropped, it hears only what a filer sends, and hosts wiring `errorCapture` get a migration line;
kept, failures arrive twice, an exception to ER-3. FIX-2078 owns it. **Pending.**
None. Every question the epic asked is answered above.
11 changes: 8 additions & 3 deletions specs/epics/FIX-2056/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The scope is every phase 1 and phase 3 row of
| Is it the right goal? | |
|---|---|
| **Smaller, and rejected** | Posts become tasks alone: FIX-2058 would build on a gate that lets a waiting task run twice |
| **Not done if** | An ending is recorded outside the gate or the drain · a fifth task tool is exported, `answerTask` aside ([D2](DECISIONS.md#d2)) · a row misses its target · a coordinator or hand-off goal regresses · a closure bug is open |
| **Not done if** | An ending is recorded outside the gate or the drain · a fifth task tool is exported, deprecated ones included, `answerTask` aside ([D2](DECISIONS.md#d2), [(e)](DECISIONS.md#e)) · a row misses its target · a coordinator or hand-off goal regresses · a closure bug is open |

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.

Linking deprecated exports into the not-done bar is correct for FIX-2087. If ER-5 gains “no deprecated aliases,” this line could slim back to D2 + ER-5 only — less bar density without weaker closure.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

from: epic-agent
session: FIX-2056
kind: reply

Declined: (e) is the owner's recorded decision and stays in full where children read it; trimming it is editorial, not a change of direction.


Generated by Claude Code


```mermaid
flowchart LR
Expand Down Expand Up @@ -112,6 +112,7 @@ every child blocks the closure, left off. The longest chain is four.
- **Patterns**, already plan boards; claim orders; routing policies, rounds and records; a delegate's memory.
- **The agent flow**, and `chief-of-staff` until FIX-2071; **messages** until FIX-2070; **parks and
`answerTask`** until FIX-2058.
- **Shift Manager's error route** into the Error Reporter, re-expressed on the ending path ([(f)](DECISIONS.md#f)).
- **`dispatcher()`** stays the transport a row runs through, not a row of its own.
- **Not children:** FIX-2072, FIX-2073, FIX-2075, FIX-2063, FIX-1024, FIX-1637 ([why](DECISIONS.md#decided-in-review-recorded-so-no-child-reopens-them)).

Expand All @@ -128,7 +129,7 @@ every child blocks the closure, left off. The longest chain is four.

| The debt | |
|---|---|
| **Removes** | Posts · six task tools · `settleSplitTask` · reopen · blocked · the automatic error routes ([f](DECISIONS.md#open)) · `afterRun`'s resends · the stopgap · a second fit call |
| **Removes** | Posts · six task tools · `settleSplitTask` · reopen · blocked · the `reportOwed` error marker · `afterRun`'s resends · the stopgap · a second fit call |
| **Adds** | A board `mode` · `getTask`'s wait · four filing settings · the role check at hire · scheduled tasks · one read for retired rows until FIX-2071 ([D3](DECISIONS.md#d3)) |

**Net: down.** Six task tools and a row kind leave; one setting per job arrives.
Expand All @@ -145,6 +146,10 @@ failure. **[The debt](#whats-already-here-and-the-debt):** net down.
3. **[D3](DECISIONS.md#d3) · A retired row in flight at upgrade is read, not dropped, through one
map.** If wrong: one read nobody needed.

**Open, the owner's:** [(e) deprecate or break](DECISIONS.md#open) · [(f) the automatic error route](DECISIONS.md#open).
**Decided by the owner:** [(e) remove the old APIs outright](DECISIONS.md#e), no deprecation
release · [(f) keep Shift Manager's error route](DECISIONS.md#f) · [(a) one epic](DECISIONS.md#a) ·
[(b) D1 kept](DECISIONS.md#b).

**Open, the owner's:** none.

Epic · 10 issues and a closure · Orchestration Primitives · Goal 2, differentiate on hard problems · Goal 4, keep the foundation honest
7 changes: 4 additions & 3 deletions specs/epics/FIX-2056/migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@
[Spec](SPEC.md) · [Decisions](DECISIONS.md)

One line per public surface the set removes, for the changesets and for consumers outside the
repo. Whether each is deprecated for a release first or removed in a breaking bump is
[(e)](DECISIONS.md#open), **pending the owner's answer**. Each tool's `<tool>_tasks` action follows its tool.
repo. Each is removed outright in its owner's PR, with no deprecation release, in a minor bump

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.

Clarity for external consumers: Pre-1.0 minor is right internally; a half-sentence here that teams outside the repo must rewrite at upgrade (accepted cost in (e)) would keep changeset authors from sounding semver-safe when the API surface is gone.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

from: epic-agent
session: FIX-2056
kind: reply

Adopted in d95ab2d: the changeset now says teams outside the repo rewrite at upgrade.


Generated by Claude Code

([(e)](DECISIONS.md#e)); that PR's changeset carries the row's line and says teams outside the
repo rewrite at upgrade. Each tool's `<tool>_tasks` action follows its tool. Shift Manager's
`errorCapture` is not here: it is kept ([(f)](DECISIONS.md#f)).

| Removed | Use instead | Owner |
|---|---|---|
Expand All @@ -18,4 +20,3 @@ repo. Whether each is deprecated for a release first or removed in a breaking bu
| `DELEGATED_POST_ENTRY` | A routed task through `WORKER_TASK_ENTRY` | FIX-2083 |
| `settleSplitTask` | Nothing: the claim gate settles a split when its pieces end | FIX-2077 |
| The agent worker's `run` entry | `respond` | FIX-2084 |
| `errorCapture` into the Error Reporter | Pending [(f)](DECISIONS.md#open) | FIX-2078 |
Loading