# Tracking Issue Lifecycle State Implementation Handoff

## Status

- Date: 2026-05-21
- Source: GitHub issue `graysurf/agent-kit#270`.
- Issue URL: <https://github.com/graysurf/agent-kit/issues/270>
- Intended next step: prepare the existing issue with plan-tracking snapshots, then execute the sibling plan.
- Recommended plan:
  `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-plan.md`
- Recommended execution state:
  `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-execution-state.md`

## Purpose

Harden the lightweight plan-tracking issue lifecycle so issue-backed execution can audit and repair current-state dashboards from the
append-only source, plan, state, session, and validation comments. The goal is to prevent drift between local scratchpad Markdown and the
GitHub issue comments that become authoritative once `execute-from-tracking-issue` starts.

## Confirmed Facts

- Issue #270 is open and marked `ready-for-implementation`.
- Issue #270 asks for one canonical `execute-from-tracking-issue:state:v1` task ledger schema.
- Issue #270 asks for GitHub issue comments to be authoritative after issue-backed execution starts.
- Issue #270 asks for deterministic dashboard rendering or repair so the mutable issue body can be recomputed from append-only comments.
- Issue #270 asks for lifecycle checkpoint rules for start, session, validation, PR open, PR merge, complete, and blocked states.
- Issue #270 asks for a validator or dry-run audit that detects dashboard/state drift before closeout.
- Related issue #269 is already closed, and its repair work landed in PR #271.
- The current `tracking-issue-closeout` helper already parses issue comments and renders a final dashboard for closeout.
- The current `execute-from-tracking-issue` skill is workflow-only and has no deterministic renderer, validator, or helper script.

## Decisions

1. Do not open a second provider issue. Issue #270 is the durable tracking issue for this work.
2. Prepare issue #270 with equivalent `plan-tracking-issue` source and plan snapshot comments before execution.
3. Add a deterministic helper under `execute-from-tracking-issue` instead of stretching the closeout helper.
4. Keep append-only execution comments authoritative. Local execution-state files are scratchpads or recovery inputs after issue-backed
   execution starts.
5. Make the helper audit-first: dry-run validation and render outputs must work without mutating GitHub.
6. Keep final closeout behavior owned by `tracking-issue-closeout`.

## Scope

- Add a canonical schema and lifecycle checkpoint contract to `execute-from-tracking-issue`.
- Add a deterministic helper script for issue lifecycle audit and dashboard rendering.
- Add focused tests for schema validation, dashboard rendering, and drift detection.
- Update issue workflow docs and tooling index references for the new helper.
- Add a changelog entry for the user-visible workflow capability.

## Non-Scope

- Do not change `plan-tracking-issue` issue creation behavior.
- Do not replace `tracking-issue-closeout` final closeout and closed-dashboard repair behavior.
- Do not introduce dispatch `plan-issue` runtime semantics into lightweight plan tracking.
- Do not make local execution-state Markdown the authoritative record after issue-backed execution starts.
- Do not merge or close issue #270 unless explicitly requested after implementation review.

## Implementation Boundaries

- `execute-from-tracking-issue` owns in-progress lifecycle state, session, validation, and dashboard rendering.
- `tracking-issue-closeout` owns final closeout checks, closeout comments, and issue closure.
- `plan-tracking-issue` owns provider issue creation and source/plan snapshot comments.
- The new helper can share marker names and parsing ideas with closeout, but it should expose an execution-lifecycle report schema distinct
  from the closeout report.

## Requirements

- The canonical task ledger columns are exactly `ID | Status | Task | Evidence | Notes`.
- The helper must reject or warn on state comments that use a different task ledger shape.
- The helper must locate the latest source snapshot, plan snapshot, state, session, and validation comments by stable marker lines.
- The helper must render a compact current dashboard from latest append-only comments.
- The helper must compare the existing issue body to the rendered dashboard and report body drift.
- The helper must detect stale dashboard links to state, session, or validation comments.
- The helper must support fixture-driven dry runs through local issue JSON.
- The helper must optionally repair the mutable issue body in live mode while avoiding append-only comment duplication.
- Docs must define checkpoint expectations for start, session, validation, PR open, PR merge, complete, and blocked states.

## Acceptance Criteria

- Focused tests fail without the new helper and pass after implementation.
- `execute-from-tracking-issue` has a documented deterministic helper entrypoint.
- Dry-run audit outputs a JSON report with marker presence, schema status, dashboard drift, and rendered dashboard paths when requested.
- Dashboard rendering links to the latest state/session/validation comments when those comments have URLs.
- Body repair updates only the issue body; it does not post state/session/validation/closeout comments.
- Skill docs state that local execution-state files are scratchpads or recovery inputs after issue-backed execution starts.
- Issue workflow docs preserve the sequence: `plan-tracking-issue` -> `execute-from-tracking-issue` -> `tracking-issue-closeout`.
- `scripts/check.sh --all` passes before reporting implementation complete.

## Validation Plan

- `plan-tooling validate --file docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-plan.md --format text --explain`
- `scripts/check.sh --tests -- -k execute_from_tracking_issue`
- `scripts/check.sh --markdown`
- `git diff --check`
- `scripts/check.sh --all`

## Risks And Guardrails

- A broad helper can blur execution and closeout ownership. Keep closeout-only gates and issue closure in `tracking-issue-closeout`.
- A live repair flag can accidentally hide append-only evidence gaps. Make repair body-only and require a successful audit model.
- Dashboard drift checks can be too brittle if they compare entire Markdown bodies. Detect material links and status fields rather than
  demanding byte-for-byte equality.
- Entry point changes require script smoke spec and tooling index updates.

## Execution

- Recommended plan:
  `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-plan.md`
- Recommended execution state:
  `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-execution-state.md`
- Status: ready for sibling plan execution.
- Next-task source:
  `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-plan.md`

## Retention Intent

This source document is a plan-created coordination artifact. It can be cleaned up after the helper, docs, tests, issue snapshots, PR, and
issue timeline all reflect the same lifecycle-state contract.

## Open Questions

- None. The exact helper filename and output schema names can be chosen during implementation as long as they are documented and tested.

## Read-First References

- `skills/workflows/issue/execute-from-tracking-issue/SKILL.md`
- `skills/workflows/issue/execute-from-tracking-issue/tests/test_workflows_issue_execute_from_tracking_issue.py`
- `skills/workflows/issue/tracking-issue-closeout/bin/tracking_issue_closeout.py`
- `skills/workflows/issue/tracking-issue-closeout/tests/test_workflows_issue_tracking_issue_closeout.py`
- `skills/workflows/issue/README.md`
- `docs/runbooks/skills/TOOLING_INDEX_V2.md`
