magnus919_agent-skills/neckbeard/references/lifecycle.md

Change Lifecycle Integration

The platform mechanics for carrying a change request from intake to an authorized post-merge release. This reference is loaded by ../SKILL.md only for change-request / issue-to-PR / ticket-to-release work — a request that will produce a pull request or an equivalent reviewable deliverable. A single-line edit, an ad-hoc fix, or a review without an issue/ticket trajectory does not load this reference; that work uses the core loop in ../SKILL.md.

The lifecycle does not invent phases or gates. It maps onto the nine-phase change-request journey (journey.md) and the five gates (stages.md). It records its outcomes in the delivery packet (delivery-packet.md), field group (i) — PR/review-submission number, CI status, review status, final verified head SHA, release status, and terminal-state evidence plus rollback/follow-up triggers and closeout lesson capture. Stop and escalation rules live in risk-authority-gates.md.

Two modes, one structure

The workflow is platform-neutral. Two documented modes share the same phase sequence, the same five gates, and the same packet fields; only the platform mechanics differ.

	GitHub reference mode	Enterprise mode
Use when	The target repository is public/open-source (public remote, open-source license, contribution governance).	The target repository is private or enterprise-internal: ticket trackers, private hosting, enterprise review and CI tooling, change governance.
Source of truth	An issue in the repository tracker.	A ticket, email thread, or verbal request.
Review submission	A pull request.	An enterprise change request / review submission.
Authority to merge	Maintainer action on a protected branch.	Enterprise approval workflow / change manager.
Authority to release	A separate grant beyond merge.	A separate authorization (CAB, change-manager sign-off, change-freeze window).

Mode selection is recorded in packet group (b). GitHub is a documented reference mode, never the assumed default. Enterprise mode makes no open-source assumption — no public visibility, no fork-based contribution, no community norms.

---

GitHub reference mode

GitHub mechanics are described here; contribution norms are delegated to the catalog skill opensource-contributions and are discovered per repository, never hardcoded.

Contribution-norm delegation (public/OSS only)

Load opensource-contributions only when the repository is public/OSS (public remote and an open-source license). It owns contribution-norm detail: CONTRIBUTING.md interpretation, agent disclosure, fork etiquette, commit conventions, PR templates, and post-submission etiquette. This reference delegates to it and does not re-derive its content.

If the repository is private or enterprise-internal, do not load opensource-contributions; use enterprise mode below, and record the skip in packet group (e) with the reason "non-public repository."

1. Snapshot the issue and repository context before planning — phase 1

Before any planning or implementation begins, capture all of the following as mandatory intake artifacts. The phase 1 intake gate (journey.md) cannot be satisfied without them.

• Issue body — the full request text.
• All issue comments — not just the opening post.
• Linked and referenced work — related issues, PRs, and commits that touch the same problem.
• Repository conventions — CONTRIBUTING.md, AGENTS.md, .github/ templates, or equivalent, discovered per repository.
• Base ref — the current base branch ref the change will target.

Record these in packet group (a). Planning may not start until the snapshot is complete.

2. Classify authority — phase 1

Classify the granted authority into four separate classes and record each before implementation. These complement the authority classes in risk-authority-gates.md (Explore / Modify / Publish / Deploy / Merge); they are never collapsed into a single "has access" judgment.

Class	Scope
Contributor	Can fork, branch, and open a PR.
Maintainer	Can approve, review, and close.
Merge	Can land a change into a protected branch.
Release	Can tag, publish, or deploy.

Record the granted class per row in packet group (b). A contributor grant does not imply merge or release authority. Merge authority does not imply release authority (see Authority boundary).

3. Pre-work integrity checks — phases 1–2

These checks run before a branch is created and before work proceeds. Each has its own recorded outcome in the packet; they are distinct, not one merged check.

Check	What it does	Recorded outcome
Duplicate-issue search	Search the repository issue tracker for an existing issue describing the same or overlapping problem.	"duplicate found and handled" or "no duplicate."
Existing-PR search	Search for open and recently closed PRs addressing the same issue or problem, including PRs from other contributors not linked to the issue.	"PR found — see handling" or "no existing PR."
Conflicting-branch check	Check whether another contributor has already pushed a branch targeting the same issue or change surface.	Coordinate, wait, or proceed-with-awareness decision.
Maintainer-direction review	Review issue comments, assignments, labels, and governance docs for explicit direction ("I'll handle this," "don't work on this yet," "assigned to X," a deferral label).	Proceed, or stop/escalate if direction conflicts.

Maintainer direction is a hard gate. If maintainer direction conflicts with proceeding, the agent must not proceed regardless of the other checks. This is consistent with the stop rules in risk-authority-gates.md.

Handling an existing open PR (no duplicate work). When the existing-PR search finds an open PR addressing the same problem, decide and record:

• Continue/assist if it is the agent's own prior work — resume from packet state (delivery-packet.md, resumability).
• Coordinate or defer if another contributor owns it.
• Never open a duplicate PR. The decision is recorded in the packet.

4. Determine fork-vs-branch before PR creation — phase 6

Before creating a branch or PR, determine the repository's contribution workflow from CONTRIBUTING.md, .github/ conventions, or maintainer direction — per repository, never assumed:

• Fork-and-PR vs branch-in-repo.
• Record the choice in the packet, and apply fork etiquette via opensource-contributions when a fork is required.

The lifecycle never assumes a branch-in-repo workflow or leaves the mode implicit.

5. PR readiness, submission, and merge are separate states — phases 6–8

These three states are explicitly distinct; reaching one does not grant the next.

State	Meaning	Who controls it
Ready	Code complete, self-reviewed, tests pass locally, verification evidence recorded.	The agent can reach this independently.
Submitted	The pull request is opened.	The agent performs the act of opening.
Merged	The change lands in the protected target.	Requires maintainer action plus passing CI and approved review — not the agent's own readiness assessment.

Merge is gated on external authority beyond the agent's readiness declaration.

Issue linkage and closing keywords. The PR body must (a) reference the source issue by number and (b) use the repository's own closing-keyword convention, discovered from CONTRIBUTING.md or project norms (e.g., Closes #N, Fixes #N, Resolves #N). If the repository specifies no convention, use a defensible default: Closes #N.

PR body content. Beyond the issue link and closing keyword, the PR body describes the change — what it does, why, and how it was verified — and follows the repository's PR template if one exists (discovered per repository).

6. Post-submission monitoring — phase 8

After the PR is submitted, both monitors are mandatory and run until they terminate; checking once is not enough.

CI monitoring. Monitor CI status until CI completes. CI failure is a blocking condition: the PR is never merge-ready while CI is red. When CI is red, triage it:

1. Diagnose the failure from the logs.
2. Fix it if the failure is attributable to the change.
3. Escalate when the failure is undiagnosable after two attempts (per risk-authority-gates.md).

Never consider the PR merge-ready, and never merge it, while CI is failing.

Review monitoring. Monitor for review feedback (comments, change requests, approvals) and respond to material feedback with code changes rather than argument. Review monitoring is distinct from CI monitoring.

7. Material change and exact-head binding — phases 7–8

Every material change pushed after initial submission — any change that alters behavior, fixes a bug, or responds to review feedback beyond a trivial typo fix — invalidates prior verification verdicts and must return through both independent review (gate 4) and boundary verification (gate 5) before the PR is merge-ready again. A stale verdict on a superseded head SHA is never carried forward; the new head is independently verified.

Materiality uses the canonical definition owned by stages.md (§ Gate 5 — Material change definition):

• Material (invalidates verdicts, re-verify): alters logic, adds/removes functionality, modifies the verification surface, changes test assertions, or alters data flow across a trust boundary.
• Non-material (verdicts stand, SHA binding updated): typo fixes, formatting-only, comment-only edits, pure renames without behavior change, docs-only changes, and rebases with no semantic diff.

The merge-readiness verdict is bound to the exact full head SHA. No verdict is valid without a bound SHA, and a verdict referencing a different SHA (e.g., from before a rebase or force-push) is explicitly stale and insufficient.

Update the final-verified-head-SHA field after every review round. Each review round ends with packet group (i) final verified head SHA refreshed to the current head and fresh verification evidence recorded for that head:

