Skip to content

spec(epic): record FIX-1816/FIX-1817 epic-row changes and the P2-wait decision (FIX-1815) - #2904

Merged
jhoffner merged 3 commits into
mainfrom
epic/hand-offs-amend-er11
Oct 8, 2026
Merged

jhoffner merged 3 commits into
mainfrom
epic/hand-offs-amend-er11

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

Follow-up to #2891, the merged epic spec for FIX-1815, and to #2893, which recorded Q1 and Q3. This PR records decisions made on 2026-10-08. On that date the product owner approved the two child specs in session: FIX-1816 at #2900 (head 964ecb69) and FIX-1817 at #2899 (head 163730d8). Under ER-11 the epic has to record the changes those specs make to its rows. This PR records them as decided, and the results of the cross-spec pass below, and changes nothing else. It edits only specs/epics/FIX-1815/.

What it records

  1. D5 L5, reshaped (FIX-1816 D1). An ask is a task on the asker's own board. It is addTask with a waitForResponse option. There is no new tool, no new core export, and no awaitDispatch or resultOf: waitForResponse adds no tool. The product owner's reason: ask and add both add a task.
  2. D5 L6, dropped. Asks can't nest. A turn that is working a task row can't wait.
  3. D5 L7, the depth half. The limit is depth 1, and that follows from the design. The timeout is fixed. It fires from the durability sweeper's expiry step, between 10 and 20 minutes after the ask.
  4. ER-5. It now reads "an opt-in option" where it said "a separate, opt-in call". D4's fire-and-forget default doesn't change.
  5. D5 L9 (FIX-1817). It adds answerTask as a new task tool, and addTask.followUpOf, which binds a follow-up to the root task's session. A follow-up is refused while that session still has an unfinished task. A person's message keeps the shipped allow concurrency.
  6. The product owner's decision on a FIX-1794 P2 slip. If P2 slips, ask waits with it. No stop-gap waker gets built (ER-7). This is recorded in DECISIONS and in PLAN's sequencing.

Cross-spec pass, authorized by the product owner on 2026-10-08: (1) an asked task gets no parkOnQuestion in v1, new ER-22, owned by FIX-1817 and mirrored by FIX-1816, a coordinator call the product owner can overrule; (2) ER-12 gains a second agreed exception, FIX-1817's L9 changes to FIX-1794's S5 to S7, landing after FIX-1816 P3 where both touch S6, with fix-1786-pm told before FIX-1794 P2 merges (ER-21); (3) D5 L9 adds parkOnQuestion and turnReentries now counts question re-entries; (4) the tool check is one set per turn, "waitForResponse adds no tool", with FIX-1786's ER-32 literal "eight" raised as an amendment request. Recorded in DECISIONS → Decided in the cross-spec pass.

What changed

  • DECISIONS: The L5 to L9 rows are rewritten, and L2's wait binding now names the task row it waits on. L6 keeps its number and is marked dropped. There are new sections, D5 amendments from the child specs and Decided in the cross-spec pass, and new How it got here lines. D3's and D4's Locks in lines restate the new answers.
  • BUSINESS-RULES: ER-4 notes depth 1 and the fixed timeout, and is checked by a stalled ask's timeout and cancel. New ER-22; ER-12, ER-15 and ER-21 carry the second FIX-1794 exception. ER-5 is reworded. ER-11 now says "D5's list" where it said "D5's nine".
  • PLAN: The row ranges are updated. Ask goes live only once FIX-1794 P2 merges, and waits with it if P2 slips.
  • SPEC: The set table's rows describe ask as a task on the asker's own board, depth 1 by construction, and name ER-22; What stays as it is and the sign-off are updated.
  • DOCS: The draft ask prose has one timeout sentence, "within twenty minutes", deferring to FIX-1816's DOCS.md; it says asks don't nest and an asked worker can't question back.
  • EVOLUTION: There are four rows for this epic's L5, L6, L7 and L9 as merged in spec(epic): hand-offs that wait for an answer or stay open, and survive a restart (FIX-1815) #2891. The FIX-1537 row now records that FIX-1537 closes as a duplicate of FIX-1816, as FIX-1816's approved spec decided under ER-18.
  • Figures: end-state.svg drops awaitDispatch and the parked asker row, and adds waitForResponse, answerTask and "no nested asks". path.svg changes ask's build lane to L1–L3, L5, L7, L8. end-state.svg names parkOnQuestion beside answerTask; ownership.svg gains ER-22's row.

