Skip to content

spec(epic): FIX-1649 wrap, the path as shipped and leg c as the closure checks it - #2714

Merged
jhoffner merged 3 commits into
mainfrom
spec/FIX-1649-wrap
Oct 4, 2026
Merged

jhoffner merged 3 commits into
mainfrom
spec/FIX-1649-wrap

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 4, 2026 •

Copy link
Copy Markdown
Collaborator

Wrap amendment to the retained FIX-1649 epic spec, opened after the epic's work finished. The closure, FIX-1663 (#2709, 894c418d2), passed on 01444863c with every control right. This PR changes only specs/epics/FIX-1649/. The original review record stays #2421.

What changes

1. The path as it actually shipped. figures/path.svg used to show the 30 September plan as phases. It now has one lane per issue or group, dated 30 Sep to 4 Oct, each bar running from when the issue was filed (or the gate) to when it merged. The lanes cover the first build, closure run 1's fixes, FIX-1690, design v2, FIX-1722, 1723 and 1725, the late fixes (FIX-1730 to 1735, 1747, 1749), FIX-1736, FIX-1737's four slices, FIX-1650's inputs, and the closure's runs until one was clean.

The path as it shipped, 30 September to 4 October 2026, one lane per issue, with the critical path outlined through design v2, FIX-1736, FIX-1737 and the clean closure run

The longest wait was v2's look, not the shell: the structure merged on day one.

2. The closure's goal check is now the one home for how legs a to c are checked, the way it-draws-v2s-look/ already is for leg d. The goal check is goals/shift-manager/a-lab-is-worked-through-one-skinned-shell/goal.md and legs.mts.

  • SPEC's Signal is one line per leg, and the leg c sweep is one sentence.
  • ER-13 points at the goal check instead of naming signal ids.
  • EVOLUTION records why leg c's sweep was narrowed (Shift Manager mounts no react chrome) and why the control was named.
  • PLAN's prospective sections now read as what happened.

