Context, versioned

Git gave your code diff, log, hooks, CI. Your context never got the same tools — it lived in a doc that drifted. FAF changes that: project.faf is a git-native artifact. It versions with your code, so the context an agent reads always matches the commit it's working on.

Four commands give your context what your code has had for years.

Instant context from any repo — faf git

faf git owner/repo turns a GitHub repo into a scored project.faf in one command. Point it at a dependency, a reference implementation, or a repo you're about to work in, and an agent has accurate context in seconds.

faf git pallets/flask              # instant, scored context → project.faf
faf git pallets/flask --ref 3.0.0  # versioned — context at a specific tag

--ref pins the context to any branch or tag, so your context is versioned the same way your code is.

Diff your context — faf diff

A semantic diff for context: slot-by-slot deltas and the score change between two .faf versions. It reads git ranges the way git does — a ref, A..B, A...B.

faf diff HEAD~1        # against the previous commit
faf diff main..HEAD    # across a branch

It shows what moved — a filled slot, a changed command — and the score delta, e.g. 85% → 100% when a branch completes the picture. One flag wires it into git itself:

faf diff --install-driver

Now native git diff, git log -p, and git show render .faf score and slot deltas inline — context changes surface in the tools you already read.

The score timeline — faf log

faf log walks git history and reports the .faf score at every commit that touched it — your context quality as a line you can watch rise, or catch regressing, across the life of the project. The trend can't be gamed.

faf log            # the last 20 commits that touched the .faf
faf log --all      # the full history
faf log --reverse  # oldest-first

Guard it in pre-commit — faf hooks

faf hooks --install adds a pre-commit context guard: it scores the staged .faf against HEAD and warns on a regression. Add --strict and a regression blocks the commit.

faf hooks --install           # warn on a context-score regression
faf hooks --install --strict  # block the commit on a regression

Context stops rotting quietly, because a drop shows up before it lands — not three sprints later when an agent trusts the stale version.

In CI

The same commands gate a pipeline. Require a readiness threshold, surface what changed, and keep regressions off the branch:

• faf score — fail the build below your bar (target: Trophy 100%).
• faf diff main..HEAD — show the reviewer exactly what context moved.
• faf hooks --install --strict — regressions never reach the PR in the first place.

Context becomes something you can require, the way you require green tests.

Proof over time. faf log tracks your context score across commits; its sibling TAF does the same for your tests — an append-only receipt on every CI run, committed to a taf-receipts branch, git-anchored and impossible to game. Anyone can go green once; the timeline is the proof. → faf-taf-git

Why it matters

Git made code changes legible — diffable, reversible, attributable. FAF does the same for context: project.faf is versioned, diffable, and scored at every commit. The context an agent reads travels with the branch and matches the code, instead of drifting in a doc nobody updated.

Verified and true. Scored and recorded — at every commit. That's context, versioned.

Built under the WJTTC test discipline — Brake · Engine · Aero · Tyres — where every artifact's test ships in the same commit as the artifact. The proof travels with the change.

Further reading

• The format — the .faf spec (application/vnd.faf+yaml, IANA-registered).
• The AGENTS.md field guide — faf.one/agents.
• faf-cli — on npm (npx faf-cli git owner/repo).