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
63 changes: 63 additions & 0 deletions specs/issues/FIX-1629/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# FIX-1629 · Business rules

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md)

When → then → proved by. CI = unit test in the owning package. VG = the goal check.

## Reading a row

| # | When | Then | Proved by |
|---|---|---|---|
| BR-1 | A board has tasks | One row per task, collapsed. Status comes first; goal (or title) and reason share the rest, one line each, clipped with the full text on hover | CI |
| BR-2 | The window is 1280 wide, panels at default | Status and ≥40px of the reason are in view on every row; the pane does not scroll sideways | VG read |
| BR-3 | A row is clicked, or Enter/Space on it | It expands in place, below itself, inside the pane. No overlay, nothing floats | CI · VG read |
| BR-4 | A row is expanded | Every field the task carries is shown: id, full goal wrapped, title, status, attempts / max, assignee, priority, labels, deps, reason, error, input, output, metadata, revision, created / updated, lease holder, dispatch run, latest change (kind, was, ×N). Absent fields are omitted, not faked | CI · VG read |
| BR-5 | A row is expanded | The raw JSON of the task is available folded inside the row, complete and unchanged | CI |
| BR-6 | A task updates while its row is open | The row stays open and shows the new values | CI |
| BR-7 | A value is huge, markup, or one unbroken token | It wraps or scrolls inside the row; the pane never widens | CI |
| BR-8 | Reason, per FIX-1481 BR-4 / BR-8 | Shown whenever `feedback` is present, whatever the status, verbatim; the slot is absent on a board where no task carries it | CI (existing tests kept) |

## Changing a task from its row
Comment thread
jhoffner marked this conversation as resolved.
Resolved

| # | When | Then | Proved by |
|---|---|---|---|
| BR-9 | The viewed flow has public actions whose input requires a string `taskId` | The expanded row lists them. Of the eight task tools that is six: `addTask` and `listTasks` take no `taskId` | CI · VG answer |
| BR-10 | Such an action's name ends with `_<suffix>` of any board the tab lists for the flow | It is listed only on that board's rows. One that matches no listed board's suffix is listed on every board | CI |
| BR-11 | No action qualifies | The row says so in one line and links the docs on exposing task actions | CI |
| BR-12 | An action is picked | Its form opens in the row with `taskId` filled and locked; other fields as the action bar draws them | CI |
| BR-13 | The action is submitted | It runs through the panel's existing action dispatch against the viewed flow and session; nothing else is called | CI · VG answer |
| BR-14 | It succeeds | The row shows the new state from the change item, without a reload | VG answer · VG tool |
| BR-15 | A tool returns `{ ok: false, error }`, or the request fails | The row shows the refusal or error, in words, read from the root `block_trace` output of the request the row dispatched (matched by that request id), or from the failed request. With no trace for it (observability off), the row says the outcome isn't visible. Never shown as success | CI · VG refuse |
| BR-16 | Two submits race on one task | Each gets its own verb's answer; the second may be refused. No client-side lock | CI (tool level, existing) |

## The ready-made actions

| # | When | Then | Proved by |
|---|---|---|---|
| BR-17 | A flow spreads `taskToolActions(board)` into `actions` | It gains the eight task tools as actions, named `<tool>_<board suffix>`, each running the same guarded verb a model's tool does. A request- or sequencer-backed board is refused when `taskToolActions` is called, naming its backing: its tasks don't outlive the request, so a later action could never find them | CI |
| BR-18 | One of them targets a settled task, or an illegal move | Refused by the verb, returned as a value | CI |
| BR-25 | `completeTask`, `failTask`, `blockTask` or `cancelTask` runs as an action on a row a live worker holds | It runs with no claim, as a coordinator's call does today, and lands if the transition is legal. The worker's own later result is refused `lost-claim` and dropped | CI |
| BR-19 | A channel declares `boardActions: true` | Each of its boards gets the eight actions. Without it, the channel's public actions are exactly today's | CI |
| BR-26 | A channel board's action is invoked while addressing any session but that channel's | Refused by name before the ledger is read, the same check `fileTask` and `readBoard` make. Channels share one flow, so the action map alone does not fence them | CI |
| BR-20 | `boardActions` is anything but `true`, `false` or absent | Refused at bind, by name, like any other bad value in the closed key list (which grows from six keys to seven) | CI |
| BR-21 | The reference app's `support.help` | Per the open fork | CI · hand check on Jake's screen |

## What none of this may do

| # | Rule | Proved by |
|---|---|---|
| BR-22 | No engine or core route, type or verb is added | Diff review · CI (route table test unchanged) |
| BR-23 | No action claims or drains a board (FIX-1457 ER-1) | CI |
| BR-24 | Nothing Workforce-specific (seats, rosters, channels) enters orchestration, engine or core | Diff review |

## Failure taxonomy

A refused verb is a value on the row. A thrown error or HTTP failure is shown on the row and the
form stays filled for a retry. Nothing is fatal to the panel; a render error in one row must not
blank the tab.

## Acceptance criteria this issue owns

- The goal check passes, and both controls fail at their named legs.
- FIX-1481's `the-checklist-rows` row-4 leg and FIX-1497's VB leg pass against the new row.
- FIX-1523 closes.
109 changes: 109 additions & 0 deletions specs/issues/FIX-1629/DECISIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# FIX-1629 · Decisions

[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md)

One decision to sign, one fork to call. The rest was decided and is listed so nobody re-derives it.

## The tree

```mermaid
flowchart TD
I["FIX-1629"] --> D1["D1 · change a task only through flow actions<br/>ready-made set is the eight task tools"]
D1 -.->|"rejected"| X1["edit the record as JSON<br/>needs an engine write that skips the task guards"]
D1 -.->|"rejected"| X2["a debug route for task verbs<br/>puts task-board knowledge in the engine"]
I --> O1["Open · support.help opts in now, or waits for FIX-1591"]
I --> E1["accordion rows · status and reason lead"]
E1 -.->|"absorbs"| X3["FIX-1523 · reason off screen at 1280"]
```

Solid edges are what you're signing. Dashed edges lost or were absorbed.

<a name="d1"></a>
## D1 · A task changes only through the flow's own actions. The ready-made set is the eight task tools. No record editor, no DevTool-only route

| | |
|---|---|
| **Instead of** | An editable JSON view of the task record in the Tasks tab or the Resources panel, or a debug-gated engine route that runs task verbs for the DevTool |
| **Because** | Every way a task moves already exists as a guarded verb (terminal rows refuse, a lost claim refuses, `parked → pending` is fenced). The eight task tools (`addTask`, `assignTask`, `completeTask`, `failTask`, `blockTask`, `cancelTask`, `updateTask`, `listTasks`) are the framework's own surface over those verbs, already given to models. Exposing them as flow actions reuses the action path the DevTool already calls. A record editor needs a state-write route that no client has today and would bypass every guard. A debug verb route puts task-board knowledge in the engine (L1) and is a DevTool-only mutation path. Tenets 2 and 5: refine what exists, one convergence point for writes |
| **Locks in** | What you can do to a task from the DevTool is exactly what the flow exposes. A flow that exposes nothing shows nothing to press, with a line saying how to expose the set. Fields no verb writes (the goal, attempts, revision) can't be changed from the DevTool. Adding an editor later means a new write route and a decision about which guards it skips |

