@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/product-roadmap/scripts/roadmap-reconcile.sh

@@ -0,0 +1,327 @@
+#!/usr/bin/env bash
+
+# roadmap-reconcile.sh — READ-ONLY roadmap↔GitHub reconcile module.
+#
+# Shared core behind `product-roadmap validate` (drift report) and `next`
+# (advisory next-action). Part of feat-roadmap-program-layer's report-only
+# design: this module NEVER writes to roadmap.md or any file. When drift is
+# found, remediation routes through the existing cron-roadmap-review.ts (the
+# sole writer, via reviewed fix PRs) — see ADR-033 / ADR-054.
+#
+# Verdict vocabulary mirrors cron-roadmap-review.ts's prompt:
+#   STALE_STATUS    — roadmap count cell disagrees with the live milestone
+#   MISSING_ISSUE   — a roadmap Phase row resolves to no GitHub milestone
+#   EMPTY_MILESTONE — a milestone has 0 open AND 0 closed issues
+#
+# Public functions (sourced by plugins/soleur/test/roadmap-reconcile.test.sh):
+#   extract_phase_counts          stdin: roadmap md  -> "N|open|closed" per Phase row
+#   reconcile_counts ROADMAP MS   files: roadmap, milestones-json -> verdict lines
+#   pick_next_action ISSUES       file: open-issues-json -> CODEABLE|OPERATOR|NONE line
+#   pick_phase MS                 file: milestones-json -> "N|title" of the live phase, or empty
+#   filter_frontier ISSUES        file: open-issues-json -> {frontier,blocked,claimed}
+#
+# pick_phase depends on milestones being titled `Phase N: ...`. The frontier is a
+# phase's open issues with no open blocker (GitHub-native "blocked by" edges) and
+# no assignee; it needs `gh` >= 2.94.0, the first release exposing `blockedBy`.
+#
+# Milestone↔phase is NOT 1:1 (the Phase-N milestone also holds internal-tooling
+# issues not on roadmap rows); reconcile keys strictly off the Current-State
+# count cell, never feature-row tallies.
+
+set -euo pipefail
+
+ROADMAP_FILE="${ROADMAP_FILE:-knowledge-base/product/roadmap.md}"
+
+# Labels that mark an issue as codeable (an agent can build it via /soleur:go).
+# Deliberately narrow: anything else (recruitment, interviews, research, marketing,
+# ops, chores) classifies as an operator action. Under-classifying to OPERATOR is
+# the safe failure for an advisory tool — it only ever NAMES the item, never wrongly
+# tells the founder to /soleur:go a non-codeable task.
+CODEABLE_LABELS='"domain/engineering","type/bug","type/feature","type/refactor"'
+
+# A non-engineering domain-leader label means the work is operator-driven (marketing,
+# legal, ops, sales, finance, support, product) — it OVERRIDES a codeable type/* label.
+# Caught by dogfooding: #2603 ("Publish a case study") is type/feature + domain/marketing
+# and must classify OPERATOR, not CODEABLE — never tell the founder to /soleur:go it.
+OPERATOR_DOMAIN_LABELS='"domain/marketing","domain/legal","domain/operations","domain/sales","domain/finance","domain/support","domain/product"'
+
+# extract_phase_counts: read roadmap markdown on stdin, emit "N|open|closed"
+# for each `| Phase N (...) |` row in the `## Current State` table that carries
+# an "X open, Y closed" count. Rows without counts (prose, Beta users) are skipped.
+extract_phase_counts() {
+  awk '
+    /^## Current State/ { inblock = 1; next }
+    inblock && /^## / { inblock = 0 }
+    inblock { print }
+  ' \
+  | grep -E '^\| Phase [0-9]+' \
+  | while IFS= read -r line; do
+      grep -qE '[0-9]+ open, [0-9]+ closed' <<<"$line" || continue
+      num="$(printf '%s\n' "$line" | sed -E 's/^\| Phase ([0-9]+).*/\1/')"
+      counts="$(printf '%s\n' "$line" | grep -oE '[0-9]+ open, [0-9]+ closed' | head -1)"
+      open="$(printf '%s\n' "$counts" | sed -E 's/^([0-9]+) open.*/\1/')"
+      closed="$(printf '%s\n' "$counts" | sed -E 's/^[0-9]+ open, ([0-9]+) closed/\1/')"
+      printf '%s|%s|%s\n' "$num" "$open" "$closed"
+    done
+}
+
+# reconcile_counts ROADMAP_FILE MILESTONES_JSON_FILE: emit verdict lines.
+reconcile_counts() {
+  local roadmap_file="$1" milestones_file="$2"
+  local rows num ropen rclosed found mopen mclosed ms_json
+  # Slurp milestones ONCE — the caller may pass a process-substitution FIFO,
+  # which drains on first read; re-reading it per loop iteration would yield
+  # empty and spuriously emit MISSING_ISSUE for every phase after the first.
+  ms_json="$(cat "$milestones_file")"
+  rows="$(extract_phase_counts < "$roadmap_file")"
+  [[ -z "$rows" ]] && return 0
+  while IFS='|' read -r num ropen rclosed; do
+    [[ -z "${num:-}" ]] && continue
+    found="$(jq -r --arg n "$num" '
+      [ .[] | select(.title | test("^Phase " + $n + "[:( ]")) ] | first
+      | if . == null then empty else "\(.open_issues)|\(.closed_issues)" end' \
+      <<< "$ms_json")"
+    if [[ -z "$found" ]]; then
+      printf 'MISSING_ISSUE|phase %s|roadmap=%so/%sc|milestone=none\n' "$num" "$ropen" "$rclosed"
+      continue
+    fi
+    mopen="${found%%|*}"
+    mclosed="${found##*|}"
+    if [[ "$mopen" -eq 0 && "$mclosed" -eq 0 ]]; then
+      printf 'EMPTY_MILESTONE|phase %s|milestone=0o/0c\n' "$num"
+    fi
+    if [[ "$mopen" != "$ropen" || "$mclosed" != "$rclosed" ]]; then
+      printf 'STALE_STATUS|phase %s|roadmap=%so/%sc|milestone=%so/%sc\n' \
+        "$num" "$ropen" "$rclosed" "$mopen" "$mclosed"
+    fi
+  done <<< "$rows"
+}
+
+# jq helpers shared by every line this module prints about an issue. `clean`
+# makes a title safe to print as the last field of a `|`-separated line: issue
+# titles are attacker-authorable on a public repo, and a newline in one could
+# otherwise forge a whole extra `CODEABLE|#N|…` line. `classify` is the single
+# CODEABLE-vs-OPERATOR rule, used by both `next` and `next --frontier`.
+ISSUE_JQ_DEFS="
+  def clean: (.title // \"\") | gsub(\"[[:cntrl:]\\u2028\\u2029]\"; \" \") | gsub(\"[|]\"; \"/\");
+  def classify: if any(.labels[]?.name; IN($OPERATOR_DOMAIN_LABELS)) then \"OPERATOR\"
+                elif any(.labels[]?.name; IN($CODEABLE_LABELS)) then \"CODEABLE\"
+                else \"OPERATOR\" end;
+"
+
+# pick_next_action OPEN_ISSUES_JSON_FILE: lowest-numbered open issue first
+# (deterministic tie-break), classified CODEABLE vs OPERATOR by label; explicit
+# NONE when the set is empty (never silent). One jq pass.
+pick_next_action() {
+  local line
+  line="$(jq -r "$ISSUE_JQ_DEFS"'
+    sort_by(.number) | (first // empty) | "\(classify)|#\(.number)|\(clean)"' "$1")" || return 2
+  if [[ -z "$line" ]]; then
+    echo "NONE|no actionable next item"
+    return 0
+  fi
+  printf '%s\n' "$line"
+}
+
+# pick_phase MILESTONES_JSON_FILE: the lowest-numbered OPEN `Phase N` milestone
+# that still has open issues, as "N|title"; empty when none. Read from live
+# milestones, not the roadmap's Current State cells: a phase row may carry no
+# frozen count, and skipping it picked the phase after it.
+# Known edge: the REST open_issues count includes open pull requests, so a
+# phase whose only open items are PRs is still picked (its frontier is empty).
+pick_phase() {
+  jq -r '
+    [ .[] | select(.state == "open" and (.open_issues // 0) > 0)
+          | select(.title | test("^Phase [0-9]+[:( ]"))
+          | {n: (.title | capture("^Phase (?<n>[0-9]+)").n | tonumber), title} ]
+    | sort_by(.n) | (first // empty) | "\(.n)|\(.title)"' "$1"
+}
+
+# filter_frontier OPEN_ISSUES_JSON_FILE: split a phase's open issues into the
+# frontier (no open blocker, no assignee; sorted by number) and the held-back
+# sets. Fails closed: a blocker counts as resolved only when its node reads
+# CLOSED. An issue with an OPEN blocker is `blocked`; one whose blockers could
+# not all be read (count above the nodes returned — a blocker in a repo the
+# token cannot see, or a truncated page — or a node whose state is neither OPEN
+# nor CLOSED) is `unverified`, held back but reported separately so "could not
+# check" never reads as "waiting". Blockers in any repository count. Returns 2,
+# naming the field, when number is not a number, blockedBy not an object or
+# assignees not an array (a missing or null field would otherwise read as
+# unblocked and unclaimed, and a string number could carry a forged line).
+# ONE jq pass: callers may pass a FIFO.
+filter_frontier() {
+  local out
+  out="$(jq -c '
+    def nodes: (.blockedBy.nodes // []);
+    def blocked: any(nodes[]; .state == "OPEN");
+    def held: ((.blockedBy.totalCount // 0) > (nodes | length)) or any(nodes[]; .state != "CLOSED");
+    def claimed: ((.assignees // []) | length) > 0;
+    ([ .[] | ((if (.number | type) == "number" then empty else "number" end),
+              (if (.blockedBy | type) == "object" then empty else "blockedBy" end),
+              (if (.assignees | type) == "array" then empty else "assignees" end)) ]
+     | unique) as $missing
+    | if ($missing | length) > 0 then {missing: $missing}
+      else { frontier:   ([ .[] | select((held | not) and (claimed | not)) ] | sort_by(.number)),
+             blocked:    ([ .[] | select(blocked) ] | sort_by(.number)),
+             unverified: ([ .[] | select(held and (blocked | not)) ] | sort_by(.number)),
+             claimed:    ([ .[] | select((held | not) and claimed) ] | sort_by(.number)) }
+      end' "$1")" || return 2
+  if [[ "$(jq -r 'has("missing")' <<< "$out")" == "true" ]]; then
+    echo "roadmap-reconcile: ERROR — issue data lacks field(s): $(jq -r '.missing | join(", ")' <<< "$out") (needs gh >= 2.94.0)." >&2
+    return 2
+  fi
+  printf '%s\n' "$out"
+}
+
+# --- CLI entrypoint (only when executed directly, never when sourced) ---
+_milestones_json() {
+  gh api 'repos/{owner}/{repo}/milestones?state=all&per_page=100' \
+    --jq '[ .[] | {title, state, open_issues, closed_issues} ]'
+}
+
+_usage() {
+  echo "usage: roadmap-reconcile.sh [validate|next [--frontier]]" >&2
+}
+
+# Held-back counts in the founder's words (DC-6), from filter_frontier output.
+_held_text() {
+  jq -r '"\(.blocked | length) waiting on another issue"
+    + (if (.unverified | length) > 0 then ", \(.unverified | length) whose blockers could not be read" else "" end)
+    + ", \(.claimed | length) with someone on it"' <<< "$1"
+}
+
+main() {
+  local mode="${1:-validate}"
+  [[ $# -gt 0 ]] && shift
+  case "$mode" in
+    validate)
+      if [[ $# -gt 0 ]]; then
+        _usage
+        return 64
+      fi
+      local ms verdicts
+      if ! ms="$(_milestones_json 2>/dev/null)"; then
+        echo "roadmap-reconcile: ERROR — could not fetch GitHub milestones (gh auth?)." >&2
+        return 2
+      fi
+      verdicts="$(reconcile_counts "$ROADMAP_FILE" <(printf '%s' "$ms"))"
+      if [[ -z "$verdicts" ]]; then
+        echo "roadmap-validate: clean — Current State counts match GitHub milestones."
+        return 0
+      fi
+      echo "roadmap-validate: drift detected (read-only — no file was modified)"
+      echo "$verdicts"
+      echo ""
+      echo "To fix: trigger the roadmap-review cron, which opens a reviewed PR:"
+      echo "  /soleur:trigger-cron cron/roadmap-review.manual-trigger"
+      return 1
+      ;;
+    next)
+      # Advisory, read-only: the next action for the live phase, chosen from its
+      # frontier (open, no open blocker, no assignee). `--frontier` lists it all.
+      # Exit contract: 0 = answer printed; 2 = the data could not be trusted
+      # (fetch failure, old gh, unparseable data) — never "nothing to do";
+      # 64 = usage.
+      local frontier_mode=0 pfx=roadmap-next
+      if [[ $# -eq 1 && "$1" == "--frontier" ]]; then
+        frontier_mode=1
+        pfx=roadmap-frontier
+      elif [[ $# -gt 0 ]]; then
+        _usage
+        return 64
+      fi
+      local errf ms sel phase mstitle issues filtered frontier held ready action num title
+      errf="$(mktemp)" || return 2
+      _RR_TMP="$errf"
+      if ! ms="$(_milestones_json 2>"$errf")"; then
+        echo "roadmap-next: ERROR — could not fetch GitHub milestones:" >&2
+        cat "$errf" >&2
+        rm -f "$errf"
+        return 2
+      fi
+      if ! sel="$(pick_phase <(printf '%s' "$ms"))"; then
+        echo "roadmap-next: ERROR — could not parse the milestone list." >&2
+        rm -f "$errf"
+        return 2
+      fi
+      if [[ -z "$sel" ]]; then
+        rm -f "$errf"
+        echo "$pfx: all phases complete — no open Phase milestone has open issues."
+        return 0
+      fi
+      phase="${sel%%|*}"
+      mstitle="${sel#*|}"
+      if ! issues="$(gh issue list --milestone "$mstitle" --state open --limit 1000 \
+          --json number,title,labels,assignees,blockedBy 2>"$errf")"; then
+        if grep -q 'Unknown JSON field' "$errf"; then
+          echo "roadmap-next: ERROR — reading blocking edges requires gh >= 2.94.0 (upgrade: https://github.com/cli/cli#installation)." >&2
+        else
+          echo "roadmap-next: ERROR — could not list open issues for $mstitle:" >&2
+          cat "$errf" >&2
+        fi
+        rm -f "$errf"
+        return 2
+      fi
+      rm -f "$errf"
+      filtered="$(filter_frontier <(printf '%s' "$issues"))" || return 2
+      held="$(_held_text "$filtered")" || return 2
+      if [[ "$frontier_mode" -eq 1 ]]; then
+        # Line 1 is always the `roadmap-frontier:` summary; then one line per
+        # ready issue, then one per held-back issue. Every issue line is
+        # KIND|#N|title[|detail] with the title cleaned of `|` and control chars.
+        ready="$(jq -r '.frontier | length' <<< "$filtered")" || return 2
+        echo "roadmap-frontier: Phase $phase — $ready ready to start, $held"
+        jq -r "$ISSUE_JQ_DEFS"'
+          (.frontier[]   | "\(classify)|#\(.number)|\(clean)"),
+          (.blocked[]    | "WAITING|#\(.number)|\(clean)|\([.blockedBy.nodes[] | select(.state == "OPEN") | "\(.repository.nameWithOwner // "")#\(.number)"] | join(","))"),
+          (.unverified[] | "UNVERIFIED|#\(.number)|\(clean)"),
+          (.claimed[]    | "CLAIMED|#\(.number)|\(clean)")' <<< "$filtered" || return 2
+        return 0
+      fi
+      frontier="$(jq -c '.frontier' <<< "$filtered")" || return 2
+      action="$(pick_next_action <(printf '%s' "$frontier"))" || return 2
+      num="${action#*|}"
+      num="${num%%|*}"
+      title="${action#*|*|}"
+      case "${action%%|*}" in
+        CODEABLE|OPERATOR)
+          # Defence in depth: filter_frontier already refuses a non-numeric
+          # .number, so this is unreachable on data that passed it.
+          if [[ ! "$num" =~ ^#[0-9]+$ ]]; then
+            echo "roadmap-next: ERROR — unexpected issue line: $action" >&2
+            return 2
+          fi
+          ;;
+      esac
+      case "${action%%|*}" in
+        CODEABLE)
+          echo "roadmap-next: Phase $phase — next codeable item ($held):"
+          echo "  $num $title"
+          echo "  Build it: /soleur:go $num"
+          ;;
+        OPERATOR)
+          echo "roadmap-next: Phase $phase — next item is operator-driven, not codeable ($held):"
+          echo "  $num $title"
+          echo "  This needs you (recruitment / interviews / ops), not an agent build."
+          ;;
+        *)
+          echo "roadmap-next: Phase $phase ($mstitle) — nothing ready to start: $held."
+          echo "  See which issues are waiting, and on what: roadmap-reconcile.sh next --frontier"
+          ;;
+      esac
+      return 0
+      ;;
+    *)
+      _usage
+      return 64
+      ;;
+  esac
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  # Owns `next`'s stderr capture file if the script dies between mktemp and rm
+  # (measured: bash runs this trap on SIGTERM too).
+  _RR_TMP=""
+  trap '[[ -z "${_RR_TMP:-}" ]] || rm -f "$_RR_TMP"' EXIT
+  main "$@"
+fi

package/skills/provision-cloudflare/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: provision-cloudflare
+description: "This skill should be used when provisioning scoped Cloudflare API tokens for tenant deploys."
+disable-model-invocation: true
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Provision Cloudflare
+
+Create a scoped Cloudflare API token via Terraform `cloudflare_api_token` with least-privilege permissions for a tenant's deploy pipeline.
+
+## Art. 32 Pre-condition
+
+**MUST run on the operator's local machine. MUST NOT run in CI.** Bootstrap credentials are accepted via `read -s` (interactive terminal only) and never persisted to disk, env exports, or CLI args.
+
+## Usage
+
+```
+soleur:provision-cloudflare <tenant-slug> <cf-zone-id> <cf-account-id> [--dry-run]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `tenant-slug` | Yes | Canonical tenant identifier (kebab-case) |
+| `cf-zone-id` | Yes | Cloudflare zone ID for the tenant's domain |
+| `cf-account-id` | Yes | Cloudflare account ID |
+| `--dry-run` | No | Print TF plan + smoke-test commands without executing |
+
+## Execution
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/provision-cloudflare/scripts/provision-cloudflare.sh" <slug> <zone-id> <account-id> [--dry-run]
+```
+
+The script:
+
+1. Validates prerequisites (DPA gate, format validation, tool availability)
+2. Checks idempotency (warns if `cloudflare.tf` already exists)
+3. Generates `provisioning/<slug>/cloudflare.tf` with 4 permission groups + sensitive output
+4. Emits a copy-pasteable `terraform apply` compound command with credential re-entry
+5. After operator confirms TF apply, runs token extraction + smoke-test pipeline
+6. Prints teardown commands and bootstrap revocation reminder
+
+## Encryption Posture
+
+If this run provisions a `cloudflare_r2_bucket` for the tenant, R2 has no encryption attribute
+either -- it is provider-managed at rest, and a bare "the provider handles it" is not an
+acceptable declaration. Do not complete the run without adding a row to
+`encryption-posture-ledger.json` (repo-root `scripts/`): `at_rest.mechanism: provider-managed:<named
+attestation>`, `at_rest.evidence` (attestation name + URL + retrieval date, plus the bucket's
+`location`/jurisdiction field in the `.tf`), `at_rest.does_not_defend`, `at_rest.disclosed_as`,
+and `at_rest.live_verification`. This run provisions a scoped API token, not a bucket, so the
+step is normally a no-op -- it applies only when a bucket enters scope.
+
+## Sharp Edges
+
+- R2 backend has no state locking. Single operator at N=2.
+- Token extraction uses `terraform output -raw` piped to a subshell to avoid terminal scrollback exposure.
+- CF provider pinned at `~> 4.0`; upgrade when Soleur's main root upgrades.
+- Does NOT grant `User Details:Read` or `Account Settings:Read` (least-privilege).

package/skills/provision-cloudflare/scripts/provision-cloudflare.sh

@@ -0,0 +1,271 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# (#7797) Refuse to run under shell tracing. UNCONDITIONAL: the scoped deploy token is read
+# from `terraform output` at runtime, BELOW this point, so a conditional arm would test an
+# empty variable at guard time and then trace the acquisition itself. Stdout, because agent
+# runtimes surface stdout and swallow stderr.
+case "$-" in
+  *x*)
+    printf '[FATAL] refusing to run under xtrace: this script handles a live credential and -x would print it (see #7797)\n'
+    exit 78
+    ;;
+esac
+
+SLUG=""
+CF_ZONE_ID=""
+CF_ACCOUNT_ID=""
+DRY_RUN=false
+
+usage() {
+  echo "Usage: provision-cloudflare <tenant-slug> <cf-zone-id> <cf-account-id> [--dry-run]" >&2
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=true; shift ;;
+    --help|-h) usage ;;
+    -*)        echo "Unknown flag: $1" >&2; usage ;;
+    *)
+      if [[ -z "$SLUG" ]]; then SLUG="$1"
+      elif [[ -z "$CF_ZONE_ID" ]]; then CF_ZONE_ID="$1"
+      elif [[ -z "$CF_ACCOUNT_ID" ]]; then CF_ACCOUNT_ID="$1"
+      else echo "Unexpected argument: $1" >&2; usage
+      fi
+      shift ;;
+  esac
+done
+
+[[ -n "$SLUG" ]] || { echo "Error: tenant-slug is required." >&2; usage; }
+[[ -n "$CF_ZONE_ID" ]] || { echo "Error: cf-zone-id is required." >&2; usage; }
+[[ -n "$CF_ACCOUNT_ID" ]] || { echo "Error: cf-account-id is required." >&2; usage; }
+
+if ! [[ "$SLUG" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+  echo "Error: tenant-slug must be kebab-case (e.g. 'acme-prd')." >&2
+  exit 1
+fi
+
+if ! [[ "$CF_ZONE_ID" =~ ^[a-f0-9]{32}$ ]]; then
+  echo "Error: cf-zone-id must be a 32-char hex string." >&2
+  exit 1
+fi
+
+if ! [[ "$CF_ACCOUNT_ID" =~ ^[a-f0-9]{32}$ ]]; then
+  echo "Error: cf-account-id must be a 32-char hex string." >&2
+  exit 1
+fi
+
+PROVISIONING_DIR="provisioning/${SLUG}/cloudflare"
+CREATED_RESOURCES=()
+
+cleanup() {
+  local exit_code=$?
+  echo ""
+  echo "=== Teardown commands (resources created during this run) ==="
+  if [[ ${#CREATED_RESOURCES[@]} -eq 0 ]]; then
+    echo "  (no resources were created)"
+  else
+    for res in "${CREATED_RESOURCES[@]}"; do
+      echo "  $res"
+    done
+  fi
+  echo ""
+  echo "Bootstrap cleanup: Revoke the Cloudflare API token used for bootstrapping — it is no longer needed."
+  exit "$exit_code"
+}
+trap cleanup EXIT INT TERM
+
+# --- Pre-checks ---
+
+command -v curl >/dev/null 2>&1 || { echo "Error: 'curl' not found." >&2; exit 1; }
+command -v terraform >/dev/null 2>&1 || { echo "Error: 'terraform' not found." >&2; exit 1; }
+
+# --- DPA gate ---
+
+DPA_FILE="knowledge-base/legal/tenant-dpa-register.md"
+[[ -f "$DPA_FILE" ]] || { echo "DPA register not found at $DPA_FILE. Run from Soleur monorepo root." >&2; exit 3; }
+awk -F'|' -v slug="$SLUG" '/^\|/ { gsub(/^ +| +$/, "", $2); if ($2 == slug) found = ($8 ~ /^ *(dpa-signed|provisioning-in-progress) *$/) } END { exit !found }' "$DPA_FILE" \
+  || { echo "No active DPA row for '$SLUG'. Sign DPA (Step 0) first." >&2; exit 3; }
+
+# --- Idempotency check ---
+
+if [[ -f "${PROVISIONING_DIR}/cloudflare.tf" ]]; then
+  echo "WARNING: ${PROVISIONING_DIR}/cloudflare.tf already exists."
+  echo "  Continuing will overwrite. Existing CF resources are unchanged until 'terraform apply'."
+  echo ""
+fi
+
+# --- Generate TF config ---
+
+mkdir -p "$PROVISIONING_DIR"
+
+cat > "${PROVISIONING_DIR}/cloudflare.tf" <<TFEOF
+terraform {
+  required_version = ">= 1.6"
+
+  backend "s3" {
+    bucket                      = "soleur-terraform-state"
+    key                         = "tenants/${SLUG}/cloudflare.tfstate"
+    region                      = "auto"
+    endpoints                   = { s3 = "https://4d5ba6f096b2686fbdd404167dd4e125.r2.cloudflarestorage.com" }
+    skip_credentials_validation = true
+    skip_requesting_account_id  = true
+    skip_metadata_api_check     = true
+    skip_region_validation      = true
+    skip_s3_checksum            = true
+    use_path_style              = true
+    use_lockfile                = false
+  }
+
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 4.0"
+    }
+  }
+}
+
+variable "cf_bootstrap_token" {
+  description = "Cloudflare API token for bootstrapping (re-entered at apply time)"
+  type        = string
+  sensitive   = true
+}
+
+provider "cloudflare" {
+  api_token = var.cf_bootstrap_token
+
+  # 5xx retry budget ~7.75min/request (15+30+60+120+120+120s vs ~7s v4
+  # default) — rides out multi-minute Cloudflare API blips at plan (#10643).
+  # v5 renames this trio `max_retries`; carry the budget across a migration.
+  retries     = 6
+  min_backoff = 15
+  max_backoff = 120
+}
+
+resource "cloudflare_api_token" "tenant_deploy" {
+  name = "${SLUG}-deploy"
+
+  policy {
+    permission_groups = [
+      data.cloudflare_api_token_permission_groups.all.zone["Workers Routes Write"],
+      data.cloudflare_api_token_permission_groups.all.zone["DNS Write"],
+    ]
+    resources = {
+      "com.cloudflare.api.account.zone.${CF_ZONE_ID}" = "*"
+    }
+  }
+
+  policy {
+    permission_groups = [
+      data.cloudflare_api_token_permission_groups.all.account["Workers Scripts Write"],
+      data.cloudflare_api_token_permission_groups.all.account["Cloudflare Pages Write"],
+    ]
+    resources = {
+      "com.cloudflare.api.account.${CF_ACCOUNT_ID}" = "*"
+    }
+  }
+}
+
+data "cloudflare_api_token_permission_groups" "all" {}
+
+output "cf_deploy_token" {
+  value     = cloudflare_api_token.tenant_deploy.value
+  sensitive = true
+}
+TFEOF
+
+echo "Generated ${PROVISIONING_DIR}/cloudflare.tf"
+
+# --- Dry-run output ---
+
+if $DRY_RUN; then
+  echo ""
+  echo "=== DRY RUN — No changes will be made ==="
+  echo ""
+  echo "--- Generated Terraform config ---"
+  cat "${PROVISIONING_DIR}/cloudflare.tf"
+  echo ""
+  echo "--- Copy-pasteable TF apply command ---"
+  echo "read -rs -p 'Cloudflare API token: ' TF_VAR_cf_bootstrap_token && \\"
+  echo "  export TF_VAR_cf_bootstrap_token && \\"
+  echo "  (cd ${PROVISIONING_DIR} && terraform init && terraform apply); \\"
+  echo "  unset TF_VAR_cf_bootstrap_token"
+  echo ""
+  echo "--- Smoke-test (run after TF apply) ---"
+  echo "cd ${PROVISIONING_DIR} && terraform output -raw cf_deploy_token | ("
+  echo "  read -r TOKEN"
+  echo "  curl --disable --noproxy '*' -sS --config - \\"
+  echo "    https://api.cloudflare.com/client/v4/user/tokens/verify \\"
+  echo "    < <(printf 'header = \"Authorization: Bearer %s\"\\n' \"\$TOKEN\") | jq .result.status"
+  echo ")"
+  echo ""
+  echo "--- Teardown ---"
+  echo "  cd ${PROVISIONING_DIR} && terraform destroy"
+  echo "  rm -rf ${PROVISIONING_DIR}/cloudflare.tf"
+  echo ""
+  echo "Next step: type /soleur:provision-doppler ${SLUG} <org> <repo> yourself (user-invoked; Soleur cannot run it, ADR-236)"
+  exit 0
+fi
+
+# --- Interactive flow ---
+
+echo ""
+echo "=== Cloudflare provisioning for '${SLUG}' ==="
+echo ""
+echo "This will create a scoped API token with:"
+echo "  - Workers Scripts:Edit (account: ${CF_ACCOUNT_ID})"
+echo "  - Workers Routes:Edit (zone: ${CF_ZONE_ID})"
+echo "  - Cloudflare Pages:Edit (account: ${CF_ACCOUNT_ID})"
+echo "  - DNS:Edit (zone: ${CF_ZONE_ID})"
+echo ""
+
+echo "--- Step 1: Terraform apply ---"
+echo ""
+echo "Run this command in a separate terminal:"
+echo ""
+echo "  read -rs -p 'Cloudflare API token: ' TF_VAR_cf_bootstrap_token && \\"
+echo "    export TF_VAR_cf_bootstrap_token && \\"
+echo "    (cd ${PROVISIONING_DIR} && terraform init && terraform apply); \\"
+echo "    unset TF_VAR_cf_bootstrap_token"
+echo ""
+
+read -p "TF apply complete? Type 'yes': " ACK
+[[ "$ACK" == "yes" ]] || { echo "Aborted." >&2; exit 1; }
+
+# --- Token extraction + smoke-test ---
+
+echo ""
+echo "--- Smoke-test: verifying scoped token ---"
+
+# Token-shape guard (never echoes the value): the token is written into curl's stdin config
+# below, so a quote or newline in it would inject a config directive. An unusable token
+# makes zero curl calls and aborts the run non-zero, never a green smoke-test.
+_bearer_ok() { local LC_ALL=C; case "${1:-}" in ''|*[!A-Za-z0-9._~+/=-]*) return 1 ;; esac; }
+
+VERIFY_RESULT=$(
+  cd "$PROVISIONING_DIR" && terraform output -raw cf_deploy_token | (
+    read -r TOKEN || true
+    if ! _bearer_ok "$TOKEN"; then
+      echo "Error: the deploy token from terraform output is missing or has an unexpected shape; not sent." >&2
+      exit 1
+    fi
+    # The bearer rides curl's stdin config channel, never its argument list.
+    curl --disable --noproxy '*' -sS --config - \
+      https://api.cloudflare.com/client/v4/user/tokens/verify \
+      < <(printf 'header = "Authorization: Bearer %s"\n' "$TOKEN")
+  )
+)
+
+CREATED_RESOURCES+=("cd ${PROVISIONING_DIR} && terraform destroy")
+
+TOKEN_STATUS=$(echo "$VERIFY_RESULT" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
+if [[ "$TOKEN_STATUS" == "active" ]]; then
+  echo "Smoke-test passed: scoped token is active."
+else
+  echo "Warning: Token verify returned status '${TOKEN_STATUS:-unknown}'. Full response:" >&2
+  echo "$VERIFY_RESULT" >&2
+fi
+
+echo ""
+echo "Next step: type /soleur:provision-doppler ${SLUG} <org> <repo> yourself (user-invoked; Soleur cannot run it, ADR-236)"