Checks: the spec-figures verify block passes. Both changed figures were rendered in light and dark and checked by eye.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Qmij1MasdpEs8jm9ZpDzNq


Generated by Claude Code

…ecision

Under ER-11, from the child specs the product owner approved on
2026-10-08 (FIX-1816 at #2900 964ecb6, FIX-1817 at #2899 163730d):
L5 reshaped to addTask's waitForResponse; L6 dropped; L7's depth half
holds at depth 1 with a fixed sweeper-fired timeout; ER-5 reads as an
opt-in option; L9 adds answerTask and addTask.followUpOf. The product
owner's call: if FIX-1794 P2 slips, ask waits with it, no stop-gap
waker (ER-7). EVOLUTION rows, the box and path figures re-derived.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qmij1MasdpEs8jm9ZpDzNq
@linear-code

linear-code Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

FIX-1815

FIX-1817

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

Request Review

jhoffner commented Oct 8, 2026

Copy link
Copy Markdown
Collaborator Author

Second-look + architecture pass (spec-only PR, no code to refactor)

Overall: the shape is right. It records approved child-spec outcomes against the epic rows (ER-11) and touches nothing else. Cross-file consistency holds: I grepped for stale awaitDispatch/resultOf/"nine"/"L5 to L8" and the only hits are intentional history (the L5 row's "no awaitDispatch", EVOLUTION, the spike note). Findings, most useful first:

  1. ER-4's "checked by" is now vacuous (BUSINESS-RULES.md, ER-4). The check column still says "FIX-1820's gap sweep with a mutual ask". With L6 dropped and asks capped at depth 1 by construction, A→B→A cannot be built, so that sweep can't be run as written. Re-point it at what can still fail: a timed-out ask resumes with a timeout error (L7's red state), and cancel of the asker reaches the asked row. Otherwise the closure plan inherits a test that cannot go red.

  2. D3's "Because" still argues a deadlock that can't occur (DECISIONS.md, D3). "A asks B while B asks A, and both wait forever" is now unreachable; only the cancel-propagation half of the rationale still holds. The "Locks in" line was updated but the reason above it wasn't, so the card contradicts itself. Reword "Because" to the cancel gap plus "an ask whose answer never comes". Also consider whether the "depth cap" survives as a rule at all, or becomes the by-construction invariant "a task-row turn cannot ask", which is the thing worth locking and testing.

  3. Same fact recorded four times (restraint). L5/L6/L7/L9 changes appear in the rewritten D5 rows, the new "Recorded under ER-11" section, four new EVOLUTION rows, and the PR body. EVOLUTION already carries the Amended/Superseded lineage and the D5 rows carry the current truth. I'd cut the ER-11 section down to the one decision with no other home, the P2-slip call (and its "no stop-gap waker, ER-7" reasoning), and link to EVOLUTION for the rest. Less to keep in sync next amendment.

  4. SPEC.md set table (line ~97) still says FIX-1816 is "bounded by a timeout and a depth cap". Say "bounded by a fixed timeout" to match L7/DOCS.

  5. DOCS.md draft promises "ten minutes" while L7 says the ask resumes "within 10 to 20 minutes". The draft covers it ("within ten to twenty minutes"), but the lead "time limit of ten minutes" will read as a guarantee to a reader. Lead with the observable behavior (resumes with a timeout error, typically 10 to 20 minutes) and drop the bare "ten minutes".

  6. Product note, not a blocker: the timeout is fixed and sweeper-granular, so a caller with a tight turn budget can't choose a shorter ask. That's an accepted trade in the approved child spec; worth one line in L7 so FIX-1820 doesn't discover it as a "bug".

No code or architecture-deepening opportunities apply here; the one structural point is #3 (one home per fact). Items 1–2 are the ones I'd fix before merge.


Generated by Claude Code

L2's wait binding names the task row under the reshaped L5, not a
request. EVOLUTION's FIX-1537 row records FIX-1816's approved call
(ER-18): FIX-1537 closes as a duplicate of FIX-1816 and stays
FIX-1312's child.

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

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

Problem

Epic FIX-1815 merged on main (#2891) with a heavier Layer 1 story (awaitDispatch / resultOf, L6 lease parking, open-ended depth cap). Child specs (#2900, #2899) reshaped ask around addTask + waitForResponse, dropped L6, and fixed L7 — this PR records that delta. The question is whether the recording is as lean as the design it captures.

Verdict

Direction: approve. Folding ask into the existing task board (not a parallel request-wait API) is the simpler architecture and matches how orchestration already thinks (notices, park/resume, runOnce). Dropping L6 follows from depth-1-by-construction. The P2-slip decision (wait with P2, no stop-gap waker) is consistent with ER-7.

This PR’s shape: mostly right, a bit heavy. EVOLUTION rows + D5 table updates are the necessary amendment surface. Re-stating the same bullets in DECISIONS (“Recorded under ER-11…”), D3/D4 locks, PLAN, both SVGs, and epic DOCS draft increases drift risk — and we already have small inconsistencies (see inline).

Simpler approach (if you were doing it again)

  1. Epic first draft: Frame L5 as “task on asker’s board + waitForResponse” from the spike, avoiding awaitDispatch / L6 in #2891 entirely.
  2. Amendment PR: EVOLUTION.md + DECISIONS.md D5/D3/D4/ER rows + PLAN.md P2 gate; defer epic DOCS.md quoted sections to FIX-1816/1817 DOCS.md (ownership table already says children publish specifics).
  3. Retention: Rename the child-spec log section so it doesn’t share the ER-11 label with the “no extra Layer 1” rule — or link only to #recorded-under-er-11-from-the-child-specs without saying “under ER-11” in prose.

Skipped (not blocking)

  • Renumbering L6 away: keeping the ghost row is defensible for #2891 lineage; just gloss it wherever L-ranges appear.
  • Sweeper-based 10–20m timeout: inherent tradeoff of D1 + periodic expiry; FIX-1816 owns the exact deadline wording.

No changeset needed (spec-only).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1815/DECISIONS.md Resolved
Comment thread specs/epics/FIX-1815/DECISIONS.md Resolved
Comment thread specs/epics/FIX-1815/BUSINESS-RULES.md Resolved
Comment thread specs/epics/FIX-1815/DOCS.md Resolved
Comment thread specs/epics/FIX-1815/SPEC.md Resolved
Comment thread specs/epics/FIX-1815/EVOLUTION.md Resolved
Cross-spec pass, authorized by the product owner on 2026-10-08:
- ER-22: an asked task gets no parkOnQuestion in v1 (coordinator
  call, overrulable by the product owner); FIX-1817 owns, FIX-1816
  mirrors. Ownership figure gains its row.
- ER-12: FIX-1817's L9 rows (S5 work entry, S6 session key, S7
  capability) are a second agreed touch of FIX-1794 code; on S6,
  FIX-1817 lands after FIX-1816 P3. ER-15, ER-21, PLAN seams follow.
- D5 L9: parkOnQuestion added; turnReentries counts question
  re-entries too.
- Tool count: one set of task tools per turn; the check is
  "waitForResponse adds no tool". FIX-1786 ER-32's literal "eight"
  is raised as an amendment request.

Review 5463206853: the ER-11 section is renamed "D5 amendments from
the child specs"; ER-4's check is a stalled ask's timeout and cancel;
DOCS has one timeout sentence pointing at FIX-1816's DOCS; the set
row describes ask as a task on the asker's own board.

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

jhoffner commented Oct 8, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-pm
session: fix-1815-pm
kind: reply

CI note on 1444530: Test (2/3) failed in @flow-state-dev/engine, at session-stream-conformance › filesystem › "keeps an unfinished run older than a page of runs listed (BR-23)". It reported "no matching event within 25000 ms; got []".

This isn't caused by this PR. It only touches specs/epics/FIX-1815/**, and no code or test is in its diff. The failing test is a timing-sensitive engine conformance check, and main has already needed a fix for tests failing under load (b9f41f1, "stop two tests failing when the machine is busy"). I know of no fix PR for this case yet. I've re-run the failed job once. If it fails again, I'll treat it as real and raise it separately rather than widen this spec PR.


Generated by Claude Code

@jhoffner
jhoffner merged commit 2301887 into main Oct 8, 2026
25 of 27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants