# acceptance

Adopt this skill: https://proskills.md/skills/other/smixs-code-quality-skills-acceptance

Page: https://proskills.md/skills/other/smixs-code-quality-skills-acceptance
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/acceptance/SKILL.md
size: 15848
sha: 81d69750bc37f7615567af38a8a0625c3d3bf1a4
upstream: https://github.com/smixs/code-quality/blob/main/skills/acceptance/SKILL.md

```text
---
name: acceptance
description: "Acceptance runbook for code changes in any project: pick the level by risk, write a spec with a finish line and a failure table, build in one pass, verify one frozen candidate with parallel lanes (the gate, two reviewers from different model families, a blind QA, a live check), one batched repair, two rounds, a done table built from evidence, each defect class turned into a mechanism. Use for: acceptance, accept a change, is it done, definition of done, ready to merge, verify a branch."
---

# Acceptance

## The idea

A three-star kitchen. The chef does not re-cook every plate or read the cooks' reports. The chef trusts the brigade because:

1. The recipe is fixed before service: what goes on the plate and what to do when something goes wrong.
2. The cook tastes before sending the plate to the pass.
3. No plate reaches the dining room without the pass, and the people at the pass did not cook it.
4. The chef tastes what the dish depends on.
5. A plate goes back to the station once, with every note at once. The menu does not change mid-service.
6. After service the lesson goes into the recipe and the equipment, not into shouting.

Trust comes from evidence produced by people who did not write the code, on the candidate that will land. Speed comes from parallel checks, one repair, two rounds and no paperwork for its own sake.

## What the trust rests on

- The verifier is never the author. Reviewers, QA and the live lane did not write this code. A lead does not accept their own risky change alone.
- The candidate is frozen: base SHA and head SHA are recorded before the pass and nobody touches them until the verdict.
- The gate catches test tampering: a deleted or skipped test, a weakened assertion, a mock of the module under test, a hook bypass.
- Mutants prove the tests are not idle.
- Three model families look from different sides.
- The live lane is mandatory for a user path. Without it the result is "accepted locally", not "done".
- Rejected findings reach the owner together with the fact they were rejected on.

## 0. Level

Pick the level by risk, not by line count. When unsure, go one level up. Level 3: money, auth and secrets, access to someone else's data, data and migrations, updaters, deploys, locks, queues and races, shared contracts, multi-module refactors, releases, or the owner's word.

| Level | What applies |
|---|---|
| 1 | Self-check by risk: the diff, the relevant test, typecheck and lint where present. Commit and push only if the task and the project allow it. |
| 2 | Executor with the self-check from §3, lane A. Lane B when a risk is named in the task or found while reading the code and its consumers. Lane E when a user path changes. |
| 3 | The whole runbook. |

## 1. The recipe: a spec before code

Write the spec with [references/spec-card.md](references/spec-card.md). It carries a version number and must have:

- **Finish line.** What the user or consumer will observe, as checkable lines. At the end these lines become the done table. No separate DoD file.
- **Failure table** for every new outbound call, durable write and side effect, with the failure modes that apply. In the seven-round case below, every defect sat in a failure the spec did not describe.
- **Platform facts with the strongest available proof:** `file:line` in the dependency source, an official contract with its version, or a reproducible probe. An assumption without proof does not become a decision.
- Out of scope and do-not-touch. The highest test seam. PBT for invariants. A TLA+ model by the rule in spec-card, written by the lead before code.

One reviewer pass over the spec, from another model family, asked for every finding at once (brief in spec-card). The lead applies all of it in one edit. If the edit closed a blocker or a high finding, a second pass reads only the changed paragraphs and the sections that depend on them. Then the spec version is frozen.

A late finding becomes a new spec version and goes to the executor and every lane. If it changes a mechanism, the scope or permissions, the changed sections get one reviewer pass while the executor continues with the unaffected parts.

## 2. The station: a project card

Each project has one card per [references/station-card.md](references/station-card.md): the gate command and a fallback gate, what counts as touched tests, the live check before merge and after release, machine limits, known red tests, deploy and rollback. The card lives in a project document or in `.scratch/work/station.md`; the root `AGENTS.md` or `CLAUDE.md` only links to it.

No card: the lead assembles a draft from existing commands and runs it once. Saving the card into the project needs permission to change its instructions. A card that was never run does not allow a release acceptance.

## 3. The cook: the executor in one pass

- A role from your team roster, in the environment the project uses (for example a visible terminal session). Its own worktree from the base SHA in the task: fresh origin/main by default, the exact SHA with its dependencies listed for a dependent task. The task in one message, from the ticket in [references/briefs.md](references/briefs.md).
- First the executor copies the finish line and the failure table verbatim into `TASK.md` as checkboxes. That is its "yes, chef".
- It builds everything in one pass and tastes it: touched tests, typecheck, lint, the gate on the change.
- It reports `DONE|BLOCKED: <SHA> + three lines`. Every claim carries the command, exit code, a one-line result and the path to the full log. What it did not check goes into a "not verified" list.
- It does not invent a mechanism the spec lacks: BLOCKED with a question.
- Forbidden: weakening or deleting tests to get green, `--no-verify`, leaving the scope.

## 4. The pass: one parallel check of a frozen candidate

- The lead records base SHA and head SHA. The executor does not touch the candidate until the verdict.
- Each lane works in its own worktree detached at head (`git worktree add --detach`). Mutants run only in the QA lane's throwaway worktree. Evidence goes outside the worktrees, into the task folder `.scratch/work/<task>/`.
- Before the start each lane is "required" or "n/a: reason". Lanes start in one message. Code reading runs in parallel. Heavy commands (tests, mutants, builds, browsers) queue by the card's machine limits; waiting for a resource is not a hang.
- Nothing runs hidden. Every lane except the QA subagent runs in a terminal pane the owner can watch (Herdr: `herdr pane run <pane> "<command>; herdr agent prompt <lead> '<lane>: <result>'"`); the pane reports to the lead itself as its last command. No `nohup`, `&`, background tasks or watchers for the work. Fewer shell panes than lanes: one script runs the lanes in turn in one pane; QA is the longest lane anyway.
- Unattended work starts with a resource check: every required model and tool answers a short probe, and every role has a named substitute.
- Target for the pass: one hour after resources are ready. Each lane has its own limit. A stuck lane gets one restart and one substitute from the roster. After that the state is `WAITING_RESOURCE` with the state saved, never "done".

| Lane | Role | What it does | Limit |
|---|---|---|---|
| A. Gate | the lead, with the card's command | `check --since <base> --tests` of this plugin: touched tests with coverage, CRAP and complexity of changed functions, coverage of added lines, test tampering, secrets, cycles. Without the plugin, the card's fallback gate | 15 min |
| B. Correctness | a senior from a model family other than the author's | the shared brief, fully: the failure table against the code, tests, security | 45 min |
| C. Consumers | a third model family | the shared brief, fully: consumers outside the diff, contract and data compatibility, migrations, needless complexity | 30 min |
| D. Blind QA | a fresh agent that did not write the code | scenarios from the spec before reading the diff, the real process with real failures, mutants, a check for weakened tests | 60 min |
| E. Live | per the card, the "before merge" surface | the user path on a surface built from head; evidence from a log, a screen or a stored record | per card |
| F. Model | the lead | TLC on `specs/<module>.tla` and a model mutant, when spec-card says a model applies | 15 min |

- One brief for both reviewers ([references/briefs.md](references/briefs.md)). Each covers its half fully and reports a proven blocker outside it, without repeating the other half's checklist.
- A finding counts when it names the broken contract, the consequence, and either `file:line` with a scenario "input → wrong result" or an exact evidence gap: which guarantee cannot be confirmed and which command, artifact or environment is missing.
- A level-3 result exists only after every required lane reported on the current candidate. A skipped required lane is not closed by a note in the verdict.
- The live lane may start before the gate once the candidate is frozen; its result counts only for the same head.
- No safe surface for the candidate before merge: the result is "accepted locally, release not verified", and the live check moves to §8. The old production is not a check of the candidate.

## 5. The chef tastes: the lead's verdict

While the lanes run, the lead proves the load-bearing safety fact of the change, one per independent risk class in the spec (usually one, at most three), and takes it to "ran it and saw it" (the pstack `blast-radius` skill does exactly this). An unproven fact stays a limitation and blocks the release when safety cannot be confirmed without it.

When the lanes are back, the lead writes the verdict per [references/verdict-and-done.md](references/verdict-and-done.md):

- **Fix.** The lead reproduced the finding (read the line, reran the repro) or two lanes agree. Duplicates of one cause merge. Usually five items or fewer; a confirmed finding is never dropped to keep the count.
- **Next wave.** Real but non-blocking findings, each with an owner and a date or a return event.
- **Rejected.** With a fact: a file, a version, a run. "I would have done it differently" without a shown defect is rejected.

## 6. Back to the station: one batched repair

- The repair starts after the verdict. Every fix item goes in one message into the same executor session (repair brief in briefs).
- Every behavior finding is closed by a **red test** that covers every site with the same defect. Where no test can show it, a repro.
- **No design change in a repair.** If a defect cannot be closed without a new mechanism (a state file, a protocol, a snapshot, a second runner), the candidate is BLOCKED and does not land. The mechanism becomes a new version of the task: a spec paragraph, one reviewer pass, its own pass. In the seven-round case, a snapshot mechanism added by a round-four repair brought five new findings.
- The repair check looks only at what changed. The gate always runs. QA reruns its red scenarios and the new tests. The reviewer with more findings reads the repair diff `prev..head`. The live lane reruns when the user path changed.

## 7. Two rounds

- Round 1 is the pass. Round 2 is one batched repair and a check of what changed.
- After round 2 the candidate lands if no open defect of the "must not ship" class remains. The rest goes to the next wave.
- "Must not ship": lost or corrupted data; money; secrets, auth, access to someone else's data; a broken user path; a silently wrong result.
- Such a defect blocks the release at any round count. Round 3 changes the verification method or the owner of the node, not only the model. Work continues until the defect is closed, the owner stops it, or the task is BLOCKED.
- Iterations toward a quality bar (a reference design, a measured target) before the candidate is handed in are not acceptance rounds.

## 8. Service: landing and the live check

- Before landing the lead checks the permissions for commit, merge and push separately. No permission means a local delivery.
- The landing run per the card: rebase on origin/main, typecheck, lint, the full suite **once** with a wait for a free machine, the build, the QA mutant on the new SHA with its tests only, fast-forward merge, push. A red test outside the task is named and checked on the base. A red on the test's own time limit is rerun alone on the same SHA: green alone means a false red from load, and the test's limit goes up to the common one.
- After a rebase the gate and the full suite always run on the new SHA. Reviewer and QA verdicts carry over when `git patch-id` of the change is unchanged; otherwise the changed part is checked as in §6.
- Release and deploy only on the owner's word and by the project's runbook. After the deploy the same scenario runs in production (the card's "after release" surface).
- Techniques for landing, mutants, PBT and reviewers in a pane: [references/techniques.md](references/techniques.md).

## 9. The done table and the report

- The lead fills the done table at the end from finished files: the finish-line rows, the lanes, the landing. Only PASS on the current candidate goes in. Not applicable: "n/a: reason".
- The decision trail is the round verdicts plus the executor reports. No separate decision log and no third-model audit of it. In unattended work the round verdict is updated at every lane status change and read first after a context compaction or a restart.
- Before cleanup the evidence sits in the task folder outside the worktrees. Then own worktrees and temp files are removed and own agents are stopped by the environment's normal means.
- The report to the owner: the result on the first line; what is on main and what is in production; what was not verified; the next wave; one line "what I need from you".

## 10. The lesson into structure

After delivery the lead answers one question per defect class that reached the pass: what catches it next time without a human? Pick the strongest mechanism:

1. a type that makes the wrong state fail to compile;
2. a lint or gate rule;
3. a shared helper or script;
4. a runtime check;
5. a line in the spec card or a brief, with an example of the failure.

The mechanism becomes a ticket for the project or for this plugin. Text is allowed only where judgment is needed. One rule lives in one place.

## What we do not do

Measured on two production repos in September 2026: one change took seven rounds and a day and a half; a comparable change took two rounds in one day.

| We do not | Why |
|---|---|
| Use the full gate over the whole tree as the verdict | Red on old debt (827 findings in one repo, 21 tests in the other); it says nothing about the change. Debt is measured separately. |
| Run Jev during acceptance | Only false notes in both repos. Turn it on by hand for an experiment. |
| Add a third reviewer of the same diff | Three families are already there, counting QA. |
| Review the spec one blocker per pass | Ten passes of one blocker each versus one pass with everything at once. |
| Keep a DoD file from the start or a third-model audit of a decision log | Paper. The spec's finish line and the round verdicts do the same. |
| Run the full suite every round | Once in the landing run; touched tests in rounds. |
| Repeat a green check without a new reason | Time without new information. |

## Not evidence

- A self-report by the executor or QA without the command, exit code and log.
- "The build is green" instead of a real call, a screen or a stored value.
- A lane verdict on another SHA, in a modified worktree, or against another spec version.
- At level 3, a review by one model without a second family.
- A "local" smoke instead of the card's surface; the old production instead of the candidate.
- A comment about a race instead of a model or a test.
```

