Référence › Commandes › Provenance

Référence › Commandes

Provenance

Les commandes qui indiquent qui a écrit chaque morceau de code, et qui le comprend.

Commandes : archec provenance · archec guard · archec debt

Sur cette page : Le hook Claude Code · Le garde · La dette de compréhension

Qui a écrit le code : le modèle, un assistant IA ou une personne. Chaque ligne d’un fichier de code reçoit l’une de ces quatre origines :

  • générée : archec gen l’a écrite, et elle est encore telle que gen l’a écrite. Gen laisse un .archegen.json dans son dossier de sortie : les fichiers qu’il a écrits, avec une empreinte par ligne. Un fichier sans manifeste mais avec une ligne Generated by archec en tête compte comme entièrement généré.
  • IA : un assistant IA l’a écrite. Le commit qui a modifié la ligne en dernier le dit : un trailer Co-Authored-By: qui nomme un assistant (Claude, Copilot, Codex, Cursor, Gemini, Aider, Devin…), Generated-by: (autre qu’archec), Assisted-by:, AI-assisted: yes, ou l’adresse d’un assistant comme auteur. Ou bien un marqueur dans .arche/provenance.jsonl le dit.
  • modifiée après gen : gen a écrit le fichier, et une personne a changé cette ligne depuis.
  • humaine : tout le reste.

Les lignes viennent de git blame : chaque ligne compte pour le commit qui l’a modifiée en dernier. Hors d’un dépôt git, il ne reste que les marqueurs et les manifestes de gen.

Commande Ce qu’elle fait
archec provenance <main.arche|folder|file…> [--json] [--since <rev>] [--model] [--html -o page.html] La part des lignes de chaque origine, par part du modèle et par fichier. Avec un modèle : les fichiers que nomment ses parts (source, code, implements "glob"), avec ceux de leurs parts, et les fichiers de code à côté de lui. Un fichier généré qui nomme un élément (@arche Ctrl, ou une genmap) va avec cette part. Les fichiers écrits par un assistant IA, et où personne n’a commité depuis, sont marqués ! not reviewed et listés à la fin (un trailer Reviewed-by: sur le commit de l’assistant compte comme une relecture). --since <rev> : seulement les lignes modifiées après ce commit. --model : les fichiers .arche aussi. --html : une page à part. Code de sortie 0 dans tous les cas.
archec audit <main.arche> --authors [--json] [--since <rev>] Identique à archec provenance <main.arche>.
archec provenance mark <file> [--lines a-b] --tool <name> [--model <m>] [--session <s>] Déclare qu’un assistant a écrit ces lignes (tout le fichier sans --lines). Le marqueur garde une empreinte de chaque ligne : il les retrouve même après que d’autres les ont déplacées. Une ligne qu’une personne a changée depuis lui revient. Pour les assistants sans hook.
archec provenance mark --commit <sha> --tool <name> Déclare qu’un assistant a fait ce commit, quand son message ne le dit pas.
archec provenance hook Lit un événement PostToolUse de Claude Code sur stdin (Edit, MultiEdit, Write) et marque les lignes que l’assistant a ajoutées. N’échoue jamais.
archec guard hook [--main m.arche] [--part P] Lit un événement PreToolUse de Claude Code sur stdin (Edit, MultiEdit, Write) et refuse la modification, avec la raison, quand elle enfreint les règles du modèle. Voir Le garde. Sans rien dire, il laisse la modification se faire.
archec guard --staged [--main m.arche] [--part P] [--json] Les mêmes vérifications sur ce qui est indexé, comme hook git pre-commit. Code de sortie 1 quand quelque chose est refusé.
archec guard install [--command "npx archec"] [--claude | --git] Écrit les deux hooks : l’entrée PreToolUse dans .claude/settings.json et .git/hooks/pre-commit. Relancez-la : rien n’est ajouté deux fois.
archec diagram <main.arche> [view] --overlay provenance [--since <rev>] Chaque bloc coloré selon qui a écrit la plus grande partie de son code (généré en bleu, IA en ambre, modifié en violet, humain en vert), avec les proportions écrites dessus et une barre qui les résume, en SVG.
archec doc <main.arche> --html|--md --provenance La spécification, avec un chapitre « Who wrote the code » : les mêmes tableaux.
archec debt <main.arche> [--since <rev>] [--json] La dette de compréhension, par part : la part de ses lignes qu’un assistant IA a écrites, dans une fonction à laquelle aucune exigence ne mène, et non validées ; les personnes qui la connaissent, une part connue d’une seule personne ou de personne étant signalée. Voir La dette de compréhension. Code de sortie 0 dans tous les cas : c’est archec ci --debt-max qui sert d’étape.
archec diagram <main.arche> [view] --overlay debt [--since <rev>] Chaque bloc coloré selon sa dette : vert jusqu’à 10 %, ambre jusqu’à 30 %, rouge au-delà ; la dette, la part d’IA et le nombre de personnes écrits dessus.
archec doc <main.arche> --html|--md --debt La spécification, avec un chapitre « Comprehension debt » : le tableau par part, et les fonctions écrites par une IA auxquelles aucune exigence ne mène.

Le hook Claude Code#

Ajoutez ceci à .claude/settings.json dans le projet. Après chaque modification, il note dans .arche/provenance.jsonl les lignes que Claude a écrites :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "archec provenance hook" }]
      }
    ]
  }
}

Si archec n’est pas dans le PATH, copiez tools/provenance/claude-hook.mjs dans .claude/hooks/ et utilisez "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/claude-hook.mjs". Il n’a besoin que de node. ARCHE_AI_TOOL et ARCHE_AI_MODEL fixent l’outil et le modèle qu’il enregistre.

Commitez .arche/provenance.jsonl avec le code, pour que les autres voient la même chose. Une ligne de ce fichier :