![D1. How does the DevTool change a task? Chosen: the flow's own actions, with the eight task tools as the ready-made set. Instead of: edit the record as JSON. It comes down to the task guards: actions go through the verbs that refuse illegal moves, an editor writes past them. The price: only what a verb allows, and a flow must expose actions. Layer fit: actions need no engine change; the editor needs a new write route. Locks in: the DevTool can do what the flow exposes and nothing else. Flips if: you need to change fields no verb writes, such as the goal](figures/d1-actions-not-edits.svg)

It comes down to the task guards: an editor writes a row the verbs would have refused.

<a name="open"></a>
## Open · Should the reference app's `support.help` channel turn its escalation actions on now?

**Plain terms.** Workforce channels gain an opt-in that exposes their boards' eight task
tools as actions, off by default. Turning it on for `support.help` makes the screen you sent
manageable. It also means anyone who can reach that channel can cancel, complete or reassign an
escalation, including one a seat is working on right now; that seat's own result is then refused
and dropped. FIX-1591 ("who attends escalations") is parked waiting on you.

**Trade-off.** On now: your screenshot works end to end, and the demo shows the feature on its
headline board. Off until FIX-1591: nothing pre-empts that hold, but the reference app's only
board stays read-only in the tab; the feature is proved only on the lab hire.

**Recommendation: on now.** It is a developer's tool on a demo board with no production users,
and the change is one line to reverse. It does not decide FIX-1591's question: nothing drains
`escalations` and no person-side screen is built.

**What would change my mind:** if you mean `support.help` to demo "nobody works this board" as
the point of the unattended-board warning, off is right.

**If wrong:** on, and you wanted the hold: revert one line, nothing else moves. Off, and you
wanted it: the tab stays read-only on the board you use most until a follow-up.

![Open fork. Should support.help expose its escalation actions now? Recommended: on now. Instead of: off until FIX-1591 decides. It comes down to your screenshot: on, the escalations rows are manageable from the tab; off, they stay read-only. The price of on: any caller who can reach the channel can change an escalation, even one a seat is working on, on a demo with no production users. FIX-1591 hold: on does not decide it, nothing drains the board. Locks in: a one-line setting in the reference app. Flips if: the demo is meant to show an unattended board](figures/open-support-help-actions.svg)

It comes down to your screenshot: off, the board you asked about stays read-only.

## Decided, not asked

- **FIX-1523 is absorbed and closes when this ships.** The collapsed row leads with status, then
the goal and the reason sharing the remaining width; nothing scrolls sideways at 1280.
- **Which actions a row offers:** every public action on the viewed flow whose input has a
required string `taskId`. One whose name ends with the suffix of any board the tab lists
(`_support_help_escalations`) shows only on that board's rows; the rest show on every board.
Generic, so an app's own `answer` action shows too. Of the eight task tools, `addTask` and
`listTasks` take no `taskId`, so a row offers six.
- **`taskId` is filled in and locked;** other fields use the action bar's existing form.
- **The row reads the result from the request's root trace.** The dispatch returns only a
request id and a refusal writes nothing, so the tool's `{ ok, error }` lives only in the root
`block_trace` of the request the row sent. With traces off, the row says the outcome isn't
visible. A refusal never shows as success.
- **An action's settlement overrides a worker's claim.** An action has no claim ticket, so it
settles as a coordinator does today: legal transitions only, no ownership check. The holding
seat's later result is refused (`lost-claim`). Clearing a stuck row is the debugging job, and
refusing would need a new substrate guard. It is why channel exposure stays opt-in.
- **Durable boards only.** A request- or sequencer-backed ledger is gone before the row's action
runs, so `taskToolActions` refuses those backings by name, as `unparkAndDrain` does.
- **A channel's actions work only in its own session.** Channels share one flow, so each action
runs the session check `fileTask` and `readBoard` already make.
- **One PR, not two.** You asked for both halves together; Cursor's review agreed.
- **The row reads the item stream, as today.** It updates from the change item the action's
own request emits. Changes made by another session stay FIX-1506's.
- **One orchestration export, `taskToolActions`,** so a non-Workforce board gets the set without
Comment thread
jhoffner marked this conversation as resolved.
Resolved
reaching for an internal resolver. The suffix rule moves from Workforce into orchestration so
names have one home.
- **Several rows can be open at once;** a live update never collapses an open row.
- **The Resources panel is untouched.** It stays the ledger view.

## Considered and dropped

| Option | Why it lost |
|---|---|
| Accordion only, actions later | Half of what was asked |
| Match actions by a fixed name list | Misses an app's own `answer`; `taskId` in the input is the honest signal |
| Always expose channel board actions | Opens every production channel's rows to any caller |
| Offer `unpark` as a ninth tool | Not in the eight; answering a parked row stays the app's action (FIX-1457 ER-1) |
| A POC of the row | The UI is an extension of an existing table and form; the goal check renders it on a live hire |

## How it got here

- **Draft** — Framed as read-in-place plus change-through-actions; chose the eight task tools as
flow actions over a record editor, a Workforce opt-in with one open fork on `support.help`,
one PR.
- **Review, round 2** — The refusal path moved to the request's root trace, because the dispatch
response and the change items carry no refused result. Added the claim-override, durable-board
and channel-session rules the second look and Codex found missing. D1 and the fork stand.
113 changes: 113 additions & 0 deletions specs/issues/FIX-1629/DOCS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# FIX-1629 · Documentation draft

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs** · [Evolution](EVOLUTION.md)

Drafted by the spec author; this session could not dispatch `docs-writer`. The implementer runs
`docs-writer` then `docs-editor` over these drafts against what shipped, before publishing.
Quoted text is the proposed prose.

## UPDATE · `apps/docs/docs/devtool/overview.md` · "Task boards" (replace the section body)

> The Tasks tab lists the task boards the open session emitted. A task board is the queue a flow
> files work into for workers to claim. Each task is one row: its status first, then its goal,
> then a short note about it when there is one.
>
> Click a row, or focus it and press Enter, to open it in place. The open row shows everything
> the task carries: the full goal, attempts, assignee, priority, labels, the note and any error,
> input and output, metadata, revision and timestamps, and the dispatch run working it. The raw
> record is folded at the bottom if you want the JSON. Rows stay open while the task changes
> underneath them.
>
> The note is the task's `feedback` field. Parking a task for review records why it is
> waiting, or clears the note when you give no reason. A failure with retries left records the
> error and sends the row back to `pending`. Resuming a parked task writes the answer you hand
> it. The row shows whichever wrote last, and the note slot appears only on boards where some
> task carries one. A note is not an error: a failure with no retries left writes `error`.
>
> ### Changing a task from its row
>
> An open row lists the flow's actions that take a `taskId`. Pick one and its form opens in the
> row with the task's id filled in. Submit it and the DevTool runs the action exactly as the
> action bar would, in the session you are looking at. The row updates when the task changes.
>
> If the task can't move that way, say you cancel a task that already finished, the action
> refuses and the row shows why. Nothing is written. The row reads that answer from the
> request's trace, so with trace observability off it tells you the outcome isn't visible.
>
> The DevTool changes tasks only through your flow's actions. There is no way to edit a
> task's record directly, which keeps every change going through the same checks a worker's
> would. If a row says the flow has no task actions, see
> [exposing task actions](/docs/orchestration/task-board#changing-tasks-from-outside-a-run).

## UPDATE · `apps/docs/docs/orchestration/task-board.md` · new section after "Commanding the board with its capability"

> ## Changing tasks from outside a run
>
> Workers change tasks while a board drains. Sometimes a person needs to as well: cancel a task
> nobody needs, bump a priority, mark one failed. `taskToolActions` gives your flow the same
> eight task tools a model can hold, as actions any caller of the flow can run:
>
> ```ts
> import { taskBoard, taskToolActions } from "@flow-state-dev/orchestration/task-board";
>
> const board = taskBoard({ name: "todos", collection: todos, workers });
>
> defineFlow({
> kind: "ops",
> resources: { [todos.id]: todos },
> actions: {
> drain: { block: board.drain },
> ...taskToolActions(board),
> },
> });
> ```
>
> The actions are named for the board: `addTask_todos`, `assignTask_todos`, `completeTask_todos`,
> `failTask_todos`, `blockTask_todos`, `cancelTask_todos`, `updateTask_todos` and
> `listTasks_todos`. Each runs the same checked transition a worker's would, so a move the task
> can't make comes back as `{ ok: false, error }` rather than a write. None of them claims or
> drains the board. Settling a task a worker is still running is allowed, as it is for a
> coordinator: your write lands and the worker's own result is refused when it arrives.
>
> The board needs a collection that outlives a request (`defineTaskCollection`). A board on
> the default request-scoped ledger is refused, because a later action could never find its
> tasks.
>
> They are public actions. Anyone who can call your flow can call them, so add them only to a
> flow whose callers you trust with the board. The DevTool's Tasks tab offers them on each row.

## UPDATE · `apps/docs/docs/workforce/channels.md` · "Working the rows", after the paragraph on `channelBoardTaskTools`

> A channel can offer the same eight tools to callers, as actions. Add `boardActions: true` to
> its `CHANNEL.md`:
>
> ```md
> ---
> description: Ask the support team anything.
> members: [support.devices, support.accounts]
> boards: [escalations]
> boardActions: true
> ---
> ```
>
> Each board gains `cancelTask_support_help_escalations` and its seven siblings beside
> `fileTask` and `readBoard`. It is off by default because anyone who can reach the channel can
> then settle or reassign its rows, including one a seat is working on, and `author` checks on
> filing don't apply to these. Each action works only in its own channel's session. Turn it on
> for boards people are meant to work from outside, and for development.

And in "What the file is checked for": *"the closed list of six keys"* → *"seven"*.

## UPDATE · `packages/orchestration/README.md` · task-board exports

> - `taskToolActions(board)` — the eight task tools over `board`, as a flow `actions` map named
> `<tool>_<board>`. Public actions; see the docs before exposing them.

## UPDATE · `packages/workforce/README.md` · channels

> - `CHANNEL.md` `boardActions: true` — expose each board's task tools as channel actions. Off by default.

## Changesets

`@flow-state-dev/orchestration` (minor: new export), `@flow-state-dev/workforce` (minor: new key),
`@flow-state-dev/devtool` (patch: Tasks tab).
Loading
Loading