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

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.

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

Failure cases

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.