@chief-clancy/plan 0.2.0 → 0.4.0

package/src/workflows/approve-plan.md

@@ -0,0 +1,1199 @@
+# Clancy Approve Plan Workflow
+
+## Overview
+
+Approve a Clancy implementation plan. Behaviour depends on the install context:
+
+- **Standalone mode** (no `.clancy/.env`): write a local `.clancy/plans/{stem}.approved` marker file with the plan's SHA-256 and approval timestamp. The marker is the gate `/clancy:implement-from` checks before applying changes
+- **Standalone+board mode** (`.clancy/.env` present, no full pipeline): with a board ticket key, run the existing comment-to-description transport flow; with a plan-file stem, write the local marker (board push lands in PR 9)
+- **Terminal mode** (full pipeline installed): existing behaviour — promote an approved plan from a ticket comment to the ticket description and transition the ticket to the implementation queue
+
+---
+
+## Step 1 — Preflight checks
+
+### 1. Detect installation context
+
+Check for `.clancy/.env`:
+
+- **Absent** → **standalone mode**. No board credentials. Board ticket arguments are blocked; only plan-file stems are accepted
+- **Present** → continue to `.clancy/clancy-implement.js` check below
+
+If `.clancy/.env` is present, check for `.clancy/clancy-implement.js`:
+
+- **Present** → **terminal mode**. Full Clancy pipeline installed
+- **Absent** → **standalone+board mode**. Board credentials available via `/clancy:board-setup`. Board ticket arguments work via the existing transport flow. Plan-file stems write the local marker
+
+### 2. Terminal-mode preflight (skip in standalone mode and standalone+board mode)
+
+If in **terminal mode** (`.clancy/.env` present AND `.clancy/clancy-implement.js` present):
+
+a. Source `.clancy/.env` and check board credentials are present.
+
+b. Check `CLANCY_ROLES` includes `planner` (or env var is unset, which indicates a global install where all roles are available). If `CLANCY_ROLES` is set but does not include `planner`:
+
+```
+The Planner role is not enabled. Add "planner" to CLANCY_ROLES in .clancy/.env or run /clancy:settings.
+```
+
+Stop.
+
+### 3. Standalone-mode preflight (only in standalone mode)
+
+If in **standalone mode** (no `.clancy/.env`), check that `.clancy/plans/` exists. If not:
+
+```
+No local plans found. Run /clancy:plan --from .clancy/briefs/<brief>.md first.
+```
+
+Stop.
+
+### 4. Standalone+board preflight (only in standalone+board mode)
+
+If in **standalone+board mode**, source `.clancy/.env` for board credentials. Both plan-file stems and board ticket arguments are valid in this mode — Step 2 routes between them.
+
+---
+
+## Step 2 — Resolve target
+
+The argument can be either a **plan-file stem** (e.g. `add-dark-mode-2`, matching a file at `.clancy/plans/{stem}.md`) or a **board ticket key** (e.g. `PROJ-123`, `#42`). Resolution depends on the installation mode detected in Step 1.
+
+### Standalone mode
+
+In standalone mode, the argument must be a plan-file stem. Board ticket keys are not valid here because there are no board credentials.
+
+**With argument:** look up `.clancy/plans/{arg}.md`. If the file does not exist:
+
+```
+Plan file not found: .clancy/plans/{arg}.md. Plan stems include the row number (e.g. `add-dark-mode-2`). Run /clancy:plan --list to see available plans.
+```
+
+Stop. Do not attempt to interpret the argument as a ticket key in standalone mode.
+
+**No argument:** auto-select the oldest unapproved local plan.
+
+1. Scan `.clancy/plans/` for `.md` files
+2. **Filter to plan files only**: a file qualifies as a plan if it contains the literal heading `## Clancy Implementation Plan` (the marker written by Step 4f / 5a of `plan.md`). Files without this heading are scratch / notes / drafts and are silently skipped — they are not approvable
+3. For each remaining file, check whether a sibling `.approved` marker exists at the same path with the `.approved` suffix. The unapproved set is qualifying files with no sibling marker
+4. Sort the unapproved set by the `**Planned:**` header date (ascending). Tie-break by Plan ID (alphabetical ascending). Files with a missing or unparseable `**Planned:**` date sort **last** (after all dated plans), then by Plan ID alphabetically among themselves. Mirrors `plan.md` Step 8 inventory's deterministic ordering
+
+If the unapproved set is empty:
+
+```
+No local plans awaiting approval. Run /clancy:plan --from .clancy/briefs/<brief>.md first, or all existing plans are already approved.
+```
+
+Stop. If non-empty, auto-select the first entry. Confirm with the user (skipped in `--afk` mode):
+
+```
+Auto-selected {stem} (planned {date}). Approve this plan? [Y/n]
+```
+
+If declined: `Cancelled.` Stop.
+
+### Standalone+board and terminal modes
+
+In these modes the argument may be either a plan-file stem or a board ticket key. **Try plan-file lookup first (does `.clancy/plans/{arg}.md` exist?)**, then fall back to ticket-key validation. The plan stem wins over ticket key on collision (e.g. if `PROJ-123.md` exists in `.clancy/plans/` AND `PROJ-123` is a valid ticket key, the plan stem wins). Document the collision rule explicitly so users are not surprised.
+
+**With argument that resolves to a plan file:** continue to Step 4 (Confirm), then Step 4a (Write local marker). The board push offer for plan-file-stem mode is deferred to a future PR — for now the local marker is the only side effect.
+
+**With argument that does not resolve to a plan file:** validate as a ticket key per the board configured in `.clancy/.env` (case-insensitive):
+
+- **GitHub:** `#\d+` or bare number
+- **Jira:** `[A-Za-z][A-Za-z0-9]+-\d+` (e.g. `PROJ-123` or `proj-123`)
+- **Linear:** `[A-Za-z]{1,10}-\d+` (e.g. `ENG-42` or `eng-42`)
+- **Azure DevOps:** `\d+` (bare number, e.g. `42` — work item IDs are always numeric)
+- **Shortcut:** `[A-Za-z]{1,5}-\d+` or bare number (e.g. `SC-123` or `123` — Shortcut story IDs are numeric, prefixed identifiers are optional)
+- **Notion:** UUID format (`[a-f0-9]{32}` or with dashes) or `notion-[a-f0-9]{8}` short key
+
+If invalid format:
+
+```
+Invalid ticket key: {input}. Expected format: {board-specific example}.
+```
+
+Stop.
+
+If valid: proceed with that key. The board transport flow runs (Steps 3-7 below) — this is the existing behaviour, unchanged from before PR 7b.
+
+**No argument:**
+
+- **Standalone+board and terminal:** scan `.clancy/progress.txt` for entries matching `| PLAN |` or `| REVISED |` that have no subsequent `| APPROVE_PLAN |` for the same key. Sort by timestamp ascending (oldest first).
+- If 0 found:
+  ```
+  No planned tickets awaiting approval. Run /clancy:plan first.
+  ```
+  Stop.
+- If 1+ found, auto-select the oldest. Show:
+  ```
+  Auto-selected [{KEY}] {Title} (planned {date}). Promote this plan? [Y/n]
+  ```
+  To resolve the title, fetch the ticket from the board:
+  - **GitHub:** `GET /repos/$GITHUB_REPO/issues/$ISSUE_NUMBER` → use `.title`
+  - **Jira:** `GET $JIRA_BASE_URL/rest/api/3/issue/$KEY?fields=summary` → use `.fields.summary`
+  - **Linear:** `issues(filter: { identifier: { eq: "$KEY" } }) { nodes { title } }` → use `nodes[0].title`
+  - **Azure DevOps:** `GET https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$ID?fields=System.Title&api-version=7.1` → use `.fields["System.Title"]`
+  - **Shortcut:** `GET https://api.app.shortcut.com/api/v3/stories/$STORY_ID` → use `.name`
+  - **Notion:** `GET https://api.notion.com/v1/pages/$PAGE_ID` → extract title from the `title` type property in `properties`
+    If fetching fails, show the key without a title: `Auto-selected [{KEY}] (planned {date}). Promote? [Y/n]`
+- If user declines:
+  ```
+  Cancelled.
+  ```
+  Stop.
+- Note that the user has already confirmed — set a flag to skip the Step 4 confirmation.
+
+---
+
+## Step 3 — Fetch the plan comment
+
+Detect board from `.clancy/.env` and fetch comments for the specified ticket.
+
+### Jira
+
+```bash
+RESPONSE=$(curl -s \
+  -u "$JIRA_USER:$JIRA_API_TOKEN" \
+  -H "Accept: application/json" \
+  "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/comment")
+```
+
+Search for the most recent comment containing an ADF heading node with text `Clancy Implementation Plan`. **Capture the comment `id`** for later editing in Step 5b.
+
+### GitHub
+
+First, determine the issue number from the ticket key (strip the `#` prefix if present):
+
+```bash
+RESPONSE=$(curl -s \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER/comments?per_page=100")
+```
+
+Search for the most recent comment body containing `## Clancy Implementation Plan`. **Capture the comment `id`** for later editing in Step 5b.
+
+### Linear
+
+Use the filter-based query (preferred over `issueSearch`):
+
+```graphql
+query {
+  issues(filter: { identifier: { eq: "$KEY" } }) {
+    nodes {
+      id
+      identifier
+      title
+      description
+      comments {
+        nodes {
+          id
+          body
+          createdAt
+          user {
+            id
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+If the filter-based query returns no results, fall back to `issueSearch`:
+
+```graphql
+query {
+  issueSearch(query: "$IDENTIFIER", first: 5) {
+    nodes {
+      id
+      identifier
+      title
+      description
+      comments {
+        nodes {
+          id
+          body
+          createdAt
+          user {
+            id
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Important:** `issueSearch` is a fuzzy text search. After fetching results, verify the returned issue's `identifier` field exactly matches the provided key (case-insensitive). If no exact match is found in the results, report: `Issue {KEY} not found. Check the identifier and try again.`
+
+Search the comments for the most recent one containing `## Clancy Implementation Plan`. **Capture the comment `id`** and the existing comment `body` for later editing in Step 5b. Also capture the issue's internal `id` (UUID) for transitions in Step 6.
+
+### Azure DevOps
+
+Fetch work item comments:
+
+```bash
+RESPONSE=$(curl -s \
+  -u ":$AZDO_PAT" \
+  -H "Accept: application/json" \
+  "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID/comments?api-version=7.1-preview.4")
+```
+
+Search `comments` array for the most recent comment where the `text` field (HTML) contains `Clancy Implementation Plan` (as an `<h2>` heading or plain text). **Capture the comment `id`** for later editing in Step 5b. Also fetch the work item title and description:
+
+```bash
+WORK_ITEM=$(curl -s \
+  -u ":$AZDO_PAT" \
+  -H "Accept: application/json" \
+  "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID?fields=System.Title,System.Description&api-version=7.1")
+```
+
+### Shortcut
+
+Fetch story comments:
+
+```bash
+RESPONSE=$(curl -s \
+  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+  "https://api.app.shortcut.com/api/v3/stories/$STORY_ID/comments")
+```
+
+Search for the most recent comment where `text` contains `## Clancy Implementation Plan`. **Capture the comment `id`** for later editing in Step 5b. Also fetch the story for its title and description:
+
+```bash
+STORY=$(curl -s \
+  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+  "https://api.app.shortcut.com/api/v3/stories/$STORY_ID")
+```
+
+### Notion
+
+Fetch page comments:
+
+```bash
+RESPONSE=$(curl -s \
+  -H "Authorization: Bearer $NOTION_TOKEN" \
+  -H "Notion-Version: 2022-06-28" \
+  "https://api.notion.com/v1/comments?block_id=$PAGE_ID")
+```
+
+Search `results` array for the most recent comment where `rich_text` content contains `Clancy Implementation Plan`. **Capture the comment `id`** for later reference in Step 5b. Also fetch the page for its title and content:
+
+```bash
+PAGE=$(curl -s \
+  -H "Authorization: Bearer $NOTION_TOKEN" \
+  -H "Notion-Version: 2022-06-28" \
+  "https://api.notion.com/v1/pages/$PAGE_ID")
+```
+
+**Notion limitation:** Comments use `rich_text` arrays. Search each comment's `rich_text[].text.content` for the plan marker.
+
+If no plan comment is found:
+
+```
+No Clancy plan found for {KEY}. Run /clancy:plan first.
+```
+
+Stop.
+
+---
+
+## Step 3b — Check for existing plan in description
+
+Before confirming, check if the ticket description already contains `## Clancy Implementation Plan`.
+
+If it does:
+
+```
+This ticket's description already contains a Clancy plan.
+Continuing will add a duplicate.
+
+[1] Continue anyway
+[2] Cancel
+```
+
+If the user picks [2], stop: `Cancelled. No changes made.`
+
+---
+
+## Step 4 — Confirm
+
+**If the user already confirmed via auto-select in Step 2, SKIP this step entirely** (avoid double-confirmation).
+
+**AFK mode:** If running in AFK mode (`--afk` flag or `CLANCY_MODE=afk`), skip the confirmation prompt and auto-confirm. Display the summary for logging purposes but proceed without waiting for input.
+
+Display a summary and ask for confirmation:
+
+```
+Clancy — Approve Plan
+
+[{KEY}] {Title}
+Size: {S/M/L} | {N} affected files
+Planned: {date from plan}
+
+Promote this plan to the ticket description? [Y/n]
+```
+
+If the user declines (interactive only), stop:
+
+```
+Cancelled. No changes made.
+```
+
+For **plan-file stem mode** (Step 2 resolved the argument to a local plan file), the summary shows the plan stem instead of `[{KEY}] {Title}`:
+
+```
+Clancy — Approve Plan (local)
+
+{stem}
+Size: {S/M/L} | {N} affected files
+Planned: {date from plan}
+
+Approve this plan? [Y/n]
+```
+
+After confirmation in plan-file stem mode, jump to Step 4a (local marker write). For board ticket key mode, continue to Step 5 below.
+
+---
+
+## Step 4a — Write local marker
+
+Run this step instead of Steps 5, 5b, 6 when the resolved argument was a plan-file stem (standalone mode, or standalone+board / terminal mode where Step 2 found a matching plan file). Write a `.clancy/plans/{stem}.approved` marker that gates `/clancy:implement-from`.
+
+### Compute the SHA-256
+
+**Order of operations** (do these in order, exactly):
+
+1. Read the plan file at `.clancy/plans/{stem}.md` from disk into memory as bytes.
+2. Compute the SHA-256 hash of those bytes — no normalisation (no line-ending fix, no trailing-whitespace strip, no BOM removal). Hex-encode lowercase.
+3. **Then** (only after the hash is computed) open the `.approved` marker for exclusive create as described below.
+
+The `.approved` file is **never** included in the hash — only `.clancy/plans/{stem}.md` is hashed, and only its on-disk byte content at the moment of step 1. PR 8's `/clancy:implement-from` re-reads the same plan file, hashes it the same way, and compares to the `sha256=` value stored in the marker. Any divergence (re-edit, line-ending change, trailing whitespace tweak) blocks implementation until re-approval.
+
+### Write the marker file with O_EXCL
+
+Open `.clancy/plans/{stem}.approved` for **exclusive create** (Node `fs.openSync(path, 'wx')`, equivalent to `open(2)` with `O_EXCL`). Write the marker body as plain text:
+
+```
+sha256={hex sha256 of the plan file at approval time}
+approved_at={ISO 8601 UTC timestamp, e.g. 2026-04-08T22:30:00Z}
+```
+
+Two `key=value` lines, each terminated with `\n`. No JSON, no extra whitespace, no comments. PR 8 parses this with a tolerant `^(sha256|approved_at)=(.+)$` regex per line.
+
+### Handle EEXIST (already-approved)
+
+If the exclusive create fails with `EEXIST`, the marker already exists — the plan was previously approved. Stop with:
+
+```
+Plan already approved: {stem}
+Marker: .clancy/plans/{stem}.approved
+
+To re-approve (e.g. after revising the plan):
+  Delete .clancy/plans/{stem}.approved manually, then re-run /clancy:approve-plan {stem}
+```
+
+A `--fresh` flag for `/clancy:approve-plan` is not implemented in this release. Manual deletion is the supported re-approval path.
+
+### Marker is the gate for /clancy:implement-from
+
+The `.approved` marker is the gate `/clancy:implement-from` checks before applying changes. PR 8 reads the marker, hashes the current plan file, and compares to the stored `sha256`. Match → proceed; mismatch → block with a "plan changed since approval" error. This is why the SHA must be computed over the plan file content (not just touched as an empty file).
+
+### After writing the marker
+
+After the marker is written successfully, update the source brief file's marker comment (Step 4b below), then jump to Step 7 (Confirm and log). Steps 5, 5b, and 6 (board transport) are skipped entirely in plan-file stem mode.
+
+---
+
+## Step 4b — Update brief marker (best-effort)
+
+After Step 4a writes the local plan marker, update the source brief file's planned-rows marker so `/clancy:plan --list` and the brief's display logic know which rows have been approved. This step is best-effort: any failure here logs a warning but does NOT roll back the `.clancy/plans/{stem}.approved` marker.
+
+### Resolve the source brief filename
+
+Read the plan file at `.clancy/plans/{stem}.md` and extract the `**Brief:**` header line (e.g. `**Brief:** 2026-04-01-add-dark-mode.md`). The value is the brief filename relative to `.clancy/briefs/`. If the line is absent or empty, warn and skip the rest of Step 4b:
+
+```
+⚠ Plan {stem} has no **Brief:** header — cannot update brief marker. Continuing without brief update.
+```
+
+### Resolve the row number
+
+Extract the row number from the plan file's `**Row:**` header line (e.g. `**Row:** #2 — Add toggle component`). The number after `#` and before the em-dash (U+2014, U+2013, or hyphen) is the row. If absent, warn and skip Step 4b.
+
+### Find and update the marker
+
+Open `.clancy/briefs/{brief-filename}` and find the marker comment matching this tolerant regex (line-anchored, allows missing-or-present `approved:` prefix, allows arbitrary whitespace):
+
+```
+^<!--\s*(?:approved:([\d,]*)\s+)?planned:([\d,]+)\s*-->\s*$
+```
+
+This matches all of:
+
+- `<!-- planned:1,2,3 -->` (no approved prefix yet — current state from PR 6b)
+- `<!-- approved:1 planned:1,2,3 -->` (PR 7b adds the approved prefix)
+- `<!-- approved: planned:1,2,3 -->` (empty approved list — should not happen but handle gracefully)
+- `<!--planned:1,2,3-->` (no surrounding spaces — hand-edited)
+
+If no marker line matches, warn and skip — do not synthesise a marker. The brief should already have one written by `/clancy:plan --from`.
+
+**Reversed-order markers** (`<!-- planned:1,2 approved:1 -->` — `planned:` first, `approved:` second) do NOT match this regex and fall through to the warn-and-skip branch. The canonical ordering is enforced on every write, so a brief that drifts into reversed order requires manual correction. If you see the warning "no marker found" but the brief clearly has a marker, check the order — `approved:` must come before `planned:`.
+
+**Code-fence false positives:** the regex is line-anchored but does NOT track fenced-code-block context. If a brief file embeds an example marker inside a triple-backtick block (e.g. documentation about how markers work), the regex may match the example. The first match wins, so authors should keep the real marker as the first marker line in the file. The `## Feedback` detector in `plan.md` Step 3a uses code-fence-aware parsing for the same reason — apply that pattern manually if a brief becomes complex enough to need it.
+
+If a marker matches, parse the existing `approved:` and `planned:` row lists. Add the current row number to the `approved:` list (deduped, sorted ascending). Reconstruct the marker with the canonical ordering: `approved:` first, `planned:` second, single space between fields and inside the comment. Example:
+
+- Before: `<!-- planned:1,2,3 -->`, current row = `2`
+- After: `<!-- approved:2 planned:1,2,3 -->`
+- Before: `<!-- approved:1 planned:1,2,3 -->`, current row = `2`
+- After: `<!-- approved:1,2 planned:1,2,3 -->`
+
+Write the updated brief file back. The read-modify-write is not concurrency-safe — running multiple `/clancy:approve-plan` commands against the same brief in parallel may produce duplicate or missing entries. Single-user local flow is assumed (mirrors the concurrency note in [`plan.md` Step 3a](./plan.md)).
+
+### Best-effort failure handling
+
+If any step in 4b fails (file not found, marker not found, write error, regex mismatch), log a warning but do NOT roll back the `.clancy/plans/{stem}.approved` marker. The local marker is the source of truth — the brief marker is metadata for display and `/clancy:plan --list`. Example warning:
+
+```
+⚠ Failed to update brief marker for {stem}: {reason}
+The plan is still approved. The .clancy/plans/{stem}.approved marker is in place.
+You can manually update .clancy/briefs/{brief}.md if needed.
+```
+
+After Step 4b completes (successfully or with a warning), jump to Step 7 (Confirm and log). Skip Steps 5, 5b, and 6 entirely.
+
+---
+
+## Step 5 — Update ticket description
+
+Append the plan below the existing description with a separator. Never overwrite the original description.
+
+The updated description follows this format:
+
+```
+{existing description}
+
+---
+
+{full plan content}
+```
+
+### Jira — PUT issue
+
+Fetch the current description first:
+
+```bash
+CURRENT=$(curl -s \
+  -u "$JIRA_USER:$JIRA_API_TOKEN" \
+  -H "Accept: application/json" \
+  "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY?fields=description")
+```
+
+Merge the existing ADF description with a `rule` node (horizontal rule) and the plan content as new ADF nodes. Then update:
+
+```bash
+curl -s \
+  -u "$JIRA_USER:$JIRA_API_TOKEN" \
+  -X PUT \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY" \
+  -d '{"fields": {"description": <merged ADF>}}'
+```
+
+If ADF construction fails for the plan content, wrap the plan in a `codeBlock` node as fallback.
+
+### GitHub — PATCH issue
+
+Fetch the current body:
+
+```bash
+CURRENT=$(curl -s \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER")
+```
+
+Append the plan:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  -X PATCH \
+  "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER" \
+  -d '{"body": "<existing body>\n\n---\n\n<plan>"}'
+```
+
+### Linear — issueUpdate mutation
+
+Fetch the current description:
+
+```graphql
+query {
+  issue(id: "$ISSUE_ID") {
+    description
+  }
+}
+```
+
+Update with appended plan:
+
+```graphql
+mutation {
+  issueUpdate(
+    id: "$ISSUE_ID"
+    input: { description: "<existing>\n\n---\n\n<plan>" }
+  ) {
+    success
+  }
+}
+```
+
+### Azure DevOps — PATCH work item
+
+Fetch the current description:
+
+```bash
+CURRENT=$(curl -s \
+  -u ":$AZDO_PAT" \
+  -H "Accept: application/json" \
+  "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID?fields=System.Description&api-version=7.1")
+```
+
+Azure DevOps descriptions are **HTML**. Append the plan (converted to HTML) with a horizontal rule separator:
+
+```bash
+curl -s \
+  -u ":$AZDO_PAT" \
+  -X PATCH \
+  -H "Content-Type: application/json-patch+json" \
+  "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID?api-version=7.1" \
+  -d '[{"op": "replace", "path": "/fields/System.Description", "value": "<existing HTML>\n<hr>\n<plan as HTML>"}]'
+```
+
+Convert the plan markdown to HTML using the same conversion rules as Step 5 in plan.md (headings, lists, tables, bold, code → HTML equivalents). If HTML construction is too complex, wrap the plan in `<pre>` tags as fallback.
+
+### Shortcut — PUT story
+
+Fetch the current description:
+
+```bash
+CURRENT=$(curl -s \
+  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+  "https://api.app.shortcut.com/api/v3/stories/$STORY_ID")
+```
+
+Append the plan (Shortcut descriptions use markdown):
+
+```bash
+curl -s \
+  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -X PUT \
+  "https://api.app.shortcut.com/api/v3/stories/$STORY_ID" \
+  -d '{"description": "<existing description>\n\n---\n\n<plan>"}'
+```
+
+### Notion — Append blocks to page
+
+Notion page "descriptions" are stored as **child blocks**, not a single text property. To append the plan, add new blocks to the page:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $NOTION_TOKEN" \
+  -H "Notion-Version: 2022-06-28" \
+  -X PATCH \
+  "https://api.notion.com/v1/blocks/$PAGE_ID/children" \
+  -d '{"children": [
+    {"type": "divider", "divider": {}},
+    {"type": "heading_2", "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Clancy Implementation Plan"}}]}},
+    {"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "<plan section text>"}}]}}
+  ]}'
+```
+
+Convert the plan into Notion block format:
+
+- `## Heading` → `heading_2` block
+- `### Heading` → `heading_3` block
+- Plain text paragraphs → `paragraph` block
+- `- bullet` → `bulleted_list_item` block
+- `- [ ] checkbox` → `to_do` block
+- Tables → not natively supported as blocks; use `paragraph` blocks with monospace formatting, or split into individual `paragraph` blocks per row
+- Code blocks → `code` block with `language: "markdown"`
+
+**Notion limitation:** Each `rich_text` block has a **2000-character limit**. Split long sections across multiple blocks. The `children` array can contain up to **100 blocks** per request — if the plan is very large, make multiple PATCH calls.
+
+**Notion limitation:** Unlike other boards, this appends to the page body (not the description property). The plan content will appear at the bottom of the page, after existing content, separated by a divider.
+
+---
+
+## Step 5b — Edit plan comment (approval note)
+
+After updating the description, edit the original plan comment to prepend an approval note. This is **best-effort** — warn on failure, continue.
+
+### GitHub
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  -H "Content-Type: application/json" \
+  -X PATCH \
+  "https://api.github.com/repos/$GITHUB_REPO/issues/comments/$COMMENT_ID" \
+  -d '{"body": "> **Plan approved and promoted to description** -- {YYYY-MM-DD}\n\n{existing_comment_body}"}'
+```
+
+### Jira
+
+```bash
+curl -s \
+  -u "$JIRA_USER:$JIRA_API_TOKEN" \
+  -X PUT \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/comment/$COMMENT_ID" \
+  -d '{
+    "body": {
+      "version": 1,
+      "type": "doc",
+      "content": [
+        {"type": "paragraph", "content": [
+          {"type": "text", "text": "Plan approved and promoted to description -- {YYYY-MM-DD}.",
+           "marks": [{"type": "strong"}]}
+        ]},
+        <...existing ADF content nodes...>
+      ]
+    }
+  }'
+```
+
+### Linear
+
+```graphql
+mutation {
+  commentUpdate(
+    id: "$COMMENT_ID"
+    input: {
+      body: "> **Plan approved and promoted to description** -- {YYYY-MM-DD}\n\n{existing_comment_body}"
+    }
+  ) {
+    success
+  }
+}
+```
+
+### Azure DevOps
+
+```bash
+curl -s \
+  -u ":$AZDO_PAT" \
+  -X PATCH \
+  -H "Content-Type: application/json" \
+  "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID/comments/$COMMENT_ID?api-version=7.1-preview.4" \
+  -d '{"text": "<p><strong>Plan approved and promoted to description -- {YYYY-MM-DD}.</strong></p><existing HTML comment>"}'
+```
+
+### Shortcut
+
+```bash
+curl -s \
+  -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -X PUT \
+  "https://api.app.shortcut.com/api/v3/stories/$STORY_ID/comments/$COMMENT_ID" \
+  -d '{"text": "> **Plan approved and promoted to description** -- {YYYY-MM-DD}\n\n{existing_comment_text}"}'
+```
+
+### Notion
+
+**Notion limitation:** The Notion API does **not support editing comments**. There is no PATCH/PUT endpoint for comments. Instead, post a new comment with the approval note:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $NOTION_TOKEN" \
+  -H "Notion-Version: 2022-06-28" \
+  -X POST \
+  "https://api.notion.com/v1/comments" \
+  -d '{"parent": {"page_id": "$PAGE_ID"}, "rich_text": [{"type": "text", "text": {"content": "Plan approved and promoted to page content — {YYYY-MM-DD}."}, "annotations": {"bold": true}}]}'
+```
+
+This posts a new comment rather than editing the original plan comment. The approval note references the plan being promoted to the page body (not description, since Notion uses blocks).
+
+On failure for any platform:
+
+```
+Could not update plan comment. The plan is still promoted to the description.
+```
+
+---
+
+## Step 6 — Post-approval label transition
+
+Transition the ticket from the planning queue to the implementation queue via pipeline labels. This is **best-effort** — warn on failure, continue.
+
+**Crash safety:** Add the new label BEFORE removing the old one. A ticket briefly has two labels (harmless) rather than zero labels (ticket lost).
+
+**This label transition is mandatory — always apply and remove.** Use `CLANCY_LABEL_BUILD` from `.clancy/.env` if set, otherwise `clancy:build`. Use `CLANCY_LABEL_PLAN` from `.clancy/.env` if set, otherwise `clancy:plan`. Ensure the build label exists on the board (create if missing), add it to the ticket, then remove the plan label.
+
+**If build label creation fails** (GitHub/Linear/Shortcut require explicit creation): warn and **do not remove the plan label**. The ticket must keep at least one pipeline label — removing the plan label without a build label would orphan the ticket from both queues.
+
+### GitHub
+
+1. **Add build label** (ensure it exists first):
+
+   ```bash
+   # Ensure label exists (ignore 422 = already exists)
+   curl -s \
+     -H "Authorization: Bearer $GITHUB_TOKEN" \
+     -H "Accept: application/vnd.github+json" \
+     -H "X-GitHub-Api-Version: 2022-11-28" \
+     -H "Content-Type: application/json" \
+     -X POST \
+     "https://api.github.com/repos/$GITHUB_REPO/labels" \
+     -d '{"name": "$CLANCY_LABEL_BUILD", "color": "0075ca"}'
+
+   # Add to issue
+   curl -s \
+     -H "Authorization: Bearer $GITHUB_TOKEN" \
+     -H "Accept: application/vnd.github+json" \
+     -H "X-GitHub-Api-Version: 2022-11-28" \
+     -H "Content-Type: application/json" \
+     -X POST \
+     "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER/labels" \
+     -d '{"labels": ["$CLANCY_LABEL_BUILD"]}'
+   ```
+
+2. **Remove plan label:**
+   ```bash
+   curl -s \
+     -H "Authorization: Bearer $GITHUB_TOKEN" \
+     -H "Accept: application/vnd.github+json" \
+     -H "X-GitHub-Api-Version: 2022-11-28" \
+     -X DELETE \
+     "https://api.github.com/repos/$GITHUB_REPO/issues/$ISSUE_NUMBER/labels/$(echo $CLANCY_LABEL_PLAN | jq -Rr @uri)"
+   ```
+   Ignore 404 (label not on issue).
+
+### Jira
+
+1. **Add build label** (Jira auto-creates labels):
+
+   ```bash
+   # Fetch current labels
+   CURRENT_LABELS=$(curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -H "Accept: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY?fields=labels" | jq -r '.fields.labels')
+
+   # Add build label
+   UPDATED_LABELS=$(echo "$CURRENT_LABELS" | jq --arg build "$CLANCY_LABEL_BUILD" '. + [$build] | unique')
+
+   curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -X PUT \
+     -H "Content-Type: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY" \
+     -d "{\"fields\": {\"labels\": $UPDATED_LABELS}}"
+   ```
+
+2. **Remove plan label:**
+
+   ```bash
+   # Re-fetch labels (may have changed), remove plan label
+   CURRENT_LABELS=$(curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -H "Accept: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY?fields=labels" | jq -r '.fields.labels')
+
+   UPDATED_LABELS=$(echo "$CURRENT_LABELS" | jq --arg plan "$CLANCY_LABEL_PLAN" '[.[] | select(. != $plan)]')
+
+   curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -X PUT \
+     -H "Content-Type: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY" \
+     -d "{\"fields\": {\"labels\": $UPDATED_LABELS}}"
+   ```
+
+3. **Status transition** (only if `CLANCY_STATUS_PLANNED` is set — skip if unset):
+
+   ```bash
+   # Fetch transitions
+   curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -H "Accept: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions"
+
+   # Find matching transition and execute
+   curl -s \
+     -u "$JIRA_USER:$JIRA_API_TOKEN" \
+     -X POST \
+     -H "Content-Type: application/json" \
+     "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY/transitions" \
+     -d '{"transition": {"id": "$TRANSITION_ID"}}'
+   ```
+
+On failure:
+
+```
+Could not transition ticket. Move it manually to your implementation queue.
+```
+
+### Linear
+
+1. **Add build label** (ensure it exists, then add):
+
+   ```graphql
+   # Ensure label exists — check team labels, workspace labels, create if missing
+   mutation {
+     issueLabelCreate(input: {
+       teamId: "$LINEAR_TEAM_ID"
+       name: "$CLANCY_LABEL_BUILD"
+       color: "#0075ca"
+     }) { success issueLabel { id } }
+   }
+
+   # Fetch current label IDs on the issue, add build label ID
+   mutation {
+     issueUpdate(
+       id: "$ISSUE_UUID"
+       input: { labelIds: [...currentLabelIds, buildLabelId] }
+     ) { success }
+   }
+   ```
+
+2. **Remove plan label:**
+
+   ```graphql
+   # Fetch current label IDs, filter out plan label ID
+   mutation {
+     issueUpdate(
+       id: "$ISSUE_UUID"
+       input: { labelIds: [currentLabelIds, without, planLabelId] }
+     ) {
+       success
+     }
+   }
+   ```
+
+3. **State transition** (always):
+
+   ```graphql
+   # Resolve "unstarted" state
+   query {
+     workflowStates(
+       filter: {
+         team: { id: { eq: "$LINEAR_TEAM_ID" } }
+         type: { eq: "unstarted" }
+       }
+     ) {
+       nodes {
+         id
+         name
+       }
+     }
+   }
+
+   # Transition
+   mutation {
+     issueUpdate(id: "$ISSUE_UUID", input: { stateId: "$UNSTARTED_STATE_ID" }) {
+       success
+     }
+   }
+   ```
+
+   If no `unstarted` state found: warn, skip transition.
+
+### Azure DevOps
+
+Azure DevOps uses **tags** (semicolon-delimited string field) instead of labels, and **board columns/states** for transitions.
+
+1. **Add build tag:**
+
+   ```bash
+   # Fetch current tags
+   CURRENT=$(curl -s \
+     -u ":$AZDO_PAT" \
+     -H "Accept: application/json" \
+     "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID?fields=System.Tags&api-version=7.1")
+
+   # Append build tag (semicolon-delimited)
+   # If existing tags are "clancy:plan; bug-fix", new value is "clancy:plan; bug-fix; clancy:build"
+   curl -s \
+     -u ":$AZDO_PAT" \
+     -X PATCH \
+     -H "Content-Type: application/json-patch+json" \
+     "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID?api-version=7.1" \
+     -d '[{"op": "replace", "path": "/fields/System.Tags", "value": "<existing tags>; $CLANCY_LABEL_BUILD"}]'
+   ```
+
+2. **Remove plan tag:**
+
+   ```bash
+   # Re-fetch tags, remove plan tag from the semicolon-delimited string
+   # E.g., "clancy:plan; bug-fix; clancy:build" → "bug-fix; clancy:build"
+   curl -s \
+     -u ":$AZDO_PAT" \
+     -X PATCH \
+     -H "Content-Type: application/json-patch+json" \
+     "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID?api-version=7.1" \
+     -d '[{"op": "replace", "path": "/fields/System.Tags", "value": "<tags without plan tag>"}]'
+   ```
+
+3. **State transition** (only if `CLANCY_STATUS_PLANNED` is set — skip if unset):
+
+   ```bash
+   curl -s \
+     -u ":$AZDO_PAT" \
+     -X PATCH \
+     -H "Content-Type: application/json-patch+json" \
+     "https://dev.azure.com/$AZDO_ORG/$AZDO_PROJECT/_apis/wit/workitems/$WORK_ITEM_ID?api-version=7.1" \
+     -d '[{"op": "replace", "path": "/fields/System.State", "value": "$CLANCY_STATUS_PLANNED"}]'
+   ```
+
+### Shortcut
+
+Shortcut uses **labels** and **workflow state transitions**.
+
+1. **Add build label:**
+
+   ```bash
+   # Resolve build label ID (create if missing)
+   LABELS=$(curl -s \
+     -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+     "https://api.app.shortcut.com/api/v3/labels")
+
+   # Find or create the build label, get its ID
+   # Then add to story:
+   curl -s \
+     -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+     -H "Content-Type: application/json" \
+     -X PUT \
+     "https://api.app.shortcut.com/api/v3/stories/$STORY_ID" \
+     -d '{"labels": [{"name": "$CLANCY_LABEL_BUILD"}, ...existing_labels]}'
+   ```
+
+2. **Remove plan label:**
+
+   ```bash
+   # Fetch current story labels, filter out plan label, update
+   curl -s \
+     -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+     -H "Content-Type: application/json" \
+     -X PUT \
+     "https://api.app.shortcut.com/api/v3/stories/$STORY_ID" \
+     -d '{"labels": [labels_without_plan_label]}'
+   ```
+
+3. **Workflow state transition:**
+
+   ```bash
+   # Resolve the "Unstarted" or "Ready for Development" state ID from workflows
+   WORKFLOWS=$(curl -s \
+     -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+     "https://api.app.shortcut.com/api/v3/workflows")
+
+   # Find state with type "unstarted", get its ID
+   curl -s \
+     -H "Shortcut-Token: $SHORTCUT_API_TOKEN" \
+     -H "Content-Type: application/json" \
+     -X PUT \
+     "https://api.app.shortcut.com/api/v3/stories/$STORY_ID" \
+     -d '{"workflow_state_id": $UNSTARTED_STATE_ID}'
+   ```
+
+   If no suitable state found: warn, skip transition.
+
+### Notion
+
+Notion uses **multi-select properties** for labels and **status properties** for transitions.
+
+1. **Add build label** (add to multi-select property):
+
+   ```bash
+   # Fetch current page properties
+   PAGE=$(curl -s \
+     -H "Authorization: Bearer $NOTION_TOKEN" \
+     -H "Notion-Version: 2022-06-28" \
+     "https://api.notion.com/v1/pages/$PAGE_ID")
+
+   # Update multi-select property to include build label
+   curl -s \
+     -H "Authorization: Bearer $NOTION_TOKEN" \
+     -H "Notion-Version: 2022-06-28" \
+     -X PATCH \
+     "https://api.notion.com/v1/pages/$PAGE_ID" \
+     -d '{"properties": {"$CLANCY_NOTION_LABELS": {"multi_select": [existing_options, {"name": "$CLANCY_LABEL_BUILD"}]}}}'
+   ```
+
+2. **Remove plan label** (update multi-select without plan label):
+
+   ```bash
+   curl -s \
+     -H "Authorization: Bearer $NOTION_TOKEN" \
+     -H "Notion-Version: 2022-06-28" \
+     -X PATCH \
+     "https://api.notion.com/v1/pages/$PAGE_ID" \
+     -d '{"properties": {"$CLANCY_NOTION_LABELS": {"multi_select": [options_without_plan_label]}}}'
+   ```
+
+3. **Status transition** (only if `CLANCY_STATUS_PLANNED` is set):
+
+   ```bash
+   curl -s \
+     -H "Authorization: Bearer $NOTION_TOKEN" \
+     -H "Notion-Version: 2022-06-28" \
+     -X PATCH \
+     "https://api.notion.com/v1/pages/$PAGE_ID" \
+     -d '{"properties": {"$CLANCY_NOTION_STATUS": {"status": {"name": "$CLANCY_STATUS_PLANNED"}}}}'
+   ```
+
+On failure:
+
+```
+Could not transition ticket. Move it manually to your implementation queue.
+```
+
+---
+
+## Step 7 — Confirm and log
+
+**Mode gate (read first):** if Steps 4a/4b ran (the resolved argument was a plan-file stem), skip the entire "board-specific success message" and "board-mode progress.txt entry" blocks below and jump straight to the **Local mode (Step 4a / 4b path)** subsection further down. The board-success-message text only applies when Steps 5/5b/6 ran for a board ticket key. Do NOT render both — exactly one branch executes per approval.
+
+On success in **board ticket mode**, display a board-specific message:
+
+**GitHub:**
+
+```
+Plan promoted. Label swapped: {CLANCY_LABEL_PLAN} → {CLANCY_LABEL_BUILD}. Ready for /clancy:implement.
+
+"Book 'em, Lou." — The ticket is ready for /clancy:implement.
+```
+
+**Jira (with transition):**
+
+```
+Plan promoted. Ticket transitioned to {CLANCY_STATUS_PLANNED}.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+**Jira (no transition configured):**
+
+```
+Plan promoted. Move [{KEY}] to your implementation queue for /clancy:implement.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+**Linear:**
+
+```
+Plan promoted. Moved to unstarted. Ready for /clancy:implement.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+**Azure DevOps (with transition):**
+
+```
+Plan promoted. Work item transitioned to {CLANCY_STATUS_PLANNED}.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+**Azure DevOps (no transition configured):**
+
+```
+Plan promoted. Move work item {ID} to your implementation queue for /clancy:implement.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+**Shortcut:**
+
+```
+Plan promoted. Moved to unstarted. Ready for /clancy:implement.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+**Notion (with transition):**
+
+```
+Plan promoted to page content. Status updated to {CLANCY_STATUS_PLANNED}.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+**Notion (no transition configured):**
+
+```
+Plan promoted to page content. Move the page to your implementation queue for /clancy:implement.
+
+"Book 'em, Lou." -- The ticket is ready for /clancy:implement.
+```
+
+Append to `.clancy/progress.txt` for **board mode**:
+
+```
+YYYY-MM-DD HH:MM | {KEY} | APPROVE_PLAN | —
+```
+
+On board failure:
+
+```
+Failed to update description for [{KEY}]. Check your board permissions.
+```
+
+### Local mode (Step 4a / 4b path)
+
+For **plan-file stem mode** (Step 4a wrote a `.approved` marker), display:
+
+```
+Clancy — Approve Plan (local)
+
+✅ Approved {stem}
+   Marker: .clancy/plans/{stem}.approved
+   sha256: {first 12 hex chars}…
+
+Next: /clancy:implement-from .clancy/plans/{stem}.md
+
+"Book 'em, Lou."
+```
+
+**Conditional Brief line:** if Step 4b actually resolved AND updated the brief marker (i.e. the `**Brief:**`/`**Row:**` headers were present, the marker regex matched, and the write succeeded), insert this line between `sha256:` and the blank line above `Next:`:
+
+```
+   Brief:  .clancy/briefs/{brief}.md (row #{N} marked approved)
+```
+
+Do NOT print the Brief line when Step 4b warned and skipped (missing headers, no matching marker, or write error). In that case, also print the warning that Step 4b emitted under the success block but do not change the exit status — the plan IS approved regardless of whether the brief marker was updated.
+
+Append to `.clancy/progress.txt`:
+
+```
+YYYY-MM-DD HH:MM | {stem} | LOCAL_APPROVE_PLAN | sha256={first 12 hex}
+```
+
+The `LOCAL_APPROVE_PLAN` token mirrors the `LOCAL_PLAN` / `LOCAL_REVISED` convention used by `/clancy:plan --from` (see [`plan.md` Step 6](./plan.md)). PR 8's `/clancy:implement-from` does NOT scan progress.txt for approval state — it reads the `.clancy/plans/{stem}.approved` marker directly. The log entry is for human audit only.
+
+---
+
+## Notes
+
+- This command only appends -- it never overwrites the existing ticket description
+- If the ticket has multiple plan comments, the most recent one is used
+- The plan content is taken verbatim from the comment -- no regeneration
+- Step 3b checks for existing plans in the description to prevent accidental duplication
+- The ticket key is case-insensitive -- accept `PROJ-123`, `proj-123`, or `#123` (GitHub)
+- Step 5b edits the plan comment with an approval note -- this is best-effort and does not block the workflow
+- Step 6 transitions the ticket to the implementation queue -- this is best-effort and board-specific
+- The `## Clancy Implementation Plan` marker in comments is used by both `/clancy:plan` (to detect existing plans) and `/clancy:approve-plan` (to find the plan to promote)