Release Deploy Reporting

---
name: release-deploy-reporting
description: Use ONLY when verification passed AND operator explicitly says "prepare deploy" / "draft deploy" / "ship it"; drafts deploy handoff, captures deploy hash + probes + smoke, advises spec DRAFT→DONE flip. Do NOT auto-invoke; operator triggers explicitly.
source_inspiration: conceptual-only
license_status: clean-room-original
fusebase_flow_version: 2.1
risk_level: high
invocation: manual-for-side-effects
expected_outputs:
  - docs/tmp/handoff/<YYYY-MM-DD>-<slug>-deploy.md
  - release notes section
  - deploy report (after operator pastes back)
  - rollback notes
related_workflows:
  - greenlight-deploy.md
  - verification-gate.md
  - smoke-verification.md
hook_dependencies:
  - permission_request
  - pre_tool_use
  - stop
---

# Release & Deploy Reporting

## Purpose

The final skill in the eight-phase flow: draft the deploy green-light handoff, capture deploy artifacts (hash + probes + smoke), produce release notes, and advise the spec DRAFT→DONE flip. Manual-invoke only — operator types "prepare deploy" or equivalent; this skill never auto-fires.

## Lightweight-lane mode (FR-21)

If the ticket was classified **Lightweight** (`flow-skills/lightweight-lane/SKILL.md`), do NOT draft a deploy handoff, do NOT require a `production_deploy` JSON artifact, and do NOT use the DP.6 magic phrase. Instead the same single AI Developer session that built + live-verified the change deploys it on a **plain explicit operator go-ahead** ("ship it"). Still required (safety floor): the FR-07 protected-path re-check, capturing the deploy hash, a one-line rollback, one commit + SHA, and an explicit go-ahead (never auto-deploy). Report in 1–3 lines. The durable record is `change_tier: lightweight` + the SHA in the change-note / commit body (git carries it); a consolidated ledger is **opt-in and path-configurable** — only if the project keeps one, append one line (default `docs/changes/index.md`, but a per-app layout may point elsewhere or omit it — never assume a repo-root ledger exists). In hook-wired projects, record the go-ahead with `bash hooks/local/approve-local.sh lightweight_deploy <slug> 'ship it' --command 'fusebase deploy'` (one command — see `policies/approval-policy.yml`). The full procedure below applies to **Full-lane** deploys only.

## When to invoke (Full lane)

- Active phase is `Deploy` (per FLOW_RULES state announcement)
- `validation-and-qa` reported gate passed
- `code-review` reported zero blockers — OR every still-open blocker carries a **recorded waiver** in the deploy handoff's `blocker_waivers:` block: verbatim review-summary blocker line + the operator's own accept-phrase naming it + the accepted consequence (the concrete failing scenario / missing test case being shipped). Safety blockers (correctness defect — code-review step 4d; missing/meaningless tests — step 5) are never downgradable to "non-blocker"; they ship only under such a named waiver. A bare "operator accepted the blockers" — unquoted, unnamed, unrecorded — does NOT satisfy this precondition.
- `security-permissions-review` either ran clean OR all approval artifacts are in place per `approval-policy.yml`
- Operator says "prepare deploy" / "draft deploy handoff" / "ship it"

## Do not invoke when

- Gate has not passed (`validation-and-qa` reported failures)
- Code-review surfaced unaddressed blockers (unaddressed = neither fixed nor covered by a recorded `blocker_waivers:` entry per § When to invoke — a chat-only "operator said it's fine" leaves the blocker unaddressed)
- Security review surfaced missing approval artifacts
- Operator did NOT explicitly ask — this skill's `invocation: manual-for-side-effects` means no auto-trigger

## Required inputs

| Input | Where it lives | If missing |
|---|---|---|
| Spec | `docs/specs/<slug>/spec.md` (status DRAFT) | Stop; cannot deploy without spec |
| Verification gate report | chat paste from `validation-and-qa` | Stop; cannot deploy without gate pass |
| Deploy command | project-specific section of `AGENTS.md` | Stop; ask operator for deploy command |
| Approval artifact for `production_deploy` (+ `database_migration` / `auth_or_permission_change` / `protected_path_edit` as the deploy needs) | `state/approvals/<action>-<slug>-<YYYYMMDD>.json` | After the operator types the **DP.6 phrase**, the **Deploy session authors** every required artifact on their behalf (`approve-local.sh`) — never require the operator to run terminal commands (FR-12 needs the artifact on disk; the gate does not check the author). Present the full scope in chat BEFORE the phrase. (`dp1_waiver: eligible` = reversible fast-path; excluded/sensitive classes still need the phrase, but the session — not the operator — authors.) |
| Worker-undisturbed list | `policies/protected-paths.yml` | Stop; cannot run final pre-deploy check without it |
| CLI edition map, for Fusebase Apps deploys | `docs/fusebase-cli-edition.md` | Continue with generic deploy handoff, but mark CLI probes/log diagnostics unknown |

