Repository navigation
Description
An approved epic does not approve its children — each child is its own issue before code.
Epic: one owner per workflow verdict — phase status, verification, gates, runtime activation, planning writes
The deliverable is the owners, not the individual fixes. Every arm below is the same defect in a different subsystem: a verdict the workflow acts on — is this phase complete, is this verification current, did this gate pass, does this hook actually fire, did this write go through the seam — is derived at more than one site, the copies use different vocabularies, and nothing forces them to agree. The absorbed issues are the symptom list, not the work list. An implementation that repairs them where they were reported has not closed this epic, even with every symptom gone and CI green.
Closing this epic means three things land together in every arm: one owner module with a closed vocabulary that both the producer and every consumer import; the duplicate derivations are deleted rather than kept in sync, because two copies that agree today are the same defect as two that disagree; and enforcement is by construction — a property test, a type that rejects the wrong shape, or a drift guard that fails CI on the next copy, each shipped with a positive control proving it can go red.
This is the shape that worked in #1372, #2143, #2121, #3180 and #4906. Splitting delivery across many PRs is expected; splitting it so that an owner never lands is not.
This epic subsumes three idle epics
Found by an architecture review of next @ 19a7b1fe69 (2026-09-27). Each subsumed epic had no Phase 0, no sub-issues, no ADR and no seam work in flight, so its body is carried forward here as one arm rather than competing with this epic for the same code:
| Subsumed | Becomes | Why it belongs here |
|---|---|---|
#4907 — verification is a pure function of inputs it does not contain; stale has one owner |
Arm B | the phase-status ladder (Arm A) consumes the verification verdict; two epics would own the same stale routing |
| #4631 — gates resolve scope and read evidence through shared seams | Arm C | the gate logic lives inside src/check-command-router.cts (2,017 lines), which Arm C must first split into gate modules |
| #4632 — registration is not activation: one runtime descriptor + an activation probe | Arm D | the hooks surface (applySettingsJsonHooks, 655 lines, cyclomatic 157) and runtime-name literals are the same missing-descriptor defect |
Not subsumed — in progress: #4629 (STATE.md write intent; ADR-4629 merged, C1 merged, C2 open as PR #4935). Its seam is untouched here. Arm E deletes the src/roadmap-upgrade.cts cross-reference loop, which also writes STATE.md, and routes that write through #4629's seam. The gap in #4629's terminal guard — a STATE.md target arriving through a variable — is reported to #4629 (comment), not claimed.
Five arms, one rule
Arm A — phase status has four vocabularies (new). "What state is phase P in?" is derived at four sites that do not agree:
| Site | Vocabulary | Reads verification through |
|---|---|---|
src/commands.cts:217 determinePhaseStatus (+ foldPhaseStatus), used by progress (:3418), stats (:3938), and init plan-phase's phase_status (src/init.cts:1265) |
6 labels | raw frontmatter status — never the staleness check |
src/health-diagnostic-rules/phase-structure.cts:112 derivePhaseStatusLabel — its own docblock calls it a reconstruction of determinePhaseStatus |
6 labels | isPhaseComplete (ADR-3180 §7.4) |
src/state-contract.cts:195 statusFromProgressCell → state.json |
3 wire values | the ROADMAP Status cell |
src/workstream-inventory-builder.cts PhaseStatus.status |
3 values | isPhaseComplete |
The first two disagree today: for a phase whose *-VERIFICATION.md says passed but whose fingerprint is stale, progress and stats report Complete, while the health rule and isPhaseComplete report it not complete. ADR-3180 already decided that isPhaseComplete is the only owner of completion; the ladder above it has no owner.
Arm B — verification staleness (carried from #4907): the covered set contains files verification writes (#4857, #4887, #4981), emitter and checker derive inputs independently (#4817), stale is read two ways and no workflow regenerates the report (#4765, #4887), a nonexistent phase dir answers missing (#4987), and detectDrift sees only added files (#4886). #4894 shipped since the epic was filed.
Arm C — gates (carried from #4631, plus the structural precondition): gate logic — decision coverage, UI plan/safety, TDD checkpoint, API coverage — lives in src/check-command-router.cts and prints through output(), so a gate's verdict is only testable through stdout. Each gate derives its own commit range (#3926, #4563, #4498), hand-parses evidence (#4562, #4541, #4259, and the router's private extractYamlBlock / extractXmlTagBodies), reports a verdict its exit code discards (#4686), or scopes too wide (#4869).
Arm D — runtime activation (carried from #4632, plus the hooks surface): runtime vocabulary is hand-maintained per runtime (#4332, #4438), registered hooks do not fire (#4849, #4557), the installer advertises commands it did not register (#4567), two resolvers read the runtime differently (#4690, #4347), _hostBehaviors is duplicated in install-engine.cts:263 and runtime-artifact-conversion.cts:102, install-engine.cts:1441 special-cases runtime === 'hermes', and applySettingsJsonHooks holds every settings-json registration branch in one function.
Arm E — planning writes that #4906's census missed. src/roadmap-upgrade.cts rewrites ROADMAP.md (applyRoadmapEdits → fs.writeFileSync, :2294-2298) and plan files (:2285) outside the PlanningDoc seam, and src/phase.cts:4131 flips a plan checkbox with a raw regex .replace beside a sibling that uses updateBullet. local/no-adhoc-markdown-parsing does not see either shape (line-indexed and split/join edits), so ADR-4910's Done-when is false today with lint:ci green.
Design lock
Phase 0: #5057 → PR #5058 (docs/adr/5057-one-owner-per-workflow-verdict.md). Phases 1–14 are listed in the ADR's Phases section with their ordering constraints; each becomes a chore(#5056): … — Phase N sub-issue when it opens. It locks the owner, vocabulary and ratchet for each arm, the ordering constraints, and the per-phase acceptance rule below.
What makes a phase done
Every phase carries the same three criteria: census → zero (enumerate every instance tree-wide, publish the count, close at zero); deletion, not coexistence (bespoke derivations removed, including correct ones); unrepresentable by construction (one property test, type, or drift guard, shipped with a positive control). Absorbed issues are fail-first regression evidence; a phase may not close on them alone. Absorbed issues already closed use Refs #NNNN, never a closing keyword.
Done when
- Phase status has one owner with a closed ladder; every display label, wire value and ROADMAP Status cell is a projection of it;
determinePhaseStatus,foldPhaseStatusandderivePhaseStatusLabelare deleted - No verification artifact written during verification is an input to its own digest; the fingerprint is idempotent (property test);
VerificationStatusis a closed enum shared bygsd-verifierandverification.cts;stalehas one routing table and a command that regenerates, proven by a two-cycle verify endingpassed - No gate lives in a command router; every gate returns a typed verdict, derives scope through one resolver, reads evidence through the document seams, distinguishes "none" from "could not read", derives its exit code from its verdict, and has a positive control
- Every runtime-specific fact lives in its descriptor (no runtime-name literals in install or hook code); an unknown runtime id refuses; every runtime × registered hook passes an activation probe in CI; advertised commands are generated from the registered surface
- No planning artifact is mutated outside the
PlanningDocseam, and the lint sees line-indexed andsplit/joinedits - The ADR is ratified
Acceptedat closeout and/adr-phase-coveragereports zero orphans
Non-goals
- Repairing the absorbed issues individually at their call sites.
- Epic: STATE.md writes declare intent and are verified — retire the opaque transformFn contract #4629's STATE.md write seam (in progress under its own epic).
- Changing any gate's policy (what it forbids), the fail-closed staleness contract,
ON_CRASH = ALLOWfor advisory guards, orverify codebase-drift's warn-only contract. - Gates whose accepted-evidence model is narrower than GSD's producers ([Bug]: TDD mode rejects genuine Vitest RED evidence because the parser requires Node-specific TAP summaries #4692, bug(tdd-gate): a gap closure split into a RED plan and a GREEN plan blocks the phase permanently #4867, bug(tdd-red-evidence): a genuine swift-testing RED scores INVALID_RED / zero_tests_discovered because the parser only reads Node TAP summaries (Swift sibling of #4692, #4724) #4957) — individually fixable, not a parser-form defect (per the Epic: gates resolve scope and read evidence through shared seams, and fail closed when they find nothing #4631 boundary note).
- Adding runtimes; relitigating feat(runtime): Remove Gemini CLI support — sunset by Google 2026-06-18 (Antigravity CLI is the successor) #1928; replacing markdown as the storage format.
🤖 Generated with Claude Code
Activity
docs(#5057): ADR-5057 — one owner per workflow verdict (Phase 0 of #5056
test(#5060): fail-first suite for the Phase Status Module
test(#5060): bind the deriveProgressFromRoadmap and superseded-plan c…
refactor(#5060): the Phase Status Module owns the phase-status ladder
test(#5060): pin projection vocabularies, bracket agreement and miles…
refactor(#5060): close the review findings on the Phase Status Module
test(#5060): give the E1 milestone-op collision fixture a verified phase
156 remaining items
chore(open-gsd#5207): hook registration is a table behind the setting…
fix(open-gsd#5207): bind the hook-table parity pin to the reconcile p…
test(open-gsd#5207): assert hook registration through the table and t…
Merge pull request #5216 from open-gsd/chore/5215-chore-5056-registra…
Merge pull request #5218 from open-gsd/chore/5217-chore-5056-planning…
fix(open-gsd#5215): prove hook registration activates and generate th…
test(open-gsd#5217): failing-first tests for seam-routed planning wri…
refactor(open-gsd#5217): every planning-artifact mutation goes throug…
Merge pull request #5220 from open-gsd/chore/5219-ratify-adr-5057-and…
refactor(open-gsd#5219): the four check verbs outside a gate module b…
trek-e commentedon Oct 29, 2026
Roll-up: every arm shipped, ADR-5057 ratified
Closing as completed. Verified against
next@a58d8aaac6.VerificationStatus, onestaleroutedetectDriftwhole change setPlanningDocCoverage check.
/adr-phase-coveragewas re-run against the shipped state: 7 ADR decisions (15 sub-decisions) plus 4 user-facing capabilities, each owned by exactly one merged phase, with no orphan, no dangling deferral and no multi-owner. ADR-5057 isAccepted(ratified 2026-10-04, Phase 14).Arm E. The four sites in the ADR's census are at zero:
applyRoadmapEditsis deleted, thephase.ctscheckbox flip goes throughupdateBullet, and the cross-reference loop is replaced byreplaceProse(PROJECT.md) andreadModifyWriteStateMd(STATE.md).no-adhoc-markdown-parsinghas theadhocSplitJoinMutationandadhocLineIndexedMutationdetectors with positive controls.Not part of this epic. The ROADMAP Progress-table and phase-entry grammar work is #5692, which was always a separate epic ("kept separate" in its Phase 0, #5703). Its Phase 4 (#5764) has landed. STATE.md write intent remains #4629, and
stripTemplatePlaceholdersinsrc/state-transition.ctsbelongs to it.