tracking-issue-closeout

name	tracking-issue-closeout
description	Finalize and close plan-tracking GitHub issues after issue-backed execution is complete and the user or project policy has approved closure.

Tracking Issue Closeout

Contract

Prereqs:

• Run inside the target GitHub-backed git repository, or pass --repo <owner/repo>.
• gh is available on PATH, and gh auth status succeeds for live mode.
• python3 is available on PATH.
• The target issue was created by plan-tracking-issue or has equivalent source and plan snapshot comments.
• Issue-backed execution has already completed through execute-from-tracking-issue.
• The user explicitly approved issue closure, or project policy explicitly says this tracking issue closes after successful execution.

Inputs:

• GitHub issue number or URL via --issue <number-or-url>.
• Optional repository override via --repo <owner/repo>.
• Required close authorization via --review-approved or --review-comment-url <url>.
• Optional offline fixture via --issue-json <path> for audit/render dry runs without live GitHub reads.
• Optional output paths for rendered dashboard, closeout comment, and JSON report.
• Optional --skip-pr-checks only when PR merge state has already been verified externally and recorded in the issue.
• Optional --repair-closed for an already closed issue whose final dashboard drifted after execution. This mode is explicit and never closes the issue again.
• Optional --finalize-closed with --repair-closed to append one missing <!-- tracking-issue-closeout:v1 --> comment for an already closed, otherwise complete issue. Existing closeout markers are never duplicated.

Outputs:

• Final issue body dashboard with status, durable record links, validation summary, linked PRs, blockers, and next action.
• Append-only <!-- tracking-issue-closeout:v1 --> closeout comment summarizing checks, outcome, and approval basis.
• Closed GitHub issue with reason completed in live mode.
• In --repair-closed mode, updated final dashboard body and JSON report only by default.
• In --repair-closed --finalize-closed mode, one missing closeout marker may be appended before the dashboard repair; existing markers are left untouched.
• Machine-readable JSON closeout report when --report-out <path> is supplied.
• Concise stdout summary with issue URL, close status, rendered files, and check result.

Exit codes:

• 0: success
• 1: readiness, validation, GitHub mutation, or close gate failure
• 2: usage error

Failure modes:

• Target issue is unreadable, already closed without --repair-closed, open while --repair-closed is selected, or not associated with the selected repository.
• Missing source snapshot, plan snapshot, execution-state comment, or completed session/final summary.
• Latest execution state is not complete, lacks the canonical task ledger, or contains task rows not marked done or deferred.
• Closure is not explicitly approved by the user or by supplied project-policy evidence.
• Validation evidence is absent from execution comments.
• Linked PRs are not merged when live PR checks are enabled.
• Body/comment mutation or issue close fails, leaving the issue open with the failing command reported.

Scripts (only entrypoints)

• $AGENT_HOME/skills/workflows/issue/tracking-issue-closeout/scripts/tracking-issue-closeout.sh

Workflow

1. Read the tracking issue:
   • Live mode: gh issue view <issue> --json number,title,state,body,comments,labels,url.
   • Fixture mode: load --issue-json <path> and require --dry-run.
2. Verify closeout readiness:
   • <!-- plan-tracking-issue:snapshot:v1 kind=source --> exists.
   • <!-- plan-tracking-issue:snapshot:v1 kind=plan --> exists.
   • <!-- execute-from-tracking-issue:state:v1 --> exists.
   • The execution-state marker and status fields are outside any collapsed <details> block when the state comment uses the default collapsed-ledger format.
   • Latest execution state has Status: complete.
   • Every latest execution-state task row is done or explicitly deferred.
   • At least one <!-- execute-from-tracking-issue:session:v1 --> comment exists and the latest session indicates completion.
   • Validation evidence exists in a validation comment or execution session.
   • The user supplied --review-approved or --review-comment-url.
   • Explicit linked PR references are merged unless --skip-pr-checks is used. The parser accepts PR #<number>, pull request #<number>, and GitHub /pull/<number> links; generic issue, decision, task, and bare #<number> references are not PR evidence.
3. Render final issue body as a compact current dashboard. Do not copy the full source, plan, or sprint logs into the body; link the durable snapshot/session comments instead.
4. Render one append-only closeout comment with marker <!-- tracking-issue-closeout:v1 -->.
5. In dry-run mode, write requested body/comment/report artifacts and print the planned actions without mutating GitHub.
6. In --repair-closed mode:
   • Require the issue to already be closed and all other closeout gates to pass.
   • Render and update only the final dashboard body.
   • Do not post a new closeout comment unless --finalize-closed is also supplied and no closeout marker exists.
   • With --finalize-closed, append exactly one missing closeout marker before repairing the dashboard; if a marker already exists, do not duplicate it.
   • Do not call gh issue close.
   • Report mode=repair-closed / repair_only=true, or mode=repair-closed-finalize / finalized_closed_issue=true, in stdout and JSON.
7. In normal live mode:
   • Post the closeout comment first.
   • Update the issue body dashboard, including the closeout comment URL when available.
   • Close the issue with reason completed.
8. Report the final state, issue URL, linked PRs, validation summary, and any accepted caveats.

Relationship To Nearby Skills

• plan-tracking-issue: creates the tracking issue and source/plan snapshot comments.
• execute-from-tracking-issue: executes the issue-backed plan and appends state/session/validation comments; it does not close by default. Execution-state creation remains owned by execute-from-tracking-issue, not by closeout or repair mode.
• issue-follow-up: use for generic GitHub issue timelines that are not tied to plan snapshot markers.
• Shared issue lifecycle tool (skills/workflows/issue/_shared/lib/manage_issue_lifecycle.sh): lower-level generic open/update/comment/close operations.
• dispatch-issue-closeout: use for heavyweight dispatch or plan-issue runtimes with task-lane close gates, approvals, and merged PR checks.