## Procedure

1. Verify all preconditions: gate passed, code-review clean **or every open blocker recorded in `blocker_waivers:` (verbatim blocker + operator accept-phrase + accepted consequence — § When to invoke)**, security clean **or recorded `security: N/A — no sensitive surface`**, approval artifact(s) present **or authored by the Deploy session on the operator's DP.6 phrase (all tickets; present the full scope in chat first for sensitive actions)**.
2. Final pre-deploy worker-undisturbed check: re-run `git diff` against `protected-paths.yml`. If anything changed since the gate report, STOP and report.
3. For Fusebase Apps deploys, use `docs/fusebase-cli-edition.md` to identify supporting CLI assets for commands, logs, app quality checks, and post-deploy diagnostics.
4. Draft deploy handoff from `templates/handoff-deploy.md` (canonical; see `workflows/greenlight-deploy.md`). Include:
   - Self-attestation phrase the deployer should output first
   - **DP.1 authoring** — the Deploy session authors the DP.1 (and any `database_migration` / `auth_or_permission_change` / `protected_path_edit`) approval artifact(s) on the operator's DP.6 phrase, for ALL tickets — the operator never runs approval commands. `dp1_waiver: eligible|excluded — <reason>`: `eligible` (reversible AND no protected-path / security / migration surface) is the fast-path where the artifact is minimal bookkeeping; excluded/sensitive classes require presenting the full scope in chat before the phrase, but the session still authors the artifact(s) on that phrase (not the operator)
   - **`blocker_waivers:` block** (only when open code-review blockers exist) — one entry per blocker: verbatim review-summary line + operator's accept-phrase + accepted consequence. A step-4d/step-5 safety blocker with no entry means the handoff cannot be drafted — STOP and surface the blocker instead
   - Pre-deploy worker-undisturbed re-check instructions
   - Deploy command (exact)
   - **Rollback surface + plan** — classify the deploy per § Rollback-surface classification below and include the surface-appropriate rollback steps; a bare `git revert` plan is valid ONLY for the `code-only` class
   - Probe list (G-M..G-Q or project equivalents from `verification-gate.md`)
   - Smoke prompts S1..Sn (if applicable), copied from the `smoke-testing` contract with success criterion, ground-truth diagnostic, adversarial check, and evidence required
   - Single-docs-commit instructions (FR-14): spec DRAFT→DONE flip with deploy hash, tasks.md verification marks, backlog index update, README header
5. Save handoff to `docs/tmp/handoff/<YYYY-MM-DD>-<slug>-deploy.md` BEFORE outputting in chat (FR-04).
6. Tell operator: "Deploy handoff saved to <path>. Open and paste into the AI Developer (Codex) chat to authorize deploy."
7. After operator pastes back deploy report:
   - Verify deploy hash captured
   - Verify each probe result with concrete evidence
   - Verify smoke results meet threshold from gate contract and satisfy `flow-skills/smoke-testing/SKILL.md` (operator-visible outcome + ground-truth diagnostic, not supporting checks only)
   - Verify single docs commit landed (one SHA covering all post-deploy doc updates)
8. If all verified, acknowledge with summary + tally update + identify what's next (parked backlog options, observation period).
9. If any probe failed, do NOT acknowledge as success. Surface failure with rollback per the handoff's rollback-surface plan (`git revert <hash>` + redeploy ONLY for `code-only`; otherwise the surface-appropriate steps from § Rollback-surface classification) or fix-forward (follow-up task) options. Operator decides.

## Rollback-surface classification

`git revert <hash>` + redeploy only un-ships CODE. Every deploy handoff classifies what the deploy
actually changes and carries a rollback plan matched to that surface. A revert-only plan on a
non-code surface is a false rollback: the code goes back while the migration/secret/sidecar/contract
stays forward.

