Skip to content

feat(process): retain approved specs and merge before implementation - #1975

Merged
jhoffner merged 2 commits into
mainfrom
fix/spec-retention-and-merge-gate
Sep 20, 2026
Merged

jhoffner merged 2 commits into
mainfrom
fix/spec-retention-and-merge-gate

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 20, 2026 •

Copy link
Copy Markdown
Collaborator

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:

  • Retain issue sets under specs/issues/<ISSUE-ID>/ and epic sets under specs/epics/<EPIC-ISSUE-ID>/.
  • Require SPEC, DECISIONS, BUSINESS-RULES, PLAN, and DOCS. DOCS contains proposed reader-facing prose/examples and concrete publication destinations, or a justified no-impact statement.
  • Add conditional EVOLUTION covering one or multiple predecessor designs, precise anchors, retained/amended/superseded decisions, evidence, and compatibility. No lineage registry or mandatory backlink edits.
  • Keep authored figures, assets, and POCs with their owner, excluding generated dependencies and secrets. POCs remain outside production imports and default package/build/test/lint/Knip discovery.
  • Make the repository canonical for spec content; Linear carries status and links.
  • Bind human approval to the reviewed source head. Approval permits a merge after required checks; it does not substitute for an observed merge or authorize a changed revision. No second human approval gate is added.
  • Retain original merged review history. Material amendments require fresh approval and follow-up PRs from main. Live epic status does not create per-tick commits to historical spec PRs.
  • Preserve project specs at 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.
  • Spec-folder guard suite: 22 checks passed; the integrated repository guard passed.
  • Real Knip and Turbo discovery probes excluded retained POCs while preserving production sentinels/tasks.
  • Retained fixture checks accepted the required document set and multi-predecessor links, and rejected dangling local citations and misplaced project artifacts.
  • Coherence, restraint, correctness, and completeness reviews closed cleanly.

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, and issue-implement now treat direction approval and observed spec merge as separate steps (including MERGE-ONLY worker dispatch), bind owner labels to approvedHeadSha, 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>/ and specs/epics/<ID>/ with five required documents plus DOCS.md (concrete reader-facing draft and publication targets) and conditional EVOLUTION.md. Cross-spec review, distill-lessons round endpoints, project-spec status 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-poc pointers, and implementer/challenger prompts are tightened so material direction changes need renewed approval, POCs stay in owned poc/<experiment>/, and coordinators link intent plus live progress at gates.

Reviewed by Cursor Bugbot for commit 77d5fd0. Configure here.

@vercel

vercel Bot commented Sep 20, 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 20, 2026 7:58pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 20, 2026 7:58pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 20, 2026 7:58pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 20, 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-20T18:25:27.866699Z 77d5fd0 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.

@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 — 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 implement adds 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.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

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

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

  2. Merge retained specs without a workflow merge gate — Policy-only (“don’t implement until merged”) without MERGE-ONLY workers and scout specMerged fields. Simpler on paper, but you already proved why approval ≠ merge matters; the harness work is doing real work.

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

  4. Fold DOCS.md into PLAN.md and make EVOLUTION.md strictly 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.md still says specs stay on never-merged spec PRs (BP-037) — contradicts retained specs/; 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.mjs into 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.

Open in Web View Automation 

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

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

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.

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.

Comment thread spec/README.md
# `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.

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.

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.

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.

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 =

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.

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.

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.

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.

Comment thread .github/workflows/ci.yml
# 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.

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.

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.

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.

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.

Copy link
Copy Markdown
Collaborator Author

second-look: PR #1975 (fix/spec-retention-and-merge-gate, head 77d5fd0)

Verdict: Appropriately scoped — the surface tracks tightly to the pre-approved requirement set stated in the PR description, and several places net-simplify rather than add.
Scope: diff → +1940 / −1795 across 47 files (process/docs/skills/workflows only — no packages/*/src or apps/* touched, so improve-codebase-architecture has no opening here).

# 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-line labelUnattributable/carriedApprovalHolds block, plus the labelPresent/labelProvenanceUnreadable schema fields, deleted outright — replaced by three small pure functions (historicalSpecFor, specApprovalFor, specMergedFor).
  • scripts/validate-spec-folder.mjs + its test: the four scanRoots/scanFiles/ephemeralDirs/scanExtensions exports (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 + conditional EVOLUTION.md as 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 in orchestration.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-ONLY as a new bounded dispatch mode threaded through epic-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 the WORKER_SCHEMA.specMerge receipt shape (pr/headSha/mergeCommitSha) has a real, singular consumer (jumpsTheApprovalGate's mergedByWorker check in epic-wake.js) — not a speculative extension point.
  • spec-poc/README.md, spec/README.md retained alongside the new specs/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

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

Comment on lines +77 to +79
- 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge 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 👍 / 👎.

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.

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.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Feedback round 1 is complete at e0bf7512c. The stale active lifecycle carriers identified by Codex are corrected, including the matching Conductor atlas diagram and phase table; historical archive records remain untouched. The optional DOCS/EVOLUTION and namespace simplifications are unchanged because DOCS and conditional evolution are approved requirements, while project-spec paths, branch names, and historical POCs are explicit non-goals. Focused verification: changeset validator passes, atlas local structure has zero broken references, and the relevant Conductor done-condition tests pass 18/18. All five inline threads have individual outcomes.

@jhoffner
jhoffner merged commit defcbb7 into main Sep 20, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Sep 21, 2026
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
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.

1 participant