continuous-improvement 3.1.0 → 3.9.1

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

@@ -0,0 +1,147 @@
+---
+name: workspace-surface-audit
+tier: companion
+description: "Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Audits the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup, then recommends the highest-value continuous-improvement-native skills, hooks, agents, and operator workflows. Use when the user wants help setting up Claude Code or understanding what capabilities are actually available in their environment."
+origin: continuous-improvement
+---
+
+# Workspace Surface Audit
+
+Read-only audit skill for answering the question "what can this workspace and machine actually do right now, and what should we add or enable next?"
+
+This is the continuous-improvement answer to setup-audit plugins. It does not modify files unless the user explicitly asks for follow-up implementation.
+
+## When to Use
+
+- User says "set up Claude Code", "recommend automations", "what plugins or MCPs should I use?", or "what am I missing?"
+- Auditing a machine or repo before installing more skills, hooks, or connectors
+- Comparing official marketplace plugins against continuous-improvement coverage
+- Reviewing `.env`, `.mcp.json`, plugin settings, or connected-app surfaces to find missing workflow layers
+- Deciding whether a capability should be a skill, hook, agent, MCP, or external connector
+
+## Non-Negotiable Rules
+
+- Never print secret values. Surface only provider names, capability names, file paths, and whether a key or config exists.
+- Prefer continuous-improvement workflows over generic "install another plugin" advice when continuous-improvement can reasonably own the surface.
+- Treat external plugins as benchmarks and inspiration, not authoritative product boundaries.
+- Separate three things clearly:
+  - already available now
+  - available but not wrapped well in continuous-improvement
+  - not available and would require a new integration
+
+## Audit Inputs
+
+Inspect only the files and settings needed to answer the question well:
+
+1. **Repo surface**
+   - `package.json`, lockfiles, language markers, framework config, `README.md`
+   - `.mcp.json`, `.lsp.json`, `.claude/settings*.json`, `.codex/*`
+   - `AGENTS.md`, `CLAUDE.md`, install manifests, hook configs
+2. **Environment surface**
+   - `.env*` files in the active repo and obvious adjacent continuous-improvement workspaces
+   - Surface only key names such as `STRIPE_API_KEY`, `TWILIO_AUTH_TOKEN`, `FAL_KEY`
+3. **Connected tool surface**
+   - Installed plugins, enabled connectors, MCP servers, LSPs, and app integrations
+4. **continuous-improvement surface**
+   - Existing skills, commands, hooks, agents, and install modules that already cover the need
+
+## Audit Process
+
+### Phase 1: Inventory What Exists
+
+Produce a compact inventory:
+
+- active harness targets
+- installed plugins and connected apps
+- configured MCP servers
+- configured LSP servers
+- env-backed services implied by key names
+- existing continuous-improvement skills already relevant to the workspace
+
+If a surface exists only as a primitive, call that out. Example:
+
+- "Stripe is available via connected app, but continuous-improvement lacks a billing-operator skill"
+- "Google Drive is connected, but there is no continuous-improvement-native Google Workspace operator workflow"
+
+#### Environment Grain
+
+Before any tool-class advice, capture the per-host facts that make commands either run or fail. The 28-day usage report's recurring "command failed / wrong approach" friction class roots almost entirely in this grain being unrecorded at session start — the agent reaches for `jq`, finds it missing, retries; reaches for bash chaining, hits PowerShell parser errors, retries; trusts a stale `pwd` after `tsc`, runs verification from the wrong directory, retries.
+
+Probe and record (no destructive commands; quote results inline):
+
+- **Shell flavor.** `echo $SHELL` on POSIX or `$PSVersionTable.PSEdition` on Windows; detect `bash`, `zsh`, `pwsh`, or `cmd`. PowerShell on Windows treats `&&`, `2>&1`, and quoting differently from bash; Git Bash on Windows is bash-shaped but lacks several POSIX utilities by default.
+- **OS family + line endings.** `uname -s` (or PowerShell `$IsWindows`) plus `git config --get core.autocrlf`. On Windows with `core.autocrlf=true`, `git status` reports phantom modifications on every checked-out file — `git diff --stat` is the reliable change-set view.
+- **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.
+
+Output the recorded grain as a single fenced block so it survives context compaction and any later phase can reference it without re-probing:
+
+```
+shell-flavor:    pwsh
+os:              windows-11 / autocrlf=true
+jq:              missing
+case-sensitive:  false
+cwd-baseline:    D:/Ai/continuous-improvement
+parallel-actor:  yes
+```
+
+The fenced block is the contract surface — keep the field names stable so downstream skills (`gateguard`, `verification-loop`, future autonomous-release-train) can parse it without per-host special-casing.
+
+### Phase 2: Benchmark Against Official and Installed Surfaces
+
+Compare the workspace against:
+
+- official Claude plugins that overlap with setup, review, docs, design, or workflow quality
+- locally installed plugins in Claude or Codex
+- the user's currently connected app surfaces
+
+Do not just list names. For each comparison, answer:
+
+1. what they actually do
+2. whether continuous-improvement already has parity
+3. whether continuous-improvement only has primitives
+4. whether continuous-improvement is missing the workflow entirely
+
+### Phase 3: Turn Gaps Into continuous-improvement Decisions
+
+For every real gap, recommend the correct continuous-improvement-native shape:
+
+| Gap Type | Preferred continuous-improvement Shape |
+|----------|---------------------|
+| Repeatable operator workflow | Skill |
+| Automatic enforcement or side-effect | Hook |
+| Specialized delegated role | Agent |
+| External tool bridge | MCP server or connector |
+| Install/bootstrap guidance | Setup or audit skill |
+
+Default to user-facing skills that orchestrate existing tools when the need is operational rather than infrastructural.
+
+## Output Format
+
+Return five sections in this order:
+
+1. **Current surface** — what is already usable right now
+2. **Parity** — where continuous-improvement already matches or exceeds the benchmark
+3. **Primitive-only gaps** — tools exist, but continuous-improvement lacks a clean operator skill
+4. **Missing integrations** — capability not available yet
+5. **Top 3-5 next moves** — concrete continuous-improvement-native additions, ordered by impact
+
+## Recommendation Rules
+
+- Recommend at most 1-2 highest-value ideas per category.
+- Favor skills with obvious user intent and business value:
+  - setup audit
+  - billing/customer ops
+  - issue/program ops
+  - Google Workspace ops
+  - deployment/ops control
+- If a connector is company-specific, recommend it only when it is genuinely available or clearly useful to the user's workflow.
+- If continuous-improvement already has a strong primitive, propose a wrapper skill instead of inventing a brand-new subsystem.
+
+## Good Outcomes
+
+- The user can immediately see what is connected, what is missing, and what continuous-improvement should own next.
+- Recommendations are specific enough to implement in the repo without another discovery pass.
+- The final answer is organized around workflows, not API brands.

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

@@ -0,0 +1,66 @@
+---
+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
+---
+
+# Worktree Safety Skill
+
+A pre-dispatch invariant. Before any tool call that writes source files or runs git, validate that the current working directory is a registered worktree with a healthy `.git`, owned by this session, on the expected branch.
+
+## When to Use
+
+- Before every Edit / Write / Bash that touches source code in a multi-worktree session.
+- Before any `git` command in an auto-loop.
+- After any pause/resume — CWD may have drifted, the worktree may have been pruned, the lease may have expired.
+- When the verification ladder reports a class-`worktree` failure (see `recovery-classification`).
+
+## Why This Skill Exists
+
+GSD-2's [CONTEXT.md](https://github.com/gsd-build/gsd-2/blob/main/CONTEXT.md) names "Worktree Safety" as one of four runtime invariant modules. Common failure modes it catches:
+
+- **Units dispatch into ghost / invalid worktree roots** — `.git` missing, fallback path-only creation, the worktree was pruned but the loop kept its handle.
+- **Health checks unit-specific instead of lifecycle-wide** — earlier units (sketch, plan) write into invalid roots before any check runs.
+- **Brittle exit / merge signals** — relying on artifact presence instead of authoritative branch and commit state.
+- **Parallel actors mutating the working tree of a worktree they don't own** — a known hazard on this host (see `feedback_parallel_actor.md`).
+
+The continuous-improvement repo runs on Windows + Git Bash with `autocrlf=true` and a parallel-actor expectation, both of which make weak worktree handling expensive.
+
+## The Five-Check Envelope
+
+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.
+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.
+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:
+
+```
+worktree-safety (resolved):
+  root:          d:/Ai/ci-wt-skill-trio  (matches CWD, canonicalized)
+  .git:          file pointer → /shared/.git/worktrees/skill-trio  (present)
+  registration:  listed in `git worktree list` (not prunable)
+  branch:        feat/verification-ladder-skill-trio  (matches lease)
+  lease:         owned by session 4f2a (this session)  → CLEAR
+```
+
+If any line is non-`CLEAR`, dispatch is blocked and the failure routes to `recovery-classification` as class `worktree`.
+
+## Anti-Patterns
+
+- **Per-tool checks, not lifecycle checks.** Validating only at execute-task lets sketch / plan / research units write into invalid roots first.
+- **Trusting CWD.** A `process.chdir` (or operator `cd`) in another loop iteration can leave CWD pointing at a pruned worktree. Re-resolve every time; do not cache.
+- **Fallback-to-primary on worktree miss.** Silently writing to the primary checkout when the worktree is broken is the worst recovery — it corrupts the wrong branch with no audit trail.
+- **Skipping lease ownership.** Two sessions in the same worktree race on every commit. The lease is the authoritative single-writer signal; do not skip it because "it's only one session" — that assumption breaks the moment a parallel actor appears.
+- **Allowing detached HEAD silently.** A detached HEAD is sometimes legitimate (bisect, snapshot read), but every check must name whether detached is expected for this unit.
+
+## Pairs With
+
+- [verification-loop](verification-loop.md) — runs as a pre-Phase-0 invariant; the resolved-safety block fires before the resolved-ladder block.
+- [state-reconciliation](state-reconciliation.md) — both fire before dispatch; safety runs first because reconciliation depends on a valid worktree root.
+- [recovery-classification](recovery-classification.md) — any non-`CLEAR` line routes here as class `worktree`.
+- [gateguard](gateguard.md) — gateguard fires at the tool boundary; worktree-safety is the lifecycle counterpart that runs before tool dispatch is even considered.

package/plugins/continuous-improvement/templates/planning-with-files/findings.md

@@ -0,0 +1,8 @@
+# Findings
+
+## Research Notes
+- Created on {{date}}.
+- Record source links, code references, and synthesized findings here.
+
+## Sources
+- Add links and short summaries here.

package/plugins/continuous-improvement/templates/planning-with-files/progress.md

@@ -0,0 +1,7 @@
+# Progress
+
+## Session Log
+- {{date}}: Initialized planning files.
+
+## Verification Notes
+- Record commands, tests, outputs, and checkpoints here.

package/plugins/continuous-improvement/templates/planning-with-files/task_plan.md

@@ -0,0 +1,23 @@
+# Task Plan
+
+## Goal
+{{goal}}
+
+## Status
+{{status}}
+
+## Phases
+{{phases}}
+
+## Key Questions
+- [ ] What existing implementation or context should be reviewed first?
+- [ ] What constraints or risks need validation before execution?
+- [ ] What verification proves the task is complete?
+
+## Decisions Made
+- None yet.
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+| --- | --- | --- |
+| None yet | - | - |

package/plugins/expert.json

@@ -1,8 +1,8 @@
 {
   "name": "continuous-improvement",
-  "version": "3.1.0",
+  "version": "3.9.0",
   "mode": "expert",
-  "description": "Full plugin: 10 tools including instinct management, import/export, observation viewer, dashboard, and instinct packs.",
+  "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 disciplined and learnings survive context resets.",
   "tools": [
     {
       "name": "ci_status",
@@ -36,6 +36,14 @@
       "name": "ci_import",
       "what": "Import instincts from JSON (skip duplicates)"
     },
+    {
+      "name": "ci_plan_init",
+      "what": "Create project-root planning files for persistent task memory"
+    },
+    {
+      "name": "ci_plan_status",
+      "what": "Summarize task_plan.md, findings.md, and progress.md status"
+    },
     {
       "name": "ci_dashboard",
       "what": "Visual dashboard showing instinct health, confidence distribution, and learning progress"
@@ -50,7 +58,11 @@
       "mcpServers": {
         "continuous-improvement": {
           "command": "node",
-          "args": ["<install-path>/bin/mcp-server.mjs", "--mode", "expert"]
+          "args": [
+            "<install-path>/bin/mcp-server.mjs",
+            "--mode",
+            "expert"
+          ]
         }
       }
     },
@@ -58,13 +70,22 @@
       "mcpServers": {
         "continuous-improvement": {
           "command": "node",
-          "args": ["<install-path>/bin/mcp-server.mjs", "--mode", "expert"]
+          "args": [
+            "<install-path>/bin/mcp-server.mjs",
+            "--mode",
+            "expert"
+          ]
         }
       }
     }
   },
   "hooks": {
-    "included": ["PreToolUse", "PostToolUse", "SessionStart", "SessionEnd"],
+    "included": [
+      "PreToolUse",
+      "PostToolUse",
+      "SessionStart",
+      "SessionEnd"
+    ],
     "description": "Full hook suite: observation capture + session-level instinct loading and auto-reflection."
   }
 }

package/skills/README.md

@@ -0,0 +1,79 @@
+# Source Skills
+
+This directory holds the **source-of-truth** for the companion skills bundled with the `continuous-improvement` plugin.
+
+> Edit files **here**. The plugin bundle at `plugins/continuous-improvement/skills/<name>/SKILL.md` is **regenerated** every time you run `npm run build` (see [`bin/generate-plugin-manifests.mjs`](../bin/generate-plugin-manifests.mjs)). Edits made directly inside `plugins/continuous-improvement/skills/` will be overwritten.
+
+## Featured companion — installed by default with the plugin
+
+`proceed-with-the-recommendation` is the **recommended pairing** for the 7 Laws. It is the execution arm that turns "do all of it" into a disciplined, verified, one-concern-at-a-time walk through the agent's recommendation list. If you only adopt one companion alongside the core skill, adopt this one.
+
+| Skill | What it does | Source |
+|-------|--------------|--------|
+| **`proceed-with-the-recommendation`** ⭐ | Walks any agent's recommendation list top-to-bottom under the 7 Laws — routes each item to the right specialist (`superpowers:*`, `ralph`, `workspace-surface-audit`, `simplify`, `security-review`, `schedule`, `loop`), falls back to inline behavior when a specialist isn't installed, verifies per item, halts on `needs-approval` | @naimkatiman |
+
+## Tier 1 — recommended pairing for **beginner** mode
+
+These add concrete enforcement to the 7 Laws. Tier-1 skills are the always-on minimum for any user running `npx continuous-improvement install` (default beginner mode).
+
+| Skill | What it does | Pairs with which Law |
+|-------|--------------|----------------------|
+| `para-memory-files` | File-based persistent memory using PARA (Projects/Areas/Resources/Archives) for cross-session context | Law 5 (Reflect), Law 7 (Learn) |
+| `verification-loop` | Six-phase verification (build, types, lint, tests, security, diff) with a structured PASS/FAIL report | Law 4 (Verify Before Reporting) |
+| `gateguard` | PreToolUse fact-forcing gate that blocks Edit/Write/destructive Bash until concrete investigation is presented | Law 1 (Research) |
+| `tdd-workflow` | RED→GREEN→REFACTOR enforcement, 80%+ coverage gate across unit/integration/E2E | Law 3 (One Thing), Law 4 (Verify) |
+
+## Tier 2 — additional skills for **expert** mode
+
+Tier-2 skills layer on top of tier-1 for users running `npx continuous-improvement install --mode expert`. They cover autonomous-mode safety, response-depth control, and context-window discipline that matter once an agent runs longer or more aggressively.
+
+| Skill | What it does | When it pays off |
+|-------|--------------|------------------|
+| `safety-guard` | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory | Autonomous loops, prod systems, `--dangerously-skip-permissions` sessions |
+| `token-budget-advisor` | Heuristic input/output token estimator that offers 25%/50%/75%/100% depth choices before answering | Long sessions where response size matters |
+| `strategic-compact` | PreToolUse hook that suggests `/compact` at logical phase boundaries (research→plan, plan→implement, debug→next) instead of arbitrary auto-compaction | Multi-phase tasks that approach context limits |
+| `wild-risa-balance` | Decision-framing lens that pairs WILD (Wild/Imaginative/Limitless/Disruptive) generation with RISA (Realistic/Important/Specific/Agreeable) execution, used to split recommendation lists into bold pilots above a safe baseline | Multi-item recommendation blocks where bold options keep losing to safe ones in a flat list |
+
+The `/learn-eval` slash command also ships as part of the expert install: extract a session pattern, run a checklist quality gate, and decide global-vs-project save location before writing any skill file.
+
+## Other always-bundled companion skills
+
+These ship in the same plugin bundle regardless of mode and are available the moment you install the `continuous-improvement` plugin from the marketplace.
+
+| Skill | What it does | Source |
+|-------|--------------|--------|
+| `ralph` | Autonomous loop that executes a PRD story-by-story with quality checks between iterations | [snarktank/ralph](https://github.com/snarktank/ralph) |
+| `superpowers` | **Law activator.** Routes tasks to the correct Law-aligned specialist (brainstorming → Law 2, writing-plans → Law 2, TDD → Law 3+4, verification-before-completion → Law 4, etc.) so the right discipline fires automatically. Not a peer skill — a dispatcher for the others. | [obra/superpowers](https://github.com/obra/superpowers) |
+| `workspace-surface-audit` | Audits the active repo, MCP servers, plugins, and env, then recommends high-value skills/workflows | continuous-improvement |
+
+## How they get to your machine
+
+Two paths, you pick:
+
+**Path A — Install the plugin (recommended).** Bundled with the core skill, no per-skill copying. All companions land in one shot:
+
+```bash
+/plugin marketplace add naimkatiman/continuous-improvement
+/plugin install continuous-improvement@continuous-improvement
+```
+
+(The `-dev` suffix is reserved for the in-repo development marketplace at `plugins/continuous-improvement/.claude-plugin/marketplace.json` — only used when iterating on the bundle locally.)
+
+**Path B — Drop a single skill in by hand.** Useful if you want only one companion without the rest of the plugin:
+
+```bash
+SKILL=proceed-with-the-recommendation
+mkdir -p ~/.claude/skills/$SKILL
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
+  -o ~/.claude/skills/$SKILL/SKILL.md
+```
+
+Or paste the file's contents directly into your agent's system prompt.
+
+## Pressure-test logs
+
+Adversarial pressure-test logs for skills in this directory live under [`docs/testing/`](../docs/testing/). They are not skills — they are baseline guarantees future edits must preserve.
+
+## Relationship to the core skill
+
+The core [`SKILL.md`](../SKILL.md) at the repo root defines the **7 Laws of discipline**. The skills in this directory are independent execution tools that build on those laws. They do not depend on `SKILL.md` and `SKILL.md` does not depend on them — but `proceed-with-the-recommendation` was written specifically to operationalize the 7 Laws end-to-end, which is why it's the featured pairing.

package/skills/deploy-receipt.md

@@ -0,0 +1,178 @@
+---
+name: deploy-receipt
+tier: "1"
+description: Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline at the deploy seam. A merge into a branch that auto-deploys is not "done" until the deploy provider reports the merged commit SHA running and a healthcheck endpoint returns 200. Companion to the vendored `finishing-a-development-branch` skill — does not replace it, runs after it for projects on Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, or any other auto-deploy target.
+origin: https://github.com/naimkatiman/continuous-improvement
+---
+
+# Deploy Receipt — Closing the Merge-to-Production Gap
+
+## Why This Skill Exists
+
+Multiple sessions in the operator's recent telemetry ended in a "partially achieved" state with the same shape: PR merged green, branch deleted, agent reports done — and then hours later the operator discovers the deploy provider never picked up the commit, was building from a stale lockfile, or silently rolled back. The merge happened. The deploy did not.
+
+`finishing-a-development-branch` (vendored from Obra superpowers in `third-party/superpowers/`) ends at the merge. For repos that do not auto-deploy that is the correct boundary. For repos that DO auto-deploy from `main` (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, Cloud Run, App Runner, et al.) the merge is only the trigger — the work is not done until the deployed SHA matches the merged HEAD and the application answers a healthcheck.
+
+This skill defines the receipt that closes that gap, without modifying the vendored upstream file.
+
+## When to Activate
+
+Activate when ALL of the following are true:
+
+1. A merge into the deploy branch (typically `main` or `master`) has just landed
+2. The repo declares an auto-deploy target — detect via any of:
+   - `railway.toml`, `railway.json`, or `RAILWAY_*` env vars in `.env.example`
+   - `wrangler.toml` / `wrangler.jsonc` (Cloudflare Workers)
+   - `vercel.json` or `.vercel/` directory
+   - `netlify.toml`
+   - `fly.toml`
+   - `app.yaml` (App Engine), `apprunner.yaml` (App Runner)
+   - GitHub Actions workflow with `deploy:` job triggered on push to the deploy branch
+3. `finishing-a-development-branch` has reported "merged" — not "PR opened", not "review pending"
+
+Do NOT activate when:
+- Repo is library-only / package-published (npm, PyPI, crates.io) — those have a different verification surface
+- Deploy is manual (operator runs `wrangler deploy` themselves) — the merge is genuinely the boundary
+- Merge target is a non-deploy branch (`develop`, `staging-only`, `experimental`)
+
+## What a Receipt Is
+
+A deploy receipt has three components, all required:
+
+1. **SHA match.** The deploy provider's currently-running revision SHA equals the merge commit SHA on the deploy branch. Not "the latest deploy started after the merge" — the SHA itself.
+2. **Health response.** A documented healthcheck endpoint (project-specific; common shapes: `GET /health`, `GET /api/health`, `GET /version`) returns HTTP 200 within a reasonable timeout (default 5 minutes from merge).
+3. **Build artifact integrity** (when verifiable). If the deploy emits a build hash, log digest, or version string, it matches what was built on the merge commit. If it does not emit one, this component is recorded as `not verifiable for this provider` — it does not block the receipt, but the gap is logged.
+
+A receipt missing any required component is NOT a receipt. The merge is reported as `merged but not deployed — operator action required` per the close-the-loop rule below.
+
+## How to Verify (per provider)
+
+The skill is provider-aware but never hardcodes a specific API key or token shape. Three verification routes, in priority order:
+
+### Route A — Provider CLI (preferred when authenticated)
+
+The CLI is the highest-fidelity source.
+
+| Provider | Command shape | Receipt extraction |
+|---|---|---|
+| Railway | `railway status --json` | `.deployments[0].meta.commitHash` |
+| Cloudflare Workers | `wrangler deployments list --json` | `[0].metadata.deployment_trigger.metadata.commit_hash` |
+| Vercel | `vercel inspect <url> --json` | `.gitSource.sha` |
+| Netlify | `netlify api listSiteDeploys --data='{"site_id":"<id>"}'` | `[0].commit_ref` |
+| Fly.io | `fly releases --json` | `[0].commit_sha` |
+
+If the CLI is not installed or not authenticated in this session, fall through to Route B. Do NOT prompt the operator to install the CLI mid-session — that is a drive-by.
+
+### Route B — GitHub Deployments API (works for any provider that posts back)
+
+```
+gh api repos/{owner}/{repo}/deployments --jq '.[0] | {sha, ref, environment}'
+gh api repos/{owner}/{repo}/deployments/{id}/statuses --jq '.[0] | {state, target_url}'
+```
+
+A `state: success` status whose parent deployment's `sha` matches the merge SHA is a valid receipt component (1).
+
+### Route C — Version endpoint curl (works for any HTTP service)
+
+The most provider-agnostic. Requires the application to expose a version endpoint that returns its build SHA.
+
+```
+curl -fsS https://<deployed-host>/version
+# Expect a JSON body or plain text containing the merge SHA, e.g. {"commit":"a477ec1"}
+# Or a Git-style SHA prefix that matches `git rev-parse --short HEAD`
+```
+
+If no version endpoint exists in the project, log this as a gap and recommend adding one as a deferred follow-up — do not fabricate a receipt from a 200 on `/` or `/health` alone, because both can succeed against the OLD deploy.
+
+## Output Shape (always emit this verbatim block)
+
+After running verification:
+
+```
+## Deploy Receipt — <project name>
+- Merge SHA:        <abbreviated sha>
+- Deployed SHA:     <abbreviated sha or "not retrieved (reason)">
+- SHA match:        yes | no | not verifiable
+- Health endpoint:  <url> → <status code> in <ms>ms
+- Build artifact:   <digest if available, else "not emitted by provider">
+- Receipt status:   COMPLETE | INCOMPLETE — <reason>
+- Verified via:     CLI | GitHub Deployments | version curl | combination
+```
+
+A `COMPLETE` receipt is the only state that lets the merge be reported as `done`. `INCOMPLETE` receipts surface a single named operator-action item (e.g. "Railway last deploy is older than the merge — re-trigger from dashboard or `railway up`").
+
+## On-Incomplete Modes
+
+The default behavior on `INCOMPLETE` is **report-only** — the receipt block names the gap, the operator decides recovery. A second mode is available for projects that want the skill to also stage a recovery branch and a failing repro test, without ever executing rollback or merge.
+
+### Mode A — `report-only` (default)
+
+The current behavior. Print the receipt block, surface the named operator-action item, hand off. No branch creation, no PR opened. Use this mode when the operator is at the keyboard and will react to the receipt directly. No flag required.
+
+### Mode B — `open-hotfix-pr` (opt-in)
+
+Use this mode when the receipt is `INCOMPLETE` AND a documented recovery window has elapsed without the deploy self-correcting (default 10 minutes from merge; tunable per project via `verify-ladder.json` `deploy_receipt_recovery_window_seconds`). The skill then stages a recovery branch *for the operator to review*, but never merges or rolls back on its own.
+
+Activate with the explicit invocation:
+
+```
+deploy-receipt --on-incomplete=open-hotfix-pr
+```
+
+When triggered, this mode performs four steps in order, halting on the first failure:
+
+1. **Branch.** `git checkout -b hotfix/<merge-sha-short>-<symptom-slug> origin/<deploy-branch>`. The symptom slug is derived from the named gap on the receipt — `sha-mismatch`, `health-non-200`, `version-endpoint-stale`, or `no-provider-source`. If the slug cannot be derived, halt and revert to report-only.
+2. **Failing repro test.** Write a single test file at `tests/regressions/deploy-<merge-sha-short>.test.<ext>` that asserts the gap (e.g. `expect(deployedSha).toEqual(mergeSha)` or `expect(healthResponse.status).toBe(200)`). The test MUST currently fail when run against production. The skill writes the assertion against the receipt's recorded values, not against speculation. If the test cannot be made to fail deterministically, halt and revert to report-only.
+3. **Open PR.** `gh pr create --base <deploy-branch> --head hotfix/... --draft` with body that cites the receipt block verbatim, the merge SHA, the deployed SHA, the named gap, and the documented rollback command for the detected provider (a one-line shell snippet from the table below). Draft state is mandatory — never open as ready-for-review without operator approval.
+4. **Hand off.** Print a single-line operator-action item naming the new branch, the PR URL, and the documented rollback command. Stop. Do not modify production. Do not merge the PR. Do not run the rollback.
+
+### Documented rollback commands (cited in the PR body, never executed)
+
+| Provider | Documented rollback command |
+|---|---|
+| Railway | `railway redeploy --service <service-id> --commit <previous-good-sha>` |
+| Cloudflare Workers | `wrangler rollback --message "deploy-receipt: <merge-sha-short> failed health/SHA gate"` |
+| Vercel | `vercel rollback <previous-good-deployment-url>` |
+| Netlify | `netlify rollback` (interactive — operator picks the prior deploy) |
+| Fly.io | `fly releases rollback <previous-good-version>` |
+
+The rollback command is **printed**, not run. The skill's job is to give the operator a complete recovery packet (branch + failing test + cited command) without taking the irreversible step itself.
+
+### When NOT to use Mode B
+
+- The deploy is mid-rolling-restart or mid-canary — the receipt is INCOMPLETE because the deploy is still in progress, not because it failed. Wait for the recovery window first.
+- Branch protection on the deploy branch denies hotfix branches by name pattern — the PR will fail to open and the skill should fall back to report-only with a named operator action ("hotfix branch denied by protection — recovery requires direct console access").
+- The previous-good SHA cannot be determined from `git log origin/<deploy-branch>` alone — the rollback command in the PR body would be a guess. Fall back to report-only and name the gap as "previous-good SHA unverifiable — operator must select".
+- The operator has already started a manual recovery (a fresh deploy is running, the dashboard shows a rollback in progress). Detect via Route A or Route B and skip Mode B for this receipt cycle.
+
+## Anti-Patterns
+
+- **"Eventually consistent" excuse.** Reporting done with `Deployed SHA: not retrieved` and a comment like "deploy will pick up shortly" is exactly the failure mode this skill prevents. There is no eventually — there is COMPLETE or INCOMPLETE.
+- **Health-only receipts.** A 200 on `/health` against a stale deploy is not a receipt. Without SHA match, the receipt is INCOMPLETE.
+- **Skipping for "small changes."** A docs-only commit still needs a receipt if the deploy branch auto-deploys — small changes have caused stale-build incidents on every provider in the table above.
+- **Recommending the CLI install mid-receipt.** If Route A is unavailable, fall through to B then C. Adding tooling is a separate decision the operator makes outside the receipt loop.
+- **Treating absence of evidence as evidence of success.** If none of the three routes produce a SHA, the receipt is `INCOMPLETE — no provider source available`, not `COMPLETE (assumed)`.
+- **Auto-merging the hotfix PR.** Mode B opens the PR as draft and stops. Auto-merge, `--admin` overrides, and `gh pr merge` calls are refused inside this skill. The hotfix is the operator's decision; the skill stages it but never lands it.
+- **Force-pushing or rewriting the hotfix branch.** Mode B branches off `origin/<deploy-branch>` once and pushes once. If the failing test needs changes, the skill writes a new commit on the branch — never `--force` and never `git rebase --interactive`.
+- **Executing the rollback command.** The rollback command is cited in the PR body for operator review. Mode B never runs `railway redeploy`, `wrangler rollback`, `vercel rollback`, etc. on its own. If the operator wants execution, they run it themselves or they wire a separate runner; that is a different skill.
+
+## Pairs With
+
+- `finishing-a-development-branch` (vendored, third-party/superpowers/) — runs first; reports the merge. This skill runs after.
+- `verification-loop` — same Law 4 family; this skill is the deploy-seam specialization
+- `proceed-with-the-recommendation` — routing-table row for "Merge / close branch" should pair `finishing-a-development-branch` with this skill when the project is auto-deploy
+- `safety-guard` — orthogonal; safety-guard prevents destructive ops, this verifies post-deploy state
+
+## Close-the-Loop Rule
+
+If the receipt is INCOMPLETE, the merge is NOT reported as a closed item in the Phase 7 summary of `proceed-with-the-recommendation`. It moves to **What is next → Immediate operator action**, with the named action and the exact command or dashboard step. The operator's session record is what determines done — not the agent's optimism.
+
+## Installation
+
+```bash
+mkdir -p ~/.claude/skills/deploy-receipt
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/deploy-receipt.md \
+  -o ~/.claude/skills/deploy-receipt/SKILL.md
+```
+
+Restart the Claude Code session so the registry picks it up.