# Plan: Deliver Dispatch Plan

## Overview

Add `deliver-dispatch-plan` as the canonical end-to-end entrypoint for
heavyweight dispatch-ready plan delivery while preserving the existing
`dispatch-plan-delivery` runtime contract. Align dispatch review decisions with
the shared delivery outcome vocabulary, and require the final integration PR to
carry a compact delivery review outcome comment before merge. Keep sprint PR
review evidence in `dispatch-pr-review` so dispatch timelines stay traceable
without duplicating comments.

## Read First

- Primary source: `docs/plans/deliver-dispatch-plan/deliver-dispatch-plan-discussion-source.md`
- Source type: `discussion-to-implementation-doc`
- Execution state: `docs/plans/deliver-dispatch-plan/deliver-dispatch-plan-execution-state.md`
- Open questions carried into execution:
  - Decide wrapper-first soft rename vs full skill-tree move after the reference
    inventory in Task 1.1.
  - Decide whether final integration outcome URL should remain skill-policy-only
    or become a later `plan-issue` CLI gate.

## Scope

- In scope: canonical `deliver-dispatch-plan` entrypoint, compatibility guidance
  for `dispatch-plan-delivery`, shared outcome disposition reuse, dispatch PR
  review evidence alignment, final integration PR outcome comment requirement,
  docs/catalog/reminder alias updates, and focused regression tests.
- Out of scope: runtime root rename, existing runtime migration, nils-cli
  `plan-issue` feature work, deleting the old skill name, mandatory specialist
  review for all sprint PRs, and changes to `dispatch-subagent-pr` ownership.

## Assumptions

1. The first implementation should be a soft rename because existing runtime
   roots and prompt/reference paths use `dispatch-plan-delivery`.
2. The fixed runtime root remains `$AGENT_HOME/out/dispatch-plan-delivery`.
3. Sprint PR review outcomes should stay in `dispatch-pr-review` evidence
   comments, with issue-side URL mirroring.
4. The final integration PR is the correct place for the deliver-level outcome
   comment because it is the PR that merges `PLAN_BRANCH` into `DEFAULT_BRANCH`.
5. `code-review-specialists` remains supplemental and read-only; the dispatch
   decision path stays in `dispatch-pr-review`.

## Sprint 1: Canonical Entrypoint And Compatibility Boundary

**Goal**: Introduce `deliver-dispatch-plan` as the preferred user-facing
entrypoint without breaking existing dispatch runtime paths.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k 'dispatch_plan_delivery or deliver_dispatch_plan'`,
  `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh`
- Verify: the new canonical name is discoverable, the old name remains
  compatibility-safe, and runtime root text still uses
  `$AGENT_HOME/out/dispatch-plan-delivery`.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 1.1: Inventory dispatch-plan-delivery references

- **Location**:
  - `skills/automation/issue/dispatch-plan-delivery/`
  - `skills/workflows/issue/README.md`
  - `README.md`
  - `hooks/codex/skill-usage-reminder.skills.json`
  - `docs/runbooks/skills/SKILL_USAGE_REMINDER_INDEX.md`
  - `scripts/README.md`
  - `scripts/check_plan_issue_worktree_cleanup.sh`
  - `tests/fixtures/issue/`
- **Description**: Classify existing `dispatch-plan-delivery` references into
  user-facing name references, compatibility/runtime path references, fixture
  references, and historical references. Use the inventory to choose the exact
  soft-rename mechanics before editing broad references.
- **Dependencies**:
  - none
- **Complexity**: 3
- **Acceptance criteria**:
  - Inventory distinguishes canonical-name changes from runtime-path references
    that must stay unchanged.
  - In-flight runtime compatibility risks are documented in the implementation
    notes or commit summary.
  - The implementation choice is explicit: wrapper-first soft rename unless the
    inventory proves a full move is low risk.
- **Validation**:
  - `rg -n "dispatch-plan-delivery|deliver-dispatch-plan" .`

### Task 1.2: Add the canonical deliver-dispatch-plan entrypoint

- **Location**:
  - `skills/automation/issue/deliver-dispatch-plan/SKILL.md`
  - `skills/automation/issue/deliver-dispatch-plan/tests/test_automation_deliver_dispatch_plan.py`
  - `skills/automation/issue/dispatch-plan-delivery/SKILL.md`
- **Description**: Add the new canonical skill entrypoint and keep the old
  `dispatch-plan-delivery` skill as compatibility guidance. The new entrypoint
  should own the end-to-end delivery wording, while the old name directs users
  to the new name without invalidating existing runtime root paths.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 5
- **Acceptance criteria**:
  - `deliver-dispatch-plan` has a valid skill contract and describes the
    heavyweight dispatch delivery lifecycle.
  - `dispatch-plan-delivery` remains discoverable as a compatibility name.
  - The contract explicitly says the runtime root remains
    `$AGENT_HOME/out/dispatch-plan-delivery`.
  - Tests assert the preferred name, compatibility wording, and runtime root
    preservation.
- **Validation**:
  - `scripts/check.sh --tests -- skills/automation/issue/deliver-dispatch-plan/tests/test_automation_deliver_dispatch_plan.py`
  - `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh --file skills/automation/issue/deliver-dispatch-plan/SKILL.md`
  - `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh --skill-dir skills/automation/issue/deliver-dispatch-plan`

### Task 1.3: Update catalogs, relationship docs, and reminders

- **Location**:
  - `README.md`
  - `skills/workflows/issue/README.md`
  - `skills/workflows/issue/execute-from-tracking-issue/SKILL.md`
  - `skills/workflows/issue/deliver-tracking-issue/SKILL.md`
  - `skills/workflows/plan/plan-tracking-issue/SKILL.md`
  - `skills/workflows/plan/create-plan/SKILL.md`
  - `skills/workflows/plan/create-plan/tests/test_workflows_plan_create_plan.py`
  - `skills/workflows/plan/plan-tracking-issue/tests/test_workflows_plan_plan_tracking_issue.py`
  - `hooks/codex/skill-usage-reminder.skills.json`
  - `docs/runbooks/skills/SKILL_USAGE_REMINDER_INDEX.md`
- **Description**: Prefer `deliver-dispatch-plan` in user-facing docs while
  retaining `dispatch-plan-delivery` as a compatibility alias where old
  workflows may still be referenced.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 4
- **Acceptance criteria**:
  - README and issue workflow quick-choice tables recommend
    `deliver-dispatch-plan`.
  - Nearby skill relationship sections mention `dispatch-plan-delivery` only as
    compatibility or legacy naming where needed.
  - Reminder aliases include both names and point at the canonical skill.
  - Existing tests expecting the old name are updated with compatibility-aware
    assertions.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'plan_tracking_issue or execute_from_tracking_issue or deliver_tracking_issue or create_plan'`
  - `scripts/check.sh --docs`
  - `scripts/check.sh --markdown`

## Sprint 2: Shared Outcome Schema For Dispatch Review Decisions

**Goal**: Reuse one outcome vocabulary across provider delivery comments and
dispatch PR review decisions.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k 'dispatch_pr_review or deliver_github_pr or deliver_gitlab_mr or deliver_tracking_issue'`
- Verify: provider delivery workflows and dispatch review evidence reference the
  same disposition rules.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 2.1: Extract shared review outcome disposition schema

- **Location**:
  - `skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md`
  - `skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_SCHEMA.md`
  - `skills/workflows/pr/github/deliver-github-pr/SKILL.md`
  - `skills/workflows/mr/gitlab/deliver-gitlab-mr/SKILL.md`
  - `skills/workflows/issue/deliver-tracking-issue/SKILL.md`
- **Description**: Move the reusable disposition vocabulary and reason rules
  into a shared schema reference, then make the provider delivery comment
  contract consume it.
- **Dependencies**:
  - none
- **Complexity**: 4
- **Acceptance criteria**:
  - Shared schema defines `fixed-now`, `accepted-residual`,
    `follow-up-linked`, `deferred-task`, `no-action`, and `blocked`.
  - Reason and evidence requirements are defined once.
  - Existing provider delivery skills reference the shared schema and keep their
    provider-specific comment commands.
  - Tests assert provider delivery skills still mention the marker
    `agent-kit:delivery-review-outcome:v1`.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'deliver_github_pr or deliver_gitlab_mr or deliver_tracking_issue'`
  - `scripts/check.sh --markdown`

### Task 2.2: Add dispatch review disposition fields

- **Location**:
  - `skills/workflows/issue/dispatch-pr-review/SKILL.md`
  - `skills/workflows/issue/dispatch-pr-review/references/REVIEW_EVIDENCE_TEMPLATE.md`
  - `skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md`
  - `skills/workflows/issue/dispatch-pr-review/tests/test_workflows_issue_dispatch_pr_review.py`
  - `tests/fixtures/issue/review_evidence_merge_valid.md`
  - `tests/fixtures/issue/review_evidence_merge_with_fail_verdict.md`
  - `tests/fixtures/issue/review_evidence_decision_mismatch.md`
- **Description**: Extend dispatch PR review evidence so each meaningful review
  item records a disposition, reason, and evidence. Include explicit
  `code-review-specialists` used/skipped status and reason.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 5
- **Acceptance criteria**:
  - Review evidence template has a section for specialist-review status.
  - Review evidence template has an item disposition table or equivalent
    machine-checkable shape.
  - `request-followup`, `merge`, and `close-pr` examples carry the new evidence
    expectations.
  - Validation still rejects generic non-evidenced decisions.
  - Tests cover valid merge evidence with no findings and valid follow-up
    evidence with blocked/follow-up dispositions.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/issue/dispatch-pr-review/tests/test_workflows_issue_dispatch_pr_review.py`

### Task 2.3: Align code-review-specialists usage policy in dispatch flows

- **Location**:
  - `skills/automation/issue/deliver-dispatch-plan/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/SKILL.md`
  - `skills/workflows/issue/dispatch-pr-review/SKILL.md`
  - `skills/workflows/code-review/code-review-specialists/SKILL.md`
- **Description**: Clarify that `code-review-specialists` is optional
  supplemental evidence for dispatch PRs, with used/skipped reason required in
  review evidence. Force specialist review for broad, high-risk,
  security-sensitive, migration-heavy, or API-contract-heavy diffs.
- **Dependencies**:
  - Task 2.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Dispatch plan delivery does not require specialists for every small sprint
    PR.
  - Dispatch review evidence always records used/skipped specialist status.
  - `code-review-specialists` remains read-only and does not post comments or
    decide outcomes.
  - Tests assert the read-only and used/skipped decision boundaries.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'dispatch_plan_delivery or deliver_dispatch_plan or dispatch_pr_review or code_review_specialists'`

## Sprint 3: Final Integration PR Outcome Comment

**Goal**: Make the plan-level integration PR carry the same compact delivery
outcome comment expected from deliver-series workflows.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k 'dispatch_plan_delivery or deliver_dispatch_plan'`
- Verify: the final integration PR cannot be merged by the skill contract until
  the outcome comment is posted and its URL is persisted.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 3.1: Add final integration outcome artifact path

- **Location**:
  - `skills/automation/issue/deliver-dispatch-plan/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/references/RUNTIME_LAYOUT.md`
  - `skills/automation/issue/dispatch-plan-delivery/references/CLOSE_PLAN_FINAL_MILE.md`
  - `skills/automation/issue/dispatch-plan-delivery/references/prompts/main-agent-init.md`
- **Description**: Define `PLAN_INTEGRATION_OUTCOME_PATH` under the existing
  issue runtime as the durable location for the final integration delivery
  outcome comment URL.
- **Dependencies**:
  - Task 1.3
  - Task 2.1
- **Complexity**: 4
- **Acceptance criteria**:
  - Runtime layout lists `PLAN_INTEGRATION_OUTCOME_PATH`.
  - Final-mile checklist includes writing and verifying the outcome URL.
  - Main-agent prompt names the artifact and when to create it.
  - Compatibility text explains that the path lives under the existing
    `dispatch-plan-delivery` runtime root.
- **Validation**:
  - `scripts/check.sh --tests -- skills/automation/issue/dispatch-plan-delivery/tests/test_automation_dispatch_plan_delivery.py`
  - `scripts/check.sh --markdown`

### Task 3.2: Require final integration outcome comment before merge

- **Location**:
  - `skills/automation/issue/deliver-dispatch-plan/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/references/CLOSE_PLAN_FINAL_MILE.md`
  - `skills/automation/issue/dispatch-plan-delivery/tests/test_automation_dispatch_plan_delivery.py`
- **Description**: Insert a pre-merge step for the final integration PR that
  posts a compact `agent-kit:delivery-review-outcome:v1` comment summarizing
  conformance, integration CI, sprint PR review evidence URLs, residuals, and
  the merge/block decision.
- **Dependencies**:
  - Task 3.1
- **Complexity**: 5
- **Acceptance criteria**:
  - Final integration PR merge is blocked if the outcome comment cannot be
    posted.
  - The comment uses `gh pr comment <integration-pr> --body-file <comment.md>`.
  - The comment references plan conformance and integration CI artifacts.
  - The comment links or summarizes sprint PR review evidence without copying
    long raw logs.
  - Tests assert marker, command, merge-before-comment prohibition, and URL
    persistence.
- **Validation**:
  - `scripts/check.sh --tests -- skills/automation/issue/dispatch-plan-delivery/tests/test_automation_dispatch_plan_delivery.py`

### Task 3.3: Include outcome URL in issue close evidence

- **Location**:
  - `skills/automation/issue/deliver-dispatch-plan/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/SKILL.md`
  - `skills/automation/issue/dispatch-issue-closeout/SKILL.md`
  - `skills/workflows/issue/README.md`
- **Description**: Require final close reporting to include the final
  integration outcome comment URL alongside the integration PR mention URL,
  conformance artifact, and integration CI artifact.
- **Dependencies**:
  - Task 3.2
- **Complexity**: 3
- **Acceptance criteria**:
  - Close reporting and failure mode text mention the outcome URL.
  - `dispatch-issue-closeout` explains how existing dispatch runtimes should
    treat missing outcome URLs during compatibility transition.
  - Issue workflow README distinguishes sprint review evidence from final
    integration delivery outcome comment.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'dispatch_plan_delivery or dispatch_issue_closeout'`
  - `scripts/check.sh --docs`

## Sprint 4: Migration Safety And Full Validation

**Goal**: Finish compatibility coverage, docs consistency, and repo-wide gates.
**Demo/Validation**:

- Command(s): `scripts/check.sh --all`
- Verify: all skill contracts, docs, markdown, shell, Semgrep, and pytest gates
  pass.

**PR grouping intent**: per-sprint
**Execution Profile**: serial

### Task 4.1: Add compatibility and migration notes

- **Location**:
  - `skills/automation/issue/deliver-dispatch-plan/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/SKILL.md`
  - `skills/automation/issue/dispatch-plan-delivery/references/CODEX_ADAPTER.md`
  - `skills/automation/issue/dispatch-plan-delivery/references/CLAUDE_CODE_ADAPTER.md`
  - `skills/automation/issue/dispatch-plan-delivery/references/OPENCODE_ADAPTER.md`
- **Description**: Document how existing users should transition from
  `dispatch-plan-delivery` to `deliver-dispatch-plan`, and why runtime paths
  stay unchanged in v1.
- **Dependencies**:
  - Task 1.3
  - Task 3.3
- **Complexity**: 3
- **Acceptance criteria**:
  - Compatibility notes are concise and do not duplicate the full skill
    contract.
  - Adapter docs explain that role mapping remains dispatch-flavored even when
    the entrypoint is deliver-named.
  - No guidance suggests deleting or renaming existing runtime directories.
- **Validation**:
  - `scripts/check.sh --markdown`
  - `scripts/check.sh --docs`

### Task 4.2: Run reference sweep and update tests

- **Location**:
  - `skills/automation/issue/deliver-dispatch-plan/tests/test_automation_deliver_dispatch_plan.py`
  - `skills/automation/issue/dispatch-plan-delivery/tests/`
  - `skills/workflows/issue/dispatch-pr-review/tests/`
  - `tests/fixtures/issue/`
  - `docs/testing/script-smoke.md`
  - `scripts/README.md`
- **Description**: Sweep references and fixtures so assertions match the new
  canonical name while preserving runtime path compatibility.
- **Dependencies**:
  - Task 1.3
  - Task 2.2
  - Task 3.3
  - Task 4.1
- **Complexity**: 4
- **Acceptance criteria**:
  - Tests do not fail because of stale canonical-name assumptions.
  - Runtime path fixture references remain intentionally unchanged.
  - Docs/tests distinguish user-facing skill name from runtime root.
- **Validation**:
  - `rg -n "dispatch-plan-delivery|deliver-dispatch-plan" .`
  - `scripts/check.sh --tests -- -k 'dispatch_plan_delivery or deliver_dispatch_plan or dispatch_pr_review'`

### Task 4.3: Final repository validation and delivery notes

- **Location**:
  - repository root
  - `docs/plans/deliver-dispatch-plan/deliver-dispatch-plan-execution-state.md`
- **Description**: Run the complete validation suite, record execution evidence
  in the execution state if using plan execution, and prepare final delivery
  notes with compatibility caveats and follow-up decisions.
- **Dependencies**:
  - Task 4.2
- **Complexity**: 3
- **Acceptance criteria**:
  - `scripts/check.sh --all` passes.
  - Final summary lists canonical name changes, compatibility behavior, review
    outcome alignment, final integration comment behavior, and any accepted
    residuals.
  - Any remaining CLI hard-gate idea is captured as a follow-up rather than
    silently implied as done.
- **Validation**:
  - `scripts/check.sh --all`

## Testing Strategy

- Unit/contract: focused pytest for `deliver-dispatch-plan`,
  `dispatch-plan-delivery`, `dispatch-pr-review`, provider delivery skills, and
  nearby plan/issue relationship docs.
- Integration: skill-governance contract validation and skill layout audit.
- Docs: `scripts/check.sh --docs` and `scripts/check.sh --markdown`.
- Shell/tooling: existing `scripts/check.sh --all` coverage, including shell
  lint and Semgrep.
- Manual review: inspect `rg -n "dispatch-plan-delivery|deliver-dispatch-plan"`
  output before final delivery to ensure canonical-name changes and runtime-path
  compatibility are intentional.

## Risks & gotchas

- A full directory move may create broad churn and break old prompt/reference
  paths. Prefer wrapper-first unless the inventory proves the move is safe.
- New and old names can confuse users if docs present them as equal peers. Make
  `deliver-dispatch-plan` canonical and `dispatch-plan-delivery` compatibility.
- Shared outcome schema extraction can regress provider delivery docs if tests
  only cover dispatch. Keep provider delivery tests in the focused gate.
- The final integration outcome comment is GitHub-specific in v1 because
  dispatch plan delivery is GitHub/`plan-issue` oriented.
- Adding required fields to review evidence can break existing fixtures. Update
  fixtures deliberately and keep validation errors actionable.
- Future CLI enforcement may belong in nils-cli, but this plan should first land
  skill policy and tests in agent-kit.

## Rollback plan

- If canonical rename causes skill discovery or governance issues, keep the new
  docs/tests but revert the new skill entrypoint and leave
  `dispatch-plan-delivery` as the only active skill while retaining the outcome
  schema and final integration PR comment work.
- If shared schema extraction creates too much churn, keep the schema embedded in
  `DELIVERY_REVIEW_OUTCOME_COMMENT.md` and reference that file directly from
  dispatch review evidence.
- If final integration PR outcome comment posting proves too brittle, downgrade
  the gate to a required issue-side final evidence comment and record the PR
  comment gate as a follow-up.
