Skip to content

Epic: one owner per workflow verdict — phase status, verification, gates, runtime activation, planning writes #5056

Closed
16 of 16 issues completed

Description

@trek-e

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, foldPhaseStatus and derivePhaseStatusLabel are deleted
  • No verification artifact written during verification is an input to its own digest; the fingerprint is idempotent (property test); VerificationStatus is a closed enum shared by gsd-verifier and verification.cts; stale has one routing table and a command that regenerates, proven by a two-cycle verify ending passed
  • 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 PlanningDoc seam, and the lint sees line-indexed and split/join edits
  • The ADR is ratified Accepted at closeout and /adr-phase-coverage reports zero orphans

Non-goals

🤖 Generated with Claude Code

Activity

  1. added
    area: corePROJECT.md, REQUIREMENTS.md, templates
    type: choreMaintenance, refactoring
    epicTracks a multi-phase deliverable with sub-issues
    on Sep 27, 2026
  2. added a commit that references this issue on Sep 27, 2026
  3. self-assigned this
    on Sep 27, 2026
  4. added 6 commits that reference this issue on Sep 28, 2026
  5. 156 remaining items

  6. added 3 commits that reference this issue on Oct 4, 2026
  7. added a commit that references this issue on Oct 4, 2026
  8. added a commit that references this issue on Oct 4, 2026
  9. added 3 commits that reference this issue on Oct 4, 2026
  10. added a commit that references this issue on Oct 5, 2026
  11. added a commit that references this issue on Oct 5, 2026
  12. trek-e commented on Oct 29, 2026

    @trek-e
    CollaboratorAuthor

    Roll-up: every arm shipped, ADR-5057 ratified

    Closing as completed. Verified against next @ a58d8aaac6.

    Phase Arm PR
    0 design lock #5058 (scope-resolver amendment #5141)
    1 A: Phase Status Module #5077
    2 B: fingerprint closed and idempotent #5103
    3 B: no verify-lifecycle write after fingerprint #5114
    4 B: closed VerificationStatus, one stale route #5131
    5 B: detectDrift whole change set #5137
    6 C: no gate in a router #5144
    7 C: one evaluation-scope resolver #5168
    8 C: typed evidence, verdict-driven exit #5171
    9 C: gate positive controls #5205
    10 D: runtime descriptor owner #5206
    11 D: hook registration table #5208
    12 D: activation probe, advertised == registered #5216
    13 E: planning mutations via PlanningDoc #5218
    14 ratification, Arm C closeout #5220

    Coverage check. /adr-phase-coverage was 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 is Accepted (ratified 2026-10-04, Phase 14).

    Arm E. The four sites in the ADR's census are at zero: applyRoadmapEdits is deleted, the phase.cts checkbox flip goes through updateBullet, and the cross-reference loop is replaced by replaceProse (PROJECT.md) and readModifyWriteStateMd (STATE.md). no-adhoc-markdown-parsing has the adhocSplitJoinMutation and adhocLineIndexedMutation detectors 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 stripTemplatePlaceholders in src/state-transition.cts belongs to it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area: corePROJECT.md, REQUIREMENTS.md, templatesepicTracks a multi-phase deliverable with sub-issuestype: choreMaintenance, refactoring

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions