taip-connect 0.5.0

package/packs/process/skills/taip-workflow-plane-task/SKILL.md

@@ -0,0 +1,356 @@
+---
+id: process/skills/taip-workflow-plane-task
+version: 1.2.0
+trigger: "plane task|start plane|pick up issue|plane issue|close plane|done plane|plane start|plane done|file plane|plane backlog|park task"
+description: >
+  Plane issue lifecycle skill. Covers three phases: START (pick up an issue from the active
+  cycle, transition to In Progress, create branch, scaffold plan file pre-filled from the
+  issue), FILE (plan-first: create an issue from a completed plan with the handover embedded,
+  park it in a non-running cycle, then close via a three-way choice — runner / park /
+  implement-now) and DONE (post PR as comment, transition to Done). Implements the close half of
+  process/planning/plan-phase-exit. Requires the Plane tool binding (integrations/tools/plane).
+user-invocable: true
+tags: [plane, project-management, workflow, sprint, agile]
+attribution:
+  source: original
+  license: brain-official
+  author: brain Official
+---
+
+# taip-workflow-plane-task
+
+Plane issue lifecycle: START (pick up → branch → plan) | FILE (plan → issue+handover → close:
+runner/park/implement-now) | DONE (PR comment → transition).
+
+Requires the `integrations/tools/plane` tool binding to be active. If Plane is not configured,
+tell the user and stop.
+
+---
+
+## Detect phase
+
+Parse the user's invocation to determine which phase:
+
+- Keywords: "start", "pick up", "begin", "take", "assign" → **START phase**
+- Keywords: "file", "backlog", "register", "park", "plan to plane" → **FILE phase**
+  (also entered automatically after plan mode — see `taip-workflow-planning` Step 4 and the
+  `PostToolUse:ExitPlanMode` hook)
+- Keywords: "done", "close", "complete", "finish", "mark done" → **DONE phase**
+
+If ambiguous, ask: "Do you want to START a Plane issue from the active sprint, FILE a planned task into a non-running sprint, or mark the current task DONE?"
+
+---
+
+## START phase
+
+### Step S1 — Identify the issue
+
+**If an issue ID or title was provided in the invocation:** use it directly → go to S3.
+
+**If no issue specified:** fetch the active sprint:
+
+```
+mcp-plane_list_cycles        → find active cycle
+mcp-plane_list_cycle_issues  → list issues (exclude Done/Cancelled states)
+```
+
+Display as a numbered list:
+```
+Active sprint issues:
+  1. [PROJ-12] Fix login redirect loop
+  2. [PROJ-15] Add export to CSV
+  ...
+Which issue do you want to start? (number or ID)
+```
+
+WAIT for user selection.
+
+### Step S2 — Confirm the issue
+
+Fetch full issue details:
+```
+mcp-plane_get_issue → title, description, state, labels, assignee
+```
+
+Display:
+```
+Issue: [PROJ-{seq}] {title}
+State: {current state}
+Labels: {labels}
+
+{description (first 300 chars)}
+```
+
+Ask: "Start work on this issue? (Y/N)"
+
+WAIT for confirmation.
+
+### Step S3 — Create feature branch
+
+Derive branch name: `feature/{slug}-{sequence_id}`
+
+- `slug`: kebab-case from issue title, max 5 words
+- `sequence_id`: issue sequence number from Plane
+
+```bash
+git checkout -b feature/{slug}-{sequence_id}
+```
+
+If branch already exists: `git checkout feature/{slug}-{sequence_id}` and warn the user.
+
+### Step S4 — Transition issue to In Progress
+
+```
+mcp-plane_update_issue → state: <In Progress state id>
+```
+
+Fetch available states first with `mcp-plane_list_states` to resolve the "In Progress" state ID.
+
+Post a start comment:
+```
+mcp-plane_add_comment → "🚀 Work started on branch `feature/{slug}-{sequence_id}`"
+```
+
+### Step S5 — Scaffold plan file
+
+Run the `taip-workflow-planning` skill with the issue content pre-filled:
+
+- **Title**: issue title
+- **What**: issue description (trimmed to 2–4 sentences)
+- **Requirements**: parsed from issue description `## Acceptance Criteria` section if present
+- **Branch**: `feature/{slug}-{sequence_id}`
+
+Create plan at: `docs/plans/YYYY-MM-DD-{slug}.md`
+
+Ask: "Create plan at `docs/plans/YYYY-MM-DD-{slug}.md`? (Y to confirm)"
+
+WAIT for confirmation, then create the file with the pre-filled template.
+
+### Step S6 — Hand off
+
+Print:
+```
+✅ Issue [PROJ-{seq}] picked up.
+   Branch: feature/{slug}-{sequence_id}
+   Plan:   docs/plans/YYYY-MM-DD-{slug}.md
+
+Next:
+  1. Fill in ## Requirements and ## Acceptance Tests in the plan file
+  2. Implement
+  3. Run /taip-workflow-acceptance-testing when ready
+  4. Run /taip-workflow-plane-task done to close the issue
+```
+
+---
+
+## FILE phase
+
+Plan-first direction: a plan already exists (you just finished plan mode), so create the Plane
+issue **from the plan** (with the `## Handover` block embedded in its description) and park it in
+a **non-running** cycle, then offer the three-way close — **runner / park / implement-now**. This
+is the close half of the `process/planning/plan-phase-exit` gate.
+
+Why a non-running sprint: the autonomous `plane-sprint-runner` only executes `ai-task` issues in
+the **active** cycle, and its filter skips only `done/cancelled/completed` — not `In Progress`.
+Parking the task in an upcoming/Backlog cycle records it (eligible for a *future* sprint) while
+guaranteeing the runner never grabs it until you promote it.
+
+### Step F1 — Pre-requisites
+
+- The Plane tool binding MUST be active (else stop — see Hard fails).
+- A plan file MUST exist under `docs/plans/` with **both** `## Requirements` and
+  `## Acceptance Tests` populated (at least one requirement and one Given/When/Then row).
+  If either is empty, stop and print:
+  > "## Requirements and ## Acceptance Tests must be filled in before I can file this task.
+  > This is a hard gate — please populate both sections in the plan first."
+
+### Step F2 — Resolve the non-running cycle
+
+```
+mcp-plane_list_cycles → all cycles
+```
+
+- Drop any cycle where `status === 'current'` OR `is_active === true` (those are the running
+  sprint — the runner reads them).
+- From the remainder, pick the nearest **upcoming** cycle (`status === 'upcoming'`, earliest
+  future `start_date`).
+- If no non-running cycle exists, create a persistent **"Backlog"** cycle with future dates.
+  Cycle creation is not in the MCP capability set — reuse the REST pattern from
+  `openclaw/sprint/setup-plane-projects.sh`:
+  ```bash
+  curl -s -X POST "${PLANE_API_URL}/api/v1/workspaces/${SLUG}/projects/${PROJECT_ID}/cycles/" \
+    -H "X-Api-Key: ${PLANE_TOKEN}" \
+    -d "$(jq -n --arg n "Backlog" --arg s "<future-start>" --arg e "<future-end>" --arg pid "$PROJECT_ID" \
+      '{name: $n, start_date: $s, end_date: $e, project_id: $pid}')"
+  ```
+
+Remember the resolved `cycleId` and `cycleName`.
+
+### Step F3 — Create the issue from the plan
+
+```
+mcp-plane_create_issue → title:       <plan title>
+                         description: <assembled from the plan, see below>
+                         label:       ai-task
+                         cycle:       <F2 cycleId>
+```
+
+Assemble the description from the plan file sections:
+- `## What` → issue summary paragraph
+- `## Requirements` → a "Requirements" list
+- `## Acceptance Tests` → an "## Acceptance Criteria" block (so a later START pre-fill round-trips)
+- `## Handover` → embed the `## Handover` block **verbatim** into the issue description, so a fresh
+  session or the sprint runner can resume from the issue alone (required by `plan-phase-exit`)
+
+If `mcp-plane_create_issue` does not accept a cycle field, create the issue first, then assign it
+to the cycle via the REST cycle-issues endpoint:
+```
+POST /api/v1/workspaces/{slug}/projects/{projectId}/cycles/{cycleId}/cycle-issues/
+  body: { "issues": ["<new-issue-id>"] }
+```
+
+Verify the issue is **not** in the active cycle before continuing.
+
+### Step F4 — Close: runner / park / implement-now (ask each time)
+
+```
+✅ Filed [PROJ-{seq}] {title}
+   Cycle:  {cycleName} (non-running — the runner will not pick this up)
+   Label:  ai-task
+
+How do you want to proceed? (ask this every time — never assume)
+  [R] runner        — promote to the ACTIVE cycle, keep the ai-task label; plane-sprint-runner
+                      executes it autonomously (opens the branch + PR). → Step F7
+  [P] park          — leave it in '{cycleName}' with the handover; pick it up in a future sprint. → Step F6
+  [I] implement-now — implement interactively in THIS session (escape hatch). → Step F5
+```
+
+WAIT for the answer. Only these three outcomes; do not begin any edits before the user chooses.
+
+### Step F5 — [I] implement-now: implement out-of-band
+
+- Fetch states: `mcp-plane_list_states` → resolve the "In Progress" state ID.
+- `mcp-plane_update_issue → state: <In Progress state id>`.
+- Post a start comment:
+  ```
+  mcp-plane_add_comment → "🚀 Implementing out-of-band on branch `{branch}`.
+  Left in cycle '{cycleName}' so the sprint runner skips it."
+  ```
+- Ensure a feature branch is checked out (it usually already exists from plan mode). If on
+  `main`/`master`, create `feature/{slug}-{sequence_id}` and warn.
+- The issue **stays in the non-running cycle** — do not move it to the active cycle.
+- Hand off to implementation:
+  ```
+  Requirements and acceptance tests confirmed. Ready to begin implementation.
+  ```
+
+### Step F6 — [P] park: leave it parked
+
+```
+📥 [PROJ-{seq}] parked in '{cycleName}' (Todo) with the handover in its description.
+   Promote it to the active cycle to let the sprint runner execute it,
+   or run /taip-workflow-plane-task file again and choose runner or implement-now.
+```
+
+Do not change the issue state and do not start any code. Stop here.
+
+### Step F7 — [R] runner: hand to the sprint runner
+
+Promote the parked issue into the **active** cycle so `plane-sprint-runner` picks it up (it reads
+only the active cycle). Keep the `ai-task` label and the embedded `## Handover` — that block is the
+runner's implementation prompt.
+
+- Resolve the active cycle: `mcp-plane_list_cycles` → the one with `status === 'current'` / `is_active`.
+- Move the issue into it (remove it from '{cycleName}' first if the cycle is exclusive):
+  ```
+  mcp-plane_transfer_cycle_issues  (or REST: POST .../cycles/{activeCycleId}/cycle-issues/ { "issues": ["<id>"] })
+  ```
+- Leave the state at **Todo** (do NOT set In Progress — the runner transitions it when it starts).
+- Post a comment: `mcp-plane_add_comment → "🤖 Handed to plane-sprint-runner (active cycle). Handover is in the description."`
+- Print:
+  ```
+  🤖 [PROJ-{seq}] promoted to the active cycle for the sprint runner. Keeping ai-task.
+     The runner will open feature/{slug}-{seq} and a PR from the handover.
+  ```
+
+Do not start any code in this session. Stop here.
+
+---
+
+## DONE phase
+
+### Step D1 — Resolve the issue
+
+**If an issue ID was provided:** use it.
+
+**If not:** infer from current branch name.
+- Parse `feature/{slug}-{sequence_id}` → extract `sequence_id`
+- Fetch issue by sequence ID via `mcp-plane_get_issue`
+
+If cannot resolve: ask "Which Plane issue does this work close? (issue ID)"
+
+### Step D2 — Verify PR exists
+
+Check that a PR has been created for the current branch:
+```bash
+gh pr view --json url,title,state 2>/dev/null
+```
+
+If no PR: "No open PR found for this branch. Run /taip-workflow-git-pr first, then come back."
+
+Stop here if no PR.
+
+### Step D3 — Post PR comment on Plane issue
+
+```
+mcp-plane_add_comment → body:
+  "✅ Work complete. PR: {pr_url}
+
+  **{pr_title}**
+
+  Branch: `{branch}`"
+```
+
+### Step D4 — Transition to Done (gated on AT)
+
+Check if acceptance testing has been run (look for a file matching `docs/tests/AT-*-{slug}*.md`).
+
+**If AT report exists and verdict is PASS:**
+- Fetch states: `mcp-plane_list_states`
+- Resolve the "Done" state ID
+- `mcp-plane_update_issue` → state: Done state ID
+- Print: "✅ Issue [PROJ-{seq}] marked Done."
+
+**If AT report exists and verdict is FAIL:**
+- Do NOT transition. Print:
+  > "❌ AT report shows failures. Fix the issues and re-run /taip-workflow-acceptance-testing before closing."
+
+**If no AT report found:**
+- Ask: "No AT report found. Has acceptance testing been completed? (Y to transition / N to run AT first)"
+- If Y: transition to Done (user takes responsibility)
+- If N: "Run /taip-workflow-acceptance-testing first."
+
+### Step D5 — Summary
+
+Print:
+```
+🎉 Issue [PROJ-{seq}] closed.
+   PR:     {pr_url}
+   Branch: {branch}
+   Plan:   docs/plans/YYYY-MM-DD-{slug}.md
+```
+
+---
+
+## Hard fails
+
+- MUST NOT start work on an issue already in Done or Cancelled state
+- MUST NOT create a PR without a plan file existing under `docs/plans/`
+- MUST NOT transition issue to Done if any AT result is Fail or Blocked
+- MUST NOT skip the branch creation step — branch name must match `feature/{slug}-{sequence_id}`
+- **FILE phase:** MUST create (file) the task in a non-running cycle — never in the active/current
+  cycle. Promotion to the active cycle happens only via the explicit **runner** close choice (F7).
+- **FILE phase:** MUST NOT file a task whose plan lacks populated `## Requirements` or `## Acceptance Tests`
+- **FILE phase:** MUST embed the plan's `## Handover` block in the issue description, and MUST ask
+  the three-way close (runner / park / implement-now) each time — never auto-pick implement-now
+- If Plane MCP tool is not active: stop and print "Plane tool binding not active. Check integrations/tools/plane config."

