🧬 FIA HARNESS

AI agents don't fail at writing code — they fail at staying on track. FIA Harness turns "spec, discipline and no fake results" from good intentions into merge checks no agent can skip. Local, zero-dependency, LLM-agnostic.

Python 3.8+ · Zero external dependencies · Single or multi-agent · 2 working modes · Rules verified in CI · LLM-agnostic (Claude, DeepSeek, GPT, OpenCode — whatever agent you use)

📖 Español: README.es.md

⚡ What problem does it solve

An agent with a spec and a conscience still drifts: it closes a phase it never finished, relaxes its own rules, or writes a report full of tests that never ran. Chat prompts and "trust me" workflows can't stop that.

FIA Harness makes the project state a machine-validated datum and refuses to let the agent self-certify in silence:

The full history is never re-sent: each phase loads only a handful of compressed control files. Small context = cheaper, faster answers with less drift.

⚡ Install in one command

uvx fia-harness init        # or: pipx run fia-harness init

Sets up a new project instantly: kit templates in /docs, the two scripts at the root and a starter PRD.md. Then python bootstrap.py and you're on rails. Prefer cloning? This repo is a GitHub template — click Use this template.

🎬 See the interlock catch the agent (60 seconds)

The rules here are not advice — they are merge checks that no agent can skip. The fia-harness-demo repo is a real, small project whose CI blocks a cheater agent that tries to close a phase without its task file or checkpoint:

git clone https://github.com/mcpedrogm-art/fia-harness-demo.git && cd fia-harness-demo
python task_generator.py --check     # ✅ green
copy PROGRESS.F2_tampered.md PROGRESS.md
python task_generator.py --check     # ❌ exit 1 — the merge is blocked

🧭 The mental model (3 steps)

1. THINK   — PRD → interview (M1) → SPEC.md approved by a human (M2). No code yet.
2. PLAN    — the spec is sliced into small verifiable phases F0…Fn (M3).
3. BUILD   — one phase = one task = one closed cycle: audit → design → code → verify.

Every transition leaves a validated artifact: PROGRESS.md is the editing surface, progress.json is the compiled truth the CI reads. Editing the Markdown without re-compiling turns CI red.

⚙️ How it works: three engines

1️⃣ Process phases (M0–M3) — think before building

🚫 Until M3 closes, not a single line of production code is written.

2️⃣ Execution phases (F0–Fn) — build phase by phase

Each planned phase = one task = one complete, closed cycle. Typical plan:

task_generator.py auto-detects the first pending phase and generates its task. You decide when to start the next one; the agent never chains phases alone.

3️⃣ The task cycle (A–L) — discipline inside every phase

A. Audit → B. Design → C. Hypotheses → E. Implementation → F. Edge cases
→ I. Tests → J2. Security → H2. Visibility → H3. UI/UX → K. Validation → L. Report

Security (J2), visibility (H2) and UI/UX (H3) are injected automatically only if the phase needs them, with the real, living content of your SECURITY.md, AEO_GEO_SEO.md and UI_UX_EXCLUSIVA.md. If they don't apply, the generator says so explicitly — never omitted in silence.

🚀 Getting started in 4 steps

⚡ Or in one command (PyPI): uvx fia-harness init mounts the new project automatically — templates in /docs, scripts at the root, starter PRD.md. Skip to step 2.

1. Prepare the new project
   ├── bootstrap.py + task_generator.py at the root
   ├── /docs with the master templates
   ├── (optional) RAG_VECTOR_EXTENSION.md inside /docs if there will be semantic search
   └── PRD.md at the root

2. python bootstrap.py          → automatic Phase M0
   Generates CONTEXT.md, PROGRESS.md, progress.json, DECISIONS.md,
   activates the templates and emits .github/workflows/harness.yml

3. Open your agent with the folder → the interview starts (M1)
   The agent reads CONTEXT.md and does NOT code anything yet.

4. Approve SPEC.md, paste the F0-Fn table into PROGRESS.md and compile:
   python task_generator.py --sync   → validates the state into progress.json
   python task_generator.py          → generates the task for the pending phase

