@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/skills/selfimprove/README.md

@@ -0,0 +1,34 @@
+# selfimprove
+
+This is a portable Agent Skill (agentskills.io format) that runs the review tool's whole-repo scan in a loop: scan, fix, review, re-scan, for N fix rounds. N defaults to 2. You need `qcr` on PATH, because the skill drives `qcr scan … --json`.
+
+## Install
+
+The skill is the whole `skills/selfimprove/` directory. Copy or symlink it into the location your CLI reads:
+
+| CLI | Skill location | Invoke |
+|---|---|---|
+| Claude Code | `.claude/skills/selfimprove/` or `~/.claude/skills/` | `/selfimprove 3` |
+| Codex | `.agents/skills/selfimprove/` or `~/.agents/skills/` | `$selfimprove 3` |
+| opencode | `.agents/skills/` or `.claude/skills/` (also `.opencode/skills/`) | copy `commands/selfimprove.md` to `.opencode/commands/` for `/selfimprove 3`; otherwise ask for the selfimprove skill by name |
+| pi | `.agents/skills/` or `~/.agents/skills/` | `/skill:selfimprove 3`, or copy `commands/selfimprove.md` to `~/.pi/agent/prompts/` for `/selfimprove 3` |
+
+`commands/selfimprove.md` is a thin prompt wrapper for clients that want a separate command file. It uses `$ARGUMENTS`, which every one of these clients supports.
+
+## Subagents
+
+The skill delegates fixers and reviewers when the client can (Claude Code, Codex, opencode, or pi with a subagent extension). Otherwise it works serially, and the review is a separate fresh pass over the diff.
+
+## Explicit invocation only
+
+The skill spends money on scans, so it is meant to run only when you ask for it:
+
+- **Claude Code and pi:** `disable-model-invocation: true` in the frontmatter stops them starting it on their own.
+- **Codex:** `agents/openai.yaml` turns implicit invocation off.
+- **Other clients:** they ignore both settings, and the skill body tells the agent to run only when invoked by name.
+
+`disable-model-invocation` is a client extension, so a strict Agent Skills validator will flag it.
+
+## Before you start
+
+`qcr scan` must read this repository, through `[companion] reviewed_repo_dir` or `QCR_REVIEWED_REPO`. Its case runner also needs `pi` on PATH and logged in.

package/skills/selfimprove/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: selfimprove
+description: Scan the whole repo with the review tool, fix the findings, re-scan and repeat for a set number of fix rounds (default 2). Run as /selfimprove [rounds].
+license: MIT
+compatibility: Any coding CLI that reads SKILL.md (Claude Code, Codex, opencode, pi). Needs git, a shell, and the `qcr scan` command (or a wrapper set as `scan_cmd`).
+disable-model-invocation: true
+metadata:
+  argument-hint: "[rounds=2]"
+---
+
+# Self-improve
+
+This skill runs a loop. Scan the repo, sort the findings, fix them, then re-scan the files the fixes changed. Repeat for **N fix rounds**. N is the number the user gave with the command (Claude Code substitutes it here: `$ARGUMENTS`; elsewhere read it from the user's message). If it is missing or not a positive integer, N is `2`. The loop does: scan → fix → re-scan, until round N's fixes have been re-scanned.
+
+The scan tells you what is wrong, and the re-scan tells you whether a fix worked. Your own sense that something is fixed does not count.
+
+Run this skill only when the user invoked it by name. It spends money; never start it because a request merely sounds related.
+
+Two terms are used throughout:
+
+- **Settings**: `.selfimprove/settings.json` at the repo root, gitignored.
+- **Ledger**: the directory chosen at setup.
+- **`<scan>`**: the settings' `scan_cmd`, by default `qcr scan`. Every `qcr scan …` below means `<scan> …`.
+
+## 1. Setup
+
+If the settings file exists, read it. Show the user a one-screen summary and go on. Don't ask the questions again. They can say "redo setup" to change anything.
+
+If there is no settings file, ask the questions in [references/setup.md](references/setup.md). Use the client's structured question tool when it has one, otherwise numbered options in chat. Ask every question even when one seems to have an obvious answer. Write the answers to the settings file, add `.selfimprove/` to `.gitignore`, and create the ledger from [references/ledger.md](references/ledger.md).
+
+Then check the environment:
+
+- `<scan> doctor --json` reports `"ok": true`. It checks that the scan can run where it is configured to (docker, the image, the scan's pi login), that a reviewed repo is set, and that a unit cut is saved. For each failed check, show the user its `detail` and `fix`. If the only failure is `unit_cut`, offer to set one up: run `<scan> units propose`, then show the user `<scan> units show`, adjust it with `<scan> units adjust --file <ops.json>` as they ask, and run `<scan> units save` only after their ok. Then run doctor again. Stop on any other failure.
+- The doctor's `reviewed_repo` is this same checkout (a worktree of it counts), not a separate clone, so commits made here resolve for `--sha`.
+- The working tree is clean.
+- The baseline build and test commands pass. Record failures that already exist so they aren't blamed on fixes.
+
+**Done when:** the settings file exists and the user has seen it, the ledger directory exists, and the baseline is recorded in `LEDGER.md`.
+
+## 2. Price and approve
+
+Run `qcr scan preview --json`. On rounds after the first, add `--delta --sha <round integration commit>` (see step 6). On a repo that has never been priced, the preview offers a calibration run instead, capped by the tool's `calibration_max_usd`. Show the user that cap and run it only after their yes, then preview again.
+
+On the first round, show the user three things: the price of this scan, an estimate for all N rounds, and the budget set at setup. Get one explicit yes. That yes covers the later rounds as long as each one's preview costs less than the first round's and the running total stays inside the budget. If a later preview is more expensive, or would go over the budget, stop and ask again.
+
+**Done when:** you have the preview's `start` arguments (`null` means something blocks the start; report the errors), and the user's approval covers them. Record the price in the ledger.
+
+## 3. Scan
+
+Run `qcr scan start <the preview's start arguments> --json`, then `qcr scan status --wait --json`. Exit 0 means the run completed, 1 means it ended incomplete or was refused, and 3 means the wait timed out (wait again).
+
+If settings say `depth: deep` and this is round 1, run `qcr scan stage2 propose --deep --json` next. Approve its price the same way as step 2, then run `qcr scan stage2 start --key <the proposal's key> --json` and `qcr scan status --wait --json`. A delta re-scan never runs a deep pass.
+
+If the scan hits its hard stop before covering the plan, report how much coverage it got. Don't restart it at a higher price without asking.
+
+After a delta re-scan, answer any pending match question (`qcr scan matches --json`, then `qcr scan match --key <K> OLD=NEW…`; passing no pairs means none of them match). Pair an old finding with a new one only when they describe the same defect at the same code.
+
+**Done when:** the run's status is finished or hard-stopped, there are no unanswered match questions, and the ledger has the run's cost, coverage, and counts of new, fixed and still-open findings.
+
+## 4. Triage
+
+Pull the open findings with `qcr scan findings --state new --json` and keep the ones inside the settings' `scope`. Give every finding exactly one verdict:
+
+- `real`
+- `not-real`
+- `by-design`
+- `duplicate`
+- `needs-owner`
+- `out-of-scope`
+
+Settings `no_touch` globs mark paths that are off limits. Any finding inside them gets `out-of-scope`. `needs-owner` means the right answer is a policy decision or a trade-off. Those findings are written to `NEEDS-OWNER.md` and never fixed.
+
+Write `not-real`, `by-design` and `duplicate` verdicts back to the store with `qcr scan dismiss <fingerprint> --reason "<verdict>: <why>"` (reason at most 500 characters). Dismissals are sticky, and they also teach PR reviews to stay quiet about the finding. So never dismiss `needs-owner` or `out-of-scope` findings, because they are real. Keep those in the ledger only.
+
+Group the `real` findings into **packets**. A packet is the files one fixer can own without overlapping another packet. Put findings that touch the same helper in the same packet, because separate branches editing the same helper produce silent duplicates.
+
+**Done when:** every finding in scope has a verdict in `dispositions/r<round>.md`, and every `real` finding belongs to exactly one packet.
+
+## 5. Fix and review
+
+For each packet, follow [references/fix-loop.md](references/fix-loop.md). The short version:
+
+- Each packet gets its own branch, and its own worktree when parallel is on.
+- Write the test first, as the settings' `tdd` says.
+- The fix is done when the build and tests pass.
+- Then a reviewer who did not write the fix approves it, as the settings' `review` says.
+- The result lands as the settings' `land` says.
+
+When the client can delegate, hand each packet to a fixer subagent and each review to a separate reviewer subagent. Run up to `parallel` at once. When it cannot delegate, work through the packets one at a time and do the review as a separate pass: start from a fresh read of the diff, not from what you remember writing.
+
+After every packet lands, update `LEDGER.md` and `fixes-explained.md`.
+
+Then build the **round integration commit**: branch `selfimprove/r<round>-integration` from the previous round's integration commit (round 1: the starting HEAD) and merge every approved packet into it, running `build` and `test` after each merge. With `land: merge` the target branch already is this commit. The re-scan reads that commit, and the next round's packets branch from it, so each round builds on the fixes before it even when nothing lands on the user's branch.
+
+**Done when:** every packet is landed, or parked with a reason in the ledger, and no fixer or reviewer is still running.
+
+## 6. Next round or stop
+
+Stop the loop when any of these is true:
+
+- N fix rounds are done.
+- The delta re-scan finds no new finding in scope.
+- Everything that is left is `needs-owner`.
+- The next round's price would go over the budget.
+
+If none is true, go back to step 2 for round + 1. The re-scan is `--delta --sha <round integration commit>`, so it covers only the files this round's fixes changed, as they stand with the fixes in. Re-scan after the last fix round as well, so that round's fixes are checked.
+
+**Done when:** the ledger records why the loop stopped. Then give the user the final report:
+
+- rounds run
+- money spent
+- findings per round (new, fixed, still open)
+- what landed and where (branches, PRs or merges)
+- regressions the reviewers caught
+- the `NEEDS-OWNER.md` list
+
+## Guardrails
+
+- Worktrees and branches the loop creates for itself are fine. Stop and ask the user before anything that reaches outside the repo:
+  - pushing
+  - force-pushing
+  - opening PRs (unless `land` says PRs)
+  - deploying
+  - copying credentials
+- Commits carry plain messages and the user's git identity. Add co-author trailers only if settings say to.
+- Wait for the user's go before any scan they haven't approved, including after the loop has stopped.
+- If the user says pause, wrap up or stop, finish only the in-flight packets. Land them the normal way, which includes review unless the user waives it. Then stop every subagent and write the ledger's "Where it stopped" section.

package/skills/selfimprove/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/selfimprove/commands/selfimprove.md

@@ -0,0 +1,6 @@
+---
+description: Scan, fix, re-scan loop over the whole repo (arg = fix rounds, default 2)
+argument-hint: "[rounds]"
+---
+
+Use the `selfimprove` skill. Fix rounds: $ARGUMENTS

package/skills/selfimprove/references/fix-loop.md

@@ -0,0 +1,49 @@
+# Fix loop: one packet
+
+## Fixer
+
+Give the fixer these four things:
+
+- the packet, meaning its findings with fingerprint, file, range and the scan's reasoning
+- the settings
+- this brief
+- a worktree, made by `git worktree add ../<repo>-si-r<round>-<packet> -b selfimprove/r<round>-<packet> <base>`. `<base>` is the previous round's integration commit, or the starting HEAD in round 1. Link or install dependencies in it.
+
+Line numbers in a finding can be stale, so locate the code by its content.
+
+1. Read the flagged code and what calls it. Confirm the verdict, and downgrade it if the code proves the finding wrong. Downgrades go back in the disposition with a reason.
+2. If `tdd` is `required` and this is a behaviour fix, write a test that fails on the current code and commit it, or note the commit. A comment-only or pure-refactor change doesn't need a new test. For those, the existing tests must stay green.
+3. Make the smallest fix that removes the defect. Write comments that state what the code does, not why it changed. The why belongs in the commit message.
+4. Run `build` and `test`. When `test_file` is set, rerun any failing file on its own before calling the failure real.
+5. Commit with a plain message that names the finding fingerprint(s).
+
+If a fix would change behaviour the repo's docs describe as intended, stop and mark it `needs-owner`. Do the same if it would trade one quality for another, such as precision for recall or speed for safety. Don't fix it.
+
+**Done when:** each finding in the packet is fixed with its test, downgraded with a reason, or moved to `needs-owner`, and the branch builds and tests green.
+
+## Reviewer
+
+When `review` is `independent`, use a different agent from the fixer, or a fresh pass when you can't delegate. Its input is the diff, the packet, and the finding text. It does not get the fixer's notes.
+
+Review adversarially:
+
+- Does the fix remove the defect?
+- Does the new test fail without the fix?
+- What did the fix break? Check its callers, error paths, config, and paths the tests don't reach.
+- Does it duplicate a helper another packet also touched?
+
+End the review with `VERDICT: approve` or `VERDICT: changes-needed`, followed by numbered items.
+
+If the verdict is changes-needed, send the items back to the fixer. Repeat until the reviewer approves. If a packet fails review three times, park it in the ledger and move on.
+
+The fixer must stop committing once review has started. If it commits after that, the review covers a commit that is no longer the branch tip, so review the new tip again.
+
+**Done when:** the review file `dispositions/r<round>-<packet>.review.md` ends with `VERDICT: approve`.
+
+## Landing
+
+- `branch`: leave the branch as it is and list it in the ledger.
+- `pr`: push the branch and open a PR. The setup answer authorised this. From round 2 on, packets are based on the previous round's integration commit, so their PRs also carry the earlier rounds' commits. Open them as stacked on that round's PRs, or say so in the description.
+- `merge`: merge into an integration worktree, run `build` and `test` there, and fast-forward the target branch only when everything is green. Land packets one at a time, and rerun the tests after each one, so a conflict between two packets shows up against the one that caused it.
+
+Afterwards, remove the packet worktree, from the main checkout rather than from inside the worktree.

package/skills/selfimprove/references/ledger.md

@@ -0,0 +1,20 @@
+# Ledger
+
+The ledger is the one place the user reads to see where the loop stands, so update it after every scan, verdict, review and landing. It lives in `ledger_dir` and holds these files:
+
+- `LEDGER.md` has the following sections:
+  - **Status** is a table with one row per packet per round: packet, findings, verdict counts, branch, review state, landed.
+  - **Rounds** has one line per scan: round, cost, files covered, new, fixed, still open.
+  - **Regressions caught** has one plain-language paragraph for each reviewer catch: what would have broken, and for whom.
+  - **Log** holds timestamped one-liners.
+  - **Where it stopped** is written when the loop ends or is paused: what is unfinished, and the exact next step.
+- `fixes-explained.md` has one entry per landed fix:
+  - **What was wrong**, including what it would have caused.
+  - **Fix**.
+  - **Proof**, meaning the test name and the re-scan result.
+
+  Write each entry for someone who hasn't read the code.
+- `NEEDS-OWNER.md` lists each finding left for the owner: the question, the options, and their trade-offs. Nothing listed here gets implemented.
+- `dispositions/r<N>.md` has one line per finding: fingerprint, verdict, packet, reason. Review files sit beside it.
+
+Every number in the ledger has to come from a command's output (`qcr scan status`, `findings`, the test runner). Don't estimate them.

package/skills/selfimprove/references/setup.md

@@ -0,0 +1,40 @@
+# Setup questions
+
+These questions run on the first run only, when there is no settings file yet. Ask them in this order, a few to a round. Each option should be short and say one thing. When there is a default, list it first. If the user doesn't pick, use the default and say that you did.
+
+| Key | Question | Options (first is the default) |
+|---|---|---|
+| `scope` | Which findings get fixed? | `all` (every validated finding) · `min-severity:P2` · `min-severity:P1`. Before settling this, calibrate: show 5 findings from the first scan across tiers and ask "fix these?" Adjust `scope` until the user's answers match it. |
+| `tdd` | Test first for behaviour fixes? | `required` (fails before, passes after; no test, no landing) · `preferred` (the fixer explains when it's skipped) · `off` |
+| `review` | Who approves a fix before it lands? | `independent` (a separate reviewer, or a fresh-pass self-review when no subagents) · `rescan-only` (the delta re-scan is the review) |
+| `land` | What happens to an approved fix? | `branch` (a branch per packet, left for the user) · `pr` (a PR per packet; PRs are opened only after this answer) · `merge` (fast-forward into the current branch once the integration build and tests pass) |
+| `parallel` | Max fixers at once? | `1` · `4` · `8`. Ignored when the client can't delegate. Each parallel fixer gets its own `git worktree add <path>`. |
+| `depth` | Scan depth for round 1? | `standard` · `deep` (more lenses and higher recall, at more cost) |
+| `budget_usd` | Total scan spend cap for the whole loop? | A number. Show the first preview's price next to the question so the user has something to go on. |
+| `ledger_dir` | Where does the ledger live? | `.selfimprove/ledger/` (gitignored) · a directory outside the repo · `docs/selfimprove/` (committed) |
+| `no_touch` | Paths fixers never edit? | Default: vendored code and dated records. Detect candidates first (`vendor/`, `third_party/`, `*VENDORED*`, dated `docs/` records) and let the user add globs. |
+| `git` | Commit identity and trailers? | `user-only` (no co-author trailers) · `with-trailer` |
+| `scan_cmd` | How is the scan invoked? | `qcr scan` (it runs its driver in its own sandbox container) · a wrapper path around it |
+| `build` / `test` | Commands that make a fix green? | Detect them from the package manifest, Makefile or CI config, and confirm with the user. |
+
+Write the answers to `.selfimprove/settings.json`:
+
+```json
+{
+  "scope": "all",
+  "tdd": "required",
+  "review": "independent",
+  "land": "branch",
+  "parallel": 4,
+  "depth": "standard",
+  "budget_usd": 60,
+  "ledger_dir": ".selfimprove/ledger",
+  "no_touch": ["vendor/**"],
+  "git": "user-only",
+  "scan_cmd": "qcr scan",
+  "build": "npm run build",
+  "test": "npm test"
+}
+```
+
+Before writing `test`, check whether the suite flakes when it runs under parallel load. If it does, record a per-file rerun command too, as `test_file`, for example `timeout 300 npx vitest run <file>`.