@roomi-fields/grillhouse 0.23.1 → 0.24.0

package/scripts/tests.mjs

@@ -37,21 +37,23 @@
 //   Turborepo's `--force` re-executes every task of the run, so the variable carries the moment of
 //   the run instead (`rejouer`), a value no cached run of the tests has. A test suspected unstable
 //   is played again, and a build, which the same inputs give again, is not.
-// - In the envelope of an agent (`GRILLHOUSE_ENVELOPPE`, scripts/enveloppe/composant.mjs), the
-//   neighbours and their traces arrive built by the launcher and read-only, as in a sandbox of
-//   Bazel: the build is the named packages' alone, with the traces of those packages their tests
-//   wait for, which live in the package the agent writes (`turbo run build <name>#trace:<t>…
-//   --only --filter=<name>`, their task ids read in Turborepo's plan of the tests,
-//   `turbo run test:vitest --filter=<name> --dry=json`), never their dependencies nor a
-//   neighbour's trace; then the tests alone (`turbo run test:vitest --only --filter=<name>`), the
-//   paths in the variable. A named package that the envelope shows read-only (the shared test
-//   material, for every role but the testwriter) is not built, nor are its traces: it arrives built,
-//   as a read-only input of Bazel, and its tests play as it is; the frame knows it read-only by
-//   testing its directory for writing (`inscriptible`), where the envelope mounts it, and the logs
-//   of its tasks go to the envelope's directories proper to the session (`sortiesDeTest`,
-//   scripts/enveloppe/enveloppe.mjs), never into its source. There the hash of the tests sees
-//   neither the code of the neighbours nor their builds: the verdict that counts is the reviewer's
-//   and the integration's, out of the envelope.
+// - In the envelope of an agent (`GRILLHOUSE_ENVELOPPE`, scripts/enveloppe/paquets-du-plan.mjs),
+//   the packages out of its plan and their traces arrive built by the launcher and read-only, as
+//   in a sandbox of Bazel: the build is the named packages' alone, with the traces of those
+//   packages their tests wait for, which live in the package the agent writes
+//   (`turbo run build <name>#trace:<t>… --only --filter=<name>`, their task ids read in
+//   Turborepo's plan of the tests, `turbo run test:vitest --filter=<name> --dry=json`), never
+//   their dependencies nor a neighbour's trace; then the tests alone
+//   (`turbo run test:vitest --only --filter=<name>`), the paths in the variable. A named package
+//   that the envelope shows read-only (one out of the plan; the shared test material, for every
+//   role but the testwriter) is not built, nor are its traces: it arrives built, as a read-only
+//   input of Bazel; the frame knows it read-only by testing its directory for writing
+//   (`inscriptible`), where the envelope mounts it. The shared test material plays its tests as
+//   it is: the logs of its tasks go to the envelope's directories proper to the session
+//   (`sortiesDeTest`, scripts/enveloppe/enveloppe.mjs), never into its source. A package out of
+//   the plan has no such directories: Turborepo and Vite cannot write its logs and its cache, and
+//   a run of its tests fails on « Read-only file system »; its tests play out of the envelope. The
+//   verdict that counts is the reviewer's and the integration's, out of the envelope.
 // - An argument that begins with « - » is an option of Vitest, written `--<name>=<value>`, carried
 //   in the variable beside the paths.
 // - A night test or a time budget bench, which the day leaves out, plays when a path names its own
