diff --git a/specs/issues/FIX-1629/BUSINESS-RULES.md b/specs/issues/FIX-1629/BUSINESS-RULES.md new file mode 100644 index 0000000000..e8e64599c5 --- /dev/null +++ b/specs/issues/FIX-1629/BUSINESS-RULES.md @@ -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 + +| # | 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 `_` 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 `_`, 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. diff --git a/specs/issues/FIX-1629/DECISIONS.md b/specs/issues/FIX-1629/DECISIONS.md new file mode 100644 index 0000000000..539a3f459d --- /dev/null +++ b/specs/issues/FIX-1629/DECISIONS.md @@ -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
ready-made set is the eight task tools"] + D1 -.->|"rejected"| X1["edit the record as JSON
needs an engine write that skips the task guards"] + D1 -.->|"rejected"| X2["a debug route for task verbs
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. + + +## 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. + + +## 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 + 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. diff --git a/specs/issues/FIX-1629/DOCS.md b/specs/issues/FIX-1629/DOCS.md new file mode 100644 index 0000000000..8c840638b5 --- /dev/null +++ b/specs/issues/FIX-1629/DOCS.md @@ -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 +> `_`. 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). diff --git a/specs/issues/FIX-1629/EVOLUTION.md b/specs/issues/FIX-1629/EVOLUTION.md new file mode 100644 index 0000000000..6d7c83317d --- /dev/null +++ b/specs/issues/FIX-1629/EVOLUTION.md @@ -0,0 +1,20 @@ +# FIX-1629 · Evolution + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · **Evolution** + +Earlier designs this issue retains or amends. Retained specs are not edited. The Tasks panel +itself (FIX-445) has no retained spec; its intent is in the file header of +`task-collections-view.tsx`. + +| Prior intent and precise source | Treatment | Why / evidence | Replacement | Compatibility | +|---|---|---|---|---| +| Reason shown on the row, keyed on the presence of `feedback`, verbatim, absent on a board with none. [FIX-1481 BR-1, BR-2, BR-4, BR-5, BR-8](../FIX-1481/BUSINESS-RULES.md) and its *Decided, not asked* | **Retained** | Still the right rule; only its place on the row moves | BR-8 | Same predicate and text | +| *"Still readable on the row, the table still looks like a table, and the full text is still in the expander."* [FIX-1481 BR-6](../FIX-1481/BUSINESS-RULES.md) | **Amended**: no table and no separate expander; the row itself expands, full text inside it | The floating expander is the defect in Jake's screenshot | BR-3, BR-7 | Full text still one click away | +| *"Any task row opened in the JSON expander: unchanged, byte for byte."* [FIX-1481 BR-7](../FIX-1481/BUSINESS-RULES.md) | **Amended**: the raw JSON moves inside the expanded row, folded, still complete | Same | BR-5 | Same data, new place | +| Reason column after Goal, Goal up to 28rem. FIX-1481 as shipped | **Superseded** by status first, goal and reason sharing the width | FIX-1523 measured the reason at 0px at 1280 | BR-1, BR-2 | FIX-1523 closes | +| FIX-1497 VB and FIX-1481's goal read the reason *"under the `Reason` heading"*. [FIX-1497 PLAN](../FIX-1497/PLAN.md), VB | **Amended**: same claim, read from the row's reason slot by task id | The heading goes away | Plan S10, C7 | Same legs and controls | +| A person answers a parked row through a flow action carrying the request's principal; never a drain. [FIX-1457 ER-1](../../epics/FIX-1457/BUSINESS-RULES.md) | **Retained** | Row actions are flow actions and none drains | BR-23 | — | +| Channel board task tools are for models, all eight or none. [workforce channels docs, "Working the rows"](../../../apps/docs/docs/workforce/channels.md#working-the-rows) | **Retained**, and the same eight are offered as actions behind an opt-in | One surface, two callers | BR-17, BR-19 | Tool names unchanged | + +Before implementing, compare each row with current code and docs; approval of the intent does +not establish what has shipped. diff --git a/specs/issues/FIX-1629/PLAN.md b/specs/issues/FIX-1629/PLAN.md new file mode 100644 index 0000000000..da4ad9c0df --- /dev/null +++ b/specs/issues/FIX-1629/PLAN.md @@ -0,0 +1,108 @@ +# FIX-1629 · Plan + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +Discipline: `tdd`. One PR. Directional: shape and order are fixed, local design is yours. + +## Surfaces + +| ID | Package · file or role | Change | Rules | +|---|---|---|---| +| S1 | `devtool` · `components/workspace/task-collections-view.tsx` | Table → list of disclosure rows (button, `aria-expanded`, `aria-controls`). Collapsed: status · goal · reason · assignee · run · kind, as a grid whose flexible cells have `minmax(0, 1fr)`. **Remove** the `
` Details column and its fixed `w-[28rem]` block | BR-1–BR-8 | +| S2 | `devtool` · new row-body component beside S1 | Field list (BR-4), folded `JsonViewer`, Actions section. Open state keyed by board + task id, held above the row so item updates don't reset it | BR-4–BR-7, BR-9–BR-15 | +| S3 | `devtool` · a pure `lib/` helper | `taskActionsFor(actions, schemas, collectionId, allCollectionIds)`: qualifying actions per BR-9 / BR-10. Takes every board the tab lists for the flow, so another board's suffixed action is told apart from a generic one. Mirrors the suffix rule (S5) locally, as the panel mirrors wire shapes | BR-9–BR-11 | +| S4 | `devtool` · `DevToolPanel.tsx` + `action-bar`'s form | Pass the flow's action names, schemas and the existing `handleSendAction` into S1. Reuse `SchemaForm`; add a way to fix one field's value. `handleSendAction` returns the dispatched request id (or the thrown error) to the row; the row reads the outcome from that request's root `block_trace` output on the session's items (`resolveBlockValue`), or its failed status. The response itself carries no output | BR-12–BR-15 | +| S5 | `orchestration` · `skills/task-tools-capability.ts` + `task-board` | Export `taskToolActions(board)` → `Record` over `buildTaskToolsList(resolver, undefined, suffix)`. Accepts a `TaskBoardHandle` (uses its own resolver; throws unless `handle.backing === "resource"`) or a `(collectionId, resolver)` pair whose caller resolves a durable ledger. **Move** `boardToolSuffix` here as `taskToolSuffix` | BR-17, BR-18, BR-25 | +| S6 | `workforce` · `channel/channel-board.ts`, `channel-flow.ts`, `channel-binder.ts` | Import `taskToolSuffix` (remove the local copy). `defineChannelFlow` takes a per-channel `boardActions`; when true, spread each board's `taskToolActions` into public `actions` **and** `internal.actions`. Each such action first runs the session-to-board check `ledgerNamed` makes (bound channel, board declared by `ctx.session.identity.id`) and refuses otherwise. Binder: seventh key in the closed list, boolean only | BR-19, BR-20, BR-26 | +| S7 | kitchen-sink · `support/channels/help/CHANNEL.md` | `boardActions: true` **if** the open fork lands on "on now"; otherwise untouched | BR-21 | +| S8 | `goals/multi-seat-collab/lab` | The lab's channel declares `boardActions`, unless `GOAL_CONTROL=channel-actions-off` | VG tool | +| S9 | `goals/devtool-workforce-visibility/works-a-task-from-its-row/` | New goal check (SPEC → How we verify) | VG | +| S10 | `goals/devtool-workforce-visibility/the-checklist-rows/run.mts`, `goals/multi-seat-collab/it-hands-a-row-between-two-seats-in-view/run.mts` | Re-point the reason read from "cell under the Reason heading" to the collapsed row's reason slot, by task id. Same legs, same controls | BR-8 | +| S11 | docs | Per [DOCS.md](DOCS.md) | — | + +## Sequence + +```mermaid +flowchart LR + S5 --> S6 --> S7 + S6 --> S8 + S3 --> S2 + S1 --> S2 --> S4 + S4 --> S10 + S4 --> S9 + S8 --> S9 + S9 --> S11 +``` + +S5/S6 and S1–S4 are independent; land orchestration first so the DevTool tests can use real action names. + +## Checks + +| ID | After | Passes when | +|---|---|---| +| C0 | S5 | **Premise first:** a task-tool handler (it declares `parentStateSchema`) runs as a flow-action root in a `fsdev run`/engine test and writes the ledger, **and** that request's root `block_trace` carries the handler's `{ ok, error }` as inline output on the session's items. If either fails, wrap each in a one-step sequencer inside S5 (its trace refs the handler's) — no engine change | +| C1 | S5 | Each of the eight actions runs its verb on a row **filed by an earlier request**; a settled-row `cancelTask_x` returns `declined`/`ok:false`; a request-backed handle is refused by name; `completeTask_x` on a row a worker holds lands, and that worker's own settlement then declines `lost-claim` (BR-17, BR-18, BR-25) | +| C2 | S6 | Channel with `boardActions: true` lists 8 × boards more public actions; without it the public map equals today's snapshot; a bad value is refused at bind by name; channel A's action invoked on channel B's session is refused and A's ledger is unchanged (BR-19, BR-20, BR-26) | +| C3 | S3 | Qualification: required `taskId` string in, optional `taskId` out, suffix scoping, unsuffixed on every board; with two boards A and B, `answer_` shows on A only and a generic `answer` on both (BR-9, BR-10) | +| C4 | S1/S2 | jsdom: collapsed order, expand by click and keyboard, every BR-4 field present when set and absent when not, JSON folded and equal to the task, open row survives an update, long unbroken token contained (BR-1, BR-3–BR-7) | +| C5 | S4 | Submit calls the existing dispatch with `taskId` fixed; a **declined** result (HTTP 2xx, `{ ok: false }` in the root trace) and a thrown error render as failures; no trace renders "outcome not visible", not success; the no-actions line appears (BR-11–BR-15) | +| C6 | S1 | FIX-1481's Reason tests pass, re-pointed at the new slot (BR-8) | +| C7 | S10 | Both existing goal checks PASS on the new row; their named controls still FAIL where they did | +| VG | S9 | The goal check PASSes; `main` fails read/answer/tool; `channel-actions-off` fails tool/refuse only | +| C8 | all | `pnpm typecheck`, `pnpm test`; engine route-table test unchanged (BR-22) | + +Second paths (BP-035): off state of `boardActions` (C2); a flow with no qualifying action (C5); +legacy `awaiting_review` rows still render as `parked` (existing fold, keep its test). + +## Pinned names + +| Name | Why | +|---|---| +| `taskToolActions` | The one public hook; docs and the diff use it | +| `taskToolSuffix` and the `_` action names | Same names models already see for channel boards; the DevTool scopes by it | +| `boardActions` (CHANNEL.md key) | A declared key users type | +| `taskId` as the qualifying input field | It is what the eight tools and the lab's `answer` already take | + +## Guardrails + +| Rule | Because | +|---|---| +| No engine/core change | L1 stays generic; the action path already exists (constraint, BR-22) | +| The DevTool never writes except through `handleSendAction` | One mutation path; anything else is the DevTool-only route D1 rejected | +| Render refusals as refusals | The verbs return `declined` as a value; a green toast on a refusal lies | +| Keep the FIX-1481 presence predicate and verbatim reason | Its BR-4/BR-8 are load-bearing; see Evolution | +| Workforce off by default | A public action set on every channel is a production exposure nobody asked for | + +## Docs + +[DOCS.md](DOCS.md) holds the drafts. Reconcile against shipped behaviour, run `docs-writer` then +`docs-editor`, and publish in this PR. + +## Sketch + +None; the shape extends an existing table and form. No POC: the goal check renders it on a live hire. + +## At implement time + +- PR #2344 (FIX-1622) touches kitchen-sink's escalations wiring; rebase over it if merged. +- Confirm the lab's `answer` action input requires `taskId` (BR-9 depends on it). +- Confirm the change item from an action's request reaches the viewed session's items (FIX-1622's POC shows this for `fileTask` on the channel). + +## Notes from review + +- "If devtool truly cannot depend on `@flow-state-dev/orchestration`, say that explicitly and point C3 at shared test vectors; otherwise export a tiny `matchesBoardSuffix(actionName, collectionId)` from orchestration (or core) and delete the mirror." (It can't today: `apps/devtool` depends on client, core, devtool and react only.) — cursor ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/2346#discussion_r4127074959)) +- "Is there an internal caller for suffixed task tools? If not, **public-only spread** is a smaller catalog and simpler C2 without changing DevTool behavior. If the mirror is required, one sentence naming the caller (or \"consistency with fileTask\") would close the loop." — cursor ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/2346#discussion_r4127074964)) +- "BR-4's field enumeration will require spec edits whenever the task record grows. BR-5 already requires byte-complete folded JSON. Consider narrowing BR-4 to structured display of known fields with BR-5 as the completeness backstop." — cursor ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/2346#discussion_r4127074977)) +- "Memoize `taskActionsFor` once per `(flow, collectionId)`, not per row; lazy-mount `JsonViewer` on expand/stream ticks." — cursor ([review](https://github.com/fixpoint-labs/flow-state-dev/pull/2346#pullrequestreview-5344706056)) +- "Add a devtool unit test that pins the mirrored function against a literal like `eng.feature.work` → `eng_feature_work`. The goal check would catch it only late." — second look ([comment](https://github.com/fixpoint-labs/flow-state-dev/pull/2346#issuecomment-5878640609)) +- "If you keep one PR, land the accordion commit first so a revert of the actions half is clean." — second look ([comment](https://github.com/fixpoint-labs/flow-state-dev/pull/2346#issuecomment-5878640609)) +- A board with no tasks may not be listed by the tab, so its suffixed actions would read as generic on other boards (BR-10). If the tab can list empty boards from the flow's declared collections, feed S3 that set. — spec author, from Codex's P2 ([thread](https://github.com/fixpoint-labs/flow-state-dev/pull/2346#discussion_r4127102778)) + +These are inputs, not instructions. Adopt, adapt, or discard; you owe no justification for +discarding one. A note that turns out to reveal a design problem is a spec blind spot: +surface it and fold it back. + +## Follow-ups + +- Close FIX-1523 on merge. +- If D1 flips later (editing fields no verb writes), that is its own issue with its own route. diff --git a/specs/issues/FIX-1629/SPEC.md b/specs/issues/FIX-1629/SPEC.md new file mode 100644 index 0000000000..d4f6886d5c --- /dev/null +++ b/specs/issues/FIX-1629/SPEC.md @@ -0,0 +1,114 @@ +# FIX-1629 · DevTool Tasks tab: inspect a task in an accordion row, and manage its state with the framework's standard tools + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) + +Feature · `devtool` + `orchestration` + `workforce` + kitchen-sink + `goals/` · medium · 1 PR · +no epic · absorbs [FIX-1523](https://linear.app/fixpoint-labs/issue/FIX-1523) + +## Five people, before and after + +| Someone who… | Today | After | +|---|---|---| +| **opens a task in the Tasks tab** | A raw JSON block floats over the table, clipped at the pane edge. The whole record is readable only in the Resources panel | The row opens in place: every field readable, raw JSON folded underneath | +| **reads why a row is parked, on a laptop** (FIX-1523) | Reason off screen below ~1500px; Status too at 1280 | Status and reason lead the row, in view at 1280 | +| **wants to cancel, re-prioritize, fail or answer a task while debugging** | Can't from the tab. Writes a curl or a throwaway action | Picks an action on the row, task id filled in, result shown on the row | +| **builds a flow with a board** | Nothing in the DevTool changes task state | Any action on the flow that takes a `taskId` shows on the row. The ready-made set is the framework's eight task tools, as actions, for a board whose tasks outlive a request; the six that name a task appear on rows | +| **runs a Workforce channel in production** | Callers can `fileTask` and `readBoard` | Unchanged unless the channel opts in to its board's task actions ([open fork](#sign-off)) | + +## The goal, and how we'll know it's met + +**A developer can open any task in the Tasks tab, read its whole record in place, change its +state from the same row through the flow's own actions, and see the result on the row without a +reload.** + +| Is it the right goal? | | +|---|---| +| **The real need** | Jake, 2026-09-28: *"way better to inspect the task by having its contents drop down like an accordion. I should also be able to manage state using standard tools available from the framework."* | +| **Smaller, and rejected** | The accordion alone. Fixes the read, leaves "manage state" for later, and Jake asked for both | +| **Bigger, and not this issue's** | A free-form record editor ([D1](DECISIONS.md#d1)) · rows changed by other sessions going live (FIX-1506) · a person-side pickup screen for escalations (FIX-1591) | +| **Not done if** | The row actions exist but only a hand-wired lab flow has any · the result shows only after a reload · the expanded row still overflows the pane at 1280 · a refusal (`declined`, illegal transition) reads as success | + +```mermaid +flowchart LR + L["multi-seat-collab hire · no model · shipped DevTool"] --> R["Tasks tab · 1280 wide · row collapsed"] + R -->|"status and reason in view"| E["expand the parked row"] + E -->|"every ledger field readable in the pane"| A["run an action from the row"] + A -->|"ledger changed · row shows it · no reload"| P["PASS"] + C["control · main, or channel-actions-off"] -.-> R + A -.->|"under a control"| F["must FAIL · names its leg"] +``` + +The check reads the screen against the ledger, never the ledger alone. + +| How we verify | | +|---|---| +| **Goal check** | `goals/devtool-workforce-visibility/works-a-task-from-its-row/`, new. Chromium, shipped DevTool bundle, the `multi-seat-collab` hire, no model. The implementer runs it; verdict in the PR | +| **Signal** | **read**: collapsed, the parked row's status and ≥40px of its reason in view at 1280×800; expanded, every field the ledger holds is in the row and nothing overflows the pane. **answer**: the seat's own `answer` action is offered on the parked row with its id filled; after submit the ledger row has left `parked` and the row's status matches, no reload. **tool**: on the channel's session, a board task-tool action run from a row changes the ledger and the row. **refuse**: the same tool on a settled row shows the refusal on the row; the ledger is unchanged | +| **Input** | The lab's held-out fixture question. A different question, or a different settled row, must pass too | +| **Anti-game** | No reading the store for what the screen should show, no URL typed by hand, no reload before the last leg, no row found by text alone (read by task id) | +| **Control that must fail** | Today's `main`: read, answer and tool. `GOAL_CONTROL=channel-actions-off` (the lab's channel does not opt in): tool and refuse only | + +## What changes + +![Two panels. Left, today: a task table whose Details expander floats a clipped JSON block over the rows. Right, after: the same row opened in place, fields listed with the full goal wrapped, the raw JSON folded underneath, and an Actions strip offering cancelTask, updateTask and answer with the task id already filled. Below, the path an action takes: the row, the flow's action, the task tool, the ledger, and the change item that updates the row](figures/what-changes.svg) + +The row opens in place; the actions strip is the only way to change the task, and each button is +an ordinary flow action. + +**What a flow author writes to get the ready-made set** (illustrative): + +```diff + defineFlow({ + kind: "ops", + resources: { [todos.id]: todos }, + actions: { + drain: { block: board.drain }, ++ ...taskToolActions(board), // addTask_todos, cancelTask_todos, updateTask_todos, … + }, + }); +``` + +**And on a Workforce channel**, off by default: + +```diff + # workforce/teams/support/channels/help/CHANNEL.md + members: [support.devices, support.accounts, support.fsd, support.general] + boards: [escalations] ++boardActions: true +``` + +## How a row action reaches the ledger + +```mermaid +flowchart LR + T["Tasks tab row"] -->|"action name + taskId"| X["existing action dispatch"] + X --> F["flow action"] + F --> H["task tool handler"] + H -->|"guarded verb"| G["task ledger"] + H -->|"result in the request's root trace"| T + G -->|"task-change item"| T +``` + +No new route, no new verb. The tab calls actions the way the action bar already does; the tools +call the same guarded verbs a worker's model calls. The dispatch answers with a request id and +no output, and a refused verb writes nothing, so the row reads the tool's own `{ ok, error }` +from the root trace of the request it dispatched ([BR-15](BUSINESS-RULES.md)). + +## What stays as it is + +- Engine and core: no route, no type. The Resources panel stays read-only. +- The task verbs and their guards. A refusal is the verb's own. +- Who may reach an action: the flow's public `actions` map, as today. +- The Reason rule from FIX-1481: shown whenever `feedback` is present, verbatim ([Evolution](EVOLUTION.md)). + +## Sign off + +**[The goal](#the-goal-and-how-well-know-its-met), at that size:** read and change a task from +its row, proved on a live hire. If wrong: we ship an accordion and call the "manage" half done. + +1. **[D1](DECISIONS.md#d1) · A task changes only through the flow's actions; the ready-made + ones are the eight task tools. No record editor, no DevTool-only route.** If wrong: you + wanted to hand-edit fields; that needs an engine write that skips the task guards. + +**Open: one** — [should the reference app's `support.help` turn its escalation actions on now?](DECISIONS.md#open) +It is the one to weigh. diff --git a/specs/issues/FIX-1629/figures/d1-actions-not-edits.svg b/specs/issues/FIX-1629/figures/d1-actions-not-edits.svg new file mode 100644 index 0000000000..e45085b46b --- /dev/null +++ b/specs/issues/FIX-1629/figures/d1-actions-not-edits.svg @@ -0,0 +1,96 @@ + + + + + + D1 · THE CALL + How does the DevTool change a task? + + + + CHOSEN + The flow’s actions · eight task tools + + INSTEAD OF + Edit the record as JSON + + + + + THE TASK + GUARDS + ▸ DECIDES IT + + + Every change is a checked move + a settled task refuses, as for a worker + − + Writes past every check + a cancelled task can be set back to pending + + + WHAT YOU + CAN CHANGE + − + Only what a verb allows + and only if the flow exposes the actions + + + Any field, any value + goal, attempts, revision included + + + + LAYERS + + + + No engine change + the action path already exists + − + A new engine write route + the DevTool-only path we ruled out + + + + + LOCKS IN + The DevTool does what the flow exposes + fields no verb writes stay read-only here + + + + FLIPS IF + You need to edit fields no verb writes + then an editor, with a guard decision, is its own issue + + diff --git a/specs/issues/FIX-1629/figures/open-support-help-actions.svg b/specs/issues/FIX-1629/figures/open-support-help-actions.svg new file mode 100644 index 0000000000..16383d32c7 --- /dev/null +++ b/specs/issues/FIX-1629/figures/open-support-help-actions.svg @@ -0,0 +1,96 @@ + + + + + + OPEN · THE FORK + Should support.help turn its escalation actions on now? + + + + RECOMMENDED + On now + + INSTEAD OF + Off until FIX-1591 decides + + + + + THE BOARD IN + YOUR SCREENSHOT + ▸ DECIDES IT + + + Manageable from the tab + cancel, re-prioritize, complete a case + − + Still read-only + the feature shows only on the lab hire + + + WHO CAN + CHANGE A CASE + − + Any caller of the channel + even a case a seat is working · demo, no users + + + Nobody from outside + as today + + + + THE FIX-1591 + HOLD + = + Not decided by this + nothing drains; no person-side screen + = + Untouched + as today + + + + + LOCKS IN + One line in the reference app + revert it and nothing else moves + + + + FLIPS IF + The demo is meant to show an unattended board + then off, and the warning stays the point + + diff --git a/specs/issues/FIX-1629/figures/what-changes.svg b/specs/issues/FIX-1629/figures/what-changes.svg new file mode 100644 index 0000000000..98b7ffca4c --- /dev/null +++ b/specs/issues/FIX-1629/figures/what-changes.svg @@ -0,0 +1,86 @@ + + + + + + TODAY + + ID · GOAL · STATUS · ASSIGNEE · RUN · KIND · DETAILS + + task_…c5775d devuser is asking to speak wi… pending + + { "revisio + "goal": "d + "status" + "metadat + floats over rows, + clipped at the pane + + task_…1e94d4 devuser is requesting a new M… pending + no way to change a task · reason off screen at 1280 + + + + AFTER + + + ▾ pending devuser is asking to speak with a… + id task_mulhacg2_1_c5775d · attempts 0 · revision 1 + goal devuser is asking to speak with a real person + regarding their laptop issue … (wrapped, whole) + metadata author support.general · verified false + updated 2026-09-28 20:51 · created 20:51 + ▸ raw JSON + ACTIONS · taskId FILLED + + cancelTask_… + + updateTask_… + + answer + + ▸ pending devuser is requesting a new MacBo… + status first · reason in view at 1280 · no sideways scroll + + + + HOW A ROW ACTION REACHES THE LEDGER · NO NEW ROUTE, NO NEW VERB + + Tasks tab row + + existing dispatch + + flow action + + task tool · verb + + task ledger + + + tool result { ok, error } from the request's root trace · a refusal shows as a refusal + + task-change item · the row shows the new state + +