Skip to content

spec(FIX-1666): DevForce goal lab raises an ask a person can approve, on a deterministic path - #2437

Merged
jhoffner merged 4 commits into
mainfrom
spec/FIX-1666
Sep 30, 2026
Merged

jhoffner merged 4 commits into
mainfrom
spec/FIX-1666

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
runs the closure (FIX-1663, leg a1) Opens the DevForce Lab in App Lab and finds Inbox empty: nothing on that tree asks a person anything Inbox holds one approval from the EM seat, the same every run, raised with no model
answers it Nothing to answer Approve & run: the EM files the feature and the coder seat starts. Deny: nothing is filed, and the EM says so
re-runs the lab a year from now Three checks, none touching approval A fourth check proves the ask, both answers and a control that removes the gate, with no model and no key
maintains the three existing checks Green Green and unchanged: the ask is off unless a host asks for it

Goal: when a host opens the DevForce goal lab with the ask turned on, the EM seat's session holds one pending approval, raised the same way every run with no model. Approving it through the session's own resume files the feature and starts the coder seat on it. Denying it files nothing.

flowchart LR
  O["open the lab · ask on · stub harness · no key"] --> L["session listing, through the lab's door · one pending approval in the EM's session"]
  L -->|"approve · the session's resume route"| A["one row for the held-out feature · handed to the coder seat · the coder's run starts"]
  L -->|"deny · same route"| D["no row · no dispatch · the EM says nothing was filed"]
  A --> P["PASS"]
  D --> P
  C["control · no-gate · files without asking"] -.-> L
  L -.->|"under the control"| F["must FAIL · a row existed before any approval"]
Loading

The check reads what a person's client would read, through the lab's own door. Goal check: goals/devforce-lab/it-waits-for-a-person-before-it-files/. The control GOAL_CONTROL=no-gate must FAIL on "a row existed before any approval".

Today the EM files at once through two doors and nothing asks a person; after, a third door, off by default, waits for a person in the EM's own session, and Approve joins the existing row and board path

The middle column is the change: the new door waits for a person, and after Approve it joins the path the other two doors already take.

How: the EM kind gets one action that pauses on the framework's stock approval before filing. One step of the lab's raises that ask once. openLab calls the step when a host turns the ask on, and so does App Lab's DevForce config. Only the lab's tree changes; nothing in the framework does.

Sign off

The goal, at that size: an ask that gates real DevForce work, not a demo gate. If wrong: the closure proves Inbox against an ask that runs nothing.

D1 · The EM asks before it files a feature; Approve files the row and the coder starts, Deny files nothing

D1 trade-off figure (beside its card in DECISIONS.md → D1)

It comes down to whether approving runs real work. A demo gate runs nothing, and a question from the coder would be a parked row that Inbox doesn't list. The premise that approving can start the run is now settled by a POC (below). If wrong: the one ask on the tree gates the wrong step, and FIX-1652 inherits it as the example. This is the one to weigh.

D2 · Raised when a host turns it on, off by default; App Lab's DevForce config turns it on

D2 trade-off figure (beside its card in DECISIONS.md → D2)

It comes down to whether opening alone shows the ask without changing the three checks. FIX-1662's merged config builds its own flow state, so it turns durable execution on and calls the raise step directly. If wrong: Inbox is empty on open, or the three checks change shape.

Open: none. Depends on FIX-1662 drawing a member seat's pending ask in the workstream's Stream. That is an amendment to FIX-1662, which is already merged (see DECISIONS → Decided, not asked). Reasoning and what lost: DECISIONS.md.

POC

specs/issues/FIX-1666/poc/durable-drain/ puts a board drain in the approved branch of a durable request and answers the ask through the engine's resume route. On approve, one row is filed and the coder runs once in a child session under the EM's session. The resume answers 202 before that run, so Approve doesn't wait for a coding run. On deny, nothing is filed. The no-gate control fails as it must.

pnpm exec tsx specs/issues/FIX-1666/poc/durable-drain/check.mts                      # PASS
GOAL_CONTROL=no-gate pnpm exec tsx specs/issues/FIX-1666/poc/durable-drain/check.mts # must FAIL

Reviewers · look here

  1. DECISIONS.md → D1: is "approve before filing" the right step for the one ask on this tree?
  2. DECISIONS.md → Decided, not asked: the ask stays in the EM seat's own top-level session (the one the lab's file and drain doors run in, not the dispatch run a channel post wakes it in), and App Lab's workstream Stream draws its member seats' pending asks. That amends FIX-1662. Leg 1 lists sessions with dispatch runs included, as Inbox does under FIX-1662's BR-24 (spec(FIX-1662): workstream Stream draws member seats' pending asks #2439).
  3. Cross-spec: FIX-1662's S12 config needs two lines (durable on, and a call to the raise step), and its Stream needs the change in item 2.

Deliberately not here: what an ask means org-wide (FIX-1652), the board on the channel (FIX-1667), App Lab's Inbox (FIX-1662).

SPEC · DECISIONS · RULES · PLAN · DOCS · Linear FIX-1666 · epic FIX-1649 (#2421) · filed from FIX-1663 D1 · merge follows approval and required checks (contract) · no changeset (spec only)

How to review this

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_01Cnm5DbhFmkarpesBpPQ9Dq

Retained spec set: the EM seat asks before it files a feature (stock
human_approval suspension), raised on open only when a host asks,
proved by a fourth model-free check with a no-gate control.

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

vercel Bot commented Sep 30, 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 30, 2026 5:27pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 30, 2026 5:27pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 30, 2026 5:27pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 30, 2026

Copy link
Copy Markdown

FIX-1666

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 30, 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-30T17:08:56.924460Z e20394c 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.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction only; read-only review)

The approach is sound: stock human_approval, lab tree only, ask off by default, its own fourth check with a no-gate control. I did not find a reason to re-open D1 or D2. Findings below, ranked. Nothing here blocks direction approval unless #1 fails.

1. The one unproven premise should be settled now, not at implement time (above the line)