@@ -79,7 +81,7 @@ import { spawnSync } from 'node:child_process';
 import { accessSync, constants, existsSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { planifier } from './avancement.mjs';
-import { composantDeLEnveloppe } from './enveloppe/composant.mjs';
+import { paquetsDeLEnveloppe } from './enveloppe/paquets-du-plan.mjs';
 import { paquets } from './paquets.mjs';
 import { garderLesResumes, RESULTATS } from './resultats.mjs';
 import { tracesDuPlan } from './turbo-des-paquets.mjs';
@@ -94,7 +96,7 @@ const racine = process.cwd();
 // Turborepo write in it (TMPDIR), and it goes at the end of the run.
 const base = ouvrirBase('tests');
 process.env.TMPDIR = base.dossier;
-const enveloppe = composantDeLEnveloppe() !== null;
+const enveloppe = paquetsDeLEnveloppe() !== null;
 const args = process.argv.slice(2);
 const force = args.includes('--force');
 const options = args.filter(a => a.startsWith('-') && a !== '--force');

package/scripts/verifier.mjs

@@ -23,7 +23,8 @@
 //   shared by every repository of the machine: a pass that finds it held waits for the end of the
 //   other measure, and says so every 30 s with who holds it. The wait bounded (60 min), the pass
 //   ends at 75, « à repasser »; a lock held by an ancestor of the pass ends it at once, red (1);
-//   either way without playing, the holder named.
+//   either way without playing, the holder named. A pass in the frame's own repository is of the
+//   second rank: it waits while a project's measure waits too.
 // - Turborepo plays the build, then the guards (the frame's, `grillhouse:gardes`, and the
 //   project's own, its root script `gardes`) and the tests (`test:vitest`) beside each other:
 //   `turbo run grillhouse:gardes gardes test:vitest --continue=dependencies-successful
@@ -92,7 +93,7 @@ import { availableParallelism, tmpdir } from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { ecrireLaMesure, garderLeTotal, ouvrirAvancement, planifier } from './avancement.mjs';
-import { composantDeLEnveloppe } from './enveloppe/composant.mjs';
+import { paquetsDeLEnveloppe } from './enveloppe/paquets-du-plan.mjs';
 import { paquets } from './paquets.mjs';
 import { AttenteDeLaMachine, avecLaMachine } from './verrou-de-machine.mjs';
 import {
@@ -197,7 +198,7 @@ export function verifier({
         const dossier =
           envMachine[AVANCEMENT] || ouvrirAvancement({ racine, genre: 'verification' });
         const effacer =
-          propre && !composantDeLEnveloppe(envMachine)
+          propre && !paquetsDeLEnveloppe(envMachine)
             ? ecrireLaMesure({
                 env: envMachine,
                 depot: nomDuDepot(racine),
@@ -226,7 +227,7 @@ export function verifier({
           }
         }
       },
-      { env, dire }
+      { env, racine, dire }
     );
   } catch (e) {
     if (!(e instanceof AttenteDeLaMachine)) throw e;

package/scripts/verrou-de-machine.mjs

@@ -31,21 +31,59 @@
 //   variable GRILLHOUSE_MESURE_TENUE carries the mark of the taking, and a process whose variable
 //   names the mark the lock holds plays under it without taking it again (the final pass of the
 //   circuit, `npm run verifier`, under the circuit's lock).
-// - In the envelope of an agent (GRILLHOUSE_ENVELOPPE set, scripts/enveloppe/composant.mjs) no lock
-//   is taken: the envelope has its own process space, where an owner's number means nothing
+// - In the envelope of an agent (GRILLHOUSE_ENVELOPPE set, scripts/enveloppe/paquets-du-plan.mjs)
+//   no lock is taken: the envelope has its own process space, where an owner's number means nothing
 //   outside, and its home shows no cache.
+// - A measure has a rank, as the job server of GNU make serves its own build first and Bazel's
+//   `--experimental_local_test_priority` orders the tests that wait for the machine. A measure
+//   played in the frame's own repository (one whose workspaces hold the package
+//   @roomi-fields/grillhouse in development, its agent copies included: `rangDeLaMesure`) is of
+//   the second rank; a project's (a circuit, a `npm run verifier`) is of the first. A measure of
+//   the first rank that waits names itself in the directory `<lock>.premier-rang/` (one file per
+//   waiting process, named by its number, removed once it holds the lock or stops); a measure of
+//   the second rank does not take the lock, even free, while a live process waits there, so a
+//   project's circuit never waits behind the frame's own checks (BPScript 320.9: 208 min of its
+//   wait went to the checks of the frame's agent copies). A waiting file whose process is gone
+//   names no one and goes. Between measures of one rank, the first to find the lock free takes
+//   it. The bound of the wait is the same for both ranks, and the wait says its rank.
 // - The lock is let go at the end of the measure, whether it succeeds or throws.
-import { mkdirSync, readFileSync, readlinkSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
-import { composantDeLEnveloppe } from './enveloppe/composant.mjs';
+import { paquetsDeLEnveloppe } from './enveloppe/paquets-du-plan.mjs';
+import { paquets } from './paquets.mjs';
 import { attendreUnPeu, lacherVerrou, prendreVerrou } from './verrou-de-fichier.mjs';
+import { vivant } from './vitest-config/base-de-passe.mjs';
 import { A_REPASSER } from './vitest-config/pression.mjs';
 
 const VARIABLE_VERROU = 'GRILLHOUSE_VERROU_MACHINE';
 const VARIABLE_TENUE = 'GRILLHOUSE_MESURE_TENUE';
 const VARIABLE_ATTENTE = 'GRILLHOUSE_ATTENTE_MACHINE_MS';
 
+// The name of the frame's package, which a repository of the second rank develops.
+const CADRE = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).name;
+
+/**
+ * The rank of a measure played at <racine>: 2 in the frame's own repository (its workspaces hold
+ * the package @roomi-fields/grillhouse in development), 1 elsewhere.
+ * @param {string} racine the root of the repository the measure plays in
+ * @returns {1 | 2}
+ */
+export function rangDeLaMesure(racine) {
+  return paquets(racine).some(p => p.pkg.name === CADRE) ? 2 : 1;
+}
+
+const RANGS = { 1: 'mesure de premier rang', 2: 'mesure de second rang (le dépôt du cadre)' };
+
 /** The longest wait for the lock of the machine, in ms, unless GRILLHOUSE_ATTENTE_MACHINE_MS names another. */
 export const ATTENTE_MACHINE_MS = 60 * 60_000;
 // The gap between two lines that say the wait goes on.
@@ -90,12 +128,9 @@ const heure = ms => new Date(ms).toTimeString().slice(0, 8);
 const duree = ms =>
   ms < 120_000 ? `${Math.round(ms / 1000)} s` : `${Math.round(ms / 60_000)} min`;
 
-// Who holds the lock <verrou>: its process, that process's working directory and command when
-// they read (on one line, cut at 200 characters), and since when the lock stands (« le processus 12 (dans /d) : node x, depuis
-// 10:04:31 (3 min) »).
-function qui(verrou) {
-  const pid = detenteur(verrou);
-  if (pid === null) return 'une autre mesure';
+// The process <pid>, its working directory and command when they read (on one line, cut at 200
+// characters): « le processus 12 (dans /d) : node x ».
+function processus(pid) {
   let ou = '';
   try {
     ou = ` (dans ${readlinkSync(`/proc/${pid}/cwd`)})`;
@@ -110,6 +145,14 @@ function qui(verrou) {
   const quoi = commande
     ? ` : ${commande.length > 200 ? `${commande.slice(0, 200)}…` : commande}`
     : '';
+  return `le processus ${pid}${ou}${quoi}`;
+}
+
+// Who holds the lock <verrou>: its process (`processus`) and since when the lock stands
+// (« le processus 12 (dans /d) : node x, depuis 10:04:31 (3 min) »).
+function qui(verrou) {
+  const pid = detenteur(verrou);
+  if (pid === null) return 'une autre mesure';
   let depuis = '';
   try {
     const t = statSync(verrou).mtimeMs;
@@ -117,9 +160,58 @@ function qui(verrou) {
   } catch {
     // the lock is gone meanwhile
   }
-  return `le processus ${pid}${ou}${quoi}${depuis}`;
+  return `${processus(pid)}${depuis}`;
 }
 
+// The directory where the measures of the first rank that wait for <verrou> name themselves.
+const fileDuPremierRang = verrou => `${verrou}.premier-rang`;
+
+// Names this process among the measures of the first rank that wait for <verrou>; a function that
+// removes its name.
+function attendreAuPremierRang(verrou) {
+  const dossier = fileDuPremierRang(verrou);
+  const f = path.join(dossier, `${process.pid}-${randomUUID()}`);
+  mkdirSync(dossier, { recursive: true });
+  writeFileSync(f, String(process.pid));
+  return () => rmSync(f, { force: true });
+}
+
+// The live processes of the measures of the first rank that wait for <verrou>; the name of a
+// process that is gone is removed.
+function premiersQuiAttendent(verrou) {
+  const dossier = fileDuPremierRang(verrou);
+  let noms;
+  try {
+    noms = readdirSync(dossier);
+  } catch {
+    return [];
+  }
+  const pids = [];
+  for (const nom of noms) {
+    const pid = Number(/^(\d+)-/.exec(nom)?.[1]);
+    if (pid && vivant(pid)) pids.push(pid);
+    else rmSync(path.join(dossier, nom), { force: true });
+  }
+  return pids;
+}
+
+// Whom a measure of the rank <rang> waits for at <verrou>: the holder of the lock, and for the
+// second rank the measures of the first that wait too, which pass first.
+function attendus(verrou, rang) {
+  const tenu = detenteur(verrou) === null ? 'libre' : `tenu par ${qui(verrou)}`;
+  const premiers = rang === 2 ? premiersQuiAttendent(verrou) : [];
+  const avant = !premiers.length
+    ? ''
+    : premiers.length === 1
+      ? ` ; une mesure de premier rang attend aussi et passe d'abord : ${processus(premiers[0])}`
+      : ` ; ${premiers.length} mesures de premier rang attendent aussi et passent d'abord : ${premiers.map(processus).join(' ; ')}`;
+  return `le verrou de la mesure lourde (${verrou}) est ${tenu}${avant}`;
+}
+
+// Whether a measure of the rank <rang> may take the lock <verrou>: the second rank only while no
+// measure of the first waits.
+const peutPrendre = (verrou, rang) => rang === 1 || premiersQuiAttendent(verrou).length === 0;
+
 // The parent of the process <pid>, read in /proc (the field after the state, which follows the
 // command, itself free to hold spaces and parentheses), or null.
 function parent(pid) {
@@ -140,10 +232,20 @@ function borneDe(env) {
   return env[VARIABLE_ATTENTE] && Number.isFinite(n) && n >= 0 ? n : ATTENTE_MACHINE_MS;
 }
 
-// Waits for the lock <verrou>, saying so (`dire`) when it begins and every <rappelMs>; returns the
-// time waited, in ms. Throws an AttenteDeLaMachine at once when an ancestor holds the lock, and at
-// the bound <borneMs>.
-function attendreLaMachine(verrou, { dire, borneMs, rappelMs }) {
+// Waits for the lock <verrou> at the rank <rang>, saying so (`dire`) when it begins and every
+// <rappelMs>; returns the time waited, in ms. Throws an AttenteDeLaMachine at once when an ancestor
+// holds the lock, and at the bound <borneMs>. A measure of the first rank names itself among those
+// that wait while it waits.
+function attendreLaMachine(verrou, { rang, dire, borneMs, rappelMs }) {
+  const retirer = rang === 1 ? attendreAuPremierRang(verrou) : () => {};
+  try {
+    return attendreAuRang(verrou, { rang, dire, borneMs, rappelMs });
+  } finally {
+    retirer();
+  }
+}
+
+function attendreAuRang(verrou, { rang, dire, borneMs, rappelMs }) {
   const debut = Date.now();
   let dit = null;
   for (;;) {
@@ -156,19 +258,20 @@ function attendreLaMachine(verrou, { dire, borneMs, rappelMs }) {
     const t = Date.now();
     if (t - debut >= borneMs)
       throw new AttenteDeLaMachine(
-        `⏱ attente du verrou de la machine bornée à ${duree(borneMs)} (${VARIABLE_ATTENTE}) : le verrou (${verrou}) est encore tenu par ${qui(verrou)} ; à repasser (code ${A_REPASSER}).`,
+        `⏱ attente du verrou de la machine bornée à ${duree(borneMs)} (${VARIABLE_ATTENTE}), ${RANGS[rang]} : ${attendus(verrou, rang)} ; à repasser (code ${A_REPASSER}).`,
         A_REPASSER
       );
     if (dit === null)
       dire(
-        `⏳ la machine mesure déjà : le verrou de la mesure lourde (${verrou}) est tenu par ${qui(verrou)} ; attente de sa fin, ${duree(borneMs)} au plus.`
+        `⏳ ${RANGS[rang]}, la machine mesure déjà : ${attendus(verrou, rang)} ; attente de son tour, ${duree(borneMs)} au plus.`
       );
     else if (t - dit >= rappelMs)
       dire(
-        `⏳ attente du verrou de la machine depuis ${duree(t - debut)} : il est tenu par ${qui(verrou)}.`
+        `⏳ ${RANGS[rang]}, attente du verrou de la machine depuis ${duree(t - debut)} : ${attendus(verrou, rang)}.`
       );
     if (dit === null || t - dit >= rappelMs) dit = t;
-    if (prendreVerrou(verrou, { attendre: false })) return Date.now() - debut;
+    if (peutPrendre(verrou, rang) && prendreVerrou(verrou, { attendre: false }))
+      return Date.now() - debut;
     attendreUnPeu(Math.max(1, Math.min(200, borneMs - (Date.now() - debut))));
   }
 }
@@ -177,8 +280,10 @@ function attendreLaMachine(verrou, { dire, borneMs, rappelMs }) {
  * Runs <mesure> under the lock of the machine and returns what it returns. <mesure> receives the
  * environment of its children, which carries the lock to them.
  * @param {(envEnfant: Record<string, string | undefined>) => T} mesure a synchronous measure
- * @param {{ env?: Record<string, string | undefined>, dire?: (ligne: string) => void,
- *   borneMs?: number, rappelMs?: number }} options `borneMs`, the bound of the wait
+ * @param {{ env?: Record<string, string | undefined>, racine?: string,
+ *   dire?: (ligne: string) => void, borneMs?: number, rappelMs?: number }} options `racine`, the
+ *   root of the repository the measure plays in, which gives its rank (`rangDeLaMesure`; the
+ *   working directory by default); `borneMs`, the bound of the wait
  *   (GRILLHOUSE_ATTENTE_MACHINE_MS, else ATTENTE_MACHINE_MS); `rappelMs`, the gap between two
  *   lines that say the wait goes on (30 s)
  * @returns {T}
@@ -190,17 +295,19 @@ export function avecLaMachine(
   mesure,
   {
     env = process.env,
+    racine = process.cwd(),
     dire = l => process.stdout.write(`${l}\n`),
     borneMs = borneDe(env),
     rappelMs = RAPPEL_MS,
   } = {}
 ) {
-  if (composantDeLEnveloppe(env)) return mesure(env);
+  if (paquetsDeLEnveloppe(env)) return mesure(env);
   const verrou = verrouDeMachine(env);
   if (env[VARIABLE_TENUE] && lire(verrou) === env[VARIABLE_TENUE]) return mesure(env);
   mkdirSync(path.dirname(verrou), { recursive: true });
-  if (!prendreVerrou(verrou, { attendre: false })) {
-    const attendu = attendreLaMachine(verrou, { dire, borneMs, rappelMs });
+  const rang = rangDeLaMesure(racine);
+  if (!(peutPrendre(verrou, rang) && prendreVerrou(verrou, { attendre: false }))) {
+    const attendu = attendreLaMachine(verrou, { rang, dire, borneMs, rappelMs });
     dire(`✓ verrou de la machine pris après ${Math.round(attendu / 1000)} s.`);
   }
   try {

package/scripts/verrous/verrou.mjs

@@ -11,12 +11,27 @@
 // - developpeur writes none of the testwriter's files, and no other file until its ticket's
 //   description holds a "## Architecture" section. The ticket is the "TON TICKET : <id>" line of the agent's
 //   launch prompt, read from its transcript.
+// - In an envelope (`GRILLHOUSE_ENVELOPPE`, the packages of the plan, scripts/enveloppe/
+//   paquets-du-plan.mjs), a write in the copy out of the packages the plan writes (`ecritsDuPlan`)
+//   and out of the shared test material, whose rule is the one above, stops the session, as the
+//   visibility of Bazel refuses a target the rule does not open: the hook answers Claude Code's
+//   `continue: false`, the tool refused (`permissionDecision: deny`), its reason naming the file's
+//   package and the plan, and leaves that reason in the session's working directory
+//   (`MARQUE_HORS_PLAN` under TMPDIR), which the launcher hands to the circuit. The mount of the
+//   envelope refuses the same write to any tool; the hook says why, and stops.
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { matieres, NOM_DE_TEST } from '../consommateurs.mjs';
+import {
+  ecritsDuPlan,
+  MARQUE_HORS_PLAN,
+  paquetQuiTient,
+  paquetsDeLEnveloppe,
+} from '../enveloppe/paquets-du-plan.mjs';
+import { paquets } from '../paquets.mjs';
 
 const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
 
@@ -68,6 +83,31 @@ function racineDe(file) {
   }
 }
 
+// The stop of a write out of the plan of the envelope <env>, `{ paquet, raison }`, or null: a
+// write in the repository holding the file, out of the packages the plan writes and out of the
+// shared test material.
+function horsDuPlan(input, { tmp = tmpdir(), env = process.env } = {}) {
+  const plan = paquetsDeLEnveloppe(env);
+  if (!plan || !WRITE_TOOLS.has(input.tool_name)) return null;
+  const raw = input.tool_input?.file_path ?? input.tool_input?.notebook_path;
+  if (!raw) return null;
+  const file = path.resolve(input.cwd ?? process.cwd(), raw);
+  if (isScratch(file, tmp)) return null;
+  const copie = racineDe(file);
+  if (!copie) return null;
+  const liste = paquets(copie);
+  const ecrits = ecritsDuPlan(plan, liste);
+  const rel = path.relative(copie, file);
+  if (ecrits.includes('.') || ecrits.some(d => rel.startsWith(`${d}/`))) return null;
+  if (matieres(copie).some(m => isInside(file, m.dir))) return null;
+  const tenant = paquetQuiTient(rel, liste);
+  const paquet = tenant === '.' ? 'la racine du dépôt' : tenant;
+  return {
+    paquet,
+    raison: `⛔ hors-plan — ${rel} est dans ${paquet}, hors des paquets du plan (${plan.join(', ')}) : ta séance s'arrête là, et le superviseur étend le plan ou refuse l'écriture.`,
+  };
+}
+
 // The ticket id of the launch prompt. A sub-agent's prompt opens its own transcript, next to the
 // session's; an agent launched as its own session (`claude --agent`) has it in the session's.
 function ticketOf(input) {
@@ -157,9 +197,30 @@ export function refusal(role, input, { tmp = tmpdir(), describe = ticketDescript
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
   const input = JSON.parse(readFileSync(0, 'utf8'));
-  const reason = refusal(process.argv[2], input);
-  if (reason) {
-    process.stderr.write(reason + '\n');
-    process.exitCode = 2;
+  const stop = horsDuPlan(input);
+  if (stop) {
+    // The mark for the circuit; the stop below is the hook's answer, mark or not.
+    try {
+      writeFileSync(path.join(tmpdir(), MARQUE_HORS_PLAN), stop.raison);
+    } catch {
+      // A working directory gone leaves no mark; the session still stops.
+    }
+    process.stdout.write(
+      `${JSON.stringify({
+        continue: false,
+        stopReason: stop.raison,
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: stop.raison,
+        },
+      })}\n`
+    );
+  } else {
+    const reason = refusal(process.argv[2], input);
+    if (reason) {
+      process.stderr.write(reason + '\n');
+      process.exitCode = 2;
+    }
   }
 }

package/skills/developpeur/SKILL.md

@@ -5,26 +5,26 @@ description: "Le développeur : travailler un ticket du dépôt courant en agent
 
 # Développeur — travailler un ticket
 
-Tu travailles un seul ticket, dans la copie qui porte son numéro. Le superviseur (`pitmaster`) te
-l'a confié ; le responsable du projet l'a validé. La charte du projet, déjà dans ton contexte,
-prime sur tout le reste.
+Tu travailles un seul ticket, dans la copie qui porte son numéro : une seule séance porte tout son
+code, dans tous les paquets de son plan. Le superviseur (`pitmaster`) te l'a confié ; le
+responsable du projet l'a validé. La charte du projet, déjà dans ton contexte, prime sur tout le
+reste.
 
 ## Au démarrage
 
 1. Ta consigne porte ton ticket, lu au lancement de ta séance : sa description et ses critères,
-   ses notes, la dernière passation de ton rôle sur ton composant (celle du testwriter, pour ta
-   première séance). Tu ne le relis pas par bd, qui le refuse à ta séance. Puis
-   `bd update <id> --claim`. Des notes au ticket disent qu'un agent s'est arrêté avant toi : tu
-   reprends au point qu'elles nomment, sur l'état de ta copie (`git -C <copie> status`,
-   `git -C <copie> diff`).
-2. Lis les documents des composants que ton ticket touche : `CADRE.md`, `INTERFACE.md`,
-   `ARCHITECTURE.md` (`docs/`, ou `packages/<x>/docs/`), et le lexique `CONTEXT.md`. Ainsi ton
-   code part de l'architecture écrite. Un document absent ne t'arrête pas.
-3. Lis la section « Ce que les composants d'avant publient » de ta consigne : pour chaque
-   fournisseur, sa ligne, les noms déclarés pour ton composant et l'adresse de sa rubrique « Rend ».
-   Le reste se lit à deux renvois : tous les éléments avec leur phrase dans
+   ses notes, la dernière passation de ton rôle (celle du testwriter, pour ta première séance), les
+   paquets de son plan et les constats du relecteur qui restent ouverts pour toi. Tu ne le relis
+   pas par bd, qui le refuse à ta séance. Puis `bd update <id> --claim`. Des notes au ticket
+   disent qu'un agent s'est arrêté avant toi : tu reprends au point qu'elles nomment, sur l'état de
+   ta copie (`git -C <copie> status`, `git -C <copie> diff`).
+2. Lis les documents des paquets du plan : `CADRE.md`, `INTERFACE.md`, `ARCHITECTURE.md`
+   (`docs/`, ou `packages/<x>/docs/`), et le lexique `CONTEXT.md`. Ainsi ton code part de
+   l'architecture écrite. Un document absent ne t'arrête pas.
+3. Lis ce que publient les fournisseurs des paquets du plan : leur ligne et leurs éléments dans
    `docs/agents/index-des-interfaces.md`, puis la section d'un élément dans l'interface du
-   fournisseur. Ainsi tu sais ce qui est déjà calculé, et où.
+   fournisseur, et la ligne « Déclaré pour » de sa section « Consommateurs ». Ainsi tu sais ce qui
+   est déjà calculé, et où.
 4. Lance les tests du testwriter, déjà dans ta copie (`npm test -- <fichiers>`, chemins depuis la
    racine du dépôt), et vois-les rouges ; sans test neuf, ce sont les rouges existants que le
    rapport de la preuve nomme.
@@ -47,16 +47,20 @@ prime sur tout le reste.
 - **Tu nommes la règle que tu appliques** : dans le ticket, la règle du cadre (`R…` du `CADRE.md`)
   et la règle d'architecture ou de spécification. Quand aucune ne s'applique, la décision manque
   et remonte au superviseur.
-- **Ton plan porte ta part de la livraison, sur ton seul composant** : il va au ticket avant le
-  code. Un plan qui demande plus t'arrête : tu rends ce découpage au superviseur. Ainsi un ticket
-  reste petit, et tu écris dans ton seul paquet.
+- **Ton plan porte la livraison, sur les seuls paquets du plan** : il va au ticket avant le code,
+  le fournisseur d'abord. Un plan qui demande un autre paquet t'arrête : ta fiche le nomme, et le
+  superviseur étend le plan ou refuse. Ainsi un ticket reste dans son plan.
 
 ## Le code
 
-- **Ton composant reçoit les faits de ses fournisseurs** : ceux de la section « Ce que les
-  composants d'avant publient ». Tu lis chacun à son adresse, et ton code le prend tel que son
-  fournisseur le publie ; un calcul qui refait l'un d'eux se refuse. Ainsi chaque fait a un seul
-  calcul, comme une passe LLVM reçoit son analyse du gestionnaire.
+- **Chaque paquet reçoit les faits de ses fournisseurs** : ceux que publie leur interface, déclarés
+  pour lui. Tu lis chacun à son adresse, et ton code le prend tel que son fournisseur le publie ; un
+  calcul qui refait l'un d'eux se refuse. Ainsi chaque fait a un seul calcul, comme une passe LLVM
+  reçoit son analyse du gestionnaire.
+- **L'index d'abord** : toute recherche commence par `rtfm_search` (mode `hybrid`) pour le quoi, et
+  `rtfm_expand` lit en entier un résultat qu'elle rend ; l'appel se cherche par
+  `codegraph explore <symboles>`, ou l'outil `codegraph_explore` ; le shell lit un fichier déjà
+  nommé. Ainsi ton code part de ce que le dépôt contient.
 - **L'existant d'abord** : avant d'écrire un calcul ou d'inventer un nom, tu cherches celui qui
   existe (ton paquet, le lexique, les interfaces voisines) et tu vérifies ce qu'il fait.
 - **Une entrée ambiguë se refuse** : ce que le produit ne sait pas interpréter d'une seule façon
@@ -68,12 +72,13 @@ prime sur tout le reste.
 - **Le comportement tient dans les critères** : ton code fait ce que disent les critères
   d'acceptation, et rien d'autre.
 
-Tu vois ton paquet en entier, et des autres composants leur interface et leur forme publiée. Tu
-écris ton seul paquet : le reste de la copie est en lecture seule, et une écriture hors de lui
-échoue (« Read-only file system ») ; un dossier hors des paquets (des données comme `libraries/`)
-s'écrit par le composant qui le possède, que ta `raison` nomme. Tes
-voisins arrivent construits, et les traces que lisent tes tests produites : `npm test -- <fichiers>` construit ton seul paquet et régénère ses propres traces, et `npm run api`,
-après lui, écrit le rapport d'API et la part générée de ton seul composant. La matière de test
+Tu lis toute la copie, index compris. Tu écris les seuls paquets du plan de ton ticket (les
+paquets de son titre) : le reste de la copie est en lecture seule, une écriture hors d'eux
+échoue (« Read-only file system »), et ton verrou arrête ta séance sur une écriture hors du plan,
+que le superviseur étend ou refuse ; un dossier hors des paquets (des données comme `libraries/`)
+s'écrit par le paquet qui le possède, que ta `raison` nomme. Les paquets hors du plan
+arrivent construits, et les traces que lisent tes tests produites : `npm test -- <fichiers>` construit les paquets du plan et régénère leurs propres traces, et `npm run api`,
+après lui, écrit le rapport d'API et la part générée des paquets du plan. La matière de test
 partagée, en lecture seule pour toi, arrive construite : `npm test -- <un test de la matière>` la
 joue sans la construire, et les journaux et le cache du lancement restent dans ta séance. Les
 gardes du cadre (frontières, consommateurs, index des interfaces, rapports d'API) tournent à côté
@@ -98,7 +103,7 @@ avec ta fiche. Ainsi le circuit reprend dès ta fiche rendue.
   recommandation ; ton code suit ensuite le verdict « Arbitrage » au ticket.
 - **Un fait que ton code prend chez un fournisseur hors de sa ligne « Déclaré pour »** (un élément
   publié pas encore déclaré pour toi, ou un fait que ta section ne porte pas) : une découverte qui
-  bloque, que le superviseur porte au référent technique, et qui entre ensuite dans la section
+  bloque, que le superviseur tranche ou porte au responsable, et qui entre ensuite dans la section
   « Consommateurs » du fournisseur.
 - **Une donnée qui manque chez un fournisseur** : tu t'arrêtes, et ta fiche finit sur BLOQUÉ, sa
   `raison` nommant la donnée et le fournisseur ; tu ne la calcules pas dans ton paquet. Le superviseur ajoute le fournisseur
@@ -117,45 +122,50 @@ son adresse) : le circuit la consigne fermée sous ton ticket, et tu continues.
 ## Vérifier et livrer
 
 - **Le circuit contrôle après toi** : ta séance finie, le circuit du ticket joue les tests du lot
-  et de chaque paquet des composants jusqu'au tien, puis les gardes dans ton enveloppe ; après le
-  dernier composant, la passe finale, la passe complète que joue l'intégration. Un rouge te
-  relance avec sa sortie quand il est dans ton composant. Tu es lancé sur un rouge (de la preuve, un `rouge existant` compris, ou des
-  contrôles), ou directement dans un composant qui ne porte aucun test (aucun paquet avec un
-  script `test:vitest`), sans testwriter ni preuve : une séance qui ne change aucun fichier de ton
-  composant arrête le circuit (`sans-livraison`), et ta passation dit pourquoi. Tes propres
-  lancements pendant le travail restent les tiens. Ainsi ton lot arrive au relecteur vert.
-- **Un rouge qui reste dans les tests va à leur testwriter** : quand le rouge qui reste est dans les
-  tests d'un composant du titre, le tien ou un composant d'avant (un test existant que ton
-  changement de type casse), ta fiche porte `renvoi` : le rôle testwriter et ce composant, écrit
-  comme le titre le nomme. Le circuit rejoue ce composant depuis son testwriter, ta `raison` et ta
-  passation pour rapport, puis les composants d'après qu'il n'a pas encore menés et la passe
-  finale, sans te relancer sur ce rouge ; dans la reprise d'un `RENDU`, les constats de ton
-  composant et des composants d'après restent, chacun rejoué ensuite ; le même renvoi deux fois de suite, sans contrôles verts
-  entre eux, l'arrête (`sans-livraison`). Ainsi le rouge va à l'agent qui écrit les tests.
+  et de chaque paquet du plan, puis les gardes dans l'enveloppe du plan ; puis la passe finale, la
+  passe complète que joue l'intégration. Un rouge te relance avec sa sortie quand il est dans un
+  paquet du plan ; hors du plan, il attend la passe finale, où il monte au superviseur. Tu es lancé
+  sur un rouge (de la preuve, un `rouge existant` compris, ou des contrôles), sur un constat du
+  relecteur ouvert pour toi, ou directement sur un plan qui ne porte aucun test (aucun paquet avec
+  un script `test:vitest`), sans testwriter ni preuve : une séance qui ne change aucun fichier du
+  plan n'a rien à livrer, et ses contrôles rouges arrêtent le circuit (`sans-livraison`) ; ta
+  passation dit pourquoi. Tes propres lancements pendant le travail restent les tiens. Ainsi ton
+  lot arrive au relecteur vert.
+- **Un rouge qui reste dans les tests va au testwriter** : quand le rouge qui reste est dans les
+  tests du lot (un test existant que ton changement de type casse), ta fiche porte `renvoi`, le
+  rôle testwriter. Le circuit relance le testwriter, ta `raison` et ta passation pour rapport, puis
+  la preuve et ta séance, sans te relancer sur ce rouge ; le même renvoi deux fois de suite, sans
+  contrôles verts entre eux, l'arrête (`sans-livraison`). Ainsi le rouge va à l'agent qui écrit
+  les tests.
 - **Ta séance finit sur ta fiche**, que ton schéma décrit et que le circuit lit seule :
   - `statut` FAIT : ton code est écrit, et les contrôles le jugent ;
   - `statut` BLOQUÉ, avec sa `raison` : ce qui reste est hors de ta portée (un test, la matière
-    de test partagée, un fichier hors de ton enveloppe, une décision hors de ton rôle) ; avec
+    de test partagée, un fichier hors du plan, une décision hors de ton rôle) ; avec
     `renvoi`, c'est le renvoi au testwriter ; sans lui, le circuit s'arrête (`hors-portee`) ;
   - `statut` BESOIN, avec sa `question` : une réponse te manque pour avancer ; le circuit
     s'arrête (`besoin`) ;
   - `ecarts` : ce que le message de commit nomme, chacun sous son `sujet` (ce qui s'écarte :
     une référence, un test, un plafond), avec son `texte` ;
   - `decouvertes` : ce que le circuit consigne fermé sous le ticket.
-    Sur un arrêt, le régulateur tranche, et le circuit ne te relance pas sur ce rouge. Ainsi
+    Sur un arrêt, ta question monte au superviseur, et le circuit ne te relance pas sur ce rouge. Ainsi
     tu ne tournes jamais sur un rouge que tu as dit hors de ta portée.
+- **Un fait repris porte sa pièce** : un fait que tu reprends d'un autre agent (une passation, un
+  rapport, un constat) se relit à sa pièce avant que tu t'appuies dessus, et ta raison ou ta
+  question porte la sienne, `piece` (fichier:ligne depuis la racine de la copie, ou « $ commande »
+  et sa sortie), que le circuit cherche dans la copie. Ainsi une ligne mal lue s'arrête à toi.
 - **Une relance reprend ta séance** : après des contrôles rouges, le circuit reprend ta séance avec
-  une consigne courte, le rapport neuf seul ; ta consigne, ta compétence et ce que tu as lu restent
+  une consigne courte, le rapport neuf ; ta consigne, ta compétence et ce que tu as lu restent
   valables. La dernière tentative, sur le modèle fort, est une séance neuve et entière. Ainsi tu
-  repars de ce que tu sais.
+  repars de ce que tu sais. Toute relance (des contrôles rouges, un `RENDU`, une reprise du
+  superviseur) porte les constats du relecteur qui restent ouverts pour toi, tous, jusqu'à la
+  relecture qui les juge levés. Ainsi aucun constat ne se perd d'une relance à l'autre.
 - **Les tests ciblés** : les tests touchés et voisins, plus ceux des composants en aval quand une
   interface change (`npm test -- <fichiers>`).
 - **Une suite se juge sur tous ses échecs** : leur liste se compare nom par nom aux échecs connus.
   Ainsi « vert » veut dire que rien de neuf n'a cassé.
 - **Un écart dit l'état que le lot laisse au commit** : un écart voulu, une référence changée, un
   test mis en quarantaine avec le ticket qui le referme entrent dans `ecarts` de ta fiche, avec leur
-  cause ; un test qu'un composant d'après du ticket referme se dit dans ta passation, car la passe
-  finale est verte avant le commit. Un sujet qu'une fiche d'avant nomme se reprend tel quel, et ta
+  cause ; la passe finale est verte avant le commit. Un sujet qu'une fiche d'avant nomme se reprend tel quel, et ta
   valeur remplace la sienne : le circuit écrit chaque sujet une fois, de la dernière fiche qui le
   porte. Ainsi le message de commit ne se répète ni ne se contredit.
 - **Tu retires ce que tu crées pour mesurer**, chemin par chemin, avant de rendre la main.