Skip to content

lessons: FIX-1455 epic wrap (cycle 18) - #2231

Merged
jhoffner merged 2 commits into
mainfrom
lessons/FIX-1455-wrap
Sep 25, 2026
Merged

jhoffner merged 2 commits into
mainfrom
lessons/FIX-1455-wrap

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 25, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

The costliest rework in the kitchen-sink rebuild epic came after review, not during it. Six PRs merged before their first automated review came back: #1991, #2131, #2164, #2215, #2115 and #2184. Each one left draft within 66 seconds of its merge, and leaving draft is what starts Codex and Cursor. A seventh PR, #2203, merged a final head that no reviewer ever saw.

Three of those reviews found problems after the merge. Nobody answered them and nobody filed them, so they are still on main:

#2184's own merged head also failed CI six minutes after it merged. #2169 merged with CI green against an older main. Between them, main was red for 43 minutes on 09-24, and four other PRs had to carry the repair.

What this does

  • Ledger (factual): adds docs/internal/cycle-ledger/cycle-18.md and its index row. It has one row for each of 42 artifacts: the epic PR and 3 amendments, 8 issue specs, 7 spec amendments and 23 implementation PRs. It also checks the coordinator's six observations against the artifacts. Four are confirmed, two of them with corrections, and two can't be derived from the artifacts.

  • Proposal (the second commit, 7a55e7d): adds one paragraph to orchestration.md → Gates that says what a merge-ready head is. It also adds one clause to epic-lifecycle's "ready to merge" line that points at the paragraph. The paragraph:

    A merge-ready head has been reviewed. Automated review runs when a PR is opened ready or leaves draft, so a PR marked ready in the same breath as its merge merges a head no reviewer saw. Take a PR out of draft when its work is ready for review, not when it is ready to merge. Call it ready to merge — or merge it through MERGE-ONLY — only once that review and the required checks have returned on its current head.

Need your sign-off

1. Adopt the merge-ready definition, or leave merging as it is?

  • Plain terms: Agents open PRs as drafts, and the review bots only start once a draft is marked ready. A PR marked ready and merged in the same minute gets no review at all.
  • Trade-off: Each merge waits two to five minutes for a review that usually comes back clean. In return, what a review finds lands before the merge instead of stranding on main.
  • Recommendation: Adopt it (commit 7a55e7d).
  • What would change my mind: The artifacts can't show who pressed ready and merge, because everything goes through the shared jhoffner login. If you did it yourself each time, this paragraph binds nobody who did it. Then question 2 is the real fix, or the answer is to do nothing.
  • If wrong: one paragraph and a few minutes per merge. It's easy to revert.

2. Should main refuse a merge whose checks didn't run against current main? This is a repository setting, not something this PR changes.

Found at wrap, not proposed (owners needed)

Proposal alternatives that were considered and dropped are listed in the cycle file. No changeset is needed, because this PR is internal docs and skill text only (BP-022).

Links: cycle-18.md · epic FIX-1455 · epic spec #1978

🤖 Generated with Claude Code
https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB


Generated by Claude Code

…epic

Forty-two artifacts: the epic PR and three amendments, eight issue specs,
seven spec amendments and twenty-three implementation PRs. Six merged
before their first automated review returned, and a seventh merged a
head no reviewer saw. The coordinator's six observations are checked
against the artifacts: four confirmed (two with corrections), two not
derivable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
Proposed, for the owner's review. Automated review starts when a PR
leaves draft, and six artifacts in this epic left draft within 66 s of
their merge. The Gates section now says what ready to merge means, and
epic-lifecycle's ready-to-merge line points at it.

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

vercel Bot commented Sep 25, 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 25, 2026 12:03am UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 25, 2026 12:03am UTC
flow-state-dev-ui Ignored Ignored Sep 25, 2026 12:03am UTC

Request Review

@linear-code

linear-code Bot commented Sep 25, 2026

Copy link
Copy Markdown

FIX-1455

@jhoffner
jhoffner marked this pull request as ready for review September 25, 2026 14:51
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 25, 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-25T14:54:57.492974Z 7a55e7d 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.

@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

Verdict: approve. The behavioral part of this PR is the right shape: one short normative paragraph under Gates in orchestration.md, plus a single anchor link in epic-lifecycle step 4. That is simpler than inventing checks, bots-as-required-check wiring, or new BPs — it names an invariant where merging is already governed. I would not swap this for a third-party package or a workflow script change for the primary class (draft → merge in one breath).

Where complexity concentrates is cycle-18.md, not the grounding edits. For 42 artifacts the forensic table is doing real work; the lede, class section, coordinator observations, and claims are well targeted. The main simplification opportunity is deduplicating representations, not dropping the proposal:

  1. Finding map (~45 lines) largely mirrors the master table’s class counts. Consider making the table authoritative for routine rows and keeping a full thread map only for high-wave or post-merge incidents (#2029, #2061, draft→merge rows), or add one Method line when a full map is mandatory (I’m not sure policy requires 42/42 every cycle).
  2. Verbatim blockquote of the landed gate (proposal section) will drift from orchestration.md over time. A link + “landed in Gates” is enough unless you want a historical snapshot at wrap time.
  3. Footer sums repeat Load aggregates — pick one rebuildable totals block.
  4. Method chain: “cycle 17’s rules unchanged” skips the authoritative cycle-15.md Method hop that cycles 16–17 use; REST vs MCP also diverges from distill-lessons — minor consistency nit for the next entry.
  5. Cross-links: cycle 17 #2033 and cycle 5 merge-ready notes are the direct predecessor of this proposal; linking them would shorten the “not the first time” story without new prose.

Skipped (needs your call, not blocking): truncating cycle entries above N artifacts; moving the 42-row table to docs/internal/epic-wraps/ (older cycles 4–6 pattern); repo branch-up-to-date settings for #2169 (correctly filed as owner/tooling).

Trade-off to keep in mind: the new gate intentionally adds merge latency (bots after ready) in exchange for fewer unreviewed merges — appropriate given this epic’s evidence.

Nice work landing cycle 17’s deferred #2033 class with a minimal upstream fix.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/contributing/orchestration.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-18.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-18.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-18.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-18.md Resolved
Comment thread .agents/skills/epic-lifecycle/SKILL.md Resolved

@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.

Code Snob — already tight. No POC.

Read .agents/skills/epic-lifecycle/SKILL.md, docs/contributing/orchestration.md (Gates), docs/internal/cycle-ledger.md, docs/internal/cycle-ledger/cycle-18.md, and the class sections of cycle-16 and cycle-17.

A rewrite would not shrink the contract. The landed rule is one paragraph plus the pointer the ledger specifies. The sentence that review starts when a PR is opened ready or leaves draft is the trigger that rule enforces, not a second copy of the imperative. The cycle file is the same shape as 16 and 17: the class table holds the review-arrival clocks (the main table only has the gap in seconds), and the finding map is how the 68 and 113 counts get re-derived. Cutting either drops evidence the next cycle scores. The altitude — definition in Gates, pointer in the skill, no new BP — is already the sign-off on this PR.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@jhoffner
jhoffner merged commit 0811d87 into main Sep 25, 2026
14 checks passed

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

ℹ️ 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 on lines +384 to +385
ready to merge. Call it ready to merge — or merge it through MERGE-ONLY — only once that
review and the required checks have returned on its current head.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Enforce the current-head review gate in lifecycle checks

When feedback fixes produce a new head, this rule is not enforced by the paths that decide merge readiness: .agents/workflows/epic-wake.js:2407 still defines readyToMerge as merely approved, green, and mergeable, and lines 3633-3656 emit merge gates directly from that value; .agents/skills/issue-lifecycle/SKILL.md:123 likewise uses only approved + green, while the MERGE-ONLY checklist at docs/contributing/orchestration.md:684-691 never verifies that an automated review returned for the current head. Since these reviews are explicitly not required checks, the coordinator can still surface and merge exactly the unreviewed head this new rule is intended to prevent; carry current-head review evidence through the scan/schema and validate it in every readiness and MERGE-ONLY path.

AGENTS.md reference: AGENTS.md:L54-L54

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Valid. This PR merged before the review came back, so the fix goes in a follow-up PR from main. It adds a "latest reviewed commit matches the latest commit" check to readyToMerge in epic-wake.js, to issue-lifecycle's readiness line, and to the MERGE-ONLY checklist. I'll link the PR here once it's open.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up: #2250. It enforces the rule at all four places that can offer a merge gate: the wake scan, the worker, sub-PRs, and the repair PR. It also covers issue-lifecycle's readiness line and the MERGE-ONLY checklist. The workflow verifier passes 321/321, and the new check fails on the old logic.


Generated by Claude Code

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