# Deliver Dispatch Plan Implementation Handoff

## Status

- Date: 2026-05-22
- Source type: discussion-to-implementation-doc
- Status: ready for implementation planning
- Intended next step: create a tracking issue, then implement the sibling plan.
- Recommended plan: docs/plans/deliver-dispatch-plan/deliver-dispatch-plan-plan.md
- Recommended execution state: docs/plans/deliver-dispatch-plan/deliver-dispatch-plan-execution-state.md

## Purpose

The deliver-series workflows now have a shared review outcome comment contract
for ordinary GitHub PR, GitLab MR, and lightweight tracking-issue delivery. The
remaining heavyweight dispatch entrypoint is still named
`dispatch-plan-delivery`, even though it is also an end-to-end delivery flow.

This document records the intended design for adding a canonical
`deliver-dispatch-plan` entrypoint while preserving the existing dispatch
runtime model and adding the same review outcome discipline where it fits.

## Confirmed Facts

- `dispatch-plan-delivery` is the heavyweight plan execution workflow for
  `plan-issue` runtimes. It owns sprint/task lane orchestration, subagent
  dispatch, sprint acceptance, a final `PLAN_BRANCH -> DEFAULT_BRANCH`
  integration PR, and `close-plan`.
- `dispatch-plan-delivery` keeps the main agent orchestration/review-only for
  sprint tasks. Implementation belongs to subagent-owned task lanes.
- The fixed runtime root is `$AGENT_HOME/out/dispatch-plan-delivery`; changing
  that path would affect existing runtime artifacts, prompts, fixtures, and
  worktree cleanup checks.
- `dispatch-pr-review` is already the canonical main-agent review decision path
  for dispatch PRs. It posts decision-scoped PR review evidence comments for
  `request-followup`, `merge`, and `close-pr`, then mirrors comment URLs back to
  the issue timeline.
- `POST_REVIEW_OUTCOMES.md` already requires GitHub-side review actions plus
  runtime-truth row sync after every dispatch review decision.
- `code-review-specialists` is intentionally read-only. It may supply
  supplemental findings, but it does not decide merge, close, or follow-up.
- The delivery review outcome comment contract uses the marker
  `agent-kit:delivery-review-outcome:v1`, records the merge/block decision, and
  classifies meaningful items with dispositions such as `fixed-now`,
  `accepted-residual`, `follow-up-linked`, `deferred-task`, `no-action`, and
  `blocked`.

## Decisions

- Add `deliver-dispatch-plan` as the canonical user-facing end-to-end delivery
  entrypoint for dispatch-ready plan delivery.
- Keep `dispatch-plan-delivery` as a compatibility name in v1. Do not delete or
  hard-rename it in the same change.
- Keep the runtime root as `$AGENT_HOME/out/dispatch-plan-delivery` in v1. The
  name alignment should not invalidate existing `plan-issue` runtime state.
- Treat dispatch review evidence as the sprint-PR outcome report. Do not post a
  second delivery outcome comment for every sprint PR by default.
- Align dispatch review evidence with the shared delivery outcome disposition
  vocabulary, including explicit reasons for accepted residuals, follow-ups,
  deferred work, blocked items, and meaningful no-action decisions.
- Require `dispatch-pr-review` evidence to state whether
  `code-review-specialists` was used. If it was skipped, record the reason.
- Add a delivery review outcome comment to the final integration PR before it is
  merged, because that PR is the deliver-level reviewable that crosses from
  `PLAN_BRANCH` to `DEFAULT_BRANCH`.
- Persist the final integration outcome comment URL under the plan issue runtime
  and include it in the plan issue close evidence.
- Update discoverability so future users see `deliver-dispatch-plan` as the
  preferred entrypoint and `dispatch-plan-delivery` as a compatibility alias.

## Scope

- Add or expose a canonical `deliver-dispatch-plan` skill entrypoint.
- Preserve compatibility for existing `dispatch-plan-delivery` users and
  references.
- Update documentation, README tables, skill relationship sections, reminder
  aliases, and tests to prefer the new name.
- Extract or share the review outcome disposition schema so dispatch and
  provider delivery workflows use the same vocabulary.
- Update `dispatch-pr-review` review evidence templates and validation wording
  to capture item dispositions and specialist-review used/skipped decisions.
- Update final integration PR workflow guidance so it posts and records a
  delivery review outcome comment before merge.
- Add focused tests for name preference, compatibility, outcome schema, final
  integration comment requirements, and docs references.

## Non-Scope

- Do not rename `$AGENT_HOME/out/dispatch-plan-delivery` in v1.
- Do not migrate existing `plan-issue` runtime state.
- Do not remove the `dispatch-plan-delivery` name in v1.
- Do not make `code-review-specialists` mandatory for every dispatch sprint PR.
- Do not make `code-review-specialists` post comments or decide outcomes.
- Do not change `plan-issue` CLI behavior unless a later implementation finds a
  small doc/test-only change insufficient.
- Do not merge `dispatch-pr-review`, `dispatch-subagent-pr`, or
  `dispatch-issue-closeout` into the deliver naming family; they are dispatch
  subflows, not the end-to-end entrypoint.

## Implementation Boundaries

- Canonical naming belongs in skill metadata, catalog docs, README tables,
  relationship sections, and hook/reminder aliases.
- Runtime compatibility belongs in the skill contract and tests. The old
  runtime root remains valid until a separate migration plan exists.
- Review decision enforcement remains in `dispatch-pr-review`.
- Final plan delivery orchestration remains in `deliver-dispatch-plan`
  / compatibility `dispatch-plan-delivery`.
- Shared outcome vocabulary should live in a shared reference, not be copied
  into every skill.

## Requirements

- `$deliver-dispatch-plan` should be the preferred name for future end-to-end
  dispatch-ready plan delivery.
- `$dispatch-plan-delivery` should remain discoverable and should route readers
  to the new canonical entrypoint.
- Documentation should explain that sprint PRs use decision-scoped
  `dispatch-pr-review` evidence rather than a duplicate delivery outcome
  comment.
- Every dispatch PR review decision must capture:
  - decision: `merge`, `request-followup`, or `close-pr`
  - whether specialist review was used or skipped
  - meaningful review items and dispositions
  - reason and evidence where the shared disposition rules require them
  - issue-side sync or row update expectation
- The final integration PR must get a compact delivery review outcome comment
  before merge, using the existing `agent-kit:delivery-review-outcome:v1`
  marker.
- The final integration outcome comment URL must be persisted in the issue
  runtime and reported during close.
- Blocking failure handling must be explicit: if the final integration outcome
  comment cannot be posted, do not merge the integration PR.

## Acceptance Criteria

- A canonical `deliver-dispatch-plan` skill entrypoint exists and passes skill
  governance.
- Existing `dispatch-plan-delivery` references either remain valid as
  compatibility references or are updated to the new canonical name when they
  are user-facing.
- The fixed runtime root remains `$AGENT_HOME/out/dispatch-plan-delivery`.
- Shared disposition vocabulary is referenced by provider delivery and dispatch
  review workflows.
- `dispatch-pr-review` review evidence template includes item disposition and
  specialist used/skipped fields.
- The final integration PR flow requires posting and recording a delivery
  review outcome comment before merge.
- Focused tests cover naming, compatibility, dispatch review disposition
  evidence, final integration outcome comment, and README/relationship wording.
- `scripts/check.sh --all` passes before implementation is delivered.

## Validation Plan

Recommended focused commands:

```bash
scripts/check.sh --tests -- \
  skills/automation/issue/dispatch-plan-delivery/tests/test_automation_dispatch_plan_delivery.py \
  skills/workflows/issue/dispatch-pr-review/tests/test_workflows_issue_dispatch_pr_review.py \
  skills/workflows/issue/deliver-tracking-issue/tests/test_workflows_issue_deliver_tracking_issue.py \
  skills/workflows/pr/github/deliver-github-pr/tests/test_workflows_pr_github_deliver_github_pr.py \
  skills/workflows/mr/gitlab/deliver-gitlab-mr/tests/test_workflows_mr_gitlab_deliver_gitlab_mr.py

skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh
skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh
scripts/check.sh --docs
scripts/check.sh --markdown
```

Before delivery, run:

```bash
scripts/check.sh --all
```

## Risks And Guardrails

- A hard rename could break in-flight dispatch runtime paths. Mitigate by using
  a soft rename and keeping the old runtime root.
- Duplicating both `dispatch-pr-review` evidence comments and delivery outcome
  comments for every sprint PR would create noisy timelines. Mitigate by using
  dispatch review evidence for sprint PRs and reserving the delivery outcome
  comment for the final integration PR.
- Making `code-review-specialists` mandatory for every sprint PR could make
  broad dispatch plans too slow. Mitigate by requiring an explicit used/skipped
  decision and forcing specialist review only for high-risk scopes.
- Moving shared outcome rules without tests could desynchronize provider
  delivery and dispatch review behavior. Mitigate with tests that assert all
  relevant skills reference the shared schema.
- Adding a final integration outcome URL gate only in prose may be missed by
  future agents. Mitigate with plan final-mile checklist updates and tests.

## Execution

- Recommended plan: docs/plans/deliver-dispatch-plan/deliver-dispatch-plan-plan.md
- Recommended execution state: docs/plans/deliver-dispatch-plan/deliver-dispatch-plan-execution-state.md
- Recommended tracker: create through `plan-tracking-issue` after this bundle is
  committed if a live provider issue is desired.

## Retention Intent

This is an execution coordination source artifact. Keep it with the sibling
plan until implementation is complete; after closeout, it may be retained as
historical planning context or removed through the normal docs/plans cleanup
process.

## Open Questions

- Whether the implementation should physically move the full
  `dispatch-plan-delivery` skill tree in v1 or add a canonical wrapper first.
  The plan recommends the wrapper-first soft rename unless implementation
  inventory proves a full move is low risk.
- Whether the final integration outcome URL should become a `plan-issue` CLI
  hard gate in a later nils-cli change. This plan keeps the first step inside
  agent-kit skill policy and tests.

## Read-First References

- `skills/automation/issue/dispatch-plan-delivery/SKILL.md`
- `skills/workflows/issue/dispatch-pr-review/SKILL.md`
- `skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md`
- `skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md`
- `skills/workflows/code-review/code-review-specialists/SKILL.md`