package/packs/process/skills/taip-workflow-planning/SKILL.md

@@ -0,0 +1,159 @@
+---
+id: process/planning/plan-file-scaffold
+version: 2.1.0
+trigger: "create plan|make plan|plan this|plan file|planning"
+description: >
+  Scaffolds a plan file for a new development task. Checks for a feature branch,
+  proposes a filename under docs/plans/, waits for user confirmation, then creates
+  the plan with What, Requirements, Steps, Files, Excluded, Acceptance Tests,
+  Verification, Decisions, and Handover sections.
+  Blocks implementation until ## Requirements and ## Acceptance Tests are populated,
+  then exits the planning phase via a written ## Handover per process/planning/plan-phase-exit.
+user-invocable: true
+tags: [planning, workflow, process]
+attribution:
+  source: original
+  license: brain-official
+  author: brain Official
+---
+
+# taip-workflow-planning
+
+Plan file scaffold: branch check → propose filename → confirm → create.
+Implementation is blocked until `## Requirements` and `## Acceptance Tests` are populated.
+
+## Pre-conditions
+
+**Check 1 — Feature branch:**
+Verify a feature branch exists and is the current working branch.
+If on `main` or `master`: stop and ask the user to create a feature branch first.
+
+## Step 1 — Propose plan filename
+
+Propose: `docs/plans/YYYY-MM-DD-<short-slug>.md`
+
+- Use today's date
+- Slug: 3–5 words from the task description, kebab-case
+- Example: `docs/plans/2026-06-03-brain-agent-crypto.md`
+
+Ask: "Create plan at `docs/plans/YYYY-MM-DD-<slug>.md`? (Y to confirm or provide a different name)"
+
+WAIT for explicit confirmation. Do NOT auto-create.
+
+If a file already exists at that path: "A file already exists at that path. Please choose a different name."
+
+## Step 2 — Create plan file
+
+On confirmation, create with this template:
+
+```markdown
+# Plan: <Title>
+
+**Date:** YYYY-MM-DD
+**Status:** Draft
+**Branch:** `<current-branch>`
+
+## What
+
+<Goal and scope — 2–4 sentences>
+
+## Requirements
+
+<!-- Link to docs/requirements/ SR-ids, or list inline for lite tasks -->
+<!-- Lite: bullet each requirement directly here                       -->
+<!-- Full: - [SR-001](../requirements/software-requirements.md#sr-001) -->
+
+- [ ] <requirement or link>
+
+## Steps
+
+- [ ] Step one (depends on: none)
+- [ ] Step two (depends on: step 1)
+
+## Files
+
+- `path/to/file` — what changes and why
+
+## Excluded
+
+- What is explicitly not in scope
+
+## Acceptance Tests
+
+<!-- MUST be populated before implementation begins.                    -->
+<!-- Given/When/Then — one row per acceptance criterion.               -->
+<!-- Link to docs/tests/ file if a full test case file exists.        -->
+
+| # | Given | When | Then | Pass criterion |
+|---|---|---|---|---|
+| AC1 | <precondition> | <action> | <expected outcome> | <observable pass> |
+
+## Verification
+
+1. Command or check to confirm success
+
+## Decisions
+
+- Notes on decisions made during implementation
+
+## Handover
+
+<!-- Populated at the phase-exit gate (Step 4), before closing the planning session. -->
+<!-- Everything a fresh session or the sprint runner needs to resume with full context. -->
+
+**Start here:** <one-line goal>
+**Plan:** `docs/plans/YYYY-MM-DD-<slug>.md`   **Task:** <PROJ-seq, or "none">
+**Branch:** `feature/<slug>` (off `develop`)
+**Acceptance tests:** <one-line summary, or "AC1–ACn above">
+**Decisions/constraints:** <key decisions and hard constraints>
+**Next command:** <exact next command, e.g. /taip-workflow-plane-task start PROJ-seq>
+```
+
+Fill `## What` from the task description. Leave other sections as scaffolding with the comments;
+`## Handover` is filled at Step 4.
+
+## Step 3 — Gate on Requirements + Acceptance Tests
+
+After the plan file is created, show it to the user and print:
+
+```
+Next: populate ## Requirements and ## Acceptance Tests before beginning implementation.
+Implementation MUST NOT start until both sections are filled in.
+```
+
+Do NOT proceed to any file edits until the user confirms both sections are populated.
+
+If the user asks to start coding before populating them, remind:
+> "## Requirements and ## Acceptance Tests must be filled in before I can make any code changes.
+> This is a hard gate — please add at least one requirement and one Given/When/Then row."
+
+## Step 4 — Phase exit (write handover → close)
+
+This is the exit gate between the planning phase and the implementation phase
+(`process/planning/plan-phase-exit`). Once `## Requirements` and `## Acceptance Tests` are populated:
+
+1. **Write the `## Handover` section** in the plan file — fill every field (start-here goal, plan
+   path, task id(s), branch, acceptance tests, decisions/constraints, exact next command).
+
+2. **If the Plane tool binding (`integrations/tools/plane`) is active:**
+   Hand off to the `taip-workflow-plane-task` **FILE phase**. It creates a Plane issue from this
+   plan with the `## Handover` block embedded in the description, parks it in a **non-running**
+   cycle, then offers the three-way close (runner / park / implement-now). Do this before any edits.
+
+3. **Print the handover in chat and STOP.** Do NOT begin implementation in this session —
+   implementation starts deliberately in a fresh session or via the sprint runner.
+
+**Escape hatch:** if the user explicitly says "implement now", continue in this session — but the
+plan file + `## Handover` (and the filed task when Plane is active) MUST already exist first.
+
+**If Plane is not active:** still write `## Handover`, print it, and stop (unless "implement now").
+
+## Rules
+
+- Plan file MUST exist before any file edit or multi-step implementation
+- `## Requirements` MUST contain at least one item before implementation
+- `## Acceptance Tests` MUST contain at least one Given/When/Then row before implementation
+- Planning MUST exit via `process/planning/plan-phase-exit`: a written `## Handover` (and a filed
+  task carrying it when a PM binding is active), then the session SHOULD close
+- Do NOT delete the plan file after completion — it is the audit trail
+- Update `**Status:**` field as work progresses: Draft → In Progress → Done

package/packs/process/skills/taip-workflow-release/SKILL.md

@@ -0,0 +1,134 @@
+---
+id: process/git/release-cut
+version: 1.1.0
+trigger: "cut a release|prepare release|tag a version|tag a release|release version|make a release|hotfix release"
+description: >
+  Cuts a release per the project's declared git workflow (simplified or gitflow). Detects the
+  variant from CLAUDE.md, gates on a pre-tag release record and version==tag-semver, performs the
+  variant's branch/merge sequence, creates an annotated semver tag, registers the release, and
+  promotes the acceptance-tested artifact through the declared environments.
+  Use when the user says "cut a release", "tag a version", "prepare a release", or "hotfix release".
+user-invocable: true
+tags: [git, release, semver, changelog, gitflow, workflow]
+attribution:
+  source: original
+  license: brain-official
+  author: brain Official
+---
+
+# taip-workflow-release
+
+Release cut: **detect variant → pre-flight → version → record → CHANGELOG+release-notes+bump →
+branch/merge → annotate tag → back-merge (gitflow) → register → push → promote through environments.**
+
+## Step 0 — Detect the variant
+
+Read the `## Git / Release workflow` line from the project `CLAUDE.md` (written by the `taip-connect`
+installer). Resolve `simplified` or `gitflow`; **default `simplified`** if the section is absent.
+Announce the detected variant and its governing rule:
+
+- `simplified` → `process/git/branch-strategy` + `process/git/release-process`
+- `gitflow` → `process/git/gitflow-branch-strategy` + `process/git/gitflow-release-process`
+
+Everything below branches on this value.
+
+## Pre-conditions
+
+- **Clean tree** — `git status` MUST be clean; stop and ask the user to commit/stash otherwise.
+- **CI green** — confirm CI is passing on the source branch; warn if it cannot be determined.
+- **Last tag** — `git describe --tags --abbrev=0` (none → this is the first release).
+- **Version source** — locate the single-source version: `package.json` `version`, fallback `VERSION`.
+
+## Step 1 — Next version
+
+Derive the next `<semver>` from the Conventional Commits since the last tag (feat → MINOR, fix →
+PATCH, `!`/`BREAKING CHANGE` → MAJOR). Show the proposed version and the changes; **confirm with the
+user** before proceeding.
+
+## Step 2 — Set up the release branch (variant-specific)
+
+- **simplified:** stay on `develop` (the release is prepared here, then merged to `main`).
+- **gitflow:** `git checkout -b release/X.Y.Z develop` — Steps 3–4 commit onto this branch.
+
+## Step 3 — Release record (HARD GATE)
+
+Create `docs/releases/<semver>/release-record.md` BEFORE any tag (IEC 62304 §5.8;
+`qms/software-release/software-release`): version + date, changes since last release (with
+change-request/issue IDs), regression-test report reference, SOUP inventory version, known anomalies
+with safety evaluation, approver sign-off. MUST NOT tag until this exists.
+
+## Step 4 — CHANGELOG + release notes + version bump
+
+Update `CHANGELOG.md` (new version + date) and bump the single-source version so it **equals**
+`<semver>` (`engineering/ci/deterministic-image-tags`). Also write the **user-facing** release notes
+at `docs/releases/<semver>/release-notes.md` — categorized (New features / Improvements / Fixes /
+Breaking changes / Security), with no internal ticket IDs or system names, and a migration note on
+every breaking change (`process/git/release-notes`; draft them with `business/skills/workflow-release-notes`).
+The CHANGELOG (developer-facing) and the release notes (user-facing) are distinct documents. Commit
+all of this on the current branch (`develop` for simplified, `release/X.Y.Z` for gitflow) — in the
+release commit, not a post-tag follow-up.
+
+## Step 5 — Merge to `main` + annotated tag (confirm first)
+
+Show the exact commands, then on confirmation:
+
+- **simplified:**
+  ```sh
+  git checkout main && git merge --no-ff develop -m "chore(release): X.Y.Z"
+  git tag -a vX.Y.Z -m "Release vX.Y.Z"
+  ```
+- **gitflow:**
+  ```sh
+  git checkout main && git merge --no-ff release/X.Y.Z -m "chore(release): X.Y.Z"
+  git tag -a vX.Y.Z -m "Release vX.Y.Z"
+  ```
+
+Annotated tags only (`git tag -a`) — no lightweight tags, no pre-release suffixes (`-rc`, `-alpha`).
+
+## Step 6 — Back-merge into `develop` (gitflow only)
+
+```sh
+git checkout develop && git merge --no-ff release/X.Y.Z && git branch -d release/X.Y.Z
+```
+So `main` and `develop` never diverge. (Simplified skips this — `main` already tracks `develop`.)
+
+## Step 7 — Register + push
+
+Record the release AND each per-tenant deployment in `taip-infra/deployments/registry.yaml`
+(cross-repo — if the file/repo is absent, note it and continue; do not fail the release). Then push:
+
+```sh
+git push origin main vX.Y.Z          # simplified
+git push origin main develop vX.Y.Z  # gitflow
+```
+
+## Step 8 — Promote through environments (build once)
+
+Promote the **same** artifact that was tagged — the identical `<semver>-<gitsha>` image, never a
+rebuild — through the tiers declared in `CLAUDE.md` `## Environments` (default **2-tier** if absent;
+see `engineering/ci/environment-promotion`):
+
+- **2-tier:** the candidate runs on **integration** (or an ephemeral release-candidate deploy); run
+  `/taip-workflow-acceptance-testing`; on sign-off promote the identical digest to **production**.
+- **3-tier:** deploy the candidate to **staging**, run acceptance testing there; on sign-off promote
+  the identical `staging` digest to **production**.
+
+MUST NOT rebuild between acceptance and production, and MUST NOT promote an artifact that skipped its
+tier's acceptance stage. Record each promotion in `registry.yaml` (Step 7). Note: `develop`→integration
+is continuous (every merge), independent of cutting a release.
+
+## Hotfix path (gitflow only)
+
+For an urgent production fix: `git checkout -b hotfix/X.Y.Z main` (bump PATCH), run Steps 3–4 on it,
+then merge `--no-ff` into `main` (annotated tag) **and** into `develop`; delete the branch; register.
+
+## Rules
+
+- MUST NOT tag before `docs/releases/<semver>/release-record.md` exists (both variants).
+- MUST use annotated `vMAJOR.MINOR.PATCH` tags; version source MUST equal the tag semver.
+- MUST update `CHANGELOG.md` in the release commit.
+- MUST ship user-facing `docs/releases/<semver>/release-notes.md` — categorized, no internal identifiers (`process/git/release-notes`).
+- MUST record the release in `taip-infra/deployments/registry.yaml` (degrade gracefully if absent).
+- **gitflow:** MUST merge every release/hotfix into **both** `main` and `develop`; tag only on the `main` merge commit.
+- **simplified:** MUST merge `develop`→`main` and tag on `main`.
+- MUST promote the **same** acceptance-tested image digest to production — never rebuild between acceptance and prod (`engineering/ci/environment-promotion`).