Skip to content

spec(FIX-1629): DevTool Tasks tab: inspect a task in an accordion row, and manage its state with the framework's standard tools - #2346

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-1629
Sep 28, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-1629

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 28, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Someone who… Today After
opens a task in the Tasks tab Raw JSON floats over the table, clipped at the pane edge The row opens in place, every field readable
reads why a row is parked, on a laptop Reason off screen below ~1500px (FIX-1523) Status and reason lead the row, in view at 1280
wants to cancel, re-prioritize or answer a task while debugging Can't from the tab Picks an action on the row, task id filled, result on the row
builds a flow with a board Nothing in the DevTool changes task state Any action taking a taskId shows on the row; the ready-made set is the eight task tools, for boards whose tasks outlive a request
runs a Workforce channel in production fileTask / readBoard only Unchanged unless the channel opts in

Goal: 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 without a reload.

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"]
Loading

The check reads the screen against the ledger. Check: goals/devtool-workforce-visibility/works-a-task-from-its-row/, no model; today's main must fail read/answer/tool, GOAL_CONTROL=channel-actions-off must fail tool/refuse only.

Today a floating clipped JSON block; after, the row opens in place with its fields, folded raw JSON and an Actions strip with the task id filled; below, row to dispatch to flow action to task tool to ledger; the tool's result comes back from the request's root trace and the change item updates the row

The row opens in place; its actions strip is the only way to change a task, and each button is an ordinary flow action.

How: the tab lists the viewed flow's actions that take a taskId and runs them through the dispatch the action bar already uses. It reads each result from the dispatched request's root trace, so a refusal shows as one. Orchestration adds taskToolActions(board) (the eight task tools as actions); Workforce channels opt in with boardActions: true. No engine or core change.

Sign off

Open · Should the reference app's support.help turn its escalation actions on now?

