Skip to content

spec(FIX-1816): Ask, a hand-off that waits for its answer - #2900

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-1816
Oct 8, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-1816

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
builds a worker that must check with a colleague before it acts Files a task, and the turn stops. The answer comes back later as a new turn Asks. The turn waits, then continues with the real answer as the result of its call
asks a worker for a brief that its team writes Gets the brief in the same answer, from a skill's private team. FIX-1814 removes that team Gets the brief in the same answer: the lead asks the analyst, and the lead's answer carries the analyst's
runs Workforce on a server that restarts n/a A restart while a turn waits loses nothing. The work is filed one time
asks a colleague who never finishes n/a Gets a timeout error within twenty minutes, instead of waiting forever
watches the task list of the conversation Sees filed tasks only Also sees each ask as a task, marked as asked

Goal: a worker can ask a colleague on its roster and continue the same turn with the real answer of the colleague. A server restart during the wait loses nothing, and the work of the colleague is filed one time.

flowchart LR
  F["durable store · real model · Workforce over HTTP"] --> A["A, a chat turn, asks B · server killed while A waits"]
  A -->|"A's own turn ends with B's answer · one row · B completed once"| P["PASS · goal met"]
  C1["control · no-run-once"] -.->|"a second row · B runs twice"| X["must FAIL"]
  C2["control · no-waker"] -.->|"A stays suspended"| X
Loading

The check reads the stores after the run. Each control removes one half of "survives a restart, filed one time", and each control must fail. Check: goals/hand-offs/ask-survives-a-restart/, openai/gpt-5.4-mini, SQLite, controls GOAL_CONTROL=no-run-once and GOAL_CONTROL=no-waker. Why this goal and not a smaller one: SPEC.md.

Today a turn files a task and ends, and the ending of the task wakes a new turn. After, the turn files the same task as an ask and parks; the same ending resumes the parked turn with the answer

Same board, same row, same notice. Only one thing is new: the ending resumes the turn that parked, and does not wake a new turn.

How: addTask({ goal, assignee, waitForResponse: true }) files the task as usual, then parks the turn on the row. No new tool: the task tools stay eight. When the row ends, the notice of FIX-1794 arrives in the conversation. For an asked row, the server resumes the parked turn with the output of the row. The notice is the fast path; a resume-owed marker on the row replays any answer still unpaid after a restart. A colleague that never finishes is bounded by the durability sweeper, which resumes the turn with a timeout error.

Sign off

The goal, at that size: the same turn, across a real restart, filed one time. If wrong: an ask that works until the first deploy.

An ask is a task on the board of the asker, and its turn parks on that row · D1

D1 trade-off figure (opens the figure)

This is the one to weigh, and it is an epic-level change. It replaces the epic's L5 surface (awaitDispatch and resultOf) with a wait option on addTask, no new tool, no core export, so it binds only when the epic records it under ER-11. The option, not a separate askTask tool, is your review call, adopted.

It comes down to the count: the request-level wait adds a second signal and a third answer-once check.

Its price is a wait on another epic's PR. The ask goes live only when FIX-1794 P2 lands. If that slips, the goal slips with it, one for one; nothing here is reworked, and the tool is not offered to models until then, so nothing half-works. My recommendation: wait. The alternative, a stop-gap waker built here, is the second "child finished" signal the epic forbids (ER-7), and it would be torn out at the lift. What would change my mind: you need ask live before FIX-1794 P2 can land; then the stop-gap comes to the epic as an amendment. If wrong: ask arrives late, and works only where a conversation board exists.

Ask ships: the caller is a lead whose answer carries the results of its team · D2

Ask ships, chosen, beside stop and ship assign alone. Decides it: whether the request that asked carries the answer. Price: a second hand-off to keep correct

It comes down to the output of the request that asked: with assign, that output never carries the answer. If wrong: we keep a second hand-off for a need that assign could satisfy.

"Ask the delegate" stays a post · D3

It stays a post, chosen, beside it becomes an ask. Decides it: what the person sees. Price: the ledger token stays

It comes down to what the person sees: an ask puts the line of each delegate into one reply. If wrong: a coordinator that must write one reply continues to post the lines of its delegates.

Cut before the gate, within the approved objective, one line each in DECISIONS.md: no wait from a turn already working a task (so asks never nest), one wait per step, no testing helper, no reaching into a colleague's run already under way, and a fixed ten-minute timeout.

Open: none. D1 is the one to weigh. Reasons and what lost: DECISIONS.md. The cases: BUSINESS-RULES.md.

