Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions fork-kit/review/COMMENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,33 @@ state: an old config without the new key is read with the default
findings: none
```

A quick check of a nit-only fix (SKILL.md, "Order", step 7). The `nit-only:` line is for the orchestrator: on `yes` it
still posts the override for the fix head, because the other lenses still name the old head. The gate reads the report
as any other, and counts it as a round (a read of a new head).

The gate reads: `lens quick-check, read, clean, state`

```text
lens: quick-check · reviewer: lens agent · read at: 0123456789abcdef0123456789abcdef01234567
covered: the fix diff since round 1 (tests and message text only)
nit-only: yes
state: no write step changed
blocker: none
major: none
```

The state answer only in `checks:` (an older shape): the gate takes the read, but the kit's `check` refuses it (no state
line). Write the answer on a `state:` line.

The gate reads: `lens correctness, read, clean, no state`

```text
lens: correctness · reviewer: lens agent · read at: 0123456789abcdef0123456789abcdef01234567
covered: src/queue.ts
checks: a second run finds the entry and does nothing; an empty queue file is read as empty
finding: minor src/queue.ts:12 the error text names the wrong flag
```

## Reports that block

A major finding. The head is held until this lens posts a new read on a fixed head (or a person decides).
Expand Down
16 changes: 8 additions & 8 deletions fork-kit/review/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ question every time, one or two independent lenses, at most two lens rounds, roo
failing tests. Unlike the other kits it installs nothing on a host: an agent reads the skill and runs the tools from a
checkout of the fork.

| File | What |
| -------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [SKILL.md](SKILL.md) | the review skill: plan, state question, order, rounds, minors, lenses, runners, posting |
| [REVIEW.md](REVIEW.md) | how a project adopts it: the review block, lens prompt files, the gate, kit settings |
| [COMMENTS.md](COMMENTS.md) | the lens comment format, with examples checked against the gate's own parser |
| [review-kit.example.json](review-kit.example.json) | the kit settings (`.github/review-kit.json` in the project; optional) |
| [lib/review_kit.py](lib/review_kit.py) | `plan` (which lenses a change needs), `check` (how the gate reads a comment), `doc` |
| [eval/](eval/README.md) | the model eval: which model and effort finds the confirmed bugs, from one config file |
| File | What |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [SKILL.md](SKILL.md) | the review skill: tiers, state question, order, rounds, minors, lenses, runners, posting |
| [REVIEW.md](REVIEW.md) | how a project adopts it: the review block, lens prompt files, the gate, kit settings |
| [COMMENTS.md](COMMENTS.md) | the lens comment format, with examples checked against the gate's own parser |
| [review-kit.example.json](review-kit.example.json) | the kit settings (`.github/review-kit.json` in the project; optional) |
| [lib/review_kit.py](lib/review_kit.py) | `plan` (which lenses a change needs), `check` (how the gate reads a comment), `doc` |
| [eval/](eval/README.md) | the model eval: which model and effort finds the confirmed bugs, from one config file |

The kit holds no project facts: which paths are critical and which lenses they need are the project's `review` block
(read by the gate), and who runs a lens is the project's kit settings. The kit imports the gate's own parser
Expand Down
27 changes: 21 additions & 6 deletions fork-kit/review/REVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,21 @@ Add a `review` block to the queue config (`.github/pr-queue.json` by default), i
then only reports what it would ask for. Start from the gate's
[review.recommended.json](../../fork-ci/actions/pr-queue/review.recommended.json):

- `rules`: the project's paths, heaviest first; the first rule that matches a path takes it. Critical paths (stored
data, migrations, deploy, security, the merge path itself) name **two** lenses; the last rule is the catch-all
`**`, normal, one lens.
- `rules`: the project's paths, heaviest first; the first rule that matches a path takes it. A rule's `weight` is
the tier of its paths (`critical`, `normal` or `light`; SKILL.md, "Tier"). Critical paths (stored data,
migrations, deploy, security, the merge path itself) name **two** lenses; the last rule is the catch-all `**`,
normal, one lens. A project with its own tier names (a tier per module or plugin) writes one rule per module
path with the weight its tier maps to; the tier list itself stays in the project's own files.
- `lenses`: each lens's name and its prompt file.
- `min_lenses`: at least 2 for critical, 1 for normal, 0 for light.
- `rounds`: the gate's own cap. Keep `max` at or above the kit's `lens_rounds` (the plan warns otherwise).
- `findings: true`: the gate holds a head while a lens's newest read has an open blocker or major.
- `state_line: true`: the gate parses it but does not enforce it yet; the kit's `check` does.

Also set the queue config's `lens_format_doc` (a text the gate only quotes in its comments) to where agents read
the format: the kit's [COMMENTS.md](COMMENTS.md) at the fork tag the project pins, or the project's adapter skill
if it links there.

Check it: `python3 -I fork-kit/review/lib/review_kit.py plan --root . --changes <file>` with a
`git diff --name-status -z -M` output, or `--base origin/main` on a branch. A config the gate refuses gives a plain
message and exit 2.
Expand Down Expand Up @@ -68,6 +74,15 @@ rule order would let a lighter rule take a heavier rule's paths.

## What stays in the project

The review block, the lens prompt files with the project's own hints, the kit settings, and anything about outside
reviewers. The general rules (tiers by path, the state question, one or two independent lenses, rounds, minors,
attacks with tests, the comment format) are the kit's, so a project does not keep its own copy.
| Project fact | Where |
| ---------------------------------------------------------------- | -------------------------------------------------------------- |
| which paths are critical, normal or light; the lenses each needs | the `review` block of the queue config (read by the gate) |
| its lens prompts, with its domain's typical bugs and attacks | the lens prompt files the block names |
| who runs each lens, rounds, minors, the state question | `.github/review-kit.json` |
| the override prefix, ready and push commands, lens authors | the queue config (`override`, `ready_command`, `push_command`) |
| outside reviewers, follow-up issue labels, its own checks | the project's adapter skill or docs |

The general rules (tiers by path, the state question and the failure table, one or two independent lenses, twin lens
names, rounds and the nit-only quick check, minors, attacks with tests, the comment format) are the kit's, so a
project does not keep its own copy. A project's adapter skill is a few lines: it points at [SKILL.md](SKILL.md) and
adds only its domain lenses and commands.
Loading
Loading