@andresmassello/uscha 2.1.0 → 2.2.0

package/README.md

@@ -10,6 +10,10 @@ never what was claimed.
 **[uscha.dev](https://uscha.dev)** — the method, the five rules, the skills, the library
 (the diamond thesis, how-it-works diagrams, essay, 2-day dev course, reference, paper).
 
+**New here? Start with [First use: from install to one measured result](docs/FIRST-USE-EN.md)**
+— one machine, one small repo, one criterion closed by a real test, and the merge left to you
+([en español](docs/FIRST-USE.md)).
+
 ```bash
 npx --yes @andresmassello/uscha@latest install --target claude   # Claude Code
 npx --yes @andresmassello/uscha@latest install --target codex    # Codex
@@ -40,7 +44,7 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v2.1.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v2.2.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -76,7 +80,7 @@ and see which file, which test, and when.
 | `/uscha-mirador` | Bird's-eye HTML dashboard: readiness, trail, acceptance, loops |
 | `/uscha-status` | One-line progress readout, in chat |
 
-**A measurement engine** (`qa_ledger.py`, 53 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 56 subcommands, Python stdlib) that ingests
 evidence from **11 language stacks** — maven, gradle, ant, python, node, go, rust, dotnet,
 cpp, swift, flutter — and computes a readiness score with hard caps and visible provenance.
 
@@ -132,6 +136,14 @@ else `doctor` reports `advisory` rather than implying a guard it cannot see.
   method is enforced by the engine, not by asking the agent to be disciplined.
 - **Model-agnostic.** The engine never reads tokens, model names or vendor telemetry. Any
   model-reported number enters through an adapter, never the engine.
+- **Field truth for greenfield.** In a new system every test payload was invented by the
+  agent that wrote the code, so `corpus-run` scores a corpus of REAL inputs against the
+  real command and persists the percentage as a fact — advisory until the project
+  declares a budget, a blocking gate once it does (ADR-046).
+- **Evidence is executed, not narrated.** The smoke run is a report the project's tool
+  writes, not a paragraph an agent types: `smoke-ingest` reads `{"checks": [{"name",
+  "ok", ...}]}`, a failed check blocks like any fact gate, and an empty or malformed
+  report is refused rather than scored (ADR-047).
 
 ## The diamond — specs are the source code, end to end
 
@@ -172,7 +184,7 @@ automatic tool can perform: a human verdict.
    from the compiled code: 0.815 measured (12 archetypes) — names AND behaviour
 ```
 
-**What each arrow is, in the engine (kit 1.96.0, 53 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.96.0, 56 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|
@@ -188,7 +200,12 @@ under an oracle the compilers never saw — that is the closed loop working. It
 1.99.0, when a fourth compiler from a second vendor read one genuinely ambiguous sentence in
 `transformer` the other way and lost a case the three Claude-family models had agreed on
 (ADR-042). The number went down because the bench got harder, and the whole point of the arm was
-to let it. 0.815 is the mean *recoverability* of the asset from compiled code counting only
+to let it. Since 2.2.0 that headline is a **derived fact**: `qa_ledger.py facts` counts the verdict
+rows of `DIAMOND-BENCH.md` — the report `bench` generates over the committed fixture — into
+`SYSTEM-FACTS.json`, and `facts --check` compares every published copy of it against that count.
+It was added because the project's own homepage said 9/12 for nine releases after the number
+moved, and every one of those releases was green: the claim sat in one HTML element and its noun
+in the next, where the gate could not see it. 0.815 is the mean *recoverability* of the asset from compiled code counting only
 static and behavioural footing. It read **0.062** until 1.90.0, with the behaviour dimension
 `UNMEASURED`, because no oracle case carried an AC tag — a named absence, not a zero. The 12
 bench oracles are now curated per case (`ORACLE-TAGS-CURATED.json`, human-authored; payloads and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",

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

@@ -19,6 +19,8 @@ phases. **You are NOT a generator. You are an interrogator that distills.** The
 is in the questions, not in agreeing.
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or

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

@@ -19,6 +19,8 @@ what the code DOES, mechanically, by running it — never what it should do.** Y
 the capture harness; you may NOT create, rename, or edit any `.approved` file.
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or

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

@@ -27,6 +27,8 @@ artifacts; these can block) and **self-reported** agent counts (log-step — nar
 recorded for the retrospective; a measured red always overrides a narrated green).
 
 <!-- uscha:orientation-block:begin -->
+<!-- uscha kit: 2.2.0 -- generated region: edit tools/skill-blocks/, then run `python tools/gen-skill-blocks.py` (never this block by hand) -->
+
 ## First contact (show ONCE, then never again)
 
 **Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
@@ -110,10 +112,30 @@ Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`,
    only *run* the existing suite.
 4. **Stop at merge.** You create the PR and confirm CI is green. You do NOT merge.
    The human owns the merge gate.
-5. **Tracked-markdown protocol.** Before modifying any tracked `.md`
-   (CLAUDE.md, plan/delta docs, docs/adr), ask the human for the current version first.
-   Those files carry real progress (checkboxes, notes); never regenerate from scratch.
-6. **The golden is the one artifact you cannot author.** For migration/legacy work,
+5. **Tracked-markdown protocol: READ the file, never ask for it.** Before modifying any
+   tracked `.md` (CLAUDE.md, plan/delta docs, docs/adr), READ the current version out of
+   the tree. Those files carry real progress (checkboxes, notes): preserve it and edit in
+   place, never regenerate from scratch. The current version of a tracked file is
+   INFORMATION the tree already holds, so asking the human for it is noise — you ask the
+   human for DECISIONS, never for information you can read (ADR-044).
+6. **`origin: agent` — a decision the human never made does not enter scope silently.**
+   Every acceptance criterion, ADR decision item or HANDOFF rule that YOU introduce
+   (rather than one the human answered) carries the marker on its own line:
+
+   ```
+   - [ ] AC-12 — when X then Y. (origin: agent)
+   - [ ] AC-12 — when X then Y. (origin: agent, confirmed: 2026-09-07)
+   ```
+
+   Unmarked items are human-origin by default; nothing existing is retro-tagged. An
+   unconfirmed item is **not in scope**: do not implement it, do not gate on it, do not
+   quote it as agreed. Ask the human to confirm it ONE BY ONE — a package-level "ok" over
+   a twenty-item summary confirms nothing — and only then write
+   `confirmed: YYYY-MM-DD` on the same line. List every still-unconfirmed item in the PR
+   body under **Agent-origin, unconfirmed**. `spec-check` names them with file:line and
+   `readiness` counts them on their own line; both are ADVISORY and neither changes an
+   exit code or the score.
+7. **The golden is the one artifact you cannot author.** For migration/legacy work,
    `.approved` fixtures are field truth captured from the ORIGINAL code and approved by
    a HUMAN. You emit `.received` and stop; you never write, edit or rename `.approved`
    (a `PreToolUse` hook denies the write — INV-GOLDEN-01).
@@ -126,6 +148,12 @@ QL="./.claude/skills/uscha-devloop/qa_ledger.py"                      # instalac
 [ -f "$QL" ] || QL="$HOME/plugins/uscha/skills/uscha-devloop/qa_ledger.py"  # Codex plugin install
 [ -f "$QL" ] || QL="$HOME/.claude/skills/uscha-devloop/qa_ledger.py"  # Claude global install
 python3 $QL init --config uscha.config.json
+
+# adding a service LATER never re-runs init: that would build a NEW ledger and drop every
+# step. --add-repo appends and re-seals the checksum, leaving every existing repo untouched
+# (kit 2.2.0). The new repo has no evidence yet, so it reads UNMEASURED and the repo
+# averages read lower until its first snapshot — that is absence, not a regression:
+python3 $QL init --add-repo <NAME> --path <path> --type <type> --test-command "<cmd>"
 ```
 
 ## Execution policy line (before every phase)
@@ -368,7 +396,9 @@ python3 $QL log-step --repo <REPO> --tool <code-review|judgment-day|improve> \
 weaken the measuring apparatus? did it ADD a secret? — private keys, cloud tokens and
 key-container files block as facts, kit 1.12.0; generic password/token literals advise;
 new dependencies advise too — the change-budget rule "no new deps without approval" made
-visible, kit 1.30.0)
+visible, kit 1.30.0). A rename is reported as a MOVE, never as a deleted test, and `--repo`
+SCOPES the diff to that repo's path, so a monorepo sibling's hunks are neither this repo's
+findings nor this repo's exit code (kit 2.2.0)
 and, for migration work, golden-diff (does behavior still match the human-approved
 baseline?). Then PERSIST each verdict with `log-gate` — a failing fact gate blocks
 convergence and caps readiness ≤65 through the ledger:
@@ -397,6 +427,10 @@ have caught this and what was done>"` — reflection is part of closing, not opt
 python3 $QL gate-check --from-git --base <base> --repo <REPO>   # exit 1 = BLOCKER
 python3 $QL log-gate --repo <REPO> --iteration <N> --kind gate-check --verdict <pass|fail>
 
+# CI, when the pipeline has run for this commit (kit 2.2.0). A green run is a FACT and
+# belongs in the ledger; --ref is the receipt that outlives the conversation:
+python3 $QL log-gate --repo <REPO> --iteration <N> --kind ci   --verdict <pass|fail|not-run> --ref <run URL or id>
+
 python3 $QL golden-diff [--dir <fixtures-root>]   # exit 0 CLEAN · 1 DIVERGE · 2 NOT-RUN
 python3 $QL log-gate --repo <REPO> --iteration <N> --kind golden-diff \
   --verdict <pass|fail|not-run>   # not-run records the absence — it is never green
@@ -406,6 +440,33 @@ python3 $QL log-gate --repo <REPO> --iteration <N> --kind golden-diff \
 but when a PIT report EXISTS and fails the gate, persist it the same way:
 `log-gate --kind pit-check --verdict fail`.)
 
+**Field truth — the greenfield evidence class (kit 2.2.0, ADR-046).** `characterize` and
+`golden-diff` answer "does it still do what the OLD code did?", which greenfield has no way to
+ask: there is no old code, and every test payload was invented by the agent that wrote the
+subject. `corpus-run` is the evidence class for that gap — REAL inputs with their real expected
+outputs, one JSON object per line (`input`, `expected`, optional `id`), each fed to the command
+on stdin and compared against its trimmed stdout. Run it when the repo declares a corpus
+(`repos[R].corpus`) or when the human hands you one; it is NOT part of the inner loop, since a
+real corpus can be large (schedule it like pit-check). It is **advisory** until the project
+declares a budget — with no `--threshold`, `repos[R].corpus_threshold` or
+`defaults.corpus_threshold`, the percentage is measured and gates nothing, and it never counts as
+an `ok` gate. With one declared, a run under it caps readiness ≤65 and blocks convergence like
+any fact gate. A missing, empty or malformed corpus is exit 2 naming the line — never a scored
+0 %. Never author a corpus yourself: an invented corpus is the invented input this instrument
+exists to expose.
+
+```bash
+python3 $QL corpus-run --repo <REPO> --corpus <path.jsonl> --command "<cmd>"   [--threshold <P>] [--ac AC-FIELD-01] [--timeout 30]   # exit 1 = under the declared budget
+# a corpus measured elsewhere (CI, a nightly) goes in through the parity door:
+python3 $QL log-gate --repo <REPO> --iteration <N> --kind corpus   --verdict <pass|fail|advisory|not-run>
+```
+
+`--ac` stamps criterion ids on the record: a criterion whose only evidence is a corpus record
+closes MEASURED iff that record PASSED, and a ticked criterion without one reports
+`narrated_only` — the same rule a green JUnit testcase has always obeyed. `readiness` prints one
+conditional `--- field <repo>: ...` line per repo that declares a corpus or ran one; it carries
+no weight in the score (that dimension is deferred to its own ADR).
+
 4. The **static analysis gate** (`java-qa-gate`: Checkstyle/PMD/SpotBugs/FindSecBugs)
    is NOT counted by hand. Run the gate so its XML reports are written, then ingest
    them — the ledger parses the reports, normalizes severities to the common gate