PLAN "At implement time" item 1 admits that durable suspension plus board.drain in the resumed request is untested (unparkAndDrain composes drain in a sequencer, but not after a durable resume). D1's whole value ("Approve & run runs real work") rests on it, and the spec's fallback is "stop and return a blocker". That is an expensive place to learn it: a blocker after implementation re-opens D1. It is also exactly the "factual claim" shape settle-claim / spec-poc exist for. A throwaway POC on this spec branch (suspend → resume → drain → child run appears under the EM's session) costs little and converts "Open: none" into "Settled".

Related, and not in the spec: the drain runs inside the resume request. With the stub it finishes at once. With a real harness (App Lab's actual use), the person's Approve click blocks for the length of a coding run, unless park-exit or an async hand-off applies. The check cannot see this because it only runs the stub. Either state in D1 that Approve returns when the drain idles, or say the approved branch hands off and returns. Which one holds changes what "the coder starts" means for AR-8/AR-9.

2. Leaner alternative worth one line in "Considered and dropped"

Approve could file the row and stop; the existing DRAIN_ENTRY door starts the coder. That drops the durable-plus-drain risk entirely. It fails the goal as written ("& run"), so it is the right thing to reject, but it is the obvious simpler shape, and its absence from the dropped table means the next reader will ask. The rejection reason is "the coder must start on approve", which ties back to #1.

3. Deny re-open behaviour is unspecified (AR-5 gap)

AR-5 covers a pending ask and an approved one. After Deny, a second openLab over the same store finds no pending ask and no row, so by the stated rule ("raised once per feature") it is ambiguous whether it raises again. If it raises again, a denied feature re-asks on every open, which is noisy in App Lab; if it does not, something must record the denial. Decide and add a rule. The leg 3 "fresh open" wording sidesteps it.

4. "Fail open" wording contradicts AR-6

PLAN S2 says "fail open if it could not be raised"; AR-6 says open fails when raising fails. "Fail open" reads as the opposite (continue without the ask). Reword to "fail the open".

5. Architecture note: where the raise lives

host.mts is already 642 lines and carries one opt-in door (channels). S2 adds a second inline: durable flag, per-feature idempotency lookup, run-as-person, suspend-until-pending. Since this PR is already touching openLab, put the raise in its own module beside notify.mts (host keeps the option and one call) rather than growing the host. That also makes D2's fallback ("export the raise as a step the config calls") free rather than a later refactor.

That fallback deserves a nudge: S5/D2 bet that FIX-1662's config goes through openLab, and the spec only finds out in implement-time item 2. #2424 is open now, so this can be read at spec time.

6. Minor

  • addRow's doc comment says "Shared by the two doors below"; with a third door this becomes stale. Fold into S1 so the file doesn't drift (BP-034).
  • Nothing in this PR needs a changeset or package docs (lab-only), which matches the PR body.

No concerns on scope, the BP-031 handling (resume only via the verified bearer; AR-13), or tenet fit.


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.

Simplify / architecture review

This PR is spec-only (~2.3k lines across three full issue sets). I ran parallel read-only passes (quality, performance-at-plan-time, reuse against goals/, kitchen-sink, core). No code was changed in this review.

Bottom line

FIX-1666’s approach looks like the right minimum for the epic gap — stock human_approval, lab tree only, third EM door sharing addRow, raise-on-open behind an option, dedicated goal check with a no-gate control. That matches existing patterns (apps/kitchen-sink/flows/chat-agent/approval-gate.ts, goals/suspension/completes-via-the-resume-endpoint/, devforce openLab + bearer door) without lifting framework or App Lab APIs.

The main simplify concern is not “wrong mechanism,” but PR shape and cross-spec surface area: three unrelated spec gates in one PR titled FIX-1666, heavy duplication between closure legs and child goals, and a second D1 child (channel-attached board) still absent while FIX-1664 and FIX-1663 leg a2 already assume it.

What I’d simplify before merge (recommended)

  1. Split or retitle the PR — Reviewers approving “DevForce ask” are also approving App Lab task view + full closure QA. Either epic-level title/description or three spec PRs (1666 → 1664 → 1663) so each gate matches one decision.
  2. Make the board dependency explicit — FIX-1663 D1 names two blocking children; this PR delivers the ask child (1666) but not the channel-board child (epic calls this FIX-1385 / FIX-1662 follow-up). FIX-1664’s goal input already requires a channel-attached board; PLAN’s fixture fallback is easy to miss. Add a stub FIX-1667 spec, or a blocking line in FIX-1664 SPEC.md sign-off, and update FIX-1663 D1 to say 1666 is child one when merged.
  3. Thin FIX-1663 legs a1/a2 — They re-list FIX-1666 / FIX-1664 goal signals verbatim. Simpler closure: “subprocess goals/devforce-lab/it-waits-for-a-person-before-it-files/ and goals/app-lab/it-shows-and-stops-a-task-run/ on this SHA; PASS iff both PASS,” plus one sentence of journey intent. Cuts drift and ~pages of duplication.
  4. Deduplicate FIX-1663 PLAN vs BUSINESS-RULES — QR-11–16 largely restate Parts 1–4 (PLAN review notes already flag this). Pick one home for procedural closure rules.
  5. FIX-1663 PLAN hygiene — Line 9 still says “FIX-1664 has no spec yet”; controls row can name FIX-1664’s GOAL_CONTROL values now that 1664 is in the same PR.
  6. FIX-1664 open fork — Composer / send-a-turn is the real product sign-off; keep the fork in DECISIONS.md only and point SPEC sign-off there (avoid two BP-041 blocks + duplicate figure narrative).

FIX-1666 implementation notes (when you build it)

  • Reuse, don’t reinvent: durable gate shape from approval-gate.ts; HTTP grading from goals/suspension/completes-via-the-resume-endpoint/; goal scaffolding from goals/devforce-lab/it-wakes-the-seat-a-file-declared/.
  • Stop-the-line is correct: PLAN’s “durable + board.drain after resume is unproven” — if it doesn’t compose, block rather than approving into a no-op “& run.”
  • Performance (App Lab path): approve path may wait for full drain on resume; closure a1 is user-visible — spec doesn’t need change, but implementers should treat synchronous vs async drain as an explicit product call.

What I’d not push in this PR (larger refactors)

  • Collapsing FIX-1663 into “only re-run child checks on one SHA” (conflicts with epic ER-1 browser proof).
  • Merging FIX-1664 into FIX-1662 (epic D1 already split them).
  • Resolving FIX-1664’s turn fork in prose without a Linear child (product decision).

Approval stance

I’m not approving yet because of scope bundling and missing/implicit board child, not because FIX-1666’s design looks over-engineered. Addressing the items above (especially 1–3) would make this an easy approve on direction.

Happy to re-review after a focused revision.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1666/PLAN.md Resolved
Comment thread specs/issues/FIX-1666/PLAN.md Resolved
Comment thread specs/issues/FIX-1666/SPEC.md Resolved

@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: e20394cc24

ℹ️ 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-1666/PLAN.md Resolved
Comment thread specs/issues/FIX-1666/PLAN.md Resolved
Review round 1 (Codex):
- The ask stays in the EM seat's session, where Inbox reads it. FIX-1662's
  Stream only drew the channel transcript, so the card could not show
  there; the workstream's Stream now draws its member seats' pending asks
  with the same card and resume (an amendment to FIX-1662, noted as a
  follow-up). AR-3 and leg 1 check the EM is a member of the channel.
- "Raised once per feature" now counts a denied ask: the reopen guard reads
  the EM session's request history for any asking request for the feature,
  so a Deny stands after reopen. AR-5 and leg 4 cover it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
…tep App Lab's config calls

Review round 1 (second look, Cursor), on top of the Codex fold:
- POC poc/durable-drain/: a board drain in the approved branch of a durable
  request, resumed through the engine route, files one row and runs the
  coder in a child session under the EM's; resume answers 202 before the
  run. Recorded in DECISIONS -> Settled; the no-gate control fails.
- D2: FIX-1662's merged config builds its own flow state rather than
  opening through openLab, so the raise is its own step; the config turns
  durable on and calls it (D2's change-my-mind fired).
- "fail open" corrected to "the open fails"; AR-8 says Approve returns at once.
- The file-then-stop alternative added to Considered and dropped.
- Below-the-bar comments recorded verbatim in PLAN -> Notes from review.

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

Copy link
Copy Markdown
Collaborator Author

Review round 1: how each item was handled (head c7639a48b, on top of the Codex fold in b9f8f3a52)

Second look

  1. Unproven durable-plus-drain premise, and Approve latency. Settled with a POC: poc/durable-drain/, recorded in DECISIONS → Settled. A drain in the approved branch of a durable request, answered through the engine's resume route, files one row and runs the coder once in a child session under the EM's session. The resume answers 202 before the run, so Approve doesn't block on a coding run (AR-8). The no-gate control fails.
  2. Leaner alternative (file and stop). Added to Considered and dropped, with the reason: "& run" would run nothing.
  3. What happens on re-open after a Deny. Folded in b9f8f3a52: a Deny is final for that store (AR-5, leg 4).
  4. "fail open". Corrected to "the open fails, naming the step".
  5. Where the raise lives, and whether FIX-1662's config goes through openLab. Folded. FIX-1662's merged spec shows the config builds its own flow state, so D2's change-my-mind fired. The raise is now a separate step in its own module beside notify.mts. openLab keeps the option and one call. The config sets durable: true and calls the step (D2, S2, S5, and the D2 figure are updated).
  6. addRow doc comment. Recorded in PLAN → Notes from review.

Cursor review: the PR-shape points (three specs bundled, about 2.3k lines, FIX-1664/1663 legs, a FIX-1667 stub) don't apply to this PR. It contains only specs/issues/FIX-1666/ (8 files at open), so those are dropped as describing a different diff; they belong on the epic's cross-spec review if anywhere. I recorded the reuse pointers verbatim in PLAN → Notes from review.

Follow-up for cross-spec review (coordinator): FIX-1662's Stream has to draw the pending asks of its member seats (an amendment to FIX-1662, which is already merged), and FIX-1662's S12 config needs the two lines from D2.


Generated by Claude Code

…patch runs

The ask runs in the EM seat's own top-level session (s_<seat id>, where the
lab's file and drain doors run), not the notify dispatch run. Leg 1 and AR-3
list with include=dispatch-runs, matching FIX-1662 BR-24 (#2439). The dropped
child-session alternative no longer rests on the default listing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
@jhoffner
jhoffner merged commit 9e4adca into main Sep 30, 2026
13 checks passed
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