diff --git a/specs/epics/FIX-2056/DECISIONS.md b/specs/epics/FIX-2056/DECISIONS.md index 5e874e7f7e..132adaf50c 100644 --- a/specs/epics/FIX-2056/DECISIONS.md +++ b/specs/epics/FIX-2056/DECISIONS.md @@ -89,7 +89,7 @@ FIX-2081's own scope. | Seam | Owner, then who else touches it | |---|---| -| The task tool list (`orchestration/src/skills/task-tools-capability.ts`) | FIX-2080 lands first: it removes `blockTask`, adds `status` (held or pending) to `updateTask`'s patch, turns the busy-session refusal into a wait and adds `held` to the status filter. Then FIX-2081 owns the list and field rules, and FIX-2082's wait and FIX-2086's `message` land after it | +| The task tool list (`orchestration/src/skills/task-tools-capability.ts`) | FIX-2080 lands first: it removes `blockTask`, adds `status` (held or pending) to `updateTask`'s patch, turns the busy-session refusal into a wait and adds `held` to the status filter. Then FIX-2081 owns the list and field rules, and FIX-2082's wait, FIX-2083's `target` on `createTask` and FIX-2086's `message` land after it | | Who a filing can reach (`workforce/src/conversation-board/board.ts`, `reach()`) | FIX-2081 replaces a task session's roster arm with the self-step grant, after FIX-2076's plan rows land, so a worker files its own steps with or without delegates | | 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: after the engine's last drain on every terminal path, which follows `onFinished` (`engine/src/execution/runAction.ts:2447`→`:2630`→`:2641`, `:2773`→`:2918`→`:2936`), through an engine seam for framework packages, not an author hook. 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 | diff --git a/specs/epics/FIX-2056/SPEC.md b/specs/epics/FIX-2056/SPEC.md index d7bbc2e6a9..86f0356f2f 100644 --- a/specs/epics/FIX-2056/SPEC.md +++ b/specs/epics/FIX-2056/SPEC.md @@ -78,7 +78,7 @@ The reviewed snapshot; live state, and each issue's gap rows, are in Linear. | [FIX-2080](https://linear.app/fixpoint-labs/issue/FIX-2080) · filing settings | Start, session, result, attempts; cascades; the one read for retired rows ([D3](DECISIONS.md#d3)) | — | | [FIX-2081](https://linear.app/fixpoint-labs/issue/FIX-2081) · five tools | Five task tools, one rule per field; delegates as authority | FIX-2076, FIX-2080 | | [FIX-2082](https://linear.app/fixpoint-labs/issue/FIX-2082) · waits | `getTask` and the waited dispatch as one wait; 5 deep, 100 under a top task | FIX-2076, FIX-2077, FIX-2081 | -| [FIX-2083](https://linear.app/fixpoint-labs/issue/FIX-2083) · routed tasks | Posts become routed tasks; one fit check; the stopgap goes | FIX-2078, FIX-2080, FIX-2081 | +| [FIX-2083](https://linear.app/fixpoint-labs/issue/FIX-2083) · routed tasks | Posts become routed tasks; one fit check; the stopgap goes | FIX-2077, FIX-2078, FIX-2080, FIX-2081 | | [FIX-2084](https://linear.app/fixpoint-labs/issue/FIX-2084) · worker contract | Roles checked at hire; `respond` and `dispatch` | FIX-2078, FIX-2083 | | [FIX-2085](https://linear.app/fixpoint-labs/issue/FIX-2085) · schedules | A schedule files an ordinary task | — | | [FIX-2086](https://linear.app/fixpoint-labs/issue/FIX-2086) · steer and follow-up | `updateTask({ message })`; finished output never changes | FIX-2077, FIX-2081 | @@ -103,6 +103,7 @@ flowchart LR T -->|"getTask"| W T -->|"updateTask"| S T -->|"createTask, delegates"| R["FIX-2083 · routed tasks"] + B -->|"a routed task stays open while its filed work runs"| R L -->|"session, result, attempts"| R L -->|"dependents cancelled, with their cause"| E["FIX-2078 · endings and debts"] E -->|"the sweeper recovers a lost wait"| B @@ -113,7 +114,7 @@ flowchart LR ``` An edge is what one issue hands the next. FIX-2076, FIX-2080 and FIX-2085 start at once; -every child blocks the closure, left off. The longest chain is four. +every child blocks the closure, left off. The longest chain is five (FIX-2080, FIX-2081, FIX-2077, FIX-2083, FIX-2084). ## What stays as it is diff --git a/specs/epics/FIX-2056/migration.md b/specs/epics/FIX-2056/migration.md index 699299306b..c69cd8f11b 100644 --- a/specs/epics/FIX-2056/migration.md +++ b/specs/epics/FIX-2056/migration.md @@ -11,7 +11,7 @@ repo rewrite at upgrade. Each tool's `_tasks` action follows its tool. Shi | Removed | Use instead | Owner | |---|---|---| | `addTask` | `createTask({ …, held: true })` to file without starting; `updateTask({ id, status: "pending" })` releases it | FIX-2081 | -| `dispatchTask` | `createTask`; `{ taskId }` is `updateTask({ id, status: "pending" })`; `{ taskId, assignee }` is `updateTask({ id, assignee })`; wait with `getTask({ id, wait: true })`; a coordinator files a routed task | FIX-2082 removes the wait form, FIX-2083 the post form; the later removes the tool ([FIX-2081 D1](../../issues/FIX-2081/DECISIONS.md#d1)) | +| `dispatchTask` | `createTask`; `{ taskId }` is `updateTask({ id, status: "pending" })`; `{ taskId, assignee }` is `updateTask({ id, assignee })`; wait with `getTask({ id, wait: true })`; a coordinator files a routed task: `createTask` with `target` and the routing settings | FIX-2082 removes the wait form, FIX-2083 the post form; the later removes the tool ([FIX-2081 D1](../../issues/FIX-2081/DECISIONS.md#d1)) | | `readTask({ taskId })` | `getTask({ id })` | FIX-2081 | | `updateTask`'s `taskId`, `patch` (FIX-2080's interim `patch.status` included), `addLabel`, `removeLabel` | Flat input: `updateTask({ id, priority, labels, status, … })`; `labels` replaces the list | FIX-2081 | | `addDelegate`, `removeDelegate`, `setFallback` on every coordinator | `managesOwnDelegates: true` in the coordinator's `WORKER.md`; otherwise the user edits the list | FIX-2081 | @@ -28,7 +28,10 @@ repo rewrite at upgrade. Each tool's `_tasks` action follows its tool. Shi | The board's `counts.blocked` | `counts.held` | FIX-2080 | | `createCascadeSkipDependents` | Nothing: every board cancels a failed or cancelled row's dependents | FIX-2080 | | `TaskCollection.reopen` | A follow-up: `createTask` in the task's session | FIX-2086 | -| `DELEGATED_POST_ENTRY` | A routed task through `WORKER_TASK_ENTRY` | FIX-2083 | +| `DELEGATED_POST_ENTRY`, `delegatedPostEntry`, `delegatedPostHistory`, `delegatedPostOnFinished`, `delegatedPostSchema`, `DelegatedPost` | A routed task through `WORKER_TASK_ENTRY`: declare `work` with `workerTaskEntry`; the turn still gets `{ message }` | FIX-2083 | +| `taskLedgers({ taskTurn })` | Nothing: a routed turn is a task turn | FIX-2083 | +| `defineCoordinatorFlow`'s `delegateFlows`; `defineSessionBoard`'s `postFlows` and `posts`; `posts` and `both` in `listDelegates`' takes | Nothing: a delegate is a worker whose flow takes tasks, checked by its roles at hire | FIX-2083 | +| `TaskCollectionRef.dispatch`, `TaskDispatchOptions`, `Task.dispatchCall`, the `already-dispatched` decline | `createTask`, and `updateTask({ id, status: "pending" })` to release a held row | The later of FIX-2082 and FIX-2083, with `dispatchTask` | | `settleSplitTask` | Nothing: a split task stays running, and the claim gate settles it when a request for it ends with no piece open | FIX-2077 | | A split task's `{ answer, pieces }` output | The latest `reportProgress` checkpoint, else the worker's last answer; a piece's result from its own row, through FIX-2081's `listTasks({ filedByTask })` | FIX-2077 | | A failed piece failing its task, and the retry marker (`retryOf`) | The worker's turn decides: throw to fail the task, or file a new piece. A turn that ignores a failed piece completes the task | FIX-2077 | diff --git a/specs/issues/FIX-2083/DECISIONS.md b/specs/issues/FIX-2083/DECISIONS.md new file mode 100644 index 0000000000..58145194f5 --- /dev/null +++ b/specs/issues/FIX-2083/DECISIONS.md @@ -0,0 +1,178 @@ +# FIX-2083 · Decisions + +[Spec](SPEC.md) · **Decisions** + +The concept fixed what a routed task is (*Routing*, rules 5, 6, 7 and 9) and the epic gave the +settings to FIX-2080 and the ending path to FIX-2078. These three calls carry the rest. + +## The tree + +```mermaid +flowchart TD + I["FIX-2083"] --> D1["D1 · judgment files with createTask and the routing settings · the user's words ride as written"] + D1 -.->|"rejected"| X1["a post flag on createTask · a second shape of one tool"] + D1 -.->|"rejected"| X1b["the model's goal only · a paraphrase drops a detail"] + I --> D2["D2 · a round's deadline is a wake on the coordinator's session"] + D2 -.->|"rejected"| X2["a timer in each delegate's run · lost on a restart"] + I --> D3["D3 · one fit check · a lead is refused only on a clear none fits"] + D3 -.->|"rejected"| X3["keep two calls · two judgments of fit"] +``` + +Solid edges are what you're signing. Dashed edges lost, and the label says why. + + +## D1 · A judgment coordinator files with `createTask` and the routing settings; the delegate reads the user's words as written + +| | | +|---|---| +| **Instead of** | A `post: true` flag moved onto `createTask`, which refuses a goal; or the model's goal alone, as for any task | +| **Because** | [FIX-1872 D2](../FIX-1872/DECISIONS.md#d2) holds: a delegate answers what the person wrote, and the coordinator goal grades a held-out word arriving intact. A flag keeps a second shape of one tool, which FIX-2081 just retired. So the model files an ordinary task with the routing settings and its own goal, and on a turn routing a message the server attaches that message, as written, with who wrote it and the recent lines, to every task the turn files with its result to the conversation | +| **Locks in** | `target` on `createTask`, the public field naming a workstream record: a filing setting, set only at filing and refused on `updateTask`, and refused from a filer whose delegates have no targets. The workstream session it resolves to is server-written, stored top level beside `session` (BP-031), never an input. The attached message is server-written and never an input field. The routing settings are the model's per task (the concept's *chooses per task*): a routed task is attempts 1 ([epic](../../epics/FIX-2056/DECISIONS.md)) by FIX-2080's rule for a conversation-result task: unset reads 1, so a judgment model that leaves `maxAttempts` out gets 1, never the board's default, and any other value is refused at filing, naming the rule. The policies file 1 | + +![D1: how a judgment coordinator hands a message on. createTask with the routing settings and the message attached, chosen, beside a post flag on createTask. Decides it: what the delegate answers; both keep the user's words. The price: a field and a server-attached message on createTask. Locks in target on createTask; flips if the product wants coordinators to brief in their own words](figures/d1-createtask-as-written.svg) + +It comes down to the tool surface: both keep Alice's words, but a flag is a second shape of `createTask`. + +**What would change my mind:** the product wanting a coordinator to brief its delegates in its own +words. Then nothing is attached, and the goal is the brief. + + +## D2 · A round's deadline is a wake on the coordinator's session + +| | | +|---|---| +| **Instead of** | Today's timer, which each delegate's run keeps beside its turn and which wakes the coordinator at the deadline | +| **Because** | The timer lives in the delegate's process, so a restart loses it and the round waits for some other wake. FIX-2078's wake is the engine's one due-time source ([its D1](../FIX-2078/DECISIONS.md#d1)), fired until a pass clears it, after a crash too. The deadline belongs to the coordinator's round, not to a delegate's run, which a routed task's `work` entry no longer special-cases | +| **Locks in** | A round's deadline is due time on a wake on the coordinator's session whose entry is `roundDeadline`, cleared when every round is closed. On a host where FIX-2078's start check finds no wake support, the round deadline keeps an in-process timer, as today, so rounds still close there, though not across a restart. This issue therefore lands after FIX-2078, as the epic already orders. `roundDeadline` stays an internal entry | + +![D2: who closes a round at its deadline. A wake on the coordinator's session, chosen, beside a timer in each delegate's run. Decides it: a host restart before the deadline; the wake closes the round on time, the timer is lost. The price: one more due-time kind on the wake. Locks in that this lands after FIX-2078](figures/d2-round-wake.svg) + +It comes down to a restart: the wake closes the round on time; the timer is gone with the process. + +**What would change my mind:** FIX-2078 landing without a wake the sweeper keeps. Then the timer +stays until it does. + + +## D3 · One fit check; it vets a lead by refusing only a clear "none fits" + +| | | +|---|---| +| **Instead of** | Two calls: best fit's evaluator, which picks with a confidence, and FIX-1920's lead-fit generator, which answers *does the work say its sort* and *does the lead fit* | +| **Because** | Both judge one thing, whether a worker's description fits the work. One check, asked the candidates and the work, answers a pick and a confidence. Best fit reads the pick through its ladder unchanged. Opening a workstream asks it about the chosen lead, with two more choices beside the pick: *none fits* and *the work doesn't say its sort*. It refuses only *none fits*, so it stays a backstop for clear misfits, never a router, and a bare-name lead still passes. A failed call lets the open through, as today | +| **Locks in** | Lead-fit's two-part answer is one choice of three; `lead-doesnt-fit` now means the check answered *none fits*. `leadFit: { model }` keeps naming the model, and its record keeps its shape | + +![D3: how fit is judged. One check for best fit and the lead vet, chosen, beside keeping two calls. Decides it: two judgments of fit that can disagree on the same worker. The price: lead-fit's two-part answer becomes one choice, so a borderline lead may change verdict. Locks in lead-doesnt-fit meaning none fits; flips if a lead vet needs a judgment best fit can't give](figures/d3-one-fit-check.svg) + +It comes down to agreement: two calls can call one worker a fit for routing and a misfit for leading. + +**What would change my mind:** a lead vet that needs something best fit can't answer, such as +whether the lead can manage the workers under it. Then the vet keeps its own call. + +## Decided, not asked + +- **A routed task is only its settings.** Session *ongoing*, result *conversation*, and, from a + policy, attempts 1, on the coordinator's delegation board, worked on `work`. No kind marker, + no entry of its own, no special case on cancel, assign or lease. The conversation's recent + lines ride the task's server-written brief and are shown to the delegate's model as one + user-role message on that turn, never system text, never stored (today's guarantee). +- **The ongoing session of a workstream record** is the workstream's session, resolved at filing as + today. A record whose target names none files nothing and is recorded. +- **Rule 5 holds.** One open routed task per delegate session; a second waits. Best fit's hold + ([FIX-1833 D2](../FIX-1833/DECISIONS.md#d2)) still picks the delegate; the message now queues, + pending in the user's list and cancellable there. The cost, from rules 5, 6 and 9 together: a + delegate waiting on work it filed holds later messages to it until that work ends. A waiting + task whose round has closed is still worked; its answer lands once, late, as today. +- **A routed turn is a task turn.** The `taskTurn: false` stopgap goes; the delegate may file work, + and its task stays open until that work ends (rule 6, FIX-2077). Until FIX-2082 lifts the + task-turn wait refusal, a routed delegate files work and ends its turn, and rule 6 keeps its task + open; from FIX-2082 on it may also wait on that work (rule 9). The coordinator never waits on a + routed task (FIX-2082's refusal). +- **Routing never picks the coordinator itself.** Its candidates exclude the coordinator, whatever + its delegate list says, so no routed task lands on its own plan ledger. Best fit's self-pick + stays what it is today: the coordinator answers, and nothing is filed. +- **Endings.** One entry, `onTaskSettled`, through FIX-2078's path. A conversation-result ending + lands as a line under the delegate's name and feeds the rounds; nothing wakes a judgment turn + for it. A failure's error report rides it ([(f)](../../epics/FIX-2056/DECISIONS.md#f)). A + delegate's failed after-answer memory save is logged and does not fail its routed task, so the + user still gets the answer: the owner's decision of 2026-10-21 + ([audit thread](https://github.com/fixpoint-labs/flow-state-dev/pull/3598#issuecomment-6320943151)). + The rule and its carve-out for conversation-result tasks are FIX-2088's D1 + ([#3602](https://github.com/fixpoint-labs/flow-state-dev/pull/3602)); this issue builds nothing for it. +- **Rounds, deadlines and the routing record key on task ids.** A round holds the ids it filed. + A routed task's id stays derived from the message, the round and the delegate record, so the + same pick twice files one task. Stored routing records and round state naming a post id are + dual-read (BP-030). +- **A delegate is a worker whose flow takes conversation tasks.** `defineCoordinatorFlow` stops + requiring the post entry; FIX-2084 checks roles at hire. +- **The convergence point** for *a task whose result goes to the conversation*: FIX-2080's filing + check, refusing it from anything but a conversation. Its two writers are routing's filing step + and `createTask` on a judgment turn. +- **Retired rows.** This PR turns FIX-2080's *post to a routed task* entry on as it stops writing + posts, and builds no read of its own (ER-6). +- **`dispatchTask`.** This issue removes its post form; if FIX-2082 has landed, the tool and its + action too (FIX-2081 D1). +- **Changeset lines**, removed outright under [(e)](../../epics/FIX-2056/DECISIONS.md#e), each a + row in the epic's [`migration.md`](../../epics/FIX-2056/migration.md): + `DELEGATED_POST_ENTRY`, `delegatedPostEntry`, `delegatedPostHistory`, `delegatedPostOnFinished`, + `delegatedPostSchema` and `DelegatedPost` (a delegate declares `work` only); + `taskLedgers({ taskTurn })` (nothing); `defineCoordinatorFlow`'s `delegateFlows`, + `defineSessionBoard`'s `postFlows` and `posts`, and `posts`/`both` in `listDelegates`' takes + (a delegate is a worker whose flow takes tasks; FIX-2084's role check is the one answer). The + implementation's sweep checks they are gone. `dispatchTask({ post, target })` has no row of its + own: it is FIX-2081's `dispatchTask` row, whose routed-task line reads `createTask` with + `target` and the routing settings. +- **The collection's dispatch verb.** If this lands after FIX-2082, it removes + `TaskCollectionRef.dispatch`, `TaskDispatchOptions`, `Task.dispatchCall` and the + `already-dispatched` decline with the tool, under the same row. If FIX-2082 lands later, it + does. +- **No POC and no checker.** The premises are read from code at `96404d25`, and no claim here + rests on a count. + +## Considered and dropped + +| Option | Why it lost | +|---|---| +| Keep the post entry, drop only the kind marker | The entry is what holds the timer, the cancel action and the stopgap; the row would only look like a task | +| A `routed: true` preset on `createTask` | A name for three settings; one rule per field (FIX-2081) and the concept's per-task choice say set them | +| Address a workstream by an `assignee` like `eng.em (pricing-page)` | A string format a model must spell exactly; `target` is today's field, moved | +| Let a routed task run beside another in the delegate's session | Rule 5 is the owner's, and two open tasks in one session break FIX-2077's done | +| Refuse a goal on a routing turn's `createTask` | A field rule that changes with the turn; the attached message already keeps the words | + +## Notes from review + +Recorded for the implementer, not baked into the design. Round 1, on `48372389`. + +- **Tag the goal legs by slice** (Cursor, SPEC goal): *core* (no post writes; legs a, c, e; the + sweep) · *D2* (leg b) · *D3* (leg d's fit part), so a split implementation can land without + re-opening the whole goal. +- **Name the three settings where the routing figure first says "three settings"** (Cursor): + `session: ongoing`, `resultTo: conversation`, `maxAttempts: 1`. +- **Assemble the brief once per routing turn** (Cursor, D1): message and recent lines built once + and attached to each task the turn files, especially *everyone* filing N; one internal filing + helper, the successor to `filePost` / `deliverTo`, serving both writers. +- **No second entry or settlement path** (Cursor): `defineCoordinatorFlow` and the board's + `among: [work, onDelegatedPost]` go to `work` only, and `task-settled.ts`'s post branch is + deleted rather than adapter-mapped (ER-6). +- **Sweep the helpers too** (second look): the goal check's sweep also finds no `isPostRow`, + `onPostSettled` or `postCancelled` in `packages/` or `apps/`, leaving `workerTaskEntry` and + `conversation-board/task-entry.ts` as the only entry and ending pair (`task-settled.ts`, + `notice-delivery.ts`, `board.ts`). +- **Merge order** (second look, cross-spec audit): this lands after FIX-2077, FIX-2078, FIX-2080 + and FIX-2081 merge (the blocked-by relations); D2 rests on FIX-2078's sweeper-kept wake, and a + routed task stays open while its filed work runs only under FIX-2077's rule 6. No edge from + FIX-2082: the interim under *A routed turn is a task turn* covers either order. +- **D3 can be its own PR** (Cursor, second look): it shares no code path with the post removal. + It stays in this issue because the epic puts *one fit check* here + ([SPEC](../../epics/FIX-2056/SPEC.md), set and debt); the implementer may land it separately. + +## How it got here + +- **Draft** — framed as the epic's R-01 to R-05: a post becomes a task with FIX-2080's settings + on `work`, its ending on FIX-2078's path, its round deadline on FIX-2078's wake, and the two + fit calls folded into one. +- **Owner decision (2026-10-21)** — on the cross-spec audit's F1 + ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/3598#issuecomment-6320943151)): + for a conversation-result task, a failed after-answer memory save is logged, not a failed + task; every other task keeps FIX-2088 D1. Recorded under *Endings*, citing FIX-2088. + +**Open: none.** diff --git a/specs/issues/FIX-2083/SPEC.md b/specs/issues/FIX-2083/SPEC.md new file mode 100644 index 0000000000..eb22f5d2f7 --- /dev/null +++ b/specs/issues/FIX-2083/SPEC.md @@ -0,0 +1,160 @@ +# FIX-2083 · Routed tasks replace posts: a coordinator hands a user's message to a delegate by filing a task + +**Spec** · [Decisions](DECISIONS.md) + +## Six people, before and after + +| Someone who… | Today | After | +|---|---|---| +| **sends a message a coordinator routes** | It becomes a *post*: a row titled "Post for writer" she can cancel, and nothing else. A crash mid-answer ends it unanswered | An ordinary task in her list: writer's ongoing session, result to this conversation, one try. A crash is handled as any task's | +| **asks a delegate that hands part of the job on** | Gets writer's first reply. The handed-on work's result lands in writer's own session, not hers | Gets one answer, under writer's name, once the handed-on work is back | +| **sends a second message while that delegate still works** | Both run side by side in writer's session | The second waits in her list as a pending task she can cancel, then starts in the same session when the first ends. If writer is waiting on work it handed on, the second waits for that too | +| **runs rounds on a host that restarts** | A round past its deadline closes only when something else wakes the conversation | It closes within seconds of its deadline, restart or not ([D2](DECISIONS.md#d2)). A host without wakes keeps today's in-process round timer, so a restart there still waits for another wake, as today | +| **writes a judgment coordinator's prompt** | `dispatchTask` with `post: true` | `createTask` with the routing settings. The delegate still reads her words as written ([D1](DECISIONS.md#d1)) | +| **maintains the framework** | A post row kind, its own entry, ending entry, cancel action and stopgap; two fit calls | One task through one entry and one ending path; one fit check ([D3](DECISIONS.md#d3)) | + +## The goal, and how we'll know it's met + +**Every message a coordinator routes becomes a task its user can see and cancel, worked in the +delegate's ongoing session, whose one complete answer lands in her conversation under the +delegate's name, with nothing in the framework that writes or works a post: a post row stored +before the upgrade is read only through FIX-2080's map, until FIX-2071.** + +| Is it the right goal? | | +|---|---| +| **The real need** | *"Routed work is an ordinary task they can see, steer and cancel. Maintainers: one row kind, one entry"* (the issue). Stories R-01 to R-05; the epic's PD-3 and PR-1, re-homed here | +| **Smaller, and rejected** | "Drop the post kind; keep its entry, deadline timer and cancel action." The row looks like a task and still answers early, misses a deadline after a restart, and keeps the stopgap | +| **Bigger, and not this issue's** | Steer (FIX-2086) · `respond` and `dispatch` names (FIX-2084) · messages to a coordinator (FIX-2070) · `getTask`'s wait and its refusal of a conversation-result task (FIX-2082) | +| **Not done if** | An answer lands before the delegate's filed work ends · a round needs a later wake to close · a post row in a store at upgrade is lost · `onDelegatedPost`, `post: true` or a post row kind is still written · best fit and the lead vet still make different calls · the project hand-off goal (FIX-2005) or the coordinator goal regresses | + +```mermaid +flowchart LR + A["a Workforce app · real engine · durable store · scripted delegates"] --> L1["leg a · everyone and best fit"] + A --> L2["leg b · rounds · host killed past a deadline"] + A --> L3["leg c · a delegate files work and ends"] + A --> L4["leg d · judgment and a workstream"] + A --> L5["leg e · a post row stored before upgrade"] + L1 --> T["what Alice sees · her task list and her conversation"] + L2 --> T + L3 --> T + L4 --> T + L5 --> T + T -->|"each answer once · complete · on time"| P["PASS · goal met"] + C["control · round deadline on an in-process timer"] -.-> L2 + L2 -.->|"under the control"| F["must FAIL · round still open"] +``` + +The check reads Alice's task list and her conversation, not the coordinator's calls. The dashed +path keeps today's deadline timer, and it must fail. + +| How we verify | | +|---|---| +| **Goal check** | `goals/coordinators/routes-each-message-as-a-task/` · no model: scripted delegates and turns on the real coordinator flow · run by the implementer at completion · verdict in the implementation PR. Then the existing `goals/coordinators/hands-each-post-to-its-delegates/` and the FIX-2005 hand-off leg of `goals/workforce-privacy/two-users-share-a-project-and-nothing-else/`, real model, are rewritten on routed tasks (same intent; they read post rows today), then must pass. `goals/coordinators/routes-a-follow-up-by-its-conversation/` is rewritten the same way, and `goals/coordinators/one-fence-answers-each-post-once/` is retired into this check, whose legs a and b keep its intent (each answer lands once; a round closes at its deadline). The implementation PR does each, naming the intent kept | +| **Signal** | a: each message is one task per delegate in Alice's list, read through the public task action, with session *ongoing*, result *conversation*, one attempt, including when the judgment model leaves `maxAttempts` out (it reads 1); a judgment model's `maxAttempts: 3` on such a task is refused at filing, naming FIX-2080's rule; each answer lands once under its delegate's name; a second message to a busy delegate starts only after the first ends, in the same session; Alice's cancel ends the task and the round does not wait; cancelling the waiting second task ends it unstarted. b: with the host killed while a delegate works past a 2 s deadline, the round closes within the deadline + 2 s of restart, and the late answer lands once and goes no further. c: one line under writer's name, after the filed task ends, carrying its result. d: the judgment delegate's input holds Alice's held-out word; a workstream ask lands in the workstream's session; best fit's pick, its fallback and a misfit lead's refusal each run the one fit check, and a lead opened on work that names no sort (a bare name) passes. e: a seeded post row is worked and answered once, through FIX-2080's map. Sweep: no post entry declared, no post row written, no `post` field offered | +| **Input** | Deterministic delegates and evaluator picks, SQLite, the sweeper in-process. Other wording, delegate count and kill point must pass too | +| **Anti-game** | Read tasks through `listTasks_tasks` as Alice and lines from her conversation. No spies on filings or timers | +| **Control that must fail** | `GOAL_CONTROL=round-timer` must FAIL leg b on *the round closes within the deadline + 2 s of restart*. Today's `main` must FAIL leg c on *one line, after the filed task ends* and the sweep. With FIX-2080's *post to a routed task* entry off, leg e must FAIL | + +## What changes + +![Today against after. Today: a coordinator files a post row with a post kind, handed to onDelegatedPost in the delegate's session, its answer back on onPostSettled, a cancel on postCancelled, a deadline timer in the delegate's run, and two fit calls. After: routing files a task with three settings on the conversation's delegation board, handed to work in the delegate's ongoing session; its ending reaches onTaskSettled and lands under the delegate's name; the round's deadline is a wake on the coordinator's session; one fit check](figures/what-changes.svg) + +The post's six parts go; a task's settings, its one entry and its one ending path carry the job. + +**A judgment coordinator's call, and a delegate flow of your own:** + +```diff +- dispatchTask({ post: true, assignee: "writer" }) ++ createTask({ goal: "Draft the launch post", assignee: "writer", ++ session: "ongoing", resultTo: "conversation", maxAttempts: 1 }) ++ // writer reads Alice's message as written, with this goal beside it +- dispatchTask({ post: true, assignee: "eng.em", target: "pricing-page" }) ++ createTask({ goal: "…", assignee: "eng.em", target: "pricing-page", ++ session: "ongoing", resultTo: "conversation", maxAttempts: 1 }) +``` + +```diff + defineFlow({ + kind: "research", +- request: { onStarted: loadWorker, onFinished: delegatedPostOnFinished }, ++ request: { onStarted: loadWorker }, +- task: { actions: { [DELEGATED_POST_ENTRY]: delegatedPostEntry(researchAnswer) } }, ++ task: { actions: { [WORKER_TASK_ENTRY]: workerTaskEntry({ name: "research", turn: researchAnswer }) } }, ++ // a routed task arrives here like any task; the turn still gets { message } + }) +``` + +**Docs:** update *Workforce → Coordinators* (a routed task replaces the post throughout; the +judgment call; *Making your own flow a delegate* loses the post entry), *Shift Coordinator*, +*Projects → Checking the lead fits* (the one fit check), *Overview* and the glossary (post → +routed task), and the workforce and shift-manager READMEs. No new page. + +## How a message is routed + +```mermaid +flowchart LR + M["Alice's message · respond"] --> R["routing · policy or judgment"] + R -->|"fit check, best fit only"| R + R --> T["a routed task · delegation board"] + T --> W["work · the delegate's ongoing session"] + W -->|"ending · FIX-2078's one path"| S["onTaskSettled"] + S --> L["a line under the delegate's name · rounds"] + K["wake at the round's deadline"] --> S2["closes overdue rounds"] +``` + +A routed task is a task with three settings; routing only chooses who. + +## What stays as it is + +- **The policies** (judgment, best fit, round robin, everyone), best fit's ladder and hold, + rounds and their limit, the routing record, and a coordinator's recent lines shown to the + delegate as data, never as instructions. +- **Who settles a row**: the claim gate (ER-1). **Done** is FIX-2077's rule 6. +- **A project coordinator's** workstream records and `changeWorkstreamDelegate`. +- **`leadFit: { model }`** and the `lead-doesnt-fit` refusal, now answered by the one check. + +## What's already here, and the debt + +| Already here | What this does with it | +|---|---| +| Ways to hand a user's message to a delegate: the post (`onDelegatedPost`, `dispatchTask({ post })`) and a task through `work` | **Two today, one after.** The closest is the task: it differs only by settings, which FIX-2080 adds | +| The post's parts: its row kind, `isPostRow`'s three board refusals, `onPostSettled`, `postCancelled`, `delegatedPostOnFinished`, the deadline timer, `taskTurn: false` | **Removes** | +| FIX-2080's settings and its map entry *a post to a routed task* | **Builds on**, and turns the entry on | +| FIX-2078's one ending path and its wake | **Builds on.** A round's deadline is one more due time ([D2](DECISIONS.md#d2)) | +| FIX-2081's `createTask` and [D1](../FIX-2081/DECISIONS.md#d1): `dispatchTask` stays until its post form goes | **Removes** the post form here, and the tool if FIX-2082 has landed | +| Best fit's evaluator call; FIX-1920's lead-fit call | **Folds** into one fit check ([D3](DECISIONS.md#d3)) | +| [FIX-1872 D1](../FIX-1872/DECISIONS.md#d1): a post is worked on its own entry | **Superseded**, as the epic says: its reason, a cold session, is the session setting | +| [FIX-1872 D2](../FIX-1872/DECISIONS.md#d2): the model names who; the post goes as written | **Kept**, on `createTask` ([D1](DECISIONS.md#d1)) | +| [FIX-1870 D2](../../epics/FIX-1870/DECISIONS.md#d2); #3102's PD-3 and PR-1 | **Kept and finished** | +| [FIX-1833 D2](../FIX-1833/DECISIONS.md#d2): best fit holds the delegate on the last message | **Kept;** a held message now waits its turn (rule 5) | +| [FIX-1791 D1](../FIX-1791/DECISIONS.md#d1)'s round closing at its deadline | **Amended:** closed by a wake, not the delegate's timer | + +| The debt | | +|---|---| +| **Removes** | The post row kind and its schema · `DELEGATED_POST_ENTRY` and `delegatedPostEntry`, `delegatedPostHistory`, `delegatedPostOnFinished`, `delegatedPostSchema` · `dispatchTask`'s post form · `defineCoordinatorFlow`'s `delegateFlows`, `defineSessionBoard`'s `postFlows` and `posts`, and `posts`/`both` in what `listDelegates` says a delegate takes · `onPostSettled` and `postCancelled` · the deadline timer, where wakes are supported · `taskTurn: false` · the lead-fit call · if this lands after FIX-2082, `TaskCollectionRef.dispatch`, `TaskDispatchOptions`, `Task.dispatchCall` and the `already-dispatched` decline, with the tool. Each public one is a changeset line ([decided](DECISIONS.md#decided-not-asked)) | +| **Adds** | `target` on `createTask`, set at filing only ([D1](DECISIONS.md#d1)) · the user's message attached to a routed task's brief ([D1](DECISIONS.md#d1)) · a round-deadline due time on FIX-2078's wake | +| **Leaves** | A post-shaped row read through FIX-2080's map until FIX-2071 · a worker's message to a round-robin or everyone coordinator is still routed, until FIX-2070's `receive` (R-06) | + +**Net: down.** A row kind, two entries, an action, a timer, a stopgap and a model call go; one +field and one due time arrive. + +## Sign off + +**[The goal](#the-goal-and-how-well-know-its-met), at that size:** every routed message is a task +Alice lists, whose one complete answer lands on time, and nothing writes or works a post. If wrong: FIX-2084 +builds the worker contract on an entry that should be gone. + +**[The debt](#whats-already-here-and-the-debt), net down:** posts and their six parts go; `target` +and one due time arrive. If wrong: `createTask` carries a coordinator-only field for good. + +1. **[D1](DECISIONS.md#d1) · A judgment coordinator files with `createTask` and the routing + settings; the delegate reads the user's words as written.** If wrong: a field and an attached + message on `createTask` that only coordinators use. **The one to weigh.** +2. **[D2](DECISIONS.md#d2) · A round's deadline is a wake on the coordinator's session.** If + wrong: one more due-time kind the sweeper serves. +3. **[D3](DECISIONS.md#d3) · One fit check; it vets a lead by refusing only a clear "none fits".** + If wrong: a lead opened today is refused, or the reverse. + +**Open: none.** + +Improvement · `workforce` + `orchestration` + `shift-manager` · large · epic [FIX-2056](../../epics/FIX-2056/SPEC.md) · blocked by FIX-2077, FIX-2078, FIX-2080, FIX-2081 diff --git a/specs/issues/FIX-2083/figures/d1-createtask-as-written.svg b/specs/issues/FIX-2083/figures/d1-createtask-as-written.svg new file mode 100644 index 0000000000..606611af57 --- /dev/null +++ b/specs/issues/FIX-2083/figures/d1-createtask-as-written.svg @@ -0,0 +1,94 @@ + + + + + + D1 · THE CALL + How does a judgment coordinator hand a user's message to a delegate? + + + + CHOSEN + createTask, message attached + + INSTEAD OF + A post flag on createTask + + + + + WHAT THE TOOL + LOOKS LIKE + ▸ DECIDES IT + + + One shape: createTask + settings and a goal, as for any task + − + Two shapes of one tool + post: true refuses a goal; FIX-2081 just retired that + + + WHAT THE DELEGATE + READS + = + Her words, as written + attached by the server, the goal beside them + = + Her words, as written + the post, as today + + + + THE PRICE + − + A field and an attached message + target, and a server rule on routing turns + + + Nothing new on createTask + beyond the flag itself + + + + + LOCKS IN + target on createTask, public + and the message attached on every routing-turn filing + + + + FLIPS IF + Coordinators should brief in their own words + then nothing is attached; the goal is the brief + + diff --git a/specs/issues/FIX-2083/figures/d2-round-wake.svg b/specs/issues/FIX-2083/figures/d2-round-wake.svg new file mode 100644 index 0000000000..f578909ed8 --- /dev/null +++ b/specs/issues/FIX-2083/figures/d2-round-wake.svg @@ -0,0 +1,94 @@ + + + + + + D2 · THE CALL + Who closes a round when its deadline passes with a delegate still working? + + + + CHOSEN + A wake on the coordinator + + INSTEAD OF + A timer in each delegate's run + + + + + THE HOST RESTARTS + BEFORE THE DEADLINE + ▸ DECIDES IT + + + Closed on time + the sweeper fires the wake after restart + − + Waits for another wake + the timer died with the process + + + A QUIET + CONVERSATION + + + Closed on time + nothing else has to touch it + − + Closed on time, if alive + else at the next message + + + + THE PRICE + − + One more due-time kind + and this lands after FIX-2078 + + + Nothing new + today's code + + + + + LOCKS IN + A round's deadline is due time on the wake + this issue lands after FIX-2078 + + + + FLIPS IF + FIX-2078 lands without a durable wake + then the timer stays until it does + + diff --git a/specs/issues/FIX-2083/figures/d3-one-fit-check.svg b/specs/issues/FIX-2083/figures/d3-one-fit-check.svg new file mode 100644 index 0000000000..01dd0cb567 --- /dev/null +++ b/specs/issues/FIX-2083/figures/d3-one-fit-check.svg @@ -0,0 +1,95 @@ + + + + + + D3 · THE CALL + How is fit judged, for best fit's pick and a workstream's lead? + + + + CHOSEN + One fit check + + INSTEAD OF + Two calls, as today + + + + + ONE WORKER, + TWO VERDICTS + ▸ DECIDES IT + + + Cannot disagree + one judgment of description against work + − + Can disagree + a fit for routing, a misfit for leading + + + A BORDERLINE + LEAD + − + May change verdict + two-part answer becomes one choice: none fits + + + As today + says and fits, answered apart + + + + A CALL THAT + FAILS + = + The open goes through + as today + = + The open goes through + as today + + + + + LOCKS IN + lead-doesnt-fit means: the check said none fits + leadFit: { model } and its record keep their shape + + + + FLIPS IF + A lead vet needs what best fit can't answer + then the vet keeps its own call + + diff --git a/specs/issues/FIX-2083/figures/what-changes.svg b/specs/issues/FIX-2083/figures/what-changes.svg new file mode 100644 index 0000000000..c5f2691a1f --- /dev/null +++ b/specs/issues/FIX-2083/figures/what-changes.svg @@ -0,0 +1,71 @@ + + + + + + + TODAY · A POST + + Coordinator routes Alice's message + judgment: dispatchTask post: true + + A post row · kind post · one attempt + assign refused, complete refused, cancel sends postCancelled + + onDelegatedPost · taskTurn false + its own entry in the delegate's session, beside other posts + + A deadline timer in the delegate's run + lost on a restart + + onPostSettled · a second ending entry + a line under the delegate's name, rounds by post id + + Two fit calls + best fit picks with a confidence + lead fit answers says and fits apart + + + + + AFTER · A ROUTED TASK + + Coordinator routes Alice's message + judgment: createTask, her words attached + + A task · ongoing · conversation · 1 attempt + in Alice's list; cancel and assign as any task + + work · the delegate's ongoing session + a task turn; one open task at a time + + A wake on the coordinator's session + closes the round on time, after a restart too + + onTaskSettled · the one ending path + a line under the delegate's name, rounds by task id + + One fit check + best fit reads its pick + a lead is refused only on none fits + +