continuous-improvement 3.1.0 → 3.9.1

package/skills/workspace-surface-audit.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/skills/worktree-safety.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/templates/insights-claude-md.md

@@ -0,0 +1,91 @@
+# insights-claude-md.md — paste-in CLAUDE.md blocks
+
+The four blocks below originate from the 28-day Claude Code usage report (`usage-data/report.html`, "Suggested CLAUDE.md Additions" section). Each block targets a recurring friction class the report flagged:
+
+- **Verification Discipline** — sessions where typecheck/test was skipped or run from the wrong CWD
+- **Environment Notes** — Windows + Git Bash + PowerShell mismatches that cost retries
+- **Think Before Acting** — sessions where edits started before grounding was complete
+- **Git & Deploy Workflow** — merge declared "done" while the deploy provider was still on a stale commit
+
+The discipline behavior is already encoded as continuous-improvement skills (`gateguard`, `workspace-surface-audit`, `verification-loop`, `deploy-receipt`). These blocks are the *project-local* CLAUDE.md text — the per-repo reminder that lives where developers actually look when they read `CLAUDE.md`. Skills enforce; CLAUDE.md communicates.
+
+## How to use this file
+
+1. Open the target project's `CLAUDE.md`.
+2. Pick the blocks that apply to that project (TypeScript projects probably want all four; library-only projects can skip the deploy block).
+3. Paste them under existing sections or as new top-level sections.
+4. Adjust placeholders — the report's wording is opinionated. `pnpm` is just an example; if the project uses `npm` or `yarn` or `bun`, swap it. If the project's deploy target is not Railway or Cloudflare, swap those names. The structure stays; the specifics adapt.
+5. Optionally lock the section headings under `bin/check-docs-substrings.mjs` so a wholesale CLAUDE.md rewrite doesn't silently drop the discipline contract.
+
+The blocks are paste-in markdown — copy them verbatim into your project's CLAUDE.md.
+
+---
+
+## Block 1 — Verification Discipline
+
+Paste under a "Working norms" or "Coding standards" section. Adjust `pnpm` → your package manager.
+
+```markdown
+## Verification Discipline
+- Always run `pnpm typecheck` and `pnpm test` after code changes before declaring done
+- Run verification commands from the repo root; verify CWD with `pwd` if a previous command may have changed it
+- Never claim 'verified' or 'done' without showing the passing output
+```
+
+Why this block: the report flagged sessions where Claude either skipped typecheck/test until the operator prompted, or ran `tsc` from `frontend/` and incorrectly concluded deps weren't installed. The CWD line addresses the second failure mode directly.
+
+## Block 2 — Environment Notes
+
+Paste under a "Local development" or "Environment" section. Adjust the shell + tool list to match the project's actual setup.
+
+```markdown
+## Environment Notes
+- Shell is Git Bash on Windows; do NOT use `jq` (not installed) — use PowerShell or node/python for JSON parsing
+- Be careful with bash quoting in curl/psql commands; prefer heredocs or files over inline single-quoted JSON
+- CLAUDE.md is case-sensitive on some filesystems — always use uppercase
+```
+
+Why this block: the report flagged repeated jq-not-installed retries, shell-quoting failures on curl/psql, and a Windows case-sensitivity issue with `CLAUDE.md` vs `claude.md`. If your environment is different (macOS + zsh, Linux + bash, WSL2), rewrite this block to name *your* environment's grain — the goal is to surface the per-project gotchas before the agent re-discovers them at a cost of one wasted retry each.
+
+## Block 3 — Think Before Acting
+
+Paste near the top of CLAUDE.md, ideally above any task-specific instructions.
+
+```markdown
+## Think Before Acting
+- For any non-trivial request, produce a short plan before editing files
+- When the user references prior work (e.g. 'the Finnhub stuff'), verify it exists in the repo before acting on the assumption
+- Use TDD for new features: write failing test, then code, then verify
+```
+
+Why this block: the operator literally had to type "you need to think before u response" mid-session, and a separate session was wasted verifying nonexistent "Finnhub work" that was only used as a framework analogy. The first bullet generalizes the "plan first" rule from the global CLAUDE.md; the second is project-local — if your project has its own analogy-vs-real-code traps, name them here.
+
+## Block 4 — Git & Deploy Workflow
+
+Paste under a "Git workflow" or "Release process" section. Adjust the deploy provider names to match your project.
+
+```markdown
+## Git & Deploy Workflow
+- Never push directly to main — use PR workflow; harness will block direct pushes
+- After merging, verify Railway/Cloudflare actually picked up the commit before declaring deploy complete
+- For production POSTs and wrangler tail, expect harness blocks and surface them as caveats requiring user action
+```
+
+Why this block: multiple sessions hit "Railway deploy didn't pick up the latest commit" or "harness blocked merge-to-main / production POST / wrangler" — pre-emptive awareness saves retry cycles. The second bullet is what `deploy-receipt` enforces in-tooling; this CLAUDE.md text makes the same expectation visible to humans reviewing PRs.
+
+If your project deploys somewhere other than Railway or Cloudflare, swap those names. If your project does NOT auto-deploy from main (library-only / package-published), drop the second bullet entirely — receipt verification doesn't apply.
+
+---
+
+## Companion skills (already installed if you have continuous-improvement)
+
+Each block has a corresponding skill that enforces the rule when an agent is in the loop. Pasting the block tells humans the rule; installing the skill makes the agent obey it.
+
+| Block | Companion skill |
+|---|---|
+| Verification Discipline | `verification-loop` (per-project ladder via `.claude/verify-ladder.json`) |
+| Environment Notes | `workspace-surface-audit` (records environment grain at session start) |
+| Think Before Acting | `gateguard` (blocks Edit/Write/Bash before grounding) |
+| Git & Deploy Workflow | `deploy-receipt` (verifies deployed SHA + healthcheck before declaring done) |
+
+If you want both layers (CLAUDE.md text + skill enforcement), paste the block AND keep the skill installed. If you only want one, the skill is the higher-fidelity surface — it runs at the tool boundary and cannot be skipped by an agent that didn't read the markdown.

package/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/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/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/templates/verify-ladder.example.json

@@ -0,0 +1,60 @@
+{
+  "_doc": [
+    "Per-project verification ladder for the verification-loop skill.",
+    "Copy this file to .claude/verify-ladder.json at your repo root and trim per project.",
+    "Phase 0 of verification-loop reads this manifest first, then sniffs package.json scripts,",
+    "then per-language toolchain files (Cargo.toml, go.mod, pyproject.toml, etc.), then asks.",
+    "Set any field to the literal null to skip that phase for this project.",
+    "",
+    "Three starter shapes are provided below — pick one, delete the others, then trim."
+  ],
+
+  "_synthetic_checks_doc": [
+    "synthetic_checks names a directory (relative to the repo root) containing",
+    "*.synthetic.{sh,mjs,ts,py} files. Each file is invoked once after deploy-receipt",
+    "reports COMPLETE, with BASE_URL + BASELINE_URL + EXPECTED_SHA env vars set.",
+    "Exit 0 = production matches baseline; non-zero = drift, stdout is the diff.",
+    "Set to null to skip; set to a different path (e.g. 'infra/synthetic/') to relocate.",
+    "See synthetic-checks/README.md for the full contract."
+  ],
+
+  "_typescript_node_example": {
+    "build":            "npm run build",
+    "typecheck":        "npx tsc --noEmit",
+    "lint":             "npm run lint",
+    "test":             "npm test",
+    "security":         "npm audit --audit-level=high",
+    "deploy_receipt":   null,
+    "synthetic_checks": null
+  },
+
+  "_rust_cargo_example": {
+    "build":            "cargo build --release",
+    "typecheck":        "cargo check --all-targets",
+    "lint":             "cargo clippy --all-targets -- -D warnings",
+    "test":             "cargo test --all-features",
+    "security":         "cargo audit",
+    "deploy_receipt":   null,
+    "synthetic_checks": null
+  },
+
+  "_python_uv_example": {
+    "build":            null,
+    "typecheck":        "uv run pyright",
+    "lint":             "uv run ruff check .",
+    "test":             "uv run pytest",
+    "security":         "uv run pip-audit",
+    "deploy_receipt":   null,
+    "synthetic_checks": null
+  },
+
+  "_cloudflare_worker_example": {
+    "build":            "npm run build",
+    "typecheck":        "npx tsc --noEmit",
+    "lint":             "npm run lint",
+    "test":             "npm test",
+    "security":         "npm audit --audit-level=high",
+    "deploy_receipt":   "npx wrangler deployments list --json",
+    "synthetic_checks": "synthetic-checks/"
+  }
+}