3. Two closure decisions recorded in EVOLUTION.

  • Inbox naming, per BR-18: a1 reads its expected set of workstreams from the store. For an ask a post started, a1 checks only the parent channel's Stream. Checking every member Stream is an open follow-up.
  • The narrow ER-15 allowance: sendAction( in lib/talk.ts for the room kind's read, post and join, and createSession( in lib/reads.ts for the room kind. ER-15 already lists both writes, so they are linked, not repeated.

Reviewers · look here

  • Is the critical path right? It runs through design v2, FIX-1736, FIX-1737 and the clean closure run.
  • Is the leg c sweep framed correctly? EVOLUTION records it as narrowed, not as a defect. D2's two shelves stay the contract.

Not changed: the 30 September set table, the box figure (it still draws react chrome as composed in), and D2's card.

Verify: fences balanced, no unquoted risky mermaid labels, every SVG self-contained with both themes and an aria-label, every referenced figure exists. The path was rendered and checked in light and dark.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq


Generated by Claude Code

… the closure checks it

Redraw figures/path.svg from the merged PRs, 30 Sep to 4 Oct: every child that
landed, the v2-look slices of FIX-1737 and the late fixes FIX-1730..1736, 1747,
1749, with the closure's runs and the critical path through design v2.

Reconcile leg c in SPEC, BUSINESS-RULES (ER-13) and PLAN with FIX-1663's goal
check: the sweep is the registry cards Shift Manager draws plus the devtool
page (c:sweep), hardcoded-accent fails at c:tool alone, worker-session may
reach c:sweep, and the static half is c:static. EVOLUTION records the closure's
two calls: Inbox's workstreams per BR-18 (a1 reads its set from the store) and
ER-15's room-kind allowance for sendAction( in lib/talk.ts and createSession(
in lib/reads.ts, already listed in ER-15 and not repeated.

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

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

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 4, 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-04T11:14:51.067417Z b4d0197 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.

@linear-code

linear-code Bot commented Oct 4, 2026

Copy link
Copy Markdown

FIX-1649

jhoffner commented Oct 4, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (read-only; notes for the implementing agent)

Verdict: the approach is right. No better shape; nothing here is an opening for a refactor. A post-closure spec amendment that records what the goal check actually runs is the lean option. The alternative is leaving SPEC/ER-13 describing a leg c that no longer exists. I checked the claims against the repo at b4d0197c:

  • legs.mts:833-834 emits c:sweep and c:<part> as described; goal.md:33,36 carry hardcoded-accent → c at the tool card, and worker-session allowed to reach c:sweep. The new control wording matches.
  • The ER-15 carve-outs exist exactly where named: lib/talk.ts:70 (sendAction() and lib/reads.ts:756,761 (createSession( on ROOM_KIND).
  • BR-18 in FIX-1662 does say a seat on two channels shows its ask on both Streams, so the a1 reading is grounded.
  • The FIX-1663 EVOLUTION and FIX-1662 BUSINESS-RULES link targets exist.

Worth fixing (small)

  1. Mixed naming inside one SPEC section. The signal row now says leg c matches "no value the Shift Manager theme declares", but the mermaid edge in the same section still reads no App Lab value on any swept part (SPEC.md ~L72), and the "Amended 2026-10-04" paragraph says "App Lab". Pick one term for the skin value. Shift Manager reads right after the rename, and the mermaid label is the stale one. Same check for the Anti-game row ("App Lab code that names the second tree"), which is fine as a product name, but make the choice deliberate.
  2. ER-13 is now doing too much in one cell. It carries the control, the exception, the "nothing else reaches leg c" rule and two dates. The same rule lives in SPEC's control row and the sweep paragraph. Three copies will drift. Keep the full statement in SPEC's sweep paragraph and have ER-13 say "leg c fails at c:tool alone under hardcoded-accent; see SPEC for the worker-session allowance".
  3. PLAN.md alt text duplicates path.svg's aria-label almost word for word (~1.5 KB each). Two hand-maintained copies of the same prose. The SVG's own aria-label is the accessible name; a one-sentence alt in PLAN.md ("the path as shipped, 30 Sep to 4 Oct, critical path outlined") plus the existing prose below it is enough.

Notes, no action needed

  • ER-15's carve-out lives only in EVOLUTION. The ER-15 cell says "decided at closure" and links to EVOLUTION. The file-level specifics (lib/talk.ts, lib/reads.ts) are in EVOLUTION's "Replacement" cell. Fine given the PR's "linked, not repeated" intent. But if part 4's check is the real enforcement, the rule is only discoverable through the EVOLUTION table. Consider naming the two files in ER-15's bullets, since they are the contract part 4 enforces.
  • path.svg is hand-placed pixel geometry (bars at fixed x offsets standing in for timestamps). It will be accurate once and can't be regenerated. That is acceptable for a wrap artifact that is frozen by design, and the PR says it was rendered in both themes. I didn't render it myself.
  • Box figure still draws react chrome as composed in. The PR flags this as deliberately unchanged. It now contradicts the narrowed leg c sweep ("Shift Manager mounts no @flow-state-dev/react chrome"), and D3 still talks about a "chrome kit". If the box is meant to show what ships, the next amendment should reconcile it. If it is the 30 Sep intent, a one-line caption note would stop a later reader from reading the contradiction as a defect.

Architecture (improve-codebase-architecture lens)

Spec-only diff (specs/epics/FIX-1649/), no code, packages or BP surface touched. No deepening opportunity is created or implied here. The one recurring pattern worth noting for distill-lessons is that leg c's plan was narrowed in goal.md after closure run 1, but the epic spec waited until wrap to catch up. If specs should follow the goal check sooner, the trigger is "goal.md narrows a leg", not "epic wraps".

No blocking findings.


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 review — FIX-1649 wrap spec

Verdict: Direction looks right; I would not block merge on architecture. The wrap amendment table, path redraw, and closure→epic backfill match how other epics in this repo handle terminal state. The main simplify opportunity is less duplication, not a different story.

What works

  • EVOLUTION as the amendment ledger (leg c sweep narrowed, hardcoded-accent at c:tool, Inbox multi-channel reading, ER-15 room writes) is the right place for “why we changed intent after shipping.”
  • Redrawing path.svg to “as shipped” is consistent with the epic-spec template: the path updates on scope/dependency changes; wrap is the natural terminal update.
  • Pointing leg c at what Shift Manager actually draws (registry cards + devtool, not react chrome) fixes real drift between pre-build spec and shipped app — that amendment is necessary.

Where the approach went further than needed

  1. Two sources of truth for leg c — EVOLUTION says goal.md + legs.mts are canonical, but SPEC (Signal row, sweep block, mermaid) and ER-13 now repeat signal IDs, part lists, and control coupling. Leg d already delegates to goals/shift-manager/it-draws-v2s-look/; legs a–c could follow the same pattern.

    Cleaner alternative (same semantics, smaller diff): EVOLUTION + path + minimal SPEC fold (“closure passed on 01444863c; checks: FIX-1663 goal”) + ER-13 without c:tool jargon. Keep sweep/control detail in the goal tree only.

  2. Path narrative copied ~4× — PLAN image alt, path.svg aria-label, PLAN prose, and SVG footer text all carry the full timeline. That’s the highest ongoing maintenance cost in this PR (hand-edited pixel Gantt), not SVG byte size.

    Cleaner alternative: Short alt/aria (“date Gantt; detail in PLAN §The path”); one prose paragraph in PLAN; SVG = geometry + lane labels only. If you need a generator later, consider Mermaid gantt or exporting from a tool — not required for this merge.

  3. Stale pre-ship line at wrap — “Today’s main: legs a, b and d fail…” is misleading after #2709 merged. Drop or rephrase (“pre–Shift Manager merge” / control today's-main only).

Skipped (judgment call, not simplify-in-diff)

  • Whether the frozen 2026-09-30 set table should gain a “closed” row — EVOLUTION already says live state is Linear; a separate editorial pass.
  • Whether ER-15 bullets belong in BUSINESS-RULES vs evolution-only — both are defensible; I’d pick one normative home.

Checks

Spec-only PR; no code tests run. Subagent pass: code-quality + reuse reviewers aligned on duplication; performance reviewer flagged maintainability only.

Happy to approve a follow-up that thins SPEC/ER-13, or this PR after the “Today’s main” fix if you want that corrected before merge.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/epics/FIX-1649/EVOLUTION.md Resolved
Comment thread specs/epics/FIX-1649/SPEC.md Resolved
Comment thread specs/epics/FIX-1649/SPEC.md Resolved
Comment thread specs/epics/FIX-1649/SPEC.md Resolved
Comment thread specs/epics/FIX-1649/BUSINESS-RULES.md Resolved
Comment thread specs/epics/FIX-1649/PLAN.md Resolved
Comment thread specs/epics/FIX-1649/figures/path.svg Resolved
…ne home

SPEC's Signal cell is one line per leg, with leg c linked to the closure's
goal.md as leg d links to it-draws-v2s-look; the sweep block is one sentence;
the today's-main clause is scoped to that control on a pre-Shift-Manager
commit. ER-13 points at FIX-1663's goal check instead of naming c:* signals.
EVOLUTION's wrap rows keep the why and end at the SPEC goal section plus
goal.md; the ER-15 row links to the rule in BUSINESS-RULES. path.svg's
aria-label and PLAN's alt are short; the timeline lives in one PLAN paragraph.

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

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

ℹ️ 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-1649/EVOLUTION.md Resolved
Comment thread specs/epics/FIX-1649/PLAN.md Resolved
…d, the plan historicized

EVOLUTION's Inbox row now says what shipped: BR-18's asksFor() draws an ask
on every channel that has its seat, and Inbox names a post-started ask's
parent channel only. a1 reads Inbox's set, so for a post-started ask it
proves the parent Stream only; checking every member Stream is an open
follow-up for the goals/lib helper fold. PLAN's "Where it is" and "What
unblocks what, from here" become what happened.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
@jhoffner
jhoffner merged commit 19b8a56 into main Oct 4, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants