@cleocode/cleo 2026.5.106 → 2026.5.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "v2026.5.106",
+  "version": "2026.5.107",
   "description": "CLEO CLI — the assembled product consuming @cleocode/core",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -30,18 +30,18 @@
     "tree-sitter-rust": "0.23.1",
     "tree-sitter-typescript": "^0.23.2",
     "yaml": "^2.8.3",
-    "@cleocode/animations": "v2026.5.106",
-    "@cleocode/cant": "v2026.5.106",
-    "@cleocode/lafs": "v2026.5.106",
-    "@cleocode/contracts": "v2026.5.106",
-    "@cleocode/caamp": "v2026.5.106",
-    "@cleocode/nexus": "v2026.5.106",
-    "@cleocode/runtime": "v2026.5.106",
-    "@cleocode/playbooks": "v2026.5.106",
-    "@cleocode/paths": "v2026.5.106"
+    "@cleocode/animations": "2026.5.107",
+    "@cleocode/caamp": "2026.5.107",
+    "@cleocode/cant": "2026.5.107",
+    "@cleocode/contracts": "2026.5.107",
+    "@cleocode/lafs": "2026.5.107",
+    "@cleocode/paths": "2026.5.107",
+    "@cleocode/runtime": "2026.5.107",
+    "@cleocode/playbooks": "2026.5.107",
+    "@cleocode/nexus": "2026.5.107"
   },
   "peerDependencies": {
-    "@cleocode/core": "v2026.5.106"
+    "@cleocode/core": "2026.5.107"
   },
   "peerDependenciesMeta": {
     "@cleocode/core": {

package/templates/HANDOFF-REDIRECT-STUB.md

@@ -1,37 +0,0 @@
-# STALE — DO NOT READ THIS FILE FOR STATE
-
-**This file is deprecated as canonical state per T1593 (shipped in v2026.4.157).**
-
-The current state of the project lives in **TASKS + BRAIN** — never in markdown.
-
-## What you must do instead
-
-```bash
-cleo briefing
-```
-
-That command returns:
-- The structured `lastSession.handoff.note` — guaranteed current, written at session-end
-- `nextTasks` ranked by score — the system's recommendation for what to work on
-- `blockedTasks` showing dependency chains — what cannot start yet
-- `memoryContext` with relevant BRAIN observations
-- `activeEpics` with completion percentages
-
-## If you are seeing this and you ALREADY started reading instead of running `cleo briefing`
-
-Stop. Run `cleo briefing`. Then `cleo memory find "IRONCLAD-ROADMAP"` if needed.
-The system has explicit instructions for the next orchestrator that do NOT live in this file.
-
-## Verification
-
-Run any of these to verify state from the canonical source:
-
-```bash
-cleo briefing                        # next-session handoff (canonical)
-cleo dash                            # task counts
-cleo memory find "roadmap"           # roadmap observations in BRAIN
-```
-
----
-
-*This file deliberately contains no state. Reading it cannot mislead you. Run `cleo briefing`.*

package/templates/hooks/commit-msg

@@ -1,213 +0,0 @@
-#!/bin/sh
-# CLEO_MANAGED_HOOK v1
-# T1588 — project-agnostic T-ID enforcement for every commit subject.
-# T1608 — diff-scope validation: warn when staged files drift from task scope.
-#
-# Rule: subject MUST contain `T<digits>` somewhere, OR be a merge/revert
-# (which preserves the git merge --no-ff path established in T1587 and the
-# stock `git revert` flow).
-#
-# Diff-scope check (T1608): if `cleo` is on the PATH and the referenced task
-# has a non-empty files[] array, compare the staged diff against that scope.
-# If >50 % of staged files fall outside the task's declared scope, emit a
-# WARNING on stderr — but still exit 0 (hard-block is intentionally omitted
-# to avoid rejecting valid refactors; the warning feeds audit tooling).
-#
-# Override: `git commit --no-verify` bypasses (standard git behaviour).
-# A best-effort audit of `--no-verify` lives in the git shim (see T1591) —
-# hooks themselves cannot observe `--no-verify`.
-#
-# This script is POSIX `/bin/sh` only (no bash/zsh-isms). It MUST work in
-# any environment cleo init runs in: node-less projects, Rust, Python,
-# bare repos, etc. Do not introduce node/pnpm dependencies here.
-# The diff-scope check degrades gracefully when cleo or python3 is absent.
-set -e
-
-MSG_FILE="$1"
-if [ -z "$MSG_FILE" ] || [ ! -f "$MSG_FILE" ]; then
-  echo "cleo commit-msg hook: missing message file argument" >&2
-  exit 1
-fi
-
-# First non-empty, non-comment line = the subject.
-SUBJECT=""
-while IFS= read -r line || [ -n "$line" ]; do
-  case "$line" in
-    '#'*) continue ;;
-  esac
-  trimmed=$(printf '%s' "$line" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
-  if [ -n "$trimmed" ]; then
-    SUBJECT="$trimmed"
-    break
-  fi
-done < "$MSG_FILE"
-
-if [ -z "$SUBJECT" ]; then
-  echo "cleo commit-msg hook: empty commit subject — refusing." >&2
-  exit 1
-fi
-
-# Bypass merge / revert / fixup / squash / amend-only metadata commits.
-case "$SUBJECT" in
-  'Merge '*) exit 0 ;;
-  'Revert '*) exit 0 ;;
-  'fixup! '*) exit 0 ;;
-  'squash! '*) exit 0 ;;
-  'amend! '*) exit 0 ;;
-esac
-
-# Match `T` followed by 1+ digits anywhere in the subject.
-# POSIX BRE — `[0-9][0-9]*` is `\d+` equivalent.
-if ! printf '%s' "$SUBJECT" | grep -Eq 'T[0-9]+'; then
-  cat >&2 <<EOF
-cleo commit-msg hook: commit subject is missing a task ID.
-
-  subject: $SUBJECT
-
-Every commit MUST reference at least one CLEO task. Examples:
-
-  feat(T1588): ship POSIX commit-msg hook
-  T1588 — wire hooks-install into cleo init
-  fix: T1588 typo
-
-Override (audited via git shim — see T1591):
-
-  git commit --no-verify
-
-EOF
-  exit 1
-fi
-
-# -----------------------------------------------------------------------
-# T1608: diff-scope validation (warning-only — exits 0 on all paths below)
-# -----------------------------------------------------------------------
-# Extract the first T-ID from the subject (e.g. "feat(T1608): ..." → T1608).
-TASK_ID=$(printf '%s' "$SUBJECT" | grep -Eo 'T[0-9]+' | head -n 1)
-
-# Resolve cleo binary: prefer explicit CLEO_BIN env, then PATH lookup.
-CLEO_BIN="${CLEO_BIN:-}"
-if [ -z "$CLEO_BIN" ]; then
-  CLEO_BIN=$(command -v cleo 2>/dev/null || true)
-fi
-
-if [ -z "$CLEO_BIN" ] || [ ! -x "$CLEO_BIN" ] || [ -z "$TASK_ID" ]; then
-  # cleo not available or no T-ID extracted — skip diff-scope check.
-  exit 0
-fi
-
-# Resolve python3 (used for JSON parsing — lightweight, no npm required).
-PYTHON3_BIN=$(command -v python3 2>/dev/null || true)
-if [ -z "$PYTHON3_BIN" ]; then
-  # python3 unavailable — skip diff-scope check gracefully.
-  exit 0
-fi
-
-# Fetch task.files[] via cleo show. Suppress errors (task may not exist
-# in cleo DB for the target project; non-zero cleo exit → skip silently).
-TASK_JSON=$("$CLEO_BIN" show "$TASK_ID" 2>/dev/null) || true
-if [ -z "$TASK_JSON" ]; then
-  exit 0
-fi
-
-# Extract the files[] array as one path per line via python3 -c.
-# Using -c avoids the stdin-conflict that arises with heredoc + pipe.
-TASK_FILES=$("$PYTHON3_BIN" -c "
-import json, sys
-try:
-    d = json.loads(sys.argv[1])
-    files = d.get('data', {}).get('task', {}).get('files', [])
-    print('\n'.join(f for f in files if f))
-except Exception:
-    pass
-" "$TASK_JSON" 2>/dev/null) || true
-
-if [ -z "$TASK_FILES" ]; then
-  # Task has no files[] scope declared — nothing to validate against.
-  exit 0
-fi
-
-# Get staged file list (diff-scope is only meaningful for staged changes).
-# git diff --cached exits 0 even when empty, so this is always safe.
-STAGED_FILES=$(git diff --cached --name-only 2>/dev/null) || true
-
-if [ -z "$STAGED_FILES" ]; then
-  # No staged files (e.g. amend of message only) — skip check.
-  exit 0
-fi
-
-# Count staged files and how many are in-scope (path prefix or exact match).
-# A staged file is "in-scope" when it matches any task file path OR any
-# task file path is a path-prefix of the staged file (directory scope).
-# We delegate the maths to python3 to avoid shell integer-division quirks.
-# Both TASK_FILES and STAGED_FILES are passed as argv to avoid stdin conflict.
-DRIFT_RESULT=$("$PYTHON3_BIN" -c "
-import sys
-
-# argv[1] = newline-separated task files; argv[2] = newline-separated staged files
-task_files = [f.strip() for f in sys.argv[1].splitlines() if f.strip()]
-staged = [f.strip() for f in sys.argv[2].splitlines() if f.strip()]
-
-def in_scope(staged_path, task_files):
-    for tf in task_files:
-        # Exact match.
-        if staged_path == tf:
-            return True
-        # task file is a directory prefix of the staged file.
-        if staged_path.startswith(tf.rstrip('/') + '/'):
-            return True
-        # staged file is a directory prefix of a task file (task file
-        # is deeper; e.g. task scope is src/foo.ts, staged is src/).
-        if tf.startswith(staged_path.rstrip('/') + '/'):
-            return True
-    return False
-
-if not staged or not task_files:
-    print('SKIP')
-    sys.exit(0)
-
-out_of_scope = [f for f in staged if not in_scope(f, task_files)]
-total = len(staged)
-drift_count = len(out_of_scope)
-drift_pct = (drift_count * 100) // total if total > 0 else 0
-
-print('TOTAL=' + str(total))
-print('DRIFT_COUNT=' + str(drift_count))
-print('DRIFT_PCT=' + str(drift_pct))
-for f in out_of_scope:
-    print('OUT=' + f)
-" "$TASK_FILES" "$STAGED_FILES" 2>/dev/null) || true
-
-# Parse drift result.
-if [ -z "$DRIFT_RESULT" ] || printf '%s' "$DRIFT_RESULT" | grep -q '^SKIP$'; then
-  exit 0
-fi
-
-DRIFT_PCT=$(printf '%s' "$DRIFT_RESULT" | grep '^DRIFT_PCT=' | sed 's/^DRIFT_PCT=//')
-TOTAL=$(printf '%s' "$DRIFT_RESULT" | grep '^TOTAL=' | sed 's/^TOTAL=//')
-DRIFT_COUNT=$(printf '%s' "$DRIFT_RESULT" | grep '^DRIFT_COUNT=' | sed 's/^DRIFT_COUNT=//')
-OUT_FILES=$(printf '%s' "$DRIFT_RESULT" | grep '^OUT=' | sed 's/^OUT=//')
-
-# Threshold: warn when drift exceeds 50 % (i.e. drift_pct > 50).
-THRESHOLD=50
-if [ -n "$DRIFT_PCT" ] && [ "$DRIFT_PCT" -gt "$THRESHOLD" ] 2>/dev/null; then
-  cat >&2 <<EOF
-cleo commit-msg hook [T1608]: diff-scope drift WARNING
-
-  Task   : $TASK_ID
-  Staged : $TOTAL file(s) — $DRIFT_COUNT ($DRIFT_PCT%) are outside $TASK_ID scope
-
-  Out-of-scope staged files:
-$(printf '%s' "$OUT_FILES" | sed 's/^/    /')
-
-  Task scope (files[]):
-$(printf '%s' "$TASK_FILES" | sed 's/^/    /')
-
-  This is a WARNING, not a hard block. The commit will proceed.
-  To silence: ensure staged files align with the task scope,
-  or add the files to the task via \`cleo update $TASK_ID --files ...\`.
-
-EOF
-  # Exit 0 — warning only.
-fi
-
-exit 0

package/templates/hooks/pre-push

@@ -1,87 +0,0 @@
-#!/bin/sh
-# CLEO_MANAGED_HOOK v1
-# T1588 — project-agnostic T-ID enforcement for every commit being pushed.
-#
-# git invokes this with `<remote> <url>` as args and feeds ref updates on
-# stdin: `<local-ref> <local-sha> <remote-ref> <remote-sha>` (one per line).
-#
-# For each new commit being pushed (commits in `local-sha` that are NOT
-# already in any remote ref), require a T-ID in the subject. Same allow-
-# list as commit-msg: merge / revert / fixup / squash / amend.
-#
-# Override: `git push --no-verify` (standard git override).
-#
-# T1595:reconcile-extension-point
-# Pre-push reconcile gate hooks here (see T1595 worker).
-# Reserved range below — DO NOT remove these markers; T1595 extends here.
-# T1595:reconcile-extension-point-end
-#
-# POSIX `/bin/sh` only. No node/pnpm dependency.
-set -e
-
-ZERO_SHA="0000000000000000000000000000000000000000"
-EMPTY_TREE_SHA=""
-FAIL=0
-FAIL_LOG=""
-
-check_subject() {
-  subject="$1"
-  case "$subject" in
-    'Merge '*) return 0 ;;
-    'Revert '*) return 0 ;;
-    'fixup! '*) return 0 ;;
-    'squash! '*) return 0 ;;
-    'amend! '*) return 0 ;;
-  esac
-  if printf '%s' "$subject" | grep -Eq 'T[0-9]+'; then
-    return 0
-  fi
-  return 1
-}
-
-# Read each ref-update line from stdin.
-while read -r local_ref local_sha remote_ref remote_sha; do
-  # Branch deletion (push :branch) — nothing to validate.
-  if [ "$local_sha" = "$ZERO_SHA" ]; then
-    continue
-  fi
-
-  if [ "$remote_sha" = "$ZERO_SHA" ]; then
-    # New branch: validate every commit reachable from local_sha that is
-    # NOT reachable from any other remote ref.
-    range="$local_sha --not --remotes"
-  else
-    range="$remote_sha..$local_sha"
-  fi
-
-  # Subject extraction: %s = subject. NUL-delimit for safety.
-  # shellcheck disable=SC2086
-  commits=$(git rev-list $range 2>/dev/null || true)
-  for sha in $commits; do
-    subject=$(git log -1 --pretty=%s "$sha" 2>/dev/null || true)
-    if [ -z "$subject" ]; then
-      continue
-    fi
-    if ! check_subject "$subject"; then
-      FAIL=1
-      FAIL_LOG="${FAIL_LOG}  ${sha}  ${subject}
-"
-    fi
-  done
-done
-
-if [ "$FAIL" -ne 0 ]; then
-  cat >&2 <<EOF
-cleo pre-push hook: refusing push — commits are missing task IDs.
-
-${FAIL_LOG}
-Every commit MUST reference at least one CLEO task (e.g. \`T1588\`).
-Fix the subjects (\`git rebase -i\` + reword), or override with:
-
-  git push --no-verify
-
-EOF
-  exit 1
-fi
-
-exit 0

package/templates/hooks/pre-push.t1595-extension.sh

@@ -1,140 +0,0 @@
-#!/bin/sh
-# T1595 — pre-push reconcile gate (extension)
-#
-# This file is the reconcile-gate extension for the project's pre-push
-# hook. T1588 will produce a unified pre-push hook that contains a
-# sentinel block:
-#
-#   # T1595:reconcile-extension-point
-#   # Pre-push reconcile gate hooks here (see T1595 worker)
-#
-# When T1588 lands, the contents of `reconcile_gate()` below MUST be
-# inlined at that sentinel. Until then, this file is sourced as-is by
-# any pre-push hook that wants the reconcile gate (see installer in
-# `packages/core/src/hooks/install-pre-push.ts`, future).
-#
-# CONTRACT
-#   - POSIX shell (`/bin/sh`); no bashisms.
-#   - Reads pending tag from `git tag --sort=-v:refname | head -1`
-#     (tag-shape agnostic — works for CalVer or SemVer).
-#   - Calls `cleo reconcile release --tag <pending> --dry-run --json`
-#     and parses the aggregate `reconciled` count.
-#   - Drift > 0 → exit 1 with task-ID list.
-#   - Drift == 0 → return 0.
-#   - Override: env `CLEO_ALLOW_DRIFT_PUSH=1` bypasses the gate AND
-#     appends an audit entry to
-#     `${XDG_DATA_HOME:-$HOME/.local/share}/cleo/audit/drift-push-bypass.jsonl`.
-#   - Project-agnostic: no hardcoded branch name; default branch is
-#     resolved via `git symbolic-ref refs/remotes/origin/HEAD` when
-#     needed.
-#
-# EXIT CODES
-#   0  — no drift, push allowed
-#   1  — drift detected, push refused (or cleo CLI unavailable in
-#        strict mode; see CLEO_RECONCILE_STRICT below)
-#
-# CONFIGURATION (env)
-#   CLEO_ALLOW_DRIFT_PUSH=1   bypass the gate (audited)
-#   CLEO_RECONCILE_STRICT=1   if `cleo` CLI is missing, refuse push
-#                             (default: warn-and-allow so first-time
-#                              clones without cleo installed still work)
-#   CLEO_RECONCILE_BIN=<path> override the cleo binary path (testing)
-
-set -eu
-
-reconcile_gate() {
-  # Locate cleo CLI ------------------------------------------------------
-  cleo_bin="${CLEO_RECONCILE_BIN:-cleo}"
-  if ! command -v "$cleo_bin" >/dev/null 2>&1; then
-    if [ "${CLEO_RECONCILE_STRICT:-0}" = "1" ]; then
-      echo "ERROR: cleo CLI not found on PATH (strict mode)" >&2
-      echo "       install cleo or unset CLEO_RECONCILE_STRICT" >&2
-      return 1
-    fi
-    # Soft-fail: warn but allow push. Avoids blocking fresh clones.
-    echo "warn: cleo CLI not found; skipping reconcile gate" >&2
-    return 0
-  fi
-
-  # Resolve the pending release tag -------------------------------------
-  # We use the most recent tag as the "pending" anchor. Reconcile is
-  # project-agnostic — it walks tasks released_in this tag's range
-  # regardless of CalVer vs SemVer shape.
-  pending_tag="$(git tag --sort=-v:refname 2>/dev/null | head -n 1 || true)"
-  if [ -z "$pending_tag" ]; then
-    # No tags yet → no release to reconcile.
-    return 0
-  fi
-
-  # Override path -------------------------------------------------------
-  if [ "${CLEO_ALLOW_DRIFT_PUSH:-0}" = "1" ]; then
-    audit_dir="${XDG_DATA_HOME:-$HOME/.local/share}/cleo/audit"
-    mkdir -p "$audit_dir"
-    audit_log="$audit_dir/drift-push-bypass.jsonl"
-    ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-    user="${USER:-${LOGNAME:-unknown}}"
-    repo="$(git rev-parse --show-toplevel 2>/dev/null || echo unknown)"
-    head_sha="$(git rev-parse HEAD 2>/dev/null || echo unknown)"
-    # Write a JSONL line. Stay project-agnostic: no jq dependency.
-    printf '{"ts":"%s","user":"%s","repo":"%s","head":"%s","tag":"%s","reason":"CLEO_ALLOW_DRIFT_PUSH=1"}\n' \
-      "$ts" "$user" "$repo" "$head_sha" "$pending_tag" >> "$audit_log"
-    echo "warn: pre-push reconcile gate bypassed (CLEO_ALLOW_DRIFT_PUSH=1)" >&2
-    echo "      audit: $audit_log" >&2
-    return 0
-  fi
-
-  # Run reconcile in dry-run JSON mode ----------------------------------
-  # We swallow non-zero exit codes from the CLI here because reconcile
-  # exits 2 when drift exists; we want to read the JSON regardless.
-  json_out="$("$cleo_bin" reconcile release --tag "$pending_tag" --dry-run --json 2>/dev/null || true)"
-  if [ -z "$json_out" ]; then
-    if [ "${CLEO_RECONCILE_STRICT:-0}" = "1" ]; then
-      echo "ERROR: cleo reconcile release returned empty output (strict mode)" >&2
-      return 1
-    fi
-    echo "warn: cleo reconcile release returned empty output; skipping gate" >&2
-    return 0
-  fi
-
-  # Parse the aggregate `reconciled` count without jq.
-  # The InvariantReport JSON has a top-level `"reconciled": N` integer.
-  # We grep the first such key (top-level always emitted before per-result
-  # entries). Per-result entries are nested under `results[*].details`,
-  # so the first match is the aggregate.
-  drift_count="$(printf '%s' "$json_out" \
-    | grep -o '"reconciled"[[:space:]]*:[[:space:]]*[0-9]\+' \
-    | head -n 1 \
-    | grep -o '[0-9]\+' \
-    || true)"
-  drift_count="${drift_count:-0}"
-
-  if [ "$drift_count" -gt 0 ] 2>/dev/null; then
-    echo "ERROR: pre-push reconcile gate detected drift" >&2
-    echo "       tag: $pending_tag" >&2
-    echo "       drift count: $drift_count shipped-but-pending task(s)" >&2
-    # Best-effort: extract reconciled task IDs from results[*].details.reconciled
-    # arrays. Strings look like "T1411" (project-agnostic prefix).
-    drifted_ids="$(printf '%s' "$json_out" \
-      | tr -d '\n' \
-      | grep -o '"reconciled"[[:space:]]*:[[:space:]]*\[[^]]*\]' \
-      | grep -o '"[A-Za-z][A-Za-z0-9_-]*"' \
-      | sort -u \
-      | tr '\n' ' ' \
-      || true)"
-    if [ -n "$drifted_ids" ]; then
-      echo "       drifted tasks: $drifted_ids" >&2
-    fi
-    echo "" >&2
-    echo "Refuse push: run 'cleo reconcile release --tag $pending_tag' to" >&2
-    echo "reconcile, or set CLEO_ALLOW_DRIFT_PUSH=1 (audited bypass)." >&2
-    return 1
-  fi
-
-  return 0
-}
-
-# When sourced from the unified pre-push hook the function is invoked
-# at the sentinel point. When run standalone (testing), invoke directly.
-if [ "${T1595_SOURCED:-0}" != "1" ]; then
-  reconcile_gate
-fi

package/templates/workflows/README.md

@@ -1,157 +0,0 @@
-# CLEO GitHub Actions workflow templates
-
-This directory contains CLEO's templated GitHub Actions workflows for the
-release pipeline defined in
-`.cleo/rcasd/T9345/research/SPEC-T9345-release-pipeline-v2.md`. Templates
-are project-agnostic: they ship with `{{PLACEHOLDER}}` markers that are
-resolved at scaffold time by `cleo init --workflows` (T9531) against the
-local `.cleo/project-context.json` and the ADR-061 tool resolver.
-
-## Template files
-
-| Template                          | SPEC section | Purpose                                                |
-|-----------------------------------|--------------|--------------------------------------------------------|
-| `release-prepare.yml.tmpl`        | §5.1         | Cut release branch, bump version, open bump-PR.        |
-| `release-publish.yml.tmpl`        | §5.2         | Publish + tag once the bump-PR is merged.              |
-| `release-fanout.yml.tmpl`         | §5.3         | Best-effort post-publish fanout (docs, docker, etc.).  |
-| `release-rollback.yml.tmpl`       | §5.4         | Rollback workflow (revert PR + npm deprecate + reconcile). |
-
-## Template contract
-
-- Templates MUST use `{{PLACEHOLDER}}` markers compatible with simple regex
-  substitution (`s/{{NAME}}/value/g`). They MUST NOT use Mustache, Handlebars,
-  or any nested-syntax templating engine — the scaffold step relies on
-  deterministic, single-pass regex replacement so a stale template can be
-  diffed cleanly against a re-render.
-- Placeholder names MUST be `UPPER_SNAKE_CASE` wrapped in double braces.
-- Templates MUST be ASCII-only outside of strings.
-- Templates MUST pass `actionlint` after substitution. The
-  `release-prepare-render.test.ts` snapshot test renders with sample values
-  and (if `actionlint` is on `PATH`) pipes the output through `actionlint -`
-  via `child_process.execSync`.
-
-## Placeholders
-
-All four templates draw from the same placeholder vocabulary. Unused
-placeholders for a given template are silently ignored by the scaffolder.
-
-| Placeholder           | Source                                                 | Default                              | Example                              |
-|-----------------------|--------------------------------------------------------|--------------------------------------|--------------------------------------|
-| `{{NODE_VERSION}}`    | `.cleo/project-context.json` `node.version`            | `22.x`                               | `"22.x"`                             |
-| `{{INSTALL_CMD}}`     | ADR-061 archetype defaults (`primaryType`-specific)    | `pnpm install --frozen-lockfile`     | `pnpm install --frozen-lockfile`     |
-| `{{LINT_CMD}}`        | ADR-061 `tool:lint` resolution                         | `pnpm run lint`                      | `pnpm biome ci .`                    |
-| `{{TYPECHECK_CMD}}`   | ADR-061 `tool:typecheck` resolution                    | `pnpm run typecheck`                 | `pnpm run typecheck`                 |
-| `{{TEST_CMD}}`        | ADR-061 `tool:test` resolution                         | `pnpm run test`                      | `pnpm run test`                      |
-| `{{BUILD_CMD}}`       | ADR-061 `tool:build` resolution                        | `pnpm run build`                     | `pnpm run build`                     |
-| `{{BRANCH_PREFIX}}`   | `release.branchPrefix` in `.cleo/config.json`          | `release`                            | `release`                            |
-| `{{PR_LABEL}}`        | `release.prLabel` in `.cleo/config.json`               | `release`                            | `release`                            |
-| `{{NPM_PUBLISH_CMD}}` | `release.npmPublishCmd` in `.cleo/config.json`         | `pnpm publish --access public --tag latest` | `pnpm publish -r --access public --tag latest` |
-| `{{PUBLISHERS}}`      | `release.publishers` in `.cleo/config.json`            | `npm`                                | `npm cargo`                          |
-| `{{DOCS_BUILD_CMD}}`  | `release.fanout.docsBuildCmd` in `.cleo/config.json`   | `pnpm run docs:build`                | `pnpm --filter @cleocode/docs run build` |
-| `{{ENABLE_DOCS_DEPLOY}}`     | `release.fanout.docsDeploy` in `.cleo/config.json`     | `false`                  | `true`                               |
-| `{{ENABLE_DOCKER_RETAG}}`    | `release.fanout.dockerRetag` in `.cleo/config.json`    | `false`                  | `true`                               |
-| `{{ENABLE_SENTINEL_NOTIFY}}` | `release.fanout.sentinelNotify` in `.cleo/config.json` | `false`                  | `true`                               |
-| `{{ENABLE_STUDIO_DEPLOY}}`   | `release.fanout.studioDeploy` in `.cleo/config.json`   | `false`                  | `true`                               |
-| `{{ENABLE_NIGHTLY_TRIGGER}}` | `release.fanout.nightlyTrigger` in `.cleo/config.json` | `false`                  | `true`                               |
-| `{{DOCKER_IMAGE}}`    | `release.fanout.dockerImage` in `.cleo/config.json`    | *(none — required if `dockerRetag=true`)* | `cleocode/cleo`                |
-| `{{DOCKER_HUB_USER}}` | `release.fanout.dockerHubUser` in `.cleo/config.json`  | *(none — required if `dockerRetag=true`)* | `cleocode`                     |
-| `{{SENTINEL_WEBHOOK_URL}}` | `release.fanout.sentinelWebhookUrl` in `.cleo/config.json` | *(none — required if `sentinelNotify=true`)* | `https://sentinel.example.com/hooks/release` |
-| `{{STUDIO_DEPLOY_HOOK}}` | `release.fanout.studioDeployHook` in `.cleo/config.json` | *(none — required if `studioDeploy=true`)*   | `https://studio.example.com/deploy`        |
-| `{{NPM_PACKAGES}}`    | `release.rollback.npmPackages` in `.cleo/config.json`  | *(none — required if `PUBLISHERS` contains `npm`)*   | `@cleocode/cleo @cleocode/core`            |
-| `{{CARGO_CRATES}}`    | `release.rollback.cargoCrates` in `.cleo/config.json`  | *(none — required if `PUBLISHERS` contains `cargo`)* | `cleo-core cleo-cli`                       |
-
-Source precedence (highest first):
-
-1. Explicit override in `.cleo/project-context.json` (ADR-061 §1).
-2. Project archetype default keyed on `primaryType` (e.g. `node` → `pnpm`,
-   `rust` → `cargo`, `python` → `uv`).
-3. Hard-coded fallback in the scaffolder.
-
-## GitHub permissions required per template
-
-| Template                     | `contents`      | `pull-requests` | `id-token`            | `packages`         | Other            |
-|------------------------------|-----------------|------------------|----------------------|--------------------|------------------|
-| `release-prepare.yml.tmpl`   | `write`         | `write`          | `write` (signed tags) | (MUST NOT request) | —                |
-| `release-publish.yml.tmpl`   | `write` (tag)   | `read`           | `write` (OIDC)        | `write` (publish job only) | —        |
-| `release-fanout.yml.tmpl`    | `read`          | —                | `write` (Pages, docs job only)* | —        | `pages: write`*  |
-| `release-rollback.yml.tmpl`  | `write` (revert + tag delete) | `write`          | —                     | `write` (npm deprecate) | —          |
-
-*Per-job — only granted to the job that needs it.
-
-## Required secrets
-
-| Template                     | Required secrets        | Optional secrets                                  |
-|------------------------------|-------------------------|---------------------------------------------------|
-| `release-prepare.yml.tmpl`   | `GITHUB_TOKEN` (auto)   | *(none)* — MUST NOT require `NPM_TOKEN` (R-210)   |
-| `release-publish.yml.tmpl`   | `GITHUB_TOKEN`, `NPM_TOKEN`, `ANTHROPIC_API_KEY` | `CARGO_TOKEN`, `PYPI_TOKEN`, `DOCKER_HUB_TOKEN` |
-| `release-fanout.yml.tmpl`    | `GITHUB_TOKEN` (auto)   | `DOCKER_HUB_TOKEN` (if `dockerRetag=true`), `SENTINEL_TOKEN` (if `sentinelNotify=true`), `STUDIO_DEPLOY_TOKEN` (if `studioDeploy=true`) |
-| `release-rollback.yml.tmpl`  | `GITHUB_TOKEN` (auto), `NPM_TOKEN` (if `PUBLISHERS` contains `npm`) | `CARGO_TOKEN` (if `PUBLISHERS` contains `cargo`) |
-
-## Scaffolding workflow
-
-```bash
-# Render the templates against the local project, writing to .github/workflows/.
-cleo init --workflows
-
-# Re-render after editing project-context.json or release config.
-cleo init --workflows --force
-```
-
-The scaffolder reads each `*.yml.tmpl` file in this directory, performs
-regex substitution against the placeholder vocabulary above, validates the
-result with `actionlint`, and writes the rendered YAML to
-`<project>/.github/workflows/<basename>.yml`. Existing files are NOT
-overwritten without `--force`.
-
-## Extending without forking
-
-Per SPEC R-260, downstream projects MAY layer customizations onto the
-rendered workflows via a sibling `.github/workflows/<basename>.overrides.yml`
-file (planned: `.workflow-overrides.yml` at repo root for cross-template
-overrides). The scaffolder merges overrides as a final pass; conflicts at
-the same YAML key path resolve to the override.
-
-Override examples (illustrative — full schema lands with T9531):
-
-```yaml
-# .github/workflows/release-prepare.overrides.yml
-jobs:
-  preflight:
-    steps:
-      - name: Project-specific cache warm
-        run: ./scripts/warm-cache.sh
-        timeout-minutes: 3
-```
-
-Overrides MUST NOT remove or relax any RFC2119 invariant from
-`SPEC-T9345-release-pipeline-v2.md`. The scaffolder rejects override files
-that drop required `timeout-minutes`, modify `concurrency.group`, or strip
-declared permissions.
-
-## Cross-references
-
-- SPEC: `.cleo/rcasd/T9345/research/SPEC-T9345-release-pipeline-v2.md`
-  - §5.1 → `release-prepare.yml.tmpl` *(T9532, landed)*
-  - §5.2 → `release-publish.yml.tmpl` *(T9533, landed)*
-  - §5.3 → `release-fanout.yml.tmpl` *(T9534, landed)*
-  - §5.4 → `release-rollback.yml.tmpl` *(T9535, current)*
-- ADR-061 (tool resolver): governs `tool:*` placeholder resolution.
-- ADR-073 (release pipeline v2): umbrella architectural decision.
-- T9531: `cleo init --workflows` scaffold command (consumes these templates).
-- T9532: `release-prepare.yml.tmpl` + README skeleton + snapshot test.
-- T9533: `release-publish.yml.tmpl` + README placeholders + snapshot test
-  (eliminates F6 tag-on-pre-merge-SHA race by construction).
-- T9534: `release-fanout.yml.tmpl` + 11 fanout placeholders + snapshot test
-  (five independent best-effort jobs gated on env toggles, every job
-  carries `continue-on-error: true` so fanout failures cannot mark the
-  release as failed; fanout jobs MUST NOT be required status checks per
-  R-244).
-- T9535: `release-rollback.yml.tmpl` + rollback placeholders (`NPM_PACKAGES`,
-  `CARGO_CRATES`) + snapshot test (current task — `workflow_dispatch`-only
-  rollback with 4 jobs `validate` → `revert` → `deprecate` →
-  `reconcile-rollback`. The `revert` job opens a revert PR against `main`
-  via `gh pr create --label rollback` — NEVER pushes directly to `main`
-  per ADR-065. The `deprecate` job is best-effort
-  (`continue-on-error: true`); reconcile runs whenever validate succeeded
-  so the provenance graph records the operator's intent even if a
-  downstream side-effect failed).