ci(roadmap): fail validation when a change adds required work to a completed epic #161

Reframed on 2026-10-16 as one implementable CI task. Verified against main at 04a2816: nothing of this exists yet. roadmap/scripts/validate.py, health.py and completion.py never read lifecycle; .github/workflows/roadmap-validate.yml checks out the PR head only (no fetch-depth, no merge base) and runs validate.py roadmap/epics on the final tree. The trigger case #152 was closed unmerged and split into #162 (open, no FinOps change). roadmap/epics/agent-finops.yaml is still lifecycle: completed.

Invariant

A roadmap change must not add a new required work item to an epic whose lifecycle is completed while leaving that lifecycle completed. To extend completed work, the same change must add the item as optional or move the epic back to active (or paused).

Work

1. Diff-aware check script

Add roadmap/scripts/lifecycle_guard.py (name indicative) that takes a base ref (or a base directory of manifests) and the head manifests and, for every epic whose head lifecycle is completed:

• fails if the set of required: true work-item ids grew relative to base;
• fails if an existing item flipped from required: false to required: true;
• fails for a manifest that is new in head, born completed, and holds a required item that is not bound and closed;
• passes if the same change moves the lifecycle from completed to active or paused (that is the explicit, reviewed reopening);
• treats an unreadable base as an error, never a pass: a missing merge base, a shallow checkout without the base commit, an unreadable or malformed base manifest each exit non-zero with a distinct message. Per AGENTS.md "could not observe" is never "observed absent".

A manifest that is deleted in head is not a violation of this check.

2. Wire it into roadmap-validate.yml

• On pull_request: check out with enough history to resolve the merge base (fetch-depth: 0 or a targeted fetch of github.event.pull_request.base.sha), compute git merge-base, and run the guard between that commit and the head tree. A failed merge-base lookup fails the job.
• On push to main: run the guard against the parent commit (github.event.before) or skip with an explicit "no base" notice. Do not silently pass.
• Keep permissions: {}.

3. Tests

• Unit tests in roadmap/tests/test_lifecycle_guard.py using in-memory or fixture manifests for every bullet in section 1, including the error cases for an unreadable base.
• Add the mutation to roadmap/tests/mutations.py so the existing mutation harness exercises it.
• Prove it both ways, as AGENTS.md requires: green on the current roadmap/epics against its own parent, red on a branch that reapplies the feat(roadmap): add adaptive agent runtime assurance #152 FinOps hunk (add a required trajectory-economics item to agent-finops.yaml while it stays completed), and red again on that mutation when the guard step is removed from the workflow. Paste the three run links in the PR.

4. Document

One paragraph in roadmap/README.md under the validation section: what the guard checks, how to reopen a completed epic legitimately.

Out of scope (separate issue if wanted)

A state-based check that flags an epic whose manifest says completed while completion.py computes incomplete. It catches drift without a manifest diff (a required issue reopened on GitHub) and is complementary, not a substitute. Open it as its own issue if the implementer thinks it is cheap; do not fold it into this PR.

Acceptance

• The guard fails on the feat(roadmap): add adaptive agent runtime assurance #152 mutation and passes on roadmap: add agent runtime assurance epic (split of #152, no FinOps change) #162 (the split without the FinOps commit) rebased on current main.
• An unreadable base, a missing merge base, or a malformed base manifest is a failed check with a distinct error, never a pass.
• python3 -m unittest discover -s roadmap/tests -p 'test_*.py' stays green.

Refs #152, #155, #162

History

Original body (2026-10-16, before reframing):

Invariant

A roadmap change MUST NOT add a new required work item to an epic whose lifecycle is completed while leaving that lifecycle completed. To extend completed work, the same governed change must either add the item as optional or explicitly transition the epic back to active.

Why

#152 adds a required trajectory-economics item to agent-finops.yaml. That epic became completed in #155 after #152 was opened. The merge is textually clean, because #155 touched only the lifecycle line, and on the rebased branch every current check passes: validate.py over all 18 epics and the 318 roadmap tests. The result would be a manifest that says completed while holding an open, unbound required item. Nothing reports that:

• lifecycle appears only in the schema enum and in publish.py, which copies it into the publication.
• validate.py, completion.py, health.py, reconcile.py, plan.py and ready.py never read it.
• completion.py would compute incomplete, and no check compares that with lifecycle: completed. The reconciler would only note BindingUnbound.

Both Claude approvals on #152 were given against a base where FinOps was still active, so no reviewer saw the conflict either.

Shape of the check

It must be diff-aware against the base. A validator that reads only the final YAML cannot tell "a required item was added after completion" from "this item was always there". Proposed:

• In roadmap-validate.yml on pull_request, compare every manifest under roadmap/epics/ against the merge base.
• For each epic whose head lifecycle is completed: fail if the set of required: true work-item ids grew relative to base, or if an existing item flipped from required: false to true. The same applies to a new manifest that is born completed with an item that is not bound and closed.
• Pass if the same change moves the lifecycle from completed to active or paused. That is the explicit, reviewed reopening.

Possible second, state-based check

As a separate check: health or publication flags an epic whose manifest says completed while the computed completion is not complete. This catches drift that arrives without a manifest diff, such as a required issue reopened on GitHub. It is complementary to the diff check, not a substitute.

Acceptance

• The guard fails on feat(roadmap): add adaptive agent runtime assurance #152 as it is today (the deliberate mutation) and passes on the split without the FinOps commit.
• Per AGENTS.md, it is proven both ways: green on a converged input, red on the mutation, and red again when the fix is reverted.
• An unreadable base, such as a shallow checkout or a missing merge base, is a failed check, never a pass.

Refs #152, #155