Reference › Commands › Provenance

Reference › Commands

Provenance

The commands that tell who wrote each piece of code, and who understands it.

Commands: archec provenance · archec guard · archec debt

On this page: The Claude Code hook · The guard · Comprehension debt

Who wrote the code: the model, an AI assistant, or a person. Each line of a code file gets one of four origins:

  • generated: archec gen wrote it, and it is still what gen wrote. Gen leaves .archegen.json in its output folder: the files it wrote, with a fingerprint per line. A file with no manifest but a Generated by archec line at the top counts as generated whole.
  • AI: an AI assistant wrote it. The commit that last changed the line says so: a Co-Authored-By: trailer naming an assistant (Claude, Copilot, Codex, Cursor, Gemini, Aider, Devin…), Generated-by: (not archec), Assisted-by:, AI-assisted: yes, or an assistant's address as author. Or a marker in .arche/provenance.jsonl says so.
  • edited after gen: gen wrote the file, and a person changed this line since.
  • human: the rest.

The lines come from git blame, so each line counts for the commit that last changed it. Outside a git repository, the markers and the gen manifests are all there is.

Command What it does
archec provenance <main.arche|folder|file…> [--json] [--since <rev>] [--model] [--html -o page.html] The share of lines of each origin, by part of the model and by file. With a model: the files its parts name (source, code, implements "glob"), with those of their parts, and the code files beside it; a generated file that names an element (@arche Ctrl, or a genmap) goes with that part. The files an AI assistant wrote that no person committed to since are marked ! not reviewed and listed at the end (a Reviewed-by: trailer on the assistant's commit counts as a review). --since <rev>: only the lines changed after that commit. --model: the .arche files too. --html: a page of its own. Exit 0 all the same.
archec audit <main.arche> --authors [--json] [--since <rev>] The same as archec provenance <main.arche>.
archec provenance mark <file> [--lines a-b] --tool <name> [--model <m>] [--session <s>] Say an assistant wrote these lines (the whole file without --lines). The marker keeps a fingerprint of each line, so it still finds them after others moved them; a line a person changed since is theirs. For assistants with no hook.
archec provenance mark --commit <sha> --tool <name> Say an assistant made this commit, when its message does not.
archec provenance hook Reads a Claude Code PostToolUse event on stdin (Edit, MultiEdit, Write) and marks the lines the assistant added. Never fails.
archec guard hook [--main m.arche] [--part P] Reads a Claude Code PreToolUse event on stdin (Edit, MultiEdit, Write) and refuses the edit, with the reason, when it breaks the model's rules. See The guard. Nothing said: the edit goes on.
archec guard --staged [--main m.arche] [--part P] [--json] The same checks on what is staged, as a git pre-commit hook. Exit 1 when something is refused.
archec guard install [--command "npx archec"] [--claude | --git] Writes both hooks: the PreToolUse entry in .claude/settings.json and .git/hooks/pre-commit. Run it again: nothing is added twice.
archec diagram <main.arche> [view] --overlay provenance [--since <rev>] Each block coloured by who wrote most of its code (generated blue, AI amber, edited purple, human green), the shares written on it, and a bar of them in SVG.
archec doc <main.arche> --html|--md --provenance The specification with a chapter "Who wrote the code": the same tables.
archec debt <main.arche> [--since <rev>] [--json] Comprehension debt, by part: the share of its lines an AI assistant wrote, in a function no requirement leads to, and not signed off; the people who know it, a part with one or none flagged. See Comprehension debt. Exit 0 all the same: archec ci --debt-max is the gate.
archec diagram <main.arche> [view] --overlay debt [--since <rev>] Each block coloured by its debt: green up to 10%, amber up to 30%, red above; the debt, the AI share and the number of people written on it.
archec doc <main.arche> --html|--md --debt The specification with a chapter "Comprehension debt": the table by part, and the AI-written functions no requirement leads to.

The Claude Code hook#

Add this to .claude/settings.json in the project. After each edit, it notes the lines Claude wrote in .arche/provenance.jsonl:

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

Without archec on the PATH, copy tools/provenance/claude-hook.mjs into .claude/hooks/ and use "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/claude-hook.mjs". It needs only node. ARCHE_AI_TOOL and ARCHE_AI_MODEL set the tool and model it records.

Commit .arche/provenance.jsonl with the code, so others see the same. A line of it:

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

hashes are the first 8 hex digits of the SHA-1 of each line written, trimmed. A marker counts for a line only when the line has the same text and was not committed before the marker's time.

The guard#

archec guard checks a change against the model before it lands. It runs on your machine, reads only the project, and gives the same answer each time. No AI decides anything.

It refuses four things:

  • Another part's file. The task names one part. A code file whose part (by source) is another part is refused. The task comes from --part, else ARCHE_TASK_PART, else .arche/task. archec brief writes that file as JSON: { "part": "Car.brakes", "fingerprint": "…", "files": [...] }. The files it lists are allowed whatever their part. With no task, this check is off.
  • Generated code outside its regions. A file archec gen wrote (its .archegen.json, its genmap, or a Generated by archec header) may change only between USER CODE BEGIN and USER CODE END. The text gen itself writes passes. A keep file is yours, and is not checked.
  • A new import the model does not allow. An import from one part to another needs a link between them, as in archec conform. Only the changed files are read, and only the imports the change adds count.
  • An approval kept current while its element changed. An assistant may not write reviews/approvals.yaml. In a commit, an approval's fingerprint changed on an old date, with no new archec approve, is refused.

When an assistant's edit changes an approved element, the hook asks the person (ask). The approval goes stale; approve it again after review. In a commit, the same is a warning.

Install both hooks:

archec guard install

This adds to .claude/settings.json:

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

and archec guard --staged || exit 1 to .git/hooks/pre-commit. A refused edit gets this answer, which Claude Code shows to the 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 turns the hook off for a session. git commit --no-verify skips the pre-commit hook. The hook never blocks an edit because of its own error: it says so on stderr and lets the edit go on.

Comprehension debt#

Code an assistant wrote is debt until a person understands it. archec debt measures it per part, from the repository alone: nothing is sent anywhere.

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>"

For each part (the files its source names, with its parts'), the share of its lines that are:

  • AI: an AI assistant wrote them (as archec provenance says).
  • untraced: they are in a function no requirement leads to. A requirement leads to a function when the function, or the comment above it, names the requirement's id (// Implements REQ-1); when the function is a model fn that satisfies it (by name, stop or ctrl_stop for Ctrl.stop, in a file of that component; or @arche Ctrl.stop, ARCHE_IMPL("Ctrl.stop")); or when it holds a USER CODE region of such a fn. Lines outside functions are not counted as untraced.
  • unsigned: no person signed the file off as it is now. Lines archec gen wrote are the model's, and are left out.

people are those who committed to the part's files (AI commits left out) or approved the part. ! marks a part one person or none knows.

A line is debt when an AI assistant wrote it, and no one signed it off or no requirement leads to its function.

Sign a part's code off once you can explain each line of it:

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

This records a fingerprint of each of its files in reviews/approvals.yaml. When a file changes, the approval is stale (archec approvals --stale names the files); the files that did not change stay signed off.

--since <rev> counts only the lines changed after that commit, and the people who committed since. archec ci main.arche --debt-max 20% fails when a part has more than 20% debt.