@roomi-fields/grillhouse 0.0.0-stage → 0.23.0

package/scripts/enveloppe/lancer.sh

@@ -0,0 +1,311 @@
+#!/usr/bin/env bash
+# Launches a role agent on one ticket, as its own Claude session inside the envelope of its
+# component. The supervisor runs it in the background and is told when the session ends.
+#
+#   npx grillhouse lancer [--modele <m>] [--effort <e>] [--seance <id> | --reprise <id>] <ticket> <rôle> <composant> <fichier de consigne>
+#
+# - <composant> is the component's path from the root (`packages/<nom>`, or `.` for the whole
+#   repository). It is judged before the copy is prepared, by the envelope's rule
+#   (`jugerComposant` of enveloppe.mjs), as the role and the instruction are, in the ticket's copy
+#   when it exists, else in the main tree or in the tree of the branch agent/<ticket> when it
+#   exists (`git cat-file -e`; `.` is always admitted): a path that names nothing there is refused on the standard error, CODE_USAGE, nothing prepared; when
+#   it is the name of a package or of its folder, the refusal names the path it means.
+# - --modele <m> and --effort <e> override, for this session only, the model and the thinking level
+#   of the role's definition (its agent in the frame's plugin, agents/<rôle>.md); they reach claude
+#   as --model and --effort.
+#   Each is optional and works alone; without them the role decides. The level is one of low,
+#   medium, high, xhigh, max; the model is any non-empty text, passed to claude as given. They come
+#   first, each as two words (`--modele opus`); `--modele=opus`, `--`, a value starting with `--`,
+#   an unknown option or an option after the four arguments is refused, CODE_USAGE, before the copy
+#   is prepared. A repeated option keeps its last value; every level given is checked.
+# - --seance <id> opens the session under that id (claude's --session-id), and --reprise <id>
+#   resumes the session of that id (claude's --resume), which claude finds among the transcripts
+#   of the copy's working directory (`~/.claude/projects/<copy in dashes>/`, which the envelope
+#   mounts in writing over the real directory, so that a transcript outlives its session). The
+#   circuit gives them, so that a relaunch of an agent on its step resumes its session. The two
+#   together are refused, CODE_USAGE; each takes a value as --modele does.
+#   A resumed session receives its instruction alone: the session it resumes holds the sections
+#   the launcher adds below, save « La construction de ton paquet échoue », which it receives.
+# - The agent's copy is the worktree .claude/worktrees/<ticket> (branch agent/<ticket>), created
+#   from the main tree's HEAD when absent and moved forward to it otherwise. When the branch exists
+#   without a copy, it is brought back to the main tree's HEAD and the copy is made on it: the lot
+#   the branch carried ahead of main (a branch the queue sent back) comes back as local work in
+#   the copy, a conflict with main marked in its file; a branch with nothing ahead simply starts
+#   again from main. A ticket whose branch is still in the integration queue is not launched:
+#   the refusal goes to the log, which names the queue, CODE_COPIE, before any copy is made.
+#   Moving forward keeps
+#   the work in progress of the copy: git stashes it, fast-forwards, and reapplies it
+#   (`--autostash`). A refusal, such as commits of the agent on its branch, goes to the log and
+#   stops the launch, CODE_COPIE; so does a reapplication that conflicts: the log names each file
+#   in conflict, the work stays in git's stash, and no agent starts on a half-merged copy. Its
+#   submodules go through the common preparation (scripts/sous-modules.sh): before moving forward,
+#   a submodule carrying local work stops the launch, CODE_COPIE, its log naming it, the work in
+#   place; then every submodule is set at the commit of HEAD, before any installation, except one the
+#   project shares (`grillhouse.partage`), which the copy reads from the main repository. Its
+#   dependencies are installed when `node_modules` is absent or `package-lock.json` is newer than
+#   the last installation (`node_modules/.package-lock.json`, written by npm), and it is built there
+#   by Turborepo, which restores an unchanged build from its cache, outside the envelope, so the
+#   agent finds the published parts of its neighbours. As Bazel builds the dependencies of a target
+#   before the target: for a component that is a package of the frame, its providers are built
+#   first (the packages whose build its build waits for, read in Turborepo's graph,
+#   `turbo run build --filter=<paquet> --dry=json`, which node reads on its standard input, whatever
+#   its size), and a failure stops the launch, CODE_COPIE;
+#   then the traces of other packages its tests wait for (`grillhouse.traces`, read in Turborepo's
+#   plan of its tests, `turbo run test:vitest --filter=<paquet> --dry=json`), which the envelope
+#   shows read-only, and a failure stops the launch, CODE_COPIE; then the package, its own traces
+#   and what its tests read (`turbo run build <its traces> --filter=<paquet>...
+#   --continue=dependencies-successful`), whose failure does not stop it: each task whose
+#   dependencies succeed goes to its end, so what its tests read without depending on it is built
+#   whole; the session opens, its instruction ending with a section « La construction de ton
+#   paquet échoue » with the end of that output, since repairing it is the session's work (a
+#   provider's lot that breaks its consumers). Its consumers are not built. Any other component,
+#   the whole repository (`.`) included, builds the copy whole (`turbo run build`). The
+#   installation and the build play through `scripts/sous-modules.sh monter`, each shared submodule
+#   of the main repository read-only, by the list the pose printed, whatever the installation
+#   rewrites afterwards; with a shared submodule and no possible mount (bwrap absent or
+#   refused), the launch stops, CODE_COPIE, before any command runs. In the envelope the main
+#   repository is read-only as a whole.
+# - The envelope receives the role: it decides who writes the package of the shared test material.
+# - The session runs `claude -p` with the role's agent and, as its prompt, read on its standard
+#   input from a temporary file the launcher writes and removes (an argument may not pass the
+#   128 KiB Linux allows one, MAX_ARG_STRLEN), the instruction file
+#   followed by the section « Ce que les composants d'avant publient »: for each component whose
+#   `## Consommateurs` section names the component, its line, the names of the elements declared
+#   for the component, and the address of the rubric « Rend » of its frame, the rest of its
+#   elements left to the index of the interfaces (`scripts/index-interfaces.mjs --publie`, read in
+#   the prepared copy; a reading that fails stops the launch, CODE_COPIE), then the
+#   section « Ton dossier de travail », which names the session's working directory, where every
+#   temporary file goes (`dossierDeTravail` of enveloppe.mjs, the envelope's TMPDIR), then the
+#   section « La construction de ton paquet échoue » when it fails. The prompt
+#   carries « TON TICKET : <ticket> », which the role's locks read. The envelope is the sandbox, so
+#   the session runs without permission prompts, under the rights and the context of its role
+#   (scripts/droits.mjs, given the main tree, the copy and the ticket; a reading that fails stops
+#   the launch, CODE_COPIE): the user's own configuration left out, its settings on the command
+#   line (its refusals, among them the change of its author at the ticket, AUTEUR_FIXE: its
+#   comments carry the author the launch names in BEADS_ACTOR, which the envelope passes on; its
+#   locks), its tools and no server of the index.
+# - A role that ends on a sheet (scripts/resultats.mjs: the testwriter, the developpeur) runs with
+#   `--output-format json --json-schema <its schema>` (`npx grillhouse resultats --schema
+#   <rôle>`): claude's JSON result, its sheet in `structured_output`, goes to
+#   .claude/worktrees/<ticket>.resultat.json, which a launch removes first and the circuit reads,
+#   then to the log; its errors go to the log.
+# - Its output, and an envelope refusal (CODE_REFUS), are added to .claude/worktrees/<ticket>.log,
+#   the log of the ticket, which keeps every session of the ticket: each launch past the checks of
+#   its call adds a header line, `=== <time> · <rôle> · <composant> ===`, then its preparation and
+#   its session. The agent writes its handover in the ticket. Once the envelope has ended, the
+#   launcher writes the session's exit code to .claude/worktrees/<ticket>.fin, which a launch
+#   removes first: a launch that stops before its session leaves none, so the circuit
+#   (scripts/circuit.mjs) tells a code of the session from CODE_USAGE, CODE_REFUS and CODE_COPIE.
+#   It then writes the session's line to the register (scripts/registre.mjs --copie), and exits
+#   with the envelope's code.
+# - The exit codes are named in scripts/enveloppe/codes.mjs; a malformed call exits CODE_USAGE.
+# - CLAUDE_BIN replaces `claude` (the tests use it).
+set -euo pipefail
+ici="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+eval "$(node "$ici/codes.mjs")"
+usage="usage: npx grillhouse lancer [--modele <m>] [--effort <e>] [--seance <id> | --reprise <id>] <ticket> <rôle> <composant> <fichier de consigne>"
+refus_usage() { echo "$usage" >&2; exit "$CODE_USAGE"; }
+modele="" effort="" seance="" reprise="" surcharge=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --modele|--effort|--seance|--reprise)
+      [ $# -ge 2 ] && [ -n "$2" ] && [[ "$2" != --* ]] || refus_usage
+      if [ "$1" = --modele ]; then
+        modele=$2
+      elif [ "$1" = --seance ]; then
+        seance=$2
+      elif [ "$1" = --reprise ]; then
+        reprise=$2
+      else
+        case "$2" in low|medium|high|xhigh|max) effort=$2 ;; *) refus_usage ;; esac
+      fi
+      shift 2 ;;
+    -*) refus_usage ;;
+    *) break ;;
+  esac
+done
+[ -z "$modele" ] || surcharge+=(--model "$modele")
+[ -z "$effort" ] || surcharge+=(--effort "$effort")
+[ -z "$seance" ] || [ -z "$reprise" ] || refus_usage
+[ -z "$seance" ] || surcharge+=(--session-id "$seance")
+[ -z "$reprise" ] || surcharge+=(--resume "$reprise")
+[ $# -eq 4 ] || refus_usage
+ticket=$1 role=$2 composant=$3 consigne=$4
+# The main tree, from the common git directory: launched from an agent copy, the new copy still
+# lands next to the others, never inside one.
+racine=$(cd "$(git rev-parse --path-format=absolute --git-common-dir)/.." && pwd)
+# A role is one of the circuit's, whose rights scripts/droits.mjs gives (ROLES).
+node --input-type=module -e "import { ROLES } from '$ici/../droits.mjs'; process.exit(Object.hasOwn(ROLES, process.argv[1]) ? 0 : 1);" "$role" || { echo "⛔ Rôle inconnu : $role (aucun rôle du circuit, scripts/droits.mjs)." >&2; exit "$CODE_USAGE"; }
+[ -f "$consigne" ] || { echo "⛔ Consigne introuvable : $consigne" >&2; exit "$CODE_USAGE"; }
+# The component, judged by the envelope's rule before anything is prepared: in the ticket's copy
+# when it exists (a relaunch, whose package an earlier agent may have created), else in the main
+# tree or, when the branch agent/<ticket> exists (one the queue sent back), in its tree, whose lot
+# the copy made again carries.
+juge="$racine" branche=
+if [ -d "$racine/.claude/worktrees/$ticket" ]; then
+  juge="$racine/.claude/worktrees/$ticket"
+elif git -C "$racine" rev-parse --verify --quiet "refs/heads/agent/$ticket" > /dev/null; then
+  branche="agent/$ticket"
+fi
+refus_composant=$(node --input-type=module -e "import { spawnSync } from 'node:child_process'; import { existsSync } from 'node:fs'; import path from 'node:path'; import { jugerComposant } from '$ici/enveloppe.mjs'; import { paquets } from '$ici/../paquets.mjs'; const [depot, composant, branche] = process.argv.slice(1); const dansBranche = p => { const rel = path.relative(depot, p); return rel === '' || (!rel.startsWith('..') && spawnSync('git', ['-C', depot, 'cat-file', '-e', branche + ':' + rel]).status === 0); }; const existe = p => existsSync(p) || (branche !== '' && dansBranche(p)); process.stdout.write(jugerComposant({ depot, composant, paquets: paquets(depot) }, { existe }) ?? '');" "$juge" "$composant" "$branche") || exit "$CODE_USAGE"
+[ -z "$refus_composant" ] || { echo "⛔ $refus_composant" >&2; exit "$CODE_USAGE"; }
+# The ticket is matched whole: `demo-3160` is not `demo-316`, and its dots are dots.
+motif=$(printf '%s' "$ticket" | sed 's/[.[\*^$]/\\&/g')
+grep -qE "TON TICKET : ${motif}([^A-Za-z0-9_.-]|$)" "$consigne" || { echo "⛔ La consigne ne porte pas « TON TICKET : $ticket »." >&2; exit "$CODE_USAGE"; }
+
+copie="$racine/.claude/worktrees/$ticket"
+journal="$copie.log"
+fin="$copie.fin"
+resultat="$copie.resultat.json"
+mkdir -p "$(dirname "$copie")"
+rm -f "$fin" "$resultat"
+printf '=== %s · %s · %s ===\n' "$(date -Iseconds)" "$role" "$composant" >> "$journal"
+# A branch still in the queue is not relaunched: the queue brings it onto main, or sends it back.
+if node --input-type=module -e "import { lireEntrees } from '$ici/../integration/file-attente.mjs'; const [r, b, t] = process.argv.slice(1); process.exit(lireEntrees(r).some(e => e.branche === b || e.ticket === t) ? 0 : 1);" "$racine" "agent/$ticket" "$ticket"; then
+  refus="⛔ La branche agent/$ticket est encore en file d'intégration : la file l'amène sur main ou la renvoie ; le ticket ne se relance pas avant."
+  echo "$refus" >> "$journal"
+  echo "$refus" >&2
+  exit "$CODE_COPIE"
+fi
+# The output of the session package's build, when it fails.
+echec=$(mktemp)
+(
+  # Each step returns on failure: `set -e` does not act inside a subshell tested by `||`.
+  if [ ! -d "$copie" ]; then
+    tete=$(git -C "$racine" rev-parse HEAD) || exit 1
+    branche="agent/$ticket"
+    lot=
+    if git -C "$racine" rev-parse --verify -q "refs/heads/$branche" > /dev/null; then
+      # A branch already there: the queue sent it back, or it was left without a commit. Its lot,
+      # when it carries one, goes back as local work on main; the branch returns to main.
+      if [ "$(git -C "$racine" rev-list --count "$tete..$branche")" -gt 0 ]; then
+        base=$(git -C "$racine" merge-base "$tete" "$branche") || exit 1
+        lot=$(mktemp) || exit 1
+        git -C "$racine" diff --binary "$base" "$branche" > "$lot" || exit 1
+      fi
+      git -C "$racine" branch -q -f "$branche" "$tete" || exit 1
+      git -C "$racine" worktree add -q "$copie" "$branche" || exit 1
+    else
+      git -C "$racine" worktree add -q -b "$branche" "$copie" HEAD || exit 1
+    fi
+    if [ -n "$lot" ]; then
+      # The lot is applied three ways: a conflict is marked in the file, the rest of the lot is
+      # there. The index is left as HEAD has it, so that all of it is local work.
+      git -C "$copie" apply --3way "$lot" || [ -n "$(git -C "$copie" ls-files -u)" ] || exit 1
+      git -C "$copie" reset -q || exit 1
+      rm -f "$lot"
+    fi
+  else
+    bash "$ici/../sous-modules.sh" garde "$copie" || exit 1
+    git -C "$copie" merge -q --ff-only --autostash "$(git -C "$racine" rev-parse HEAD)" || exit 1
+    # A conflicting reapplication exits 0: the unmerged files are what tells it.
+    conflits=$(git -C "$copie" diff --name-only --diff-filter=U) || exit 1
+    if [ -n "$conflits" ]; then
+      echo "⛔ Le travail en cours de la copie entre en conflit avec main ; il reste dans la remise de git (git stash list)."
+      echo "Fichiers en conflit :"
+      sed 's/^/  /' <<<"$conflits"
+      exit 1
+    fi
+  fi
+  # The list the pose fixes is the one every mount gets, whatever the installation rewrites.
+  partages=$(bash "$ici/../sous-modules.sh" pose "$copie") || exit 1
+  monter() { bash "$ici/../sous-modules.sh" monter "$copie" --partages "$partages" "$@"; }
+  monter true || exit 1
+  if [ -f "$copie/package.json" ]; then
+    # --no-save leaves the lock file as committed, so a clean copy stays clean.
+    installe="$copie/node_modules/.package-lock.json"
+    if [ ! -d "$copie/node_modules" ] || [ "$copie/package-lock.json" -nt "$installe" ]; then
+      monter npm --prefix "$copie" install --no-save --no-audit --no-fund --silent || exit 1
+    fi
+    # The package of the session, when the component is a package of the frame: its name.
+    paquet=$(node --input-type=module -e "import path from 'node:path'; import { paquets } from '$ici/../paquets.mjs'; const [r, d] = process.argv.slice(1); const p = paquets(r).find(p => !p.hors && p.dossier === path.normalize(d).replace(/\/\$/, '')); process.stdout.write(p?.pkg.name ?? '');" "$copie" "$composant") || exit 1
+    if [ -z "$paquet" ]; then
+      (cd "$copie" && monter npx --no-install turbo run build) || exit 1
+    else
+      # Its providers: the packages whose build its own build waits for, as Turborepo reads them.
+      graphe=$(cd "$copie" && monter npx --no-install turbo run build "--filter=$paquet" --dry=json) || exit 1
+      # The graph comes on the standard input: as an argument, it may pass the size Linux allows one.
+      fournisseurs=$(node -e 'const [p] = process.argv.slice(1); const t = JSON.parse(require("node:fs").readFileSync(0, "utf8")).tasks.filter(t => t.taskId !== `${p}#build`); console.log([...new Set(t.map(t => `--filter=${t.package}`))].join("\n"));' "$paquet" <<<"$graphe") || exit 1
+      if [ -n "$fournisseurs" ]; then
+        mapfile -t filtres <<<"$fournisseurs"
+        (cd "$copie" && monter npx --no-install turbo run build "${filtres[@]}") || exit 1
+      fi
+      # The traces its tests wait for, as Turborepo's plan of its tests reads them. Another
+      # package's trace is produced here, and a failure stops the launch, as a provider's; its own
+      # waits for its own build, and is produced with it below.
+      plan=$(cd "$copie" && monter npx --no-install turbo run test:vitest "--filter=$paquet" --dry=json) || exit 1
+      traces() { node --input-type=module -e "import { readFileSync } from 'node:fs'; import { tracesDuPlan } from '$ici/../turbo-des-paquets.mjs'; const [p, propres] = process.argv.slice(1); console.log(tracesDuPlan(JSON.parse(readFileSync(0, 'utf8')), t => (t.package === p) === (propres === 'oui')).join('\n'));" "$paquet" "$1" <<<"$plan"; }
+      autres=$(traces non) || exit 1
+      if [ -n "$autres" ]; then
+        mapfile -t ids <<<"$autres"
+        (cd "$copie" && monter npx --no-install turbo run "${ids[@]}") || exit 1
+      fi
+      propres=$(traces oui) || exit 1
+      ids=()
+      [ -z "$propres" ] || mapfile -t ids <<<"$propres"
+      # The package itself, its own traces, and what its tests read (the shared test material),
+      # built after its providers: a failure does not stop the launch, it goes into the instruction.
+      # Each task whose dependencies succeed goes to its end (--continue=dependencies-successful):
+      # the package's failure does not cancel the build of what its tests read without depending
+      # on it, which the envelope shows read-only.
+      if ! (cd "$copie" && monter npx --no-install turbo run build ${ids[@]+"${ids[@]}"} "--filter=$paquet..." --continue=dependencies-successful) > "$echec" 2>&1; then
+        cat "$echec"
+        echo "⚠️  La construction de $paquet échoue : la séance s'ouvre, la consigne porte l'erreur."
+      else
+        : > "$echec"
+      fi
+    fi
+  fi
+) >> "$journal" 2>&1 || { rm -f "$echec"; echo "⛔ La copie $copie n'a pas pu être préparée : voir $journal." >&2; exit "$CODE_COPIE"; }
+# What the components before publish, read in the prepared copy, follows the instruction.
+publie=$(cd "$copie" && node "$ici/../index-interfaces.mjs" --publie "$composant" 2>> "$journal") \
+  || { rm -f "$echec"; echo "⛔ Ce que publient les composants d'avant n'a pas pu se lire : voir $journal." >&2; exit "$CODE_COPIE"; }
+# The session's working directory, the one the envelope gives as TMPDIR, follows them.
+travail=$(node --input-type=module -e "import { dossierDeTravail } from '$ici/enveloppe.mjs'; process.stdout.write(dossierDeTravail(process.argv[1]));" "$copie" 2>> "$journal") \
+  || { rm -f "$echec"; echo "⛔ Le dossier de travail de la séance n'a pas pu se lire : voir $journal." >&2; exit "$CODE_COPIE"; }
+dossier=$'\n\n'"## Ton dossier de travail"$'\n\n'"Tout fichier temporaire s'écrit dans \`$travail\`, que \`\$TMPDIR\` nomme aussi."
+construction=
+if [ -s "$echec" ]; then
+  construction=$'\n\n'"## La construction de ton paquet échoue"$'\n\n'"Ses fournisseurs et ce que ses tests lisent sans dépendre de lui sont construits ; sa propre construction échoue, et la réparer fait partie de ta tâche. La fin de sa sortie :"$'\n\n```\n'"$(tail -n 100 "$echec")"$'\n```'
+fi
+rm -f "$echec"
+# The prompt, assembled in a file: claude reads it on its standard input, since as an argument it
+# may pass the size Linux allows one (MAX_ARG_STRLEN, 128 KiB).
+# A resumed session holds the sections of its first instruction: only a failed build is news.
+prompt=$(mktemp)
+if [ -n "$reprise" ]; then
+  printf '%s' "$(cat "$consigne")$construction" > "$prompt"
+else
+  printf '%s' "$(cat "$consigne")"$'\n\n'"$publie$dossier$construction" > "$prompt"
+fi
+
+# The rights and the context of the role's session (scripts/droits.mjs), one option per line.
+droits=$(node "$ici/../droits.mjs" "$role" --racine "$racine" --copie "$copie" --ticket "$ticket" 2>> "$journal") \
+  || { rm -f "$prompt"; echo "⛔ Les droits de la séance n'ont pas pu se lire : voir $journal." >&2; exit "$CODE_COPIE"; }
+mapfile -t droits_du_role <<<"$droits"
+
+# The schema of the role's end-of-session sheet (scripts/resultats.mjs), for a role that has one:
+# the session ends on it, which claude writes in its JSON result, on the standard output.
+fiche=()
+schema=$(node "$ici/../resultats.mjs" --schema "$role" 2> /dev/null) || schema=
+[ -z "$schema" ] || fiche=(--output-format json --json-schema "$schema")
+
+# An envelope in error does not stop the launcher (set -e): its code is kept for the exit.
+code=0
+lancer_claude() {
+  node "$ici/enveloppe.mjs" "$copie" "$composant" "$role" -- \
+    "${CLAUDE_BIN:-claude}" -p --agent "$role" \
+    ${surcharge[@]+"${surcharge[@]}"} ${fiche[@]+"${fiche[@]}"} --permission-mode bypassPermissions \
+    "${droits_du_role[@]}" < "$prompt"
+}
+if [ -n "$schema" ]; then
+  lancer_claude > "$resultat" 2>> "$journal" || code=$?
+  { cat "$resultat"; echo; } >> "$journal"
+else
+  lancer_claude >> "$journal" 2>&1 || code=$?
+fi
+rm -f "$prompt"
+echo "$code" > "$fin"
+# The envelope ended: the session's line goes to the register from outside it, whatever its end hook did.
+node "$ici/../registre.mjs" --copie "$copie" >> "$journal" 2>&1 || true
+exit "$code"

package/scripts/etapes.mjs

@@ -0,0 +1,323 @@
+// The steps of a ticket, the tree of its circuit, as a pipeline of GitLab CI shows its stages and
+// their jobs and GitHub Actions its jobs and their steps, and the stops of its circuit: the one
+// list, which the circuit (scripts/circuit.mjs), the board (scripts/tableau.mjs), the bilan
+// (scripts/bilan.mjs) and the texts read.
+//
+// - A step (ETAPES): its number (« 2 », « 2.3 »), its title, who works there (`qui`: the role
+//   agents, or AUTO for a step the circuit leads itself; none for a step that only holds its
+//   sub-steps), its short form on the board's line where the roles' names do not hold in its
+//   width (`quiCourt`, the roles keeping their whole name everywhere else), whether it runs for each component of the ticket's title (`parComposant`), its
+//   sub-steps (`sous`), and the step of the circuit's state it is (`etat`: the `etape` of
+//   `.claude/worktrees/<ticket>.circuit.json`, the final pass being the checks once `finale`).
+//   A step that runs only for a project that declares it names the key of that declaration under
+//   `grillhouse` of the project's package.json (`declaration`): the board shows it only there.
+//   The opening reads its sub-steps elsewhere in the state: the survey of the components by its
+//   start while it runs (`releve`) and by its stop (`arrets`), the questioning of the plan by the questioning under way (`questionnement`)
+//   and by its stop. SUITE is the tree in its order, each step before its sub-steps.
+// - A step carries as many bounded loops as it needs (`boucles`): each its key (`cle`, which
+//   keys its count in the state's `boucles`), its label, its maximum (`max`, the pass that stops
+//   it; null for the components, whose number is the title's) and the sub-steps it spans (`sur`;
+//   the step and all its sub-steps without it): the components of the title, the testwriter's
+//   sessions after a refused proof, the developpeur's sessions with their checks, the rounds of
+//   a questioning, the reviews, the same stop come back after a RELANCE of the regulator. The
+//   circuit stops each loop at its maximum and writes its count in its state; the board shows
+//   « <label> <n>/<max> » on the ticket's line from the second pass.
+// - The arbitrage of a stop (ARBITRAGE) stands out of the sequence, under the stopped step: the
+//   regulator settles the stop, and the questionneur asks its questions of his decision before it
+//   is applied, as Amazon's bar raiser and a cockpit's challenge and response; it has no number.
+// - The stops of the circuit, each by its name and its exit code (ARRETS): the circuit ends on one
+//   with its code, and its header says when.
+// - The table of the stops (TABLE_DES_ARRETS, below): each kind of stop and its gesture.
+import { A_REPASSER } from './vitest-config/pression.mjs';
+
+// Who works at a step the circuit leads itself, with no agent.
+export const AUTO = 'auto';
+
+// The rounds of a questioning, of the plan at 1.2 and of a decision at the arbitrage.
+const TOURS = { cle: 'questionnement', libelle: 'tour', max: 4 };
+
+export const ETAPES = [
+  { numero: '0', titre: 'Exploration', qui: ['explorateur'], etat: null },
+  {
+    numero: '1',
+    titre: 'Ouverture',
+    qui: [],
+    etat: null,
+    sous: [
+      {
+        numero: '1.1',
+        titre: 'Relevé des composants',
+        qui: [AUTO],
+        etat: null,
+        releve: true,
+        arrets: ['composants-manquants'],
+      },
+      {
+        numero: '1.2',
+        titre: 'Questionnement',
+        qui: ['questionneur', 'referent-technique'],
+        quiCourt: 'questionneur ⇄ référent',
+        etat: null,
+        questionnement: 'plan',
+        arrets: ['questionnement'],
+        boucles: [TOURS],
+      },
+    ],
+  },
+  {
+    numero: '2',
+    titre: 'Composants',
+    qui: [],
+    parComposant: true,
+    etat: null,
+    boucles: [
+      { cle: 'composant', libelle: 'composant', max: null },
+      { cle: 'tests', libelle: 'essai', max: 3, sur: ['2.1', '2.2'] },
+      { cle: 'code', libelle: 'essai', max: 3, sur: ['2.3', '2.4'] },
+    ],
+    sous: [
+      {
+        numero: '2.1',
+        titre: 'Tests',
+        qui: ['testwriter'],
+        parComposant: true,
+        etat: 'testwriter',
+      },
+      { numero: '2.2', titre: 'Preuve du rouge', qui: [AUTO], parComposant: true, etat: 'preuve' },
+      {
+        numero: '2.3',
+        titre: 'Code',
+        qui: ['developpeur'],
+        parComposant: true,
+        etat: 'developpeur',
+      },
+      { numero: '2.4', titre: 'Contrôles', qui: [AUTO], parComposant: true, etat: 'controles' },
+    ],
+  },
+  {
+    numero: '3',
+    titre: 'Passe finale',
+    qui: [AUTO],
+    etat: 'controles',
+    finale: true,
+    sous: [
+      {
+        numero: '3.1',
+        titre: 'Régénération des références',
+        qui: [AUTO],
+        etat: 'references',
+        declaration: 'references',
+        arrets: ['references'],
+      },
+    ],
+  },
+  {
+    numero: '4',
+    titre: 'Relecture',
+    qui: ['relecteur'],
+    etat: 'relecture',
+    boucles: [{ cle: 'relecture', libelle: 'tour', max: 3 }],
+  },
+  {
+    numero: '5',
+    titre: 'Intégration',
+    qui: [],
+    etat: null,
+    sous: [
+      { numero: '5.1', titre: 'Commit', qui: [AUTO], etat: 'integration' },
+      { numero: '5.2', titre: 'File : main, poussée, CI', qui: [AUTO], etat: 'file' },
+    ],
+  },
+];
+
+// Every step and sub-step, in the order of the tree.
+export const SUITE = ETAPES.flatMap(e => [e, ...(e.sous ?? [])]);
+
+// The arbitrage of a stop, out of the sequence, under the stopped step.
+export const ARBITRAGE = {
+  numero: null,
+  titre: "Arbitrage de l'arrêt",
+  qui: ['regulateur', 'questionneur'],
+  etat: null,
+  boucles: [{ cle: 'arret', libelle: 'arrêt', max: 3 }, TOURS],
+};
+
+// The bounded loop of key <cle>.
+export const boucle = cle =>
+  [...SUITE, ARBITRAGE].flatMap(e => e.boucles ?? []).find(b => b.cle === cle) ?? null;
+
+// The loops that run at the step <etape>: those of the arbitrage at the arbitrage; else those of
+// each step that spans it, itself or its parent.
+export const bouclesDe = etape => {
+  if (etape === ARBITRAGE) return ARBITRAGE.boucles;
+  const parent = ETAPES.find(e => e === etape || e.sous?.includes(etape));
+  return [...new Set([parent, etape])]
+    .flatMap(e => e?.boucles ?? [])
+    .filter(b => (b.sur ? b.sur.includes(etape.numero) : true));
+};
+
+// The exit code of each stop of the circuit.
+export const ARRETS = {
+  lancement: 10,
+  bloqué: 11,
+  'sans-fiche': 12,
+  preuve: 13,
+  controles: 14,
+  'sans-livraison': 15,
+  'relecture-arret': 16,
+  integration: 17,
+  question: 18,
+  'hors-portee': 19,
+  besoin: 20,
+  'composants-manquants': 21,
+  questionnement: 22,
+  references: 23,
+  'a-repasser': A_REPASSER,
+};
+
+// The role that settles a stop of the circuit, and the one that questions a plan or a decision.
+export const REGULATEUR = 'regulateur';
+export const QUESTIONNEUR = 'questionneur';
+
+// A role in words.
+const NOMS = {
+  'referent-technique': 'référent technique',
+  regulateur: 'régulateur',
+  developpeur: 'développeur',
+};
+export const nomDuRole = role => NOMS[role] ?? role;
+
+// Who works at the step <e>, in words, « questionneur ⇄ référent »: its short form, else its
+// roles' names.
+export const quiDe = e => e.quiCourt ?? e.qui.map(nomDuRole).join(' ⇄ ');
+
+// The step <e> in words, « 2.3 Code ».
+export const libelle = e => `${e.numero} ${e.titre}`;
+
+// The step of a circuit's state (`etape`, `finale`, its stop `raison`, its questioning under way
+// `questionnement`, an object or its `objet`, the start of its survey of the components under way
+// `releve`), or null (« integre », an unknown step): the step
+// whose stop or questioning it is, else the step of its `etape`.
+export const etapeDuCircuit = ({ etape, finale, raison, questionnement, releve }) => {
+  const objet = questionnement?.objet ?? questionnement ?? null;
+  return (
+    SUITE.find(
+      e =>
+        (raison && e.arrets?.includes(raison)) ||
+        (objet && e.questionnement === objet) ||
+        (!raison && !objet && releve && e.releve)
+    ) ??
+    SUITE.find(
+      e =>
+        e.etat !== null &&
+        e.etat === etape &&
+        Boolean(e.finale) === (etape === 'controles' && finale === true)
+    ) ??
+    null
+  );
+};
+
+// The step where the role agent <role> works, the arbitrage for the regulator, or null for any
+// other agent.
+export const etapeDuRole = role =>
+  role === AUTO ? null : ([...SUITE, ARBITRAGE].find(e => e.qui.includes(role)) ?? null);
+
+// The step where a ticket's plan is questioned.
+const QUESTIONNEMENT_DU_PLAN = SUITE.find(e => e.questionnement === 'plan');
+
+// Whether the role agent <role> judges a plan or a stop (the questioning of the plan, the
+// arbitrage), and so delivers nothing to the lot.
+export const juge = role =>
+  [QUESTIONNEMENT_DU_PLAN, ARBITRAGE].some(e => role !== AUTO && e.qui.includes(role));
+
+// The table of the stops and their gesture: the written policy of the circuit's stops, as Zuul
+// and GitHub's merge queue write their bounded retries and their failure policy, and as the
+// sheriffs of Chromium quarantine a flaky test by a rule, not by a judgement. The circuit
+// (scripts/circuit.mjs) tries its lines in their order on each stop, and on the regulator's
+// decision: a gesture the table names, it applies itself, with no regulator; the regulator is
+// launched for what no line settles, and for the line that sends to him. Each line: `genre`, the
+// kind of stop as the circuit reads it in its structured results and its state; `geste`, what
+// follows; `cas`, the case of BPScript 320.3 (2026-10-20) it would have settled, by its stop (A)
+// or its decision (D) in the analysis of that ticket. The gestures (GESTES):
+// - `superviseur`: the circuit ends on the stop, its reason saying why, for the supervisor, with
+//   no regulator, and the board shows it under its step after « ⤷ Arrêt · superviseur »;
+// - `a-repasser`: the circuit ends at 75, which the supervisor plays again at rest;
+// - `regulateur`: a session of the regulator settles the stop;
+// - `developpeur-du-composant`: the red goes to the developpeur of the component that owns it,
+//   never to the one under way: it waits for that component's checks, or, at the final pass, the
+//   circuit relaunches that developpeur (the checks of scripts/circuit.mjs);
+// - `testwriter`: the circuit plays the component again from its testwriter.
+export const GESTES = [
+  'superviseur',
+  'a-repasser',
+  'regulateur',
+  'developpeur-du-composant',
+  'testwriter',
+];
+
+export const TABLE_DES_ARRETS = [
+  {
+    // A component the survey of the ticket finds and its title misses (21): the circuit ends on
+    // it at 1.1, before any session.
+    genre: 'composants-manquants',
+    geste: 'superviseur',
+    cas: 'A3 : 020-loader mis au titre en cours de route ; A14 : 040-checker, nommé au critère 13 et absent du titre, rouge à la première passe finale',
+  },
+  {
+    // A questioning of the plan that does not converge at 1.2 (22), a disagreement or a fourth
+    // round still questioned.
+    genre: 'questionnement',
+    geste: 'superviseur',
+    cas: 'A14 : 040-checker nommé au critère 13 et absent du titre, que le plan questionné aurait relevé ; D15 : une consigne neuve sur le fond, hors du plan',
+  },
+  {
+    // The same stop (its name, step and component) after a RELANCE, the copy and the ticket's
+    // description unchanged since that decision.
+    genre: 'meme-arret-sans-fait-nouveau',
+    geste: 'superviseur',
+    cas: 'A8 → A9 : RELANCE --reprendre sans contexte, le même arrêt sur la même copie (D9) ; A11 → A13 : le même rouge de la passe finale trois fois (D13, D14)',
+  },
+  {
+    // Checks whose failures all depend on a duration under load (verifier's 75), the integration
+    // at 75, or the branch kept in the queue.
+    genre: 'a-repasser',
+    geste: 'a-repasser',
+    cas: 'A12, A17, A18 : un vrai rouge pris pour la charge du processeur (D14, D20, D21) ; seul le code 75 du vérificateur dit la charge',
+  },
+  {
+    // A red whose findings are all to settle (SARIF `genre` a-arbitrer), which no developpeur
+    // settles.
+    genre: 'a-arbitrer',
+    geste: 'regulateur',
+    cas: 'A16 : la garde consommateurs-arbitres attend un arbitrage, que seul le régulateur écrit (D19, juste)',
+  },
+  {
+    // A red that belongs to another component of the title than the one whose checks run.
+    genre: 'rouge-d-un-autre-composant',
+    geste: 'developpeur-du-composant',
+    cas: 'A4, A6, A8–A10 : la garde des mots de 030-binder rendue aux développeurs de 050, 130 et 900 (D5, D7, D9–D11)',
+  },
+  {
+    // A developpeur's sheet whose `renvoi` names the testwriter of a component of the title up to
+    // his own.
+    genre: 'renvoi-au-testwriter',
+    geste: 'testwriter',
+    cas: 'A5, A7 : « Agent : testwriter » non lu, les tests périmés de 050 et de 130 (D6, D8) ; A2 (D2)',
+  },
+  {
+    // On the supervisor's answer to a question, a component the title gained since the stop.
+    genre: 'composant-ajoute',
+    geste: 'testwriter',
+    cas: 'A3 : 020-loader mis au titre, puis RELANCE testwriter 020-loader (D4) ; A14 : 040-checker, puis testwriter 040-checker (D17)',
+  },
+  {
+    // The ticket's description changed while the stop was settled, a criterion added: the circuit
+    // then admits only a RELANCE from a testwriter.
+    genre: 'critere-neuf',
+    geste: 'testwriter',
+    cas: 'D15 : une consigne neuve sur le fond donnée au développeur de 030-binder sans test (A14), rendue au testwriter de 040-checker (D17)',
+  },
+];
+
+// The line of the table for the kind of stop <genre>, or null.
+export const gesteDe = genre => TABLE_DES_ARRETS.find(l => l.genre === genre) ?? null;