## File: skills/acceptance/references/briefs.md
size: 5738
sha: 6aa8becbc6b06ba0897c35e7508e4dfad5382ccd
upstream: https://github.com/smixs/code-quality/blob/main/skills/acceptance/references/briefs.md

````text
# Briefs

One brief per role. Fill in `<…>`, change nothing else. Every role writes evidence into `.scratch/work/<task>/` of the main checkout, never inside a worktree.

## Executor ticket

```text
Task: <one line>. Spec: <path>, version <N>; the ticket is only a frame, the spec wins.
First copy the "Finish line" and "Failure table" sections verbatim into TASK.md as checkboxes.
Worktree: <path>, branch <name> from <base SHA> (<origin/main or an integration SHA with its dependencies>). Dependencies: <per the card>.
Build it all in one pass; checks at the end: touched tests, typecheck, lint, the gate on the change (<command from the card>). The last run is in a clean detached worktree at the SHA you hand in: files under .gitignore never reach the commit.
Not allowed: weakening or deleting tests to get green; --no-verify; touching <do-not-touch>; inventing a mechanism the spec lacks (then BLOCKED with a question); heavy runs in parallel with someone else's.
Stuck for more than an hour on one spot: BLOCKED with what you tried. Do not reinterpret the goal.
After handing in, do not touch the candidate until the verdict.
Commits: <project rules>.
Report in <.scratch/work/<task>/report.md>: for each finish-line row the command, exit code, one-line result, log path; a "not verified" list.
Last command: <how to tell the lead, for example a message to the lead's session: "<TASK> DONE|BLOCKED: <SHA> <three lines>">
```

## Reviewer brief (lanes B and C)

```text
You are a reviewer. Do not change code. checkout, stash, reset, clean and restore are forbidden.
Task: <one line>. Spec: <path>, version <N>, the "Finish line" and "Failure table" sections.
Your worktree: <path>, detached at <head>. Range: git diff <base>..<head>. First check that HEAD = <head> and git status is empty.
Your half: <B | C>. Cover it fully. The half is the required minimum, not a border: look around for what else the change touched. A proven finding outside your half is accepted; do not repeat the other half's checklist.

B. Correctness:
- Every failure-table row against the code. Boundary inputs. An error swallowed or loud. Retry, a crash midway, a second writer, the order of writes.
- The root, not the symptom: a guard that hides a broken invariant; a retry that hides a broken contract; a fix in the wrong module.
- Tests: do they call the code the way a user does and compare with a literal? Would a test pass if every imported function returned undefined? Is there a test for every failure-table row? Were old tests weakened?
- Security: user input reaching a dangerous sink, secrets in logs, time-of-check versus time-of-use.

C. Consumers and simplicity:
- Who else calls what changed: dynamic calls, CLIs, background jobs, response formats. What breaks outside the diff.
- Contract and data compatibility: old files and records on disk, migrations, rollback to the previous version.
- A needless mechanism, a second path to the same thing, configuration for cases that do not exist, dead code. Three duplicated lines beat a premature abstraction.

List EVERY finding you can prove, not only the first. Format for each:
[blocker|high|medium|low] <file:line or "evidence gap"> — the broken contract in one sentence. Consequence: … Proof: a scenario "input or state → wrong result", or which guarantee cannot be confirmed and which command, artifact or environment is missing. Fix: …
Then a "Checked and clean" list: what you looked at and why it is fine. No taste without a shown defect.
Result: finding counts by level. Write to <.scratch/work/<task>/review-<b|c>-r<k>.md>.
```

## Blind QA brief (lane D)

```text
You are the tester, not the author. Your throwaway worktree: <path>, detached at <head>. Do not touch other worktrees.
Phase 1, before the diff. Read the spec (version <N>: finish line, failure table) and the public interface. Write the scenarios: one, the strongest, per finish-line row and per failure-table row, plus garbage input, a repeat, a cut-off. At most 30 in total; do not multiply variants of one row. Put them as the first section of <qa.md> with the time written, before reading the diff. Do not edit that section later.
Phase 2. Read the diff <base>..<head>. Run the scenarios on the real code and the real process. A controlled double is allowed only at an external boundary the task does not implement: the network, an external API, a model. Never replace the module under test, its storage or its decision code. Each scenario: command, exit code, result, log path. Phase 2 has one hour; what did not fit is listed as not checked, with the reason.
Mutants: one at the consumer boundary that must go red; two or three for money, access, data, migrations and side effects. Use the plugin's mutant command; without it, by hand per "Mutants" in references/techniques.md. A green mutant is a test defect unless it is equivalent.
Weakened tests: git diff <base> <head> over test files. Removed assertions, skips, a mock of the module under test.
Verdict: PASS, REPAIR_REQUIRED or BLOCKED. REPAIR_REQUIRED means "not ready to land". A defect: level, file:line, a one-command repro, expected versus actual. What you could not check goes in its own list. Write to <.scratch/work/<task>/qa-r<k>.md>.
```

## Repair brief (same executor session, after the verdict)

```text
Round 2. Fix every item in one pass:
1. <finding: file:line or gap, scenario, expectation>
For each behavior item: first a red test on every site with this defect, then the fix.
No design change. If an item needs a new mechanism (a state file, a protocol, a snapshot, a second runner), do not build it: BLOCKED with a proposal.
Checks: touched tests, typecheck, lint, the gate. Report in the same format, with the new SHA.
```
````

## File: skills/acceptance/references/spec-card.md
size: 2874
sha: a42226c19c09cd1140087e4ff2e2000ce073d9fc
upstream: https://github.com/smixs/code-quality/blob/main/skills/acceptance/references/spec-card.md

````text
# Spec card

The spec is the recipe. The header carries a version number. An empty section says "n/a: reason" and stays. Words come from the project glossary.

1. **The task in one line.** What changes for the user or the consumer.
2. **Finish line.** The fewest independent observable lines "done when …", usually one to ten, each with its check: a command, a scenario, a screen, a record on disk. With more lines, first check whether the task splits; never drop lines to hit a number.
3. **Decisions.** Modules, interfaces, data formats, the order of operations. A hash, a cache or a compare-before-write gets its format in bytes. Existing seams are named and reused. One rule in one place.
4. **Failure table.** A row for every new outbound call (a model, the network, git, the file system), every durable write (a file, a database, a cache, a marker) and every operation on a lock, a session or a queue.

   | Call or write | Failure | What the user sees | What the code does | Test |
   |---|---|---|---|---|

   Pick the modes by what the boundary does. For a write or a side effect always: half done, retry after a crash, a second concurrent writer. For a read: unavailable, garbage, stale, cut off. A mode that does not apply is not written out; when in doubt, one line "n/a: why".
5. **Platform facts.** The claim, the version and the strongest available proof: `file:line` in the dependency source, an official contract with its version, or a reproducible probe. Proof weaker than the source is marked as a limitation.
6. **Tests.** The highest seam. Required scenarios, taken from the failure table. PBT with a generator and a seed for parsers, validators and invariants. Mutants at the consumer boundary that must go red.
7. **TLA+ model.** Needed when correctness depends on how two actors interleave, on lock or queue transitions, or on the order of durable writes across a crash: the invariants in words and the path to the `.tla`. Otherwise "n/a: correctness does not depend on event order".
8. **Out of scope.** Do-not-touch, what is deleted, what stays.
9. **Limits.** Time, money, machine resources.

## Spec review brief (one pass)

```text
Read the spec <path> (version <N>) and the code it points to at <base SHA>. Project canon: <glossary, ADRs, philosophy>.
Find EVERY place where:
- two developers would build it differently;
- a failure of a call or a write is not described;
- a platform fact is wrong or has no proof;
- the spec contradicts the canon;
- a mechanism is needless or duplicates an existing seam.
Every finding at once, grouped: blocker / high / medium. For each: the spec quote, why it is a problem, the exact text fix.
Change nothing. Result: READY or NOT READY. Write to <file>.
```

Reviewer effort for a spec: medium. The second pass after blocker fixes reads only the changed paragraphs and the sections that depend on them.
````

## File: skills/acceptance/references/station-card.md
size: 2665
sha: 1200e4df506d5cf49d8683240602c88e81375539
upstream: https://github.com/smixs/code-quality/blob/main/skills/acceptance/references/station-card.md

```text
# Station card

One per project. It lives in a project document (for example `docs/acceptance-station.md`) or in `.scratch/work/station.md`; the root `AGENTS.md` or `CLAUDE.md` only links to it. Keep it short, about 40 lines, but complete commands and permissions matter more than the line count. The runbook links to the card and never copies its commands.

## Sections

1. **Repository.** The main branch, where worktrees live, how dependencies appear in a worktree (a symlink, a copy, an install) and what is forbidden there.
2. **Commands.** Touched tests. All tests. Typecheck. Lint. Build. Mutant. The landing run.
3. **Touched tests.** How they are chosen: by default the plugin's selection by name and by import. A project exception is written here, for example "a change under `apps/admin` runs the whole `apps/admin` suite, because render harnesses hide the import".
4. **Gate.** One runnable gate command for the change and its expected output. A fallback when the code-quality plugin is absent: touched tests with their exit code, a `git diff` of test files for deleted and weakened assertions, a secret scan, typecheck and lint. Neither one nor the other means acceptance is BLOCKED.
5. **Live check** (shaped like the pstack verify skill), for two surfaces: "before merge" (the candidate built from head: a local run, a preview, a staging stand, a branch on a server) and "after release" (production):
   - Launch: how to start it or where to deploy, and the sign that it is ready.
   - Doctor: one check that this instance is worth driving.
   - Scenario: how to walk the user path, with concrete commands or buttons.
   - Evidence: what to capture and where to put it.
   - Cleanup: what to tear down; evidence stays.
   - Rollback.
   - For a tool other projects use, the before-merge check runs on a real consumer repo, not on a sample (27.09: 1.3.0 passed a harness sample and missed 73 render tests of the sotish admin).
6. **Test and landing environment.** A test environment without production secrets; personal and production `.env` files are never copied into a worktree.
7. **Machine limits.** Executors, heavy runs, browsers. The load threshold for a heavy run. Read-only reviewers do not count against the limit; gate runs and mutants queue.
8. **Known red tests outside the task.** Test name, cause, since when. So nobody mistakes them for a regression.
9. **What needs the owner's word.** Commit, merge, push, deploy, release, version, messages to people.

## Checking the card

The lead walks the card once: the gate, launch, doctor, one scenario, evidence, cleanup. A card nobody ran is a draft, and no release acceptance runs on it.
```

## File: skills/acceptance/references/techniques.md
size: 3803
sha: 3ad387f80f57c144c9ac744dd51e35f9aa668e9b
upstream: https://github.com/smixs/code-quality/blob/main/skills/acceptance/references/techniques.md

```text
# Techniques

The process is in SKILL.md; this file holds only the how.

## PBT

- Where: parsers, validators, resolvers, normalizers, codecs, state predicates. Not for mappings, configs or I/O wrappers.
- Property catalog: round trip; comparison with a simple independent model; boundaries; an invariant after an operation; multi-step flows through `fc.commands` or `fc.modelRun` (Python: `RuleBasedStateMachine`).
- "Does not crash on garbage" means invalid input gets the designed rejection, not a silent success.
- A failure prints its seed, the seed reproduces it. A counterexample is kept as a regression test with its seed.
- A property that restates the implementation or filters out almost every input does not count.

## Mutants

- One at the consumer boundary: a call from a shell, an agent or a child process, a send, a write of a fact. For money, auth, someone else's data, side effects and migrations, two or three from the contract-violation catalog: a skipped auth check, a foreign tenant, a repeated side effect, a wrong error type, a non-atomic write. The landing run repeats one QA mutant on the new SHA with its tests only.
- The verifier picks the mutant after the executor's tests, never the executor.
- Tool: `bun <plugin-root>/scripts/quality.ts mutant --repo <worktree> --file <path> --find '<exact text>' --replace '<text>'` (exact replace, run, restore from a copy, a proof that the file is clean).
- By hand, without the command, and only in the QA lane's throwaway worktree: a `trap` that restores; the anchor as an exact string via `grep -F`; a copy of the file; the edit; `cmp` that the file changed; the run; restore from the copy; `git status --porcelain` before and after match. `git checkout --` and `stash` are forbidden. BSD sed has no `0,/re/`. Check the test path with `ls` before the run. An interrupted worktree is spoiled and removed; the candidate and other lanes' worktrees are never mutated.
- A green mutant does not prove a defect by itself: first check equivalence and reachability. An equivalent mutant is recorded without an artificial test.
- A mutation caught only by reading the source with a regex does not count.
- Report: the mutant, the exact test that went red, the seed or input.

## Reviewers in a visible pane

- `codex exec` started from a script waits for stdin and hangs: always `codex exec … < /dev/null`, output with `-o <file>`.
- A reviewer in a terminal session gets the brief as a file path, not pasted text.

## Landing

- A script where each check is its own line, output goes to a file, and a failure stops the run. A pipe on a checking command (`| tail`, `| grep`) is forbidden: it hides the exit code.
- The landing run happens in a clean worktree with the card's test environment. Personal and production `.env` files are not copied.
- The head SHA is fixed at hand-in. The published ref is compared before a release. An empty ref or a different SHA blocks the release.
- One integrator builds the candidate, the next one waits. Machine limit by default: two executors, one heavy run, one browser.
- Several small accepted branches land in one run. A red run is split.
- Before rerunning a failed run, read the whole log of the step, not the tail.
- A known flaky test is rerun alone, only when it is the single red test.
- "Regression" only after reproducing it on both SHAs in one environment. Until then: "the test is red for me, cause not found".

## Deploy

- A green landing run is a technical acceptance. Publishing and deploying need the task's permissions.
- A release without the agreed live check is not accepted. A local task does not turn into a release.
- After a frontend deploy, check the cache.
- A UI diff is grepped for hex, oklch, rgb, arbitrary values and new color tokens; a match means "not accepted".
```

## File: skills/acceptance/references/verdict-and-done.md
size: 1874
sha: 30a08a9b14f42ac0b0282fb077ef02ce5f96579c
upstream: https://github.com/smixs/code-quality/blob/main/skills/acceptance/references/verdict-and-done.md

````text
# Round verdict and done table

## Round verdict

In unattended work this file is updated at every lane status change and read first after a context compaction or a restart.

```markdown
# Round <k> verdict: <task>, spec v<N>, base <SHA>, head <SHA>

| Lane | Status before start | Who | Result | File |
|---|---|---|---|---|
| A. Gate | required | lead | PASS / FAIL | <report> |
| B. Correctness | required | <model> | <N findings> | <file> |
| C. Consumers | required | <model> | <N findings> | <file> |
| D. Blind QA | required | <model> | PASS / REPAIR_REQUIRED / BLOCKED | <file> |
| E. Live | required / n/a: reason | <who> | <result> | <log, screen> |
| F. Model | required / n/a: correctness does not depend on event order | lead | <TLC> | <file> |

Load-bearing facts the lead proved: <fact, command, result> (one per risk class).
Waiting for resources: <lane, what, since when> or "none".

## Fix
1. <finding> — who found it; how the lead confirmed it: the line or the repro.

## Next wave
- <finding> — why it does not block; owner; date or return event.

## Rejected
- <finding> — the fact: file, version, run.
```

## Done table

Filled at the end from finished files. Only PASS on the current candidate goes in. Finish-line rows are copied from the spec verbatim.

```markdown
# Done: <task>, spec v<N>

| Row | Evidence | Result |
|---|---|---|
| <finish line 1> | <test, command, screen: path> | PASS |
| Gate on <head> | <gate report> | PASS |
| Reviewers, two families | <files>, verdict <file> | closed |
| Blind QA | <qa-r<k>.md> | PASS |
| Mutants | <log> | red N of N |
| Model | <tlc.log> or n/a: reason | |
| Live check before merge | <log, screen> or "accepted locally, release not verified" | |
| Landing | main <SHA>, <log> | |
| Live check after release | <log> or "no release" | |
| Not verified | <list> | |
| Next wave | <file> | |
```
````

## File: README.md
upstream: https://github.com/smixs/code-quality/blob/main/README.md

````text
<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
  <img src="assets/logo-light.svg" width="440" alt="Code Quality">
</picture>

# Code Quality

**Your AI agent made the tests green. Did it fix the code, or the tests?**

A quality advisor for coding agents: git hooks and Stop hooks that raise a loud red flag on test tampering, secrets and skipped hooks, and hold one complexity bar on every changed function. They never block: the agent sees the evidence and decides. 12 languages, one config file, no server.

<p>
  <a href="https://skills.sh/smixs/code-quality"><img src="https://skills.sh/b/smixs/code-quality?style=flat-square" alt="skills.sh installs"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-22c55e?style=flat-square" alt="MIT"></a>
  <a href="scripts/"><img src="https://img.shields.io/badge/tests-407_passing-22c55e?style=flat-square&logo=bun&logoColor=white" alt="407 tests"></a>
  <a href="https://docs.claude.com/en/docs/agents/agent-skills"><img src="https://img.shields.io/badge/Claude_Code-skill-D97757?style=flat-square&logo=anthropic&logoColor=white" alt="Claude Code skill"></a>
  <a href="hooks/hooks.json"><img src="https://img.shields.io/badge/OpenAI_Codex-Stop_hook-000000?style=flat-square&logo=openai&logoColor=white" alt="Codex"></a>
  <a href="adapters/pi.ts"><img src="https://img.shields.io/badge/pi-extension-6E56CF?style=flat-square" alt="pi"></a>
  <a href="skills/code-quality/references/jev.md"><img src="https://img.shields.io/badge/Jev-TypeSafe_%7C_OpenRouter-0ea5e9?style=flat-square" alt="Jev"></a>
</p>

<p>
  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go">
  <img src="https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white" alt="Rust">
  <img src="https://img.shields.io/badge/Java-ED8B00?style=flat-square&logo=openjdk&logoColor=white" alt="Java">
  <img src="https://img.shields.io/badge/Kotlin-7F52FF?style=flat-square&logo=kotlin&logoColor=white" alt="Kotlin">
  <img src="https://img.shields.io/badge/C%23-512BD4?style=flat-square&logo=dotnet&logoColor=white" alt="C#">
  <img src="https://img.shields.io/badge/Swift-F05138?style=flat-square&logo=swift&logoColor=white" alt="Swift">
  <img src="https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white" alt="PHP">
  <img src="https://img.shields.io/badge/Ruby-CC342D?style=flat-square&logo=ruby&logoColor=white" alt="Ruby">
  <img src="https://img.shields.io/badge/C%2B%2B-00599C?style=flat-square&logo=cplusplus&logoColor=white" alt="C++">
  <img src="https://img.shields.io/badge/Dart-0175C2?style=flat-square&logo=dart&logoColor=white" alt="Dart">
</p>

</div>

![Two toll lanes: red barrier down, green barrier up](assets/hero.webp)

## Advice, not a gate

Nothing here stops the agent. No hook refuses a commit, a push, a shell command or the end of a turn. The plugin trusts the model the way a good reviewer trusts a colleague: it measures, shows its work and says plainly when something is dangerous. The agent decides, and says why.

Dangerous moves are red flags, printed first in every output:

```
RED FLAG: tamper/test-deleted  tests/queue.test.ts:1  test file deleted -- a green run stops proving the code works; check: is the test change intended? restore it, or say why in the commit message
```

Red flags: a secret in the change or in the pushed history, a deleted, skipped or weakened test, a baseline refreshed with the code, red tests on push, and a git command that skips the hooks (`--no-verify`, `commit -n`, `core.hooksPath`). Everything else (complexity, CRAP, diff coverage, cycles, dead code, clones, glossary, AI attribution, Jev) is a finding or a note in the report.

## What's new in 1.3

- **Advice, never a block (1.3.3).** No hook stops a commit, a push, a shell command or the end of a turn. Dangerous moves are `RED FLAG` lines, first in every output; the Stop report reaches the agent once, with its next message.
- **Accept a change by its own tests.** `check --since <base> --tests` runs every test that reaches the change through the project's imports, with coverage, and judges only the changed functions.
- **Prove a test catches a bug.** `mutant` makes one exact mutation, runs the tests and restores the file byte for byte, even after Ctrl-C.
- **The report is about the pushed commit.** When a push has touched tests to run, pre-push runs them only on the checked-out commit and says so otherwise.
- **Calm on a shared machine.** Test runs wait for a busy machine, Ctrl-C kills the whole test group, and a copy run by hand no longer takes the machine's git hooks.

Full notes: [releases](https://github.com/smixs/code-quality/releases).

## The cheap way out, caught

| The agent | The report |
|---|---|
| Marked the failing test `it.skip` | `tamper/test-skipped tests/queue.test.ts:12` |
| Dropped two assertions | `tamper/assertion-weakened tests/queue.test.ts:48` |
| Swapped `toEqual` for `toBeTruthy` | `tamper/assertion-weakened tests/queue.test.ts:52` |
| Stubbed the module under test | `note: tamper/mock-added tests/queue.test.ts:+64` |
| Refreshed the baseline with the code | `tamper/baseline-touched baseline.json:1` |
| Shipped 50 lines, 31 covered | `cov/diff: 62% (31/50 lines, minimum 80%)` |

Deterministic: file and line in the report, red flags first. No model is asked for an opinion, and the commit still goes through; the agent answers the flag.

## How it works

```mermaid
flowchart LR
    A[git hooks] --> Q
    B[Stop hook: Claude, Codex, pi, omp; Grok after global hook install] --> Q
    C[OpenCode idle notice] --> Q
    Q[one script] --> R[RED FLAG lines first: secrets, tampered tests, red tests on push, skipped hooks]
    R --> D{new finding on a changed line?}
    D -->|yes| F[FINDINGS, advice to the agent]
    D -->|no| P[CLEAN]
    F --> G[the commit, push or turn goes ahead; the agent decides]
    P --> G
```

- **One bar.** Cyclomatic complexity 10, CRAP 30, 80% coverage of added lines, no new cycles, no new dead code, no secrets.
- **Old debt is not news.** A baseline snapshot keeps existing findings as debt. Only new findings on changed lines are reported.
- **Seconds, not minutes.** `check` runs in 3-19 s on a real repo. The full run with tests and coverage is a manual one: a debt measurement, not a verdict on a change.
- **Acceptance on the change.** `check --since <base> --tests` runs the change's touched tests with coverage and reports on the change with it. `check` exits 1 on findings so a script or CI can decide; no hook turns that into a stop. `mutant` proves a test catches one exact bug and always restores the file.
- **Any language.** Complexity from lizard, coverage from lcov, adapters for TypeScript, Python, Go, Rust, Java, Kotlin, C#, Swift, PHP, Ruby, C/C++, Dart.

## Install

[Bun](https://bun.sh) is required for the gate and the shell hooks. Install for your agent:

| Agent | Install |
|---|---|
| Claude Code | `claude plugin marketplace add smixs/code-quality` then `claude plugin install code-quality@code-quality` |
| Codex | `codex plugin marketplace add smixs/code-quality` then `codex plugin add code-quality@code-quality`; review and trust its hooks with `/hooks` |
| Grok 1.0.40 | `grok plugin install smixs/code-quality --trust`, then from this repository or its installed plugin root run `bun scripts/quality.ts install-grok-hooks` |
| pi | `pi install git:github.com/smixs/code-quality` |
| omp | `omp plugin install github:smixs/code-quality` |
| OpenCode V1 | `bun add github:smixs/code-quality` in a project with `package.json`, then add `"plugin": ["file:./node_modules/code-quality"]` and `"skills": ["./node_mod
````