Reviewers · look here

  • Decisions → D1. Is the board the right home for an ask? The other option is a wait on the request, with no board.
  • Rules → BR-11 and BR-12. A restart between the ending of the row and the resume. Is the resume-owed marker enough to resume one time, and not two times?
  • Plan → S7. The timeout fires from the durability sweeper's expiry step, at ten to twenty minutes.
  • Plan → the PR plan. P3 waits on FIX-1794 P2. Is it correct that P1 and P2 can start now?

Not here: asks to several colleagues at the same time (fan-in), nested asks, and the answered park of an assigned task (FIX-1817).

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1816 · epic FIX-1815 (#2891) · builds on FIX-1794, FIX-1802 · merges after human approval and required checks (contract)

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_01Qmij1MasdpEs8jm9ZpDzNq


Generated by Claude Code

An ask is a task on the asker's own board; its turn parks on the row and
resumes with the row's output. Replaces the epic's L5 surface (D1), names
the kill line's caller (D2), and keeps "ask the delegate" a post (D3).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qmij1MasdpEs8jm9ZpDzNq
@jhoffner jhoffner added the spec label Oct 8, 2026 — with Claude
@linear-code

linear-code Bot commented Oct 8, 2026

Copy link
Copy Markdown

FIX-1816

@vercel

vercel Bot commented Oct 8, 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 Oct 8, 2026 9:28pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 8, 2026 9:28pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 8, 2026 9:28pm UTC

Request Review

@jhoffner jhoffner left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Second-look and architecture pass on the FIX-1816 spec.

Direction: sound. Putting the ask on the asker's board and parking the turn on the row reuses the claim ticket, the notice and runOnce, so it adds no second finished signal. The goal and its two controls would fail if the goal were not met. I found no reason to prefer the request-level wait.

One blocking finding (🔴), inline on PLAN.md S7. The timeout path depends on a "durability sweeper resume" that does not exist. Today's sweeper only marks overdue suspensions expired (every 10 minutes), and S2 admits only pending gates. A timed-out ask, and so a mutual ask (BR-15), can strand the turn with no error. The spec should decide how the timeout actually fires.

Two non-blocking notes (🟡), inline:

  • Whether the resume-owed marker is needed or derivable from "row terminal and gate pending". It removes the writer-completeness guardrail if so.
  • A gap between filing the row and persisting the gate, where the marker can name a gate that never existed. Add a rule so it clears.
  • D1 should price the FIX-1794 P2 schedule dependency, and say what happens to the goal if it slips.

Architecture: no refactor is warranted here beyond what the plan already lifts (the notice module, S9). I would not add more opportunistic cleanup to this spec.


Generated by Claude Code

Comment thread specs/issues/FIX-1816/PLAN.md Resolved
Comment thread specs/issues/FIX-1816/PLAN.md Resolved
Comment thread specs/issues/FIX-1816/PLAN.md Resolved
Comment thread specs/issues/FIX-1816/DECISIONS.md Resolved

@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.

Simplify review (FIX-1816 spec)

Problem framing: Workforce needs an in-turn hand-off that survives restart and returns a colleague's real output once — without resurrecting FIX-1814's private team or bolting a second global wait protocol onto dispatch.

Verdict: The chosen shape (askTask → board row → park → FIX-1794 notice + resume-owed replay → fifth RequestHost verb) is the right tradeoff versus epic L5 (awaitDispatch + resultOf) and versus addTask({ wait: true }). It composes seams already on the roadmap (FIX-1794 P2, FIX-1802 settle-owed pattern, generator suspend/resume, runOnce) instead of inventing a parallel stack. Approving direction; the notes below are about tightening the spec set and nudging implementation so complexity stays bounded.


Where the approach could feel heavier than necessary

  1. Two wake paths, one outcome — Notice delivery (happy path) and "any touch of the board" replay (resume-owed, FIX-1802 pattern) both drive the same gate. That is probably required for BR-11 (kill between ending write and resume) and for P2 testing without FIX-1794 P2, but the spec never states the invariant in one place. Readers infer duplication. A single paragraph in SPEC or BR (notice pays the debt; touch replays unpaid debt) would cut conceptual load without changing design.

  2. resume-owed beside notice-owed — Three durability hooks on one ending write (gate resolve, notice-owed, resume-owed). D1's "count" argument rejects request-level wait; it does not yet prove resume-owed is not redundant if the notice handler always invoked the fifth verb for asked rows. Worth a short proof sketch in DECISIONS or EVOLUTION (different consumers: conversation notice vs parked generator gate), or an explicit "we considered collapsing these" row — otherwise implementers may over-build or under-build.

  3. Document duplication — DECISIONS.md § "Decided, not asked" largely mirrors PLAN surfaces S1–S7 / guardrails. Template intent is decisions = why; plan = how. Trimming that section to pointers (timeouts, fifth verb, nested row park → PLAN) would shrink the authority surface. Similarly, EVOLUTION rows for "retained unchanged" (FIX-1791 ledger, park-exit) repeat DECISIONS/PLAN; evolution could stay amend/supersede-only. BR-11's mermaid duplicates the fence figure; one diagram may be enough.

  4. Verification scope — Goal leg 2 (lead → analyst → auditor) proves D2's product story more than a new mechanism; leg 1 already covers restart, runOnce, and waker. Optional simplification: keep leg 2 as a D2 acceptance note or secondary goal path so P3's gate stays focused — not blocking if you want one mermaid for PO sign-off.

  5. BR-8 (two askTask in one step) — Consistency under replay, but no persona in the table needs it for v1. Deferring to "one ask per tool-call site until fan-in" would narrow P2 CI unless you already have a caller that double-asks before any await.

  6. DOCS error names — ask_timed_out, etc. are user-facing contracts not in PLAN "pinned names". Either pin them in PLAN or label DOCS errors illustrative until P3 — avoids drift.


Implementation-time performance (not spec blockers)

When this ships, watch:

  • Board-touch replay (for each row with resume-owed) on hot list/claim paths — needs an index or cheap "any owed?" short-circuit, not full-board scans per touch.
  • Resume on child ending — if S2 runs inline in the notice/ending handler, child completion latency includes asker replay; queueing may be preferable with bounded concurrency.
  • Documented one replay per ask — cost is intentional; no spec change needed, but worth calling out in P1/P2 reviews.

Timeout without idle-board sweeper (PLAN follow-up) trades busy-wait for stale parked state until the next touch — already acknowledged.


What I would not simplify away

  • Separate askTask vs addTask (epic D4).
  • Fifth session-scoped verb vs public resume routes (BR-13 / BP-031).
  • S6 nested row park for task workers that ask (lease double-claim).
  • Three PRs with P3 gated on FIX-1794 P2 lift (no notice fork in FIX-1816).
  • D3 keeping coordinator posts off askTask (FIX-1791 ledger).

Third-party / reuse

No missing npm package jumps out; the win is reusing FIX-1794's notice module and FIX-1802's owed-marker pattern rather than custom reply channels (FIX-1537) or harness-manager human ask (wrong layer). PLAN's "no copy" rule for S9 is the right guardrail.


Summary: Architecture looks like the smallest change that meets leg (a) + kill line + restart goal. Main simplify opportunity is spec hygiene (one invariant for dual wake paths, dedupe DECISIONS/EVOLUTION, optional narrow BR-8 / leg-2 gate) and implement-time discipline on board-touch cost and inline resume. Happy to merge this spec as directionally correct.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1816/SPEC.md Resolved
Comment thread specs/issues/FIX-1816/DECISIONS.md Resolved
Comment thread specs/issues/FIX-1816/PLAN.md Resolved
Comment thread specs/issues/FIX-1816/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1816/SPEC.md Resolved
Comment thread specs/issues/FIX-1816/DOCS.md Resolved
Comment thread specs/issues/FIX-1816/EVOLUTION.md Resolved
Cut nested asks (depth one by construction), the nesting goal leg, the
testing helper, the lease-abort cancel, the per-call timeout and several
asks per step. The timeout now fires from the durability sweeper's
expiry step through the resume path. D1 prices the FIX-1794 P2 slip;
the stored resume-owed marker is justified; BR-7 clears a marker whose
gate was never created; error names pinned; touch guardrail added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qmij1MasdpEs8jm9ZpDzNq
Comment thread specs/issues/FIX-1816/SPEC.md Resolved
The product owner, in review: both calls add a task, so a ninth tool is
unnecessary. An ask is now addTask with waitForResponse: true, a flat
optional field like deps and priority. The cuts carry over: refused on
a turn working a task row (depth one), one wait per step, a fixed
timeout. Errors renamed wait_*; D1, the dropped alternatives, PLAN's
pinned names, DOCS and two figures updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qmij1MasdpEs8jm9ZpDzNq
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