More › ai-engineering

More

AI-assisted engineering, offline

An AI writes code fast. Someone still has to understand it after. Chris Loy's "The AI coding trap" puts it this way: a coding model is a very fast junior, and "if you can't explain why each part of a diff exists, it isn't ready to merge". His remedies are old ones: write the spec first, keep the design modular so each change needs little context, write the tests first, give the standards to the model as context, and pay back the comprehension debt.

arche-lang already holds the spec, the parts and their links, the requirements and the tests. This page says which commands keep AI-written code understood with that model. Every check here is local and deterministic: it runs offline, gives the same answer every time, and no verdict depends on an AI. Sending anything out is opt-in, through one gateway.

Loy's practices, and the commands#

Practice Commands
Spec first the model: requirements, parts, ports, links (docs/spec.md); archec check, archec ci
Modular design, small context the parts and the links between them; archec conform, archec arch-diff (docs/understand-code.md)
Tests first test plans traced to requirements; archec test, archec ci
Standards as context rules, archec vet, the USER CODE regions (docs/regeneration.md)
Know who wrote what archec provenance (docs/understand-code.md)
Nothing leaves unless you say so archec config (below)

Guard: keep an assistant inside its task#

Loy's practices: modular design to limit what the assistant touches; standards through context; a change you can explain. archec guard holds an assistant to them while it writes, and checks each commit the same way. It runs offline in every mode (offline, local-ai, online): it sends nothing and asks no model, so its verdict never depends on an AI.

Practice What guard refuses
Modular design, small context an edit to a code file of another part than the task's (.arche/task from archec brief, --part, ARCHE_TASK_PART)
The model is the spec a new import between two parts the model does not link (archec conform, on the changed files only)
Generated code is the model's a change to generated code outside its USER CODE regions
A person signs off an assistant writing reviews/approvals.yaml, or an approval's fingerprint rewritten with no new approval; an assistant's change that stales an approval is put to the person
archec guard install        # .claude/settings.json (PreToolUse) and .git/hooks/pre-commit
archec brief main.arche Car.brakes   # writes .arche/task: the assistant works on Car.brakes only

A refused edit comes back to the assistant with the reason and what to do instead (link Car.brakes and Car.ui in the model first). The same rules run at git commit (archec guard --staged). More: the guard.

Explaining a diff, and tests first: archec impact, archec ci --tests-first#

Loy's rule for comprehension debt: if you cannot say why each part of a diff exists, it is not ready to merge. His other rule: write the tests first. These two commands check both. They read git and the files only. They send nothing, in every mode.

Why each part of a diff exists#

archec impact main..HEAD          # a branch
archec impact --staged --md       # what you are about to commit, for the PR

For each hunk, archec says:

  • its part: the part whose source names the file;
  • the functions it touches, added, changed or removed;
  • the requirements traced to them: satisfies on the part's fn of that name, else on the part;
  • the tests that verify those requirements.

Then it lists what has no reason yet:

  • hunks in files no part names;
  • functions no requirement leads to.

Last comes the architecture change, as archec arch-diff gives it.

impact HEAD~1..HEAD
3 files, 3 hunks in code: 2 in a part, 1 in none; 1 requirement; 1 function no requirement leads to

App.calc
  src/calc/add.js:1-4: added add → REQ-ADD; outside functions
  src/calc/calc.js:5-8: added mul → no requirement; outside functions

Requirements
  REQ-ADD The calc shall add two numbers.
    tests: TC-ADD (test/add.test.js)

Functions no requirement leads to
  mul in App.calc (src/calc/calc.js:5)

Not in any part
  tools/x.js: 1 hunk, no part's `source` names it

architecture HEAD~1 → HEAD
…

Before you merge, give each line without a reason one: a requirement, a source, or a smaller diff.

Tests first#

archec ci main.arche --tests-first --range main..HEAD
archec ci main.arche --tests-first --prove-red

For each function the range adds (test files aside), the tests-first gate asks for:

  • a requirement on the function's fn or on its part;
  • a test case that verifies that requirement;
  • that case in the model, and its file in git, at the function's commit or before it.

A case's file is its source, or its label when the label is a path: case TC-ADD "test/add.test.js" { verifies REQ-ADD }.

--prove-red goes further. It checks out the commit before the function's in a temporary git worktree, puts the test there as it was at the function's commit, and runs it. The test must fail there. A test that passes before the code exists proves nothing. The worktree is removed after.

archec picks the command from the test file's language: node --test, python3 -m pytest, go test, cargo test. Give your own with --test-cmd "npm run build && node --test {file}".

The gate says apart the functions an AI assistant wrote (from the commit's trailer or author, or from the archec provenance markers) that have no requirement or no test. The verdict never depends on AI.

Comprehension debt: archec debt#

Loy's test: if you cannot explain why each part of a diff exists, it is not ready to merge. Code an AI assistant wrote and nobody understands is comprehension debt. archec debt measures it, part by part, from the repository alone.

archec debt main.arche                 # by part
archec debt main.arche --since main    # only what changed on this branch
archec approve main.arche Pump.ctrl --code --as "Cy"
archec ci main.arche --debt-max 20%    # fail when a part is over 20%

For each part it gives the share of its lines that are:

  • written by an AI assistant (archec provenance);
  • untraced: in a function no requirement leads to (spec first: name the requirement in a comment above the function, or make it a model fn that satisfies it);
  • not signed off: no person approved the file as it is now (archec approve <Part> --code, a fingerprint per file, stale when it changes).

It also counts the people who know the part: those who committed to its files (AI commits left out) and those who signed it off. A part one person or none knows is flagged.

A line is debt when an assistant wrote it, and no one signed it off or no requirement leads to it. archec diagram main.arche --overlay debt colours each block by its debt; archec doc --html --debt adds a chapter to the specification.

What it sends: nothing, in every mode. It reads the files, git log, git blame, .arche/provenance.jsonl and reviews/approvals.yaml. The verdict of archec ci --debt-max never depends on an AI.

See comprehension debt.

Context before code: archec brief and archec agent-context#

An assistant writes better code when it is given the right small context, not the whole repository. The model already says what that context is. Both commands read the model and the files beside it. They send nothing anywhere, in every mode.

archec brief gives one part's context, before the part is changed:

archec brief main.arche Car.brakes --task
  • its interface: ports and functions, as written;
  • its neighbours' interfaces, never their code;
  • the requirements traced to it, and the cases that verify each one (or a line saying that no test does yet: write it first);
  • the parts it may depend on: the model's links. Any other import is a divergence that archec conform and archec ci refuse;
  • the files it owns (source), and the USER CODE regions it may edit in the generated code;
  • the budgets, chains and rules that apply, and what check and vet say now;
  • a model fingerprint: it changes when the model changes what the part may do.

--task writes .arche/task beside the model:

{ "part": "Car.brakes", "fingerprint": "3f0c…", "files": ["src/brakes/abs.c"] }

archec guard reads it to refuse an edit to another part's files. --clear-task removes it. In archec mcp, the tool brief does the same (task: true writes the file).

archec agent-context writes the project's context into CLAUDE.md or AGENTS.md:

archec agent-context main.arche -o CLAUDE.md

It writes the architecture, the allowed dependencies, where hand-written code goes and the conventions. They go between two markers; your own text around them is kept. The block comes from the model alone, so it reads the same on every machine. archec ci fails its agent-context gate when the block is out of date.

How this follows the practices of "The AI coding trap" (Chris Loy):

Practice Here
Spec first The brief lists the requirements of the part and their tests, and says when a requirement has none.
Modular design, to limit context The brief is one part: its interface, its neighbours' interfaces, its own files.
Tests first A requirement with no case is shown as "no test verifies it yet".
Standards through context agent-context puts the architecture and the conventions where the assistant reads them.
Comprehension debt The task file and the fingerprint tie each change to one part of the model.

What leaves the machine#

Nothing, by default. archec is offline unless you say otherwise. Every call out of the machine goes through one module (src/egress.ts), and a test proves that no command reaches the network when offline.

The modes#

Mode What the AI commands do Set it with
offline (the default) Nothing goes to any model. review, live-fix and new --describe are refused and say how to allow them; everything else works. nothing, or archec config ai offline, or --offline
local-ai The AI commands ask a model on this machine: Ollama (http://localhost:11434, the default) or llama.cpp's server (http://localhost:8080), both speak the Anthropic Messages API. Nothing leaves the machine. archec config ai local-ai, then archec config local-ai http://localhost:11434 qwen3-coder; or --ai local-ai
online The AI commands send to the Anthropic API (Claude). archec config ai online, or --ai online

The mode is about the AI only. The other services (a store, Polarion…) each need their own allow, in every mode. A call to this machine (localhost, 127.0.0.1) does not leave it: it is allowed, and logged.

What each command sends, and where#

Command Service Sends To Allow it with
archec review claude each traced element's kind, id, name and texts the Anthropic API (or the local model) archec config ai online (or ai local-ai)
archec live-fix claude the failing live item, what was measured, the declarations involved as written the Anthropic API (or the local model) archec config ai online (or ai local-ai)
archec new --describe claude your sentence, a language summary, the boards' names, archec check's messages the Anthropic API (or the local model) archec config ai online (or ai local-ai)
archec add, search, audit, publish, store info/fetch/outdated/diff/deps/login/request/star/discuss/yank/review, new --from, new --template owner/name store the package names asked for, a token; publish sends the package the store: the hosted one is https://store.arche-lang.xyz, else --store, ARCHE_STORE, archec store use archec config allow store https://store.arche-lang.xyz
the same, with a git store index store a git clone / git pull of the index the git host archec config allow store <git URL>
archec polarion pull polarion the project id and query, the token the Polarion server in polarion.yaml archec config allow polarion
archec parts check parts the BOM's part numbers, the API key Nexar, Digi-Key or Mouser archec config allow parts
archec issues (open, sync, resolve) issues issue titles and texts: the failing requirement, test or live item Jira, GitHub or GitLab, as configured archec config allow issues
archec lib fetch libraries git ls-remote, git clone of each library the library's git host archec config allow libraries
archec add of a signed package sigstore the bundle, through cosign verify-blob Sigstore (Rekor, its trust root) archec config allow sigstore; refused, the signature is read but not verified
archec store serve with GitHub sign-in github the sign-in code, then /user and /user/orgs GitHub archec config allow github (or ARCHE_ALLOW=github for the server)

A local store (a folder), a git index on this machine and libraries in folders send nothing.

A refused call says what blocked it and the one line that allows it:

archec: not sent to store.arche-lang.xyz (store): nothing goes out unless you allow it.
  To allow it: archec config allow store https://store.arche-lang.xyz
  (or for this command only: --allow store=https://store.arche-lang.xyz)

Where the settings come from#

Four places. The strictest wins.

  1. The organisation policy: the file ARCHE_POLICY names, else /etc/arche/policy. Lines ai offline, allow store https://store.acme.corp, deny claude, deny all, private "secret/**"; # starts a comment.

  2. The project, in main.arche:

    project "Brake controller" {
      ai local-ai                          // at most a model on this machine
      allow store "https://store.acme.corp" // the only store it may reach
      deny issues                           // never, whatever you allow
      private "proprietary/**", "*.key"     // never sent
    }
  3. Your config, ~/.arche/config.json, written by archec config. It is not read in CI (when the CI variable is set).

  4. The command line: --offline (nothing at all), --ai offline|local-ai|online, --allow service[=url]. ARCHE_AI and ARCHE_ALLOW ("store=https://…,parts") in the environment count as flags: use them in CI.

The policy and the project only restrict: their ai is a ceiling, their deny always wins, and an allow with a URL is the only place that service may go. They never turn anything on, so cloning a repository never makes archec send anything. Your config and the command line grant: the mode, and each allow.

archec config shows the mode in effect, where it comes from, and each layer. archec config test store https://store.arche-lang.xyz says whether that call would go out, and why.

What is kept#

  • .arche/egress.log beside main.arche (else ~/.arche/egress.log): one line per call sent: the time, the service, the host, the bytes sent, what for, and the files whose content went. Once it is there, refused calls are added too (a refusal alone writes nothing into the project).
  • --show-sent prints each request as it goes (secrets hidden).
  • --dry-run sends nothing: the AI commands print their whole request.
  • private files are never sent: a call that would carry one is refused.
  • A command that sent something ends with one line on stderr: archec: sent 1 request(s), 14.2 kB, to api.anthropic.com (claude) — logged in .arche/egress.log.

Breaking change#

Until 0.12.1, the commands in the table above called out when they ran. Now archec is offline by default: run the "Allow it with" line once, or pass the flag for one run.

Limits#

  • The gateway guards archec's own calls. Tools archec starts are not watched: podman in archec live may pull images, and the Arche app's Pull and Push buttons run git on the project's own remote.
  • private stops a call that names a private file. It does not read the text that is sent: a private file's text copied into a public one goes.
  • local-ai needs a server that speaks the Anthropic Messages API (Ollama, llama.cpp). A small local model may answer worse than Claude; the answers stay advice either way.
  • A hosted store that offers GitHub sign-in needs allow github (or ARCHE_ALLOW=github) on the server.