Uscha: you bring the idea, the method builds the rest.

The system map.

The whole territory in one diagram: the flow line, its inner loop (converge without chasing zero), the frontier of the outer loop, and the CONSTITUTION no station may violate. Map first; then the doc walks it station by station.

The specification, at a glance.

The evidence engine at the center, the flow's phases on the left, the six verification layers on the right, the principles in the strip, and the agent's pieces that hold it up at the bottom.

The flow at a glance.

The full cycle is a single line, runnable by a person, an agent, or the CI. The tool executes; the methodology governs; the evidence decides; the human approves.

Two things the flow guarantees: lowering the cost of entry (you don't have to design the system to be able to start — Discovery proposes that) and raising the certainty of the output (an honest state, with evidence and blockers, tells you how ready it truly is). In Claude Code all of this lives in nine callable skills (kit 1.65.0) and a measurement engine in Python.

Two fronts: discovery vs adr-refine.

The classic mistake is asking you to write entities, endpoints, and error cases from the start. But a new system begins earlier: all you know is what you want to achieve. That's why there are two fronts; you pick by starting point — and they emit different packages: /uscha-discovery writes the full spec package (CONTEXT, DOMAIN-MODEL/CONSTITUTION, SPEC, docs/adr, ACCEPTANCE, RISKS/HANDOFF); /uscha-adr-refine emits docs/adr/*.md + ACCEPTANCE.md (plus optional CONSTITUTION entries).

Both skills have allowed-tools: Read, Write, Glob, Grep (discovery adds WebFetch to read manuals/PDFs/URLs). Neither touches code: they generate clarity, not implementation.

The document package.

The front ends up writing the package directly into the repo as decisions crystallize — it doesn't hoard everything for the end. The build reads it from the files, not from the chat.

Why it matters even if it's all Claude Code: context resets (a new session, a /clear, or a compaction don't have the chat), sub-agents read files, a teammate or the CI builds from the repo, and the audit trail stays durable. The truth lives in versioned files.

SPEC ≠ ADR.

If it describes observable behavior, it goes in SPEC. If it justifies a choice between alternatives, it goes in ADR. Almost every non-trivial change needs a SPEC; only some need a formal ADR.

An ADR is written with judgment

Only if the decision meets all three: hard to reverse, surprising without context, and the result of a real trade-off. Otherwise it's noise that buries the important ones.

# docs/adr/ADR-NNN-<slug>.md
## Status: Accepted            # proposed/accepted/deprecated/superseded
## Context / Forces
## Alternatives: A) … B) … C) …
## Decision
## Reasons
## Consequences (+ / -)
## Implementation Plan          # affected paths · patterns · tests
## Verification
- [ ] <criterion checkable by an agent>

The Implementation Plan is what makes the ADR executable: Claude Code reads it and implements it without asking again. During the build, the code links back: // ADR: <slug> — see docs/adr/ADR-NNN-<slug>.md, which makes it safe to supersede (you find everything the ADR governs).

The CONSTITUTION layer.

The ADR chooses between alternatives. The CONSTITUTION forbids: it records the invariants that no ADR or SPEC may violate, whatever trade-off wins. It's the project's hierarchy of truth.

## CONSTITUTION.md — project invariants
# Security (non-negotiable)
- Secrets never in logs or in the repo       # CWE-532 / CWE-798
- All external input validated                # CWE-20
- Parameterized SQL only, never concat        # CWE-89
# Domain (example — fill per project)
- Mandatory idempotency on critical operations
- Business invariants that must never break
- Never two effects for the same requestId
# Operation
- No destructive migration without explicit rollback
- No merge without a human gate

Risk-based workflow.

Opening question: what can this break, and how much does it cost if it breaks? Risk scales the apparatus — profile A doesn't drag along the whole machinery. The profiles are a process heuristic you apply by hand: no profile concept exists in code or config, and no profile selects gates automatically.

/uscha-devloop phase by phase.