📖 Step-by-step guide: INSTRUCCIONES DE APLICACION.txt (ES) · Full protocol: INICIO_PROYECTO.md (ES)

📁 File map

⚡ Two working modes

Automatic promotion to Full if any of these appear: auth/roles, payments, PII/health, critical migrations, writes to external services, deploy/secrets, uncertain scope. Promotion keeps the already-validated work.

To enable Lite: declare Modo de trabajo: Lite in CONTEXT.md (detected automatically by task_generator.py) or force it with --lite.

🧩 Conditional modules

The base harness is common; these layers activate only when a project needs them:

🚨 Enforcement: the rules have teeth

Since v2, the harness enforces by infrastructure, not just by convention. bootstrap.py emits a GitHub Actions workflow that runs on every push and PR:

State flow: PROGRESS.md is the editing surface (human or agent); task_generator.py --sync compiles and validates it into progress.json. If you edit the Markdown by hand and don't compile, CI turns red until you run --sync. And --sync is fail-closed: if the state violates a rule, it writes nothing.

python task_generator.py --sync      # compile & validate PROGRESS.md -> progress.json
python task_generator.py --check     # validate without modifying (CI runs this)
python task_generator.py --seal      # seal the normative docs (SHA-256)
python task_generator.py --approval "install Skill X v1.2" --phase F2 --ref "chat 5-sep"
python task_generator.py --reopen F3 --reason "found a regression in auth"

🛡️ The rules that never break

1. 🚫 Never code without an approved spec — not a line before M3.
2. 🗣️ Never assume in silence — every assumption is declared and confirmed.
3. 📦 Never re-send unnecessary context — the control files are the compressed source.
4. ✅ Never close a phase without its Definition of Done — and never mix phases.
5. 🔐 Never close a security phase without its checklist — security is not postponed to a final audit.
6. 🙋 Never install/search/connect a Skill, MCP or library without human approval — silence is not permission.
7. 🧪 Never invent results — tests that didn't run don't exist.
8. 🛑 Never commit/push/deploy without explicit authorization.

🚨 Since v2, rules 4, 5, 7 and 8 are also verified automatically in CI on every project that starts with bootstrap.py (previous section).

⚠️ Limitations — what the CI cannot guarantee

The harness raises the cost of drifting from trivial to deliberate and traceable, but it is not a tamper-proof boundary. Be aware of its edges:

• It trusts the machine, not the person. The agent and the validator share the same local filesystem and shell. A malicious actor with full write access could re-seal a doc or fabricate evidence. The harness makes that detectable and awkward, not impossible.
• Approvals are conversational, not cryptographic. --approval freezes a snapshot of SPEC.md, but the approval entry itself can still be authored by the agent. Git-authority signing is a planned option, not yet the default.
• Evidence is declared, not independently reproduced. The CI checks that a raw validation block exists and is non-empty; it cannot verify the output is genuine.
• Local-first trust model. There is no cloud, no telemetry and no remote authority — the trade-off of never sending your code anywhere.

These limits are the honest boundary of a kit that runs on your machine with your rules. For a solo dev + agent building MVPs, they are the right trade.

🐕 Dogfooding

This repository is governed by the kit it ships:

• The badge above is this repo's own CI: 73 tests plus a self-application job that runs fia-harness init → bootstrap.py → --check on a fresh temp project in every push.
• The fia-harness-demo repo is generated with the kit and its golden-rules CI catches the cheater agent live.

✅ Verify the kit

python -m unittest discover tests -v

The tests cover the PROGRESS.md parser, section extraction, marker-based injectors, keyword heuristics, template header trimming, Lite-mode detection, the state machine (dependencies, checkpoints, evidence, approvals, seals, spec snapshot, drift, fail-closed, reopen), the packaging (anti-drift copies, init e2e, cp1252 consoles) and a complete e2e cycle in a temp folder.

In a bootstrapped project, check its state at any time:

python task_generator.py --check

📜 Documentation and sources of truth

📄 License

MIT — see LICENSE. The kit is yours: local, auditable, no cloud, no telemetry, no accounts.