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 genl’a écrite, et elle est encore telle que gen l’a écrite. Gen laisse un.archegen.jsondans son dossier de sortie : les fichiers qu’il a écrits, avec une empreinte par ligne. Un fichier sans manifeste mais avec une ligneGenerated by archecen 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.jsonlle 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 deARCHE_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 gena écrit (son.archegen.json, son genmap, ou un en-têteGenerated by archec) ne peut changer qu’entreUSER CODE BEGINetUSER CODE END. Le texte que gen écrit lui-même passe. Un fichierkeepest à 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 nouvelarchec 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 unfndu modèle qui lasatisfies(par son nom,stopouctrl_stoppourCtrl.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 gena é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.