@soleur/opencode 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,300 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SLUG=""
+TENANT_ORG=""
+REVIEWER=""
+DRY_RUN=false
+
+usage() {
+  echo "Usage: provision-github <tenant-slug> <tenant-org> <reviewer-github-username> [--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 "$TENANT_ORG" ]]; then TENANT_ORG="$1"
+      elif [[ -z "$REVIEWER" ]]; then REVIEWER="$1"
+      else echo "Unexpected argument: $1" >&2; usage
+      fi
+      shift ;;
+  esac
+done
+
+[[ -n "$SLUG" ]] || { echo "Error: tenant-slug is required." >&2; usage; }
+[[ -n "$TENANT_ORG" ]] || { echo "Error: tenant-org is required." >&2; usage; }
+[[ -n "$REVIEWER" ]] || { echo "Error: reviewer-github-username 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 ! [[ "$TENANT_ORG" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$ ]]; then
+  echo "Error: tenant-org must be a valid GitHub org name (alphanumerics and hyphens)." >&2
+  exit 1
+fi
+
+if ! [[ "$REVIEWER" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$ ]]; then
+  echo "Error: reviewer must be a valid GitHub username (alphanumerics and hyphens)." >&2
+  exit 1
+fi
+
+PROVISIONING_DIR="provisioning/${SLUG}/github"
+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 "IMPORTANT: After deleting the App installation, sweep bypass_actors for ghost entries:"
+  echo "  gh api /repos/${TENANT_ORG}/${SLUG}/rulesets --jq '.[].bypass_actors'"
+  echo ""
+  echo "Bootstrap cleanup: Revoke the GitHub PAT used for bootstrapping — it is no longer needed."
+  exit "$exit_code"
+}
+trap cleanup EXIT INT TERM
+
+# --- Pre-checks ---
+
+gh auth status >/dev/null 2>&1 || { echo "Error: 'gh' CLI not authenticated. Run 'gh auth login'." >&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 gh repo view "${TENANT_ORG}/${SLUG}" >/dev/null 2>&1; then
+  echo "WARNING: Repository '${TENANT_ORG}/${SLUG}' already exists."
+  echo "  Continuing will regenerate TF config. Existing repo is unchanged until 'terraform apply'."
+  echo ""
+fi
+
+# --- Resolve org-id ---
+
+ORG_ID=$(gh api "/orgs/${TENANT_ORG}" --jq .id 2>/dev/null) \
+  || { echo "Error: Could not resolve org ID for '${TENANT_ORG}'. Check org name and permissions." >&2; exit 1; }
+
+echo "Resolved org ID: ${TENANT_ORG} → ${ORG_ID}"
+
+# --- Resolve reviewer user ID ---
+
+REVIEWER_ID=$(gh api "/users/${REVIEWER}" --jq .id 2>/dev/null) \
+  || { echo "Error: Could not resolve user ID for '${REVIEWER}'." >&2; exit 1; }
+
+echo "Resolved reviewer ID: ${REVIEWER} → ${REVIEWER_ID}"
+
+# --- Generate TF config ---
+
+mkdir -p "$PROVISIONING_DIR"
+
+cat > "${PROVISIONING_DIR}/github.tf" <<TFEOF
+terraform {
+  required_version = ">= 1.6"
+
+  backend "s3" {
+    bucket                      = "soleur-terraform-state"
+    key                         = "tenants/${SLUG}/github.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 {
+    github = {
+      source  = "integrations/github"
+      version = "~> 6.0"
+    }
+  }
+}
+
+variable "github_token" {
+  description = "GitHub PAT with repo + admin:org scope (re-entered at apply time)"
+  type        = string
+  sensitive   = true
+}
+
+provider "github" {
+  owner = "${TENANT_ORG}"
+  token = var.github_token
+}
+
+resource "github_repository" "tenant" {
+  name        = "${SLUG}"
+  description = "Tenant repository for ${SLUG}"
+  visibility  = "private"
+
+  has_issues   = true
+  has_projects = false
+  has_wiki     = false
+
+  delete_branch_on_merge = true
+  allow_squash_merge     = true
+  allow_merge_commit     = false
+  allow_rebase_merge     = false
+}
+
+resource "github_repository_environment" "production" {
+  repository  = github_repository.tenant.name
+  environment = "production"
+
+  reviewers {
+    users = [${REVIEWER_ID}]
+  }
+
+  deployment_branch_policy {
+    protected_branches     = false
+    custom_branch_policies = true
+  }
+}
+
+resource "github_repository_environment_deployment_policy" "main_only" {
+  repository     = github_repository.tenant.name
+  environment    = github_repository_environment.production.environment
+  branch_pattern = "main"
+}
+TFEOF
+
+echo "Generated ${PROVISIONING_DIR}/github.tf"
+
+INSTALL_URL="https://github.com/apps/soleur/installations/new/permissions?target_id=${ORG_ID}"
+
+# --- Dry-run output ---
+
+if $DRY_RUN; then
+  echo ""
+  echo "=== DRY RUN — No changes will be made ==="
+  echo ""
+  echo "--- Generated Terraform config ---"
+  cat "${PROVISIONING_DIR}/github.tf"
+  echo ""
+  echo "--- Copy-pasteable TF apply command ---"
+  echo "read -rs -p 'GitHub PAT: ' TF_VAR_github_token && \\"
+  echo "  export TF_VAR_github_token && \\"
+  echo "  (cd ${PROVISIONING_DIR} && terraform init && terraform apply); \\"
+  echo "  unset TF_VAR_github_token"
+  echo ""
+  echo "--- App install URL (human consent gate, per ToS B.3) ---"
+  echo "  ${INSTALL_URL}"
+  echo ""
+  echo "--- Verification ---"
+  echo "  gh api /repos/${TENANT_ORG}/${SLUG}/installation"
+  echo "  gh api /repos/${TENANT_ORG}/${SLUG}/environments/production"
+  echo ""
+  echo "--- Teardown ---"
+  echo "  gh api -X DELETE /app/installations/<install-id>"
+  echo "  cd ${PROVISIONING_DIR} && terraform destroy"
+  echo "  Sweep bypass_actors: gh api /repos/${TENANT_ORG}/${SLUG}/rulesets --jq '.[].bypass_actors'"
+  echo ""
+  echo "All provisioning complete. Run runbook Steps 5-10 manually."
+  exit 0
+fi
+
+# --- Interactive flow ---
+
+echo ""
+echo "=== GitHub provisioning for '${SLUG}' ==="
+echo ""
+echo "This will:"
+echo "  1. Create repo '${TENANT_ORG}/${SLUG}' via Terraform"
+echo "  2. Create 'production' Environment with required reviewer (${REVIEWER})"
+echo "  3. Pin deployment branch policy to 'main' only"
+echo "  4. Install Soleur GitHub App on the repo (human consent)"
+echo ""
+
+echo "--- Step 1: Terraform apply ---"
+echo ""
+echo "Run this command in a separate terminal:"
+echo ""
+echo "  read -rs -p 'GitHub PAT: ' TF_VAR_github_token && \\"
+echo "    export TF_VAR_github_token && \\"
+echo "    (cd ${PROVISIONING_DIR} && terraform init && terraform apply); \\"
+echo "    unset TF_VAR_github_token"
+echo ""
+
+read -p "TF apply complete? Type 'yes': " ACK
+[[ "$ACK" == "yes" ]] || { echo "Aborted." >&2; exit 1; }
+
+# --- Verify TF apply ---
+
+if ! gh repo view "${TENANT_ORG}/${SLUG}" >/dev/null 2>&1; then
+  echo "Error: Repository '${TENANT_ORG}/${SLUG}' not found. TF apply may not have completed." >&2
+  exit 1
+fi
+
+CREATED_RESOURCES+=("cd ${PROVISIONING_DIR} && terraform destroy")
+echo "Verified: Repository '${TENANT_ORG}/${SLUG}' exists."
+
+# --- Verify Environment ---
+
+ENV_CHECK=$(gh api "/repos/${TENANT_ORG}/${SLUG}/environments/production" --jq '.name' 2>/dev/null) || true
+if [[ "$ENV_CHECK" == "production" ]]; then
+  echo "Verified: Environment 'production' exists with required reviewers."
+else
+  echo "Warning: Could not verify 'production' Environment. Check GitHub settings." >&2
+fi
+
+# --- Step 2: App install (human consent gate) ---
+
+echo ""
+echo "--- Step 2: Install Soleur GitHub App ---"
+echo ""
+echo "This step requires human consent per GitHub ToS B.3."
+echo "Open this URL and install the Soleur App on '${TENANT_ORG}/${SLUG}':"
+echo ""
+echo "  ${INSTALL_URL}"
+echo ""
+echo "Select ONLY the '${SLUG}' repository (not org-wide)."
+echo ""
+
+read -p "App installed? Type 'yes': " ACK
+[[ "$ACK" == "yes" ]] || { echo "Aborted." >&2; exit 1; }
+
+# --- Verify App install ---
+
+INSTALL_JSON=$(gh api "/repos/${TENANT_ORG}/${SLUG}/installation" 2>/dev/null) || true
+INSTALL_CHECK=$(echo "$INSTALL_JSON" | grep -o '"actions":"[^"]*"' | head -1 | cut -d'"' -f4)
+REPO_SELECTION=$(echo "$INSTALL_JSON" | grep -o '"repository_selection":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+if [[ "$REPO_SELECTION" == "all" ]]; then
+  echo "ERROR: App installed org-wide (repository_selection=all). Must be 'selected' (single repo)." >&2
+  echo "Reconfigure: Settings → Integrations → Soleur → Repository access → Only select repositories" >&2
+  exit 1
+fi
+
+if [[ "$INSTALL_CHECK" == "write" ]]; then
+  INSTALL_ID=$(echo "$INSTALL_JSON" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
+  CREATED_RESOURCES+=("gh api -X DELETE /app/installations/${INSTALL_ID}")
+  echo "Verified: Soleur App installed with actions:write permission (repository_selection=${REPO_SELECTION:-selected})."
+else
+  echo "Warning: Could not verify App installation or permissions." >&2
+  echo "Expected permissions.actions = 'write'. Got: '${INSTALL_CHECK:-empty}'" >&2
+  echo "Verify manually: gh api /repos/${TENANT_ORG}/${SLUG}/installation" >&2
+fi
+
+echo ""
+echo "All provisioning complete. Run runbook Steps 5-10 manually."

package/skills/provision-hetzner/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: provision-hetzner
+description: "This skill should be used when provisioning Hetzner sub-projects and tokens for tenant infrastructure."
+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 Hetzner
+
+Guide the operator through Hetzner Console project creation, accept a project-scoped API token, and run a write-class smoke-test to verify scope.
+
+## Art. 32 Pre-condition
+
+**MUST run on the operator's local machine. MUST NOT run in CI.** The Hetzner token is read from `SOLEUR_BOOTSTRAP_HCLOUD_TOKEN` when that variable is set; otherwise it is prompted for with `read -rs` on a TTY (credential entry is a class-1 interactive carve-out: the agent never asks for the token in chat); with neither, the script exits 64 with `SOLEUR_BOOTSTRAP_INPUT_REQUIRED var=SOLEUR_BOOTSTRAP_HCLOUD_TOKEN`. It is never persisted to disk, never exported beyond the smoke-test subshell, and never placed on CLI args.
+
+## Usage
+
+```
+soleur:provision-hetzner <tenant-slug> [--dry-run]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `tenant-slug` | Yes | Canonical tenant identifier (kebab-case) |
+| `--dry-run` | No | Print Console guidance + smoke-test commands without executing |
+
+## Execution
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/provision-hetzner/scripts/provision-hetzner.sh" <slug> [--dry-run]
+```
+
+The script:
+
+1. Validates prerequisites (DPA gate, slug format, `hcloud` CLI)
+2. Displays guided instructions for Console project creation + token minting
+3. Accepts the token (environment variable, else the class-1 `read -rs` entry on a TTY, else exit 64) and, after a per-command `yes` acknowledgement that has **no** skip variable, runs the write-class smoke-test (create + delete cx11)
+4. Uses deterministic probe name (`probe-provision-<slug>`) so orphans are findable
+5. Trap handler ensures probe server cleanup on EXIT/INT/TERM
+6. Prints teardown commands on any exit
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `SOLEUR_BOOTSTRAP_HCLOUD_TOKEN` | Supplies the project-scoped token; the `read -rs` prompt is skipped. Set it for the current command only (`SOLEUR_BOOTSTRAP_HCLOUD_TOKEN="$(…)" bash …`), never exported into the shell. |
+| `SOLEUR_BOOTSTRAP_SKIP_HETZNER_TOKEN_BARRIER` | Any non-empty value skips the "Token created? Type 'yes'" barrier. The smoke test that follows is the independent verification the barrier attests to, so skipping it is safe only because that test still runs. |
+| `SOLEUR_BOOTSTRAP_LEDGER` | Run-ledger path. Default: `<cwd>/.soleur/bootstrap-runs.jsonl` (gitignored; the DPA gate already requires cwd to be the monorepo root). |
+
+There is **no** variable for the "Create the billable probe server now?" acknowledgement. Without a TTY the script exits 64 there with `SOLEUR_BOOTSTRAP_INPUT_REQUIRED var=destructive-write-ack(no-skip-variable-by-design)`; only a person at a terminal can answer it (`hr-menu-option-ack-not-prod-write-auth`). This script still uses the typed-`yes` TTY acknowledgement; migrating it to the staged agent-run approval gate that generated operator scripts use is tracked in #9387. The agent runs every step it can (prerequisites, instructions, verification) and hands over only that one prompt. Exit codes and every stdout marker: the header of `plugins/soleur/scripts/lib/operator-script.sh`.
+
+## Encryption Posture
+
+If this run provisions a persistent volume for the tenant, `hcloud_volume` carries no
+`encrypted` attribute -- encryption means the guest-side LUKS apparatus (`random_password` ->
+dedicated Doppler config -> `cryptsetup luksFormat` -> `/dev/mapper/*` mount; see
+soleur:engineering:infra:terraform-architect's Hetzner/Cloudflare requirements). Do not complete the run without adding a
+row to `encryption-posture-ledger.json` (repo-root `scripts/`) for the new volume: `at_rest.mechanism`
+(`luks` or a named `plaintext-exception` with `tracking_issue` + `expires_on`),
+`at_rest.evidence`, `at_rest.does_not_defend`, `at_rest.disclosed_as`, and
+`at_rest.live_verification`. This run provisions sub-projects and tokens, not volumes, so the
+step is normally a no-op -- it applies only when a volume enters scope.
+
+## Sharp Edges
+
+- Hetzner has no TF resource for project creation or token minting (Console-only). This is the one manual step in this skill; it is tracked as an automation gap with revisit criteria in **Tracks #4604** (per `hr-never-label-any-step-as-manual-without`) — do not treat it as permanently-manual.
+- The smoke-test creates a real cx11 server (~EUR 0.006/hr prorated). Trap handler cleans up.
+- If `hcloud server delete` fails, the probe server must be deleted manually via Console.
+- Read-only tokens silently succeed for reads; the write-class test (server create) is essential.

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

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# The proving consumer for plugins/soleur/scripts/lib/operator-script.sh (#8287
+# Phase 4). The `--dry-run` stdout is pinned byte-for-byte by
+# test/provision-hetzner-characterization.test.sh; that golden is the safety net
+# for this refactor and it must stay byte-identical.
+set -euo pipefail
+
+# --- PROLOGUE (must stay ABOVE the `source` line) ----------------------------
+# Duplicated here, never moved into the library — see "SOURCING PRECONDITIONS"
+# §2 in plugins/soleur/scripts/lib/operator-script.sh for why.
+#
+# UNCONDITIONAL, not the conditional `${HCLOUD_TOKEN:+x}` arm: this script
+# ACQUIRES its token with `read -rs` BELOW this point, so the variable is empty
+# at guard time and a conditional arm would be open by construction. The linter
+# cannot see that — its ACQUIRES set knows `doppler secrets get` / `gh auth
+# token` / `_TOKEN="$(`, not `read -rs`.
+#
+# Stdout, not stderr: 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
+
+# SSLKEYLOGFILE writes TLS session keys to disk; the smoke test must not
+# inherit it. The CA-pool variables (SSL_CERT_FILE, SSL_CERT_DIR,
+# CURL_CA_BUNDLE) are deliberately NOT stripped: `hcloud` is a Go client that
+# reads them for its root pool, and a founder behind a TLS-inspecting proxy
+# would otherwise see an x509 failure on the billable smoke test reported as
+# "token lacks write scope" (the credential linter requires only the xtrace
+# refusal above — measured).
+unset SSLKEYLOGFILE
+
+# --- shared operator-script library ------------------------------------------
+# Sourced, never inlined: there is one distribution mode and therefore no copy to
+# drift from. The library supplies the prompt classes, the run ledger and the
+# secret-write helpers. The `read -rs` below STAYS IN THIS FILE — the prompt
+# string is the operator-facing product, and the prologue rule above is why the
+# surround cannot be moved either.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# An override must be ABSOLUTE, for the reason template.sh states at its own
+# resolution ladder: `-r` tests a relative name against cwd while `source`
+# searches PATH for it, so a relative value can pass the readability check and
+# then source a DIFFERENT file into a shell that is about to hold a live token.
+# The generated scripts have carried this guard since R26; the proving consumer
+# is the one place it was missing.
+if [[ -n "${SOLEUR_OP_LIB:-}" && "${SOLEUR_OP_LIB}" != /* ]]; then
+  printf 'SOLEUR_BOOTSTRAP_BAD_ARG var=SOLEUR_OP_LIB reason=must-be-absolute value=%s\n' "$SOLEUR_OP_LIB"
+  exit 64
+fi
+SOLEUR_OP_LIB="${SOLEUR_OP_LIB:-${SCRIPT_DIR}/../../../scripts/lib/operator-script.sh}"
+if [[ ! -r "$SOLEUR_OP_LIB" ]]; then
+  printf 'SOLEUR_BOOTSTRAP_LIB_MISSING path=%s\n' "$SOLEUR_OP_LIB"
+  exit 64
+fi
+# shellcheck source=../../../scripts/lib/operator-script.sh disable=SC1091
+source "$SOLEUR_OP_LIB"
+# API contract (library header §API): prints nothing on success. EQUALITY, not
+# -ge — the library auto-updates with the plugin; see the template's comment.
+[[ ${SOLEUR_OP_LIB_API:-0} -eq 1 ]] || {
+  printf 'SOLEUR_BOOTSTRAP_LIB_INCOMPATIBLE need=1 got=%s\n' "${SOLEUR_OP_LIB_API:-0}"
+  exit 64
+}
+
+SLUG=""
+DRY_RUN=false
+
+usage() {
+  echo "Usage: provision-hetzner <tenant-slug> [--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"
+      else echo "Unexpected argument: $1" >&2; usage
+      fi
+      shift ;;
+  esac
+done
+
+[[ -n "$SLUG" ]] || { echo "Error: tenant-slug 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
+
+PROBE_NAME="probe-provision-${SLUG}"
+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 "If the probe server '${PROBE_NAME}' was not cleaned up:"
+  echo "  hcloud server delete '${PROBE_NAME}'"
+  echo ""
+  echo "To tear down the Hetzner sub-project:"
+  echo "  Delete via Hetzner Console → Projects → tenant-${SLUG}-prd → Delete"
+  echo "  (CLI does not support project deletion)"
+  exit "$exit_code"
+}
+trap cleanup EXIT INT TERM
+
+# --- Pre-checks ---
+
+command -v hcloud >/dev/null 2>&1 || { echo "Error: 'hcloud' CLI not found. Install: https://github.com/hetznercloud/cli" >&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; }
+
+# --- Dry-run output ---
+
+if $DRY_RUN; then
+  echo ""
+  echo "=== DRY RUN — No changes will be made ==="
+  echo ""
+  echo "--- Console guidance ---"
+  echo "1. Log in to the tenant's Hetzner Cloud Console"
+  echo "2. Create a sub-project named 'tenant-${SLUG}-prd'"
+  echo "3. Inside the sub-project, go to Security → API Tokens"
+  echo "4. Create a project-scoped API token with Read+Write permissions"
+  echo "5. Copy the token (shown only once)"
+  echo ""
+  echo "--- Smoke-test commands (run after token creation) ---"
+  echo "read -rs -p 'Hetzner token: ' HCLOUD_TOKEN; echo"
+  echo "("
+  echo "  export HCLOUD_TOKEN"
+  echo "  hcloud server create --name '${PROBE_NAME}' --type cx11 --image ubuntu-22.04 --location nbg1"
+  echo "  hcloud server delete '${PROBE_NAME}'"
+  echo ")"
+  echo "unset HCLOUD_TOKEN"
+  echo ""
+  echo "--- Teardown ---"
+  echo "  Delete sub-project via Console: Projects → tenant-${SLUG}-prd → Delete"
+  echo "  Revoke the API token: Security → API Tokens → Revoke"
+  echo ""
+  echo "Next step: type /soleur:provision-cloudflare ${SLUG} <zone-id> <account-id> yourself (user-invoked; Soleur cannot run it, ADR-236)"
+  exit 0
+fi
+
+# --- Interactive flow ---
+
+# Run ledger home. The library's default is "beside the main script", which for
+# THIS script is the plugin tree (a marketplace cache, untracked, not ignored —
+# review P2-19). The DPA gate above already requires cwd to be the monorepo
+# root, so the ledger goes under its `.soleur/` (gitignored). Set AFTER the
+# dry-run branch so the golden stdout is untouched, and BEFORE ledger_init.
+: "${SOLEUR_BOOTSTRAP_LEDGER:=$(pwd)/.soleur/bootstrap-runs.jsonl}"
+export SOLEUR_BOOTSTRAP_LEDGER
+
+echo ""
+echo "=== Hetzner provisioning for '${SLUG}' ==="
+echo ""
+echo "Hetzner does not have a Terraform resource for project creation or token minting."
+echo "Follow these steps in the Hetzner Cloud Console:"
+echo ""
+echo "  1. Log in to the tenant's Hetzner Cloud master account"
+echo "  2. Create a sub-project named 'tenant-${SLUG}-prd'"
+echo "  3. Inside the sub-project, go to Security → API Tokens"
+echo "  4. Create a project-scoped API token with Read+Write permissions"
+echo "  5. Copy the token (shown only once)"
+echo ""
+
+soleur_op_ledger_init 2 "provision-hetzner.sh"
+soleur_op_stage_begin 1 "operator mints the project-scoped token"
+
+# CLASS 3 — out-of-band completion barrier. It attests that a human did something
+# OUTSIDE this script, so it takes a named skip variable AND is followed by an
+# independent verification: the write-class smoke test below fails if the
+# attestation was false. Today's behaviour was fail-closed but MUTE — EOF read
+# into an empty ACK and `exit 1` with "Aborted.", the right outcome with an
+# unattributed cause. Now: SOLEUR_BOOTSTRAP_INPUT_REQUIRED and exit 64.
+soleur_op_barrier SOLEUR_BOOTSTRAP_SKIP_HETZNER_TOKEN_BARRIER "Token created? Type 'yes' to continue: "
+
+# --- Accept token + smoke-test ---
+
+echo ""
+echo "--- Write-class smoke-test ---"
+echo "Creating + deleting probe server '${PROBE_NAME}' (cx11, nbg1) to verify token scope."
+echo ""
+
+# Credential ENTRY. The library supplies the SURROUND (named skip variable, TTY
+# gate, exit 64 naming the variable); the `read -rs` itself stays in this file
+# because the prompt string is the operator-facing product (plan D12). The
+# library's class-1 helper echoes its input and is for non-secret values only.
+#
+# The TTY gate sits ABOVE the read, never below it: the property is about the
+# instant BEFORE the read, and a check that runs after it cannot see the hang.
+hcloud_token_skip="$(soleur_op_skip_value SOLEUR_BOOTSTRAP_HCLOUD_TOKEN)"
+if [[ -n "$hcloud_token_skip" ]]; then
+  HCLOUD_TOKEN="$hcloud_token_skip"
+else
+  [[ -t 0 ]] || soleur_op_input_required SOLEUR_BOOTSTRAP_HCLOUD_TOKEN
+  read -rs -p "Hetzner project-scoped API token: " HCLOUD_TOKEN
+  echo ""
+fi
+unset hcloud_token_skip
+
+soleur_op_stage_end 1 "operator mints the project-scoped token" ok 0
+soleur_op_stage_begin 2 "write-class smoke test (billable)"
+
+# CLASS 2 — per-command destructive-write acknowledgement, and it takes NO SKIP
+# VARIABLE by design. `hcloud server create` below bills a real server, and this
+# file had no acknowledgement in front of it: the existing "Token created?" ack
+# acknowledges TOKEN CREATION and is separated from the create by the token read.
+# Giving this one an environment-variable escape would be exactly the "prior
+# approval extending to a new command" that hr-menu-option-ack-not-prod-write-auth
+# forbids — an unattended billable create introduced by the machinery that claims
+# to prevent it (plan revision R8).
+soleur_op_ack_or_die "Create the billable probe server '${PROBE_NAME}' now? Type 'yes': "
+
+(
+  export HCLOUD_TOKEN
+  trap 'echo "Cleaning up probe server..."; hcloud server delete "$PROBE_NAME" 2>/dev/null || true' EXIT INT TERM
+
+  echo "Creating probe server '${PROBE_NAME}'..."
+  if ! hcloud server create --name "$PROBE_NAME" --type cx11 --image ubuntu-22.04 --location nbg1; then
+    echo "" >&2
+    echo "Error: Server creation failed. The token may have insufficient scope." >&2
+    echo "Verify the token has Read+Write permissions for this sub-project." >&2
+    exit 1
+  fi
+
+  echo "Probe server created. Deleting..."
+
+  if ! hcloud server delete "$PROBE_NAME"; then
+    echo "" >&2
+    echo "Error: Server deletion failed. The probe server '${PROBE_NAME}' may still exist." >&2
+    echo "Delete manually: hcloud server delete '${PROBE_NAME}'" >&2
+    exit 1
+  fi
+
+  echo "Probe server deleted."
+)
+
+unset HCLOUD_TOKEN
+
+soleur_op_stage_end 2 "write-class smoke test (billable)" ok 0
+
+echo ""
+echo "Smoke-test passed: token has write scope for sub-project 'tenant-${SLUG}-prd'."
+echo ""
+echo "Next step: type /soleur:provision-cloudflare ${SLUG} <zone-id> <account-id> yourself (user-invoked; Soleur cannot run it, ADR-236)"

package/skills/provision-hetzner/test/fixture/knowledge-base/legal/tenant-dpa-register.md

@@ -0,0 +1,26 @@
+---
+title: "Tenant DPA register (SYNTHESIZED TEST FIXTURE — not the live register)"
+type: tenant-dpa-register-fixture
+status: fixture
+---
+
+# Tenant DPA register — synthesized fixture
+
+**This file is a test fixture.** Every value is synthesized (`cq-test-fixtures-synthesized-only`);
+no row describes a real tenant, a real legal entity, or a real founder. It exists because the DPA
+gate in `provision-hetzner.sh` runs BEFORE the `--dry-run` branch and reads
+`knowledge-base/legal/tenant-dpa-register.md` relative to the working directory — so a
+characterization suite running outside the repository exits 3 without a register to read.
+
+`Status` is the 7th visible column, which is `awk -F'|'` field `$8` (field `$1` is the empty
+string left of the leading pipe).
+
+## Rows
+
+| Tenant slug | Legal entity | Founder UUID | DPA signed date | DPA counter-signed date | Sub-processors (Schedule 2) | Status | Notes |
+|---|---|---|---|---|---|---|---|
+| fixture-tenant | Fixture Entity SARL | 00000000-0000-4000-8000-000000000000 | 2026-01-01 | 2026-01-02 | hetzner, cloudflare | dpa-signed | synthesized fixture row |
+| fixture-inflight | Fixture Inflight SARL | 00000000-0000-4000-8000-000000000001 | 2026-01-03 | | hetzner | provisioning-in-progress | synthesized fixture row |
+| fixture-revoked | Fixture Revoked SARL | 00000000-0000-4000-8000-000000000002 | 2026-01-04 | 2026-01-05 | hetzner | terminated | synthesized: must NOT pass the gate |
+| fixture-offboarded | Fixture Offboarded SARL | 00000000-0000-4000-8000-000000000003 | 2026-01-06 | 2026-01-07 | hetzner | dpa-signed | synthesized: historical row of an offboarded tenant (register is append-only) |
+| fixture-offboarded | Fixture Offboarded SARL | 00000000-0000-4000-8000-000000000003 | 2026-01-06 | 2026-01-07 | hetzner | terminated | synthesized: the LATER row wins; must NOT pass the gate |