continuous-improvement 3.20.4 → 3.22.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/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.20.4",
+  "version": "3.22.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/skills/proceed-with-the-recommendation.md

@@ -213,6 +213,7 @@ Rows whose **Preferred skill** is not bundled with the `continuous-improvement`
 | Fix bug / investigate failure | `superpowers:systematic-debugging` | Hypothesis → add logs/tests → reproduce → smallest fix → verify with the failing repro. (Reference behavior — does not require `superpowers:systematic-debugging`.) |
 | Write tests / add coverage | `superpowers:test-driven-development` or `tdd-workflow` | RED (failing test) → GREEN (minimal code) → REFACTOR; one test, one behavior |
 | Refactor / dead code cleanup | `simplify` | Find dupes/unused exports, delete in place, re-run type check and smallest test. (Reference behavior — does not require `simplify`.) |
+| Over-engineering check on a diff | `simplicity-review` (bundled) | Walk the reuse ladder (existing file, stdlib, native feature, one line) over the current diff and report GO/TRIM without editing; apply trims, then re-run the smallest check. Never flags input validation, data-loss handling, security, or accessibility. |
 | Security review / auth audit | `security-review` | Scan for hardcoded secrets, unsanitized input, missing authz, SQL string concat, open CORS. (Reference behavior — does not require `security-review`.) |
 | Code review before merge | `superpowers:requesting-code-review` or `code-review` | Read diff top-to-bottom, flag CRITICAL / HIGH / MEDIUM. (Reference behavior — does not require `code-review`.) |
 | Verify before shipping | `superpowers:verification-before-completion` | Smallest check that proves correctness: typecheck + one test + one curl. (Reference behavior — does not require `superpowers:verification-before-completion`.) |

package/skills/reconcile.md

@@ -20,27 +20,65 @@ Law 1 says research before executing. The most expensive skipped research is the
 
 ## Establish Ground Truth First
 
-Read before you write. Capture the full state in one pass:
+Read before you write. One command runs the whole pass and prints the resolved-state block:
 
 ```
-git branch --show-current
-git status --porcelain=v1
-git rev-list --left-right --count '@{u}...HEAD'     # behind / ahead of upstream (quote the ref — bare @{u} trips the Bash parser)
+npx ci-reconcile              # resolved-state block; exit 1 if anything blocks a mutation
+npx ci-reconcile --json       # the same state, machine-readable
+npx ci-reconcile --explain    # print the probe set and why each probe runs
+```
+
+Exit codes: `0` nothing blocks, `1` at least one blocker, `2` not a git repository. The probe set is defined once in `src/lib/git-state.mts`, and `npm run verify:reconcile-parity` fails if this document drifts from it — the list below is the list the runner executes.
+
+Run the pass by hand when the runner is not installed:
+
+```
+git rev-parse --show-toplevel                          # inside a work tree, and where
+git rev-parse HEAD                                     # the sha every later claim is relative to
+git symbolic-ref --quiet --short HEAD                  # branch name; NON-ZERO EXIT = detached HEAD
+git rev-parse --abbrev-ref --symbolic-full-name @{u}   # upstream, or non-zero = none configured
+git rev-list --left-right --count @{u}...HEAD          # behind/ahead — only after the line above succeeded
+git status --porcelain=v1                              # reported changes (inflated by autocrlf)
+git diff --name-only --ignore-all-space                # real content drift — the number to trust
 git stash list
-git worktree list
-ls .git/MERGE_HEAD .git/rebase-merge .git/rebase-apply 2>/dev/null   # in-progress operation?
+git worktree list --porcelain
+git rev-parse --git-path MERGE_HEAD                    # in-progress op: test the RESOLVED path for existence
 ```
 
-On Windows with `autocrlf=true`, `git status` reports phantom line-ending-only modifications. Trust `git diff --stat` (and `git diff --ignore-all-space`) for real content drift, not `git status`. Never stage with `git add -A` / `git add .` on such a tree — stage by explicit filename.
+Four boundaries make the obvious commands lie. Each was reproduced against real git; do not simplify them back.
+
+- **No configured upstream.** Asking `git rev-list` for counts against `@{u}` exits **128** with `fatal: no upstream configured` — it does not return zeros. Probe for the upstream first and ask for counts only once it resolved. With no upstream, compare against `origin/<default>` explicitly; never read the failure as "even".
+- **Detached HEAD.** The `--show-current` form of `git branch` prints an empty string and exits **0**, so a detached HEAD is indistinguishable from a successful read. `git symbolic-ref --quiet --short HEAD` exits non-zero instead, which is checkable. A detached HEAD blocks: there is no branch to commit onto, push, or name in a PR.
+- **Linked worktrees.** Inside a worktree `.git` is a *file*, not a directory, so listing a `.git/`-relative path for `MERGE_HEAD` fails with "Not a directory" and exit **2** — byte-identical to the "no operation in progress" result on a clean tree. A real conflicted merge therefore reads as clean. Resolve the marker with `git rev-parse --git-path MERGE_HEAD` and test *that* path; it is correct in a main checkout and in a worktree alike. Same for `rebase-merge`, `rebase-apply`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `BISECT_LOG`.
+- **Windows `autocrlf=true`.** `git status` reports phantom line-ending-only modifications. Trust `git diff --stat` / `git diff --name-only --ignore-all-space` for real content drift. Never stage with `git add -A` / `git add .` on such a tree — stage by explicit filename. The runner prints both numbers so the gap is visible instead of assumed.
+
+## Compatibility
+
+The ground-truth pass has to work wherever the agent runs, not only in Bash. `ci-reconcile` spawns `git` argv directly with no shell, so it needs no `bash`, no coreutils, and no `.git/`-relative path.
+
+| Surface | PowerShell / cmd | Git Bash / WSL | POSIX shell | Linked worktree | Detached HEAD | No upstream |
+|---|---|---|---|---|---|---|
+| `ci-reconcile` (Node) | yes | yes | yes | correct | blocks | warns |
+| `scripts/git-state-snapshot.sh` | needs Git Bash | yes | yes | root/branch only | reports `detached` | reports `none` |
+| Hand-run probe list above | yes | yes | yes | correct | non-zero exit | non-zero exit |
+
+Smoke-test on the OS you actually ship on. Both surfaces emit the same `{head, upstream, dirty, root, branch}` envelope — `ci-reconcile --snapshot` adds `contentDrift` and `inProgress` — and a test pins that parity so the two cannot drift apart silently.
 
 ## Detect a Concurrent Writer
 
 When another session/loop may be active, do not assume the tree is yours:
 
-- An in-progress `MERGE_HEAD` / `rebase-merge` you did not start means another actor is mid-operation. Do not "help" by editing conflicted files — wait, or hand off.
-- Re-read the current branch immediately before any mutation; if it shifted since your snapshot, re-survey from the top.
-- If `.git/index` keeps changing while you are idle, a writer is active. Pause and surface it rather than racing.
-- If `gateguard` is installed, its Parallel-Actor Gate already captured this baseline on the session's first mutation by running `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`) and divergence-checks every later mutation — `reconcile` complements that gate, it does not replace it. Without gateguard, run the snapshot above yourself.
+- An in-progress `MERGE_HEAD` / `rebase-merge` you did not start means another actor is mid-operation. Do not "help" by editing conflicted files — wait, or hand off. The runner reports this as a blocker; the retired `.git/`-relative probe could not see it inside a worktree at all.
+- **Re-read HEAD and the branch immediately before every mutation, not once per session.** Capture a baseline, then compare right before you commit, push, or rebase:
+  ```
+  npx ci-reconcile --snapshot > .git/reconcile-baseline.json   # or any scratch path
+  # ... do work ...
+  npx ci-reconcile --snapshot                                   # compare head + branch against the baseline
+  ```
+  If either field moved, another writer got there first — re-survey from the top instead of committing onto an unexpected base. A missing or unparseable field counts as *shifted*; "we could not tell" is never "nothing moved".
+- More than one entry in `git worktree list --porcelain` means a sibling checkout exists that another session may be writing to. The runner flags this.
+- If the git index keeps changing while you are idle, a writer is active. Pause and surface it rather than racing.
+- If `gateguard` is installed, its Parallel-Actor Gate already captured this baseline on the session's first mutation by running `bash "${CLAUDE_PLUGIN_ROOT}/scripts/git-state-snapshot.sh"` (source: `scripts/git-state-snapshot.sh`) and divergence-checks every later mutation — `reconcile` complements that gate, it does not replace it. That shell snapshot needs Git Bash and derives its `dirty` count from `git status`, which overstates drift on an `autocrlf` tree; `ci-reconcile --snapshot` is the same envelope without either limitation. Without gateguard, run one of them yourself.
 
 ## Classify, Then Act
 
@@ -99,12 +137,24 @@ Once ground truth is known and the halt gates are clear, carry the work to an op
 
 A push that printed no error is still a claim. Confirm:
 
+```
+npx ci-reconcile --verify-push <branch>      # exit 0 only when the remote tip equals local HEAD
+```
+
+or by hand:
+
 ```
 git rev-parse HEAD
 git ls-remote origin refs/heads/<branch>     # remote tip must equal local HEAD
 ```
 
-If the remote ref is absent or behind, the push did not land — investigate before reporting success.
+There are **three** outcomes here, not two, and collapsing them is how a false report gets made:
+
+- **landed** — the probe succeeded and the remote tip equals local HEAD.
+- **not-landed** — the probe succeeded and the ref is absent, or points at a different sha. The push really did not land.
+- **unverified** — `git ls-remote` itself failed (network, auth, remote down). This is *not* evidence the push failed; it is evidence you do not know. Retry the probe. Never report success, and never report failure, from a probe that did not run.
+
+Report only what the probe proved.
 
 ## Sync the Default Branch After the PR Merges
 

package/skills/simplicity-review.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.