@andresmassello/uscha 1.40.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andres Massello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# Uscha
+
+**Uscha** is a spec-driven, tool-agnostic methodology for development with
+LLM coding agents — *you bring the idea, the method builds the rest* — with its
+instantiation in Claude Code, the **uscha-kit**.
+
+> **On the name.** *Uscha* is the methodology's name; the pattern it operationalizes is a *spec-loop* — the concept, not the branding. The name was chosen partly to avoid collision with [spec-loop](https://github.com/dpolivaev/spec-loop) by D. Polivaev — an independently developed, actively maintained project that shares the term and the spec-driven, review-per-increment philosophy while taking a different implementation path (shell-based agent skills via npx). It was found late in this project's development; the two are convergent, not derivative. (The local checkout keeps the path `SpecLoop`.)
+
+> The tool executes · the method governs · evidence decides · the human approves.
+
+## Repo map
+
+```
+SpecLoop/
+├── uscha-kit/          # ★ canonical SOURCE of the kit (v1.40.1)
+│   ├── .claude/skills/    #   8 skills: uscha-discovery · uscha-adr-refine · uscha-devloop · uscha-sysdoc
+│   │                      #             uscha-reverse-discovery · uscha-characterize · uscha-rubric · uscha-mirador
+│   ├── .claude/skills/uscha-devloop/qa_ledger.py   # evidence engine (29 subcommands, stdlib)
+│   ├── hooks/             #   PreToolUse: the agent never writes .approved (INV-GOLDEN-01)
+│   ├── templates/         #   CLAUDE.md · CONSTITUTION.md · .gitattributes · docs/adr
+│   └── CHANGELOG-*.md     #   1.2.x → 1.3.0 ("facts block, wired") → 1.4.0 (python) → 1.5.0 (node) → 1.6.0 (go) → 1.7.0 (rust+dotnet) → 1.8.0 (cpp) → 1.9.0 (gradle+swift) → 1.10.0 (traceable acceptance) → 1.11.0 (tests outside the budget) → 1.12.0 (secret-scan) → 1.13.0 (atomic ledger) → 1.14.0 (plateau/stop-signal) → 1.15.0 (golden scrub) → 1.16.0 (regression-capture) → 1.17.0 (threshold provenance) → 1.18.0 (derived FSM) → 1.19.0 (spikes — PragProg backlog CLOSED) → 1.20.0 (global install) → 1.21.0 (namespace uscha-*) → 1.22.0 (doctor) → 1.23.0 (rubric layer) → 1.24.0 (Claude Code plugin) → 1.25.0 (anti-ceremony) → 1.26.0 (waste-check REUSE-FIRST) → 1.27.0 (FTY) → 1.28.0 (measured acceptance %) → 1.29.0 (rebrand → Uscha) → 1.30.0 (dependency gate) → 1.31.0 (evidence freshness + doc-version gate) → 1.32.0 (mirador — bird's-eye view + dashboard --json) → 1.33.0 (mirador telemetry — per-model tokens/time/model + transcript extractor) → 1.34.0 (mirador: project name from config + live watch/auto-refresh) -> 1.35.0 (execution-policy routing) -> 1.36.0 (discovery-intake: production findings + spec-doubt) -> 1.37.0 (ADR experiments: visible hypotheses) -> 1.38.0 (contract closure: SCR bridge + golden labels + calibration) -> 1.39.0 (universal Codex/Claude installer) -> 1.40.1 (npm/npx router)
+├── docs/                  # published artifacts (canonical here; Downloads = snapshots)
+│   ├── uscha-claude-code-doc-FINAL.html   # long deck ES (36 slides)
+│   ├── uscha-claude-code-doc-EN.html      # long deck EN
+│   ├── uscha-playbook{,-EN}.html          # Operator's Manual (trigger/move/gate)
+│   ├── uscha-onepager{,-EN}.html          # one-page sheet
+│   ├── uscha-team-pitch.html              # team adoption pitch (Vale/Martín story, 14 slides)
+│   ├── uscha-team-pitch-extended.html     # extended pitch: + typical day, readiness KPI, 2-story ledger, pilot (22 slides)
+│   ├── skills-referencia.html                 # exhaustive reference of the 8 skills (what each does, phase by phase)
+│   ├── casos-reales.md                        # logbook: real moments where the method intervenes (anonymized)
+│   ├── *.png                                  # system map · 10 steps · reverse-discovery
+│   └── diagram-sources/                       # source HTML of the PNGs (re-renderable)
+├── formats/               # 6 format explorations (A-F); playbook + atlas-map were adopted
+└── audits/                # outputs of the adversarial audits (2026-07)
+    ├── audit-metodologia-7-lentes.json        # 33 weaknesses confirmed / 13 refuted
+    ├── audit-fidelidad-doc-codigo-idea.json   # 171 claims verified doc↔code↔idea
+    ├── truth-pass-6-docs.json                 # 130 truthfulness edits post-wiring
+    └── verificacion-team-pitch.json           # 3 lenses over the pitch
+```
+
+## Status (2026-07-05)
+
+- **Kit v1.40.1** <!-- uscha:version --> — the fact-gates are WIRED into the engine (1.3.0: `log-gate`,
+  `flag-blocker`, `resolve-escalation`; UNMEASURED; per-tool convergence with a veto from
+  the measured snapshot) and the engine measures **Python** repos (1.4.0: pytest/Cobertura + ruff +
+  mypy) **TypeScript/JS** (1.5.0: lcov + jest-junit + eslint + tsc) **Go** (1.6.0: native cover
+  profile + gotestsum + golangci via checkstyle), **Rust** (1.7.0: Cobertura +
+  nextest + clippy) **C#/.NET** (1.7.0: coverlet + junit
+  logger + SARIF/Roslyn), **C++** (1.8.0: gcovr/Cobertura + ctest junit +
+  clang-tidy), **Kotlin/JVM Gradle** and **Swift** (1.9.0: zero new parsers —
+  JaCoCo/lcov/JUnit/checkstyle reused; detekt + SwiftLint). **Traceable acceptance** (1.10.0: AC-n closes on a
+  MEASURED testcase, the dominant dimension of readiness — M2 of the PragProg backlog). **Tests outside
+  the simplicity budget** (1.11.0: writing tests does not penalize the gate — M9).
+  **Secret-scan in gate-check** (1.12.0: added private keys/tokens/containers
+  block as a fact — M8). **Atomic ledger** (1.13.0: integrity checksum + hardened
+  load — M3). **Plateau/stop-signal** (1.14.0: stall and PR-candidate as
+  advisories — M6). **Golden scrub** (1.15.0: declared volatiles are masked with
+  visible masking — M7). **Regression-capture** (1.16.0: closing findings without a test =
+  narrated; escape-analysis mandatory when resolving blockers — M1). **Threshold
+  provenance** (1.17.0: each threshold is tagged by provenance — a requirement
+  declared in config vs the kit's default opinion; the biting cap says so in the
+  headline — M5). **Derived FSM** (1.18.0: `phase` computes the workflow state
+  from the ledger's facts, never declared; the PR is gated with `--require
+  pr-ready` — M4). **Formal spikes** (1.19.0: a `spike/*` branch never passes the PR
+  gate; the legitimate output is an ADR with lessons — M10). **Execution policy routing** (1.35.0: phase-level methodology/model/effort metadata for the operator and Mirador, not readiness scoring). **Discovery intake** (1.36.0: production findings + spec-doubt/SPEC-WRONG enter the ledger and reopen discovery instead of disappearing into narration). **ADR experiments** (1.37.0: `Status: Experiment` is visible/advisory in dashboard/Mirador with feedback/review metadata, not a readiness score). **Contract closure** (1.38.0: structured `spec-change-request`, golden intended vs observed-accidental labels, and post-merge calibration metrics). **Universal installer** (1.39.0: one machine installer for Codex plugin adoption and Claude global install, with dry-run/doctor/version checks). **npm/npx router** (1.40.1: `@andresmassello/uscha` exposes `uscha`/`uscha-kit` and delegates to the canonical Python installer). Smoke suite 224/224 green.
+  **The PragProg backlog is CLOSED: 10 of 10** (see
+  `docs/analisis-pragmatic-programmer.md`).
+  License: MIT. The principle "facts block, guesses advise" is an enforced property,
+  not a slogan.
+- **Docs** — passed through truth-pass against the real engine: every claim describes what
+  v1.40.1 does; the references appendix has **fetch-verified links** to the 10
+  sources. Status convention in the docs: `in the kit` / `new` / `proposal`.
+- **In progress** — dogfooding on a real case (pilot project, Python): the 1.4.0 adapter unblocked it;
+  what remains is the read-only dry-run (criterion 2 of the python-adapter HANDOFF) and the on-ramp.
+  Conscious deferrals in CHANGELOG-1.4.0 (assert density in rebuild, mechanized A-E
+  profiles).
+
+
+## Install from npm/npx
+
+```bash
+npx @andresmassello/uscha@latest install --target codex
+npx @andresmassello/uscha@latest doctor --target codex
+# or both Codex + Claude:
+npx @andresmassello/uscha@latest install --target both
+```
+
+The npm package is only a router. The canonical installer remains
+`uscha-kit/install-uscha.py`, and Python 3.8+ is still required on the target machine.
+
+## How the kit is re-packaged
+
+```bash
+powershell -NoProfile -Command "Compress-Archive -Path 'uscha-kit' -DestinationPath 'uscha-kit-X.Y.Z.zip' -Force"
+```
+
+The zips are build artifacts: they are not committed. The kit source in this repo is the truth.
+
+## History
+
+It was born as a methodology for working with Claude Code, was distilled with the
+Böckeler principle (computational blocks / inferential advises), survived two
+adversarial audits (231 agents) that found the central principle inverted in the code
+— and 1.3.0 flipped it right. The details are in `audits/` and in the CHANGELOGs.

package/bin/README.md

@@ -0,0 +1,6 @@
+# uscha npm package
+
+This package exposes the `uscha` / `uscha-kit` CLI for npm/npx users.
+
+It is intentionally a thin Node router over `uscha-kit/install-uscha.py`.
+The Python installer remains the source of truth.

package/bin/uscha.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const script = path.join(__dirname, '..', 'uscha-kit', 'install-uscha.py');
+const args = process.argv.slice(2);
+const candidates = process.platform === 'win32'
+  ? [ ['python', []], ['py', ['-3']] ]
+  : [ ['python3', []], ['python', []] ];
+
+let lastError = null;
+for (const [cmd, prefix] of candidates) {
+  const result = spawnSync(cmd, [...prefix, script, ...args], { stdio: 'inherit' });
+  if (!result.error) {
+    process.exit(result.status === null ? 1 : result.status);
+  }
+  if (result.error.code !== 'ENOENT') {
+    lastError = result.error;
+    break;
+  }
+  lastError = result.error;
+}
+
+console.error('[uscha] Python 3.8+ is required but was not found in PATH.');
+if (lastError && lastError.message) {
+  console.error(`[uscha] ${lastError.message}`);
+}
+process.exit(1);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@andresmassello/uscha",
+  "version": "1.40.1",
+  "description": "Uscha installer for Codex and Claude coding-agent workflows.",
+  "bin": {
+    "uscha": "bin/uscha.js",
+    "uscha-kit": "bin/uscha.js"
+  },
+  "files": [
+    "bin/",
+    "uscha-kit/",
+    "!uscha-kit/**/__pycache__/",
+    "!uscha-kit/**/*.pyc",
+    "!uscha-kit/**/*.pyo",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andresmassello/uscha.git"
+  },
+  "homepage": "https://github.com/andresmassello/uscha#readme",
+  "bugs": {
+    "url": "https://github.com/andresmassello/uscha/issues"
+  },
+  "keywords": [
+    "codex",
+    "claude",
+    "spec-driven",
+    "qa",
+    "coding-agents",
+    "sdd"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/uscha-kit/.claude/skills/uscha-adr-refine/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: uscha-adr-refine
+description: >
+  Turn a rough idea into a development-ready ADR set + ACCEPTANCE.md by INTERROGATING
+  before generating. Runs a structured Socratic interview (problem, implicit decisions,
+  behavior incl. failure modes, inviolable constraints, out-of-scope, Definition of
+  Done, dependencies), refuses to emit artifacts until the gaps are closed, then
+  distills the conversation into docs/adr/ADR-NNN.md files and an ACCEPTANCE.md. The
+  front-half counterpart to dev-loop. Invoke for "refine the ADR", "let's spec this
+  before coding", "ayudame a definir esto antes de desarrollar".
+allowed-tools: Read, Write, Glob, Grep
+disable-model-invocation: false
+---
+
+# adr-refine — interview, then distill
+
+You convert a rough idea into a development-ready specification. You do this in two
+phases. **You are NOT a generator. You are an interrogator that distills.** The value
+is in the questions, not in agreeing.
+
+## Non-negotiable principles
+
+1. **Interrogate, don't agree.** Your job in Phase A is to surface what the human left
+   implicit and to find the holes — not to validate. A refinement where you agreed with
+   everything failed.
+2. **Converge, don't run out of questions.** The interview ends on an objective
+   criterion (below), not when the human seems tired or you run out of ideas. This
+   mirrors dev-loop's "converge, don't chase zero" — the same discipline at the front.
+3. **Do not emit artifacts until convergence.** No ADR, no ACCEPTANCE.md until every
+   exit condition is met. If asked to "just write it" early, name the open gaps first.
+4. **One topic at a time.** Never dump 20 questions. Walk the agenda below, a focused
+   batch at a time, and reflect back what you heard before moving on.
+5. **Record deferrals as explicit assumptions.** If the human says "you decide" on a
+   consequential decision, push back once with the trade-off; if they still defer,
+   record it as an explicit assumption in the ADR, never as a silent default.
+
+## Phase A — The interview (agenda)
+
+Start from the human's initial context. Work the agenda in order; skip a topic only if
+it's already fully answered. Keep a running list of OPEN GAPS and resolved decisions.
+
+1. **Problem and why now.** What job does this remove? What does it cost to NOT do
+   it (money, time, risk)? If "why now" has no answer, the priority is suspect.
+2. **Implicit decisions.** Surface the choices the request assumed: sync vs async,
+   storage, protocol, idempotency, transactional boundaries, who owns state. For each,
+   force an explicit decision and at least one considered alternative.
+3. **Behavior.** Happy path first, then the DIRTY cases: provider/timeout failures,
+   retries and backoff, 4xx vs 5xx, concurrency, partial/terminal states, what must NOT
+   happen. A feature without its failure behavior is half-specified.
+4. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
+   rules that cannot be broken (money to the cent, numbering without gaps, never cross
+   environments/credentials, secrets never logged, auth/authz, data retention). Write/extend
+   `CONSTITUTION.md` (one invariant per line, CWE ref where it maps); these feed the
+   dev-loop severity gate and a breach is a BLOCKER. **An ADR may never contradict the
+   CONSTITUTION** — if a decision would, it's escalated, not recorded.
+5. **Out of scope.** Explicit boundaries, with forward references ("X goes to a later
+   spec"). What you exclude is as important as what you include.
+6. **Definition of Done + how we measure success.** Concrete, checkable acceptance criteria
+   (tests green, documented, metrics published, runbook) AND success metrics (p95,
+   cost ceiling, zero orphaned records). Each item must be verifiable, not a feeling.
+7. **Dependencies.** Which other specs/systems/credentials this needs to exist first.
+
+After each batch, reflect: "Decided: … / Still open: …". Move on only when the
+current topic is closed.
+
+## Convergence — exit conditions (ALL must hold)
+
+- Every decision has a rationale and at least one considered alternative.
+- Every failure mode named has a defined behavior.
+- Out-of-scope is explicit.
+- The Definition of Done exists and every item is checkable.
+- No OPEN GAP you raised remains unresolved (resolved = decided OR recorded as an
+  explicit assumption).
+
+State plainly when you've converged ("Closed: every decision has a rationale, the failures
+have behavior, the scope has a boundary and the DoD is verifiable.") before Phase B.
+
+## Phase B — Distill the artifacts
+
+Only after convergence. Produce (and, if any new project-wide invariant surfaced in
+step 4, append it to **`CONSTITUTION.md`** — never let an inviolable rule slip into an
+ADR where it could later be "traded away"):
+
+1. **One ADR per decision worth recording** at `docs/adr/ADR-NNN-<slug>.md`, format:
+
+```markdown
+# ADR-NNN: <title of the decision>
+## Status: Accepted
+<!-- Use Status: Experiment only for a bounded hypothesis with feedback/review criteria. -->
+## Context
+<the problem + the considered options: A) … B) … C) …>
+## Decision
+<the chosen option>
+## Reasons
+- <why, point by point>
+## Consequences
++ <the good>
+- <the cost / what it forces on us>
+<!-- If Status: Experiment, also include:
+## Hypothesis
+## Feedback Signal
+## Review By: YYYY-MM-DD  (or ## Review Trigger)
+## Promote Criteria
+## Rollback / Supersede Criteria
+-->
+## Implementation Plan
+- Affected paths: <files/dirs>
+- Patterns: <pattern to follow>
+- Tests: <which tests prove the decision>
+## Verification
+- [ ] <criterion checkable by an agent>
+```
+
+   Number ADRs continuing from the highest existing one in `docs/adr/` (glob first).
+   Negative decisions count: "what we are NOT going to use and why" is a valid ADR.
+   Experimental decisions count only when they are explicit hypotheses with feedback signal,
+   review date/trigger, promote criteria and rollback/supersede criteria. Do not use
+   `Status: Experiment` as a polite way to avoid deciding.
+
+2. **`ACCEPTANCE.md`** at the repo root (or the path in `uscha.config.json` →
+   `defaults.acceptance_file`). This is the file dev-loop's readiness measures — it MUST
+   exist and be checkable:
+
+```markdown
+# Acceptance — <feature>
+## Definition of Done
+- [ ] <verifiable criterion>
+- [ ] …
+## How we measure success
+- <objective metric: p95, cost, zero orphans, …>
+## Out of scope
+- <boundary> → <future spec>
+## Recorded decisions
+- ADR-NNN — <title>
+```
+
+**Where to write:** with file tools available (Claude Code), write the files to disk.
+In a chat-only context, print each file in a fenced block, clearly labeled with its
+target path, ready to paste — and remind the human these go to `docs/adr/` and the repo
+root before running dev-loop.
+
+**Tracked-markdown protocol:** if any target `.md` already exists and is tracked, ask
+for its current version before overwriting — never silently replace.
+
+## Handoff to dev-loop
+
+Close with the handoff prompt so the build phase starts by planning, not improvising:
+
+> "Read the ADR set and ACCEPTANCE.md. Before touching code: 1) summarize the plan of
+> files to create/modify, 2) confirm which decisions were left implicit, 3)
+> show me the first test you would write."
+
+Two-command flow end to end: `/uscha-adr-refine` → (ADR set + ACCEPTANCE.md) → `/uscha-devloop`.
+
+## Anti-patterns (do not do)
+
+- Generate an ADR from a one-line request without interviewing.
+- Accept "do it however you want" on a consequential decision without recording the
+  assumption.
+- Write an ACCEPTANCE item that isn't objectively checkable ("that it works well").
+- Emit artifacts before the convergence conditions are met.