The uscha-devloop is a multi-repo, spec-driven orchestrator. It takes the ADR set + ACCEPTANCE.md as input, builds, and runs a severity-gated review loop that converges instead of looping forever, with the tests as a guardrail between steps. It stops at the merge gate. Three non-negotiable principles govern it: converge, don't chase zero; tests are a guardrail, not the finale; generating tests is not running tests.

1. Setup. qa_ledger.py init --config uscha.config.json. The config lists each repo and its type (maven/flutter/python/node/go/rust/dotnet/cpp/gradle/swift). In multi-repo, the other repos are mounted with --add-dir.
2. Phase 0 — Plan (ADR-first). The ADR set + ACCEPTANCE are the input. If acceptance criteria are missing, stop and run /uscha-adr-refine first. The acceptance criteria become the contract tests of phase 1.
3. Phase 1 — Coverage gate → conditional characterization (per repo). snapshot --phase pre + check-coverage. If coverage ≥ threshold, the existing suite is the guardrail. If below (or no report): you write characterization/contract tests at the edge (public API, endpoints) — and let the human review them before trusting them.
4. Phase 2 — Build. You implement per the plan, one commit per logical step (conventional commits). Apply ADR discipline: consult before touching governed areas; stop and propose an ADR on a new dependency, a new pattern, a non-obvious alternative, or a contradiction of an accepted ADR.
5. Phase 3 — QA loop (per repo). Run the tools in qa_tools_order (default: code-review → judgment-day → improve). One pass of all of them = one cycle. After each tool: apply only fixes ≥ severity gate (the rest to ISSUES-DEFERRED.md), run the tests, log with log-step, ingest the static gate with ingest-gate. The agent runs the fact gates inline (simplicity-check / gate-check / golden-diff — exit 0/1) and persists each verdict with log-gate; a failing fact gate blocks convergence. waste-check (reuse-first, 1.26.0) runs over the diff to catch Type-1/2 clones against the repo — advisory unless --gate. End-of-cycle advisory checks: converged and oscillation.
6. Phase 4 — Integration / contract (multi-repo). With all repos mounted, run the cross-repo contract tests. Contract breaks are gated findings. It's logged under --repo integration. It's the second layer of the QA architecture: per-repo green doesn't mean the seams are green.
7. Phase 5 — Verify (coverage, once). With stable code, /improve test writes the fine-grained coverage you deferred. Full suite green + coverage ≥ threshold before moving on.
8. Phase 6 — PR (stops at the merge). You open the PR, confirm CI green, and stop. The human does the merge.
9. Phase 7 — Smoke list. You produce a manual smoke checklist (real routes, endpoints, device flows).
10. Phase 8 — Docs + retrospective. summary + readiness; /uscha-sysdoc is optional reporting, on request — not a mandatory pipeline phase. Retrospective pulled from the ledger.

Evidence captured, not narrated.

The crack the method closes: if the same agent that makes the change writes the ledger, it can put exit_code: 0 without running anything. The guarantee only holds if the evidence is produced by execution — the qa_ledger.py parses real artifacts (JaCoCo XML, Surefire XML, the linters' reports), it doesn't transcribe what the agent says.

# the ledger does NOT trust the agent: it parses files
coverage  ← target/site/jacoco/jacoco.xml   (LINE counter)
tests     ← target/surefire-reports/TEST-*.xml
static    ← checkstyle-result.xml · pmd.xml · spotbugsXml.xml
LOC       ← its own count (prod vs test), pure stdlib

qa_ledger.py — command reference.

Pure stdlib, Python 3.8+, no dependencies. It owns everything that must be exact and reproducible. The judgments (did it converge? is it oscillating? do we escalate?) are made by the skill reading this data; the script only exposes deterministic advisory helpers.

Exact current parser surface: 56 subcommands; the list below mirrors build_parser(), including dashboard, waste-check, and spec-change-request.

# a typical pass of the loop
QL=./.claude/skills/uscha-devloop/qa_ledger.py
python3 $QL init --config uscha.config.json
python3 $QL snapshot --repo backend-api --phase pre
python3 $QL check-coverage --repo backend-api          # exit 0/1
# ...build + one QA tool...
python3 $QL log-step --repo backend-api --tool code-review --iteration 1 \
  --reported 12 --gated-reported 4 --fixed 9 --deferred 2 --suppressed 1 \
  --tests-passed true --files-changed 7 --fingerprint a,b,c
python3 $QL ingest-gate --repo backend-api --iteration 1
python3 $QL converged --repo backend-api --tools-per-cycle 3

Static gate + ingest.

The static gate (your java-qa-gate: Checkstyle/PMD/SpotBugs/FindSecBugs) is not counted by hand. You run the gate so it writes its XML, and ingest-gate parses them, normalizes to a common severity scale, separates FindSecBugs from SpotBugs, and computes the real fixed by diffing IDs.

Full scale, lowest to highest: INFO · LOW · MEDIUM · HIGH · CRITICAL · BLOCKER. The default severity gate blocks at BLOCKER / CRITICAL / HIGH; everything below goes to ISSUES-DEFERRED.md, never into the loop. Finding-ID granularity is configurable (file or line) for the fixed diffing and oscillation.

Readiness KPI.

It measures the state of the result, never the effort. A weighted 0–100 score with hard caps that override the average. It reports (always exit 0) — it is not a pass/fail gate; rebuild is the one that exits 1 unless COVERS. Cycles/regressions are churn (process health) and are reported separately — they never raise readiness. Show it after any task, not just complete runs.

Single-verdict (anti-ceremony, 1.25.0): by default readiness is ONE screen — the verdict + a collapsed --- gates: line; the dimension breakdown you see above, plus acceptance, churn, and by-repo detail, live behind --verbose. A meta-invariant in the CONSTITUTION governs that future gates stay quiet-by-default and collapse into readiness. The blockers that cap it always speak (conditional: "speak only when it matters"). No formula, no number: that would be the numerology the method avoids.

The rebuild test.

The ledger proves correctness (this build passed). The rebuild test proves completeness (the SPEC is sufficient to regenerate the system). Two different questions. It's the completeness benchmark being standardized in the SOTA.

The mechanic: on a clean tree, a fresh session points only at the package (SPEC/ADR/ACCEPTANCE — not the chat) and regenerates. If it rebuilds and passes acceptance + tests → the SPEC covers. If it diverges → the SPEC has gaps: almost always implicit decisions (error codes, cache strategy, library choice) that lived in your head and never made it into the SPEC.

# rebuild test — real subcommand (kit 1.4.0+)
# 1) ORIGINAL tree: capture the signature
$ python3 $QL rebuild --mode baseline --config uscha.config.json
  → REBUILD-BASELINE.json
# 2) CLEAN tree / fresh session: regenerate ONLY production from
#    SPEC/ADR/ACCEPTANCE, PRESERVING the tests, and run the suite
# 3) score the regenerated tree against the baseline
$ python3 $QL rebuild --mode compare --baseline REBUILD-BASELINE.json
  REBUILD: 72.2/100 — PARTIAL
  ! 1 test(s) fail on regenerated code — behavior the SPEC left implicit
  ! coverage 45.0% vs baseline 80.0% (tolerance 5)

Change budget + escalation.

Don't clean everything; don't make anything worse. Legacy debt is frozen, new debt is blocked. And the loop has a ceiling: exceeding it isn't going on alone, it's escalating.

Escalation contract — stop and ask when

• the iteration cap is reached without convergence
• oscillation is detected (a set of findings comes back)
• a test that passed now fails and the fix is not trivial
• two tools give contradictory directives on the same code
• a fix would require an architectural decision (ADR-level change)

The SIMPLICITY invariant.

Maeda's Laws of Simplicity are design philosophy, not a dev cycle. Mapping the 10 laws to gates is tempting — and that's the trap: building 13 checks to "make things simple" violates Law 1 (Reduce). The framework refutes itself. Of the whole combo, only one piece has teeth — and that piece is really two things under one coat. Separate them, or you rebuild the same mix, smaller:

# the invariant as an objective gate, not as philosophy
$ python3 .claude/skills/uscha-devloop/qa_ledger.py simplicity-check --diff HEAD
  # budgets: +lines (400 default) · net growth · files changed · nesting depth · largest hunk
  # abstraction count/density: advisory, deliberately unweighted
  SIMPLICITY: PASS · +47 lines / budget 400 · nesting 2 · largest hunk 31L

Sensors: feedback the agent can read.

A sensor is an automatic check that returns actionable feedback to the agent so it can self-correct — before human review. It's your "evidence captured, not narrated" under another name. They're ordered by when they run and by what evaluates them:

Three findings that add teeth to your kit:

Anti gate-gaming.

Your kit measures everything — but nothing checked that the change didn't WEAKEN the measurement. A maker running as an optimizer takes the cheapest path to "green", and editing the gate is often the cheapest. Three guards close the most direct exploit of an automatic gate: modifying the gate.

Golden testing.

In the Uscha the agent authors almost everything (discovery, ADRs, spec, code, tests). The golden suite is the ONLY piece the agent cannot author — and that is its reason to exist. If the agent writes the test that judges it, it encodes the same blind spot that already lost logic once.

Directly applicable to any migration of a legacy system with critical paths (byte-equivalence), where the silent loss of logic is the real risk. Already in the kit: brownfield front uscha-reverse-discovery (map + facts), uscha-characterize skill (capture), golden-diff gate, hook block-approved-writes.py (blocks the agent from touching an .approved), and .gitattributes.

Facts vs prose.

A kit full of gates can turn into a diamond: beautiful and impractical. The principle that avoids it — your Böckeler rule (computational vs inferential) applied to the methodology itself:

The book went through the kit.

Crossing Hunt & Thomas (20th Anniversary, 497 pp) against the method yielded a set of validations, tensions and ten actionable improvements, all shipped (kits 1.10.0 → 1.19.0, each with a fresh review and a green smoke suite). The per-item record lives in those releases' changelogs (uscha-kit/CHANGELOG-1.10.0.md … 1.19.0.md); the original analysis document was retired in the docs cleanup.

Did we reach it? — convergence with the SOTA.

"Loop engineering" blew up in one week of June 2026 (Steinberger, Cherny, Osmani): "don't prompt agents; design loops that prompt them". When the front brought it down to spec-driven, it converged on these same principles. Uscha didn't fall behind: it reached the same shape independently.

The autonomous loop earns its cost, or costs more than it returns.

The loop-engineering playbook (Osmani / AlphaSignal, Jun 2026) puts a 4-condition test before automating anything: fail one and the loop costs more than prompting by hand. Uscha already defines "when NOT to use it"; this is the entry filter for the outer loop.

The Uscha outer loop: the heartbeat it lacks.

Uscha is human-triggered today: you fire it. The playbook contributes the heartbeat — what turns "one run" into a loop. The synthesis: Uscha is the ideal payload of that heartbeat, because it already brings the gate, the state, the skills, and the maker ≠ checker. Only the trigger is missing.

# outer loop = schedule + /goal, wrapping /uscha-devloop
> /loop 0 3 * * *                 # cadence: every night
  /goal  readiness ≥ 80 AND tests green in touched modules
         AND 0 CRITICAL findings   # checked by a separate model
  /guard 4-condition-test          # repetitive task + automatic verification
  > run /uscha-devloop over <machine-checkable scope>
    gate     = qa_ledger.py ingest-gate + fact gates (readiness = KPI)  # ALREADY exists
    state    = QA-LEDGER.json + package in repo         # ALREADY exists
    stop     = /goal met (fresh checker) or change budget exhausted
    on-done  = open draft PR · escalate what touches the CONSTITUTION
    human    = merge / deploy ALWAYS with approval       # human gate

An unattended loop is an unattended attack surface.

Your security today is build-time (static gate + CONSTITUTION with CWE). When the loop runs on its own, operational risks appear that the playbook documents. They enter as an operational layer of the CONSTITUTION: invariants the outer loop cannot violate.

Two layers, one synthesis.

The playbook and Uscha don't compete: they're different layers. The article is the outer loop (the heartbeat that triggers machine-checkable maintenance). Uscha is the rigorous inner loop + Discovery for critical systems. The convergence on principles (maker ≠ checker = Anthropic's evaluator-optimizer, Dec 2024) confirms you reached the durable stuff, not the hype.

The Diamond, measured.

Twelve bounded archetypes, a withheld oracle (M4), four blind compilers from two vendors — Haiku, Sonnet, Opus and OpenAI Codex gpt-5.5 (measured September 2026). The question: how much of the system survives the round trip?

221 verdicts: 213 preserve, 8 fix, none unjudged. The cross-vendor arm is a falsification test the replaceability claim survived, not a survey: four blind compilers, two vendors, gpt-5.5 via Codex included.

2.x: the kit under its own instruments.

When NOT to use Uscha.

The workbench.

The generic layer that runs the methodology: Claude Code + Python + git/gh + the skills. The stack-specific part (JDK/Maven, the database, the linters) is the project's adapter and lives in each repo's CLAUDE.md — not in the workbench.

# Claude Code (native installer — no Node required, self-updating)
curl -fsSL https://claude.ai/install.sh | bash       # macOS/Linux/WSL
irm https://claude.ai/install.ps1 | iex              # Windows PowerShell
claude                                                # OAuth login
# Kit skills (global)
cp -r uscha-kit/.claude/skills/* ~/.claude/skills/
# Optional — author's toolchain, not required by the kit (Gentleman's own bucket)
scoop bucket add gentleman https://github.com/Gentleman-Programming/scoop-bucket
scoop install gentle-ai
claude --version && claude doctor                     # verify

On Windows, WSL2 is the recommended path (you install and run claude inside WSL). For headless/server: export ANTHROPIC_API_KEY=...

The agent's pieces that hold it up.

The kit installs on seven agents. What each one provides is not equal — and honesty means saying where it isn't.

CLAUDE.md — the non-negotiable rules.

Permanent rules that Claude Code reads every session. The per-change stuff lives in SPEC/ADR/ACCEPTANCE, not here. (If you use other agents, copy this file as AGENTS.md.)

1. Don't code from a vague idea. Without SPEC + ACCEPTANCE, model first (/uscha-discovery or /uscha-adr-refine).
2. The truth lives in files, not the chat. Before touching code, read SPEC/ACCEPTANCE/ADR.
3. Converge, don't chase zero. Only findings ≥ severity gate; the rest to ISSUES-DEFERRED.md.
4. ADR discipline during the build. Stop and propose an ADR on a dependency/pattern/alternative/contradiction. Link // ADR: <slug>.
5. Evidence captured, not narrated. Execution produces it. Absent = no evidence.
6. Legacy baseline. 0 new HIGH/CRITICAL, 0 regressions, no new warnings in touched files.
7. Change budget. Max iterations/files; 0 schema without an ADR; 0 new deps without approval. If exceeded → escalate.
8. Never edit the SPEC/ADR to make the implementation look correct. Version it and go back to Ready.
9. Human gate. No automatic merge or release. You stop at the PR.

One session, end to end.

A backend service (Java, Spring Boot, React, SQL), from idea to PR, all in Claude Code:

claude code · single session
$ claude
> /uscha-discovery
  1×1 grill, proposes entities/endpoints, you decide 3 things
  ✓ CONTEXT.md · DOMAIN-MODEL.md · SPEC-001 · ADR-001/2/3
  ✓ ACCEPTANCE.md · RISKS.md · HANDOFF.md
> /uscha-devloop
  plan → coverage gate → build → QA loop (sub-agents) → integration
  CONVERGED · PR opened. I stop at the merge.
> !python3 .claude/skills/uscha-devloop/qa_ledger.py readiness --acceptance ACCEPTANCE.md
  READINESS: 88/100 — RELEASE CANDIDATE
> /uscha-sysdoc                 # two-view deck from the ledger
# (you) review the PR and merge — the human gate is not automated

The methodology in 10 steps.

A minimal feature — applyDiscount(amount, percent) — walked end to end. 6 of the 10 steps are a failure or a refinement (marked ⚠): the methodology is not that everything goes right the first time — it's that every deviation has a gate that catches it.

1. Discovery. /uscha-discovery "applyDiscount(amount, percent)" → 1×1 grilling (rounding? % bounds?). Out comes SPEC-001 + ACCEPTANCE + ADR-001.
2. ⚠ spec-check advisory. spec-check --spec SPEC-001.md → vague criterion; you rewrite it testable: "amount=100, %=20 → 80.00 (2 decimals)".
3. ⚠ out-of-scope. spec-check asks for the section; you add "out of scope: coupons, taxes" → now there's an oracle for "scoped-but-absent".
4. adr-refine. /uscha-adr-refine "rounding: HALF_UP or HALF_EVEN?" → ADR-002, with the alternative recorded.
5. uscha-devloop. /uscha-devloop → plan → coverage → build → QA loop. Compiles, happy path green.
6. ⚠ pit-check. pit-check → a mutant survives in the rounding: the test runs but doesn't assert the cent. You add assertEquals("80.00", …). Coverage was lying.
7. ⚠ gate-check BLOCKS. gate-check --from-git → the agent lowered the coverage threshold in pom.xml to pass. Revert it, fix the test for real.
8. ⚠ rebuild DIVERGE → amend-spec. rebuild --mode compare → the %=120 case was left implicit. You amend the SPEC (">100 or <0 → error"), regenerate, go back to Ready. You don't patch the code.
9. ⚠ simplicity-check. simplicity-check --from-git → OVERBUILT: the diff blew its growth budget — the agent added a DiscountStrategyFactory for 3 lines (the abstraction count itself is only advisory). Trim it.
10. readiness + human gate. readiness --acceptance ACCEPTANCE.md → 88/100 RELEASE CANDIDATE. You read the diff, approve the merge (never auto). /uscha-sysdoc builds the deck. Ship.

Reproduce the environment on the team.

The skills are "shareable with the team" — but the behavior does NOT live in a single file. It's 7 layers + an external CLI + a path gotcha. Copying just settings.json isn't enough. Scope note: this taxonomy and the bootstrap script are the author's setup in Claude Code Desktop — not shipped in the kit; the kit itself only needs Python 3.8+, git, gh optional, the kit skills installed per agent, and per-repo config + permissions. Installing the kit on another agent needs none of this: npx --yes @andresmassello/uscha@latest install --target codex.

# bootstrap: one command per side
# on YOUR machine — build the bundle (no secrets, no memory):
bootstrap-claude-setup.ps1 -Mode export -Bundle D:\claude-bundle
# on the NEW machine (bundle already copied there):
bootstrap-claude-setup.ps1 -Mode import -Bundle D:\claude-bundle
# manual: gentle-ai (own bucket) + the 2 plugins via /plugin
scoop bucket add gentleman https://github.com/Gentleman-Programming/scoop-bucket
scoop install gentle-ai

Glossary of terms.

To check on the fly when a term shows up in the slides. Not linear reading: jump here when you need it (End takes you to the end).

Artifacts — the truth in files

Phases and commands

Gates and measurement

Loops

Memory and hygiene

External reference

References and credit.

As a matter of principle: the ideas in this document didn't come from nowhere. The concept/idea I developed was later enriched with the following documentary contributions:

Honest credit: the mutation testing technique is popularized by Stryker (JS) / PIT (Java); "Simplicity First" was operationalized publicly in Forrest Chang's repo (Jan 2026), Karpathy didn't endorse it. Under-attributing impoverishes; over-attributing lies.