Skip to content

spec(FIX-2058): align the epic with its four merged child specs - #3776

Merged
jhoffner merged 2 commits into
mainfrom
spec/FIX-2058-amend-4
Oct 23, 2026
Merged

jhoffner merged 2 commits into
mainfrom
spec/FIX-2058-amend-4

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Post-merge amendment to the retained epic spec for FIX-2058. No new direction. All four child specs (FIX-2129, FIX-2131, FIX-2132, FIX-2133) are merged on main. Where they differ from the epic, they are canonical, and this PR brings the epic in line with them.

What changes

Before After
Old data (owner, 2026-10-23: "I don't care about old data. For now we will be resetting everything.") ER-5: rows parked before the refactor read through FIX-2080's map; FIX-2131 adds park entries Stores are reset and nothing persisted before this work is read. No retired-shape map entries for parks, no migrated questions, BP-030 dual-read waived for this epic's persisted shapes. ER-5, the map seam row, the in-flight parks bullet, the debt table and the ownership figure all updated; dated owner line in the decision log
D2 Locks in "a steer into a held task is its answer" "a steer naming the question is its answer" (ER-8); the steer-admission seam matches
Held question's deadline "the sweeper's" the board's debt pass (ER-8, FIX-2133), in the decided-in-review list, Open, and the Open figure
The hold updateTask status: "held" the row's open questions, beside FIX-2080's held flag (both must clear), per FIX-2133 D2
The mark waitingOn: "person" "user", a plain rename (FIX-2129); the stored old value is not read. D2 card, debt table, D2 figure
Edges FIX-2137 → FIX-2129 "approval resumes" only; FIX-2137 → FIX-2132 "may drop" FIX-2137 (Done) blocks every FIX-2129 resume and stays on FIX-2132: a host's own harness block, judge or hook can ctx.suspend (FIX-2132 D1). New dashed merge-order edge FIX-2132 → FIX-2131 (FIX-2131 merges after it). No FIX-2063 → FIX-2132 edge exists
One wait per turn not stated the claim-gate seam points at FIX-2133's rule (a refused stop cancels the losing suspension)
Links ER-7/ER-8 pointed at spec/FIX-21xx branches, "pending merge" relative links to the merged specs on main

human_approval / human_input aren't named anywhere in the epic, so nothing points at FIX-2151.

Reviewers · look here

  • ER-5 (DECISIONS.md, Who owns what): does it still leave any path that reads a pre-reset row?
  • The graph (SPEC.md, How the issues flow into each other): the merge-order edge is dashed and the prose says it is order only, not a hand-off.

Checks

  • node scripts/validate-spec-folder.mjs: pass.
  • spec-figures verify: fences balanced, no unquoted risky mermaid labels, every referenced figure exists. The three edited SVGs pass xmllint and were rendered in light and dark with headless Chromium; no overflow.

SPEC.md · DECISIONS.md · child specs: FIX-2129 · FIX-2131 · FIX-2132 · FIX-2133

https://claude.ai/code/session_01Vdxnv28JumHyq2za2ybqz6


Generated by Claude Code

Owner, 2026-10-23: stores are reset and no old data is read. ER-5, the
retired-shape map seam and the in-flight parks line now say so: no map
entries for parks, no migrated questions, BP-030 dual-read waived for
this epic's persisted shapes.

From FIX-2129, FIX-2131, FIX-2132 and FIX-2133 as merged: waitingOn
"user" (plain rename); a steer naming the question answers it; the
board's debt pass pays a held question's deadline; the hold is the
row's open questions beside the held flag, not status "held"; FIX-2137
(Done) blocks every FIX-2129 resume and stays on FIX-2132; FIX-2132
merges before FIX-2131; one wait per turn points at FIX-2133. Links to
the child specs now resolve on main.

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

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2058

@vercel

vercel Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 23, 2026 9:00pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 9:00pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 9:00pm UTC

