Repository navigation
feat(process): retain approved specs and merge before implementation - #1975
Conversation
|
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.
Code Snob — outcome 3: already tight. No POC.
The new machine is three predicates (historicalSpecFor, specApprovalFor, specMergedFor), a receipt match on the existing implement action, and epicReady = approved && merged && !pending fed into the allocate hold that already existed. That is the smallest shape that keeps approval and merge as independent observations.
Read: .agents/workflows/epic-wake.js (helpers, nextRow receipt, jumpsTheApprovalGate, allocate call, spec-merge gates), .agents/workflows/verify.mjs (retainedEpic, RETENTION checks), scripts/validate-spec-folder.mjs, packages/core/test/spec-folder-check.test.ts, .github/workflows/ci.yml, knip.json, plus the issue-lifecycle / issue-spec skill rewrites.
A rewrite would not shrink the contract:
- splitting MERGE-ONLY out of
implementadds an action - collapsing the three predicates loses the merge-without-approval vs historical-approval split the tests pin
- packing the RETENTION cases or thinning the CLI happy-path fixture is test layout, not a smaller machine
- skill/doc churn is already net-down and points at
orchestration.md
Not re-litigating retention, source-head bind, or merge-before-implementation.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
Simplify review — direction holds; complexity is mostly the price of the contract
The problem statement is real: never-merged specs made every spec/FIX-* citation a lie on main, and approval could release implementation without the reviewed design landing. Retaining under specs/ and gating on observed merge (not just approval) is a coherent fix. The guard (validate-spec-folder.mjs + narrowed CI exemption), scanSources tests, and verify.mjs coverage are proportionate and match existing validate-*.mjs patterns — I would not replace that with knip, depcheck, or raw rg in CI.
Did the approach go too far?
Partly, on surface area — not on the core retention + merge gate.
| Layer | Verdict |
|---|---|
Retain on main + cite `specs/issues |
epics/` |
Separate approval vs merge + specMerged / approvedHeadSha in epic-wake |
Necessary given the stated goal; this is where most new moving parts live |
Required DOCS.md + conditional EVOLUTION.md |
Debatable — see inline on orchestration; could have shipped retention first and added doc/evolution ceremony in a follow-up |
| ~47 files of skill/subagent prose | Drift risk — much of it restates orchestration.md; a thinner “link + 3 bullets” pattern in lifecycles would age better |
spec/ + spec-poc/ README stubs + specs/ + branch names spec/* / epic/* |
Smell, not a blocker — three namespaces for one lifecycle; long-term, one public tree (or branch prefixes that match paths) would read cleaner |
Simpler approaches considered
-
Stay on never-merge + Linear mirror (pre-PR model) — Fewest automation changes, but keeps dangling local citations unless you ban them entirely and accept GitHub/Linear URLs as the only durable pointers. This PR explicitly rejects that tradeoff; I agree with the rejection if agents and humans are expected to link specs from code and docs on
main. -
Merge retained specs without a workflow merge gate — Policy-only (“don’t implement until merged”) without
MERGE-ONLYworkers and scoutspecMergedfields. Simpler on paper, but you already proved why approval ≠ merge matters; the harness work is doing real work. -
Third-party link checker — Does not encode “legacy
spec/is always wrong on mergeable branches”, placeholder rules, or README-only ephemeral dirs. Custom guard is justified. -
Fold
DOCS.mdintoPLAN.mdand makeEVOLUTION.mdstrictly optional (only when >1 predecessor) — Would cut author and skill surface without weakening retention or merge semantics. If you want a smaller v1, that’s the highest-leverage simplification I see.
Skipped / follow-up (not blocking)
docs/atlas/README.mdstill says specs stay on never-merged spec PRs (BP-037) — contradicts retainedspecs/; one sentence fix.docs/internal/archive/*on old “close at approval” lifecycle — add superseded-by pointers so greps don’t resurrect wrong gates.- CI full-tree scan (~1s today) — fine now; if
specs/grows large, consider diff-scoped runs on PRs (optional). - Wire
verify.mjsinto CI — operational reuse, not a simplify of the harness itself.
Performance
No hot-path concerns: guard is sync full-walk once per CI job; epic-wake / verify.mjs are off the merge path. Scout prompts got heavier (merge metadata) — token cost per wake, not CPU.
Approval: Implementation matches the approved scope, tests and harness evidence are credible, and the extra complexity tracks real gates rather than accidental abstraction. I’d still treat DOCS/EVOLUTION as required fifth/sixth docs and skill prose duplication as the main places a future simplification pass could shrink diff size without reversing retention.
Sent by Cursor Automation: Review For Best Approach
|
|
||
| Issue specs live at `specs/issues/<ISSUE-ID>/`; epic specs live at | ||
| `specs/epics/<EPIC-ISSUE-ID>/`. Each requires `SPEC.md`, `DECISIONS.md`, | ||
| `BUSINESS-RULES.md`, `PLAN.md`, and `DOCS.md`. Add `EVOLUTION.md` when the design |
There was a problem hiding this comment.
Simplify (optional): Requiring DOCS.md as a fifth document alongside the original four is a lot of new author ceremony on the same PR that already introduces merge receipts, amendments, and EVOLUTION.md. The intent (reconcile user docs at implement time) is right; the split could be lighter — e.g. a ## Docs section in PLAN.md with the same “proposed prose + destinations” contract, and keep EVOLUTION.md only when there is real predecessor lineage. Not saying you must change it here; flagging this as the highest-leverage place the approach may have overshot v1.
There was a problem hiding this comment.
No change to the document set. DOCS.md is an explicitly approved requirement and keeps proposed reader-facing prose, destinations, limits, and migration reviewable as one deliverable instead of burying it in an implementation plan. EVOLUTION.md remains conditional on relevant predecessor design; it is not required merely because a spec exists. The independent restraint and second-look reviews found no removal that preserved that contract.
| # `spec/` — the project-spec exception | ||
|
|
||
| This folder holds **one spec at a time, on a spec branch, and never on `main`.** | ||
| New issue and epic specs belong in [`specs/`](../specs/README.md), not here. |
There was a problem hiding this comment.
Directory smell: New work lives under specs/, but branches stay spec/<id> / epic/<name>, and spec/ + spec-poc/ remain as legacy README shells. That’s understandable for migration, but it’s the messiest part of the mental model. Longer term, consider collapsing to one tree (retire empty stubs) or aligning branch prefixes with specs/ — purely ergonomics, not a merge blocker.
There was a problem hiding this comment.
No rename or tree collapse in this PR. The approved non-goals preserve project/<slug> with spec/_projects/<slug>/, avoid branch renames, and leave historical POCs unmigrated. spec/README.md and spec-poc/README.md therefore document live exceptions and migration boundaries; specs/ is the canonical tree for new issue and epic sets.
| // holds (spec-figures.md admits no other asset into `figures/`), and a path with | ||
| // no extension names a directory, which is a location, not a link that dangles. | ||
| // Preserve the legacy guard's scope: spec prose and figures, not a general link checker. | ||
| const SPEC_CITATION = |
There was a problem hiding this comment.
Regex + URL-stripping is the right family of solution for this repo’s guard pattern. If this grows more rules, a tiny table-driven matcher (or allowlist: only specs/issues|epics/ may be cited locally) might be easier to extend than a third regex. Fine as-is for this PR.
There was a problem hiding this comment.
No change here. The guard currently has two concrete legacy-path rules and exercises the real CLI against disposable trees. A table or allowlist becomes useful only if another independent rule arrives; introducing it now would add structure without simplifying the current matcher.
| # Issue and epic specs merge into specs/ after approval and required checks, | ||
| # so their PRs run this guard too. Only standing project specs retain the | ||
| # never-merged spec/_projects/ lifecycle. Key that exception on the branch, | ||
| # not a label that may be applied after the opening CI run. Main is always checked. |
There was a problem hiding this comment.
Narrowing exemption to project/* only is simpler and safer than the old spec/* + epic/* skip — spec/epic PRs now prove they don’t leak legacy spec/ trees. Good simplify vs the previous model.
There was a problem hiding this comment.
No change. The branch-name exception intentionally covers only standing project/* specs; issue and epic spec PRs run the same retention guard as main before they can merge.
second-look: PR #1975 (fix/spec-retention-and-merge-gate, head
|
| # | Finding | Lens | Recommendation | Est. Δlines | Sev | Conf |
|---|---|---|---|---|---|---|
| — | (none passed the calibration gate) |
Net: 0 — no findings met all five gate criteria (concrete leaner alternative, net-positive removal, articulable loss, bloat not taste, not an approved/documented requirement).
Why so few candidates
The PR body's collapsed "approved scope" section functions as this target's intent source (per second-look's target-resolution table, a PR's intent source is its PR/commit messages), and it explicitly authorizes: five required documents (SPEC/DECISIONS/BUSINESS-RULES/PLAN/DOCS.md) + conditional EVOLUTION.md, retention under specs/issues|epics/<ID>/, merge-before-implementation, head-bound approval, and the MERGE-ONLY worker contract. Nearly every line of new surface traces to one of those bullets — that's the calibration gate's rule 5 (documented contract) applied at PR-approval altitude rather than architecture-doc altitude.
More notably, several of the largest diffs are net reductions in complexity, not additions:
orchestration.md→ "Gates": ~150 lines of intricate label-provenance/staleness prose ("the narrow exception,"labelProvenanceUnreadable, the carried-approval fallback) collapsed to ~35 lines once the merge-confirmation model made most of that machinery unnecessary..agents/workflows/epic-wake.js: the same ~90-linelabelUnattributable/carriedApprovalHoldsblock, plus thelabelPresent/labelProvenanceUnreadableschema fields, deleted outright — replaced by three small pure functions (historicalSpecFor,specApprovalFor,specMergedFor).scripts/validate-spec-folder.mjs+ its test: the fourscanRoots/scanFiles/ephemeralDirs/scanExtensionsexports (kept alive only so a test could assert config shape) were removed; the test now drives the real CLI against a disposable directory tree instead, which is a strictly more honest check of the same guard.
Considered & deemed justified
DOCS.md+ conditionalEVOLUTION.mdas two more required-ish documents per spec — kept: explicitly named in the approved-scope bullets ("Require SPEC, DECISIONS, BUSINESS-RULES, PLAN, and DOCS" / "Add conditional EVOLUTION"), and the epic-altitude worked example correctly points back at the issue-template's worked example instead of duplicating it (epic-spec-template.md→ "Use the issue template's documentation contract and example").- The
approvedInSession:<head>channel and its restatement inorchestration.md,epic-lifecycle/SKILL.md,issue-lifecycle/SKILL.md— kept: this predates the PR (not new surface it introduces) and the per-skill restatement is a short pointer + operational summary, matching this repo's existing single-canonical-doc-plus-per-skill-summary convention rather than a new duplication pattern. MERGE-ONLYas a new bounded dispatch mode threaded throughepic-wake.js,epic-lifecycle,issue-lifecycle,epic-agent.md,issue-worker.md— kept: this is the mechanism the approved scope calls for directly ("the coordinator authorizes and schedules; it never mechanically merges" / "No second human approval gate is added"), and theWORKER_SCHEMA.specMergereceipt shape (pr/headSha/mergeCommitSha) has a real, singular consumer (jumpsTheApprovalGate'smergedByWorkercheck inepic-wake.js) — not a speculative extension point.spec-poc/README.md,spec/README.mdretained alongside the newspecs/README.md— kept: these describe the still-live legacy/project-spec paths (spec/_projects/<slug>/unchanged lifecycle), not orphaned docs for a removed mechanism.
No line-level or correctness observations are in scope for this pass (/code-review territory); none were flagged.
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: 77d5fd0a8e
ℹ️ 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".
| - Follow the canonical [retention and authority policy](../orchestration.md#spec-retention-and-authority) | ||
| and [merge/amendment lifecycle](../orchestration.md#merging-and-amending-a-spec). | ||
| Repository content is canonical; Linear carries links and status. |
There was a problem hiding this comment.
Update carriers of the retired no-spec-on-main rule
After making repository-retained, merged issue and epic specs canonical, several active surfaces still state the opposite: docs/atlas/README.md:12-14 says specs stay on never-merged PRs, scripts/validate-changeset-refs.mjs:200-203 tells changeset authors that the repository keeps no spec copy, and labs/conductor/src/implement.ts:53-54 says every spec PR closes unmerged. Contributors and agents following those surfaces will use the retired lifecycle, so update these carriers in the same change.
AGENTS.md reference: AGENTS.md:L56-L56
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in e0bf751. Updated the three reported active carriers: docs/atlas/README.md, scripts/validate-changeset-refs.mjs, and labs/conductor/src/implement.ts. The same stale lifecycle was also present in the active Conductor atlas diagram/phase table, so docs/atlas/conductor.html now shows approval followed by confirmed merge. Historical archive entries remain unchanged as records of the old process. Verification: changeset validator exits 0; atlas structure has zero broken local references; the focused Conductor done-condition suite passes 18/18 relevant tests.
|
Feedback round 1 is complete at |
Brings the retained-spec contract (#1975) and the updated spec-folder guard onto the epic branch ahead of migrating W5's spec to specs/epics/FIX-1457/. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz


Approved issue and epic designs remain outside the repository, leaving implementers without a durable, checkout-local record of decisions and experiments. Approval can also release implementation without the reviewed design having landed.
This retains specs and authored evidence in the repo, merges spec PRs after human direction approval and required repository checks, and holds implementation until the merge is observed. It adds reviewable documentation drafts and explicit evolution from earlier designs.
Please review this implementation of the direction approved in our conversation. This is a process implementation PR intended to merge, not a never-merged spec artifact. Project specs keep their existing lifecycle; historical specs are not backfilled.
Review closely: source-head approval and PR-identity binding; recovery after merge; POC isolation from production discovery; agreement between canonical policy, templates, skills, and workflow consumers.
How to review this and approved scope
The owner approved a written scope before implementation and has now authorized submission. There was no separate formal spec PR or Linear approval artifact; do not infer either. Review implementation safety, completeness, and cross-file consistency against the following approved requirements:
specs/issues/<ISSUE-ID>/and epic sets underspecs/epics/<EPIC-ISSUE-ID>/.spec/_projects/<slug>/with their existing never-merged lifecycle. No bulk backfill or unrelated POC migration.The shared review lenses completed without remaining findings. Particular negative paths worth checking are stale approval heads, wrong-PR merge receipts, merge-without-approval, an open change request, and recovery from an already-approved merged original.
Verification and boundaries
Pre-submission verification of the frozen implementation recorded:
node .agents/workflows/verify.mjs: 310 workflow checks passed, including RED/GREEN coverage of historical recovery while retaining the open-spec veto and source-head binding.All 47 submitted files were hash-matched to that reviewed and verified snapshot before commit. The workflow harness uses injected API responses; it does not claim to have run real agents or performed GitHub merge side effects. No paid provider calls or project-wide validation runs were used for this process change.
No changeset needed: internal process, documentation, guards, and orchestration only. The fsd-coding review fixes in #1964 and unrelated working-copy changes are excluded. Current CI status is shown in the checks below.
Note
Medium Risk
These are process-control changes across epic/issue lifecycles and implementation gates; mistakes in agent guidance could cause premature implementation, wrong merge receipts, or drift from canonical orchestration policy.
Overview
This PR rewrites agent skill guidance so orchestration matches retained specs on
main, head-bound human direction approval, checked spec merge before implementation, and follow-up amendment PRs—replacing the old model of never-merged spec PRs, Linear as the durable copy, and closing specs at approval.Lifecycle and gates.
issue-lifecycle,epic-lifecycle,issue-spec, andissue-implementnow treat direction approval and observed spec merge as separate steps (including MERGE-ONLY worker dispatch), bind owner labels toapprovedHeadSha, and keep implementation merge human-controlled. Epic phases no longer assume an eternally open epic PR or unmerged wrap; live status comes from Linear and implementation PRs, not per-tick edits to merged spec bodies.Spec shape and readers. Issue/epic work is anchored at
specs/issues/<ID>/andspecs/epics/<ID>/with five required documents plusDOCS.md(concrete reader-facing draft and publication targets) and conditionalEVOLUTION.md. Cross-spec review,distill-lessonsround endpoints,project-specstatus checks, and review/second-look/settle-claim skills are updated to read retained revisions, amendment PRs, and provenance instead of Linear mirrors or “spec never merges.”Supporting posture docs.
epic-em/epic-pm,agent-mailbox,prototype/spec-pocpointers, and implementer/challenger prompts are tightened so material direction changes need renewed approval, POCs stay in ownedpoc/<experiment>/, and coordinators link intent plus live progress at gates.Reviewed by Cursor Bugbot for commit 77d5fd0. Configure here.