feat(stagecraft): the studio's Board view, view addresses, and the work item's title (swamp-club #2943) #438

Merged

seth merged 3 commits from cue/2943-stagecraft-studio-board into main

2026-10-02 15:24:07 +00:00

seth commented

2026-10-02 15:03:02 +00:00

Owner

Adds the studio's Board view (swamp-club #2943), plus the work-item title in the run record. The Board shows every work item of a factory in a column for its stage, and the cards move as the agent advances them.

What changed

Board
- One column per stage, in the order Design mode draws them. A stage the current definition no longer has gets its own column at the end. Finished stages show only a count until Show finished is ticked.
- Each card shows the title (else the key), the ticket, time in stage, and the cycle when above 1. Badges, written in words as well as colour, mark three states:
  - waiting on a person, from the stage's last awaiting event;
  - parked, at the dispatch cap, or by a cycle limit (an exit whose gates all pass but whose target stage is at its limit);
  - stale pin, meaning the item is pinned to another definition.
- Filters for those three states, and a search on key and title. Each column shows 50 cards, then Show more.
- Each column is one tab stop with arrow-key navigation, and a card links to /w/<key>.
Reads go through swamp's data query (ctx.queryData, studio_work_items.ts), so the Board works with any datastore.
- One query reads the factory's run records and one reads their pinned definitions, each checked by digest.
- A read-only store runs the gate checks that a cycle-limit park needs.
- Every predicate value passes safePart.
Route: GET /api/work-items?factory=<name>.
Live updates by poll. While a board is open, serve reads each work item's run-record version every 3 s and sends a work-items event when one changes.
- A file watch can't follow records in S3 or GCS, so it polls instead.
- The page reads the board again every 2 minutes, and when a hidden tab comes back, so the poll stays alive.
Addresses: each view has its own path: /f/<factory>/{design,simulate,board}, plus /w/<key> for #2944's work-item page. The page routes by path (route.ts).
Title: the run record keeps an optional title (schemaVersion stays 1). start takes it, and the start commands that claim and new_key print include it.
Shared helpers: safePart, recordObject and shellQuote moved into work_item_ops.ts.
Docs: README, REFERENCE, DESIGN (with a decision entry) and the skill's driving, authoring and getting-started references.

No model versions are bumped, because stagecraft has never been published. #2944 builds on this branch's router, read helper and title. Whichever PR merges second rebases onto the other.

Testing

Unit: 845 tests pass, covering the read helper, cards, poll, route, router, board layout, and title storage and quoting. One test checks that the page's definition digest equals the engine's pin digest.
Integration: integration/engine/studio_board_test.ts runs on real swamp. It covers items that are waiting, parked both ways, on a stale pin, and with and without a title, plus the work-items event after an advance. The full suite (53 tests) passes.
Headless Chromium:
- routing, filters and arrow keys;
- a card moving live within one poll;
- back and forward, and opening a card;
- every text element at 5.58:1 contrast or better.
Manual: Seth checked the board on a test repo.
Verification: verify-build and verify-reviews passed on 691e8b7c8 (12/14 steps, 2 skipped). Attestation ff140fda.

🤖 Generated with Claude Code

Adds the studio's **Board** view (swamp-club #2943), plus the work-item title in the run record. The Board shows every work item of a factory in a column for its stage, and the cards move as the agent advances them. ## What changed - **Board** - One column per stage, in the order Design mode draws them. A stage the current definition no longer has gets its own column at the end. Finished stages show only a count until **Show finished** is ticked. - Each card shows the title (else the key), the ticket, time in stage, and the cycle when above 1. Badges, written in words as well as colour, mark three states: - **waiting on a person**, from the stage's last `awaiting` event; - **parked**, at the dispatch cap, or by a cycle limit (an exit whose gates all pass but whose target stage is at its limit); - **stale pin**, meaning the item is pinned to another definition. - Filters for those three states, and a search on key and title. Each column shows 50 cards, then **Show more**. - Each column is one tab stop with arrow-key navigation, and a card links to `/w/<key>`. - **Reads go through swamp's data query** (`ctx.queryData`, `studio_work_items.ts`), so the Board works with any datastore. - One query reads the factory's run records and one reads their pinned definitions, each checked by digest. - A read-only store runs the gate checks that a cycle-limit park needs. - Every predicate value passes `safePart`. - **Route:** `GET /api/work-items?factory=<name>`. - **Live updates by poll.** While a board is open, `serve` reads each work item's run-record version every 3 s and sends a `work-items` event when one changes. - A file watch can't follow records in S3 or GCS, so it polls instead. - The page reads the board again every 2 minutes, and when a hidden tab comes back, so the poll stays alive. - **Addresses:** each view has its own path: `/f/<factory>/{design,simulate,board}`, plus `/w/<key>` for #2944's work-item page. The page routes by path (`route.ts`). - **Title:** the run record keeps an optional `title` (`schemaVersion` stays 1). `start` takes it, and the start commands that `claim` and `new_key` print include it. - **Shared helpers:** `safePart`, `recordObject` and `shellQuote` moved into `work_item_ops.ts`. - **Docs:** README, REFERENCE, DESIGN (with a decision entry) and the skill's driving, authoring and getting-started references. No model versions are bumped, because stagecraft has never been published. #2944 builds on this branch's router, read helper and title. Whichever PR merges second rebases onto the other. ## Testing - **Unit:** 845 tests pass, covering the read helper, cards, poll, route, router, board layout, and title storage and quoting. One test checks that the page's definition digest equals the engine's pin digest. - **Integration:** `integration/engine/studio_board_test.ts` runs on real swamp. It covers items that are waiting, parked both ways, on a stale pin, and with and without a title, plus the `work-items` event after an advance. The full suite (53 tests) passes. - **Headless Chromium:** - routing, filters and arrow keys; - a card moving live within one poll; - back and forward, and opening a card; - every text element at 5.58:1 contrast or better. - **Manual:** Seth checked the board on a test repo. - **Verification:** verify-build and verify-reviews passed on 691e8b7c8 (12/14 steps, 2 skipped). Attestation ff140fda. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

seth added 3 commits

2026-10-02 15:03:03 +00:00

feat(stagecraft): studio routing, work-item reads and the run record's title (swamp-club #2943 ) 5b7c2e5b32

The shared base for the Board view (#2943) and the work-item page (#2944):

- The run record keeps the work's title (optional, schemaVersion 1);
  work-item start takes a title input; claim's and new_key's start
  commands carry it, shell-quoted.
- studio_work_items.ts reads work items through the method context's
  queryData: run records of a factory, their pinned definitions (by
  digest, with the exact-version fallback), a read-only RunStore, the
  board's cards (waiting, dispatch-cap and cycle-limit parks, time in
  stage), and a version-only poll that tells the page of changes.
- GET /api/work-items?factory=<name>; the page is served on
  /f/<factory>/{design,simulate,board} and /w/<key>; a work-items event.
- safePart, recordObject and shellQuote are shared engine helpers.
- The page routes by path (route.ts), with a Board tab and view.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

feat(stagecraft): the studio's Board view, with its docs and integration test (swamp-club #2943 ) 461b2b6f57

The Board shows every work item of a factory in a column for its stage, in
Design mode's order, with a trailing column for a stage the current
definition lacks and finished stages counted until Show finished. Cards
show the title, ticket, time in stage, cycle, waiting on a person, parks
(dispatch cap and cycle limit) and a stale pin, in words as well as
colour; filters and search narrow them, and a column shows 50 cards at a
time. Each column is one tab stop with arrow-key movement; a card is a
link to /w/<key>. The page re-reads the board every two minutes and on
returning to a hidden tab, which keeps the server's poll alive.

integration/engine/studio_board_test.ts proves the route on real swamp:
the data-query predicate, latest-only reads, the list projection, each
card state, and the work-items event after an advance. README, REFERENCE,
DESIGN (with a decision entry) and the skill describe the Board, the view
addresses and start's title.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

fix(stagecraft): the Board survives a poll that cannot start, and other review findings (swamp-club #2943 )

CI / Review Integrity (pull_request) Successful in 1m15s

Details

CI / Validate Attestation (pull_request) Successful in 1m16s

Details

691e8b7c85

- A poll whose first read fails no longer fails the board read; live
  updates degrade and the page's next read asks again.
- With no definition loaded, the board's columns are the cards' own
  stages and none is called "not in the current definition".
- queryStore takes the newest version when a query gives several.
- FACTORY_VIEWS lives once, in studio_cards.ts, shared by the server's
  page paths and the page's router; a test pins that they agree.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

seth merged commit 2bc9313e4e into main

2026-10-02 15:24:07 +00:00

seth referenced this pull request from a commit

2026-10-02 15:24:09 +00:00

feat(stagecraft): the studio's Board view, view addresses, and the work item's title (swamp-club #2943) (#438)

seth deleted branch cue/2943-stagecraft-studio-board

2026-10-02 15:24:09 +00:00