Request Review

Copy link
Copy Markdown
Collaborator Author

from: epic-coordinator
session: FIX-2058
kind: review

@codex review

Please check only two things at 13ec2b80:

  1. The epic (specs/epics/FIX-2058/SPEC.md, DECISIONS.md and its figures) now agrees with the four merged child specs on main: specs/issues/FIX-2129, FIX-2131, FIX-2132, FIX-2133. Where they differ, the child specs are canonical.
  2. The epic carries no remaining pre-reset data path. The owner reset stores on 2026-10-23, so nothing persisted before this work is read: no retired-shape map entries for parks, no migrated questions, no BP-030 dual-read for this epic's persisted shapes.

Areas I'm least sure of: ER-5's wording; the dependency graph's new dashed FIX-2132 → FIX-2131 merge-order edge; FIX-2137 now drawn as blocking every FIX-2129 resume, where FIX-2129's own Depends on still says "for approval resumes".


Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 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-10-23T21:03:58.975645Z d1f8398 Manual request
ℹ️ 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 (spec-only PR, so "architecture" here means the spec set's coherence)

The approach is right: one aligning amendment, child specs canonical, no new direction. I checked every changed link and anchor against main (FIX-2129 D2, FIX-2131 D1, FIX-2132 D1, FIX-2133 D1 and Decided, not asked); they resolve. No restructuring is warranted. Findings, most important first:

1. FIX-2137 scope: the epic now contradicts the child it says is canonical (needs a decision, not a drive-by)

The PR rule is "where they differ, the child is canonical." But FIX-2129/SPEC.md:151 and :170 still say FIX-2137 blocks approval resumes only, while the epic (SPEC.md table row and the new K --> E/K --> B edges, DECISIONS.md ownership prose) now says every FIX-2129 resume. The coordinator flagged this in the @codex review request, but the PR doesn't resolve it. Pick one:

  • Recommended: narrow the epic back to "approval resumes" (the child's wording, and FIX-2137 is Done, so the edge is historical anyway). Zero child edits, and the "child is canonical" rule holds.
  • Or amend FIX-2129 to "every resume" in a separate PR. That reopens a merged spec for a Done bug's edge, which isn't worth it.

2. One link missed in the "Links" conversion

DECISIONS.md ER-1 still cites [FIX-2129 D1](https://github.com/.../pull/3735). The PR description says ER-7/ER-8 links moved to relative merged-spec links, but this one still points at the review PR. Change it to ../../issues/FIX-2129/DECISIONS.md#d1 (D1 exists there: the deadline behaviour).

3. ER-5 now says the same thing twice

ER-5's first sentence ("No row persisted before this work is read: stores are reset") fully subsumes its last sentence ("States in flight between the refactor epics get no shim"). Drop the last sentence, or the "In-flight parks" bullet in Decided in review and ER-5 will drift apart. Answering the reviewer prompt: I found no remaining path in the epic that reads a pre-reset row. Remaining parked mentions are the status being removed.

4. "Net: down" claim and ER-5's owner

ER-5 is now a negative rule (nothing to build). FIX-2131 stays its owner, which is fine. But the Debt Adds row lost "retired-shape map entries" while Removes still lists only features, so "Net: down" is now conservative. No change needed; mentioning it so nobody re-adds the map entry later.

5. Wording nits

  • "the board's debt pass's" (DECISIONS, Decided in review) reads badly; use "the board's debt pass (ER-8)".
  • SPEC.md still says "the sweeper" for FIX-2063/the graph label. That is the durability sweeper, a different thing from the old question-deadline "sweeper" this PR renamed. Fine, but consider "durability sweeper" in the graph edge label to keep the two from being confused.

Not a finding

The dashed FIX-2132 → FIX-2131 merge-order edge is correct: both child specs state "merges after FIX-2132" (FIX-2132/DECISIONS.md:89, FIX-2131/SPEC.md:178), and the prose says order only, not a hand-off.

Nothing here is blocking except #1, which needs a call on which side is canonical.


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

To use Codex here, create an environment for this repo.

@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

Scope: Five files vs main — post–child-merge epic amendment only. That is the right shape: amend on main after FIX-2129 / 2131 / 2132 / 2133 spec PRs land, not a second full epic or a branch still carrying those trees.

Did the approach go too far?

No — this PR mostly moves complexity out of the epic, not in:

  • ER-5 drops the retired-shape migration map story in favor of store reset + no BP-030 dual-read. That is simpler for implementers than “one map owner maps every parked row.”
  • Relative links into specs/issues/… replace stale blob/spec/… URLs and “pending merge” noise — less maintenance, fewer two-source-of-truth links.
  • Hold model in the coordination seam is corrected (open questions on the row, not updateTask status: "held" as the hold).

The main place the epic still overshoots the template (“coordination artifact, not design nobody signed off”) is pre-existing volume, not introduced by this amend: ER-8 and the “The hold” coordination-seam row still embed FIX-2133-level protocol. This PR adds a useful pointer (decided-not-asked, losing-suspension cancel) but does not shorten that cell. I would not block merge on that — child specs are now canonical on main; a follow-up amend could collapse that row to owner + link if you want a leaner epic.

Simpler alternatives considered

Alternative Verdict
Re-land full child spec trees in this PR Worse — duplicates authority already on main via #3734–#3747; inflates review for no gain.
Bundle FIX-2137 implementation here Out of scope — not in this diff vs main; keep impl on its own PRs.
Trim ER-8 / hold seam to links only in this amend Nice follow-up, not required for alignment correctness.
Skip SVG aria-label / label tweaks Marginal — small churn but keeps figures consistent with waitingOn: "user" and debt-pass wording.

Subagent passes

  • Code quality: Duplication of “stores reset / no old data” across ER-5, “Decided in review,” and changelog is intentional anti-reopen glue; slightly heavy but acceptable for an owner call.
  • Performance: N/A (spec-only).
  • Reuse: Matches epic-spec-template.md amend workflow; consider FIX-2077-style deferral in child specs still using blob/spec/ links (separate small amends).

Nit (non-blocking)

ER-1 still cites FIX-2129 D1 via PR #3735 while ER-7/ER-8 now use repo-relative anchors — worth normalizing in a later pass for consistency.

Approval: Directionally correct, right-sized diff, and the store-reset pivot is a cleaner epic story than the map migration path. Merge when your spec gate is satisfied.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-2058/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2058/DECISIONS.md Resolved
Comment thread specs/epics/FIX-2058/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: 13ec2b80ea

ℹ️ 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/epics/FIX-2058/SPEC.md Resolved
FIX-2129's merged spec names FIX-2137 for approval resumes only; the
child spec is canonical here (Codex on #3776).

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

Copy link
Copy Markdown
Collaborator Author

from: epic-coordinator
session: FIX-2058
kind: review

@codex review

Please check d1f8398, which narrows FIX-2137's scope to FIX-2129's approval resumes. Is there anything else in the epic that no longer agrees with the four merged child specs, or that still relies on data persisted before the reset?


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

from: epic-coordinator
session: FIX-2058
kind: reply

On 13ec2b8, "Test (2/3)" failed in @flow-state-dev/orchestration, in test/tasks/notice-claim.test.ts › "a notice held a while for its filing request is heard within seconds of that request's park" (sqlite), with expected [ { boardId: 'waits', … } ] to deeply equal []. This PR is not the cause: it changes only specs/epics/FIX-2058/** (Markdown and SVG), and no code or test reads those files. The test is a timing assertion that came in recently with FIX-2149. No fix exists yet. CI is re-running it on the new head, d1f8398. If it fails there too, I'll file it against FIX-2149's area rather than widen this spec PR.


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: d1f8398222

ℹ️ 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".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants