@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/verification-scaffold/references/guardrail-audit.md

@@ -0,0 +1,156 @@
+# Guardrail corpus audit — `.claude/hooks/` + `scripts/lint-*` (#10404)
+
+Census date: 2026-10-21. Corpus definition (enforced by `test/manifest.test.sh`,
+which re-derives this set from `git ls-files` — a new member with no row here is a
+CI failure):
+
+- `.claude/hooks/**/*.sh`, excluding `*.test.sh` and files under `/test/` — **56 files**.
+- `scripts/lint-*`, excluding `*.test.sh`, `*.baseline.txt`, `*.highwater*` — **46 files**.
+
+## Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `generic` | Repo-generic as it stands: no Soleur-domain coupling; could run in an arbitrary repository with at most path arguments. |
+| `generic-after-extraction` | The *guard idea* is repo-generic but the file carries couplings (incident machinery, shared libs, Soleur paths or rule ids) that dead-reference in a user repo. Shippable only as a template. |
+| `soleur-coupled` | The guard's *purpose* is Soleur's: it enforces a Soleur rule id, a Soleur corpus path, a vendor in Soleur's stack, or Soleur telemetry/workflow machinery. Not shipped. |
+
+**Counts:** hooks — 0 generic / 10 generic-after-extraction / 47 soleur-coupled.
+lints — 9 generic / 8 generic-after-extraction / 29 soleur-coupled.
+
+The canonical emit pair `plugins/soleur/scripts/precommit-guard.sh` +
+`plugins/soleur/scripts/lib/wrapper-boundary.sh` is NOT in the census set (it
+lives under `plugins/`, not `.claude/hooks/` or `scripts/lint-*`); it is the
+source the v1 `commit-on-main` guard emits near-verbatim. Likewise
+`.claude/hooks/guardrails.sh` is classified as a whole file; the v1 `block-stash`
+guard extracts its `block-stash-in-worktrees` arm (guardrails.sh:471) as a
+template rather than shipping the monolith.
+
+## Census — `.claude/hooks/` (56)
+
+| File | Verdict | Rationale |
+|---|---|---|
+| `agent-token-tee.sh` | soleur-coupled | Task telemetry into `.claude/.session-tokens.jsonl`, consumed by Soleur `compound` Phase 1.6. |
+| `background-poll-prefer-monitor.sh` | soleur-coupled | Enforces `hr-monitor-not-run-in-background-for-polling` — a Soleur rule keyed to the harness Monitor tool. |
+| `bare-head-self-heal.sh` | soleur-coupled | Repairs Soleur's bare-repo+worktree topology; meaningless in an ordinary clone. |
+| `bare-root-cwd-guard.sh` | soleur-coupled | Same bare-repo topology guard (cwd under the bare root). |
+| `brand-hex-commit-gate.sh` | soleur-coupled | Soleur brand-corpus hex gate. |
+| `cla-signed-author-gate.sh` | soleur-coupled | Keys on `noreply@anthropic.com`, the Soleur `cla-check` required status, `wg-cla-signed-author-before-merge`. |
+| `context-reviewed-gate.sh` | generic-after-extraction | `last_reviewed:`-trailer audit tripwire is format-generic (v2); couplings = `incidents.sh` + `hook-input.sh` sourcing. |
+| `docs-cli-verification.sh` | generic-after-extraction | Advisory "verified CLI" docs lint (v2); couplings = `incidents.sh` + a Soleur file-pattern gate (`apps/**/page.*`). |
+| `doppler-secrets-delete-redirect.sh` | soleur-coupled | Doppler vendor redirect. |
+| `durable-reminder-prefer-inngest.sh` | soleur-coupled | Inngest vendor preference in Soleur's app stack. |
+| `follow-through-directive-gate.sh` | soleur-coupled | Soleur follow-through directive machinery. |
+| `git-commit-secret-scan.sh` | generic-after-extraction | **v1 `secret-scan` source.** Couplings: `lib/hook-input.sh`, `incidents.sh` emits, `jq`, the repo `.gitleaks.toml`; the staged-scan predicate and colour pins are repo-generic. |
+| `grep-rewrite.sh` | soleur-coupled | Neutralizes one observed ugrep `grep` shim — environment remediation, not a general guard (ADR-162). |
+| `guardrails.sh` | soleur-coupled | Monolith wired to `lib/freeze-lock.sh` + `incidents.sh` + the Soleur rule corpus. Its `block-stash-in-worktrees` arm (:471) is extracted as v1 `block-stash`; its `block-commit-on-main` arm delegates to `precommit-guard.sh`, which v1 emits instead. `block-rm-rf` arms (:185, :200) stay v2 — they read `lib/freeze-lock.sh` state and are not self-contained. |
+| `iac-plan-write-guard.sh` | soleur-coupled | Enforces `hr-all-infrastructure-provisioning` on Soleur plan/spec files. |
+| `kb-domain-allowlist-guard.sh` | soleur-coupled | `knowledge-base/` domain allowlist — Soleur corpus structure. |
+| `lib/context-sanitize.sh` | generic-after-extraction | Pure display-boundary sanitizer already byte-twinned plugin-side (v2). |
+| `lib/freeze-lock.sh` | soleur-coupled | `guardrails.sh` freeze-state machinery. |
+| `lib/hook-input.sh` | generic-after-extraction | Harness-generic hook-stdin parser (ADR-156/157). v1 templates self-contain their parse, so it is not emitted; a v2 hook needing it must inline it. |
+| `lib/hook-tool-kind.sh` | generic-after-extraction | Devin→Claude tool-kind map (#8205) — harness-generic, not Soleur-domain (v2). |
+| `lib/incidents.sh` | soleur-coupled | The `emit_incident` sink — the corpus's named coupling; emitted guards strip its calls. |
+| `lib/log-rotation.sh` | generic-after-extraction | `.claude/*.jsonl` rotation util; logic portable, callers Soleur telemetry sinks (v2). |
+| `lib/commit-target-roots.sh` | soleur-coupled | Commit-target argv walker for `git-commit-secret-scan.sh` (#10609) — depends on `plugins/soleur/hooks/lib/shell-argv.pl`, the repo's hardened lexer; the emitted `secret-scan` template self-contains its parse instead. |
+| `lib/monitor-sig.sh` | soleur-coupled | Monitor-ledger signature shared by the two monitor hooks. |
+| `lib/technical-fork-cues.sh` | soleur-coupled | Cue vocabulary for `hr-technical-fork-is-not-an-operator-question`. |
+| `lib/test-incident-sandbox.sh` | soleur-coupled | Test sandbox for `incidents.sh`. |
+| `memory-backstop-mutation-battery.sh` | soleur-coupled | Mutation battery for `memory-backstop.sh`; needs a live systemd user bus. |
+| `memory-backstop-resolve.sh` | soleur-coupled | Shim resolving the newest `memory-backstop.sh` across checkouts. |
+| `memory-backstop.sh` | soleur-coupled | Soleur `~/.claude` memory protection. |
+| `monitor-arm-recorder.sh` | soleur-coupled | Monitor-ledger writer. |
+| `monitor-supersede-guard.sh` | soleur-coupled | Monitor-ledger reader. |
+| `new-scheduled-cron-prefer-inngest.sh` | soleur-coupled | Inngest vendor preference. |
+| `no-memory-write.sh` | soleur-coupled | Soleur memory-directory write ban. |
+| `pencil-collapse-guard.sh` | soleur-coupled | Pencil MCP `.pen` recovery. |
+| `pencil-open-guard.sh` | soleur-coupled | Pencil MCP + `cq-` rule. |
+| `phase-surface-hint.sh` | soleur-coupled | Soleur `.claude/phase-surface-map.json` phase vocabulary (ADR-070). |
+| `pkill-self-match-guard.sh` | generic-after-extraction | Universal self-match class (`pkill -f`, `ps\|grep`); couplings = lazy `incidents.sh` emit + a `proc.sh` pointer (v2). |
+| `post-dispatch-watch-gate.sh` | soleur-coupled | Soleur monitor/watch ledger (`hr-dispatch-async-must-arm-watch`). |
+| `pre-ask-technical-fork-gate.sh` | soleur-coupled | `hr-technical-fork` on AskUserQuestion. |
+| `pre-closing-technical-fork-gate.sh` | soleur-coupled | Same rule on the closing carrier. |
+| `pre-merge-auto-close-scan.sh` | soleur-coupled | `gh pr merge` close-keyword scan bound to the Soleur `follow-through` label. |
+| `pre-merge-rebase.sh` | soleur-coupled | Soleur merge-flow gate. |
+| `prod-write-defer-gate.sh` | soleur-coupled | Soleur prod-write surface definitions. |
+| `rule-incident-marker-capture.sh` | soleur-coupled | Soleur rule-incident marker capture. |
+| `session-rules-loader.sh` | soleur-coupled | Loads `AGENTS.rules.md` — the Soleur rule corpus itself. |
+| `ship-kb-archive-gate.sh` | soleur-coupled | `soleur:ship` KB-archive gate. |
+| `ship-net-issue-flow-gate.sh` | soleur-coupled | ship flow. |
+| `ship-operator-step-gate.sh` | soleur-coupled | ship flow. |
+| `ship-runbook-ssh-gate.sh` | soleur-coupled | ship flow. |
+| `ship-soak-followthrough-gate.sh` | soleur-coupled | ship flow. |
+| `ship-unpushed-commits-gate.sh` | generic-after-extraction | `gh pr merge` denied while `git rev-list origin/<branch>..HEAD` is non-zero — the predicate is repo-generic (v2); couplings = `hook-input.sh`/`jq` stdin parse. |
+| `skill-context-queries.sh` | soleur-coupled | Soleur skill-context plumbing. |
+| `skill-invocation-logger.sh` | soleur-coupled | Soleur skill-invocation telemetry sink. |
+| `skill-security-scan.sh` | soleur-coupled | Invokes the skill-security-scan skill under the payload via a `$PROJECT_DIR` prefix. |
+| `skill-security-scan-write.sh` | soleur-coupled | Same scanner plus `plugins/soleur` write paths. |
+| `supabase-loopback-warn.sh` | soleur-coupled | Supabase vendor stack check (ADR-153). |
+| `worktree-write-guard.sh` | generic-after-extraction | Blocks writes to the main checkout while worktrees exist — repo-generic idea (v2); couplings = `incidents.sh`/`hook-input.sh` sourcing. |
+
+## Census — `scripts/lint-*` (46)
+
+| File | Verdict | Rationale |
+|---|---|---|
+| `lint-agents-compound-sync.sh` | soleur-coupled | AGENTS budget contract across the plugin corpus. |
+| `lint-agents-enforcement-tags.py` | soleur-coupled | AGENTS `[hook-enforced:]`/`[skill-enforced:]` tag registry. |
+| `lint-agents-rule-budget.py` | soleur-coupled | `AGENTS.{md,rules.md}` byte budgets. |
+| `lint-anthropic-content-position.py` | soleur-coupled | Anthropic-harness reader lint; scans `knowledge-base/` + Soleur call sites. |
+| `lint-art30-reverification.sh` | soleur-coupled | GDPR Art.30 register/trigger corpus (`knowledge-base/legal/`). |
+| `lint-betterstack-emitter-read.sh` | soleur-coupled | BetterStack emitter corpus. |
+| `lint-bot-synthetic-completeness.sh` | generic-after-extraction | Synthetic check-run completeness for bot-authored PRs is generic (v2); coupling = the `pr-quality-guards.yml` exemption name. |
+| `lint-bot-synthetic-statuses.sh` | generic-after-extraction | `[skip ci]` ban on bot PRs is generic (v2); same named exemptions. |
+| `lint-conversations-update-callsites.sh` | soleur-coupled | `apps/web-platform/server` module boundary. |
+| `lint-credential-path-literals.py` | soleur-coupled | SCAN_DIRS = `plugins/` + `knowledge-base/`. |
+| `lint-diagnosis-claims.sh` | generic-after-extraction | "CI message may not name a cause the job did not measure" is generic (v2); scope names `apps/web-platform/infra/`. |
+| `lint-distribution-content.sh` | soleur-coupled | `knowledge-base/marketing/distribution-content/` marker lint. |
+| `lint-doppler-description-length.py` | soleur-coupled | Doppler description contract over `*.tf`. |
+| `lint-dual-lockfile.sh` | generic | `git ls-files`-driven npm-lockfile-of-record guard; Soleur mentions are comments only. |
+| `lint-encryption-posture.py` | soleur-coupled | Soleur encryption-posture ledger + `apps/*/infra` scope (ADR-140). |
+| `lint-feature-map-coverage.sh` | soleur-coupled | `apps/web-platform/app/**` page set + `feature-map.md`. |
+| `lint-followthrough-varq-ban.sh` | soleur-coupled | Soleur probe-set/varq conventions. |
+| `lint-gh-argv-arg.py` | generic | Repo-wide `gh` argv vs jq-flag-token lint over workflows + `*.sh`; no Soleur coupling. |
+| `lint-guard-contract.py` | soleur-coupled | Soleur plan/SKILL.md guard-contract shape (deepen-plan §4.11). |
+| `lint-infra-no-human-steps.py` | soleur-coupled | `hr-no-ssh-fallback-in-runbooks` on `knowledge-base` docs. |
+| `lint-integration-env-gates.sh` | soleur-coupled | `apps/web-platform/{test,lib}` env-gate wiring + `scheduled-integration-suites.yml`. |
+| `lint-legal-mirror-drift-baseline.sh` | soleur-coupled | Legal mirror corpus (`plugins/soleur/docs/pages/legal`). |
+| `lint-legal-registers.sh` | soleur-coupled | `knowledge-base/legal/` registers. |
+| `lint-legal-scope-block-placement.sh` | soleur-coupled | Legal scope-block placement + the same mirror dir. |
+| `lint-migrated-rule-ids.sh` | soleur-coupled | AGENTS rule-id migration registry. |
+| `lint-orphan-test-suites.sh` | generic-after-extraction | **v1 `orphan-test` source.** The `git ls-files '*.test.sh'` producer is generic; couplings = `scripts/test-all.sh` runner name, `TEST_GROUP`/`SCRIPTS_SHARD` labels, `apps/web-platform/infra/` surfaces. |
+| `lint-questionnaire-identity.sh` | soleur-coupled | `knowledge-base/project/questionnaires/` identity guard. |
+| `lint-rejected-register.sh` | soleur-coupled | `knowledge-base/project/rejected/` no-list guard. |
+| `lint-rule-bodies.py` | soleur-coupled | `AGENTS.rules.md` body-hash ledger. |
+| `lint-rule-ids.py` | soleur-coupled | `AGENTS.md` rule-id coverage. |
+| `lint-scheduled-show-full-output.sh` | soleur-coupled | `scheduled-*.yml` convention + `plugins/soleur/skills/schedule` coupling. |
+| `lint-shell-capture-exit.py` | generic | `git ls-files '*.sh'` producer; capture-of-negative-rc class is universal (the `test-all.sh` mention is baseline prose). |
+| `lint-shell-trace-credential-refusal.py` | generic-after-extraction | xtrace-with-credential refusal is a universal class (v2); Soleur incidents cited are comments only, but the credential-binding corpus is repo-shaped. |
+| `lint-skill-body-budget.py` | soleur-coupled | `plugins/soleur` SKILL.md corpus + `skill-body-budget.json`. |
+| `lint-squash-ci-directives.sh` | generic | `[skip ci]` token scan of `gh pr create` bodies in workflows; token set is GitHub-documented. |
+| `lint-supabase-deprecated-endpoints.sh` | soleur-coupled | Supabase endpoint corpus + `apps/web-platform/lib/supabase`. |
+| `lint-trap-tempfile-ownership.py` | generic-after-extraction | Tempfile-cleanup ownership rules are generic (v2); keys on `SOLEUR_SCRATCH_SESSION_ROOT` markers. |
+| `lint-window-closure-assertion.allowlist.txt` | soleur-coupled | Data companion of the window-closure lint (Soleur test roots). |
+| `lint-window-closure-assertion.py` | soleur-coupled | TEST_ROOTS = `apps/web-platform`, `plugins/soleur/test`, `test`. |
+| `lint-workflow-errexit-capture.py` | generic | Workflow run-body errexit-capture class; scans `.github/workflows`. |
+| `lint-workflow-install-sites.sh` | generic-after-extraction | npm-install-site audit is generic (v2); assembly names `plugins/**` and `apps/web-platform` legs. |
+| `lint-workflow-issue-write-scope.py` | generic | Issue-write permission lint over `.github/workflows`; Soleur cite is a docstring example. |
+| `lint-workflow-local-action-checkout.py` | generic-after-extraction | `uses: ./…`-needs-checkout is generic (v2); third surface names `scripts/lib/bearer-curl.sh`. |
+| `lint-workflow-run-body-syntax.py` | generic | Every `run:` body must parse as bash; `.github/workflows` only. |
+| `lint-workflow-step-env-refs.py` | generic | Step-env scoping lint over workflow files. |
+| `lint-workflows.sh` | generic | actionlint entry point with the 64 KiB hang guard; repo-specific text is comments. |
+
+## The v1 set (and why)
+
+| Guard | Source | Why v1 |
+|---|---|---|
+| `secret-scan` | `git-commit-secret-scan.sh` | The highest-value generic gate: credential-leak prevention with the colour-pin/`-diff` bypass work already measured. |
+| `commit-on-main` | `plugins/soleur/scripts/precommit-guard.sh` + `lib/wrapper-boundary.sh` | Already self-contained by design (the near-verbatim emit). |
+| `block-stash` | `guardrails.sh` `block-stash-in-worktrees` arm | Small extractable arm; boundary-regex detection generalizes. |
+| `orphan-test` | `lint-orphan-test-suites.sh` | The meta-guard: a scaffolded suite that is never wired invisibly does nothing; generalizes to user-declared runner surfaces. |
+
+`block-rm-rf` was audited for v1 promotion and stays v2: the
+`block-rm-rf-worktrees`/`block-recursive-delete` arms read freeze-lock state and
+incident machinery inside `guardrails.sh` — not self-contained.
+
+The 9 `generic` lints above are the v2 candidate pool: shipping one is a
+`guards.tsv` row + a template + an audit-verdict flip, not new design.

package/skills/verification-scaffold/references/guards/block-stash-hook.sh.template

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# block-stash.sh — PreToolUse hook emitted by soleur:verification-scaffold.
+# Decides every `git stash` at a chain boundary (any position in &&/||/;/|
+# chains, behind env-assignment or launcher prefixes). Extracted from the
+# repo-corpus stash arm; generalized for arbitrary repos.
+#
+# Documented read-only exceptions: `git stash list`, `git stash show` —
+# they mutate nothing. Everything else carrying a `git stash` subcommand
+# (`push`, `pop`, `drop`, `apply`, a bare `git stash`) is decided.
+#
+# MODE=@MODE@ — advisory (installed default): warns and allows; enforce:
+# denies. An unparseable payload is a tool error — warn+allow in advisory,
+# deny with remediation in enforce; `ask` never fires on an error path.
+#
+# Hook stdin: JSON payload with tool_input.command. Hook stdout: the PreToolUse
+# JSON decision envelope. Exit code is always 0.
+set -euo pipefail
+
+MODE="@MODE@"
+
+_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; }
+
+# --- 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
+  _vs_cmd="$(printf '%s' "$_vs_payload" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)"
+fi
+[ -n "$_vs_cmd" ] || _vs_allow
+grep -q 'stash' <<<"$_vs_cmd" || _vs_allow
+
+# Wrapper-prefix set: env assignments and launcher words that may sit between a
+# chain boundary and `git` (LEFTHOOK=0 git stash, sudo git stash, env git stash).
+VS_ENV_ASN_RE='[A-Za-z_][A-Za-z_0-9]*=[^[:space:]]+'
+VS_LAUNCHER_RE='(sudo|command|nice|env|xargs)'
+VS_BOUNDARY_PFX="(${VS_ENV_ASN_RE}|${VS_LAUNCHER_RE})"
+
+stash_hit=""
+while IFS= read -r seg; do
+  if grep -qE '^[[:space:]]*('"${VS_BOUNDARY_PFX}"'[[:space:]]+)*git[[:space:]]+stash([[:space:]]|$)' <<<"$seg"; then
+    # Read-only subcommands are the documented exception — everything else decides.
+    if grep -qE '^[[:space:]]*('"${VS_BOUNDARY_PFX}"'[[:space:]]+)*git[[:space:]]+stash[[:space:]]+(list|show)([[:space:]]|$)' <<<"$seg"; then
+      continue
+    fi
+    stash_hit="$seg"
+  fi
+done < <(printf '%s\n' "$_vs_cmd" | sed -E 's/&&|\|\||[;|]/\n/g')
+
+[ -n "$stash_hit" ] || _vs_allow
+
+reason="git stash is not allowed by this repo's verification gates — commit WIP to a branch instead, or use 'git stash list'/'git stash show' (read-only, allowed). Offending segment: ${stash_hit:0:120}"
+if [ "$MODE" = "enforce" ]; then
+  _vs_decide deny "BLOCKED: $reason"
+else
+  printf '[block-stash] WARN: %s\n' "$reason" >&2
+  _vs_decide allow
+fi

package/skills/verification-scaffold/references/guards/commit-on-main-hook.sh.template

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# commit-on-main.sh — PreToolUse hook emitted by soleur:verification-scaffold.
+# Runs scripts/verification/precommit-guard.sh (the emitted copy) over every
+# Bash command payload and translates its refusal into the hook decision
+# envelope. The DETECTION lives entirely in the emitted guard — this wrapper
+# owns only the decision verb.
+#
+# MODE=@MODE@ — advisory (installed default): a refusal warns and allows;
+# enforce: a refusal denies. A guard/tool error (missing script, usage error)
+# warns+allows in advisory and denies with remediation in enforce — `ask`
+# never fires on an error path in either mode.
+#
+# Hook stdin: JSON payload with tool_input.command. Hook stdout: the PreToolUse
+# JSON decision envelope. Exit code is always 0.
+set -euo pipefail
+
+MODE="@MODE@"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+GUARD="$PROJECT_DIR/scripts/verification/precommit-guard.sh"
+
+_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() {
+  printf '[commit-on-main] WARN: %s\n' "$1" >&2
+  if [ "$MODE" = "enforce" ]; then
+    _vs_decide deny "BLOCKED: commit-on-main: $1"
+  else
+    _vs_decide allow
+  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
+  _vs_cmd="$(printf '%s' "$_vs_payload" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)"
+fi
+[ -n "$_vs_cmd" ] || _vs_allow
+
+# Cheap pre-filter: a payload that names neither git nor commit cannot be a
+# commit. The emitted guard runs the real chain-boundary verdict.
+grep -qE 'git' <<<"$_vs_cmd" && grep -qE 'commit' <<<"$_vs_cmd" || _vs_allow
+
+[ -f "$GUARD" ] || _vs_tool_error "scripts/verification/precommit-guard.sh is missing — the commit-on-main gate is NOT running. Re-run verification-scaffold or restore the file."
+# The hook's cwd is what the tool call runs in — pass it so a `cd`-free payload
+# resolves the right repo.
+hook_cwd=""
+if command -v jq >/dev/null 2>&1; then
+  hook_cwd="$(printf '%s' "$_vs_payload" | jq -r '.cwd // ""' 2>/dev/null || true)"
+fi
+[ -n "$hook_cwd" ] || hook_cwd="$PWD"
+
+guard_rc=0
+guard_out="$(bash "$GUARD" --cwd "$hook_cwd" "$_vs_cmd" 2>&1)" || guard_rc=$?
+case "$guard_rc" in
+  0) _vs_allow ;;
+  1)
+    reason="${guard_out:-commit refused: the target repo is checked out on a default branch. Create a feature branch first.}"
+    if [ "$MODE" = "enforce" ]; then
+      _vs_decide deny "BLOCKED: $reason"
+    else
+      printf '[commit-on-main] WARN: %s\n' "$reason" >&2
+      _vs_decide allow
+    fi
+    ;;
+  *) _vs_tool_error "precommit-guard.sh exited $guard_rc (${guard_out:-no output}) — a tool error, not a refusal; nothing was decided." ;;
+esac

