@roomi-fields/grillhouse 0.0.0-stage → 0.23.1

package/skills/release/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: release
+description: Automates the complete release process for npm packages. This skill should be used when the user requests to publish a new version, bump version numbers, sync versions across files, update changelog, build, tag, and publish to npm and GitHub.
+---
+
+# Release Management Skill
+
+## Overview
+
+This skill automates the complete release workflow for npm packages, ensuring consistent versioning, changelog updates, and proper publication to npm and GitHub.
+
+## Project Structure
+
+Files that may need version updates:
+- `package.json` - Source of truth for version (ALWAYS update first)
+- `README.md` - Version badges, installation commands
+- `CHANGELOG.md` - Release history
+
+## Pre-Release Checklist
+
+Before starting a release:
+1. Ensure all tests pass: `npm test`
+2. Ensure code is formatted: `npm run format:check`
+3. Ensure linting passes: `npm run lint`
+4. Ensure build succeeds: `npm run build`
+5. Ensure working directory is clean: `git status`
+6. Ensure you're on the main branch: `git branch --show-current`
+
+## Release Workflow
+
+### 1. Determine Version Bump
+
+Follow semantic versioning (SemVer):
+- **MAJOR** (x.0.0): Breaking changes, incompatible API changes
+- **MINOR** (0.x.0): New features, backward compatible
+- **PATCH** (0.0.x): Bug fixes, backward compatible
+
+### 2. Update Version in package.json
+
+```bash
+# For patch release
+npm version patch --no-git-tag-version
+
+# For minor release
+npm version minor --no-git-tag-version
+
+# For major release
+npm version major --no-git-tag-version
+```
+
+### 3. Update CHANGELOG.md
+
+Add a new section at the top of CHANGELOG.md:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New features
+
+### Changed
+- Changes in existing functionality
+
+### Fixed
+- Bug fixes
+
+### Removed
+- Removed features
+```
+
+### 4. Update Version References
+
+Search and update version strings in:
+- README.md (installation commands, badges)
+- Any hardcoded version strings in source code
+
+### 5. Build and Test
+
+```bash
+npm run build
+npm test
+```
+
+### 6. Commit and Tag
+
+```bash
+git add package.json package-lock.json CHANGELOG.md README.md   # the files this release changed, named
+git commit -m "chore: release vX.Y.Z"
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+```
+
+### 7. Push to GitHub
+
+```bash
+git push origin HEAD
+git push origin vX.Y.Z
+```
+
+### 8. Publish to npm
+
+```bash
+npm publish --access public
+```
+
+### 9. Create GitHub Release
+
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z" --notes-from-tag
+```
+
+## Troubleshooting
+
+### npm publish fails
+- Check you're logged in: `npm whoami`
+- Check package name is available
+- Verify you have publish rights to the scope
+
+### Tag already exists
+- Delete local tag: `git tag -d vX.Y.Z`
+- Delete remote tag: `git push origin :refs/tags/vX.Y.Z`
+
+### Version mismatch
+- Always update package.json first
+- Use the version sync script to update all references
+
+## Scripts
+
+### update-version.cjs
+
+Use this script to automatically update version references across the project:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/release/scripts/update-version.cjs"
+```

package/skills/release/scripts/update-version.cjs

@@ -0,0 +1,92 @@
+/**
+ * Version Update Script
+ *
+ * Automatically updates version strings across the project.
+ * Reads the version from package.json and updates all configured files.
+ *
+ * Usage:
+ *   node <the plugin grillhouse>/skills/release/scripts/update-version.cjs
+ *
+ * Customize the FILES_TO_UPDATE array for your project structure.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read version from package.json (source of truth)
+const packageJsonPath = path.join(__dirname, '..', '..', '..', '..', 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+const version = packageJson.version;
+
+console.log(`Updating version references to: ${version}`);
+
+/**
+ * Files to update with version patterns
+ *
+ * Each entry has:
+ * - file: relative path from project root
+ * - patterns: array of { search: RegExp, replace: string template }
+ *
+ * In replace strings, use $VERSION as placeholder for the version number
+ */
+const FILES_TO_UPDATE = [
+  {
+    file: 'README.md',
+    patterns: [
+      // npm install command with version
+      {
+        search: /@your-scope\/project-name@[\d.]+/g,
+        replace: '@your-scope/project-name@$VERSION',
+      },
+      // Version badge
+      {
+        search: /version-[\d.]+-blue/g,
+        replace: 'version-$VERSION-blue',
+      },
+    ],
+  },
+  // Add more files as needed for your project
+  // {
+  //   file: 'src/config.ts',
+  //   patterns: [
+  //     {
+  //       search: /VERSION\s*=\s*['"][\d.]+['"]/g,
+  //       replace: 'VERSION = \'$VERSION\'',
+  //     },
+  //   ],
+  // },
+];
+
+// Process each file
+const projectRoot = path.join(__dirname, '..', '..', '..', '..');
+
+for (const config of FILES_TO_UPDATE) {
+  const filePath = path.join(projectRoot, config.file);
+
+  if (!fs.existsSync(filePath)) {
+    console.log(`Skipping ${config.file} (file not found)`);
+    continue;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8');
+  let updated = false;
+
+  for (const pattern of config.patterns) {
+    const newContent = content.replace(pattern.search, pattern.replace.replace('$VERSION', version));
+
+    if (newContent !== content) {
+      content = newContent;
+      updated = true;
+    }
+  }
+
+  if (updated) {
+    fs.writeFileSync(filePath, content, 'utf8');
+    console.log(`Updated: ${config.file}`);
+  } else {
+    console.log(`No changes: ${config.file}`);
+  }
+}
+
+console.log('\nVersion update complete!');
+console.log(`\nDon't forget to update CHANGELOG.md manually with release notes.`);

package/skills/relecteur/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: relecteur
+description: "Le relecteur : relire en adversaire le lot d'un ticket (tests et code) avant son commit. Chargé par l'agent relecteur, que le circuit du ticket lance après sa passe finale ; rend un verdict, que le circuit écrit au ticket, sans rien écrire dans le code."
+---
+
+# Relecteur — relire un lot avant son commit
+
+Tu relis le lot d'un ticket : les tests (testwriter) et le code (développeur), livrés dans la même
+copie. Tu ne corriges rien : ton verdict est ta fiche, que le circuit du ticket
+(`packages/grillhouse/scripts/circuit.mjs`) lit et écrit au ticket : sur `ACCEPTÉ`, il commite le lot ; sur `RENDU`, il
+relance l'agent que nomme chaque constat bloquant.
+
+## Au démarrage
+
+1. Lis le `CADRE.md` et l'`ARCHITECTURE.md` des composants que le lot touche. `${CLAUDE_PLUGIN_ROOT}/METACADRE.md` dit
+   les intentions du cadre : tu le lis quand un lot semble tenir la lettre d'une règle contre son
+   but.
+2. Lis les fichiers du lot que ta consigne nomme, dans la copie du ticket : chacun par
+   `git -C <copie> diff HEAD -- <fichier>`, un fichier neuf en entier. Ne lis pas encore les critères : ta
+   consigne n'en porte aucun, et le fichier d'affirmations qu'elle nomme attend l'étape des
+   affirmations ; tes deux premières passes partent du code seul. Le ticket ne se lit pas par bd,
+   que ta séance n'ouvre pas : ta consigne et ce fichier le portent. Tu juges sur le plan, la
+   description que ce fichier porte, où une décision du responsable est versée ; tu ne cherches
+   aucune décision dans les commentaires. Ainsi le récit du ticket n'oriente pas ta
+   lecture.
+3. Tes commandes s'écrivent sous la forme que nomme cette compétence, chacune seule, depuis la
+   copie, sans préfixe ni redirection hors d'elle. La copie se lit par git :
+   `git -C <copie> status --short`, `git -C <copie> diff HEAD -- <fichier>`,
+   `git -C <copie> log --oneline -n <n>`, `git -C <copie> ls-files <chemin>`,
+   `git -C <copie> grep -n <motif> -- <chemin>`. Ainsi chaque commande passe tes droits.
+
+## La relecture bornée
+
+Quand ta consigne porte « LA RELECTURE D'AVANT » (un `RENDU` d'avant), tu relis la seule
+différence du lot depuis elle, comme Gerrit fait relire la différence entre deux jeux de
+correctifs : le circuit garde le lot que chaque relecture a lu, et ta consigne nomme la commande
+de la différence (`git diff <lot d'avant> <lot d'aujourd'hui>`, dans la copie), ses fichiers et
+les constats d'avant.
+
+1. Chaque constat d'avant se juge levé ou non, sa preuve tirée de la différence, dans `suivi`
+   (son titre, `levé` ou `non levé`, la preuve). Un constat non levé revient dans `constats`,
+   bloquant, au même destinataire.
+2. Les six passes portent sur la différence : un constat bloquant neuf que le correctif crée,
+   dans les lignes qu'il change, rend le lot.
+3. Un défaut hors de la différence et des constats d'avant est une remarque, et ne rend pas le
+   lot. Ainsi la boucle des relectures ne s'étend jamais, et chaque tour converge.
+
+Tu joues toujours toutes les gardes sur la copie. Sans « LA RELECTURE D'AVANT », tu relis le lot
+entier.
+
+## Les six passes
+
+Chaque passe suit son fichier de `references/` à la lettre, dans cet ordre.
+
+1. **Les cas limites** (`references/edge-case-hunter.md`) : chaque chemin du diff qui manque de
+   traitement. Pour l'étape des affirmations, le fichier d'affirmations est celui que ta consigne
+   nomme (« LE FICHIER D'AFFIRMATIONS »), la description du ticket que le circuit y a écrite.
+2. **Les trous de vérification** (`references/verification-gap.md`) : chaque comportement changé
+   qu'un test ne protège pas réellement.
+3. **Le cadre** : chaque règle du `CADRE.md`, de l'architecture et de la spécification que le
+   ticket cite est tenue ; le code traite la classe de problèmes, à l'adresse que nomme la section
+   « Architecture », et non le seul cas signalé. Un lot rend aussi sur une forme recopiée, un mot
+   que le domaine ne connaît pas, un chemin que le plan écarte, un document du responsable
+   changé sans son mot, ou un banc qui ne mesure pas le cas de son ticket sur l'entrée que le cas
+   nomme. Ainsi le correctif va du plus large vers le plus spécifique.
+4. **Les entrées** : chaque fonction de l'interface du composant reçoit les types que la section
+   « Reçoit » du cadre nomme, jamais une table ou un registre entier. Les faits que le composant
+   reçoit de ses fournisseurs se lisent par `npx grillhouse index-interfaces --publie <composant>`
+   (depuis la copie) : chacun arrive tel que son fournisseur le publie, et un calcul du lot qui en
+   refait un est un constat. Ainsi le composant ne peut pas refaire le calcul d'un voisin.
+5. **L'existant** : cette notion existe-t-elle déjà ailleurs dans le projet, dans ce composant ou un
+   autre ? Tu cherches dans tout le dépôt, par l'index (`rtfm_search`, `codegraph explore`). Ainsi le produit garde un seul calcul par notion.
+6. **Les critères** : chaque critère d'acceptation du ticket a son test, qui échoue sans le code ;
+   le code ne fait rien que les critères ne disent. Tu lances les tests par `npm test --
+<fichiers>` (chemins depuis la racine du dépôt) ; une sortie relue du cache de Turborepo (« cache hit, replaying logs ») vaut un
+   lancement, tu ne la rejoues pas pour la croire. Un test mis en quarantaine (`it.skip`,
+   `it.fails`) nomme le ticket qui le corrige, sinon le lot est rendu. Un banc de temps ou un test
+   de nuit du lot se joue en nommant son fichier ; son « à repasser » (code 75) se rejoue au
+   repos et ne vaut jamais un vert. Tu joues aussi toutes les
+   gardes sur la copie, par `npm run verifier -- --gardes` (celles du cadre et celles du projet) ;
+   une garde rouge rend le lot, sa sortie en preuve. Ainsi le lot fait ce qui a été décidé, et
+   seulement cela, et un refus des gardes se voit avant l'intégration.
+
+**Tu attends au premier plan ce que tu lances** : ta séance n'a aucune tâche de fond, et elle finit
+avec ta fiche. Ainsi le circuit reprend dès ta fiche rendue.
+
+## Le verdict
+
+Une passe en trouve, tu cherches une entrée voisine qui casse le correctif : un constat se prouve
+par son exemple. Ainsi le verdict repose sur des pièces.
+
+Ton verdict est ta fiche, que ton schéma décrit et qui finit ta séance : `verdict` `ACCEPTÉ`
+ou `RENDU`, et chaque constat de `constats`, son adresse (`titre`), son genre (`genre`) et sa
+preuve (`corps`). Le circuit l'écrit au ticket, sur plusieurs lignes, son premier mot le verdict,
+que le script d'intégration et le tableau lisent, puis tes remarques. Tu n'écris rien au ticket
+toi-même.
+
+**Un constat bloquant tient un critère du plan ou une règle du cadre**, que son champ `regle`
+nomme (« critère 2 », ou le document et sa règle) ; tout autre constat est une remarque (`genre`
+`remarque`), que le circuit écrit au ticket sans relancer personne. Seuls les constats bloquants
+rendent le lot : `RENDU` en porte au moins un, `ACCEPTÉ` aucun, et ton schéma refuse une autre
+fiche. Un constat répond à un besoin réel de l'usage actuel ; un cas seulement possible n'en
+devient pas un constat bloquant, comme il ne devient pas un critère du ticket (un paquet gelé qui
+changerait, une entrée qu'aucun appelant ne donne). Ainsi seul ce que le ticket ou le cadre
+exige rend le lot, comme une relecture mûre n'exige rien dont le changement n'a pas besoin.
+
+**Chaque constat bloquant nomme son destinataire** : `role` `testwriter` quand le constat vise un
+test qui manque ou qui ne mord pas, `developpeur` quand il vise le code, et `composant` l'un de
+ceux du titre (son chemin ou le nom de son paquet), celui où la correction s'écrit. Le circuit relance ces
+agents depuis le premier composant nommé, le constat pour rapport. Un constat qui met en cause le
+critère lui-même, et non le lot, porte à la place `critere_en_cause` (son numéro) : le circuit
+s'arrête, et le régulateur tranche. Ainsi chaque constat arrive à l'agent qui le corrige.
+
+```json
+{
+  "verdict": "RENDU",
+  "constats": [
+    {
+      "titre": "packages/forms/src/index.mjs:12",
+      "genre": "bloquant",
+      "regle": "critère 2",
+      "role": "developpeur",
+      "composant": "000-forms",
+      "corps": "Preuve : mesure(0) rend NaN."
+    }
+  ]
+}
+```
+
+Une remarque qui sort des critères du ticket entre dans `decouvertes` (son sujet, son exemple et
+son adresse) : le circuit la consigne dans un ticket fermé sous le ticket. Tu ne cherches ni ne
+crées aucun ticket : ta fiche suffit. Ainsi le ticket garde ses critères, et la remarque attend le
+mot du responsable.
+
+Tu relis le message de commit comme le code : le circuit l'écrit une fois, depuis l'état final,
+du titre du ticket, des critères du plan et des `ecarts` des fiches, chaque `sujet` une fois, de la
+dernière fiche qui le porte. Un écart que le commit doit nommer (un écart voulu, une référence
+changée) entre dans `ecarts`, sous son sujet, avec sa cause ; un sujet qu'une fiche d'avant porte
+se reprend tel quel, et ta valeur, mesurée sur l'état final, remplace la sienne ; pour un critère
+qui exige qu'un écart se nomme au commit,
+l'écart entre dans tes `ecarts`, jamais dans une remarque. Ainsi le commit nomme chaque écart que
+le ticket exige.
+
+Tu ranges chaque mot qu'une garde de vocabulaire du projet signale sur une ligne que le lot touche,
+même un mot qui y était déjà. Un usage légitime (un champ homonyme, un nom de l'API) entre au
+registre des exceptions du projet, dans le lot, par un constat adressé à l'agent qui l'écrit ;
+seul un vrai mot du langage écrit en dur monte au responsable, par ta `question` (le mot, sa ligne,
+ta recommandation) : le circuit s'arrête avant le commit. Le `CONTEXTE` de ta consigne porte la
+réponse à une question d'avant. Ainsi chaque mot signalé se range dans le lot, et seul le
+responsable tranche le langage.
+
+Ta fiche rendue, tu t'arrêtes : le circuit la recueille à la fin de ta séance.

package/skills/relecteur/references/LICENSE-MIT

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2025 BMad Code, LLC
+
+This project incorporates contributions from the open source community.
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+BMad™, BMad Method™, and BMad Core™ are trademarks of BMad Code, LLC, covering all
+casings and variations (including BMAD, bmad, BMadMethod, BMAD-METHOD, etc.). The use of
+these trademarks in this software does not grant any rights to use the trademarks
+for any other purpose. See [TRADEMARK.md](TRADEMARK.md) for detailed guidelines.

package/skills/relecteur/references/SOURCE.md

@@ -0,0 +1,8 @@
+# Provenance
+
+`edge-case-hunter.md`, `deletion-check.md`, `claims-check.md` and `verification-gap.md` come from
+https://github.com/bmad-code-org/BMAD-METHOD (commit bda3c5929f672019b90f39a3ea27259d35d00974,
+`skills/bmad-build/`), under the MIT licence reproduced in `LICENSE-MIT`.
+
+One change: `claims-check.md` reads the ticket's `## Architecture` and `## Critères d'acceptation` sections, where
+the original reads a plan's `## Intent` and `## Tasks & Acceptance`.

package/skills/relecteur/references/claims-check.md

@@ -0,0 +1,14 @@
+# Claims Check
+
+Final pass for the Edge Case Hunter. Read the claims file named in the message that launched you now, for the first time; the path tracing is finished and the claims cannot steer it retroactively.
+
+It is the plan the change was built from. Read only its `## Architecture` and `## Critères d'acceptation` sections — the claims live there; ignore the rest of the file. The plan is the change's own account of itself: testimony, not evidence — a claim repeated in a code comment is still the same claim, not confirmation. Extract each checkable claim — what the change does, what it preserves, ordering, arithmetic, and parity with existing code ("exactly as X does") — then try to falsify each one against the code you have already traced. Where your trace is not enough to decide, read the code that decides it: the compared-to function, the actual callee, the state the claim assumes.
+
+Append one finding per falsified claim to the same JSON array, with the four standard fields plus:
+
+- `kind`: `"claim"`
+- `confidence`: `"high"`, `"medium"`, or `"low"`
+
+For a claim finding the standard fields read as: `location` = where the code contradicts the claim; `trigger_condition` = the claim, quoted or tightly paraphrased; `guard_snippet` = what the code actually does; `potential_consequence` = what goes wrong for someone who believed the claim.
+
+Verified claims produce nothing. Add nothing if nothing is falsified.

package/skills/relecteur/references/deletion-check.md

@@ -0,0 +1,14 @@
+# Deletion Check
+
+Secondary pass for the Edge Case Hunter — runs only when the diff removed meaningful code. Subordinate to the edge-case pass; findings are usually few or none.
+
+For each chunk of removed or replaced code (ignore pure renames and whitespace), ask: did it carry behavior or a contract that the change neither re-established nor intentionally retired? Add a finding for any resulting regression, orphaned reference, or newly-dead code. Skip anything already covered by your edge-case findings.
+
+Append each finding to the same JSON array as the edge-case findings, with the four standard fields plus:
+
+- `kind`: `"deletion"`
+- `confidence`: `"high"`, `"medium"`, or `"low"` — these are inferences; rate them
+
+For a deletion finding the standard fields read as: `location` = the removed item; `trigger_condition` = the behavior or contract it enforced; `guard_snippet` = where or how to re-establish it; `potential_consequence` = the regression or orphan.
+
+Add nothing if nothing qualifies.

package/skills/relecteur/references/edge-case-hunter.md

@@ -0,0 +1,80 @@
+# Edge Case Hunter Review
+
+**Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
+When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
+When no diff is provided (full file or function), treat the entire provided content as the scope.
+Ignore the rest of the codebase unless the provided content explicitly references external functions.
+A brief secondary deletion check runs as Step 4 when the diff removes code.
+A claims check runs as Step 5.
+
+**Inputs:**
+- **content** — Content to review, or a path to read it from: diff, full file, or function
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis
+- **claims_file** — Path to the plan this change was built from. Do NOT read it before Step 5: the path tracing in Steps 2–3 must finish before the claims are seen.
+
+**MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.**
+
+**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler. Do not assign severity labels, rankings, or priority levels.**
+
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Take the content to review from the parent message that launched you — inline, or by reading the file it points to (never from this instruction file)
+- If no content is supplied, or it is empty, unreadable, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+- Identify content type (diff, full file, or function) to determine scope rules
+
+### Step 2: Exhaustive Path Analysis
+
+**Walk every branching path and boundary condition within scope — report only unhandled ones.**
+
+- If `also_consider` input was provided, incorporate those areas into the analysis
+- Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Consider implicit branches: the diff special-cases or changes the handling of one or more members of a fixed set of values — enums, status codes, sentinels, type tags, flags, value ranges. The rest of the set is implicit branches (e.g. the diff changes the `RED` and `YELLOW` cases of a `RED`/`YELLOW`/`GREEN` enum; `GREEN` is the implicit branch)
+- Consider handle lifetime: when the changed code re-checks, re-fetches, or re-validates something it already held — a handle, index, id, pointer — the re-check exists because an intervening call can invalidate it. Identify that call, what it does to the thing held, and what the changed code silently skips when the re-check fails
+- For each call site the diff adds or changes — in test files as well as production code — read the callee's declaration and check the call against it: argument count, order, types, and defaults. Report any mismatch
+- For each path: determine whether the content handles it
+- Collect only the unhandled paths as findings — discard handled ones silently
+
+### Step 3: Validate Completeness
+
+- Revisit every edge class from Step 2 — e.g., missing else/default, null/empty inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Add any newly found unhandled paths to findings; discard confirmed-handled ones
+
+### Step 4: Deletion Check
+
+If the diff removed or replaced meaningful code (ignore pure renames and whitespace): load `references/deletion-check.md` and follow it.
+
+### Step 5: Claims Check
+
+Load `references/claims-check.md` and follow it.
+
+### Step 6: Present Findings
+
+Output all findings as a single JSON array following the Output Format specification exactly.
+
+
+## OUTPUT FORMAT
+
+Return ONLY a valid JSON array of objects. Each edge-case finding contains exactly these four fields:
+
+```json
+[{
+  "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)",
+  "trigger_condition": "one-line description (max 15 words)",
+  "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)",
+  "potential_consequence": "what could actually go wrong (max 15 words)"
+}]
+```
+
+No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when nothing is found. Deletion findings from Step 4 and claim findings from Step 5, if any, go in the same array with the extra fields defined in `references/deletion-check.md` and `references/claims-check.md`.
+
+
+## HALT CONDITIONS
+
+- If no content is supplied, or it is empty, unreadable, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+
+## CONTENT SOURCE
+
+"Review content:" in the message that launched you gives the content itself or a path to read it from. Read the file when it is a path; either way that is the content under review, and this instruction file never is.

package/skills/relecteur/references/verification-gap.md

@@ -0,0 +1,113 @@
+# Verification Gap Review
+
+**Goal:** Find changed behavior that could break without reliable verification catching it. Ask one question — "if the behavior this change is supposed to produce broke where it's actually used, would verification fail?" Do not hunt for correctness bugs, but report genuine problems you notice while tracing verification.
+
+The main verification gap shapes are:
+
+1. **Regression gap:** the changed code regresses where it's used, and no test covering that use would fail.
+2. **Missing-adoption gap:** a place that should now use the new behavior doesn't; it handles the same case its own way, or not at all, and no test would flag the omission.
+3. **Broken-verification gap:** a test appears to cover the changed behavior, but would not actually protect it because it is skipped, flaky, not run in the normal verification path, or too weak to observe the regression.
+
+## Evidence Rules
+
+- Read a test before claiming what it covers, runs, asserts, or misses.
+- Before claiming no test exists, search the whole repo by the symbol under test and by import references; expected file locations are not enough.
+- Never assert what you did not verify. If a finding cannot be grounded, drop it.
+- In a finding, say what you actually checked — "none of the tests I read cover this" — and show how far you looked. Say a test doesn't exist anywhere only when the symbol/import-reference search actually shows that.
+- Do not assign severity, confidence, priority, or ranking.
+
+## Review Sequence
+
+### Step 1: Screen for behavioral change
+
+Screen each part of the change separately. If a part is non-behavioral, skip it. Call a part non-behavioral only when the changed code does not alter return values, thrown errors, caller-visible side effects, or observable state (including iteration order and emitted messages). Once a part meets that test, move on; do not inspect callers or tests for extra confirmation.
+
+Common non-behavioral examples: formatting, comments, whitespace; pure renames; trivial getters/setters and pass-throughs; type-only or compiler-enforced changes with no runtime effect; etc.
+
+Only outcomes produced by deterministic code are worth automatically testing; tests are useless on static source text and brittle on LLM output. Skip those parts.
+
+If every part is skipped, output the clean result (see Output Format).
+
+### Step 2: Find the behavior that changed
+
+Identify what behavior changed compared to the previous version: output, side effect, branch, error path, schema/event shape, config default, validation/authorization rule, external contract, etc. If the change affects more than one behavior, handle each separately.
+
+Treat broad-impact changes as behavioral even when no single changed line looks important: dependency, toolchain, build/config, data-file, etc.
+
+### Step 3: Trace where that behavior is used
+
+Trace the changed behavior to the places that observe it. Start with direct callers and registered entry points (routes, commands, DI), contract consumers (schemas, events, APIs, database readers), and reverse-dependency info if already available.
+
+Follow a path only while the changed behavior is reachable and unverified. Stop when a test at that boundary would fail, the consumer does not observe the changed behavior, or the next hop is guesswork (dynamic dispatch, reflection, outside-repo consumers, etc.). Prefer the nearest observable boundary, often one to three hops away, especially across contract, integration, or service edges. If there are more than five similar consumers, group obvious repeats and check representative paths; expand only when a consumer observes the behavior differently.
+
+### Step 4: Qualify the consumer, then check its test
+
+For each consumer, name the smallest realistic regression this consumer would observe: invert the branch, drop the default, omit the field, return the old error code, skip the integration call, etc. This is the Demonstration. If no such regression exists, drop the path; untested downstream code is not a finding.
+
+A `Missing-adoption gap` qualifies not by the adoption failure alone but by a supersession signal: the change gives clear evidence the new behavior is meant to replace the local one — PR intent, naming or docs, a replaced sibling site, deleted duplicate logic, or a test defining the new rule — and the local site shares the same observable contract. Without a supersession signal and a shared observable contract, it is a refactor suggestion, not a verification-gap finding. Once both hold, check whether any test for that site would flag the non-adoption; missing coverage of the non-adoption is the gap itself, not a disqualifier.
+
+Find and read the relevant test. Ask whether the Demonstration would make an assertion fail.
+
+- If yes, the behavior is verified. No finding.
+- For a regression-style Demonstration: if no test runs the path, the test is skipped/flaky/not run normally, or the test runs the code without checking the changed result, report a `Regression gap` or `Broken-verification gap`.
+- For a qualifying Missing-adoption case: if none of the site tests you found assert it adopts the new behavior, report a `Missing-adoption gap`.
+
+A test counts only if it runs normally and an assertion observes the changed output, branch, or contract. These do not count: no execution; source-text assertions that match a file's wording instead of running it; success/no-throw/snapshot-only checks; mock/log-call checks; human-only checks; tests that mock away the integration; e2e tests that pass through without checking the changed output; stale assertions or fixtures.
+
+For example, `expect(x ?? DEFAULT).toBe(DEFAULT)` passes when `x` is missing.
+
+Common patterns:
+
+- **Caller-path gap** — helper test covers the branch, but caller values skip it.
+- **Contract drift** — payload/schema/event changes must be verified at the consumer.
+- **Migration compatibility** — tests only create new-format rows or fresh schemas.
+- **Phantom exception** — handled partial-failure path has no test.
+- **Missing-adoption gap** — sibling site should use the new rule/helper and does not.
+- **Removed verification** — deleted test or weakened assertion leaves behavior unpinned; removing a source-text assertion is not this, since it never counted.
+
+### Step 5: Confirm each finding is real
+
+Before writing a finding, re-open the specific tests or search results the finding relies on. Verify the Demonstration would not make any test you checked fail, or that the absence claim is backed by the symbol/import-reference search. Do not claim more than you verified; drop any finding you cannot ground.
+
+Explain why the test misses the bug using what the test sets up and checks.
+
+Do not report: compiler/type-checker-enforced cases; behavior already verified by an integration, contract, or e2e test; implementation-detail or mock-only tests; low coverage or a missing test file by itself; legacy untested code the change did not affect.
+
+Report genuine problems you noticed while tracing verification, even if they are not verification gaps. Put them under `Other findings` in the output. This permits reporting what you already reached, not extra hunting. A claim that code misbehaves is a defect, not a gap — it goes under `Other findings` for standard triage, however you found it.
+
+## OUTPUT FORMAT
+
+Emit each verification-gap finding as one block. No general advice, no severity or confidence. Triage trusts a gap finding as filed and does not re-verify it, so each block must stand on its own evidence.
+
+```markdown
+### <one-line title naming the gap>
+
+- **Changed surface:** the exact behavior or contract that changed — `file:line`.
+- **Impacted consumer or site:** named concretely with `file:line` (e.g. "the `createInvoice` mutation used by the billing dashboard at `billing/dashboard.ts:88`," not "callers of this function").
+- **Existing test evidence:**
+  - `Regression gap`: what the relevant test actually asserts, with `file:line`; or, if none, the symbol/import-reference searches run and their result.
+  - `Missing-adoption gap`: tests for the impacted site, and whether any assert it adopts the new behavior.
+  - `Broken-verification gap`: the apparent test or verification path, and why it does not count.
+- **Missing verification:** the precise assertion or check that's absent.
+- **Demonstration:**
+  - `Regression gap` / `Broken-verification gap`: the concrete regression that would ship undetected, and why the tests you checked would not fail.
+  - `Missing-adoption gap`: the case the site mishandles by not adopting the new behavior, and that none of the tests you read assert adoption.
+- **Consequence:** the concrete thing that ships wrong — a regression the checked evidence would not catch, or a site that should use the new behavior and doesn't.
+- **Disposition:** `patch` — name the test to add, fit to the repo's own way of verifying (don't impose a generic test pyramid) — or `defer` when the gap is real but not worth closing as part of this change, with one sentence of why.
+```
+
+If you noticed genuine non-gap problems while tracing verification, append:
+
+```markdown
+## Other findings
+
+- <description only; no severity, confidence, priority, or ranking>
+```
+
+When you find no verification gaps and no other findings, output exactly this single line, not an empty response:
+
+`No verification gaps found.`
+
+## CONTENT SOURCE
+
+"Review content:" in the message that launched you gives the content itself or a path to read it from. Read the file when it is a path; either way that is the content under review, and this instruction file never is. If no content is supplied, or the file it points to is missing, empty, or unreadable, say exactly that and stop — never report a clean review for content you could not read.