• A round that pushes a change updates the field and re-runs verification.
• A round that changes nothing keeps the existing SHA.

The final verdict is always bound to the exact final head of the delivered change. This is the same rule expressed in journey.md phase 8 and in the packet's exact-head-binding section.

---

Enterprise mode

Enterprise mode uses the same nine phases and five gates as GitHub mode. It makes no open-source assumption and does not reference opensource-contributions.

1. Source-of-truth snapshot — phase 1

Capture the authoritative request from wherever it actually lives — it is not assumed to be a GitHub issue:

• A ticket-tracker entry (ticket ID, description, comments), or
• an email thread, or
• a verbal request (transcribed with attribution).

Record the snapshot, the repository, and the base ref in packet group (a). The phase 1 intake gate cannot be satisfied without it.

2. Duplicate / existing-change-request check — phases 1–2

Equivalent to the GitHub duplicate-issue and existing-PR checks:

• Search the ticket tracker for an open change request covering the same problem.
• Search for any existing change branch / CR in flight.
• Record the result. If one exists, coordinate or defer.

Enterprise intake does not end at snapshotting the ticket; the dedup outcome is recorded in the packet.

3. Authority classification and approval gate — phases 1, 7

Classify authority using the same four classes as GitHub mode (contributor, maintainer-equivalent, merge, release) and record them in packet group (b).

Explicit approval gate. Enterprise review requires a named approver sign-off that the merge gate depends on:

• a named reviewer/approver;
• a recorded verdict in the packet;
• the verdict feeds the merge gate (phase 8 readiness → merge).

This is the enterprise equivalent of GitHub review approval (gate 4). Review is not merely "integrating with review tooling" — it produces a recorded approval verdict.

4. Enterprise CI and change governance — phase 8

• Enterprise CI. Integrate with the enterprise CI system (not assumed to be any particular provider); monitor it after submission exactly as GitHub mode monitors CI, and triage red CI (diagnose, fix, or escalate). The PR/change is never merge-ready while CI is red.
• Change-governance boundaries. Respect CAB approval, segregation-of- duties constraints, and change-freeze windows. A change-freeze that blocks deployment is an escalation condition (journey.md phase 9).

5. Release authority separation — phase 9

Release activity (deploy, publish, promote) requires explicit authorization distinct from merge approval — for example CAB approval, change-manager sign-off, or change-freeze-window clearance. The merge/approval gate alone does not authorize release. Record the authorization in the packet's release status field. This mirrors the GitHub-mode authority boundary and the release gate in risk-authority-gates.md.

Packet portability across modes

The packet is mode-agnostic: the same nine field groups, with the same field names and semantics, are populated in both modes. GitHub-only fields have documented enterprise equivalents:

Packet field (group i)	GitHub mode	Enterprise equivalent
PR (review-submission) number	Pull-request number	Enterprise change-request / review ID
CI status	Hosted CI result	Enterprise CI result
Review status	PR review approval	Named-approver sign-off verdict
Final verified head SHA	Head commit SHA	Head commit SHA (identical)
Release status	Tag/publish disposition	Deploy/promote disposition (CAB/clearance)

No packet field is fillable only in GitHub mode.

---

Authority boundary: readiness vs release

Pre-merge release readiness and post-merge release activity are separate gates with separate authority, in both modes.

• Release readiness (pre-merge, assessable): the change is releasable — version bumped, changelog updated, migration documented, rollback plan exists. This can be confirmed before merge and feeds the readiness gate (phase 8).
• Release activity (post-merge, gated): tagging, publishing artifacts, deploying, announcing. This is a separate gate requiring explicit authorization beyond merge authority. Merge does not imply release.

The merge gate verifies readiness; release execution is gated on a separate explicit authorization. See risk-authority-gates.md for the merge gate and release gate definitions.

Release execution records post-release verification

The release gate does not end at the authorization grant. Before the released terminal state is declared, record post-release verification evidence — a post-release smoke check, deploy/tag confirmation, or artifact checksum — in the packet's release status field.

---

Terminal states

Exactly four terminal states end a lifecycle, each requiring specific evidence recorded in packet group (i). There is no ambiguous "done" without evidence.

Terminal state	Meaning	Required evidence
merged	Landed into the protected target.	The merge commit SHA.
closed	Not merged; ended without code.	The close reason (e.g., duplicate, already fixed, withdrawn).
blocked	Cannot proceed.	Blocker evidence — the blocking condition and any escalation outcome.
released	Authorized post-merge release completed.	Release evidence (tag, artifact, deploy confirmation, post-release smoke check). Terminal — no transitions out.

These are the same terminal states defined by the packet (delivery-packet.md, lifecycle states) and by journey phase 9 closeout (journey.md). A terminal packet is never re-opened; new work starts a new packet. Closeout also records rollback/follow-up triggers — what would cause re-entry — and lesson capture per Stage 6 "Deliver and learn" (stages.md): the reusable lesson(s) with their durable destination, or an explicit "no reusable lesson identified" determination — in group (i); a fired trigger starts a new change request via phase 1 intake, it does not resurrect the terminal packet.

Reduced paths still terminate with evidence

A reduced (lightweight) run terminates in a defined terminal state, not an unspecified early stop:

• A no-change-needed run records the determination and transitions to closed with the close reason and its evidence (no PR created).
• A docs-only change that ships reaches merged with the merge SHA (doc- update evidence).

The packet's terminal lifecycle state field is populated on every reduced path.

External cancellation mid-flight

If the change request is closed or cancelled by an external actor at any phase after intake — a maintainer closes the issue, a ticket is withdrawn, a PR is closed by a maintainer — the packet transitions to the appropriate terminal state (closed or blocked) with the external closure as evidence, and the remaining phases are not executed. This is distinct from the no-change-needed termination (journey.md) and from the gate-failure blocked state (delivery-packet.md).

---

Delivery-packet fields this reference reads and writes

The lifecycle records its outcomes in the packet. It reads provenance and authority from groups (a)–(b) and writes to the groups below; every named field exists in delivery-packet.md.

Lifecycle step	Packet field(s)	Group
Snapshot the issue / source of truth	Issue snapshot (request text, comments, linked work)	(a)
Classify authority	Authority class (contributor / maintainer / merge / release)	(b)
Record mode and pre-work check outcomes	Workflow mode; dedup/PR/branch/maintainer-direction decisions	(b), (e)
Open the PR / review submission	PR (review-submission) number	(i)
Monitor CI	CI status	(i)
Monitor review	Review status	(i)
Bind verdicts per review round	Final verified head SHA	(i)
Assess release readiness and execute release	Release status (with post-release verification evidence)	(i)
Close out	Terminal lifecycle state + terminal-state evidence (merge SHA / close reason / blocker evidence / release evidence) + rollback/follow-up triggers + lesson capture (or "no reusable lesson identified")	(i)

Field group (i) — PR number, CI status, review status, final verified head SHA, release status, terminal-state evidence, rollback/follow-up triggers, and lesson capture — is the exact set this reference populates; the match is bidirectional (no field here that the packet lacks, and no group-(i) field the lifecycle never writes).

Lifecycle-to-journey mapping

Every lifecycle step and every packet lifecycle state maps onto a journey phase that journey.md defines. No phase here is invented or renamed.

Lifecycle step	Journey phase
Snapshot, authority classification, pre-work checks, fork-vs-branch decision	Phase 1 (intake and provenance) and phase 6 (implementation) for branch creation
Duplicate / dedup and discovery	Phase 2 (current-state discovery and reproduction)
Implementation commits	Phase 6 (domain-specific implementation)
Independent review, boundary verification, CI/review monitoring, exact-head re-verification, readiness	Phase 7 (independent review and boundary verification) and phase 8 (readiness, CI/review loops)
Merge / approval gate	Phase 8 → phase 9 boundary
Authorized release, closeout, terminal-state evidence	Phase 9 (authorized post-merge release and closeout)

Packet lifecycle state	Journey phase
intake	Phase 1
planning	Phases 2–5
implementation	Phase 6
in-review	Phases 7–8
ready	End of phase 8 (readiness gate passed)
merged / closed / blocked / released	Phase 9 (terminal closeout)