{"file":"src/plan.c","lines":[4,6],"hashes":["a1b2c3d4","…"],"tool":"claude-code","session":"…","time":"2026-11-10T12:00:00Z"}

hashes contient les 8 premiers chiffres hexadécimaux du SHA-1 de chaque ligne écrite, sans les espaces en début et en fin. Un marqueur ne compte pour une ligne que si la ligne a le même texte et n’a pas été commitée avant l’heure du marqueur.

Le garde#

archec guard vérifie un changement par rapport au modèle avant qu’il n’arrive. Il tourne sur votre machine, ne lit que le projet, et donne la même réponse à chaque fois. Aucune IA ne décide de rien.

Il refuse quatre choses :

  • Le fichier d’une autre part. La tâche nomme une part. Un fichier de code dont la part (d’après source) est une autre part est refusé. La tâche vient de --part, sinon de ARCHE_TASK_PART, sinon de .arche/task. archec brief écrit ce fichier en JSON : { "part": "Car.brakes", "fingerprint": "…", "files": [...] }. Les fichiers qu’il liste sont autorisés quelle que soit leur part. Sans tâche, cette vérification est désactivée.
  • Du code généré hors de ses régions. Un fichier qu’archec gen a écrit (son .archegen.json, son genmap, ou un en-tête Generated by archec) ne peut changer qu’entre USER CODE BEGIN et USER CODE END. Le texte que gen écrit lui-même passe. Un fichier keep est à vous, et n’est pas vérifié.
  • Un nouvel import que le modèle n’autorise pas. Un import d’une part vers une autre a besoin d’un lien entre elles, comme dans archec conform. Seuls les fichiers modifiés sont lus, et seuls les imports que le changement ajoute comptent.
  • Une approbation gardée à jour alors que son élément a changé. Un assistant ne peut pas écrire reviews/approvals.yaml. Dans un commit, l’empreinte d’une approbation modifiée à une date ancienne, sans nouvel archec approve, est refusée.

Quand la modification d’un assistant change un élément approuvé, le hook demande à la personne (ask). L’approbation devient périmée ; approuvez à nouveau après relecture. Dans un commit, la même chose donne un avertissement.

Installez les deux hooks :

archec guard install

Cela ajoute à .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "archec guard hook" }]
      }
    ]
  }
}

et archec guard --staged || exit 1 à .git/hooks/pre-commit. Une modification refusée reçoit cette réponse, que Claude Code montre à l’assistant :

{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"archec guard refused this edit:\n- src/a/a.ts:2 imports '../c/c' (Sys.c): Sys.a → Sys.c, a dependency the model has no link for: link Sys.a and Sys.c in the model first (a person decides), or go through a part they are linked to"}}

ARCHE_GUARD=off désactive le hook pour une session. git commit --no-verify saute le hook pre-commit. Le hook ne bloque jamais une modification à cause de sa propre erreur : il le dit sur stderr et laisse la modification se faire.

La dette de compréhension#

Le code qu’un assistant a écrit est une dette tant qu’une personne ne le comprend pas. archec debt la mesure par part, à partir du dépôt seul : rien n’est envoyé nulle part.

archec debt main.arche
Comprehension debt — 3 part(s), 23 line(s)
  debt 13% · AI 13% · untraced 30% · not signed off 100%

  part    lines    AI  untraced  unsigned  people   debt
  Ctrl       11   27%       27%      100%  1 !       27%
  Sensor     12    0%       33%      100%  2          0%
  Pump       23   13%       30%      100%  2         13%

AI-written functions no requirement leads to (1) — name the requirement in a comment, or `satisfies` on its fn
  src/ctrl.ts:9  extra  3 AI line(s)

Known by one person or none (1) — the people who edited it (no AI commits) or signed it off
  Ctrl  Ada

Sign off a part's code once you can explain it: archec approve main.arche Ctrl --code --as "<name>"

Pour chaque part (les fichiers que nomme sa source, avec ceux de ses parts), la proportion de ses lignes qui sont :

  • AI : un assistant IA les a écrites (selon archec provenance).
  • untraced : elles sont dans une fonction à laquelle aucune exigence ne mène. Une exigence mène à une fonction quand la fonction, ou le commentaire au-dessus, nomme l’id de l’exigence (// Implements REQ-1) ; quand la fonction est un fn du modèle qui la satisfies (par son nom, stop ou ctrl_stop pour Ctrl.stop, dans un fichier de ce composant ; ou @arche Ctrl.stop, ARCHE_IMPL("Ctrl.stop")) ; ou quand elle contient une région USER CODE d’un tel fn. Les lignes hors des fonctions ne comptent pas comme untraced.
  • unsigned : aucune personne n’a validé le fichier tel qu’il est maintenant. Les lignes qu’archec gen a écrites sont celles du modèle, et sont laissées de côté.

Les people sont celles qui ont commité dans les fichiers de la part (commits d’IA exclus) ou qui ont approuvé la part. ! signale une part qu’une seule personne connaît, ou personne.

Une ligne est une dette quand un assistant IA l’a écrite, et que personne ne l’a validée ou qu’aucune exigence ne mène à sa fonction.

Validez le code d’une part quand vous savez en expliquer chaque ligne :

archec approve main.arche Pump.ctrl --code --as "Cy"

Cela enregistre une empreinte de chacun de ses fichiers dans reviews/approvals.yaml. Quand un fichier change, l’approbation est périmée (archec approvals --stale nomme les fichiers) ; les fichiers qui n’ont pas changé restent validés.

--since <rev> ne compte que les lignes modifiées après ce commit, et les personnes qui ont commité depuis. archec ci main.arche --debt-max 20% échoue quand une part a plus de 20 % de dette.