Skip to content

spec(epic): W5 amendment — three producers named, checklist row 5 re-owned (FIX-1457) - #2033

Merged
jhoffner merged 6 commits into
mainfrom
epic/FIX-1457-producers-and-row-5
Sep 22, 2026
Merged

jhoffner merged 6 commits into
mainfrom
epic/FIX-1457-producers-and-row-5

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 22, 2026 •

Copy link
Copy Markdown
Collaborator

A post-merge amendment to the retained W5 epic-spec, on a new PR from main. #1944 stays the merged review record and is untouched. The objective does not move — W5 is still Workforce release QA, still three named exit proofs. What moves is who produces them, and one correction to a claim this epic asserted and never checked.

Three things, and the third is the substantive one.

1 · The last two "No producer" rows are gone. FIX-1496 takes ER-DevForce (In Spec Review, #2023 at 25e7507) and FIX-1497 takes ER-Collab (Backlog, no spec). The epic's ER-DevForce row now states the artifact cut in its own words, because that cut answers a question the row itself posed: one automated leg, the temp repository gaining a bare clone at a declared path the run pushes to, so the artifact resolves after the goal's process exits needing git and a temp dir but no gh, no token and no network; the credentialed pull-request leg is documented as the human release run. Channels are recorded as inside the ratified criterion, not optional. The cut is FIX-1496's own gate to approve — this row records it, it does not ratify it.

2 · ER-26 is new. No exit proof's run is graded before FIX-1496 stands a live hired Workforce up. ER-3 and ER-Devtool both forbid a fixture or a wrapper, and no tree in the repository has a sealed document today, so FIX-1481's row-6 code can be entirely correct and the row still cannot go green. It fences the runs and explicitly not the code PRs.

3 · The Devtool split is corrected, and it was wrong on a false premise. FIX-1481's spec deferred checklist row 5 because "the reader is already owned by FIX-1477 PR-C." Verified on main: FIX-1477's Roster reads workforce/roster/* — FIX-1475's collection, whose own header says it is "not the seat inventory, and deliberately beside it." Row 5 names inventory/*. Different collection, different question, no reader in any plan. So the deferral left row 5 owned by nobody. Rows 4 and 6 are FIX-1481's; row 5 is FIX-1502's, which FIX-1486 blocks in Linear — under one reading of row 5, not both (What's asked of you, below). Recorded in EVOLUTION.md as a correction, with how it was caught: the FSD Architect's review of #2025, not this epic's own reading.

What's in the box: three named exit proofs, and as of 2026-09-22 all three are drawn as solid held slots because each has a filed child — ER-Devtool for FIX-1481 rows 4 and 6 plus FIX-1502 row 5, ER-DevForce for FIX-1496, ER-Collab for FIX-1497. None is drawn as passed, because none has been run. An open box asks whether W5 exits on five of the six checklist rows.

Every slot is full and not one is green. That is the whole change.

The path: four exit-proof lanes, every one now holding a ticket and none carrying a bar. FIX-1481 In Spec Review, FIX-1502 Backlog and BLOCKED BY FIX-1486, FIX-1496 In Spec Review, FIX-1497 Backlog with no spec. Every route dot is now in the accent colour, so the route is whole and entirely unrun.

The route is whole and entirely unrun. Two lanes now wait on epics W5 does not run.

Who owns what: seven cross-cutting rules by four columns. ER-1 is FIX-1497's, ER-3 and the new ER-26 are FIX-1496's, ER-2 is FIX-1481's, ER-18 is MET by FIX-1467. The done-condition row reads HELD in all three proof columns rather than NO CHILD.

ER-1, ER-2 and ER-3 gained names rather than roles. ER-26 earns the seventh row.

What's asked of you

One, and it is a scope call. The full six-part form is DECISIONS.md → Open 1; the short version:

Does row 5 mean an org-level surface standing apart from any one session, or is it satisfied by one session that already sees the whole organization? Row 5 is "open Devtool and see everything in this organization — every seat, every channel, who is in which." This PR previously said building it needs org identity on the flow and session list reads, which does not exist — FIX-1486, substrate, not a QA epic's. A 2026-09-22 POC settlement measured that false: an org-scoped collection with a client read is already served on the production list_collection_state route, cross-org isolated, negative control returning 403. What is left is not a cost, it is a judgment about the row's own words. Trade-off: building it costs app wiring, three lines on a shared L2 package's deliberately-closed contract (ER-17 territory), and a reader; exiting at five buys a launch claim on time and ships a proof with a known hole. Recommendation, now conditional: exit on five of six only if you read row 5 as requiring a surface beyond a single session; otherwise it is ordinary work and W5 should build it. The earlier unconditional exit at five is withdrawn — it rested on the premise the settlement removed. Changes my mind: your answer, not the world. I lean to the second reading, because "across the org in one place rather than per session" is what the row's Today column was complaining about. If wrong, both ways: exit at five when row 5 was cheap, and the DevTool cannot answer "what is open across the whole organization" at launch when it could have; build it when the row meant more, and you buy a surface that misses the row plus a change to a closed shared contract. The second is the worse error, which is why the recommendation is conditional.

Reviewers · look here

  1. The correction, and whether the epic should have caught it. The three-and-three split was restated on six surfaces here without anyone checking the claim underneath it. DECISIONS.md now carries a matching rule for decided in review: a child that defers part of a rule names the successor, and the epic verifies the name.
  2. ER-26's scope. It fences the runs, not the code. If that reads as sequencing FIX-1481 behind FIX-1496, the wording is wrong and it will cost real schedule.
  3. A second, smaller correction, inside the first. FIX-1481's and FIX-1502's own texts justify the row-5 block as a live BP-031 hole — a session's org comes from the request body. FIX-1442 (b48158a0d, Sep 21) closed that hole; handleCreateSession no longer consults body.orgId at all. The block still stands, on re-derived ground — not a security hole, an absent addressing axis. Recorded so no child cites the closed hole as live.
  4. The end-state POC trigger has fired. The merged spec said to revisit it the moment the last gap was filed, before any child starts building. They are filed. It is recorded as fired and unactioned, because building it is its own dispatch.

Not here: FIX-1496's artifact cut (its own gate), FIX-1481's approach (#2025), or whether FIX-1486 is the right blocker.

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1457 · Project: Workforce: Layer 2 Abstraction

Opened as a draft. No gate is moved by this PR and no approval label is applied. A material amendment needs renewed human approval before the children it affects proceed.

Engineering calls — decided along the way, no product sign-off needed
  • Premises re-derived rather than taken. Every load-bearing claim was checked against origin/main and Linear: FIX-1477's Roster collection, the absence of any references/ directory or seat ro: grant anywhere in the tree, openInventory's zero .ts/.tsx call sites under apps/, the three inventory collections being declared only on the workforce channel flow, and all eight FIX-1457 children with their live states.
  • One supplied premise failed and is corrected in the spec, not silently worked around: the BP-031 hole (reviewer note 3). One was inexact: FIX-1496's DECISIONS.md D1 heading still reads "a pull request on a separate throwaway repository" — the enacted cut lives in its PLAN.md S3, BR-14, BR-15 and its Decided, not asked item, after review round 1 collapsed two legs to one. The epic row cites those rather than D1, and there is no D3 in FIX-1496 — the channel decision is an anchored item under Decided, not asked, so that is what the row links.
  • Status carried, not tracked. FIX-1481 is In Spec Review, not Backlog as the merged snapshot said. Carried because the set table was being re-dated anyway; this is not a status-tick commit.
  • Word budgets, re-measured — and the figures this bullet opened with were stale, not wrong. Method, stated so the numbers are reproducible: words outside fenced code blocks, with whole markdown-image lines (the figure embeds and their alt text) removed, and link URLs dropped while their labels are kept. Current, against budget: SPEC.md 2,637 / ~900 · DECISIONS.md 4,645 / ~1,300 · BUSINESS-RULES.md 3,662 / ~800 · PLAN.md 2,147 / ~900 · DOCS.md 1,175 · EVOLUTION.md 2,287. The six numbers here when the PR was opened — 2,688 · 4,120 · 3,078 · 2,161 · 1,142 · 1,708 — described the tree at a3347bfe, and four commits have landed on this branch since, three of them rewriting BUSINESS-RULES.md or DECISIONS.md substantially. Measured at a3347bfe this counter reads 2,512 · 4,036 · 3,159 · 1,986 · 1,167 · 1,749 — within about 7% of the originals and differing in both directions, so the two counters broadly agree and the growth in the current column is real content, not a change of instrument. Every document was already over budget before this amendment and each has grown since. Reported rather than trimmed to fit, as on spec(epic): W5 — Workforce release QA: Devtool, a DevForce proof, multi-seat collab (FIX-1457) #1944.
  • Figures. All three redrawn, rendered in both themes and looked at. Three defects found that way and fixed: the box header overrunning its rectangle, and two note lines past the right edge. Overflow was then measured with getBBox() in the browser rather than estimated — widest text is 918px against a 940px canvas. One environment note for whoever renders next: spec-figures.md's <img>-based harness silently truncates these SVGs part-way down in headless Chromium, on the merged originals too. Navigating straight to the .svg renders them whole.
  • reviewRounds is untouched. An amendment folding filed children and a caught correction is not review feedback.
How to review this — an epic-spec, not an implementation plan

This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design.

In scope to challenge:

  • The objective — is this body of work worth doing, and is the outcome the right one?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in BUSINESS-RULES.md with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.
  • Shared promises and publication ownership in DOCS.md; missing or misleading
    predecessor treatment in conditional EVOLUTION.md.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's poc/
    show shape and scoping, not shippable implementation. Directional evidence, experimental
    isolation and absence of secrets/generated dependencies remain in scope.

Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.

Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.

🤖 Generated with Claude Code

https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz


Generated by Claude Code


Generated by Claude Code

@vercel

vercel Bot commented Sep 22, 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 22, 2026 4:29am UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 22, 2026 4:29am UTC
flow-state-dev-ui Ignored Ignored Preview Sep 22, 2026 4:29am UTC

Request Review

@linear-code

linear-code Bot commented Sep 22, 2026

Copy link
Copy Markdown

FIX-1457

…owned (FIX-1457)

Post-merge amendment to the retained epic spec at specs/epics/FIX-1457/, on a new
PR from main. #1944 stays the merged review record and is not touched.

Three changes, and one of them is a correction:

- ER-DevForce and ER-Collab stop reading "No producer". FIX-1496 (In Spec Review,
  #2023 @ 25e7507) and FIX-1497 (Backlog, no spec) take them. FIX-1496's artifact
  cut is recorded in the epic's own words: one automated leg pushing to a bare
  clone at a declared path, resolving after the goal's process exits with no gh,
  no token and no network; the credentialed PR leg documented as the human
  release run. Channels are recorded as inside the ratified criterion, not
  optional.

- ER-Devtool's row split is corrected from three-and-three to two-and-one-and-
  three. FIX-1481's spec deferred checklist row 5 on the claim that FIX-1477 PR-C
  already owned the reader. That claim was false: FIX-1477's Roster reads
  workforce/roster/*, FIX-1475's collection, while row 5 names inventory/*. Row 5
  went to FIX-1502, blocked by FIX-1486. Recorded in EVOLUTION.md as a correction,
  with how it was caught.

- ER-26 is new: no exit proof's run is graded before FIX-1496 stands a live hired
  Workforce up. It fences the runs, explicitly not FIX-1481's or FIX-1502's code
  PRs. Row 6 is the sharp case — no tree in the repository has a sealed document
  today.

Open 1 is replaced rather than answered: the staffing gap closed, and whether W5
exits on five checklist rows of six is now in front of the owner, six-part form
in DECISIONS.md.

All three figures redrawn and rendered in both themes; no text overflows,
measured in-browser rather than estimated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
@jhoffner
jhoffner force-pushed the epic/FIX-1457-producers-and-row-5 branch from 6dafee9 to a3347bf Compare September 22, 2026 02:31
jhoffner pushed a commit that referenced this pull request Sep 22, 2026
…ic text (FIX-1481)

Review fold on #2037. Two fixes.

The correction blockquote linked the epic's BUSINESS-RULES.md#er-devtool and
EVOLUTION.md for "the same correction". That content is on #2033, which is open
and still a draft based on current main, so a reader on main followed the link
and found nothing — the same defect this amendment exists to fix, reintroduced
by the fix. It now names the amendment PR instead and says outright that it has
not landed. The pre-existing ER-17, ER-24, ER-25 and the intro's ER-Devtool
links are untouched: all four resolve to text that is on main today.

The PLAN.md guardrail re-derived the mechanism a second time. Every other row in
that table points at a decision card and stops, and two copies of a mechanism is
how the first one goes stale. Trimmed to point at D2 with one clause, now that
D2's Because cell carries the full derivation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
The amendment's first draft carried a false mechanism claim: that the session
listing "withholds every row that is not on that org". It does not.
`handleListSessions` filters on

  isOrgAttributed(s) && (allowed === undefined || s.orgId === DEFAULT_ORG_ID)

and `allowed` is `ctx.anonymousFlowIds`, which is never set on the pure
no-resolver path at all — `authorizeManagementRoute` returns ALLOWED at its
first guard when the host is on the default resolver and no flow authenticates.
The second conjunct is vacuously true and only unattributed legacy rows are
withheld; the DEFAULT_ORG_ID narrowing reaches that filter solely in the
mixed-app anonymous case. It was irrelevant as well as wrong — that route lists
sessions, not inventory resources.

Caught on sibling PR #2037; this wording now matches its re-derivation, per the
Architect's sibling gate. The epic carried the identical sentence rather than a
safer paraphrase, so it needed its own fix.

Replaced with the claim that survives, verified end to end on origin/main:

  The axis is missing because nothing can NAME an org — not because no org
  is reachable.

Four gaps behind it: openInventory has no call site under apps/; the three
collections are scope:"org" with no `client` config so the state-read route
refuses them 403; the read is session-addressed against the owning flow, which
only the workforce channel flow declares; and an org-scoped read's identity is
the session's org, with body.orgId never consulted (FIX-1442) and no orgId query
parameter on any engine route.

Also dropped an over-citation of my own: resources/internal.ts states the BP-031
invariant for the external-collection path, and these three are not external, so
gap 4 now rests on the two facts verified exhaustively instead.

Corrected in BUSINESS-RULES.md, SPEC.md, DECISIONS.md (D1 addendum and Open 1),
PLAN.md and EVOLUTION.md. ER-26, the producers, row 5's re-owning and the
conclusion are unchanged — row 5 still deferred, still FIX-1502, still blocked
on FIX-1486.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
…(FIX-1457)

Third pass on the same passage. The previous version still overstated it: "which
org is a question the surface cannot currently be asked" is wrong, because the
surface CAN be asked — it just always answers with the same org. Corrected in
all five places the set repeats it (BUSINESS-RULES.md, SPEC.md, DECISIONS.md D1
addendum and Open 1 plain-terms, PLAN.md, EVOLUTION.md), matching #2037's
re-derivation per the Architect's sibling gate.

The chain that survives, verified end to end on origin/main:

- the three inventory collections are scope:"org";
- an org-scoped read takes its storage key from the execution's orgId
  (createExecutionContext -> resolveOrgStorageKey), which is the org the session
  carries;
- that org is set once at creation from the configured resolver, with
  body.orgId never consulted (FIX-1442);
- the listing has no orgId query fallback by design.

Two corrections to my own previous text:

- The short-circuit is not that anonymousFlowIds is merely unset.
  authorizeManagementRoute returns ALLOWED at its FIRST guard when the host is
  on the default resolver and nothing authenticates, so the anonymous branch is
  never reached; the branch that is reached in a mixed app always returns a Set.
  So `allowed === undefined` means "no flow in this app authenticates".
- The listing clause is dropped rather than repaired. handleListSessions lists
  sessions; the rule is about reading inventory resources. It did no work in the
  argument even when true.

Also removed an unverified premise I had asserted: that nothing under
packages/devtool, packages/fsdev or apps/devtool configures a resolvePrincipal.
No single artifact is confidently "the shell flow", so the text is conditional
now — "where no resolver is configured it is DEFAULT_ORG_ID" — which is true of
the code regardless of which app is meant.

ER-26, the producers, row 5's re-owning and the conclusion are unchanged.

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

Copy link
Copy Markdown
Collaborator Author

W5 EM — hold on Open 1. My recommendation in it may be wrong, and I am settling the question with evidence rather than a fourth round of inference.

The mechanism correction in c789af5cc is done and matches #2037. The rest of this amendment stands — ER-26, the two producers, row 5's re-owning, the conclusion. This note is about the Open item only.

What changed my confidence

Correcting the mechanism narrowed the claim from "there is no org to address" to "you cannot choose the org." Those are different, and the difference cuts at the recommendation:

W5's own boundary is one user, one org. With a single organization, reading DEFAULT_ORG_ID is reading the whole world. FIX-1486 supplies selection among orgs, which a single-org deployment does not need. So inside W5's scope, FIX-1486 may not be a hard blocker for row 5 at all.

What would actually block it then is thinner: nothing calls openInventory so no rows exist; the three collections declare no client config and their factories are option-free; and no reader is built. That is closer to ordinary unbuilt work plus one small change in a shared package than to waiting on substrate this epic may not build — which is the premise my recommendation rests on.

One further finding that lowers the cost: the three collections are already declared on channel flows (inventoryWriterActions installs them on the register-channel and register-seats handlers). So a channel's own session is already a session whose owning flow declares them — if they carried a client read, the production route would serve org-scoped inventory with no new flow, which matters because ER-Devtool forbids code written only to make the inspection possible.

Why I am not acting on it

It is traced, not run. This exact passage has now been wrong three times, each time from reasoning about handlers instead of executing them. No org-scoped collection with a client read exists anywhere in the repo to copy, so "it would just work" is unproven.

A settle-claim is running: one client-read line on a throwaway org-scoped collection, one session, one GET on the production route with no debug flag, plus a negative control that drops the read and shows the request refusing. It converts the whole question from argument to evidence in minutes.

A second question it will not answer, which is a judgment about the row rather than the code: whether a DevTool reading inventory through a channel's session satisfies row 5, or whether the row's words ask for an org-level view. That could reintroduce the block from a different direction, and it belongs with the owner alongside the five-of-six call rather than inside it.

What this means for the gate

DECISIONS.md → Open 1 is untouched and still carries the original recommendation — treat it as under revision. If the settle-claim confirms the cheap path, that recommendation is probably wrong and will be rewritten before the owner is asked to decide. If it refutes or comes back inconclusive, Open 1 stands as written and the gate proceeds unchanged.

Nothing else on this PR is affected, and the sibling gate with #2037 on matched mechanism wording is satisfied as of c789af5cc.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect — coherence note on the Open 1 hold. Not owner approval / not the merge gate (shared login looks like Jake).

Sibling gate closed at c789af5cc. Spot-checked BUSINESS-RULES.md and DECISIONS.md Open 1 / D1 addendum on this head: selection-not-access, listing clause dropped (sessions ≠ inventory), body.orgId never consulted, no orgId query, conditional default-org wording. Matches the #2037 re-derivation the prior Architect note was waiting on. Mechanism surfaces agree; conclusion unchanged.

Hold on Open 1 — correct. Leaving the written recommendation in place while a settle-claim converts argument to evidence is the right process after three wrong inference passes on the same passage. Do not ask the owner on the current Open 1 prose until that run lands (or comes back inconclusive).

One fence the settle-claim must not silently answer. Route evidence can prove whether a channel-session client-read reaches org-scoped inventory without FIX-1486 on a single-org host. It cannot redefine row 5. The epic already recorded (Decided in review, salvaged from #1955) that checklist rows 3 and 5 need inventory/boards readable across sessions, and Open 1’s own distinct-value clause is across the org in one place rather than per session. A green GET through one channel session may be ordinary unbuilt work for access, and still fail the row’s words. That judgment stays with the owner beside five-of-six — not folded into the settle-claim write-up as if the code answered it.

D7 does not erase that fence. One-user / one-org means FIX-1486’s selection among orgs may be out of W5’s demo world; it does not make a single channel session the org-level inventory view the checklist asks for.

No two-direction fork. ER-26 (runs, not code), the two producers, row 5 → FIX-1502 blocked on FIX-1486, and the closed-hole correction all still cohere with #2023 / #2025 / #2037. Rest of the amendment stands as EM says. No Jake ping — Open 1 is paused for evidence, not forked.

— FSD Architect

The settlement came back CONFIRMED with a real negative control, and it
disproved the premise my recommendation rested on. Open 1 rewritten; nothing
else changed.

What the POC showed: an org-scoped collection with client.state.read is served
on the production list_collection_state route, cross-org isolated — two sessions
on two orgs against one flow through the real createFlowApiRouter, each seeing
only its own org's row, FSDEV_DEBUG_ENDPOINTS unset. Negative control with the
client read removed returns 403 "State read not permitted", so the gate fires
and the green is not a check that could only pass.

What that changes. Row 5 is not blocked on FIX-1486: its subject is selection
among organizations, which a one-user one-org deployment does not need. The
measured cost of building row 5 in W5 is calling openInventory (app wiring),
three lines adding a client read to the collection factories (small, but a
shared L2 contract, so ER-17 territory), and a reader.

What it did not settle, and is now the hinge: the run was one session reading
its own org. It says nothing about an across-sessions or org-wide view, and this
set already records that rows 3 and 5 need inventory readable across sessions.
A channel session declares the inventory collections, so reading through one
shows the whole org from a single place — which may or may not be what row 5
asks for. That is a judgment about the row's words, not a fact about the code,
so the document states both readings and picks neither.

Recommendation revised accordingly: exit on five-of-six ONLY IF the owner reads
row 5 as requiring an org-level surface beyond a single session; otherwise row 5
is buildable in W5 and should be built. Both failure directions are priced.

Also recorded the verdict under "Decided in review" with its two limits, which
is where orchestration.md puts a settlement so a sibling cannot reopen it.
A settlement costs no review rounds; reviewRounds is unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
… (FIX-1457)

Two surfaces said building row 5 inside W5 is the ER-25 growth the owner fenced.
That is false today whichever way the owner answers Open 1: row 5's READER was
never the fenced work — building org SELECTION is, and selection is FIX-1486's.
The settlement removed the premise under this clause the same way it removed it
under Open 1's old recommendation.

It mattered most in SPEC.md's set table, where a reviewer or the owner reaches
"blocked … ER-25 growth the owner fenced" and stops, never reaching the
question. A completion criterion gating on a superseded answer.

Both cells keep "blocked by FIX-1486" — a real Linear relation, still literally
true — and now point at Open 1 as the live question instead of asserting a fence.

PLAN.md's sentence also had an ambiguous pronoun: "it blocks FIX-1502 and is not
pulled in, because building IT under a QA epic is ER-25 growth". Read as
FIX-1486 that was true; read as row 5 it was false, and the ambiguity was the
defect. Disambiguated to "building org selection", with row 5's reader named as
explicitly not that work.

Left standing deliberately: BUSINESS-RULES.md:136, whose "it" is bound to
"supplying the ability to select one" in the preceding clause and so is about
selection, correctly; and the ":107" heading, which is framing rather than a
false claim. Both read better once the owner has answered.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
The POC settlement moved Open 1 and only that section was updated. Twelve other
prose surfaces, across all six documents, still asserted "row 5 is blocked by
FIX-1486" flatly, with no reference to the question that block now turns on.

The block is not deleted anywhere. It is conditionally true and the condition is
Open 1's answer: if row 5 means a surface standing apart from any session,
FIX-1486 (org identity on flow and session list reads) really is its blocker; if
one session that already sees the whole organization satisfies the row, it is
not. Each surface now says it turns on Open 1, in the form its document uses.

Swept by grepping the claim rather than the cited line numbers. Twelve prose
surfaces against the five that were flagged, so seven beyond them (pre-change
line numbers):

  SPEC.md:65   the "what replaces it" sentence                    [flagged]
  SPEC.md:169  the Corrected 2026-09-22 bullet in the sign-off    [flagged]
  DOCS.md:58   the third reader promise                           [flagged]
  PLAN.md:18   the path figure's caption                          [flagged]
  PLAN.md:68   milestone 6, closest to outright false             [flagged]
  SPEC.md:104  the mermaid caption's "one dashed edge in from below"
  PLAN.md:29   the FIX-1502 table row — Route, Consumes and Size cells
  PLAN.md:80   the Devtool-surface coordination seam
  BUSINESS-RULES.md:65   ER-Devtool
  BUSINESS-RULES.md:107  the "Why FIX-1502 is blocked" heading
  DECISIONS.md:115  D1's "half-fired" paragraph
  DECISIONS.md:172  the ownership matrix's prose

PLAN.md:29's Size cell still read "not startable inside W5 · building the read
here would be ER-25 growth" — the same clause efa779f struck from the two
cells it found. Row 5's reader was never the fenced work; org selection is. That
cell is the third instance and is corrected the same way.

EVOLUTION.md gains a dated correction row in the epic's own voice: the epic
asserted the block from reasoning and never ran it, a settle-claim POC measured
it false on the production list_collection_state route with a negative control,
and Open 1 changed shape. It names the prior row whose closing clause it
replaces. The objective does not move and no decision is reversed.

Deliberately unchanged: the three SVG figures and their alt text, which still
read BLOCKED BY. The drawings are accurate under the reading the owner may take,
and rather than redraw them ahead of the answer, the two captions that narrate
them now say which reading that is. Flagged for the coordinator.

Word counts, words outside fenced code blocks, before -> after:
SPEC 2577 -> 2637 · DECISIONS 4597 -> 4645 · BUSINESS-RULES 3608 -> 3662 ·
PLAN 2030 -> 2147 · DOCS 1167 -> 1175 · EVOLUTION 1895 -> 2287. Every document
was already over budget; measured and reported, not trimmed to fit, as on #2033.
This counter does not reproduce the absolute numbers in the PR body, so the
deltas are the load-bearing part.

No changeset: retained spec documents only (BP-022). validate-spec-folder.mjs
and validate-changeset-refs.mjs both pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
@jhoffner jhoffner added the spec label Sep 22, 2026
@jhoffner
jhoffner marked this pull request as ready for review September 22, 2026 11:45
@jhoffner
jhoffner merged commit ae91567 into main Sep 22, 2026
13 checks passed
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 22, 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-22T11:46:51.667479Z 2300b89 Draft marked ready
ℹ️ 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.

jhoffner added a commit that referenced this pull request Sep 22, 2026
…-1497)

#2033 merged, so ER-26 is in specs/epics/FIX-1457/BUSINESS-RULES.md on main
and the three sites that said "not yet on `main` / still a draft" were stating
something false.

BR-21, DECISIONS' soft-ordering bullet and PLAN's fence paragraph now link the
epic's rule directly. PLAN's fence paragraph asked for exactly this re-point
once #2033 merged; this is that.

Swept the claim rather than the string: also grepped "not yet on main",
"still a draft", "arriving with the epic amendment" and "2033" across all five
documents, both figures and the POC. One further hit, and it is the kind that
survives a citation sweep -- the Notes-from-review entry declining the density
note argued *because* ER-26 was not yet on main. That premise has lapsed. The
disposition stays as the record of what was decided and why, with a dated line
saying the condition it rested on is gone, rather than being silently rewritten
or left reading as a live argument.

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

@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 — direction is right, execution is heavier than it needs to be

The amendment does the right structural work: it closes the “no producer” gaps (FIX-1496/1497), corrects the false FIX-1477 hand-off with FIX-1502 for checklist row 5, records the org-read settlement, and reshapes Open 1 into an owner judgment instead of a false substrate block. I would not reopen the three-producer / two-and-one-and-three split — that matches how this repo runs epics (ER-23, FIX-1455-style producer rows).

What went too far is less the decisions than the amendment style: the same forensic narrative (four gaps, POC transcript, BP-031 correction, session-listing draft mistake, FIX-1496 artifact cut) is re-derived on most surfaces. That pattern is what let the original three-and-three error propagate; more copies raise drift risk now that Open 1 has two readings.

Cleaner alternative (if you want a slimmer follow-up edit on this PR)

  1. One canonical layer for row 5 + Open 1 — keep the full gate and settlement in DECISIONS.md (#open + #settled-org-read). Epic rules/checklist: invariants + links (~10 lines for mechanism). Move the long gap survey and the #2037 meta-corrections to EVOLUTION.md (or FIX-1502’s spec when it exists).
  2. Thin “proved by” cells — ER-DevForce’s table cell should be producer + one-line proof bar + link to FIX-1496; child BR IDs and artifact legs belong in the child spec only.
  3. Align visuals with Open 1 — path.svg / end-state.svg / ownership.svg still read as “row 5 blocked by FIX-1486” unconditionally; prose and PLAN step 6 already say that binds only under one reading. Either update figure copy/aria-labels or add a single legend in SPEC that figures assume reading A until the owner answers.
  4. Resolve the build-order contradiction — DECISIONS.md says nothing should start building until the end-state POC runs; PLAN.md step 2 already releases FIX-1481/1496 implementation behind direction gates, and ER-26 explicitly fences runs not code PRs. One scoped sentence (POC falsifies issue split / child boundaries; it does not block spec-approved impl) would remove a costly misread.
  5. Optional product simplification (owner, not doc-only) — if Open 1 resolves to “channel session view is enough,” row 5 may be app wiring + three client lines on inventory factories (reuse FIX-1477’s reader pattern on list_collection_state), and FIX-1502 might shrink or fold into FIX-1481. I’m not insisting on that here; it’s the simpler implementation path if the row words allow it.

Approve path

I’d be comfortable approving after the figure/Open 1 coherence fix and a light dedupe (at least ER-DevForce cell + checklist row 5 tail + POC transcript appearing once). The rest can be a fast follow-up if you prefer not to expand this amendment further.

No changeset needed (spec-only).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

| <a name="er-devforce"></a>**ER-DevForce** | **One DevForce path completes and produces a real artifact** — code, a PR, or a work product that exists outside the run — **not a mock and not a transcript**, with seats and channels used honestly rather than stubbed past | **No producer.** The first build slice is Done ([FIX-1426](https://linear.app/fixpoint-labs/issue/FIX-1426), [FIX-1410](https://linear.app/fixpoint-labs/issue/FIX-1410)); an end-to-end path is unfiled. **Which artifact counts is the EM's cut**, leaning on the owner, and is explicitly not blocking ([ER-11](#what-no-child-may-do) fences the size) |
| <a name="er-collab"></a>**ER-Collab** | **≥2 seats across ≥1 channel**: work **filed**, **assigned**, **drained**, and a **cross-seat handoff or reply observed in Devtool**. One graded scenario, run on the real path | **No producer.** Composes boards ([FIX-1385](https://linear.app/fixpoint-labs/issue/FIX-1385)), inventory ([FIX-1405](https://linear.app/fixpoint-labs/issue/FIX-1405)), manager-queue ([FIX-1430](https://linear.app/fixpoint-labs/issue/FIX-1430)), dispatch honesty ([FIX-1440](https://linear.app/fixpoint-labs/issue/FIX-1440)). *Observed in Devtool* makes it depend on ER-Devtool. **[FIX-1474](https://linear.app/fixpoint-labs/issue/FIX-1474) is not this producer** — its own body keeps this gate on today's separate paths and forbids widening it until that child lands |
| <a name="er-devtool"></a>**ER-Devtool** | **The documented Devtool checklist below is green on a live hired Workforce** ([ER-3](#what-every-exit-proof-must-satisfy)), **with no special wrapper** — no bespoke debug app, no fixture panel, no code written only to make the inspection possible | **Two producers, not one, since 2026-09-22.** [FIX-1481](https://linear.app/fixpoint-labs/issue/FIX-1481) (*In Spec Review*, [#2025](https://github.com/fixpoint-labs/flow-state-dev/pull/2025)) owns **rows 4 and 6**; [FIX-1502](https://linear.app/fixpoint-labs/issue/FIX-1502) (*Backlog*) owns **row 5**, the org-level inventory view, **blocked by [FIX-1486](https://linear.app/fixpoint-labs/issue/FIX-1486) in Linear under one reading of the row** ([Open 1](DECISIONS.md#open)); rows 1–3 ride [FIX-1320](https://linear.app/fixpoint-labs/issue/FIX-1320), which this epic does not run. **1481 still verifies the whole checklist**; 1502 builds the consumer 1481 deferred. **Nothing has been observed on a running workforce** — rows drafted below against what the surfaces expose today, **rows 4 and 6 fail as written**, rows 1–2 derived from source, and the run itself waits on [ER-26](#er-26). **A filed ticket is not a green row** |
| <a name="er-devforce"></a>**ER-DevForce** | **One DevForce path completes and produces a real artifact** — code, a PR, or a work product that exists outside the run — **not a mock and not a transcript**, with seats and channels used honestly rather than stubbed past | **[FIX-1496](https://linear.app/fixpoint-labs/issue/FIX-1496)**, *In Spec Review*, spec [#2023](https://github.com/fixpoint-labs/flow-state-dev/pull/2023) at head `25e7507`. A four-gap delta on the existing `goals/devforce-lab/`, not a new Lab tree. **Which artifact counts — the EM's cut, taken.** *Real* is three falsifiable properties, and the proof runs **one automated leg**: the temp-directory repository gains a **bare clone at a declared path the run pushes to**, so the artifact resolves at its address after the goal's process has exited, needing `git` and a temporary directory but **no `gh`, no token and no network** (its `PLAN.md` S3, `BR-1`, `BR-15`). The **credentialed pull-request leg is documented as the human release run** and is never inferred from whether `gh` happens to be installed (`BR-14`) — one leg in CI, and the verdict names which. **Channels are in, not optional:** 1496 kept channel driving rather than deferring it, because this rule's ratified wording says *with seats and channels used honestly rather than stubbed past*, which puts channels inside the criterion (its *Decided, not asked* → [the channel](https://github.com/fixpoint-labs/flow-state-dev/blob/spec/FIX-1496/specs/issues/FIX-1496/DECISIONS.md#channel)). **The cut is proposed, not approved** — 1496's own direction gate is still open, and this row records what it proposes, not a settled epic decision |

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: This proved by cell is acting as a shadow FIX-1496 spec (bare clone, BR-14/15, channel DECISIONS link, “proposed not approved”). Child specs are the right home for that depth; the epic row will drift on the next 1496 amend.

Suggest: one sentence on producer + thinnest artifact bar + link to #2023. Keep ER-11/D8 fences here only.

| 3 · **Boards** | For a workforce that ran a board, the board renders with its counts ribbon and per-row goal, status and assignee — **and which boards are open right now is answerable** | `task-collections-view` renders all of that from `task-change` / `task-board-meta` stream items, but it is **session-scoped**: a board is visible only by opening the session whose stream carried it. There is no standing board browser |
| 4 · **Parked rows** | A parked row is visible **with its reason** without expanding raw JSON, and Waiting-on-you reads as a view over parked + reason ([ER-2](#what-every-exit-proof-must-satisfy)) — **never as a new status value** ([ER-8](#what-no-child-may-do)) | **Fails as written.** `parked` is a status pill and a counts-ribbon entry; the row's columns are id, goal, status, assignee, child session, kind. **The reason is only inside the per-row `view` JSON expander** |
| 5 · **Inventory** | The three org-scoped inventory collections — `inventory/seats/*`, `inventory/channels/*`, `inventory/members/*` — are readable for a live org, so *who exists* and *who is in which channel* are answerable without walking folders | The Resources panel is **session-scoped** (`GET /sessions/:id/debug/resources`) and **off unless `FSDEV_DEBUG_ENDPOINTS=1`**. Inventory is reachable only through a session whose flow declares those collections; **there is no org-level inventory view** |
| 5 · **Inventory** · **[FIX-1502](https://linear.app/fixpoint-labs/issue/FIX-1502)** | The three org-scoped inventory collections — `inventory/seats/*`, `inventory/channels/*`, `inventory/members/*` — are readable for a live org, so *who exists* and *who is in which channel* are answerable without walking folders | The Resources panel is **session-scoped** (`GET /sessions/:id/debug/resources`) and **off unless `FSDEV_DEBUG_ENDPOINTS=1`**. Inventory is reachable only through a session whose flow declares those collections; **there is no org-level inventory view**. **Not buildable in W5 today** — see the paragraph below |

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.

Coherence with Open 1: The row still says “Not buildable in W5 today”, while Open 1 and the settlement argue row 5 may be ordinary W5 work if the row is satisfied by a channel session’s org-wide inventory view.

Consider tying Today to Open 1 explicitly (e.g. “blocked on owner reading of row 5” / “buildable if Open 1 → session-sufficient”) so implementers don’t treat FIX-1486 as a hard substrate block.

widen a read; a selection story says the work is an address the request can carry, which is the
shape FIX-1486 actually has.

> **Two corrections inside the correction, because this mechanism has now been got wrong twice.**

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 / altitude: The blockquote about this amendment’s wrong drafts (handleListSessions, #2037) is valuable forensic history but heavy inside BUSINESS-RULES (children inherit this file as rules, not changelog).

Recommend moving to EVOLUTION.md (you already have a 2026-09-22 row there) and leaving one invariant here: “gap is org selection, not access; do not cite closed BP-031 hole.”

the DevForce path at all — [ER-26](BUSINESS-RULES.md#er-26) now says every run is graded on the
workforce FIX-1496 stands up, which is a dependency the earlier draft did not have — and whether
ER-Devtool's six rows survive being split, now across **three** owners rather than two. A rough
end-state is what falsifies either. **Nothing should start building until it is run or deliberately

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.

Contradiction to resolve: “Nothing should start building until it is run or deliberately skipped” fights PLAN.md step 2 (1481/1496 may implement after direction gates) and ER-26 (“fences the runs, not the code PRs”).

If the end-state POC is still intended, scope it: e.g. falsifies the four-child division before parallel impl, not a global stop on spec-approved work. One sentence here + matching tweak in PLAN step 3 would simplify coordination.

| FIX-XXX · DevForce proof path | **ER-DevForce** — the **thinnest** DevForce path that completes and produces a **real artifact**, seats and channels used honestly | A reference app shows Workforce *can* run. A Lab shipping a work product is the evidence a launch claim rests on | **No child — named gap.** Not filed. First build slice is Done ([FIX-1426](https://linear.app/fixpoint-labs/issue/FIX-1426), [FIX-1410](https://linear.app/fixpoint-labs/issue/FIX-1410)); an end-to-end path has no owner. Scope fenced by [ER-11](BUSINESS-RULES.md) |
| FIX-XXX · multi-seat collab scenario | **ER-Collab** — one graded scenario: ≥2 seats across ≥1 channel, work filed → assigned → drained, and a cross-seat handoff or reply **observed in Devtool** | Multi-seat is the composition W3 and W4 exist to enable and the one nothing has run | **No child — named gap.** Not filed. Composes boards ([FIX-1385](https://linear.app/fixpoint-labs/issue/FIX-1385)), inventory ([FIX-1405](https://linear.app/fixpoint-labs/issue/FIX-1405)), manager-queue ([FIX-1430](https://linear.app/fixpoint-labs/issue/FIX-1430)) |
| [FIX-1481](https://linear.app/fixpoint-labs/issue/FIX-1481) · Devtool checklist | **ER-Devtool** (with FIX-1502) — the six-area checklist green on a live hired Workforce: roster, channels, boards, inventory, parked rows, resources + references, **with no special wrapper** | The inspector is how the other two proofs are observed at all. Without it, "it worked" is asserted from a log | **In Spec Review** · spec [#2025](https://github.com/fixpoint-labs/flow-state-dev/pull/2025). Owns **rows 4 and 6** — parked reasons, references vs resources — and **verifies all six**. **Row 5 is [FIX-1502](https://linear.app/fixpoint-labs/issue/FIX-1502)'s**, not its own: the 2026-09-20 three-and-three split was **corrected on 2026-09-22**. **Rows 1–3 ride [FIX-1320](https://linear.app/fixpoint-labs/issue/FIX-1320)**, an epic W5 does not run. **Nothing observed yet**; rows 4 and 6 still fail as written |
| [FIX-1502](https://linear.app/fixpoint-labs/issue/FIX-1502) · org-level inventory view | **ER-Devtool row 5** — a reader and view over `inventory/seats/*`, `inventory/channels/*`, `inventory/members/*`, so *who exists* and *who is in which channel* are answerable for a live org | The row FIX-1481's deferral left with no owner. Filed so the checklist is not silently five rows of six | **Backlog** · filed 2026-09-22, no spec. **Blocked by [FIX-1486](https://linear.app/fixpoint-labs/issue/FIX-1486)** in Linear — **you cannot *choose* the org**: a read always answers with the one the session already carries, and selecting another is the missing axis. **Whether row 5 needs that axis at all is [Open 1](DECISIONS.md#open)**, and it is the owner's: a 2026-09-22 POC settlement showed the production read already works and is cross-org isolated, so what is left is a judgment about the row's words, not a cost. **Row 5's reader is not itself the [ER-25](BUSINESS-RULES.md) growth the owner fenced** — org *selection* is |

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: This table cell is doing the job of DECISIONS.md#open (blocker, POC, ER-25 fence, five-of-six). The set table works best as scan surface.

Suggest a short cell: owner, status, blocked-by FIX-1486 under Open 1 reading A, link to Open 1 for the settlement and recommendation.

5. **W4's epic closes** → the ship fence lifts ([D4](DECISIONS.md#d4)). Polish does not wait on this.
6. **Org-bound execution is available** ([FIX-1442](https://linear.app/fixpoint-labs/issue/FIX-1442),
**On five rows or six** is [Open 1](DECISIONS.md#open), and it is the owner's.
6. **[FIX-1486](https://linear.app/fixpoint-labs/issue/FIX-1486) lands** → FIX-1502 unblocks under

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 sequencing: Step 6 says FIX-1486 “unblocks under every reading of row 5,” then immediately says it binds only under one reading (Open 1). Those two sentences fight each other.

Recommend: step 6 applies only if Open 1 requires org selection beyond session org; otherwise mark step 6 N/A for W5 exit (five-of-six path). That matches the settlement narrative and reduces duplicate FIX-1486 critical-path messaging.

<circle class="crith" cx="500" cy="474" r="3.2"/>
<text class="t-s" x="514" y="477">a proof with an owner &#8212; the route is whole, and unrun</text>
</g>
</svg>

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.

Figure vs prose drift: Visible label still reads BLOCKED BY FIX-1486 unconditionally, while PLAN.md prose (and Open 1) treat that as one reading of row 5.

Either qualify the label (e.g. “blocked if Open 1 → org-wide surface”) or drop the blocker badge and point to Open 1 — otherwise the path figure will keep contradicting the amended spec after merge.

jhoffner pushed a commit that referenced this pull request Sep 22, 2026
…d one import model

Three findings folded.

PLAN.md said "POC: none built" while this amendment adds poc/read-gate/ and
EVOLUTION cites it as the evidence. An implementer asking whether there is a
POC got two answers from one document. Split in two: none for the navigator,
whose premises are shipped code, and poc/read-gate/ for the two panel premises
that could not be read off the code.

read-gate-probe's second case was named for two claims — the refusal and the
ledger declaring no client config — and asserted only the first. The
declaration was a console.log, so half of what the test's name promised could
not fail. Now an assertion, with its own red state verified: assigning a client
config onto the ledger turns it red before the route is called. Recorded in
EVOLUTION as well as fixed, because it is the same defect class the rest of the
page is about, one level in.

premise-proof imported from "../src" while read-gate-probe imported by package
name, giving one POC folder two mental models. Both now import by package name.
Verified it resolves and passes that way rather than assumed.

Re-verified every cited line against main at 1196611 after rebasing across
#2027, #2033, #2034 and #2037; all still resolve. Observed output in the README
re-derived from a fresh run.

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