@soleur/opencode 1.0.0 → 3.354.3

package/skills/verification-scaffold/references/guards/precommit-guard.sh.template

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# precommit-guard.sh — refuse `git commit` on main/master, without hook execution.
+#
+# Canonical source for the commit-on-main check (Soleur Cloud Mode, FR5).
+# Plugin command hooks are documented cloud-capable for most events, but a
+# skill cannot rely on hook execution in a not-local session — and user repos
+# consuming via requiredPlugins have no .claude/hooks at all. work/ship/one-shot
+# invoke this script directly so the refusal is structural in both worlds.
+#
+# Scope: commit-on-main ONLY. The DONE-marker stop-gate is not extractable —
+# it reads hook-stdin transcript data a standalone script cannot see; it stays
+# prose + the plugin Stop hook.
+#
+# Self-contained by design: no jq, no .claude/hooks/lib vendoring (those paths
+# resolve relative to the repo, which is wrong when this script runs from the
+# plugin install cache), no emit_incident — callers log their own incidents.
+# ONE sibling dependency: scripts/lib/wrapper-boundary.sh ships beside this
+# script in the plugin cache, so $(dirname)/lib/… resolves in both contexts
+# (#10248 — the canonical wrapper-prefix grammar the COMMIT_RE below consumes).
+#
+# Usage:
+#   precommit-guard.sh "COMMAND"        check a shell command string
+#   precommit-guard.sh --cwd DIR        also check DIR's branch (a `cd DIR &&`
+#                                       or `git -C DIR` inside COMMAND wins)
+#
+# Exit 0 = allowed (not a commit, or not on main/master).
+# Exit 1 = refused — reason on stderr.
+# Exit 2 = usage error.
+
+set -euo pipefail
+
+COMMAND=""
+CWD=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --cwd) CWD="${2:-}"; shift 2 ;;
+    -*) echo "precommit-guard.sh: unknown flag: $1" >&2; exit 2 ;;
+    *) COMMAND="$1"; shift ;;
+  esac
+done
+
+# Detection is per pipeline segment: a `git commit` can hide anywhere in a
+# chain — `git add && git commit`, `cd repo; git commit`, `printf msg |
+# git commit -F -`, `LEFTHOOK=0 git commit`. Split COMMAND on the chain
+# operators (&&, ||, ;, |, newline), then judge each segment.
+#
+# Known lexical limits (documented, not silently missed): subshell/eval forms
+# like `bash -c 'git commit'`, `$(git commit)`, `( git commit )`, quoted
+# `-C`/`cd` paths containing spaces, `git -c <cfg> commit` side effects beyond
+# detection, and commits created without `git commit` (merge/pull/cherry-pick/
+# rebase/continue) are out of this guard's declared scope — commit-on-main ONLY.
+# Opaque string payloads (`rtk run -c '…'`, `rtk summary --shell '…'`) join that
+# same declared class — the boundary fragment deliberately excludes the
+# -c/--command/--shell atoms so they cannot match here.
+_PC_GUARD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+unset VERIFICATION_ENV_ASN_RE VERIFICATION_LAUNCHER_RE VERIFICATION_RTK_RE VERIFICATION_BOUNDARY_PFX VERIFICATION_BOUNDARY_PFX_LOADED
+if [[ -f "$_PC_GUARD_DIR/lib/wrapper-boundary.sh" ]]; then
+  # shellcheck source=/dev/null
+  source "$_PC_GUARD_DIR/lib/wrapper-boundary.sh" 2>/dev/null || true
+fi
+if [[ "${VERIFICATION_BOUNDARY_PFX_LOADED:-0}" != 1 ]]; then
+  unset VERIFICATION_ENV_ASN_RE VERIFICATION_LAUNCHER_RE VERIFICATION_RTK_RE VERIFICATION_BOUNDARY_PFX
+  echo "precommit-guard.sh: wrapper-boundary.sh unavailable at $_PC_GUARD_DIR/lib — commit gate runs pre-#10248 matching" >&2
+fi
+unset _PC_GUARD_DIR
+# #10248: the shared fragment replaces the inline env-asn/launcher alternation —
+# one canonical atom set for every boundary-anchored gate. The :- fallback is
+# the PRE-FIX atom set (env + launcher) — a superset of this file's prior
+# env*/launcher?/env* sandwich, which is the safe direction for a deny gate.
+COMMIT_RE='^[[:space:]]*('"${VERIFICATION_BOUNDARY_PFX:-([A-Za-z_][A-Za-z_0-9]*=[^[:space:]]+|sudo|command|nice|env|xargs)}"'[[:space:]]+)*git([[:space:]]+(-C[[:space:]]+[^[:space:]]+|-c[[:space:]]+[^[:space:]]+|--git-dir=[^[:space:]]+|--git-dir[[:space:]]+[^[:space:]]+|-[A-Za-z]))*[[:space:]]+commit([[:space:]]|$)'
+
+last_cd=""
+while IFS= read -r seg; do
+  # Track the dir the chain has cd'd into — it applies to later segments.
+  cd_hit="$(grep -oE '(^|[[:space:]])cd[[:space:]]+[^[:space:]]+' <<<"$seg" | tail -n 1 | sed -E 's/.*cd[[:space:]]+//' || true)"
+  [[ -n "$cd_hit" ]] && last_cd="$cd_hit"
+
+  grep -qE "$COMMIT_RE" <<<"$seg" || continue
+
+  # Resolve the repo THIS segment commits into. Priority: the -C / --git-dir
+  # attached to the commit's own git invocation, then a GIT_DIR env-assignment
+  # prefix (LEFTHOOK=0-style prefixes are the reason env-assignments are scanned
+  # at all — dropping GIT_DIR would resolve the wrong repo); then the chain's
+  # most recent cd; then --cwd; then ambient $PWD.
+  target="" git_dir=""
+  if grep -qoE -- '--git-dir[=[:space:]][^[:space:]]+' <<<"$seg"; then
+    git_dir="$(grep -oE -- '--git-dir[=[:space:]][^[:space:]]+' <<<"$seg" | tail -n 1 | sed -E 's/^--git-dir[=[:space:]]+//' || true)"
+  elif grep -qoE -- '(^|[[:space:]])GIT_DIR=[^[:space:]]+' <<<"$seg"; then
+    git_dir="$(grep -oE -- '(^|[[:space:]])GIT_DIR=[^[:space:]]+' <<<"$seg" | tail -n 1 | sed -E 's/.*GIT_DIR=//' || true)"
+  else
+    git_c="$(grep -oE -- '-C[[:space:]]+[^[:space:]]+' <<<"$seg" | tail -n 1 | sed -E 's/^-C[[:space:]]+//' || true)"
+    [[ -n "$git_c" ]] && target="$git_c"
+  fi
+  if [[ -z "$target" && -z "$git_dir" ]]; then
+    for cand in "$last_cd" "$CWD" "$PWD"; do
+      [[ -n "$cand" && -d "$cand" ]] && target="$cand" && break
+    done
+  fi
+
+  if [[ -n "$git_dir" ]]; then
+    BRANCH="$(git --git-dir="$git_dir" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  elif [[ -n "$target" && -d "$target" ]]; then
+    BRANCH="$(git -C "$target" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  else
+    continue # nowhere to resolve — nothing to refuse on
+  fi
+  # The alternation is the stamped default-branch set — soleur:verification-scaffold
+  # emits this file with `@DEFAULT_BRANCHES@` substituted for the target's resolved default.
+  if [[ "$BRANCH" =~ ^(@DEFAULT_BRANCHES@)$ ]]; then
+    printf 'BLOCKED: Committing directly to %s is not allowed. Create a feature branch first.\n' "$BRANCH" >&2
+    exit 1
+  fi
+done < <(printf '%s\n' "$COMMAND" | sed -E 's/&&|\|\||[;|]/\n/g')
+
+exit 0

package/skills/verification-scaffold/references/guards/secret-scan-hook.sh.template

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# secret-scan.sh — PreToolUse hook emitted by soleur:verification-scaffold.
+# Scans the staged index for secret-shaped strings (PEM bodies, vendor tokens,
+# cloud keys) via gitleaks and reports before a `git commit` tool call lands.
+#
+# MODE=@MODE@ — stamped at emit time:
+#   advisory (the installed default): real findings surface as `ask`; tool
+#     errors (missing/unrunnable gitleaks, absent ruleset, empty report) warn
+#     and allow — loudly, never silently.
+#   enforce: findings deny; tool errors deny with the install remediation.
+# Promote by changing MODE to "enforce" — a one-line flip. The predicates are
+# identical in both modes; only the terminal decision changes.
+#
+# Hook stdin: JSON payload with tool_input. Hook stdout: the PreToolUse JSON
+# decision envelope. Exit code is always 0 — the envelope carries the verdict.
+#
+# Portability floor: bash + POSIX tools only (stock macOS included — the
+# timeout->gtimeout->bare-fallback below is deliberate). No network egress.
+set -euo pipefail
+
+MODE="@MODE@"
+
+# --- decision envelopes -------------------------------------------------------
+# _vs_decide <allow|ask|deny> [reason]: one JSON envelope on stdout, exit 0.
+# Reasons are escaped (backslash, quote, newline) before embedding.
+_vs_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr '\n' ' '; }
+_vs_decide() {
+  local d="$1" r="${2:-}"
+  if [ -n "$r" ]; then
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"%s","permissionDecisionReason":"%s"}}\n' \
+      "$d" "$(_vs_escape "$r")"
+  else
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"%s"}}\n' "$d"
+  fi
+  exit 0
+}
+_vs_allow() { _vs_decide allow; }
+# _vs_tool_error <msg>: a scanner/tool problem, never a finding. Advisory warns
+# and allows; enforce denies with remediation. `ask` can never fire on this path.
+_vs_tool_error() {
+  local msg="secret-scan: $1"
+  printf '[secret-scan] WARN: %s\n' "$msg" >&2
+  if [ "$MODE" = "enforce" ]; then
+    _vs_decide deny "BLOCKED: $msg"
+  else
+    _vs_decide allow
+  fi
+}
+# _vs_finding <msg>: a REAL finding — the only path that may `ask`.
+_vs_finding() {
+  if [ "$MODE" = "enforce" ]; then
+    _vs_decide deny "BLOCKED: $1"
+  else
+    _vs_decide ask "$1"
+  fi
+}
+
+# --- stdin command extraction (jq -> node -> sed fallback) --------------------
+_vs_payload="$(cat)"
+_vs_cmd=""
+if command -v jq >/dev/null 2>&1; then
+  _vs_cmd="$(printf '%s' "$_vs_payload" | jq -r '.tool_input.command // ""' 2>/dev/null || true)"
+elif command -v node >/dev/null 2>&1; then
+  _vs_cmd="$(printf '%s' "$_vs_payload" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const c=JSON.parse(s).tool_input.command;process.stdout.write(typeof c==="string"?c:"")}catch(e){}})' 2>/dev/null || true)"
+else
+  # Last-resort extraction: handles the common single-quoted-string shape.
+  # Documented limit: escaped quotes inside the command truncate the value,
+  # which only ever DE-escalates this hook (the CI job still scans the push).
+  _vs_cmd="$(printf '%s' "$_vs_payload" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)"
+fi
+[ -n "$_vs_cmd" ] || _vs_allow
+
+# `git commit` at a command boundary: start, or after &&, ||, ;, |, $(.
+# Trailing space-or-end rejects commit-tree/commit-graph.
+if ! grep -qE '(^|[[:space:]]|&&|\|\||;|\$\()[[:space:]]*git[[:space:]]+commit([[:space:]]|$)' <<<"$_vs_cmd"; then
+  _vs_allow
+fi
+
+# --- environment guards -------------------------------------------------------
+GL_REMEDIATION="install gitleaks 8.24.x (e.g. 'mise use gitleaks@8.24.2' or 'brew install gitleaks') — the CI job scans every PR regardless."
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  _vs_allow
+fi
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$repo_root" ] || [ ! -f "$repo_root/.gitleaks.toml" ]; then
+  _vs_tool_error ".gitleaks.toml not found at the repo root — the staged scan was skipped. $GL_REMEDIATION"
+fi
+if ! command -v gitleaks >/dev/null 2>&1; then
+  _vs_tool_error "gitleaks is not on PATH — the staged scan was skipped. $GL_REMEDIATION"
+fi
+
+# Resolvable is not runnable: probe the binary, bounded when a bound exists
+# (stock macOS has neither timeout nor gtimeout — a missing bound must never
+# read as a broken scanner).
+gl_to=()
+if command -v timeout >/dev/null 2>&1; then gl_to=(timeout 10)
+elif command -v gtimeout >/dev/null 2>&1; then gl_to=(gtimeout 10); fi
+gl_rc=0
+{ ${gl_to[@]+"${gl_to[@]}"} gitleaks version >/dev/null; } 2>/dev/null || gl_rc=$?
+if [ "$gl_rc" -ne 0 ]; then
+  _vs_tool_error "gitleaks resolves on PATH but cannot run (rc=$gl_rc — an unpinned version-manager shim?). $GL_REMEDIATION"
+fi
+
+# --- staged scan ---------------------------------------------------------------
+# Colour is pinned off on BOTH config surfaces: gitleaks runs git itself, and a
+# user-side color.ui/color.diff=always wraps patch lines in ANSI, which makes
+# the scan report ZERO findings on a staged key (measured). GIT_CONFIG_COUNT
+# appends so a caller's own -c settings survive; GIT_CONFIG_PARAMETERS is a
+# separate source read AFTER the count list, so it is pinned too.
+report_file="$(mktemp -t verification-scan-XXXXXX.json)"
+nodiff_dir="$(mktemp -d -t verification-nodiff-XXXXXX)"
+nodiff_report="$(mktemp -t verification-nodiff-XXXXXX.json)"
+trap 'rm -f "$report_file" "$nodiff_report"; rm -rf "$nodiff_dir"' EXIT INT TERM
+
+gl_cfg_n="${GIT_CONFIG_COUNT:-0}"
+case "$gl_cfg_n" in ''|*[!0-9]*) gl_cfg_n=0 ;; esac
+scan_rc=0
+(
+  cd "$repo_root" || exit 1
+  env "GIT_CONFIG_COUNT=$((gl_cfg_n + 2))" \
+    "GIT_CONFIG_KEY_${gl_cfg_n}=color.ui" "GIT_CONFIG_VALUE_${gl_cfg_n}=never" \
+    "GIT_CONFIG_KEY_$((gl_cfg_n + 1))=color.diff" "GIT_CONFIG_VALUE_$((gl_cfg_n + 1))=never" \
+    "GIT_CONFIG_PARAMETERS=${GIT_CONFIG_PARAMETERS:+${GIT_CONFIG_PARAMETERS} }'color.ui'='never' 'color.diff'='never'" \
+    gitleaks git --pre-commit --staged --redact --no-banner --exit-code 1 \
+      --report-format json --report-path "$report_file" >/dev/null 2>&1
+) || scan_rc=$?
+
+# -diff gitattribute bypass: a path marked -diff renders "Binary files …
+# differ" with no `+` lines, so the staged scan sees nothing in it. Re-scan
+# those paths from their STAGED blobs with `detect --no-git`, which never
+# consults git's diff machinery.
+gl_nodiff=()
+while IFS= read -r -d '' _p; do
+  [ -n "$_p" ] || continue
+  if [ "$(git -C "$repo_root" check-attr diff -- "$_p" 2>/dev/null | sed 's/.*: //')" = "unset" ]; then
+    gl_nodiff+=("$_p")
+  fi
+done < <(git -C "$repo_root" diff --cached --name-only -z --diff-filter=ACMR 2>/dev/null)
+
+if (( ${#gl_nodiff[@]} > 0 )); then
+  for _p in "${gl_nodiff[@]}"; do
+    mkdir -p "$nodiff_dir/$(dirname "$_p")" 2>/dev/null || true
+    git -C "$repo_root" show ":$_p" > "$nodiff_dir/$_p" 2>/dev/null || true
+  done
+  nodiff_rc=0
+  gitleaks detect --no-git --source "$nodiff_dir" --redact --no-banner --exit-code 1 \
+    --report-format json --report-path "$nodiff_report" >/dev/null 2>&1 || nodiff_rc=$?
+  if [ "$nodiff_rc" -eq 1 ] && [ -s "$nodiff_report" ]; then
+    nd_count="$(grep -c '"RuleID"' "$nodiff_report" 2>/dev/null || echo 0)"
+    nd_files="$(printf '%s, ' "${gl_nodiff[@]}")"
+    _vs_finding "gitleaks found ${nd_count} secret-shaped string(s) in staged file(s) carrying a \`-diff\` gitattribute (${nd_files%, }), which hides them from the staged scan — they were re-scanned from their staged blobs. Scrub the secret bytes; if the attribute is not deliberate, remove it."
+  elif [ "$nodiff_rc" -ne 0 ] && [ "$nodiff_rc" -ne 1 ]; then
+    _vs_tool_error "the -diff re-scan exited $nodiff_rc without a findings report; those paths were NOT verified."
+  fi
+fi
+
+if [ "$scan_rc" -eq 0 ]; then
+  _vs_allow
+fi
+
+# Non-zero scan rc with an empty/absent report is a scanner failure, not a
+# finding — it takes the tool-error path in both modes.
+if [ ! -s "$report_file" ] || ! grep -q '"RuleID"' "$report_file" 2>/dev/null; then
+  _vs_tool_error "gitleaks exited $scan_rc but produced no findings report; the staged content was NOT scanned. Run 'gitleaks git --pre-commit --staged' locally to diagnose. $GL_REMEDIATION"
+fi
+
+count="$(grep -c '"RuleID"' "$report_file" 2>/dev/null || echo 0)"
+if command -v jq >/dev/null 2>&1; then
+  summary="$(jq -r '[.[] | "\(.File):\(.StartLine) (\(.RuleID))"] | .[0:5] | join("; ")' "$report_file" 2>/dev/null || echo "")"
+else
+  summary="$(grep -o '"File": *"[^"]*"' "$report_file" 2>/dev/null | head -n 5 | sed 's/"File": *"//; s/"$//' | tr '\n' '; ' || true)"
+fi
+reason="gitleaks found ${count} secret-shaped string(s) in the staged index. Locations: ${summary:-<redacted>}. Scrub the secrets — never commit-then-rotate. Unstage with 'git restore --staged <path>', redact in place, re-stage and retry. To mark a known-safe line, annotate it '# gitleaks:allow issue:#NNN <reason>'." # waiver-doc string (issue:#10404 teaches trailer form)
+
+_vs_finding "$reason"

package/skills/verification-scaffold/references/guards/verification-gates.yml.template

@@ -0,0 +1,49 @@
+# verification-gates.yml — emitted by soleur:verification-scaffold at the
+# REPOSITORY ROOT (.github/workflows only runs from the root — a nested copy is
+# dormant). Jobs below run advisory-first: `continue-on-error` is the chokepoint
+# the promotion step flips (see VERIFICATION.md).
+#
+# Marker convention for the emitter — a job block between
+# `# verification-scaffold:begin:<guard>` and `# verification-scaffold:end:<guard>`
+# is kept only when that guard is selected. Do not remove the markers.
+name: verification-gates
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # verification-scaffold:begin:secret-scan
+  secret-scan:
+    name: secret-scan (gitleaks)
+    runs-on: ubuntu-latest
+    continue-on-error: @CI_CONTINUE_ON_ERROR@
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: gitleaks staged+tree scan
+        # Pinned by commit SHA (supply-chain posture — never a mutable tag).
+        # Resolves gitleaks-action v2.3.9.
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7
+        env:
+          GITLEAKS_ENABLE_COMMENTS: "false"
+          GITLEAKS_ENABLE_SUMMARY: "true"
+          # Honour the emitted ruleset when the repo carries one.
+          GITLEAKS_CONFIG: ".gitleaks.toml"
+  # verification-scaffold:end:secret-scan
+  # verification-scaffold:begin:orphan-test
+  orphan-test:
+    name: orphan-test registration check
+    runs-on: ubuntu-latest
+    continue-on-error: @CI_CONTINUE_ON_ERROR@
+    env:
+      # Declare the files that RUN your suites; the check searches them for each
+      # tracked *.test.sh basename. Glob runner files are fine.
+      RUNNER_GLOBS: "scripts/test-all.sh scripts/run-tests* Makefile makefile package.json"
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: orphan-test check
+        run: bash scripts/verification/orphan-test-check.sh
+  # verification-scaffold:end:orphan-test

package/skills/verification-scaffold/references/guards/wrapper-boundary.sh.template

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# wrapper-boundary.sh — canonical inter-boundary prefix grammar (#10248).
+#
+# Boundary-anchored gates grep for a gated command anchored at a shell chain
+# boundary (`(^|&&|\|\||;|\s--\s)` and siblings). That anchor is blind to
+# command wrappers: `rtk gh pr merge`, `sudo git commit`, `X=1 gh pr merge`
+# all sit between the boundary and the gated command. ONE shared fragment —
+# interpolated by every site — gives ~20 boundary-anchored gates a common
+# wrapper-prefix grammar (only ~4 sites had any prefix list before; the rest
+# had none — that absence was the defect) so the wrapper set cannot silently
+# drift (#10248; same argv-prefix class as PR #3689's `with_lock` bypass, learnings
+# 2026-05-12-cross-session-lock-lease-bash-primitives.md SE1).
+#
+# Consumption idiom — insert between the boundary alternation and the gated
+# command:
+#   (<boundary-alternation>)[[:space:]]*(${VERIFICATION_BOUNDARY_PFX:-}[[:space:]]+)*<gated-cmd>
+# The `:-` default is load-bearing: several hooks run `set -u`, and an unset
+# fragment degrades to pre-fix matching (status quo), never a hard error and
+# never a new hole. The required trailing `[[:space:]]+` after each atom is the
+# right-edge word boundary: `rtk-foo`, `artk`, `sudox`, `FOO` (no `=`) can never
+# partially consume — the wrapper word must be a whole word between the boundary
+# and the gated command.
+#
+# Restatement pin: the rtk atom below restates exec-subcommand and global-flag
+# rows of lib/ext-filter-grammar.tsv (the argv[0]-unwrap class's canonical
+# grammar, #10230); test/rtk-grammar-parity.test.sh asserts set equality by
+# extraction — edit the TSV and this atom together. The atom admits ONLY inert
+# grammar words (counted-verbose globals, --skip-env, the six exec subcommands);
+# a string-payload flag (-c|--command|--shell) is NOT an atom, so
+# `rtk run -c 'gh pr merge'` stops the prefix at `run` and cannot match — the
+# opaque-payload class joins the pre-existing `bash -c '…'` lexical limit every
+# boundary gate already declares (#10248 CTO ruling, decision-challenges row 2).
+
+VERIFICATION_ENV_ASN_RE='[A-Za-z_][A-Za-z_0-9]*=[^[:space:]]+'
+VERIFICATION_LAUNCHER_RE='(sudo|command|nice|env|xargs)'
+# Globals: -v/-vv/-vvv/--verbose (counted) and --skip-env (takes an optional
+# =value — the argv[0]-unwrap SUT accepts both spellings). Exec subcommands:
+# run|err|test|proxy|bypass|summary (canonical TSV, class=exec). `--` is the
+# clap end-of-options marker — inert anywhere in the wrapper span, so
+# `rtk -- run gh` and `rtk run -- gh` both execute `gh` upstream and both
+# must reach the gated literal here (canonical TSV flag-global row).
+VERIFICATION_RTK_RE='rtk([[:space:]]+(-v|-vv|-vvv|--verbose|--skip-env(=[^[:space:]]+)?|--|run|err|test|proxy|bypass|summary))*'
+VERIFICATION_BOUNDARY_PFX="(${VERIFICATION_ENV_ASN_RE}|${VERIFICATION_LAUNCHER_RE}|${VERIFICATION_RTK_RE})"
+
+# Load sentinel — suites assert this, never `[[ -n "$VERIFICATION_BOUNDARY_PFX" ]]`,
+# which an inherited environment value would satisfy even after a failed source.
+VERIFICATION_BOUNDARY_PFX_LOADED=1

package/skills/verification-scaffold/references/guards.tsv

@@ -0,0 +1,21 @@
+# verification-scaffold guard manifest (#10404) — the machine form of guardrail-audit.md.
+# One row per installable guard. Columns:
+#   name         guard id the CLI accepts (--guards/--uninstall/--list)
+#   verdict      audit verdict (references/guardrail-audit.md) — every v1 row is
+#                generic-after-extraction by construction
+#   surfaces     hook | ci | hook+ci — which emitted surfaces the guard owns
+#   templates    `;`-separated template paths under references/ this row emits
+#   default_mode advisory — every v1 guard installs advisory-first (flip MODE= / drop
+#                continue-on-error to promote; emitted VERIFICATION.md names the step)
+#   deps         external deps the emitted guard needs at the target (NOT satisfied by
+#                the emit; checked and named, never silently assumed)
+#   source_files `;`-separated repo sources the templates were extracted from (provenance;
+#                the near-verbatim pair is byte-pinned by test/manifest.test.sh)
+#   emits        `;`-separated target-relative artifact paths this guard emits
+#   tier         v1 | v2 — v2 rows are candidates only; the generator refuses to emit them
+name	verdict	surfaces	templates	default_mode	deps	source_files	emits	tier
+secret-scan	generic-after-extraction	hook+ci	references/guards/secret-scan-hook.sh.template;references/gitleaks.toml.template;references/guards/verification-gates.yml.template	advisory	gitleaks 8.24.x on PATH (hook) or gitleaks-action (CI);jq or node for the settings merge	.claude/hooks/git-commit-secret-scan.sh	.claude/hooks/secret-scan.sh;.gitleaks.toml;.github/workflows/verification-gates.yml	v1
+commit-on-main	generic-after-extraction	hook	references/guards/commit-on-main-hook.sh.template;references/guards/precommit-guard.sh.template;references/guards/wrapper-boundary.sh.template	advisory	git	plugins/soleur/scripts/precommit-guard.sh;plugins/soleur/scripts/lib/wrapper-boundary.sh;.claude/hooks/guardrails.sh	.claude/hooks/commit-on-main.sh;scripts/verification/precommit-guard.sh;scripts/verification/lib/wrapper-boundary.sh	v1
+block-stash	generic-after-extraction	hook	references/guards/block-stash-hook.sh.template	advisory	git	.claude/hooks/guardrails.sh	.claude/hooks/block-stash.sh	v1
+orphan-test	generic-after-extraction	ci	references/guards/orphan-test-check.sh.template;references/guards/verification-gates.yml.template	advisory	git	scripts/lint-orphan-test-suites.sh	scripts/verification/orphan-test-check.sh;.github/workflows/verification-gates.yml;.github/verification-known-orphans.txt	v1
+block-rm-rf	generic-after-extraction	hook	-	advisory	git	.claude/hooks/guardrails.sh	.claude/hooks/block-rm-rf.sh	v2

package/skills/verification-scaffold/references/verification-readme.template

@@ -0,0 +1,55 @@
+<!-- verification-scaffold:readme:start -->
+## Verification gates (installed by soleur:verification-scaffold)
+
+Installed mode: **@MODE@** · installed guards: **@GUARD_LIST@** · generated @DATE@.
+
+| Guard | Artifacts | Decides |
+|---|---|---|
+@GUARD_TABLE@
+
+### What advisory means
+
+Every guard was installed **advisory-first**: hooks warn (or ask, on a real
+secret-scan finding) instead of denying, and each CI job carries
+`continue-on-error: true`, so nothing blocks a commit or a PR yet. Advisory is
+a decision-verb difference only — the detection predicates are identical to
+enforcement mode.
+
+### Promoting a guard to enforcement (one line per surface)
+
+Promote only after **at least one observed clean advisory run** — a gate that
+has never run green is a wall, not a floor.
+
+- Hooks (`.claude/hooks/<guard>.sh`): change `MODE="advisory"` to `MODE="enforce"`.
+- CI (`.github/workflows/verification-gates.yml`): set the job's
+  `continue-on-error` to `false` (or remove the line), then add the check to
+  the branch's required status checks. Note `commit-on-main`/`block-stash` are
+  hook-only — branch protection on the remote is the enforcement floor for the
+  *default branch itself*.
+- Re-running the scaffold NEVER overwrites your edits: re-install refuses on
+  any existing artifact (there is no `--force`).
+
+### Uninstall
+
+```bash
+bash <plugin>/skills/verification-scaffold/scripts/verification-scaffold.sh --target . --uninstall <guard>
+```
+
+removes only that guard's emitted files plus its `.claude/settings.json` hook
+entry; shared artifacts (the workflow, `.gitleaks.toml` when another guard
+still needs it) stay — the workflow is only edited when this guard's job block
+is actually present. `--uninstall` on a never-installed guard is a no-op that
+lists what is installed, and once no guard artifact remains this marker block
+is pruned (a file that held only this block is removed).
+
+### Requirements
+
+- bash + POSIX tools (stock macOS included). Emitted hooks resolve `gitleaks`
+  via `command -v` at exec time; the CI job uses the SHA-pinned
+  `gitleaks/gitleaks-action`.
+- The secret-scan hook needs `gitleaks` on PATH to run locally (8.24.x
+  recommended); without it the hook warns and allows (advisory) — the CI job
+  still scans every PR.
+- `.claude/settings.json` hook entries serve Claude-Code-compatible agent
+  sessions; the workflow is the floor for everyone else.
+<!-- verification-scaffold:readme:end -->