package/skills/verification-scaffold/references/guards/orphan-test-check.sh.template

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# orphan-test-check.sh — emitted by soleur:verification-scaffold.
+#
+# Fail when a tracked *.test.sh ANYWHERE in the repo is run by no declared
+# registration surface. A test nothing executes gates nothing while looking
+# exactly like coverage — the green summary is read as evidence.
+#
+# THE PRODUCER IS `git ls-files '*.test.sh'` — the whole repo, never a
+# directory list.
+#
+# REGISTRATION SURFACES (a suite is registered when its BASENAME appears in at
+# least one):
+#   1. any `.github/workflows/*.{yml,yaml}` file, and
+#   2. any file matched by a word of $RUNNER_GLOBS (default below — declare
+#      your own in the workflow job env).
+# or, by decision rather than registration:
+#   3. a reason-carrying line in `.github/verification-known-orphans.txt`
+#      (`repo-relative/path.test.sh # <reason>` — keyed on the PATH, never the
+#      basename: two suites can share a basename).
+#
+# Exit 0 clean (or zero suites — a pass with a printed notice), exit 1 naming
+# every orphan by path, exit 2 when the check cannot see (zero registration
+# surfaces resolved — a guard whose producer enumerates nothing must fail
+# LOUDLY, not pass vacuously).
+set -euo pipefail
+export LC_ALL=C
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+RUNNER_GLOBS="${RUNNER_GLOBS:-scripts/test-all.sh scripts/run-tests* Makefile makefile package.json}"
+KNOWN=".github/verification-known-orphans.txt"
+
+# --- producer ----------------------------------------------------------------
+TRACKED="$(git ls-files '*.test.sh' | sort -u)"
+if [ -z "$TRACKED" ]; then
+  printf 'orphan-test: no tracked *.test.sh files — nothing to check\n'
+  exit 0
+fi
+
+# --- surfaces ------------------------------------------------------------------
+SURFACES=""
+if [ -d .github/workflows ]; then
+  for f in .github/workflows/*.yml .github/workflows/*.yaml; do
+    [ -f "$f" ] && SURFACES="$SURFACES $f"
+  done
+fi
+for pat in $RUNNER_GLOBS; do
+  for f in $pat; do
+    [ -f "$f" ] && SURFACES="$SURFACES $f"
+  done
+done
+
+if [ -z "${SURFACES# }" ]; then
+  printf 'orphan-test: FAIL — zero registration surfaces resolved (.github/workflows/*.{yml,yaml} + RUNNER_GLOBS="%s"). The check cannot see anything; refusing to certify vacuously.\n' "$RUNNER_GLOBS" >&2
+  exit 2
+fi
+# shellcheck disable=SC2086
+SURFACE_TEXT="$(cat $SURFACES)"
+
+# --- exclusion manifest ---------------------------------------------------------
+# Lines: `<path> # <reason>` (reason required). Bare-path lines are reported as
+# findings — a reasonless exclusion is a silent absorption. Stale entries (the
+# path is no longer tracked, or the suite is now registered) are WARNED on.
+fails=0
+if [ -f "$KNOWN" ]; then
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in ''|'#'*) continue ;; esac
+    entry_path="${line%%#*}"
+    entry_path="$(printf '%s' "$entry_path" | sed 's/[[:space:]]*$//; s/^[[:space:]]*//')"
+    entry_reason="${line#*#}"
+    if [ "$entry_reason" = "$line" ] || [ -z "$(printf '%s' "$entry_reason" | tr -d '[:space:]')" ]; then
+      printf 'orphan-test: FAIL — %s carries a reasonless exclusion: %s (every line must read `<path> # <reason>`)\n' "$KNOWN" "$line" >&2
+      fails=$((fails + 1))
+      continue
+    fi
+    if ! grep -qxF "$entry_path" <<<"$TRACKED"; then
+      printf 'orphan-test: WARN — %s names %s, which is no longer a tracked *.test.sh; a stale exclusion can re-hide the next regression. Remove the line.\n' "$KNOWN" "$entry_path" >&2
+    fi
+  done < "$KNOWN"
+fi
+
+# --- verdict --------------------------------------------------------------------
+while IFS= read -r suite; do
+  [ -n "$suite" ] || continue
+  base="$(basename "$suite")"
+  if grep -qF -- "$base" <<<"$SURFACE_TEXT"; then
+    continue
+  fi
+  if [ -f "$KNOWN" ] && grep -qE "^${suite}[[:space:]]*#" "$KNOWN"; then
+    continue
+  fi
+  printf 'orphan-test: FAIL — %s is tracked but named by no registration surface (workflows, RUNNER_GLOBS files, or %s with a reason)\n' "$suite" "$KNOWN" >&2
+  fails=$((fails + 1))
+done <<<"$TRACKED"
+
+if [ "$fails" -eq 0 ]; then
+  printf 'orphan-test: %s tracked suite(s), all registered\n' "$(printf '%s\n' "$TRACKED" | grep -c .)"
+  exit 0
+fi
+printf 'orphan-test: %d finding(s)\n' "$fails" >&2
+exit 1

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