continuous-improvement 3.9.2 → 3.12.3

package/skills/token-budget-advisor.md

@@ -38,7 +38,7 @@ Intercept the response flow to offer the user a choice about response depth **be
 
 Use the repository's canonical context-budget heuristics to estimate the prompt's token count mentally.
 
-Use the same calibration guidance as [context-budget](../context-budget/SKILL.md):
+Use the same calibration guidance as `context-budget`:
 
 - prose: `words × 1.3`
 - code-heavy or mixed/code blocks: `chars / 4`

package/skills/verification-loop.md

@@ -23,7 +23,21 @@ 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.
 
-**Resolution priority** (first match wins):
+**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.
+
+```
+$ node 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)
+  lint:              npm run lint  (sniff:package.json:scripts.lint)
+  test:              npm test  (sniff:package.json:scripts.test)
+  security:          (ask operator — no marker found)
+  deploy_receipt:    (ask operator — no marker found)
+  synthetic_checks:  (ask operator — no marker found)
+```
+
+**Resolution priority** (first match wins; the script implements this — the prose is documentation):
 
 1. **`.claude/verify-ladder.json` manifest** at the repo root. Schema:
    ```json
@@ -36,24 +50,12 @@ Every project has its own actual invocation for build / typecheck / lint / test
      "deploy_receipt": "npx wrangler deployments list --json"
    }
    ```
-   Any field omitted falls through to step 2 for that field only. A field set to the literal string `null` means "skip this phase for this project."
-2. **Sniff `package.json` `scripts`** for `build`, `typecheck` or `tsc`, `lint`, `test`, `audit` or `security`. Tie-breaker when multiple scripts could match a phase: prefer `verify:<phase>` over `<phase>` over `<phase>:*`. Do NOT pick `test` when `verify:test` exists; the operator's explicit verification surface always wins over the convenience alias.
-3. **Sniff per-language toolchain files** if `package.json` is absent: `Cargo.toml` → `cargo build` / `cargo test`, `go.mod` → `go build ./...` / `go test ./...`, `pyproject.toml` → `pytest` / `ruff check`, `Gemfile` → `bundle exec rspec`, etc.
-4. **Ask the operator** if none of the above resolves the field. Do not invent.
+   Any field omitted falls through to step 2 for that field only. A field set to the literal JSON `null` means "skip this phase for this project" — the resolver records source `manifest:null`. Underscore-prefixed keys (`_doc`, `_node_example`, etc.) are ignored as documentation/examples.
+2. **Sniff `package.json` `scripts`** for `build`, `typecheck` or `tsc`, `lint`, `test`, `audit` or `security`. Tie-breaker when multiple scripts could match a phase: prefer `verify:<phase>` over `<phase>` over `<phase>:*` (wildcard tail). Do NOT pick `test` when `verify:test` exists; the operator's explicit verification surface always wins over the convenience alias.
+3. **Sniff per-language toolchain files** if `package.json` is absent: `Cargo.toml` → `cargo build` / `cargo check` / `cargo clippy` / `cargo test` / `cargo audit`, `go.mod` → `go build ./...` / `go vet ./...` / `go test ./...`, `pyproject.toml` → `pyright` / `ruff check .` / `pytest`, `Gemfile` → `bundle exec rspec` / `bundle exec rubocop`.
+4. **Ask the operator** (source `ask-operator`) if none of the above resolves the field. Do not invent.
 
-**Output the resolved ladder** as a single fenced block before running any phase, so the operator can spot a wrong resolution before it costs a misread:
-
-```
-verify-ladder (resolved):
-  build:           npm run build
-  typecheck:       npx tsc --noEmit  (sniff: package.json scripts.typecheck)
-  lint:            npm run lint
-  test:            npm test
-  security:        (skipped — no script defined)
-  deploy_receipt:  npx wrangler deployments list --json  (manifest)
-```
-
-Each row shows the resolved command + its source (manifest, sniff, or skipped). The fenced block is the contract surface — every later phase reads from this resolved ladder, never from a hardcoded fallback.
+Each row shows the resolved command + its source (`manifest`, `sniff:<file>:<key>`, `manifest:null`, or `ask-operator`). The fenced block is the contract surface — every later phase reads from this resolved ladder, never from a hardcoded fallback.
 
 A starter manifest is provided at `templates/verify-ladder.example.json`; copy it to `.claude/verify-ladder.json` and trim per project.
 
@@ -143,7 +145,11 @@ If either is `No`, the verification report goes back to the operator with the ex
 
 ### Phase 8: Deploy Receipt (auto-deploy projects only)
 
-For repos whose `verify-ladder.json` declares a `deploy_receipt` field — or whose sniff path detects an auto-deploy target (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io) — 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.
+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).
+
+**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.
 
 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).
 
@@ -158,11 +164,13 @@ 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.
+
 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).
 3. Invoke the file via the right interpreter (`bash` for `.sh`, `node` for `.mjs`, `tsx` for `.ts`, `python` for `.py`). Files with unrecognized extensions are skipped with a warning.
 4. Capture stdout + stderr + exit code per file. On exit 0, the check passed. On any non-zero exit, the check failed and stdout is the operator-facing diff.
-5. Aggregate: if every file exited 0, Phase 9 is `PASS`. If any file exited non-zero, Phase 9 is `FAIL — synthetic drift on <filenames>` and the captured diffs go into the verification report verbatim (no agent re-summarization).
+5. Aggregate: if every file exited 0, Phase 9 is `PASS`. If any file exited non-zero, Phase 9 is `FAIL — synthetic drift on <filenames>` and the captured diffs go into the verification report verbatim (no agent re-summarization). Exit code 2 with zero drift (every non-pass was a config error from the check itself) surfaces as `INCOMPLETE — config error` to distinguish "gate did not run" from "gate ran and found drift".
 
 **Surfacing rule:**
 

package/skills/wild-risa-balance.md

@@ -3,6 +3,7 @@ name: wild-risa-balance
 tier: "2"
 description: Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline. Decision-framing lens that pairs WILD generation with RISA execution when emitting recommendation lists. Not a runtime hook.
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # WILD / RISA Balance

package/skills/workspace-surface-audit.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 must baseline `git rev-parse HEAD` + `git status --porcelain` + upstream before the first mutation, and re-check on every subsequent mutation.
+- **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.
 
 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/skills/worktree-safety.md

@@ -3,6 +3,7 @@ name: worktree-safety
 tier: "2"
 description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: validate worktree root before any source-writing tool call. Catches missing .git, fallback path-only creation, stale leases, foreign-session ownership, and non-worktree git operations before they corrupt history."
 origin: continuous-improvement
+user-invocable: false
 ---
 
 # Worktree Safety Skill
@@ -31,10 +32,10 @@ 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.
+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.
 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.
+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.
 5. **Lease ownership** — the session ID in `.git/worktrees/<name>/lease` (or your equivalent ledger) matches this session. Stale or foreign leases block the call.
 
 Output a single fenced block before any source-writing dispatch: