continuous-improvement 3.20.0 → 3.21.0

package/plugins/continuous-improvement/skills/simplicity-review/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: simplicity-review
+tier: "2"
+description: Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Reviews the current diff for over-engineering (code that could reuse an existing file, a stdlib or native feature, or fewer lines) and reports trim findings without touching code, so 'it works' is never mistaken for 'it is the minimum that works'.
+origin: continuous-improvement
+user-invocable: true
+---
+
+# Simplicity Review — Flag the Over-Build Before It Ships
+
+Law 4 says verify before reporting. "It compiles and the test passes" is a claim about correctness, not about whether the change is the minimum that works. This skill runs a diff-scoped review with one question: could this have been smaller? It reads the change like the laziest senior dev in the room, walks a fixed reuse ladder, and reports what to trim. It never edits code. The best code is the code you never wrote.
+
+## When to Activate
+
+- After writing a feature or fix, before opening a PR, when the diff feels larger than the task warranted.
+- When you reached for a new file, a new dependency, or a wrapper component and a native or existing option might already cover it.
+- As a routed step from `proceed-with-the-recommendation` at the "Refactor / dead code cleanup" line, as the repo-owned alternative to the built-in `simplify`.
+- Before a release cut, over the diff since the last tag, as a last pass on accreted complexity.
+
+## The Ladder
+
+Read each added or changed block and stop at the first rung that holds:
+
+```
+1. Does this need to exist?   -> skip it (YAGNI)
+2. Already in this codebase?  -> reuse it
+3. Stdlib does it?            -> use it
+4. Native platform feature?   -> use it
+5. Installed dependency?      -> use it
+6. One line?                  -> one line
+7. Only then:                    the minimum that works
+```
+
+Most real cuts come from rungs 2 to 4: a hand-rolled helper that duplicates an existing one, a component built where a native input, a stdlib call, or a platform primitive already does the job.
+
+## Read Before You Cut
+
+Lazy about the solution, never about the reading. The ladder shortens the solution, not the investigation. Trace the whole change and what it touches first. A "simpler" path proposed without reading the surrounding code is a guess, and a wrong trim is worse than the over-build.
+
+## Safety Carve-Out (Never Flag)
+
+Lazy, not negligent. These are never on the chopping block, no matter how many lines they cost:
+
+- Input validation at trust boundaries.
+- Error handling that prevents data loss.
+- Security controls (authz checks, escaping, secret handling).
+- Accessibility.
+
+This aligns with `rules/common/security.md` and `rules/common/coding-style.md`. If a trim would weaken any of the above, it is not a finding.
+
+## Output
+
+A findings list. For each item:
+
+- `file:line`
+- `over-built:` what the code does the long way
+- `simpler:` the specific shorter path (reuse existing `X` / stdlib `Y` / native `Z` / one line / delete)
+- one-line rationale
+
+Close with a verdict:
+
+- `GO` — the diff is already at or near minimal; nothing to trim.
+- `TRIM` — findings listed above; apply, then re-verify.
+
+No score, no line-count target. A net-negative diff is a nice side effect, not the goal. Optimizing for fewer lines invites golfing and deletion of things that earn their keep; the ladder, not a number, decides.
+
+## Review Only
+
+This skill reports; it does not edit. Apply the trims yourself or route them through `proceed-with-the-recommendation`, then run the `verification-loop` ladder on what changed. This mirrors `audit`'s confirm-before-fix: a finding is a hypothesis until the simpler path is proven to exist and to preserve behavior.
+
+## Overlap With `simplify`
+
+The Claude Code built-in `simplify` and this skill share intent but differ in kind. `simplify` auto-applies broad reuse, efficiency, and altitude cleanups across changed code. `simplicity-review` is a repo-owned, Law-4-tagged, review-only lens scoped to over-engineering in the current diff, with an explicit safety carve-out, that feeds its findings into the 7-Laws flow. Use `simplify` when you want the fixes applied; use `simplicity-review` when you want the diff judged first.
+
+## Pairs With
+
+- **`verification-loop`** (Law 4) — the build/test/lint ladder you run after applying a trim.
+- **`gateguard`** (Law 1) — the write-time reuse gate ("confirm no existing file serves the same purpose"); this skill catches at review time what slipped past it.
+- **`proceed-with-the-recommendation`** — applies the trims under the 7 Laws.
+- **`wild-risa-balance`** (Law 2) — the recommendation-layer analog: the same anti-padding instinct applied to advice instead of code.

package/plugins/continuous-improvement/skills/verification-loop/SKILL.md

@@ -23,10 +23,10 @@ Invoke this skill:
 
 Every project has its own actual invocation for build / typecheck / lint / test / security / deploy-receipt. Hardcoding `npm run build` and `npm run test` works when the project happens to use those exact scripts; for everything else (pnpm, yarn, cargo, go, mise, just, custom scripts, monorepos with workspace-scoped commands) it returns "deps not installed" or "config not found" misreads from the wrong invocation. Phase 0 runs first so Phases 1–6 never have to guess.
 
-**Run [`scripts/resolve-verify-ladder.mjs`](../scripts/resolve-verify-ladder.mjs)** at the repo root. It encodes the full four-step resolution priority and emits the fenced block below. Use `--json` for machine consumption.
+**Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-verify-ladder.mjs"`** (source: `scripts/resolve-verify-ladder.mjs`) at the repo root. It encodes the full four-step resolution priority and emits the fenced block below. Use `--json` for machine consumption.
 
 ```
-$ node scripts/resolve-verify-ladder.mjs
+$ node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-verify-ladder.mjs"
 verify-ladder (resolved):
   build:             npm run build  (sniff:package.json:scripts.build)
   typecheck:         npm run typecheck  (sniff:package.json:scripts.typecheck)
@@ -147,9 +147,9 @@ If either is `No`, the verification report goes back to the operator with the ex
 
 For repos whose `verify-ladder.json` declares a `deploy_receipt` field — or whose sniff path detects an auto-deploy target — the verify is not complete until the deployed SHA matches the merge SHA and a healthcheck returns 200. Hand off to the `deploy-receipt` skill (Law 4 deploy-seam companion landed in PR #83) and treat its `Receipt status: COMPLETE` as the gate.
 
-**Detection.** Run [`scripts/detect-deploy-target.sh`](../scripts/detect-deploy-target.sh) at the repo root. Output is one of `railway` / `cloudflare` / `vercel` / `netlify` / `fly` / `appengine` / `apprunner` / `gha-deploy` / `none`. Anything except `none` triggers handoff to `deploy-receipt`; `none` means Phase 8 is skipped (no deploy seam exists).
+**Detection.** Run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/detect-deploy-target.sh"` (source: `scripts/detect-deploy-target.sh`) at the repo root. Output is one of `railway` / `cloudflare` / `vercel` / `netlify` / `fly` / `appengine` / `apprunner` / `gha-deploy` / `none`. Anything except `none` triggers handoff to `deploy-receipt`; `none` means Phase 8 is skipped (no deploy seam exists).
 
-**SHA extraction.** For the detected provider, [`scripts/get-deployed-sha.sh <provider>`](../scripts/get-deployed-sha.sh) returns the currently-deployed SHA via the provider CLI; `--show-command <provider>` prints the pipeline shape without executing (useful for dry-runs and citation). `deploy-receipt` owns the receipt's other components (health endpoint, build artifact, on-incomplete modes) and Route B/C fallbacks.
+**SHA extraction.** For the detected provider, `bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-deployed-sha.sh" <provider>` (source: `scripts/get-deployed-sha.sh`) returns the currently-deployed SHA via the provider CLI; `bash "${CLAUDE_PLUGIN_ROOT}/scripts/get-deployed-sha.sh" --show-command <provider>` prints the pipeline shape without executing (useful for dry-runs and citation). `deploy-receipt` owns the receipt's other components (health endpoint, build artifact, on-incomplete modes) and Route B/C fallbacks.
 
 INCOMPLETE receipts move to "Immediate operator action" in the close, never to "ready". Library-only / package-published repos skip this phase entirely (no deploy seam exists).
 
@@ -164,7 +164,7 @@ Phase 8 confirms the deploy seam. Phase 9 confirms the deployed surface matches
 
 **What the runner does:**
 
-Implementation: `scripts/run-synthetic.mjs` encodes the lexical walk, interpreter map, env injection, and exit-code aggregation below. The prose is documentation, not the contract — when the two disagree, the script wins.
+Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/run-synthetic.mjs"` (source: `scripts/run-synthetic.mjs`); it encodes the lexical walk, interpreter map, env injection, and exit-code aggregation below. The prose is documentation, not the contract — when the two disagree, the script wins.
 
 1. List every `*.synthetic.{sh,mjs,ts,py}` file in the resolved directory in lexical order.
 2. For each file, set the input env vars: `BASE_URL` (production base from project config), `BASELINE_URL` (staging baseline from project config), `EXPECTED_SHA` (the merge SHA Phase 8 reported COMPLETE), `DEPLOY_BRANCH` (the deploy branch name), `RECEIPT_TIMESTAMP` (ISO-8601 of the receipt).

package/plugins/continuous-improvement/skills/workspace-surface-audit/SKILL.md

@@ -74,7 +74,7 @@ Probe and record (no destructive commands; quote results inline):
 - **jq availability.** `command -v jq` (or `Get-Command jq`). When jq is missing, observation-pipeline hooks fall back to a thin schema and curl/JSON one-liners need a node/python rewrite.
 - **Case-sensitive filesystem.** Test by creating two paths differing only in case in a tempdir. NTFS (Windows) and APFS (macOS default) are case-insensitive; Linux ext4 and case-sensitive APFS are case-sensitive. Affects `CLAUDE.md` vs `claude.md` resolution and import paths.
 - **CWD baseline.** `pwd` (or `Get-Location`) recorded at session start. `tsc`, build scripts, and some test runners change CWD as a side effect; subsequent commands run from the wrong directory return "deps not installed" or "config not found" misreads.
-- **Parallel-actor expectation.** Document whether a second Claude / Codex / Maulana session may operate on the same working tree. If yes, the `gateguard` Parallel-Actor Gate uses [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) to produce a single JSON envelope (`{head, upstream, dirty, root, branch}`) for the baseline and the divergence check. This skill records whether parallel-actor is expected; gateguard owns the runtime mechanics, so the audit doesn't restate the git-command triple.
+- **Parallel-actor expectation.** Document whether a second Claude / Codex / Maulana session may operate on the same working tree. If yes, the `gateguard` Parallel-Actor Gate runs `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`) to produce a single JSON envelope (`{head, upstream, dirty, root, branch}`) for the baseline and the divergence check. This skill records whether parallel-actor is expected; gateguard owns the runtime mechanics, so the audit doesn't restate the git-command triple.
 
 Output the recorded grain as a single fenced block so it survives context compaction and any later phase can reference it without re-probing:
 

package/plugins/continuous-improvement/skills/worktree-safety/SKILL.md

@@ -32,7 +32,7 @@ The continuous-improvement repo runs on Windows + Git Bash with `autocrlf=true`
 
 Before any source-writing call, verify all five. Fail closed on any miss.
 
-1. **Root validity** — `git rev-parse --show-toplevel` resolves; the resolved path matches CWD after symlink-safe canonicalization. The `root` field of [`scripts/git-state-snapshot.sh`](../scripts/git-state-snapshot.sh) carries the canonicalized root, and its non-zero exit on `{"error":"not-a-git-repo"}` is itself the fail-closed signal — no second probe needed.
+1. **Root validity** — `git rev-parse --show-toplevel` resolves; the resolved path matches CWD after symlink-safe canonicalization. Run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`); its `root` field carries the canonicalized root, and its non-zero exit on `{"error":"not-a-git-repo"}` is itself the fail-closed signal — no second probe needed.
 2. **`.git` presence** — `.git` exists (file pointer for worktrees, directory for primary checkout). A missing or unreadable `.git` is an immediate stop.
 3. **Worktree registration** — `git worktree list` includes the resolved root with no `prunable` flag. Prunable worktrees can be deleted by another process at any moment.
 4. **Branch alignment** — current branch matches the lease ledger; `HEAD` is not detached unless the unit explicitly asked for detached state. The snapshot script's `branch` field carries either the branch name or the literal `"detached"`, so detached-state is observable without a second probe.

package/plugins/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.20.0",
+  "version": "3.21.0",
   "mode": "expert",
   "description": "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay sharp and learnings survive context resets.",
   "tools": [

package/scripts/README.md

@@ -0,0 +1,33 @@
+# `scripts/` — deterministic primitives skills cite
+
+This directory holds small, hand-authored scripts that skills (and hooks) cite instead of restating fixed operations inline. The motivation is the skills audit's "deterministic vs non-deterministic" axis: when a step inside a skill is the same operation every time (a fixed git command, a regex parse, a path lookup), it does not belong in the LLM-driven part of the skill — it belongs here, where the script runs the same way every invocation, costs no tokens, and stays in one place so multiple skills can share it.
+
+## Conventions
+
+- **Hand-authored, no `.mts` source.** Files in `scripts/` are not part of the `tsc` build pipeline (see [`CLAUDE.md`](../CLAUDE.md) → "Build pipeline"). The pipeline owns `bin/`, `lib/`, `test/`. `scripts/` is the bare-metal home for shell scripts and one-off Node utilities skills cite directly.
+- **One concern per script.** Each script does one thing and prints either machine-readable output (JSON envelope, single value) or a stable fenced block. Skills consume the output; they do not re-derive it.
+- **Cross-platform shape.** Bash scripts run via Git Bash on Windows, native bash on macOS/Linux. Tests for bash scripts skip when bash is not on PATH (see `src/test/hook.test.mts` for the established skip pattern).
+- **Cite from skills.** When a skill needs a primitive, the skill body cites the script path (`scripts/<name>.<ext>`) and quotes the expected output shape once. The skill does not restate the script's inner mechanics.
+
+## Inventory
+
+| Script | Purpose | Cited by |
+|---|---|---|
+| `git-state-snapshot.sh` | JSON envelope `{head, upstream, dirty, root, branch}` for the current git working tree | `skills/gateguard.md` (Parallel-Actor Gate), `skills/worktree-safety.md` (Root + branch), `skills/workspace-surface-audit.md` (Environment Grain — parallel-actor row), `skills/reconcile.md` (Detect a Concurrent Writer) |
+| `detect-deploy-target.sh` | Detect the auto-deploy provider for the repo at the current working directory (or first arg). Prints one of `railway`/`cloudflare`/`vercel`/`netlify`/`fly`/`appengine`/`apprunner`/`gha-deploy`/`none`. Always exits 0. | `skills/verification-loop.md` (Phase 8 deploy-receipt handoff), `skills/deploy-receipt.md` (When to Activate gate) |
+| `get-deployed-sha.sh` | Per-provider deployed-SHA extraction. Default mode runs the CLI; `--show-command <provider>` prints the pipeline shape without executing (useful for citation, dry-run, tests). | `skills/verification-loop.md` (Phase 8), `skills/deploy-receipt.md` (Route A — provider CLI extraction) |
+| `resolve-verify-ladder.mjs` | Resolve the per-project verification ladder for Phase 0 of `verification-loop`. Encodes the four-step priority — manifest > package.json sniff > per-language toolchain > ask-operator. Default mode prints the fenced block the skill displays; `--json` mode emits a JSON object for machine consumption. | `skills/verification-loop.md` (Phase 0) |
+| `scan-past-mistakes.mjs` | Scan the three Past-Mistake Acknowledgment Gate surfaces — `~/.claude/instincts/<hash>/observations.jsonl` (last N failure/correction rows), `~/.claude/projects/<hash>/memory/feedback_*.md`, and `<root>/CLAUDE.md` "## Past Mistakes" table. Active-in-scope judgment is the LLM's job; the script provides quotes + citations only. | `skills/proceed-with-the-recommendation.md` (Phase 0 Rule 1) |
+| `route-recommendation.mjs` + `route-recommendation.routes.json` | Match a recommendation item to its preferred-skill chain + inline fallback from the Phase 3 routing table (29 rows). Data file is the programmatic source of truth; the skill's table is documentation that mirrors it. Default mode prints a match block; `--json` for machine consumption; `--list` enumerates all rows. | `skills/proceed-with-the-recommendation.md` (Phase 3 routing table) |
+| `run-synthetic.mjs` | Phase 9 runner: invoke every `*.synthetic.{sh,mjs,ts,py}` in `synthetic-checks/`, inject `BASE_URL`/`BASELINE_URL`/`EXPECTED_SHA`/`DEPLOY_BRANCH`/`RECEIPT_TIMESTAMP` (unset vars pass through as `""`), capture stdout/stderr/exit per check, aggregate. Default mode prints the report block; `--json` for machine consumption; `--fail-fast` halts on first drift or timeout; `--timeout <sec>` per-check wall-clock cap; `--show-command` dry-run. Exit 0 all-pass, 1 drift, 2 config error, 3 usage. | `skills/verification-loop.md` (Phase 9 — production-vs-baseline diff) |
+
+When a new script lands here, add a row to this table in the same PR and cite the script from at least one skill — otherwise the script is dead code on arrival.
+
+## Relationship to other locations
+
+- `bin/` — generated CLI entrypoints (`.mjs` from `src/bin/*.mts`). Do not hand-edit; see [`CLAUDE.md`](../CLAUDE.md) → "Build pipeline".
+- `lib/` — generated library code (`.mjs` from `src/lib/*.mts`). Same rule.
+- `hooks/` — generated PreToolUse / PostToolUse / Stop hooks (`.mjs` from `src/hooks/*.mts`). Wired in `plugins/continuous-improvement/hooks/hooks.json`.
+- `scripts/` — this directory. Hand-authored primitives skills cite.
+
+When deciding where a new piece of code belongs: if it implements a runtime hook the harness will call, it goes in `src/hooks/`. If it's a verification or CLI entrypoint the plugin or `npm run` invokes, it goes in `src/bin/`. If it's reusable logic shared between those, it goes in `src/lib/`. If it's a small primitive a skill body cites by path (and the operator or harness runs ad hoc), it goes here.

package/scripts/detect-deploy-target.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# scripts/detect-deploy-target.sh
+#
+# Detect the auto-deploy provider for the repo rooted at the current working
+# directory (or the first argument, if supplied). Composability primitive used
+# by skills and hooks that need to know "does this repo auto-deploy, and if so
+# from where?" without each restating the file-marker table.
+#
+# Output: one of
+#   railway | cloudflare | vercel | netlify | fly | appengine | apprunner |
+#   gha-deploy | none
+#
+# Resolution priority (first match wins):
+#   1. railway.toml | railway.json                              → railway
+#   2. wrangler.toml | wrangler.jsonc                           → cloudflare
+#   3. vercel.json | .vercel/                                   → vercel
+#   4. netlify.toml                                             → netlify
+#   5. fly.toml                                                 → fly
+#   6. app.yaml                                                 → appengine
+#   7. apprunner.yaml                                           → apprunner
+#   8. .github/workflows/*.{yml,yaml} containing "deploy:" job  → gha-deploy
+#   9. nothing matched                                          → none
+#
+# Always exits 0. `none` is a valid result, not an error condition.
+#
+# Cited by:
+#   - skills/verification-loop.md Phase 8 (deploy-receipt handoff trigger)
+#   - skills/deploy-receipt.md "When to Activate" gate
+
+set -u
+
+ROOT="${1:-$PWD}"
+
+emit() {
+  printf '%s\n' "$1"
+  exit 0
+}
+
+# Order is the contract — earlier rows shadow later ones when multiple
+# markers exist in the same repo.
+[ -f "$ROOT/railway.toml" ]    && emit railway
+[ -f "$ROOT/railway.json" ]    && emit railway
+[ -f "$ROOT/wrangler.toml" ]   && emit cloudflare
+[ -f "$ROOT/wrangler.jsonc" ]  && emit cloudflare
+[ -f "$ROOT/vercel.json" ]     && emit vercel
+[ -d "$ROOT/.vercel" ]         && emit vercel
+[ -f "$ROOT/netlify.toml" ]    && emit netlify
+[ -f "$ROOT/fly.toml" ]        && emit fly
+[ -f "$ROOT/app.yaml" ]        && emit appengine
+[ -f "$ROOT/apprunner.yaml" ]  && emit apprunner
+
+# GitHub Actions deploy workflow: scan .github/workflows/*.{yml,yaml} for a
+# job whose key is literally `deploy:`. Cheap and conservative — false
+# positives (a non-deploy job named "deploy") are unlikely; false negatives
+# (a deploy job named something else) require the repo to declare the
+# provider via one of the file markers above instead.
+if [ -d "$ROOT/.github/workflows" ]; then
+  if grep -lE '^[[:space:]]*deploy:[[:space:]]*$' \
+        "$ROOT/.github/workflows/"*.yml \
+        "$ROOT/.github/workflows/"*.yaml 2>/dev/null \
+      | head -n 1 | grep -q .; then
+    emit gha-deploy
+  fi
+fi
+
+emit none

package/scripts/get-deployed-sha.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# scripts/get-deployed-sha.sh
+#
+# Print the currently-deployed commit SHA for an auto-deploy provider, or
+# print the CLI command shape (with `--show-command`) without executing it.
+# Composability primitive that owns the per-provider CLI knowledge so skills
+# can cite one path instead of restating the 5-provider extraction table.
+#
+# Usage:
+#   bash scripts/get-deployed-sha.sh <provider>
+#   bash scripts/get-deployed-sha.sh --show-command <provider>
+#
+# Providers: railway | cloudflare | vercel | netlify | fly
+#
+# Default mode: runs the provider CLI, pipes through jq, prints the SHA on
+# stdout. Requires the CLI to be installed and authenticated; exits 3 with a
+# clear error if the CLI is missing.
+#
+# --show-command mode: prints the command pipeline that would run, without
+# executing it. Useful for skill citations, dry-runs, and tests that should
+# not require live CLI auth.
+#
+# Exit codes:
+#   0 — SHA printed (default mode) or command printed (--show-command mode)
+#   2 — missing or unknown provider (usage error)
+#   3 — required CLI not installed (default mode only)
+#   non-zero — CLI failure (passed through)
+#
+# Cited by:
+#   - skills/verification-loop.md Phase 8 (deploy-receipt handoff trigger)
+#   - skills/deploy-receipt.md Route A (provider CLI extraction)
+
+set -u
+
+SHOW_COMMAND=false
+PROVIDER=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --show-command)
+      SHOW_COMMAND=true
+      shift
+      ;;
+    -h|--help)
+      sed -n '2,/^$/p' "$0" >&2
+      exit 0
+      ;;
+    *)
+      if [ -z "$PROVIDER" ]; then
+        PROVIDER="$1"
+      else
+        printf 'usage: get-deployed-sha.sh [--show-command] <provider>\n' >&2
+        exit 2
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [ -z "$PROVIDER" ]; then
+  printf 'usage: get-deployed-sha.sh [--show-command] <provider>\n' >&2
+  exit 2
+fi
+
+# Single source of truth for the per-provider command pipeline. Each value is
+# the literal pipeline that would run; the jq filter extracts the SHA.
+case "$PROVIDER" in
+  railway)
+    CMD='railway status --json | jq -r .deployments[0].meta.commitHash'
+    CLI=railway
+    ;;
+  cloudflare)
+    CMD='wrangler deployments list --json | jq -r .[0].metadata.deployment_trigger.metadata.commit_hash'
+    CLI=wrangler
+    ;;
+  vercel)
+    CMD='vercel inspect "$(vercel ls --json | jq -r .[0].url)" --json | jq -r .gitSource.sha'
+    CLI=vercel
+    ;;
+  netlify)
+    CMD='netlify api listSiteDeploys --data="{\"site_id\":\"$NETLIFY_SITE_ID\"}" | jq -r .[0].commit_ref'
+    CLI=netlify
+    ;;
+  fly)
+    CMD='fly releases --json | jq -r .[0].commit_sha'
+    CLI=fly
+    ;;
+  *)
+    printf 'unknown or unsupported provider: %s\n' "$PROVIDER" >&2
+    printf 'supported: railway | cloudflare | vercel | netlify | fly\n' >&2
+    exit 2
+    ;;
+esac
+
+if [ "$SHOW_COMMAND" = "true" ]; then
+  printf '%s\n' "$CMD"
+  exit 0
+fi
+
+if ! command -v "$CLI" >/dev/null 2>&1; then
+  printf 'required CLI "%s" not installed for provider "%s"\n' "$CLI" "$PROVIDER" >&2
+  exit 3
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'required CLI "jq" not installed\n' >&2
+  exit 3
+fi
+
+# Execute the pipeline. eval is intentional — the per-provider CMD contains
+# pipes and command substitution that need shell interpretation. CMDs are
+# sourced from the literal table above, not user input.
+eval "$CMD"

package/scripts/git-state-snapshot.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# scripts/git-state-snapshot.sh
+#
+# Emit a single-line JSON envelope describing the current git working-tree
+# state. Composability primitive used by skills that need to baseline or check
+# git state without each restating the same 3-command triple.
+#
+# Fields:
+#   - head:     short SHA returned by `git rev-parse --short HEAD`
+#   - upstream: short SHA of `@{u}` if the branch tracks an upstream, else "none"
+#   - dirty:    integer count of lines from `git status --porcelain` (0 == clean)
+#   - root:     absolute path from `git rev-parse --show-toplevel`
+#   - branch:   `git symbolic-ref --short HEAD`, else "detached"
+#
+# Outside a git repository the script prints `{"error":"not-a-git-repo"}` and
+# exits 1. All other failures are treated as a non-git-repo condition rather
+# than emitting a partial envelope.
+#
+# Cited by:
+#   - skills/gateguard.md            (Parallel-Actor Gate baseline + divergence)
+#   - skills/worktree-safety.md      (Root + branch alignment)
+#   - skills/workspace-surface-audit.md (Environment Grain — parallel-actor row)
+
+set -u
+
+head=$(git rev-parse --short HEAD 2>/dev/null) || {
+  printf '{"error":"not-a-git-repo"}\n'
+  exit 1
+}
+
+if upstream=$(git rev-parse --short '@{u}' 2>/dev/null); then
+  upstream_field=$(printf '"%s"' "$upstream")
+else
+  upstream_field='"none"'
+fi
+
+dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+root=$(git rev-parse --show-toplevel 2>/dev/null || printf 'unknown')
+
+if branch=$(git symbolic-ref --short HEAD 2>/dev/null); then
+  branch_field=$(printf '"%s"' "$branch")
+else
+  branch_field='"detached"'
+fi
+
+printf '{"head":"%s","upstream":%s,"dirty":%s,"root":"%s","branch":%s}\n' \
+  "$head" "$upstream_field" "$dirty" "$root" "$branch_field"

package/scripts/resolve-verify-ladder.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// scripts/resolve-verify-ladder.mjs
+//
+// Resolve the per-project verification ladder for `verification-loop` Phase 0.
+// Encodes the four-step resolution priority — manifest > package.json sniff >
+// per-language toolchain > ask-operator — so the skill body cites this script
+// instead of restating the 80+ lines of priority prose inline.
+//
+// Usage:
+//   node scripts/resolve-verify-ladder.mjs              # pretty fenced block, cwd
+//   node scripts/resolve-verify-ladder.mjs <repo-root>  # pretty, explicit root
+//   node scripts/resolve-verify-ladder.mjs --json       # JSON for machines
+//   node scripts/resolve-verify-ladder.mjs --json <repo-root>
+//
+// Output (default — pretty fenced block):
+//
+//   verify-ladder (resolved):
+//     build:            npm run build  (sniff:package.json:scripts.build)
+//     typecheck:        npx tsc --noEmit  (manifest)
+//     ...
+//
+// Output (--json — single JSON object on stdout):
+//
+//   { "build": { "command": "npm run build", "source": "sniff:..." }, ... }
+//
+// Phases: build, typecheck, lint, test, security, deploy_receipt, synthetic_checks.
+// Sources: "manifest", "manifest:null" (explicitly skipped), "sniff:package.json:<key>",
+//          "sniff:Cargo.toml" | "sniff:go.mod" | "sniff:pyproject.toml" | "sniff:Gemfile",
+//          "ask-operator" (nothing matched).
+//
+// Cited by:
+//   - skills/verification-loop.md Phase 0
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit, stdout } from "node:process";
+
+const PHASES = [
+  "build",
+  "typecheck",
+  "lint",
+  "test",
+  "security",
+  "deploy_receipt",
+  "synthetic_checks",
+];
+
+function parseArgs() {
+  const args = argv.slice(2);
+  let json = false;
+  let root = cwd();
+  for (const a of args) {
+    if (a === "--json") {
+      json = true;
+    } else if (a === "-h" || a === "--help") {
+      stdout.write(
+        "usage: resolve-verify-ladder.mjs [--json] [<repo-root>]\n",
+      );
+      exit(0);
+    } else {
+      root = a;
+    }
+  }
+  return { json, root };
+}
+
+function safeReadJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readManifest(root) {
+  return safeReadJson(join(root, ".claude", "verify-ladder.json"));
+}
+
+function readPackageJson(root) {
+  return safeReadJson(join(root, "package.json"));
+}
+
+function sniffPackageJsonScript(pkg, phase) {
+  if (!pkg || !pkg.scripts) return null;
+  const scripts = pkg.scripts;
+  // Priority: verify:<phase> > <phase> > <phase>:* (wildcard tail).
+  // Phase aliases:
+  //   typecheck also matches `tsc` (common in repos that just use `tsc`).
+  //   security also matches `audit` (common in npm projects).
+  const candidates = [`verify:${phase}`, phase];
+  if (phase === "typecheck") candidates.push("tsc");
+  if (phase === "security") candidates.push("audit");
+
+  for (const name of candidates) {
+    if (typeof scripts[name] === "string") {
+      const cmd = name === "test" ? "npm test" : `npm run ${name}`;
+      return {
+        command: cmd,
+        source: `sniff:package.json:scripts.${name}`,
+      };
+    }
+  }
+
+  // Last resort: <phase>:* wildcard tail.
+  const wildcardKey = Object.keys(scripts).find((k) => k.startsWith(`${phase}:`));
+  if (wildcardKey) {
+    return {
+      command: `npm run ${wildcardKey}`,
+      source: `sniff:package.json:scripts.${wildcardKey}`,
+    };
+  }
+
+  return null;
+}
+
+const PER_LANGUAGE = [
+  {
+    marker: "Cargo.toml",
+    commands: {
+      build: "cargo build",
+      typecheck: "cargo check --all-targets",
+      lint: "cargo clippy --all-targets -- -D warnings",
+      test: "cargo test",
+      security: "cargo audit",
+    },
+  },
+  {
+    marker: "go.mod",
+    commands: {
+      build: "go build ./...",
+      typecheck: "go vet ./...",
+      lint: "go vet ./...",
+      test: "go test ./...",
+    },
+  },
+  {
+    marker: "pyproject.toml",
+    commands: {
+      typecheck: "pyright",
+      lint: "ruff check .",
+      test: "pytest",
+    },
+  },
+  {
+    marker: "Gemfile",
+    commands: {
+      lint: "bundle exec rubocop",
+      test: "bundle exec rspec",
+    },
+  },
+];
+
+function sniffPerLanguage(root, phase) {
+  for (const lang of PER_LANGUAGE) {
+    if (!existsSync(join(root, lang.marker))) continue;
+    if (lang.commands[phase]) {
+      return { command: lang.commands[phase], source: `sniff:${lang.marker}` };
+    }
+  }
+  return null;
+}
+
+function resolve(root) {
+  const manifest = readManifest(root);
+  const pkg = readPackageJson(root);
+  const ladder = {};
+
+  for (const phase of PHASES) {
+    // 1. Manifest layer. Underscore-prefixed keys in the manifest are
+    //    documentation/examples — verify-ladder.example.json uses keys like
+    //    "_doc", "_node_example" — so PHASES never starts with "_" and we
+    //    can rely on hasOwn for an exact phase match.
+    if (
+      manifest &&
+      Object.prototype.hasOwnProperty.call(manifest, phase) &&
+      !phase.startsWith("_")
+    ) {
+      const value = manifest[phase];
+      if (value === null) {
+        ladder[phase] = { command: null, source: "manifest:null" };
+      } else if (typeof value === "string") {
+        ladder[phase] = { command: value, source: "manifest" };
+      } else {
+        ladder[phase] = { command: null, source: "manifest:invalid" };
+      }
+      continue;
+    }
+
+    // 2. package.json scripts sniff.
+    const pkgHit = sniffPackageJsonScript(pkg, phase);
+    if (pkgHit) {
+      ladder[phase] = pkgHit;
+      continue;
+    }
+
+    // 3. Per-language toolchain sniff.
+    const langHit = sniffPerLanguage(root, phase);
+    if (langHit) {
+      ladder[phase] = langHit;
+      continue;
+    }
+
+    // 4. Nothing matched — operator must declare or set to null.
+    ladder[phase] = { command: null, source: "ask-operator" };
+  }
+
+  return ladder;
+}
+
+function pretty(ladder) {
+  const widest = Math.max(...Object.keys(ladder).map((k) => k.length));
+  const lines = ["verify-ladder (resolved):"];
+  for (const [phase, entry] of Object.entries(ladder)) {
+    const label = `${phase}:`.padEnd(widest + 2);
+    let line;
+    if (entry.command === null && entry.source === "ask-operator") {
+      line = `  ${label} (ask operator — no marker found)`;
+    } else if (entry.command === null && entry.source === "manifest:null") {
+      line = `  ${label} (skipped — manifest set this field to null)`;
+    } else if (entry.command === null) {
+      line = `  ${label} (skipped — ${entry.source})`;
+    } else {
+      line = `  ${label} ${entry.command}  (${entry.source})`;
+    }
+    lines.push(line);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function main() {
+  const { json, root } = parseArgs();
+  const ladder = resolve(root);
+  if (json) {
+    stdout.write(JSON.stringify(ladder, null, 2) + "\n");
+  } else {
+    stdout.write(pretty(ladder));
+  }
+}
+
+main();