uscha.dev
how it works

Four flows, one rule: the human judges, the engine measures

uscha has a front for new systems and a front for existing ones. Both end at the same place — a human verdict the engine can check. These four diagrams show the greenfield flow, the brownfield flow, the curation mechanism (kit 1.64–1.65) where a single human decision is the only judgment in the loop — and the diamond leg (1.72–1.90) they all feed: compile, certify under a withheld oracle, round-trip.

1 · greenfield

Discovery — you bring the idea, the method proposes the shape

The skill explores first, then asks one question at a time — each with a recommended answer. You confirm or correct; you never author the shape from a blank page. The package is written to the repo as decisions crystallize.

until it converges Idea + reference material optional: docs, URLs, existing code Explore before asking read refs & code first Propose the shape one question at a time, each with a recommended answer HUMAN DECISION Confirm or correct ARTIFACTS · IN THE REPO SPEC · ADRs · ACCEPTANCE CONTEXT · DOMAIN-MODEL · RISKS → /uscha-devloop build + measured QA loop
artifact human decision skill / engine step
2 · brownfield

Reverse Discovery — extract facts, then quarantine the claims

The running system's behavior is the truth. The skill extracts facts (map, golden), then authors candidates in quarantine — never specs. The old rule "never author an inferred spec" was renegotiated in ADR-009: you may author candidates, you may never promote them without a verdict.

re-check until 0 Existing system observable behavior = ground truth Map — facts SYSTEM-MAP · boundaries · deps HUMAN APPROVES · INV-GOLDEN-01 Characterize → golden .received → STOP → .approved CANDIDATES · QUARANTINE discovery/*.md · evidence + confidence MEASURED GATE · subcmd 34 curation-check exit 2 malformed · 1 unjudged · 0 ok HUMAN VERDICT preserve · fix · undefined one candidate at a time BEHAVIOR-LEDGER.md + ADR append-only, git-verified Summary → human writes SPEC from JUDGED candidates only
artifact measured gate human decision skill step

INV-GOLDEN-01 is enforced mechanically on Claude Code (a blocking PreToolUse hook); on every other target the kit reports it as advisory — the measured control everywhere is golden-diff, which compares bytes.

3 · curation · 1.64–1.65

Curation — one human verdict, everything else measured

This is the differentiator. A candidate is machine-validated; a candidate with no verdict blocks the PR, naming itself (INV-CURATION-01). The single human decision splits into three buckets. A fix declares its expected divergence, which the golden oracle then checks. roundtrip reports traceability by id — advisory, never a gate.

CANDIDATE · discovery/*.md evidence.type · refs · confidence MEASURED validate frontmatter + refs refs resolve · confined to repo · inference⇒low GATE · subcmd 34 curation-check no verdict → blocks pr-ready, naming the candidate THE ONLY HUMAN DECISION IN THE LOOP HUMAN VERDICT preserve  ·  fix  ·  undefined preserve promote as-is fix promote + declared divergence undefined excluded ORACLE · golden-diff golden.divergences.json declared+diverges=ok · declared+identical=RED roundtrip (subcmd 35) · advisory · traceable by id · exit 0 always
candidate / artifact measured gate the human verdict advisory
4 · the diamond leg · 1.72–1.90

Compile, certify, round-trip — the forward leg the three flows feed

The curated package becomes a typed graph. Any model compiles it; the engine only validates the output contract and never compiles. A withheld oracle — authored before any compilation, never in the prompt — certifies whether the result is the same system. Then the reverse organs try to re-anchor the asset from the compiled code, and that ratio is published with its ceiling.

withheld · never in the prompt THE ASSET · ir-extract spec package + ledger → one typed graph (IR) ANY MODEL · the LLM compiles blind compilation → code four blind compilers, two vendors, same package, no oracle in sight MEASURED · compile-validate output contract — mechanical only exit 2 on violation · the engine never compiles HUMAN-AUTHORED BEFORE ANY COMPILATION · ORACLE.json the withheld oracle is this the SAME system? · cases tagged per acceptance criterion MEASURED · bootstrap-oracle · bench PASS · PARTIAL · FAIL 12 archetypes · 8 PASS · 4 PARTIAL (measured September 2026) · a stub-satisfied oracle downgrades to FAIL ADVISORY · bench-roundtrip · bench-r2 how much of the asset re-anchors from the code 0.815 = how much of the spec re-anchors from the code · NOISY = how much same-model reruns disagree
measured gate human-authored oracle advisory instrument model / skill step

Every node above maps to a real subcommand or invariant in qa_ledger.py (kit 1.96.0). These three flows are the human-judgment layer. The forward leg they feed — the LLM as compiler under a validated contract, blind compilations judged by a withheld oracle, and the measured round trip back — is the diamond: same doctrine, one level up.