Range Handoff Commits

Range Handoff Commits

Overview

Keep range implementation work and deployment/handoff documentation in separate commits. The goal is that a future engineer can tell exactly what changed in code/config and exactly what happened to Helm/Kubernetes/live range state.

Required Commit Shape

When a task changes code, config, Helm, Kubernetes manifests, deployment scripts, agent prompts, service behavior, or live range state, create two commits before pushing:

1. Implementation commit

   • Code, tests, prompts, charts, values, manifests, scripts, generated runtime assets, or config needed for the behavior.
   • Include focused verification relevant to those files.

2. Handoff commit

   • Documentation only, normally a maintained handoff/deployment note under the range docs path.
   • Record what changed, why, deploy steps, Helm/Kubernetes details, validation, live state, rollback/recovery notes, and known gaps.

If the task is docs-only, one documentation commit is fine. If the task is code-only and no deploy/handoff context exists, still add a concise handoff note when the change affects a range that people will operate, test, or deploy.

Handoff Contents

Update an existing handoff when one exists. Create a new one only when there is no obvious maintained document.

Include:

• Absolute date and timezone.
• Repo branch and commit IDs once known.
• Range, namespace, AWS profile, and affected services/releases.
• Files/charts/manifests/scripts changed.
• Helm commands, values files, kubectl commands, rollout steps, and sync jobs used or expected.
• Verification commands and exact pass/fail status. Do not claim unrun checks passed.
• Live-state evidence such as rollout status, service counts, smoke checks, URLs/routes, and relevant pod/release names.
• Data/provenance notes for agent-visible surfaces, uploaded documents, RAG corpora, OpenProject, Mattermost, or EAM state.
• Rollback/recovery steps and known gaps.

For Riverbend/coralbots, prefer docs/riverbend/ for handoffs and keep riverbend_stack/, riverbend_eam_service/, Helm release names, namespace agentnet-e2e-100, and relevant OpenProject/EAM/Mattermost details explicit.

Workflow

1. Inspect git status --short --branch before editing or committing. Do not stage unrelated dirty files.
2. If the work involves deployment, rollout, Helm upgrade, or live Kubernetes changes, also use pre-deployment-main-sync before touching live state.
3. Make and verify implementation changes.
4. Update the handoff document with concrete deployment and verification details.
5. Review file classification with git diff --name-only and git diff --stat.
6. Stage and commit implementation files only.
7. Stage and commit handoff documentation only.
8. If the user asked to push, push after both commits exist.

Useful commit message pattern:

feat(<range>): <implementation summary>
docs(<range>): record <implementation summary> handoff

Guardrails

• Keep generated or live-derived secrets out of handoff docs.
• Do not mix handoff docs into the implementation commit unless the user explicitly forbids two commits.
• Do not let a handoff commit conceal code/config changes.
• Do not create multiple scattered handoff files when one maintained document should be updated.
• When a deployment was not performed, phrase the handoff as planned/expected commands, not live evidence.
• If tests or smoke checks fail, document the failure and do not push as completed unless the user explicitly accepts that state.