How uscha works: the moving parts

Read it left to right: the method governs · the tool executes · evidence decides · the human approves

1 · The method governs 2 · The tool executes 3 · Evidence decides 4 · The human approves You the idea Spec skills discovery · adr-refine Old system? reverse-discovery + characterize The contract ADR + ACCEPTANCE model-check TLA+ for designs with state Agent + devloop builds and reviews Claude · Codex · pi Review tools tier set by paths + linters Hooks never writes goldens PR gate guard qa_ledger.py the engine tests · coverage · mutation QA-LEDGER.json the evidence Readouts status · mirador statusline pr-ready gate readiness check-terminado You approve the merge idea writes goldens checks builds on findings blocks logs records reads derives ready Legend External Frontend Database Security Backend

1 · The method governs

  • • Before code, a spec skill interviews you and writes the contract: ADRs + ACCEPTANCE (the criteria).
  • • New idea: discovery. Known feature: adr-refine. Old system: reverse-discovery + characterize.
  • • A design with state and rules is model-checked first (TLA+).

2 · The tool executes

  • • The agent builds against the contract and runs the review loop (devloop).
  • • A review tier set by the changed paths (quick · standard · deep) picks the review tools; the engine hands each one its scope, and every finding names path:rule.
  • • Hooks stop what the agent must never do, like writing an approved golden.

3 · Evidence decides

  • • The engine records only measured runs; it never takes the agent's word.
  • • Coverage says a line ran; mutation testing (PIT, pit-check) says whether a test would catch it changing.
  • • The gate reads the ledger: tests current, acceptance green, every located finding fixed or deferred, every tier tool's clean pass current.
  • • Readouts show the same numbers; they never compute their own.

4 · The human approves

  • • You decide the spec, approve the goldens, and approve the merge.
  • • Only a human lowers a review tier or confirms a deferral.
  • • The agent cannot declare 'done': the gate does, from evidence.