Open fork trade-off; on now, recommended, against off until FIX-1591 decides; it comes down to your screenshot's board

  • Plain terms: channels get an off-by-default switch exposing their boards' task tools as actions. On for support.help makes your screenshot's board manageable; it also lets any caller of that channel cancel/complete/reassign an escalation, including one a seat is working on right now (that seat's own result is then refused). FIX-1591 (who attends escalations) is parked on you.
  • Trade-off: on = the feature works on the board you use; off = nothing pre-empts FIX-1591, but that board stays read-only in the tab.
  • Recommendation: on now. Demo board, no production users, one line to revert. Nothing drains it and no person-side screen is built, so FIX-1591's question stays open.
  • Would change my mind: if the demo is meant to show "nobody works this board" as the point of the unattended-board warning.
  • If wrong: on → revert one line; off → the tab stays read-only on your main board until a follow-up.

The goal, at that size. If wrong: we ship an accordion and call the "manage" half done.

A task changes only through the flow's actions; the ready-made set is the eight task tools. No record editor, no DevTool-only route · D1

Trade-off figure: d1-actions-not-edits.svg

It comes down to the task guards: an editor writes rows the verbs would refuse. If wrong: you wanted to hand-edit fields (goal, attempts); that needs an engine write route that skips the guards.

The open fork is the one to weigh. Reasoning: DECISIONS.md · cases: BUSINESS-RULES.md.

Reviewers · look here

  • Plan → S5/S6. Is one orchestration export plus a Workforce opt-in the right layering, with nothing in engine/core?
  • Decisions → "Decided, not asked", action matching. Is "public action whose input requires a string taskId, scoped by name suffix" a sound, generic signal?
  • Evolution. FIX-1481's reason rules retained; its table/expander rules amended. Anything lost?

Not here: rows changed by other sessions going live (FIX-1506); a person-side pickup screen for escalations (FIX-1591).

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1629 · absorbs FIX-1523 · builds on FIX-1481, FIX-1497 · no epic · merges after human approval and required checks

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing the shape of the proposed solution. It is knowingly incomplete, is not real code,
    and is not what will ship. Review it for directional viability only. Do not report
    that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
    wouldn't build: all of that is true on purpose.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it
will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

🤖 Generated with Claude Code

https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N


Generated by Claude Code

Retained spec set: rows expand in place; tasks change only through the
flow's own actions, with the eight task tools as the ready-made set
(taskToolActions) and a Workforce channel opt-in. Absorbs FIX-1523.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N
@jhoffner jhoffner added the spec label Sep 28, 2026 — with Claude
@jhoffner jhoffner self-assigned this Sep 28, 2026
@vercel

vercel Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 28, 2026 9:20pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 28, 2026 9:20pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 28, 2026 9:20pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-28T21:15:25.518934Z 44b08aa PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@linear-code

linear-code Bot commented Sep 28, 2026

Copy link
Copy Markdown

FIX-1629

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass on FIX-1629 (spec)

The direction holds. Actions-not-edits (D1) is the right call and the layering (no engine or core change) checks out against the code. I found one gap that can break the headline goal, one exposure question, and two scoping points. Findings are ranked; the first two should be settled before implementation.

1. BR-15 has no data path today (correctness, blocks the goal)

BR-15 and the "Not done if: a refusal reads as success" line need the row to show a tool's { ok: false, error }. But sendAction resolves to ExecuteActionResponse (packages/client/src/types/index.ts:92): status, request, session, error. It carries no action output. handleSendAction (DevToolPanel.tsx:494) also discards everything except request.id. A declined cancelTask_x returns HTTP 200 with status: "completed", so capturing "the dispatch result (response or thrown error)" (S4) will show it as success, the exact failure the spec says it must not have.

The refusal only exists as the handler's output item on the request's stream. The spec should name where the row reads it (the item for dispatchedRequestId, matched by action name) and add it to S4 and C5. C5 should assert against a declined result, not just a thrown error. Also confirm that item is emitted for a handler used as an action root (C0 covers running it, not that its output surfaces).

2. Claim-less completes on claimed rows (BP-031 / BP-035)

withTask reads the claim ticket from the worker scope (currentWorkerClaim()); outside a worker it is undefined. D1 says "a lost claim refuses", but that guard depends on the ticket. The spec doesn't say what completeTask/failTask/blockTask do from an action against a running row owned by a live worker. It could refuse, or it could let a debugger settle over the worker. Add this to BR-18 and C1 as an explicit, tested outcome. If it lets the write through, the DevTool becomes a way to steal a claim, and boardActions on a production channel exposes that to any caller. That strengthens keeping it off by default, and it should shape how the support.help fork is worded.

3. Scope: consider two PRs (restraint)

The plan is one "medium" PR touching devtool, orchestration, workforce, kitchen-sink, the lab, three goal checks and docs. The spec's own sequence shows the accordion (S1, S2, S10, FIX-1523) and the actions (S3–S9) are independent. The accordion is low-risk and fixes what the user actually saw. The actions carry the exposure and the BR-15 unknown. Splitting gets FIX-1523 closed early and keeps the risky half reviewable on its own. I'd recommend it. If you keep one PR, land the accordion commit first so a revert of the actions half is clean.

4. Copy/behavior mismatch: the row will show six of the eight

addTask and listTasks don't take taskId, so BR-9's qualifier drops them. The row offers assignTask, completeTask, failTask, blockTask, cancelTask, updateTask. The spec (Sign off, DOCS, figure) says "the eight task tools" on the row. Say "eight actions; the six that name a task appear on rows" so the goal check and docs don't assert eight.

5. Third copy of the suffix rule (minor)

S5 moves boardToolSuffix (channel-board.ts:324) into orchestration as taskToolSuffix, good. S3 then re-mirrors it inside devtool. That is defensible (devtool mirrors wire shapes), but it is the one place a rename silently breaks scoping. 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.

Alternatives considered, not recommended

  • Skip the Workforce opt-in and prove on the lab only. Leaner, but the user's own screenshot (support.help) then stays read-only, so it misses the stated need. The opt-in is small once taskToolActions exists.
  • Match actions by tool identity instead of a taskId input. Rejected in the spec, correctly; the schema-based signal also catches app-owned answer.

No changes needed to the open fork's recommendation, subject to item 2.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Simplification review (spec only)

Verdict: The direction holds up. D1 (mutate only through flow actions, ready-made eight task tools) is the simpler system shape than a DevTool record editor or an engine debug route, and it matches how fileTask / readBoard already reach the panel. The accordion half reuses existing devtool disclosure patterns (chevron toggles, not a new Radix Accordion dep). I would not swap the whole approach for accordion-only or a hand-maintained action name list.

Where complexity creeps in anyway (worth tightening in the spec before implement, not blocking direction):

  1. Two homes for suffix scoping — taskToolSuffix in orchestration plus taskActionsFor that "mirrors locally" in devtool. That is intentional package-boundary hygiene, but it is the main drift risk in this PR. Prefer either a one-line exported helper both sides call (if a dependency is acceptable), or a single normative sentence + shared test vectors in C3 that pin the mirror invariant.

  2. internal.actions spread for boardActions (S6) — DevTool row qualification is public actions only (BR-9). Duplicating eight tools into internal.actions follows today's fileTask/readBoard mirror, but nothing in the spec names an internal caller for cancelTask_*. If the mirror is only for consistency, say so in one sentence; if not needed, dropping internal spread would shrink the action catalog and C2 snapshots with no UX loss.

  3. C0 is a real fork — If task-tool handlers are not valid action roots, S5 becomes eight wrapper sequencers. Either cite an existing handler-as-action precedent in the plan or move the premise check to a pre-implementation note with an explicit fallback shape so implementer is not inventing wrappers under VG pressure.

  4. BR-4 vs BR-5 — The expanded field laundry list will churn on every ledger field. BR-5 already guarantees complete JSON; consider softening BR-4 to "structured view covers the task type's known fields; completeness = folded JSON" unless you explicitly want spec churn on schema growth.

  5. Implement-time performance (not spec blockers) — Memoize taskActionsFor once per (flow, collectionId), not per row; lazy-mount JsonViewer on expand/stream ticks. Worth one guardrail line in PLAN so review does not rediscover this.

  6. UX noise (optional follow-up) — Listing all eight tools on every row (including listTasks / addTask) is honest per D1 but noisy; the spec already rejects a fixed eight-name filter. Fine to ship; call out in Evolution if you want permission to hide non-row verbs later without breaking BR-9.

Skipped / product-owned: support.help open fork (recommendation in spec is reasonable for a demo channel); splitting into accordion PR then actions PR (correctly rejected vs Jake's ask).

Docs: DOCS draft is appropriately scoped; implementer still runs docs-writer/docs-editor per DOCS.md.

Direction approved; inline notes are spec polish, not a different architecture.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1629/SPEC.md Resolved
Comment thread specs/issues/FIX-1629/PLAN.md Resolved
Comment thread specs/issues/FIX-1629/PLAN.md Resolved
Comment thread specs/issues/FIX-1629/PLAN.md Resolved
Comment thread specs/issues/FIX-1629/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1629/DECISIONS.md Resolved
Round 1 of spec review: nothing folded; four below-the-bar notes recorded
under PLAN.md > Notes from review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 44b08aa00b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-1629/PLAN.md Resolved
Comment thread specs/issues/FIX-1629/PLAN.md Resolved
Comment thread specs/issues/FIX-1629/PLAN.md Resolved
Comment thread specs/issues/FIX-1629/PLAN.md Resolved
…rable boards, channel fence)

- BR-15 reads the tool's { ok, error } from the dispatched request's root
  block_trace; the dispatch response and change items carry no refusal.
- BR-25: an action's settlement runs claimless, as a coordinator's does,
  and overrides a live worker's claim; the worker's result declines lost-claim.
- BR-17: taskToolActions refuses request/sequencer-backed boards.
- BR-26: channel board actions refuse any session but their channel's.
- BR-10/S3: matcher takes every listed board's suffix.
- One PR recorded as decided; review notes added to PLAN.

Re-draft: PLAN.md baseline 989 prose words (44b08aa)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: fix-1629-spec-review-r2
kind: reply

Re the second look (comment). Folded in 6fbe1b4.

  1. BR-15 data path: folded. Confirmed in code: the action POST returns a 202 handle (or SSE), ExecuteActionResponse has no output, and a refused verb writes nothing, so no change item either. The one place the tool's { ok, error } exists is the root block_trace of the dispatched request. A handler root emits inline output there, and the DevTool already reads traces. BR-15, S4 and C5 now read it there, matched by the request id handleSendAction gets back. C5 asserts a declined 2xx result, not only a thrown error. C0 now also checks that the root trace of a handler-rooted action carries its output. Traces are gated by isTraceObservabilityEnabled() (on outside production). With traces off, the row says the outcome isn't visible and never reports success.
  2. Claimless completes: decided, the action overrides. Verified: withTask reads currentWorkerClaim(), which is undefined outside a worker. claimGuard(undefined) then passes no claim, which the collection documents as the coordinator posture: no ownership check, legal transitions only. So today an action's completeTask/failTask/blockTask/cancelTask on an in_progress row lands, and the holding worker's own settlement later declines lost-claim. I kept that behaviour and made it a rule (BR-25, C1, DECISIONS). Clearing a stuck row is the debugging job this feature exists for, and refusing would need a new substrate guard. The sign-off wording now says it plainly: any caller of the channel can settle an escalation, "including one a seat is working on right now (that seat's own result is then refused)". Same change in the fork's figure and DOCS. The recommendation stays on.
  3. Two PRs: decided, one PR. Jake asked for both halves together and Cursor's review agreed. Recorded in DECISIONS → Decided, not asked. Landing the accordion commit first is in the implementer notes.
  4. Six of eight: fixed inline. BR-9 and the decided list say a row offers six (addTask and listTasks take no taskId). "Eight actions" stays where it means the action set.
  5. Suffix-mirror pin test: recorded verbatim in PLAN.md → Notes from review.

Codex's four threads are also folded in this commit. Replies are on each thread.


Generated by Claude Code

@jhoffner
jhoffner merged commit 2d05106 into main Sep 28, 2026
12 checks passed
@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect — owner lock (Jake)

  • Approach: yes
  • D1: yes — task changes only through the flow’s actions / eight task tools; no record editor, no DevTool-only route.
  • Open fork: on now — reference app support.help sets boardActions: true. Demo board; one-line revert; does not decide FIX-1591.

Soft: FIX-1506 / FIX-1622 BoardList stay out of this tab.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants