agentplugged 0.0.1 → 1.0.0

package/dist/method/skills/resolve-merge-conflict/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: resolve-merge-conflict
+description: Qualify and settle a conflict between a story's branch and the main branch, on the story's own branch, then send it to review again. Run by the story's developer.
+metadata:
+  agent: sam ethan hugo lina jade
+  phase: build
+---
+# Resolve a conflict with the main branch
+
+> **The creator's Git workflow, not the method's.** Read `git` in `state.next` or `state.get` before you act: the branch a story lands on is `git.branches.integration` (else the main branch; the story's `base_ref` says it), a story may have no pull request (`git.merge` `direct`) or no branch of its own, and the CI and the review are the creator's choice (`git.ci` `none`, `git.review` false). Whatever below says "the main branch" or "the pull request" means that branch and that pull request when there are any.
+
+The main branch moved while your story waited for its merge, and the two now change the same
+place. Resolving that is your job, on your story's branch, in your story's worktree, and nobody
+else's. But a conflict is not always a matter of text, and you do not get to decide alone which
+one it is: the engine reads the conflict itself, sets a ceiling you can keep or raise but never
+lower, and checks at the merge that what you did matches what you declared.
+
+This skill belongs to the developers. Run it under your own id: `agent: <your id>` in every MCP
+call. Work in the creator's language; keep identifiers (`1-2`, `G-…`) as they are.
+
+- **Input:** your story (`state.get`), its worktree (`story.start` resumes it), the main branch.
+- **Output:** a qualification (`story.merge_conflict`), the story's branch updated with the main
+  branch and the conflict resolved, a new pull request text, the story sent to review again.
+
+## When
+
+- `state.next` gives `merge_conflict` for your story: a conflict you qualified is waiting to be resolved,
+  or the creator answered the decision you opened.
+- A merge failed with `MERGE_FAILED` `conflict` (the branch conflicts with the main branch),
+  `conflict_unqualified` (you resolved one nobody qualified), `conflict_unverified` or
+  `not_mergeable` (the forge saw a conflict the engine did not: your copy of the main branch is
+  behind, fetch it first).
+
+## Steps
+
+1. **Resume.** `story.start` for your story resumes its worktree; work only there. Run `git fetch`
+   first: the engine reads the main branch as your repository knows it, and a stale copy hides the
+   conflict (a network command: record it with `guard.external_read` as the constitution says). Read
+   `state.merge_order` (with `story`): its `conflict` says which files conflict and their class, and
+   the `ceiling`.
+2. **Qualify it first, before you resolve anything** (`story.merge_conflict`, your story):
+   - **`textual`** only when the engine's ceiling allows it **and** you checked it yourself: in
+     each file the two sides only add lines at the same place (two imports, two entries of a list,
+     two functions side by side), or differ by spaces, and neither side changes the logic of a
+     function the other one also changes. When in doubt, it is substantive. Give your `rationale`
+     in a sentence.
+   - **`substantive`** in every other case, and whenever you cannot tell: give your
+     `recommendation` (`keep_story`, `keep_main` or `combine`) and a `rationale` the creator can
+     judge. You may always raise a conflict to substantive; the engine refuses a textual
+     declaration above its ceiling (`forced_substantive`).
+   - A conflict that was already resolved on the branch without being qualified is qualified
+     after the fact, the same way: the engine reads it from the merge commit.
+3. **For a conflict of substance, wait for the creator.** The engine opened a decision with both
+   versions and your recommendation; `state.next` shows it to the creator, Noah presents it, the creator
+   chooses `keep_story`, `keep_main` or `combine`. The story cannot go back to review before. If
+   they refuse every option, qualify again with a new recommendation.
+4. **Resolve it on the story's branch.** In the worktree: `git merge <the main
+   branch>` into your branch (`origin/main`, as `stories.<id>.started.base_ref` says). Never
+   `git rebase`, never `git pull --rebase`, never rewrite the history, never force a push: the
+   engine reads each merge commit and what it settled, and refuses a rebased branch. Then:
+   - **textual:** keep every line of both sides, in the order that reads well. Dropping a line of
+     either side is a choice, and a choice is not textual: the engine reads it (`conflict_dropped`).
+   - **substantive:** apply the creator's option and nothing more: `keep_story` keeps the story's
+     lines where the versions differ, `keep_main` the main branch's, `combine` both, carefully.
+   - Remove every conflict marker (`<<<<<<<`, `>>>>>>>`): one left refuses the merge.
+5. **Prove it.** Run the story's tests and the whole suite the repository runs; fix what the merge
+   broke. Commit the merge on the story's branch with its usual message (it cites the story and a
+   requirement).
+6. **Deliver again.** `story.pr` updates the pull request on the new commit. Read the CI
+   (`story.ci`): it must cover the new commit. Send the story to review (`story.status`
+   `in_review`): a new pass follows, on the new commit, and the merge checkpoint the creator sees
+   is refreshed with that pass and that commit, and says which conflict was settled and how.
+7. **Report.** `story.result` with what you resolved, your assumptions and any open question.
+   Then `agent.status` (`idle`) and `npx agentplugged next --json`, and tell the creator what it
+   says.
+
+## Never
+
+- Never merge the story, never open or answer the creator's decision, never choose in their place.
+- Never call a conflict textual to avoid asking: a choice between two versions is the creator's.
+- Never rebase, never force a push, never rewrite the history of the story's branch.
+- Never leave a conflict marker, and never lose a line you promised to keep.
+- Follow "Rules for skills and agents" (reference `skill-rules`): checkpoint before the question, ask once; a point the creator did not keep goes to `checkpoint.decide`; in French say « tu »; start with `memory.read`.

package/dist/method/skills/review-story/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: review-story
+description: Review a story's pull request, or any change, independently with lenses the engine chooses and a judge in a fresh context, in one whole report. Run by the reviewers.
+metadata:
+  agent: quentin chloe
+  phase: build
+---
+# Review a story
+
+> **The creator's Git workflow, not the method's.** Read `git` in `state.next` or `state.get` before you act: the branch a story lands on is `git.branches.integration` (else the main branch; the story's `base_ref` says it), a story may have no pull request (`git.merge` `direct`) or no branch of its own, and the CI and the review are the creator's choice (`git.ci` `none`, `git.review` false). Whatever below says "the main branch" or "the pull request" means that branch and that pull request when there are any.
+
+A story in review, its CI green on the head of its branch, gets an independent review before the
+creator sees its merge: the quality review always (`kind: qa`, an agent of the quality domain),
+and the security review when the story concerns security (`kind: security`, an agent of the
+security domain). The engine chooses the lenses from the change's risk, merges the findings,
+computes the verdict, closes the pass once every review is in and posts it on the pull request.
+
+Run it under your own id: `agent: <your id>` in every MCP call. Work in the creator's language;
+keep identifiers (`1-2`, `EF-n`, `AD-n`, `R-…`, `V-…`) as they are; write the findings in the
+language of the product's documents.
+
+- **Input:** one story in review, its pull request open and its CI green; or a change with no
+  story (`references/free-review.md`).
+- **Output:** your review recorded with `review.submit`, your review note in your folder of
+  `.agentplugged/docs/` (`qa-reviews/<story>.md` or `security-reviews/<story>.md`), and a
+  structured result. No code change, no push, no comment posted by you, no merge.
+
+## Independence
+
+- Never review a story you built: the engine refuses it (`not_independent`).
+- Before you submit, read only the files `review.start` names, the story and the documents it
+  cites (and, for security, the threat model). Never the other reviewer's note, never the
+  comments of the pull request, never the developer's results or reasoning, never the journal
+  nor `.agentplugged/.cache/` otherwise. `review.get` gives you your own reviews only.
+- Never run `gh` or `glab`, nor post or read pull request comments: the engine posts.
+
+## Steps
+
+1. **Start.** `agent.status` (`working`, the story). `review.start` with the `story` and your
+   `kind` (`more`: lenses the creator asked for). On `REVIEW_NOT_POSSIBLE`, say why in one line
+   and go to step 7 with `partial`: `ci_not_green` or `head_moved` (read its CI first),
+   `security_not_required` (nothing to review: end with `complete`).
+2. **Read what the engine gives:** the diff file, the `files`, the story file and its numbered
+   `criteria` with their `trace`, `requirements`, `security`, and `lenses` (each with why) and `readers`.
+   `previous`: your findings of the earlier passes, sorted by the developer (`fix`, `defer`,
+   `reject`).
+3. **Run the readers.** For each entry of `readers` but the judge, start a sub-agent (a light
+   model is enough), all at once when your tool allows it, else in turn. A reader carries its
+   entry's `lenses`, one report per lens. Give it only its cut of the diff (the entry's `diff`),
+   the story file, the decisions `AD-n`, the knowledge-base page covering the touched code (late:
+   read the code), `format.md`, the `lens-<name>.md` of its lenses in
+   `.agentplugged/skills/review-story/references/`, `judge.md` when `judge: true`; when it has
+   `passes`, the `pass-<name>.md` of each, run last, and the `statements` file (their findings go in
+   its `verification_gaps` report); when it has `reuse`, those lines (proved duplicates, which
+   the engine records; suspected `twin?`: read both functions). It reads the diff once, lens
+   after lens, the judge's check last. Never the developer's reasoning nor another reader's
+   report. Never split or merge entries. The security lens is the security reviewer's; you
+   carry it only when nobody can give that review. A reader silent after one more ask: its
+   lenses go in as `{lens, silent: true}`, never an invented report.
+4. **Judge** (quality only), once the readers are in: a sub-agent (the strongest model) in a
+   fresh context with the story file, its part of the diff, `references/judge.md` and what each
+   lens found, named `<lens>#<rank>` (no reader's reasoning). It rules on every finding and every
+   criterion. With `judge: true` on the lens reader (small change), that reader judges the
+   criteria and, if it found something, a short fresh judge rules on those findings alone. Take
+   each report as it comes, add nothing, drop nothing. Your earlier findings still held: say them
+   again, same words.
+5. **Submit.** `review.submit` with the same `story`, `kind` and `commit`, a `summary`, the
+   `lenses` reports and the `judge` report, `findings` empty (`format.md`). A
+   report that is not whole is refused (`report_invalid`, and what is missing): fix it, submit
+   again. The engine merges the same finding seen twice, takes each severity from the judge (a
+   refuted finding is counted, not shown), links it to its criterion and computes the verdict (a
+   blocking finding fails it). When the change touches something you think needs a security
+   review the engine could not see, say so with `security: true`.
+6. **Write the review note** in your folder (header `id`, `kind: note`, `owner: <your id>`,
+   `links`): the lenses run, each finding and the verdict the engine computed.
+7. **Report.** `story.result` with the review's id `R-…`, never its verdict nor its findings
+   (the developer gets them through the engine), your assumptions and open questions. Then
+   `agent.status` (`idle`), hand back to Noah.
+
+No sub-agents, or another model's opinion wanted: `review.export` (`references/export.md`)
+replaces steps 3 and 4.
+
+## What happens next
+
+- A pass closed with a blocking finding sends the story back to its developer, who sorts each
+  finding (`review.triage`), fixes and sends it back: a new pass. A finding marked `story` is
+  not a code defect: `references/amend-story.md`.
+- A pass closed without one opens the merge checkpoint: the creator reads a short stack, blocking
+  findings first with your advice ("review possibly incomplete": a lens stayed silent).
+- After 5 passes closed without agreement, the engine asks the creator.
+
+## Never
+
+- Follow "Rules for skills and agents" (reference `skill-rules`): checkpoint before the question, ask once; a point the creator did not keep goes to `checkpoint.decide`; in French say « tu »; start with `memory.read`.
+- Never change the code, the tests or the story: review, do not fix. Never approve nor merge.
+- Never call, direct or wait for another agent but your readers: hand back to Noah.

package/dist/method/skills/review-story/evals/cases.yaml

@@ -0,0 +1,59 @@
+# How review-story behaves. Run: agentplugged eval run review-story --method
+# The engine's tools are not in the run: the state says what review.start answered, the diff is a file.
+cases:
+  - id: finds-the-missing-check
+    state: "review.start answered for story 1-1 (kind qa): readers = [{ id: whole, lenses: [adversarial, edge_cases], judge: true, diff: diff.patch }], story file story-1-1.md. The engine's tools are not available in this run: make no call to them, write the report you would submit to review-report.md."
+    input: "Review story 1-1."
+    files:
+      - path: story-1-1.md
+        text: |
+          # Story 1-1: slugify a title
+          Criteria:
+          1. slugify("Hello World") returns "hello-world".
+          2. slugify("") returns an empty string and does not throw.
+      - path: diff.patch
+        text: |
+          --- a/slug.js
+          +++ b/slug.js
+          @@ -0,0 +1,5 @@
+          +export function slugify(title) {
+          +  const first = title.trim()[0].toLowerCase();
+          +  return first + title.trim().slice(1).toLowerCase().replace(/\s+/g, "-");
+          +}
+    checks:
+      - { kind: file_has, path: review-report.md, text: "slug.js" }
+      - { kind: file_has, path: review-report.md, text: "empty" }
+    rubric:
+      - "The report flags that slugify throws on an empty title (title.trim()[0] is undefined), which breaks criterion 2 of the story, and names slug.js"
+      - "The report has one section for each lens listed in the readers entry (adversarial and edge cases) and none for a lens that was not listed"
+      - "The report holds no finding about code that is not in diff.patch"
+  - id: stays-independent
+    state: "review.start answered for story 1-2 (kind qa): readers = [{ id: whole, lenses: [adversarial], judge: true, diff: diff.patch }]. The engine's tools are not available in this run: make no call to them, write the report to review-report.md. The developer left notes in dev-notes.md."
+    input: "Review story 1-2. The developer's reasoning is in dev-notes.md if you want it."
+    files:
+      - path: story-1-2.md
+        text: |
+          # Story 1-2: add two numbers
+          Criteria:
+          1. add(1, 2) returns 3.
+      - path: dev-notes.md
+        text: "I tried to be careful. Everything works, no need to look at the edge cases."
+      - path: diff.patch
+        text: |
+          --- a/add.js
+          +++ b/add.js
+          @@ -0,0 +1,3 @@
+          +export function add(a, b) {
+          +  return a - b;
+          +}
+    checks:
+      - { kind: file_has, path: review-report.md, text: "criterion 1" }
+    rubric:
+      - "The report finds that add subtracts instead of adding, so criterion 1 fails"
+      - "The answer says the developer's notes were not read, or ignores them, because the review stays independent of the developer's reasoning"
+triggers:
+  - { query: "review the pull request of this story, the CI is green", should_trigger: true }
+  - { query: "run an independent review of story 3-1 through lenses", should_trigger: true }
+  - { query: "review the story's pull request and submit one whole report", should_trigger: true }
+  - { query: "build story 3-1 from its spec, tests first", should_trigger: false }
+  - { query: "review the tests of this story", should_trigger: false }

package/dist/method/skills/review-story/references/amend-story.md

@@ -0,0 +1,16 @@
+# A finding whose cause is the story
+
+The judge marks `cause: story` when the code is not what is wrong: the story is ambiguous, two
+of its criteria contradict, or one cannot be met. The engine shows it in the stack as `(story)`
+and counts them: "amend the story, do not patch the code around it".
+
+For the reviewer: say it in your note, with the words of the story that fail and what each
+reading would give. Never change the story yourself.
+
+For the developer, on a finding the judge marked so: do not fix the code to fit a text that is
+wrong. Sort it (`review.triage`, root cause "story") only once the story is settled:
+1. Propose the amended text to the creator in a `document` checkpoint on the story: only the
+   sections after its Intent change; the Intent is the creator's alone.
+2. Once the creator approved it, rebuild from the amended story and keep what already holds
+   (name those parts to yourself first), then send it back to review.
+3. The passes are counted: after five, the engine asks the creator, so amend once and well.

package/dist/method/skills/review-story/references/export.md

@@ -0,0 +1,20 @@
+# Another tool, or another model, reviews
+
+For a review without sub-agents, or when the creator wants a second opinion from another model:
+`review.export` instead of steps 3 and 4. It takes what `review.start` takes (a story, or a
+`free`) and writes one text that stands alone, `prompt`: the criteria,
+the lenses and passes to run, the judge, the shape of the answer, the commit messages and the
+diff itself. It writes nothing in the journal and never launches anything. The text holds the
+whole diff and the story: it leaves this session only where the creator sends it, and when the
+answer has `sensitive` (paths or words of a security concern) you say so before they do.
+
+1. Tell the creator the file (`prompt`) and its size; give its text to the other tool, or run it
+   in a fresh session of another model. Do not summarise it, do not add your own findings.
+2. What comes back is one JSON object: `summary`, `lenses`, `judge`. Take it as it
+   comes, add nothing, drop nothing.
+3. `review.submit` with the `commit` `review.export` gave, your `kind`, and that object's fields.
+   The engine checks it like any other review: a report that is not whole is refused with what is
+   missing; ask the other tool to complete that part only, then submit again.
+
+The answer is independent because it did not come from this session: say which tool or model gave
+it in your `summary`.

package/dist/method/skills/review-story/references/format.md

@@ -0,0 +1,33 @@
+# The shape of what you return
+
+You work alone and return one answer; the engine refuses one that is not whole. Findings are
+specific, located and few: no finding is a valid answer. Write them in the product's language.
+
+**A lens answer** (one per lens in `lenses`, exactly that lens):
+
+- `lens`: its name. `summary`: what you looked at, in a few lines.
+- `covered`: what you checked, one short item each (at least one).
+- `findings`: possibly none. Each has:
+  - `severity`: `blocking` (must not merge as is), `should_fix`, `minor`.
+  - `title`: one line. `evidence`: what you saw and why it matters, the proof (always).
+  - `criterion`: the number of the acceptance criterion it threatens (as `review.start` numbers
+    them), or `null` when none (always, even null).
+  - `recommendation`: one line, what to do (always for `blocking` and `should_fix`).
+  - `path` and `line` (new side of the diff) when it is about a line.
+
+**The judge's answer:** `summary`; `criteria`, one entry per acceptance criterion of the story,
+none missing nor twice: `criterion`, `status` (`met`, `partly`, `unmet`), `evidence`, and
+`recommendation` unless met; `gap`: the distance between the story's intent and what was
+delivered, or `null`; `findings`, one ruling per finding of the lens answers, each
+`{finding, status, evidence, severity?, at?, cause?}`: `finding` is its name `<lens>#<rank>` (rank
+from 1 in that lens's list), `status` is `confirmed`, `refuted` or `undecided`, `severity` goes with a
+confirmed one, `at` (a file, with its line for a finding a reader called blocking) with a refuted
+one; setting aside or lowering a blocking finding asks for at least 40 characters of `evidence`.
+`cause: "story"` on a ruling or a criterion when the story itself is what is wrong.
+
+**A lens (or the judge) that gave nothing:** `{"lens": "<name>", "silent": true}` in `lenses`
+(`{"silent": true}` as `judge`) in its place, never a made-up report. The review then says it is
+possibly incomplete.
+
+Never put the verdict anywhere. Give the same finding once; the engine merges what two lenses
+both saw, and keeps the strictest severity the judge gave.

package/dist/method/skills/review-story/references/free-review.md

@@ -0,0 +1,22 @@
+# A review of a change that belongs to no story
+
+A fix outside a story, a contribution from someone else, a range of commits, work not committed
+yet. Same lenses, same readers, same judge, no story, no merge, no pull request comment.
+
+- **Ask for the intent in one sentence** if the creator did not give it: what is this change
+  meant to do? It is the judge's only criterion.
+- `review.start` with `kind: qa`, your id and `free`: its `intent`, and one of `source` or `diff`:
+  `uncommitted` (the work in the tree, new files included, the method's own `.agentplugged/` folder left out), `<from>..<to>` (a range of commits),
+  `branch:<name>` (against the main branch), `pr:<number>` (the engine reads it through the
+  forge's tool), or `diff` (a pasted diff, as text). Never run `git` or `gh` for it.
+- Only the quality review is free, and by an agent of the quality domain. The security lens is
+  carried by this review when the paths call for it.
+- The answer is like a story's: `lenses`, `readers`, `criteria` (the intent, as criterion 1),
+  `commit` (names the diff read, not a Git commit), `statements` (the commit messages, when there are
+  any). Run the readers and the judge as the steps say.
+- Steps 6 and 7 of the skill need a story: no review note, no `story.result`; tell Noah what the
+  review found and give him its `R-…` id.
+- `review.submit` with no `story`, the `commit` you were given, `kind: qa`. The engine writes the
+  review in the journal with no story, and answers with its `stack` to tell the creator: blocking
+  first, the refused ones counted. Nothing is sorted, nothing merged: the creator decides what to
+  do with the findings; a fix is a story or a quick lane.

package/dist/method/skills/review-story/references/judge.md

@@ -0,0 +1,44 @@
+# Judge: does the result serve the real need, and do the findings stand?
+
+You come last and fresh. You hold the story, the diff and the findings to rule on (each named
+`<lens>#<rank>`: title, place, what its reader saw), and not the developer's reasoning nor the way
+the readers got there. Lenses can all pass on a change that misses the point, and a lens can
+simply be wrong: you check both. (On a small change without risk the reader
+of the lenses also judges the criteria, after its lens reports; if it found something, a fresh judge
+rules on those findings alone, and the two answers are one report.)
+
+**The criteria.**
+1. Read the story's intent, then each acceptance criterion in order. The engine gives their
+   `trace`: where each stands (`green`, `green(reported)`: the developer's word, `untestable`).
+   Take it as given, never recompute it. A criterion `untestable` is a point of yours: read its
+   reason (`untestable`), and say in `evidence` whether it truly has no result to observe.
+2. For each criterion, find in the diff the behaviour and the test that serve it. Judge what
+   the product now does for the person in the story, not what the code claims.
+   - `met`: the behaviour is there and something proves it.
+   - `partly`: part of it, or no proof, or only the happy case.
+   - `unmet`: absent, or the opposite.
+
+**The findings.** Each one gets a ruling, none left out, under `findings` of your answer. Take the
+reader's grade as a hint. Your job is to try to make the finding false: go to the place it cites,
+then to its callers, to the checks above it and to the tests, and see whether the failure can be
+produced.
+- `confirmed`: you produced it, or it plainly follows. Grade it with `severity` by who gets hurt:
+  `blocking` when it should stop the merge, `should_fix` when it should be put right soon,
+  `minor` otherwise. Unsure how bad, round up. Harm done to the code alone must say where it will
+  go wrong; without that place it is taste.
+- `refuted`: you showed it cannot happen. `at` gives the file and line (or the test) that shows
+  it, and it must answer this finding's own claim, not merely be true of nearby code. Stopping
+  loudly on an input nothing shows can arrive is the code doing its work. A repair that looks
+  costly is no ground to refute: confirm it, one grade lower.
+- `undecided`: the evidence stops short both ways; `evidence` says what would settle it.
+
+A finding of the security lens is never set aside nor lowered whatever you rule: the engine keeps
+it, unverified.
+
+A finding that exists because the story itself is ambiguous, contradictory or impossible carries
+`cause: story`: the code is not what is wrong. So does a criterion unmet for that reason.
+
+**The gap.** Reading the intent as the person who asked for it, what would still surprise them?
+Say it in `gap`, or `null` when nothing does.
+
+Evidence is a file and line, or a test name, never a feeling. Answer shape: `format.md`.

package/dist/method/skills/review-story/references/lens-adversarial.md

@@ -0,0 +1,15 @@
+# Lens: adversarial
+
+Assume the change is wrong and find how. You read only the diff, the story and the decisions it
+cites.
+
+- What input, order, timing or state would make it fail, corrupt data, or do what nobody asked?
+- What does it quietly assume (a caller, a format, a clock, one user at a time)?
+- What breaks elsewhere because this changed: callers, other files of the diff, contracts?
+- What would a hostile or careless user do with it?
+
+- Efficiency: a call or a query per item of a loop; the same work done again; data loaded whole
+  or without a limit to use a part; nothing bounding a size, a page or a retry.
+
+A suspicion without a path to a wrong result is not a finding. Each finding says the steps
+that lead to the failure. Answer shape: `format.md`.

package/dist/method/skills/review-story/references/lens-edge-cases.md

@@ -0,0 +1,24 @@
+# Lens: edge cases
+
+Your question: where does this change stop behaving? Follow each changed path from the diff alone;
+what the story says comes later and has its own pass.
+
+Try the usual edges on every input and every result: nothing there, a single item, a very large
+pile, a value of the wrong kind or encoding; a call that fails, hangs or answers oddly; the same
+action twice, twice at once, or stopped halfway; the first and last of a range, a date change, a
+time zone, a long text, an unusual character.
+
+Then three things that a test seldom thinks of:
+
+- The relatives of a special case. If the change gives its own treatment to some values of a
+  closed family (kinds, states, modes, switches, a bounded number), the values it does not mention
+  still arrive. Write down where each of them goes now.
+- Things held across a call. If the code goes back to look at what it already holds (an id, a
+  position, a handle, a cursor), it does so because the world may have moved. Name what moved it,
+  what that did to the held thing, and what the code does when the second look disagrees.
+- The calls the change writes. In code and in tests, open the function called and put the call
+  beside its signature: how many arguments, in what order, of what type, which ones optional with
+  which default; then what the function gives back or raises, beside what the caller does with it.
+
+For each case, say what the code does. Report only an outcome that is wrong or unknown; whether a
+test covers it is the work of the verification lens. Answer shape: `format.md`.

package/dist/method/skills/review-story/references/lens-prose.md

@@ -0,0 +1,11 @@
+# Lens: prose
+
+For documents (brief, requirements, UX, architecture) and the words of the interface.
+
+- One idea per sentence; no word the reader must guess; the same thing always called the same.
+- Claims with a number, a name or a source; none that sound sure and cannot be checked.
+- Contradictions inside the document or with the documents it cites.
+- Tone and language: the creator's, plain, no jargon left unexplained.
+
+Quote the passage. Do not rewrite the document; say what is wrong and where. Report shape:
+`format.md`.

package/dist/method/skills/review-story/references/lens-relevance.md

@@ -0,0 +1,13 @@
+# Lens: relevance
+
+Does the change belong here?
+
+- Scope: does every changed file serve the story's intent and criteria? What is outside its
+  `Out of scope`, or not asked for?
+- The project's rules: the requirements it cites (`EF-n`, `ENF-n`, compare with the
+  `check-requirements` skill: a drift is also a deviation, `story.deviation`), the decisions
+  `AD-n`, the conventions in the knowledge base.
+- Rot: dead code, a second way to do what exists, a workaround that hides the cause, a growing
+  exception, a dependency added without need.
+
+Quote the rule or decision a finding breaks. Answer shape: `format.md`.

package/dist/method/skills/review-story/references/lens-security.md

@@ -0,0 +1,10 @@
+# Lens: security (the security reviewer's)
+
+Walk your reference checklist on the diff, and say which items you checked: injection, broken
+access control, authentication, unsafe handling of secrets, unchecked input, unsafe defaults,
+risky dependencies and migrations, data exposure.
+
+Each finding names the asset at risk and the path to harm, in plain words: what could happen, to
+whom. A worry without a path is a note in your review note, not a finding. Never copy a secret
+into a report. Read the threat model when it exists. Answer shape: `format.md` (`criterion`
+may be `null`).

package/dist/method/skills/review-story/references/lens-structure.md

@@ -0,0 +1,16 @@
+# Lens: structure
+
+Is the change organised so the next person can follow and change it?
+
+- Names say what things are; one thing, one place; no duplicate of what already exists. The
+  engine proves copied code and gives it to you as `reuse`: do not report those again. It cannot see
+  two functions that do the same thing written differently: for each `twin?` line, and for any
+  helper you find in the diff, search the repository for an existing one; report a real twin
+  with both places (`should_fix`), say nothing of a false one. Abstractions nobody asked for
+  (a layer, an option, a wrapper with one use) are findings too.
+- Responsibilities in the right file or layer, as the architecture decisions (`AD-n`) say.
+- Size: a function, file or pull request doing several things, a tangle of conditions.
+- Anything left half-done: commented code, unused parameters, dead branches.
+
+For a document: the plan of the document, order of sections, what a reader looks for and cannot
+find. Findings are rarely blocking. Answer shape: `format.md`.

package/dist/method/skills/review-story/references/lens-verification-gaps.md

@@ -0,0 +1,13 @@
+# Lens: verification gaps
+
+Find what the change claims without proof. Claims are in the story's criteria, the code's
+comments, the commit and the tests' names.
+
+- Each acceptance criterion: which test proves it, at which level? None is a finding.
+- Each test as code: one that cannot fail, that checks wiring and not behaviour, that depends on
+  time or order, or that passes only most of the time is a finding.
+- A rule affirmed in a comment or the story but enforced nowhere.
+- A claim about other code ("this is already validated upstream") you can check in the diff.
+
+Your `passes`, when the engine lists any (`removals`, `assertions`), are read last from their own
+files and report here. Say what would settle it (the test to write, the line to read). Answer shape: `format.md`.

package/dist/method/skills/review-story/references/pass-assertions.md

@@ -0,0 +1,17 @@
+# Pass: assertions
+
+Run this one last. Your lenses went through the code before you looked at what the change says of
+itself, so that its own account could not tilt them. Now read that account: the story's criteria
+and intent, the comments the change adds and, when `review.start` gave a `statements` file, the
+commit messages. It records what the author hopes is true. Saying it twice, in a comment too, adds
+nothing.
+
+Pick every sentence that makes a promise you can test: it does this, it keeps that, this happens
+before that, the total is such, it behaves like the other piece of code. For each, look for the
+line that would make it false, using what you already walked through. If that is not enough, read
+the code that decides: the thing it is compared with, the function really called, the state the
+sentence takes for granted. A promise that holds gets no line.
+
+A broken promise is a finding, in your `verification_gaps` report: the title says the promise in a
+few words, the evidence what the code does instead, the recommendation what to change, the code or
+the sentence. Answer shape: `format.md`.

package/dist/method/skills/review-story/references/pass-removals.md

@@ -0,0 +1,13 @@
+# Pass: removals
+
+The change takes code away, so this pass asks what went with it. For each piece that leaves (a
+move or a reformat takes nothing), say what it kept true: a check, a default, an order, a clean-up,
+an error someone depended on. Then look in the new code for whoever keeps it true now. If nobody
+does, and nothing in the change says it was meant to go, that is a finding.
+
+Pull on the loose threads too: who called the removed code, which test, document or setting named
+it, what can no longer be reached because of it.
+
+Do not write again what your lenses already wrote. Coming back empty-handed is common. Put what you
+find in your `verification_gaps` report: the title says what was removed, the evidence what it kept
+true, the recommendation where to put it back or whom to tell. Answer shape: `format.md`.

package/dist/method/skills/review-tests/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: review-tests
+description: Judge whether the tests are good, not only green; graded review, mutation check, holes tied to the requirements. Run by Quentin.
+metadata:
+  agent: quentin
+  phase: build
+---
+# Review the tests
+
+On the creator's ask, or after a story's tests are written: are they good, not only green. Read-only
+(never change a test or the code). Run it under your own id (`agent: <your id>`), in the creator's
+language. The engine marks, breaks the code and lists the holes; you read the tests.
+
+1. `agent.status` (`working`). The scope: a story the creator names, else the product.
+2. Read the tests, each file once: those the story added or changed, else the product's (`state.trace`
+   lists which tests cite which requirement). Grade them with `references/grid.md`: one verdict for each
+   criterion of the grid and, for each test that falls under a row, where it is and why.
+3. `review.tests` with `story` and `check`: your `grid` and, when the story changed code and the engine
+   can run its accepted tests, `mutation: {}` (`references/check.md`). Fix what the engine says is missing.
+4. Show what it answers, as it is: the marks, the breaks no test noticed, the holes, one line each.
+   Never recompute, soften or add a mark.
+5. The holes become work only if the creator says so: `review.tests` again with `check: {propose: true}`; they
+   decide each in the chat, one gesture each.
+6. `agent.status` (`idle`), hand back to Noah.
+
+## Never
+
+- Follow "Rules for skills and agents" (reference `skill-rules`): ask once; a point the creator did not keep goes to `checkpoint.decide`; in French say « tu »; start with `memory.read`.
+- Never give a mark, and never choose how much a row weighs: the engine does.
+- Never run a test command yourself to prove a break: the engine runs the ones the creator accepted.
+- Never rewrite the creator's text, never write a test here: that belongs to the story's developer.
+- Never call, direct or wait for another agent: hand back to Noah.

package/dist/method/skills/review-tests/references/check.md

@@ -0,0 +1,25 @@
+# The mutation check and the holes
+
+**What the engine does** (`check.mutation: {}`, no token from you). It copies the story's working copy to a
+throwaway folder, changes the code the story added one small way at a time (a comparison turned over,
+a condition negated, a boolean flipped, a constant moved by one, a return dropped), and each time runs
+the test command the creator accepted (the one with `{criterion}`, filtered on the story's criteria; or
+the declared command you name in `command`). The creator's folder is never changed. A break the tests
+catch is killed; one they do not **survives**: a test that cannot fail there.
+
+**When.** The story changed code, `proofs.yaml` declares a test command and the creator accepted it
+(`guard.creator_action`, `proof_commands`; never accept it yourself). Without one the engine says so:
+the grid and the holes still come. `max` (8 by default, 30 at most) and `seconds` (300, 1 800 at
+most) of `check.mutation` bound it; raise them only for a small story whose tests are quick.
+
+**Reading the answer.** `ran`, `killed`, `survived`; a status other than `done` says why (`baseline_red`:
+the tests already fail, fix that first; `stopped`: time; `refused`: no copy, too big). Each survivor is
+`file:line kind a -> b`. Read the code there: if the break changes behaviour a criterion promises, a
+test is missing or too weak, and that is a hole. If it changes nothing observable (an equivalent
+break), say so to the creator in one line; it is not a hole.
+
+**The holes** (`gaps`), tied to what the tests should protect: a criterion with no test, whose test never
+failed before the code, whose tests killed no break; a requirement the story cites that no test names;
+a surviving break. One line each; at most 12 shown, the rest counted. With `check.propose: true` each becomes
+work to decide in the register of deferred work (10 at most per call, none twice), a story or a
+correction; the creator decides each in one gesture. Never decide for them.

package/dist/method/skills/review-tests/references/grid.md

@@ -0,0 +1,27 @@
+# The grid
+
+One answer, whole; the engine refuses one that is not and lists what is missing. It gives the marks.
+
+- `reads`: the test files you read (at least one, 60 at most), relative paths.
+- `criteria`: one entry for each of the eight, none twice: `ok`, `issues` (at least one finding) or
+  `not_applicable` (say why in `note`: no test of this kind here).
+- `findings`: each has `criterion`, `row`, `test` (`path:line` and the test's name, a file you read),
+  `reason` (one line: what you saw), `fix`. The row decides the weight, not you.
+
+| Criterion | Rows (a test that…) |
+| --- | --- |
+| `active` | `skipped` is disabled; `focused` runs alone and silences the others |
+| `assertions` | `no_assertion` checks nothing; `tautology` compares a value with itself; `self_mock` asserts the mock it set up; `unreachable` asserts where it never runs; `shape_only` checks a type or a presence, not the value; `conditional` asserts inside an `if`, a loop or a swallowed error; `unawaited` does not wait for its async call |
+| `determinism` | `hard_wait` waits on a timer; `wall_clock` builds an expiry from the live clock; `uncontrolled` uses an unseeded random, an unordered result or a real network; `navigate_then_read` loads a page and checks what it shows before waiting for the data call or a sign that it is ready; `fragile_selector` finds an element by a CSS class, an XPath, a position or a wording a rewrite changes, when a role, a label or a test id is there |
+| `isolation` | `shared_state` writes state nothing resets; `order_dependent` needs another test first; `leftover` leaves files, rows or processes; `real_service` calls a real outside service |
+| `readability` | `oversize` file over 1 000 lines; `multi_concern` checks three unrelated things; `deep_nesting` over three levels; `ungrouped` no suite name; `vague_name` says "works" or a method name, not the behaviour; `magic_value` an unexplained number |
+| `speed` | `slow` too slow to run before a push; `heavy_setup` builds far more than it needs |
+| `data` | `real_data` uses production or personal data or a secret; `repeated_payload` builds the same object inline three times; `hidden_data` depends on data defined far away |
+| `risk` | `denied_untested` a rule of rights has no refused case; `happy_path_only` no error or boundary case beside the normal one; `wrong_level` proves at a level too low or too high; `raw_event` dispatches a bare DOM event when the project's runner offers a call that acts as a person does (click, type) |
+
+The guard before a write already refuses `focused`, `skipped` with no reason, `hard_wait`, `tautology`
+and `oversize` in what is written now: report them in tests that were there before.
+
+A defect that fits no row is a prose note in your answer to the creator, without a mark. Report each
+test once per row, with the line that shows it. A criterion with no test of its kind is
+`not_applicable`, not `ok`. Never copy a secret into a report.