@@ -508,13 +569,53 @@ python3 $QL check-terminado          # 0 = sealed · 1 = broken · 2 = UNMEASURE
   seal broke. **Exit 2** — the seal is UNMEASURED (no git, or no snapshot recorded): say so
   plainly; an answer nobody could measure is not a TERMINADO either.
 - Ensure conventional-commit history is clean.
+- **List the agent-origin items that are still unconfirmed** in the PR body, under
+  **Agent-origin, unconfirmed** (principle 6). `spec-check` names them with file:line;
+  copy that list. An empty list is written as "none" — silence and "none" are not the
+  same fact.
+- **Cite the operability line** in the PR body, under **Operability** (kit 2.2.0, ADR-048):
+  copy `readiness`'s `--- operability: ...` line verbatim, whichever four verdicts it
+  carries. A reviewer should not have to ask whether this change ships with a release
+  path, a reset and a RUNBOOK — and a red line in the PR body is a conversation, which is
+  exactly the conversation two projects never had until their last week.
 - Open the PR(s). Confirm CI is green.
 - **STOP.** Present the PR link(s) and wait for the human to merge.
 
-## Phase 7 — Smoke list
+## Phase 7 — Smoke run (measured, kit 2.2.0, ADR-047)
+
+**Evidence is executed, not narrated.** This phase used to end in a prose checklist, and
+prose is exactly where a smoke run goes to die: "the jar served /admin", "the simulator
+answered 200 in 6 ms" are an agent's sentences, believed because they are written
+confidently. A real one cost a field team a release — every simulator run returned an
+empty list because the database had no rows, and a smoke narrated as "verified" would
+have hidden it behind a paragraph. So RUN the smoke paths (real endpoints, real user
+flows, real device paths for this change) with the project's own tool, have that tool
+write `reports/smoke.json`, and INGEST it:
+
+```json
+{"checks": [{"name": "AC-28 the jar serves /admin", "ok": true, "status": 200,
+             "latency_ms": 6, "evidence": "curl -sS localhost:8080/admin | head -1"}]}
+```
+
+```bash
+python3 $QL smoke-ingest --repo <REPO> --report reports/smoke.json   # exit 1 = a check failed
+```
 
-Produce a concrete manual smoke-test checklist (real user paths / endpoints / device
-flows for this change), so the human can verify the system behaves as intended.
+`name` and a boolean `ok` are the whole mandatory contract; `status`, `latency_ms` and
+`evidence` are optional and never invented. A missing `checks`, an EMPTY list, or a check
+without a name or a boolean `ok` is exit 2 naming it — a run that verified nothing is not
+a clean gate. A failed check is a BLOCKER like any other fact gate: readiness ≤65,
+convergence blocked, cleared by a later clean report. `smoke` is a FACT kind and never
+runs advisory — a check either answered or it did not. Name a check `AC-nn ...` (the same
+tag grammar a JUnit testcase name uses) and a green check inside a passing report closes
+that criterion MEASURED; a failed one vetoes it, exactly like a red test.
+`log-gate --kind smoke --verdict pass|fail|not-run` is the parity door for a smoke
+measured elsewhere. `uscha-kit/templates/scripts/smoke-report-example.json` is the
+reference report. If the human runs the smoke by hand, they still write the report: a
+checklist a human ticked is evidence, a checklist an agent narrated is not.
+
+**The PR body cites the gate** (phase 6): paste the `smoke-ingest` verdict line —
+`<repo>/gate:smoke: PASS — 8/8 checks ok` — not a prose claim that the smoke passed.
 
 ## Phase 8 — Hand off to docs + retrospective
 
@@ -523,6 +624,33 @@ python3 $QL summary           # human-readable
 python3 $QL summary --json    # machine-readable, includes post_merge_calibration
 ```
 
+**Operability is MEASURED here, not promised (kit 2.2.0, ADR-048).** Release by CI, the
+reset/seed script and the RUNBOOK used to live in this phase as PROSE, and prose is what
+lets "we do that at the end" survive every gate the kit has. Run it, per repo, BEFORE
+readiness so the record is in the ledger when the KPI renders:
+
+```bash
+python3 $QL operability --repo <REPO>          # exit 0 always; the gate is the profile's
+```
+
+It reads four FACTS out of the tree and never runs anything: a `.github/workflows` step
+that runs the repo's **configured** test command, a workflow that publishes or attaches a
+release asset, a `RUNBOOK.md` (`docs/` first) naming start/config/rollback/smoke in EN or
+ES, and a `seed_command` the config declares whose script is on disk. Repo path first,
+CONFIG ROOT second, and it NAMES which it read. A CI system it does not read (GitLab,
+Jenkins, Azure) is reported `unknown` — never green, never red.
+
+The POSTURE is the risk profile's, not the kit's: on **A/B** the record is `advisory`
+(caps nothing, blocks nothing, never counted as `ok`); on **C/D/E** — where
+`defaults.operability.gate` is `true` — a missing check is a BLOCKER that caps readiness
+≤65, blocks convergence, and makes `phase --require pr-ready` refuse NAMING the missing
+one. Do NOT hand-wave a missing check: write the workflow, write the RUNBOOK section,
+declare the seed command. If the project genuinely does not want the gate, that is a
+declaration (`defaults.operability.gate: false`), not a silence.
+
+`readiness` then prints one conditional line — `--- operability: ci ok · release missing ·
+runbook ok · seed missing (advisory)` — and that is the line you cite in the PR body.
+
 **Readiness KPI — show this after finishing ANY task, not only full runs.** It measures
 the STATE of the result (not effort spent), as a weighted score 0..100 with hard caps:
 
@@ -542,6 +670,11 @@ Right after readiness, run the spec-maintenance advisory (kit 1.66.0):
 python3 $QL spec-drift --repo <REPO>
 ```
 
+It searches the repo's own path first and the CONFIG ROOT (where `uscha.config.json` and
+the ledger live) second, and NAMES which of the two it read — in a monorepo the single
+`SPEC.md` at the root is the spec of every repo, and "no spec documents" used to be
+indistinguishable from "no drift" (kit 2.2.0).
+
 Milliseconds, deterministic, exit 0 always — it never gates, so running it every pass
 adds zero ceremony. What it adds is VISIBILITY: the run lands in the ledger, so the
 mirador card and `/uscha-status` show drift without anyone remembering the command —