package/uscha-kit/.claude/skills/uscha-characterize/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: uscha-characterize
+description: >
+  Capture a golden / approval suite of a module's CURRENT behavior — the one artifact the
+  agent must NOT author. Run the ORIGINAL code with real inputs through a deterministic
+  harness, emit .received, and STOP for human approval; never create or edit a .approved
+  file. Used before any migration/modernization to freeze pre-change behavior as field
+  truth. Invoke for "characterize", "golden-capture", "capturá el comportamiento viejo".
+allowed-tools: Read, Write, Glob, Grep, Bash
+disable-model-invocation: false
+---
+
+# characterize — freeze the current behavior as field truth (the agent does not author it)
+
+The golden suite is the ONE piece of the loop the agent cannot author, and that is exactly
+its reason to exist. If you write the golden by reasoning about what the code "should"
+return, you encode the same partial understanding that loses logic silently. **You capture
+what the code DOES, mechanically, by running it — never what it should do.** You may write
+the capture harness; you may NOT create, rename, or edit any `.approved` file.
+
+## Inputs
+
+- **Target module** + a **corpus source**: a path to input fixtures, or a reference to
+  (anonymized) production data. The golden is only worth as much as the corpus (see below).
+
+## Phase 1 — Capture harness (you write this)
+
+Generate a deterministic harness that runs the ORIGINAL module over the corpus and
+serializes ALL observable output. Same input → same `.received`, byte for byte.
+
+## Phase 2 — Non-determinism checklist (emit + normalize BEFORE serializing)
+
+Control every one of these, or the diff lies. Output the checklist applied:
+- [ ] **Timestamps / dates** — frozen clock or stable placeholder.
+- [ ] **Random / seeds** — fixed seed or mocked generator.
+- [ ] **Map/set iteration order** — sort keys before serializing.
+- [ ] **GUIDs / DB auto-increment** — normalized or excluded from the snapshot.
+- [ ] **Concurrency** — thread order must not leak into the output.
+- [ ] **Target locale** — decimal separator, date format, culture. **Mandatory and
+  explicit.** A golden built on one machine and run on another with a different locale
+  breaks entirely (Windows/SQL Server: high risk).
+- [ ] **Deterministic serialization** — JSON with sorted keys, fixed float precision,
+  explicit encoding. Identical byte-for-byte when behavior is identical.
+
+## Phase 3 — Run the capture
+
+Execute the harness → generate `.received` files.
+
+**Declare volatile fields BEFORE approval (kit 1.15.0).** If the ORIGINAL code emits
+values that vary between correct runs and cannot be made deterministic at the source
+(timestamps, request ids, GUIDs from a layer you cannot touch), declare scrub rules in
+`golden.scrub.json` at the fixtures root:
+
+```json
+{ "rules": [
+    {"pattern": "\\d{4}-\\d{2}-\\d{2}T[0-9:.+Z-]+", "replace": "<TIMESTAMP>"},
+    {"pattern": "requestId=[0-9a-f-]{36}", "replace": "requestId=<UUID>"} ] }
+```
+
+`golden-diff` masks BOTH sides with these rules before comparing (text only; binary
+stays byte-for-byte) and reports every scrub-match separately (`N via scrub`) — masking
+is never invisible. Prefer fixing determinism at the source (Phase 2 checklist); scrub
+is for what you genuinely cannot control. The rules file is part of what the human
+approves in Phase 4 — gate-check flags any later edit to it (a broadened rule can mask
+real divergence).
+
+## Phase 4 — STOP for human approval
+
+Return control to the human to review and approve the `.approved` — and, if present,
+`golden.scrub.json` (the scrub rules are contract, same as the goldens). **The skill
+ends here.** It does NOT auto-complete approval, and it does NOT create any `.approved`
+file.
+
+## Corpus — where the inputs come from (critical)
+
+The golden only protects the paths you exercise; what gets lost is usually a rare path.
+Sources, in order of value:
+1. **Real production samples** (anonymized if needed) — the true distribution, including
+   cases nobody knew existed.
+2. **Hand-built edge cases** — known limits (zeros, boundaries, error states, rare
+   combinations of inputs).
+3. **Inputs of past bugs** — every historical bug is a golden input.
+A module whose corpus does not exercise its known branches is marked **PARTIAL**, never
+covered.
+
+## Guardrails (non-negotiable)
+
+- The skill STOPS at the approval point (Phase 4); it never creates/renames/edits `.approved`.
+- A `PreToolUse` hook on `**/*.approved.*` should make agent writes mechanically impossible
+  (see `hooks/block-approved-writes.ps1` + the settings snippet in the kit).
+- `.gitattributes`: `*.approved.* binary` — line endings must not create false diffs
+  (Windows/SQL Server).
+
+## Acceptance criteria
+
+- The skill ends at Phase 4 with no `.approved` created or renamed.
+- The harness is deterministic (same input → same `.received` byte for byte).
+- The output includes the non-determinism checklist that was applied.
+
+## Harness stack
+
+- **Java** → ApprovalTests.Java (`com.approvaltests:approvaltests`, JUnit 5 / JDK 21);
+  `JsonApprovals.verifyAsJson()` for structured responses, `WithTimeZone`-style helpers
+  to freeze time/locale. For read-only migrations, the "old query vs new query against prod"
+  pattern applies.
+- **C++ / other** → a fixtures dir + a deterministic serializer + a diff runner (no
+  comfortable native ApprovalTests; go custom).
+- For system I/O, a fixtures dir + custom runner that normalizes and diffs is often better
+  than relying on the library alone.
+
+## Relationship to the other skills
+
+- **reverse-discovery** orchestrates this skill as its Phase 2 (golden capture at the
+  boundaries).
+- The captured `.approved` is the arbiter that `qa_ledger.py golden-diff` byte-compares
+  against during `/uscha-devloop`.
+- If you maintain `golden-labels.json`, classify approved fixtures as `intended`,
+  `observed-accidental`, or leave them `unknown`; labels explain intent but never
+  replace the byte comparison.
+
+## Tracked-markdown / tracked-golden protocol
+
+Never overwrite an existing approved golden. If a `.received` already exists, regenerate it;
+if a `.approved` exists, it is the human's — leave it untouched and surface the diff.