@soleur/opencode 1.0.0 → 3.354.2

package/skills/ship/references/ready-run-wait.md

@@ -2,7 +2,7 @@
 
 **Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
 
-Read this when a draft PR is readied (ship Phase 6.5 CI Status Check, merge-pr 5.1, drain-prs), or when the Phase 7 poll, `monitor-pr-checks.sh` or `triage-prs.sh` reports a ready run that is `stalled`, `no-run` or `awaiting-approval`. The resolver is `plugins/soleur/scripts/ci-head-verdict.sh`; `--help` prints its contract.
+Read this when a draft PR is readied (ship Phase 6.5 CI Status Check, merge-pr 5.1, drain-prs), or when the Phase 7 poll, `monitor-pr-checks.sh` or `triage-prs.sh` reports a ready run that is `stalled`, `no-run` or `awaiting-approval`, or a red `test` persists on a PR readied more than 120 minutes ago with no STALLED message. The resolver is `plugins/soleur/scripts/ci-head-verdict.sh`; `--help` prints its contract.
 
 ## Why
 
@@ -27,10 +27,10 @@ Run it as one Bash call with `timeout: 420000`: the wait budget is 300 s of poll
 | exit 1, `awaiting-approval` | a fork's run needs a maintainer to click "Approve and run" in the Actions tab | approve it, then run `ci-head-verdict.sh verdict PR_NUMBER`; `--undo` and ready again do not clear an approval gate |
 | exit 3, `api-error` | a read failed on the last poll: the ready state is UNKNOWN | run `ci-head-verdict.sh verdict PR_NUMBER`; do not undo anything on a guess |
 
-Never arm on the wait's own non-zero outcome: report "readied but unarmed" with the marker line. After a recovery step, the way back to arming is the verdict, not the wait: `ci-head-verdict.sh verdict PR_NUMBER` answering `pending-full` or `full-decided` means a ready run exists, and only then run `gh pr merge --squash --auto`. `no-run` or `stalled` goes back to the `--undo` row, `awaiting-approval` back to the approval row, and `state=error` (exit 3) means retry later. A `no-run` that is only minutes old may belong to another session still inside its own wait: look before undoing.
+Never arm on the wait's own non-zero outcome: report "readied but unarmed" with the marker line. After a recovery step, the way back to arming is the verdict, not the wait: `ci-head-verdict.sh verdict PR_NUMBER` answering `pending-full` or `full-decided` means a ready run exists, and only then run `gh pr merge --squash --auto`. `no-run` or `stalled` goes back to the `--undo` row, `awaiting-approval` back to the approval row, and `state=error` (exit 3) with reason `api-error` means retry later; with reason `no-check-suites` CI never saw this head, so retrying never converges and the fix loop has nothing to inspect: recover as for `stalled` (the `--undo` row, user token; no suite exists, so nothing in flight can be cancelled and the Actions-tab check below does not apply). A `no-run` that is only minutes old may belong to another session still inside its own wait: look before undoing.
 
 ## Reading a ready PR's red `test` (Phase 7 poll, monitor, triage, admin-merge)
 
-`ci-head-verdict.sh verdict` answers one of six states: `n/a` (never readied, a draft now, or a repo without the mechanism), `full-decided`, `pending-full`, `no-run`, `stalled`, `awaiting-approval`. `pending-full` and `no-run` are PENDING, not a failure; `stalled` (120 minutes past the ready event with no deciding run) and `awaiting-approval` end the watch with no fix loop. On `full-decided` and `n/a` the red row is a real failure. Exit 3 prints `state=error`, which is none of the six: readers keep today's reading, so an outage never turns a real red `test` into a wait. `no-run` with reason `conflicting` is a PR with a merge conflict: GitHub builds no merge ref for it, so no run can appear; resolve the conflict, never undo/ready. `stalled` can also describe a slow healthy run: open the Actions tab before undoing, because `gh pr ready --undo` then ready cancels an in-flight ready run and starts the battery again.
+`ci-head-verdict.sh verdict` answers one of six states: `n/a` (never readied, a draft now, or a repo without the mechanism), `full-decided`, `pending-full`, `no-run`, `stalled`, `awaiting-approval`. `pending-full` and `no-run` are PENDING, not a failure; `stalled` (no deciding run 120 minutes after the later of the ready event and the head's first appearance in CI; the clock is defined in the `ci-head-verdict.sh` header and `--help`) and `awaiting-approval` end the watch with no fix loop. On `full-decided` and `n/a` the red row is a real failure. Exit 3 prints `state=error`, which is none of the six: readers keep today's reading, so an outage never turns a real red `test` into a wait. `no-run` with reason `conflicting` is a PR with a merge conflict: GitHub builds no merge ref for it, so no run can appear; resolve the conflict, never undo/ready. `stalled` can also describe a slow healthy run: open the Actions tab before undoing, because `gh pr ready --undo` then ready cancels an in-flight ready run and starts the battery again. A red `test` that persists on a PR readied more than 120 minutes ago, with no STALLED message: run `ci-head-verdict.sh verdict PR_NUMBER` yourself, because the consumers drop the reason; `state=error reason=no-check-suites` means recover as for `stalled`.
 
 When diagnosing a failed `test` on a ready PR, take the run id from the verdict marker's `run=` (the deciding run), not from `gh run list --commit`: a ready head carries the draft run too, and its only red text is the by-design line.

package/skills/test-fix-loop/SKILL.md

@@ -145,7 +145,7 @@ On termination (success or failure), write a report to stdout:
 - **Fixes applied**: files modified and what changed (last iteration)
 - **Recommendation**: what the user should investigate next (if not success). CIRCULAR or NON_CONVERGENCE on one cluster is an architecture signal, not a fix signal: recommend `soleur:engineering:review:legacy-code-expert` for that cluster's seams and characterization tests before another loop. Likewise when a fix landed but no existing test asserts the behaviour it changed -- this loop never writes tests, so name the agent that should. On NON_CONVERGENCE or MAX_ITERATIONS, name the remaining failures as load-only flake candidates to review against [determinism-checklist.md](./references/determinism-checklist.md) — the isolated re-run under-detects the contention class (fails only under suite load), so the honest answer there is determinism work on the test, not retry.
 
-On success, fixes are staged but NOT committed. The user reviews and commits via `soleur:ship` or manually.
+On success, fixes are staged but NOT committed. Commit through `soleur:ship`, which runs review. A manual commit stays an option and does not skip review: merge stays review-gated (`rf-never-skip-qa-review-before-merging`).
 
 ## Key Principles
 

package/skills/verification-scaffold/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: verification-scaffold
+description: "This skill should be used when installing the generic guardrail set (secret-scan, commit-on-main, block-stash, orphan-test) into a user repository's hooks and CI, advisory-first."
+---
+
+<!-- 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 -->
+
+# verification-scaffold
+
+Installs a fixed, tested set of **generic** repo guardrails into a user repository —
+the repo-generic fraction of Soleur's own hook/lint corpus, classified in
+[guardrail-audit.md](references/guardrail-audit.md) (which corpus member is `generic`,
+`generic-after-extraction`, or `soleur-coupled`, and why). This is the
+`constraint-scaffold` sibling for the guardrail *corpus* rather than a single gate
+(#10404, epic #10397).
+
+## Usage
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/verification-scaffold/scripts/verification-scaffold.sh" --headless
+```
+
+Installs the v1 set into the current repo. Flags: `--target <path>` (default
+cwd), `--guards a,b` / `--all` (default: all v1 rows of [guards.tsv](references/guards.tsv)),
+`--mode advisory|enforce` (default `advisory`), `--dry-run`, `--list`,
+`--uninstall <guard>`.
+
+## What it emits
+
+| Guard | Surfaces | Emitted |
+|---|---|---|
+| `secret-scan` | hook + CI | `.claude/hooks/secret-scan.sh` (gitleaks staged scan), `.gitleaks.toml` (only when absent — a default-ruleset pointer, never overwrites a user's), the `secret-scan` job in `.github/workflows/verification-gates.yml` |
+| `commit-on-main` | hook | `.claude/hooks/commit-on-main.sh` → [scripts/verification/precommit-guard.sh](references/guards/precommit-guard.sh.template) + [lib/wrapper-boundary.sh](references/guards/wrapper-boundary.sh.template) (the near-verbatim canonical emit, default-branch set stamped) |
+| `block-stash` | hook | `.claude/hooks/block-stash.sh` (chain-boundary `git stash`; `list`/`show` are documented read-only exceptions) |
+| `orphan-test` | CI | [scripts/verification/orphan-test-check.sh](references/guards/orphan-test-check.sh.template) + the `orphan-test` job + `.github/verification-known-orphans.txt` (reason-required exclusion manifest, seeded with grandfathered rows) |
+
+Hooks are registered as `PreToolUse` `Bash` entries in `.claude/settings.json`
+(node-first, `jq` fallback — a repo with neither is refused with the dependency
+named; malformed existing JSON is refused before any write). The workflow lands
+at repo ROOT — a nested `.github/workflows/` is dormant.
+
+## Advisory-first contract
+
+Every guard installs **advisory**: identical predicates, different decision verb
+— hooks warn+allow (`ask` only on a REAL secret-scan finding), CI jobs carry
+`continue-on-error: true`. Promotion is the one-line flip the emitted
+`VERIFICATION.md` documents (`MODE="enforce"`, `continue-on-error: false`), and
+it requires ≥1 observed clean advisory run first. Non-destructive: any existing
+artifact is a refusal — there is no `--force`.
+
+## Agent-owns-gates
+
+Same model as `constraint-scaffold`: the agent owns the emitted files; the
+target user never hand-edits a gate. `--uninstall <guard>` removes only that
+guard's artifacts + settings entry; it is idempotent and prints "not installed"
+for a never-installed guard, and it strips the marker doc block from
+VERIFICATION.md/README.md once no guard artifact remains.
+
+## Bite-proof
+
+Every install proves each selected guard **pass → fail → pass** on a detached
+worktree under TMPDIR (a TMPDIR inside the repo is refused, exit 69) before the
+doc block is written; a mid-install failure removes exactly the files that run
+emitted. The `secret-scan` arm requires `gitleaks` on PATH and is reported as a
+loud SKIP when absent — an advisory hook that cannot scan is a tool error, not
+a silent guard.
+
+## Requirements
+
+bash + POSIX tools on the target host (stock macOS included). Emitted artifacts
+carry no Soleur couplings and zero network egress; `manifest.test.sh` pins both.

package/skills/verification-scaffold/references/gitleaks.toml.template

@@ -0,0 +1,13 @@
+# .gitleaks.toml — emitted by soleur:verification-scaffold ONLY because the repo
+# had none (a pre-existing ruleset is never overwritten). It is deliberately a
+# default-pack pointer: `useDefault = true` inherits the gitleaks default rules
+# (cloud keys, vendor tokens, PEM bodies, webhooks). Narrow or widen by editing
+# this file — the emitted hook and the emitted CI job both read it.
+#
+# Waivers: annotate a known-safe line with `# gitleaks:allow <reason>` (or the
+# `//` form) — never commit-then-rotate.
+
+title = "verification-scaffold secret-scan floor"
+
+[extend]
+useDefault = true

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