# Plan: Tracking Issue Lifecycle State

## Overview

Add a deterministic lifecycle audit and dashboard rendering helper for `execute-from-tracking-issue`, then document the canonical
issue-backed state schema so lightweight tracking issues can detect state/body drift before closeout.

## Read First

- Primary source: `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-discussion-source.md`
- Source type: discussion-to-implementation-doc
- Open questions carried into execution: none

## Execution

- Execution state: `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-execution-state.md`

## Scope

- In scope:
  - `skills/workflows/issue/execute-from-tracking-issue/SKILL.md`
  - `skills/workflows/issue/execute-from-tracking-issue/bin/tracking_issue_lifecycle.py`
  - `skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh`
  - `skills/workflows/issue/execute-from-tracking-issue/tests/test_workflows_issue_execute_from_tracking_issue.py`
  - `tests/script_specs/skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh.json`
  - `skills/workflows/issue/README.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `CHANGELOG.md`
- Out of scope:
  - `plan-tracking-issue` issue creation changes.
  - `tracking-issue-closeout` final closeout and closure behavior.
  - Dispatch `plan-issue` runtime behavior.
  - Automatic PR merge or issue close.

## Assumptions

1. A focused Python helper is appropriate because `tracking-issue-closeout` already uses that shape for issue parsing and rendering.
2. Dashboard drift should be audited through material fields and latest comment URLs, not byte-for-byte body equality.
3. The first helper can be GitHub-focused because `execute-from-tracking-issue` is GitHub-specific.
4. Issue #270 can be prepared with source and plan snapshots instead of creating a duplicate tracking issue.

## Sprint 1: Canonical State Schema And Helper Surface

**Goal**: Give `execute-from-tracking-issue` a deterministic helper that can parse issue comments and enforce the canonical state ledger
shape.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k execute_from_tracking_issue`
- Verify:
  - The helper entrypoint exists and supports `--help`.
  - State comments with `ID | Status | Task | Evidence | Notes` pass schema checks.
  - State comments missing `Evidence` fail or report drift.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 1.1: Add failing coverage for lifecycle helper contract

- **Location**:
  - `skills/workflows/issue/execute-from-tracking-issue/tests/test_workflows_issue_execute_from_tracking_issue.py`
- **Description**: Add tests for a future helper module, canonical state table parsing, missing marker checks, and script smoke coverage.
- **Dependencies**:
  - none
- **Complexity**: 2
- **Acceptance criteria**:
  - Tests expect an entrypoint under `scripts/tracking-issue-lifecycle.sh`.
  - Tests expect a report schema distinct from closeout.
  - Tests expect noncanonical state columns to be reported as state schema drift.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_from_tracking_issue`

### Task 1.2: Implement lifecycle issue parsing and schema audit

- **Location**:
  - `skills/workflows/issue/execute-from-tracking-issue/bin/tracking_issue_lifecycle.py`
  - `skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh`
  - `tests/script_specs/skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh.json`
- **Description**: Add a Python helper plus shell entrypoint that loads issue JSON or live `gh issue view`, finds marker comments, validates
  the state ledger schema, and emits a JSON lifecycle audit report.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 4
- **Acceptance criteria**:
  - `--issue-json` works only with `--dry-run`.
  - Missing source, plan, or state markers are reported as failed checks.
  - Canonical state columns are extracted and reported.
  - Noncanonical state columns produce a failed `state schema` check.
  - `--report-out` writes deterministic JSON.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_from_tracking_issue`

## Sprint 2: Dashboard Rendering And Drift Audit

**Goal**: Recompute the mutable issue dashboard from latest append-only comments and detect stale issue-body links before closeout.
**Demo/Validation**:

- Command(s):
  - `scripts/check.sh --tests -- -k execute_from_tracking_issue`
  - `scripts/check.sh --markdown`
- Verify:
  - A current dashboard can be rendered from source, plan, state, session, and validation comments.
  - Stale dashboard links to old state/session/validation comments are detected.
  - Body repair remains body-only.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 2.1: Add dashboard and drift tests

- **Location**:
  - `skills/workflows/issue/execute-from-tracking-issue/tests/test_workflows_issue_execute_from_tracking_issue.py`
- **Description**: Add fixtures that include latest state/session/validation comment URLs and an issue body pointing at stale URLs.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Tests assert the rendered dashboard uses the latest comment URLs.
  - Tests assert stale body pointers are reported as dashboard drift.
  - Tests assert repair mode does not render or post append-only comments.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_from_tracking_issue`

### Task 2.2: Implement dashboard rendering, drift report, and body repair

- **Location**:
  - `skills/workflows/issue/execute-from-tracking-issue/bin/tracking_issue_lifecycle.py`
  - `skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh`
- **Description**: Render a compact dashboard from latest comments, report stale body pointers, and expose an explicit body-only repair mode.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 5
- **Acceptance criteria**:
  - `--body-out` writes the rendered current dashboard.
  - `--repair-body` requires a successful model and updates only `gh issue edit --body-file` in live mode.
  - Dry-run repair writes body/report files without GitHub mutations.
  - The report includes `dashboard_drift`, `stale_links`, `ready`, and `repair_body`.
- **Validation**:
  - `scripts/check.sh --tests -- -k execute_from_tracking_issue`

## Sprint 3: Docs, Snapshots, And Validation

**Goal**: Document the lifecycle checkpoint contract, prepare issue #270 for issue-backed execution, and validate the repo.
**Demo/Validation**:

- Command(s):
  - `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`
- Verify:
  - The plan validates.
  - Focused tests and full gate pass.
  - Issue #270 has source and plan snapshot comments before execution-state comments.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 3.1: Document lifecycle checkpoints and helper usage

- **Location**:
  - `skills/workflows/issue/execute-from-tracking-issue/SKILL.md`
  - `skills/workflows/issue/README.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `CHANGELOG.md`
- **Description**: Update docs to describe the canonical task ledger, checkpoint expectations, audit helper, and body-only dashboard repair.
- **Dependencies**:
  - Task 2.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Docs define start, session, validation, PR open, PR merge, complete, and blocked checkpoints.
  - Docs state that issue comments are authoritative and local execution-state Markdown is a scratchpad or recovery input.
  - Tooling index lists the helper entrypoint.
  - Changelog records the new user-visible workflow helper.
- **Validation**:
  - `scripts/check.sh --markdown`

### Task 3.2: Validate and persist execution evidence

- **Location**:
  - `docs/plans/tracking-issue-lifecycle-state/tracking-issue-lifecycle-state-plan.md`
  - `skills/workflows/issue/execute-from-tracking-issue/tests/test_workflows_issue_execute_from_tracking_issue.py`
  - `skills/workflows/issue/execute-from-tracking-issue/bin/tracking_issue_lifecycle.py`
  - `skills/workflows/issue/execute-from-tracking-issue/SKILL.md`
- **Description**: Run plan validation, focused tests, markdown checks, whitespace checks, and the full repository gate; fix any in-scope
  drift before opening a PR.
- **Dependencies**:
  - Task 1.2
  - Task 2.2
  - Task 3.1
- **Complexity**: 2
- **Acceptance criteria**:
  - Plan validation passes.
  - Focused lifecycle tests pass.
  - Markdown checks pass.
  - `git diff --check` passes.
  - `scripts/check.sh --all` passes.
  - Issue #270 receives state/session/validation comments that reference the final commit/PR.
- **Validation**:
  - `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 Gotchas

- Keep the helper GitHub-specific; do not imply GitLab support for `execute-from-tracking-issue`.
- Do not duplicate closeout checks in a way that creates conflicting close policies.
- Avoid broad body equality checks; future dashboard wording should not break audit when durable links and status are current.
- New entrypoints require script smoke specs and ownership checks.