| Surface class | The deploy changes... | Valid rollback plan | `git revert`+redeploy alone? |
|---|---|---|---|
| `code-only` | app/backend source, assets, config fully re-applied by redeploy | `git revert <hash>` + redeploy | VALID |
| `migration` | DB/dashboard schema, store structure, data backfill | Down-migration or restore path, stated AND checked against data written since deploy; if irreversible, say so explicitly and give the forward-fix path | NOT valid alone |
| `secret/config` | secrets, env vars, third-party keys, permission grants | Restore prior secret/config value (name where the prior value lives); revoke newly-issued credentials | NOT valid alone |
| `sidecar/infra` | sidecar containers, cron registrations, resource tiers | Remove/re-register sidecar/cron to prior state with exact CLI commands (`app-sidecar`, backend cron docs) | NOT valid alone |
| `cross-app contract` | an API surface other apps call (`callAppApi` providers, `*.contract.json`) | Coordinated plan: contract-compatible revert or consumer notification; check dependent apps first (`app-api-contract-testing`) | NOT valid alone |

Classify by the DIFF + deploy steps, not intent: if the deploy runs a migration, writes a secret,
touches sidecars/cron, or changes a provider contract, that class applies even when "the main
change is code." Multi-class deploys carry one plan per class. A Deploy session must refuse a
handoff whose rollback plan does not match its surface class.

## Output artifacts

| Artifact | Path / location | Mode |
|---|---|---|
| Deploy handoff | `docs/tmp/handoff/<YYYY-MM-DD>-<slug>-deploy.md` | Mode B (full) |
| Release notes | embedded in deploy handoff + spec.md DONE section | Mode B (full) |
| Deploy verification | chat acknowledgment to operator | Mode A |
| Tally update | project-specific counter in `AGENTS.md` | Human-readable |

## Failure cases

| Failure mode | Detection | Response |
|---|---|---|
| Approval artifact missing | `state/approvals/` lacks file matching `approval-policy.yml: require_approval.production_deploy` | Present the full deploy scope + ask for the DP.6 phrase; author the artifact(s) yourself on that phrase (`approve-local.sh`). Do NOT tell the operator to run terminal commands. |
| Worker-undisturbed file changed since gate | `git diff` against `protected-paths.yml` non-empty | STOP. Per FR-07, do NOT deploy on changed protected paths. |
| Probe failure | Pasted report shows `Pn FAIL` | Do NOT mark spec DONE. Surface rollback / fix-forward options. |
| Smoke threshold not met | Pass ratio below gate contract | Do NOT mark spec DONE. Surface failure with concrete `Sn observed Y, expected Z`. |
| Multiple docs commits instead of one | Pasted report shows multiple SHAs for spec/tasks/backlog updates | Note as FR-14 violation; document but don't block (deploy already happened); flag for next deploy cycle |
| Rollback plan mismatched to surface | Handoff for a migration / secret / sidecar / cross-app-contract deploy carries only `git revert` + redeploy | STOP before deploy; reclassify per § Rollback-surface classification and rewrite the rollback plan |
| Open code-review blocker without recorded waiver | Handoff/report carries an open blocker (incl. step-4d correctness / step-5 test blockers) with no matching `blocker_waivers:` entry (verbatim blocker + operator accept-phrase + consequence) | STOP before deploy. A chat-only or paraphrased "operator accepted" is not a waiver — record the entry in the operator's own words, or fix the blocker |

## Escalation path

- Deploy command unknown or platform-blocker emerges → STOP; file `docs/problem-catalog/deploy-blocker-<date>/problem.md`
- Probe infrastructure unavailable → cannot verify; STOP and surface to operator before attempting deploy
- Rollback needed → produce the surface-appropriate steps from the handoff's rollback-surface classification (`git revert` + redeploy only for `code-only`); operator confirms before execution

## Anti-patterns

- Do NOT auto-invoke (`invocation: manual-for-side-effects` enforces this)
- Do NOT deploy without the approval artifact(s) (FR-12) — but author them yourself on the operator's DP.6 phrase; never force the operator to run approval commands
- Do NOT self-approve: authoring artifacts WITHOUT the operator's DP.6 phrase (or a plain go-ahead in the Lightweight lane) is forbidden — the phrase is the authorization, not your judgment
- Do NOT mark spec DONE before all probes pass
- Do NOT split deploy docs across multiple commits (FR-14)
- Do NOT print or persist secrets / session keys in handoff or report
- Do NOT accept `git revert` + redeploy as the rollback plan for a deploy whose surface class is not `code-only` (§ Rollback-surface classification)
- Do NOT skip the final worker-undisturbed re-check even though gate already ran one

## Clean-room note

Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See `docs/source-map.md`.