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
51 changes: 35 additions & 16 deletions specs/issues/FIX-1664/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,50 +12,69 @@ names the kind of check the plan runs.
|---|---|---|---|
| BR-1 | A task is opened from Tasks, a board card, or a workstream's task list | FIX-1662's task route shows this issue's header, the four tabs and the inspector in the right panel's slot; the tab is in the URL | Goal check |
| BR-2 | The route names a board or task the Lab doesn't hold | A named state saying no such task on that board; no other read is made | CI |
| BR-3 | The task has never been claimed | Session says the task hasn't started; Interrupt is disabled with *nothing is running*; the inspector shows the row's fields and dashes | CI |
| BR-4 | The header renders | Title (or goal), the row's status word, elapsed time from the row's start while it runs, the worker, and the harness per BR-18. No branch | Goal check |
| BR-3 | The row names no run: never claimed, handed off but not yet started in its session, or stored before the [task-run link](PLAN.md#the-task-run-link) existed | Session says no run has started for this task; Interrupt is disabled with *nothing is running*; the inspector shows the row's fields. The screen updates when the row does; it never looks for a run any other way | CI |
| BR-4 | The header renders | Title (or goal), the row's status word, elapsed time from the row's start while it runs, and the worker. No harness (a gap, BR-18) and no branch | Goal check |

## The Session

| # | When | Then | Proved by |
|---|---|---|---|
| BR-5 | The task has a run | The Session is the items of the child session keyed on this board and this task, in stored order, drawn by the registry components; one live stream for it while the tab is open | Goal check under `worker-session` |
| BR-5 | The row names a run | The Session is the items of the session the row's link names, in stored order, drawn by the registry components; one live stream for it, open only while the Session tab is | Goal check under `worker-session` |
| BR-6 | The run stores a new item | It appears with no reload | Goal check |
| BR-7 | The task ran more than once | Every attempt's items, in order, in the one session | CI |
| BR-8 | The board's seat keys sessions per worker or by a custom key | The Session shows that shared session whole, with a line saying it holds other tasks' work too; it never filters by guess | CI |
| BR-7 | The task ran more than once | Every attempt the named session holds, in order. An earlier attempt that ran in another session (a re-drain from another conversation, or a custom key) isn't shown; the header says which attempt is showing | CI |
| BR-8 | The named session is shared with other tasks (a per-worker or custom session policy) | The Session shows only the items stamped with this task's id, with a line saying the session is shared. It never shows the whole session as this task's, and never filters by time or order | CI |
| BR-9 | The run's session exists but the caller's principal can't reach it | A named state saying the run isn't visible to this user; no fallback to another session | CI |
| BR-10 | The row is parked | The Session shows the log and the row's reason; the ask is answered from Inbox (FIX-1662), and the task screen links there | CI |

## Controls

| # | When | Then | Proved by |
|---|---|---|---|
| BR-11 | Interrupt is pressed, or Esc with the Session focused | The run's in-progress request gets the shipped abort. The view shows *interrupted* only after that request reads `aborted` | Goal check under `optimistic-interrupt` |
| BR-11 | Interrupt is pressed, or Esc with the Session focused | The request the row's link names gets the shipped abort. The view shows *interrupted* only after that request reads `aborted` | Goal check under `optimistic-interrupt` |
| BR-12 | The abort answers that the request already finished | The view refreshes to what the request and row say; nothing is drawn as interrupted | CI |
| BR-13 | The abort is refused or fails | The error shows by the button; the run is drawn as still running | CI |
| BR-14 | The run was interrupted | App Lab writes nothing to the row; its next status is whatever the board records | CI |
| BR-15 | Hand off, reassign or Open PR is shown | Disabled, with a line naming FIX-1651 and what arrives | CI |
| BR-16 | The composer is shown | Disabled, with a line naming the operation from [the open fork](DECISIONS.md#open), or FIX-1652 if the fork goes the other way. *Also post to the workstream* is disabled with it | CI |
| BR-15 | Hand off, reassign or Open PR is shown | Disabled, with a line naming what arrives and its owner from the [registry](#gap-registry) | CI |
| BR-16 | The composer is shown | Disabled, with its owner line from the [registry](#gap-registry), which follows [the open fork](DECISIONS.md#open). *Also post to the workstream* is disabled with it | CI |

## Tabs and the inspector

| # | When | Then | Proved by |
|---|---|---|---|
| BR-17 | Diff or Checks opens | A named empty state naming FIX-1651; the tab label carries no count | CI |
| BR-18 | The inspector renders | Worker and team from the inventory; harness from the run's reported handle, else a dash naming FIX-1652; started from the row; tokens and cost from the reported handle, else a dash, with *estimated* when the harness estimated | Goal check |
| BR-17 | Diff or Checks opens | A named empty state with its owner from the [registry](#gap-registry); the tab label carries no count | CI |
| BR-18 | The inspector renders | Worker and team from the inventory; started from the row. Harness, tokens and cost are one named gap ([registry](#gap-registry)): no shipped read gives a client what the run reported | Goal check |
| BR-19 | The run recorded a plan or file operations | The plan lists its steps with their status; files list path and created or edited | CI, against a seeded record |
| BR-20 | The run recorded neither | Each section says this harness records none | Goal check (the stub records none) |
| BR-21 | Acceptance criteria and *review by* render | Named gaps naming FIX-1651 | CI |
| BR-20 | The run recorded neither | Each section says this harness records none ([registry](#gap-registry)) | Goal check (the stub records none) |
| BR-21 | Acceptance criteria and *review by* render | Named gaps, owners from the [registry](#gap-registry) | CI |
| BR-22 | Linked renders | *After*: the row's dependencies. *Blocks*: rows on the same board that depend on it. Each opens its task | CI |
| BR-23 | The trace link is shown | It opens the devtool App Lab was started with, with the run's session id beside it; with no devtool given, it is disabled and says how to start one | CI |
| BR-24 | Brief opens | The row's title, goal, context and input, as stored; acceptance criteria per BR-21 | CI |

<a name="gap-registry"></a>
## Gap registry

**The one place each gap's owner is written.** Every disabled control, empty tab and empty
field on the task screen takes its owner line from this table, as a prop at the surface (ER-5);
SPEC, PLAN and DOCS point here rather than repeat it. When a gap's owner ships, or the open fork
is answered, this table changes and the rest follows.

| Gap on the task screen | Day one | Owner | Rules |
|---|---|---|---|
| Typing to the worker, and *also post to the workstream* | Disabled composer | The operation from [the open fork](DECISIONS.md#open) if filed, else FIX-1652 | BR-16 |
Comment thread
jhoffner marked this conversation as resolved.
Resolved
| Hand off, reassign, Open PR | Disabled | FIX-1651 | BR-15 |
| Diff, Checks | Empty tab, no count | FIX-1651 | BR-17 |
| Acceptance criteria, *review by* | Empty section | FIX-1651 | BR-21, BR-24 |
| Harness, tokens, cost | Empty field | FIX-1652 | BR-4, BR-18 |
| A harness that records no plan or files | A line saying so | FIX-1652 | BR-20 |

## Failure taxonomy

Nothing on the task screen is fatal. The row read failing shows the route's Retry; the run
lookup, the stream and each recorded collection failing degrade only their own tab or section
to Retry. Nothing retries on its own, and nothing is drawn from a guess or from App Lab's hope:
a state changes on screen when the store says it changed.
Nothing on the task screen is fatal. The row read failing shows the route's Retry; the
session read, the stream and each recorded collection failing degrade only their own tab or
section to Retry. A read that answers with a truncated page says *more than shown* with Retry;
App Lab never pages through a listing to find something. Nothing retries on its own, and
nothing is drawn from a guess or from App Lab's hope: a state changes on screen when the store
says it changed.

## Acceptance criteria this issue owns

Expand Down
39 changes: 28 additions & 11 deletions specs/issues/FIX-1664/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@ Two decisions and one open fork are the sign-off surface. The epic's D1 to D3 an

```mermaid
flowchart TD
I["FIX-1664"] --> D1["D1 · Session is the task's own run session"]
I["FIX-1664"] --> D1["D1 · Session is the run the task's row names"]
D1 -.->|"rejected · a chat, not the task"| X1["the worker's own conversation"]
D1 -.->|"rejected · display-only, ambiguous"| X1c["match the listing's topic to a rebuilt key"]
D1 -.->|"rejected · a new read in the engine"| X1b["a task transcript API"]
I --> D2["D2 · only Interrupt works"]
D2 -.->|"rejected · the board refuses it"| X2["reassign through the board's action"]
Expand Down Expand Up @@ -54,20 +55,24 @@ out when you needed it means the issue's first sentence, steer without a termina
It comes down to steering: without the operation, the task screen watches and stops, nothing more.

<a name="d1"></a>
## D1 · The Session tab is the task's own run session, found by its dispatch key, shown live
## D1 · The Session tab is the run the task's own row names, shown live

| | |
|---|---|
| **Instead of** | The assigned worker's own conversation session · a new "task transcript" read in the engine |
| **Because** | A handed-off row runs in a child session the dispatch seam keys on the board and the task, and the session listing already returns dispatch runs with that key. Reading it is reading what ships (ER-5), and the live stream FIX-1609 shipped (`useSession` with `live`) follows it with no reload. The worker's own conversation is where it talks, not where this task ran. A transcript read would be a second API over the item log, which the Architect named an invent-kill |
| **Locks in** | A task's screen is exactly one run's session. Every attempt of the task is in it, in order, because a per-task key re-enters the same child. A board whose seat uses a per-worker or custom session key shares one session across tasks; its Session tab says so rather than filtering by guess |
| **Instead of** | The assigned worker's own conversation session · rebuilding the dispatch key and matching it against the session listing's `topic` · a new "task transcript" read in the engine |
| **Because** | Only the run itself knows, for certain, which session it is in. A handed-off attempt enters its run session through the board's claim gate, whatever the seat's session policy and whichever conversation drained the board, so the gate is the one place that can write down *this task's attempt N is running in session S, request R*. Rebuilding the key from outside can't do that: the listing's `topic` is display-only, the run's session id also folds in the parent session and its lineage (so a re-drain from another conversation makes a second run with the same topic), and a per-worker or custom policy never produces a per-task key at all. So the association is **a small new field on the task row, stamped by the gate** in `@flow-state-dev/orchestration` (Layer 2, the substrate that already owns the row and the gate), filed as its own child of FIX-1649 under the epic's split trigger: [the task-run link](PLAN.md#the-task-run-link). The row already reaches App Lab through FIX-1662's board read, so the link arrives with it; the live stream FIX-1609 shipped (`useSession` with `live`) follows the session with no reload. The worker's own conversation is where it talks, not where this task ran. A transcript read would be a second API over the item log, which the Architect named an invent-kill |
| **Locks in** | A task's screen is the run its row names, and Interrupt aborts the request the row names. A session shared across tasks (a per-worker or custom policy) shows only the items stamped with this task's id, which every item a task's worker emits carries from the moment the gate marks the scope; the screen says the session is shared. **FIX-1664's build waits on the task-run link**; nothing in Core or Engine changes |

![D1: what does a task's Session tab show? The task's own run session, chosen, beside the worker's conversation. Decides it: what the person is told the task did. Price: a per-worker session shows other tasks too](figures/d1-run-session.svg)
![D1: what does a task's Session tab show? The run the task's row names, chosen, beside the worker's conversation. Decides it: what the person is told the task did. Price: one small field on the row, in the orchestration package, before the screen can be built](figures/d1-run-session.svg)

It comes down to truth about the task: the worker's chat can't say what this run did.
It comes down to truth about the task: only the run can say where it ran, so the run writes it down.

**What would change my mind:** FIX-1651 defining a task as something other than a board row a
seat runs. Then the key moves, and the tab stays.
seat runs. Then the link moves to whatever it runs, and the tab stays.

**If wrong:** one small orchestration field nobody else reads, and FIX-1664 a child issue later
than it would otherwise be. Getting the lookup wrong instead shows another task's work, or
aborts another task's run, as this one's.

<a name="d2"></a>
## D2 · Of the four controls only Interrupt works; Hand off, reassign and Open PR are disabled and name FIX-1651
Expand All @@ -92,8 +97,12 @@ the button calls it, with no change to the screen.
- **Brief is the row's own fields**; acceptance criteria are a named gap (FIX-1651).
Comment thread
jhoffner marked this conversation as resolved.
Resolved
- **The plan and files are what the harness recorded** on the run session (Claude Code records
both), else a line saying this harness records none. Files show created or edited, no line counts.
- **Started is the row's; tokens, cost and harness come from the run's reported handle**, a dash
until then, as FIX-1662's BR-7 draws harness. **Branch** has no client read and is omitted.
- **Started is the row's. Harness, tokens and cost are a named gap owned by FIX-1652.** The
run reports them in its return value, which the client never sees; a detached run keeps no
session-state log of it; and the harness manager's run record, which does hold them, is
deliberately not client-readable. No shipped read carries them, so the inspector says so
rather than drawing a dash that looks like *not reported yet* ([the gap registry](BUSINESS-RULES.md#gap-registry)).
**Branch** has no client read and is omitted.
- **Linked** is the row's dependencies and its dependents; *review by* names FIX-1651.
- **The trace link opens the devtool App Lab was started with** (`--devtool <url>`), with the
run's session id beside it: the devtool can't open a session from its address yet.
Expand All @@ -106,8 +115,11 @@ the button calls it, with no change to the screen.

| Alternative | Why not |
|---|---|
| Find the run through the harness manager's run record | Not client-readable by design; its read surface is a lab's own `status` action |
| Find the run through the harness manager's run record | Not client-readable by design; its read surface is a lab's own `status` action. It also covers only boards the harness manager runs, and keys by the lab's own topic, not board and task |
| Find the run through its parent session's children | The parent is the session that drained the board, which the client can't learn: the row's claim coordinate is server-only |
| Rebuild the dispatch key and match the session listing's `topic` (the approved draft) | `topic` is display-only; the run's id also folds in the parent session and lineage, so two runs can share a topic; a per-worker or custom policy never yields the per-task key. It can show or abort the wrong run, or find none |
| Expose the row's claim coordinate (`claimedBy`) | Server-only by design, and it names the session that **claimed** the row, which on a handed-off board is the drain's, not the run's: the child never claims |
| Publish the harness's tokens and cost through a new projection now | A second read of the same numbers, for three inspector fields, with no second consumer. FIX-1652 owns inspecting a run and can shape it once |
| Cancel the row as well as abort the run on Interrupt | A shell-written board change; what an interrupted row becomes is FIX-1651's |
| Fold the task level back into FIX-1662 (epic D1's mind-changer) | It reads a run session, a harness's records and a request, none of which the workstream level reads |

Expand All @@ -116,5 +128,10 @@ the button calls it, with no change to the screen.
- **Draft**: framed as watching and steering one run; the Session reads the task's own run
session; only Interrupt ships; the turn into a coding run found unshipped and put as the open
fork.
- **Amendment after merge** (review on PR #2428, Codex): the run lookup by rebuilt key and
`topic` was ambiguous and couldn't serve a shared session, so D1 now reads a link the gate
stamps on the row, split out as the task-run link; and harness, tokens and cost had no
client-readable source, so they became a named gap. The goal, D2 and the open fork are
unchanged.
Comment on lines +131 to +135

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Add the required evolution record for this amendment

This explicitly replaces an approved D1 after the original spec merged, but the directory still has no EVOLUTION.md. The retained-spec contract in docs/contributing/orchestration.md:711-728 requires that file when an earlier design is amended, including the precise predecessor anchors, disposition, evidence, replacement, and compatibility consequences; scattering only a short summary through the rewritten documents loses that required lineage.

Useful? React with 👍 / 👎.


**Open: one** — [above](#open).
15 changes: 9 additions & 6 deletions specs/issues/FIX-1664/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,17 @@ below, which differ from the epic's draft because the composer and Hand off don'
> ## A task
>
> Open a task from Tasks or from a card on a board. The Session tab is that task's own run:
> every step the worker takes, the tool calls and edits as they happen, and every earlier
> attempt above them. It isn't the worker's chat, so what you read is what this task did.
> every step the worker takes, the tool calls and edits as they happen, and earlier attempts
> above them when they ran in the same place. It isn't the worker's chat, so what you read is
> what this task did. If the worker keeps one session for several tasks, the tab shows only
> this task's steps and says the session is shared.
>
> **Interrupt** stops the run (Esc does the same). The screen says *interrupted* once the run
> has actually stopped. What happens to the task afterwards, whether it's retried or left, is up
> to the board, not App Lab.
>
> The panel on the right shows who is on it, which harness, when it started, and tokens and
> cost once the run reports them. If the harness records its plan and the files it touched, as
> The panel on the right shows who is on it and when it started. If the harness records its
> plan and the files it touched, as
> Claude Code does, they're listed; otherwise the panel says so. *Open trace* opens the devtool
> for the full detail. Tell App Lab where it runs:
>
Expand All @@ -47,13 +49,14 @@ below, which differ from the epic's draft because the composer and Hand off don'
> | Hand off, reassign, Open PR | Disabled | The eng workstream kit |
> | Diff and Checks | An empty tab saying so | The eng workstream kit |
> | Acceptance criteria, who reviews | An empty section | The eng workstream kit |
> | Which harness, tokens and cost | An empty field saying so | Attention and inspect |
> | A harness that records no plan | A line saying so | Attention and inspect |
>
> A board that hands work off keeps each task on the worker it was given to, which is why
> reassigning is off rather than refused.

The first row's *Filled in by* follows the open fork: the operation's issue by name if it is
filed, attention and inspect if not.
The table mirrors the [gap registry](BUSINESS-RULES.md#gap-registry), which is canonical; the
first row's *Filled in by* follows the open fork there.

## Voice watch-outs for the publisher

Expand Down
Loading
Loading