Repository navigation
Amend FIX-1481 spec: D2's stale BP-031 justification, BR-17's gloss, and a BR-16/BR-15 citation - #2037
Conversation
…n (FIX-1481) Post-merge amendment to the retained FIX-1481 spec. Two corrections, one root cause: a document that stopped matching what it points at. D2 deferred checklist row 5 partly on a BP-031 hole — that declaring a client surface on the inventory collections opens an org-scoped read on a session whose org is caller-supplied, because no principal resolver is configured. That hole was already closed when the spec was written. FIX-1442 (b48158a, merged 2026-09-21) made handleCreateSession bind `orgId: ctx.principal?.orgId ?? DEFAULT_ORG_ID`, and the comment beside it reads "`body.orgId` is deliberately not consulted, at all." The claim came from the epic coordinator off a stale checkout, not from the spec author. D2's conclusion is unchanged: row 5 stays deferred, still FIX-1502's, still blocked on FIX-1486. Only the third justification moves, and it re-derives to something true — with no resolver every session binds to DEFAULT_ORG_ID and the listing withholds every row not on it, so *which org* is a question the surface cannot be asked. An absent addressing axis, not a security hole, which is exactly what FIX-1486 supplies. Four occurrences in DECISIONS.md (the tree's X4 node, D2's Because cell, the Considered-and-dropped row, the How-it-got-here line) plus the PLAN.md guardrail that cited BP-031. A dated correction note records the wrong claim and why it was wrong. Framing matches the epic's own record of the same correction in FIX-1457's BUSINESS-RULES.md and EVOLUTION.md (PR #2033). Separately, DOCS.md cited BR-16 (the scope badge stays put) where it meant BR-15 (an older server sends neither flag, so no mark anywhere). The sentence was right; only the pointer was wrong. A sweep of every BR citation in the spec set found no other mismatch. No code, no changeset — retained spec documents only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
Simplify review
Verdict: Approve. The substantive work here is the right minimum: sweep every surface that still read like a live BP-031 hole, rewrite D2 on true ground (absent org addressing axis + FIX-1486 / FIX-1502), and fix the BR-15 pointer. I spot-checked handleCreateSession on main; the FIX-1442 framing matches the code.
Could this have been smaller? Yes, a little — not by skipping the sweep.
| Layer | Necessary? | Note |
|---|---|---|
Mermaid X4, D2 Because, Considered and dropped, PLAN guardrail |
Yes | Anything less leaves citation-toxic text in a merged spec |
DOCS.md BR-16 → BR-15 |
Yes | Trivial, correct |
| ~17-line Correction blockquote | Defensible, optional | FIX-1476-style retention when the retracted sentence looks like an open security hole; not required if Because + one How it got here bullet are trusted as the audit trail |
| How it got here amendment bullet plus the blockquote | Redundant | Pick one primary surface; I'd keep the blockquote or the bullet, not both |
| Coordinator / stale-checkout attribution in the blockquote | Taste | Unusual in specs/; fine if you want provenance on the record, skippable if you want the card to stay implementer-facing |
| Dense Because cell (handler name + path + two Linear links in one table cell) | Trade-off | Accurate; a shorter middle clause with the cite once in PLAN would scan easier |
Cleaner alternative (if you want a follow-up trim, not a merge blocker): inline rewrite only + one dated How it got here bullet + link to epic EVOLUTION.md (#2033) for the shared FIX-1442 story — same pattern as FIX-1457's "Corrected — factual" rows, without re-quoting the wrong claim and the commit comment on the issue card.
Epic cross-ref: The blockquote points readers at epic EVOLUTION.md for "the same correction." That entry lives on the open epic amendment #2033, not on main yet. Worth a quick read once #2033 lands so nobody follows the link to a row that isn't there on their branch; the link is directionally right for the intended end state.
Performance / reuse: N/A for markdown; reuse pattern matches post-merge factual amend policy. No code changes needed.
Happy to merge as-is; the extra narration is modest redundancy, not wrong direction.
Sent by Cursor Automation: Review For Best Approach
…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
|
Review fold pushed as Taken — the epic cross-reference. This was the sharp one, and it is worth naming as more than a link nit: the blockquote pointed at I checked the other four epic links in the three changed files while I was there — the intro's Taken — the Declined — dropping either the blockquote or the Declined — removing the attribution. Agreed it is unusual in On the dense Because cell: noted as a fair trade-off. Leaving it, because the handler name and the exact expression are what make the claim checkable without leaving the page — the property this correction exists to restore. Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1534c49c69
ℹ️ 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".
|
FSD Architect — coherence note on the fold. Not owner approval / not the merge gate (shared login looks like Jake). Fold on One load-bearing precision left — Codex’s P2 on D2’s Because cell is real. Spot-checked
What still holds (and is what #2033 already says more carefully): Codex’s other P2 (epic links to unlanded text): already answered by Sibling coherence: #2033 (draft) and this PR agree on conclusion and on not citing the closed hole as live. No two-direction fork. Tighten the mechanism here so the retained issue card does not become the sharper-but-wrong quote source while the epic stays vaguer-but-safer. — FSD Architect |
|
W5 EM — Codex's P2 on the Because cell is right, and one correction to the Architect's note: #2033 is not the safer of the two. It has the identical sentence. The finding stands, and the wrong text is mineI supplied the replacement premise. Both halves Codex names are wrong, and I confirmed it by reading
So this amendment replaced a wrong justification with another wrong justification. That is worse than the original defect, not better, and it is the second time I have written this passage incorrectly — both times by reasoning about the handlers instead of reading them. Correction to the coherence note
It does not. Both are being re-derived. #2033's fix is dispatched, and this PR's is in progress. What survives, and the altitude it will be written atNarrow, and each part verifiable in one handler:
Which org is a question the surface cannot be asked. Absent addressing axis, not a security hole — and that axis is exactly what FIX-1486 supplies, which is why FIX-1502 is blocked on it. D2's conclusion does not move. Row 5 stays deferred, stays FIX-1502's, stays blocked on FIX-1486. Only the mechanism sentence changes, and it gets narrower. Codex's other P2 was already answered by Generated by Claude Code |
|
FSD Architect — follow-up on the EM reply. Not owner approval / not the merge gate (shared login looks like Jake). Retract: the earlier note that #2033 was “vaguer-but-safer” was wrong. Same false listing sentence on both, same brief — EM is right that fixing this PR alone would leave the epic to merge the identical claim. Altitude accepted. The three verifiable halves named in the reply are exactly the re-derivation this card needs:
That keeps “absent addressing axis, not a security hole,” keeps D2’s conclusion, and does not re-introduce the two incorrect mechanism sentences Codex and the spot-check named. Sibling gate: both this PR and #2033 must land that same narrow wording before either merges. EM says #2033’s fix is already dispatched and this one is in progress — good. Will re-read the folded text on the next push; no further action until then. No Jake ping — no new two-direction fork; same correction, both surfaces, already owned. — FSD Architect |
…om reasoning (FIX-1481)
Codex was right, and the replacement premise was wrong in two ways. Both are
fixed by reading the handlers rather than reasoning about them.
Wrong: "the listing beside it withholds every row not on that org." In an app
where no flow authenticates and the host resolver is the default,
authorizeManagementRoute returns ALLOWED ({}) before ever reaching the
anonymous branch, so ctx.anonymousFlowIds is undefined. The listing's filter is
`isOrgAttributed(s) && (allowed === undefined || s.orgId === DEFAULT_ORG_ID)`,
so the disjunction short-circuits true and every org-attributed row survives
whatever its org. The DEFAULT_ORG_ID conjunct only bites for an anonymous
caller in a MIXED app, where unauthenticatedFlowIds() makes allowed a Set. The
listing was also beside the point: it lists sessions, not inventory resources.
Wrong: "DEFAULT_ORG_ID, the only org a session can bind to." With a resolver
configured, handleCreateSession binds ctx.principal.orgId. Only the no-resolver
case falls through to the default.
What replaces them is narrower and verified end to end: the three collections
are scope: "org" (packages/workforce/src/inventory/collections.ts); an
org-scoped read resolves its storage key from the execution's orgId
(createExecutionContext -> resolveOrgStorageKey), which is the org the session
carries; and that is set once at creation from the configured principal
resolver, never from the caller. So a client config opens onto whichever org
the session already holds, and no surface accepts "show me organization X".
The axis is missing because nothing can NAME an org, not because no org is
reachable.
D2's conclusion is unchanged, and its other two legs are untouched.
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
… the data (FIX-1481)
BR-17 answered "what does the mark mean" with "immutable to everyone — the
store refuses the write." That overstates it in two directions, and the same
overstatement was in DOCS.md twice.
`writable: false` closes the state-write and content-write doors on the handle
that declares it. It does not seal the storage cell — a seat's read-only view
is a shallow copy of the declared entry (workforce/src/seat-resources.ts ->
readOnly), so the same org or user cell stays writable through a flow that
declares it writable. And on a collection the flag gates
persistNamespaceInstanceState and the instance writeContent only; create
(including { replace: true }), getOrCreate and delete never consult it
(engine/src/context/resource-registry.ts), filed as FIX-1510.
Swept the five spec documents for the claim rather than fixing the cited spot:
three occurrences, not the one that was reported. DECISIONS.md and PLAN.md
carry only the inverse rule (absent means writable), which is correct.
The predicate is unchanged and no CI proof moves. BR-10..BR-16 stand as
written; the mark is still `writable === false` and nothing else.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
… list (FIX-1481) "gates persistNamespaceInstanceState and the instance writeContent only" is true at the function level and misreads as an operation list. upsert on an existing key routes through persistNamespaceInstanceState and is refused the same way (resource-registry.ts:1541, patch branch), which apps/docs/docs/resources/collections.md already states at the operation level. Reworded so the "only" attaches to the lifecycle carve-out it was about. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
…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


Post-merge amendment to the retained FIX-1481 spec. Three corrections with one root cause: a document that stopped matching what it points at. #2025 stays the merged review record and is untouched.
No decision changes here. D1, D2's conclusion, the predicate, the plan's sequencing, the POC and all code are as merged.
1 · D2 cited a BP-031 hole that was already closed
D2 defers checklist row 5. Its third justification said that declaring a client surface on the inventory collections "opens an org-scoped read on a session whose org is caller-supplied where no principal resolver is configured."
That hole was closed before the spec was written. FIX-1442 (
b48158a0d, merged 2026-09-21) replaced thebody.orgIdfallback inpackages/engine/src/routes/session-routes.tswithorgId: ctx.principal?.orgId ?? DEFAULT_ORG_ID, and the comment beside it now reads "body.orgIdis deliberately not consulted, at all." That commit is onmainand was onspec/FIX-1481too.The stale claim was the epic coordinator's, not the spec author's — handed over from a stale checkout and repeated in good faith. The correction note says so.
What is true instead. The three inventory collections are
scope: "org", so a read resolves against the org its session is bound to. That binding is made once, at creation, from the configured principal resolver and never from the caller, and where no resolver is configured it isDEFAULT_ORG_ID. Aclientconfig would therefore open the door onto whichever org the session already carries; show me organization X stays unaskable. Not a security hole — an absent addressing axis, which is what FIX-1486 supplies and therefore why FIX-1502 is blocked on it.Row 5 is still deferred, still FIX-1502's, still blocked on FIX-1486. Only the ground under one justification moved.
Four occurrences fixed in
DECISIONS.md(the decision tree'sX4node, D2's Because cell, the Considered and dropped row, the How it got here line) and one inPLAN.md(a guardrail that cited BP-031 as its reason). A dated correction note under D2 records the wrong claim and why it was wrong, so a reader who meets the old wording elsewhere lands on the retraction — a live-looking security hole in a decision card is the kind of thing that gets cited onward.Framing matches the epic's own record of the same correction in FIX-1457's
BUSINESS-RULES.mdandEVOLUTION.md(#2033) rather than inventing a second account.2 · BR-17 promised more than the mark delivers
BR-17 answered what does the mark mean with "immutable to everyone — the store refuses the write." That overstates it in two directions:
packages/workforce/src/seat-resources.ts→readOnly), so the sameorgorusercell stays writable through a flow that declares it writable.persistNamespaceInstanceStateand the instancewriteContentonly.create(including{ replace: true }),getOrCreateanddeletenever consult it — filed as FIX-1510.Both verified against
packages/engine/src/context/resource-registry.tsonorigin/main.This surfaced from the other end: #2039 had to narrow the tooltip and the published page to say the true thing, which left the spec asserting what the implementation had just stopped claiming.
Swept the five documents rather than fixing the reported spot — three occurrences, not one (BR-17, and two bullets in
DOCS.mdincluding the framing sentence nobody had flagged).DECISIONS.mdandPLAN.mdcarry only the inverse rule, absent means writable, which is correct and untouched.The predicate is unchanged and no CI proof moves. BR-10 … BR-16 stand as written; the mark is still
writable === falseand nothing else.3 · DOCS.md cited BR-16 where it meant BR-15
The sentence is right; only the pointer was wrong. BR-16 is the scope badge staying put. BR-15 is the older-server rule.
Swept every
BR-<n>citation in the spec set (DECISIONS.md,PLAN.md,DOCS.md,BUSINESS-RULES.md, the POC) against the rule table. This was the only mismatch — the merged numbering runs BR-1 … BR-19 with no gaps. BR-16's two other citations (PLAN.md S3 and V3) are correct.Parts worth reviewing closely
Verification
node scripts/validate-spec-folder.mjs— passnode scripts/validate-changeset-refs.mjs— passb48158a0dconfirmed an ancestor oforigin/main;handleCreateSessionread directly fromorigin/mainwritablegates (single state/content, collection state/content) andreadOnly's shallow copy read directly fromorigin/mainNo changeset: retained spec documents only, no published package touched (BP-022).
Links
FIX-1481 · merged spec review #2025 · implementation #2032 · #2039 · epic amendment #2033 · FIX-1442 · FIX-1486 · FIX-1502 · FIX-1510
🤖 Generated with Claude Code
https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz