@andresmassello/uscha 1.85.0 → 1.85.1

package/README.md

@@ -8,7 +8,7 @@ never what was claimed.
 > The tool executes · the method governs · evidence decides · the human approves.
 
 **[uscha.dev](https://uscha.dev)** — the method, the five rules, the skills, the library
-(essay, 2-day dev course, reference, paper).
+(the diamond thesis, how-it-works diagrams, essay, 2-day dev course, reference, paper).
 
 ```bash
 npx --yes @andresmassello/uscha@latest install --target claude   # Claude Code
@@ -40,12 +40,77 @@ 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 v1.85.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.85.1** <!-- 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)
 
 ---
 
+## The diamond — specs are the source code, end to end
+
+Uscha closes a cycle most spec-driven tools only walk halfway. The **spec package plus its
+behavior ledger** is the canonical asset of a system; the code is a regenerable build artifact.
+An LLM compiles the package into code under a validated contract; reverse discovery decompiles
+existing code back into *curated* specs — passing, mandatorily, through the one step no
+automatic tool can perform: a human verdict.
+
+```
+                THE ASSET (solid) ── it appreciates with every model generation
+          ┌───────────────────────────────────────────────────────────────┐
+          │   SPEC PACKAGE  +  BEHAVIOR LEDGER  +  IR                     │
+          │   SPEC · ADRs · ACCEPTANCE · CONSTITUTION                     │
+          │   verdicts: preserve · fix · undefined                        │
+          └──────────────┬─────────────────────────────▲──────────────────┘
+                         │                             │
+        FORWARD          │                             │          REVERSE
+        the LLM compiles │                             │   reverse discovery
+                         ▼                             │
+   ┌─────────────────────────────────────┐   ┌─────────┴─────────────────────┐
+   │ compile-validate — output contract, │   │ CURATION · the human gate     │
+   │   mechanical only, model-blind      │   │ candidate ─▶ verdict ─▶ ledger │
+   │ withheld ORACLE — authored BEFORE   │   │ no verdict → PR blocked,      │
+   │   compiling, never in the prompt    │   │   the candidate is NAMED      │
+   └─────────────────┬───────────────────┘   └─────────▲─────────────────────┘
+                     │                                 │
+                     ▼                                 │
+   ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐   ┌─────────────┴─────────────────────┐
+     CODE (dashed) — build artifact,      │ discover · golden capture         │
+     regenerable, disposable          ───▶│ candidates: typed evidence        │
+   └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘   │   + confidence                    │
+                                          └───────────────────────────────────┘
+                                            ▲ also enters here: any LEGACY
+                                              system (= 100% drift)
+
+   round trip · bench-roundtrip — how much of the asset the reverse organs re-anchor
+   from the compiled code: 0.062 measured (12 archetypes) — names, not yet semantics
+```
+
+**What each arrow is, in the engine (kit 1.85.1, 51 subcommands, all measured):**
+
+| Leg | Subcommands | What it establishes |
+|---|---|---|
+| Asset → typed graph | `ir-extract`, `ir-render` | the whole package becomes one canonical IR (M2, ADR-015) — deterministic, `UNTYPED` is a measurement not an error |
+| Forward, the compiler | `compile-validate`, `compile-ingest` | any model produces code; the engine validates the output contract and never compiles (M3, ADR-016) |
+| Forward, is it the *same* system? | `bootstrap-oracle`, `bootstrap-variance`, `bench` | a withheld oracle judges blind compilations — **12 archetypes, 9 PASS · 3 PARTIAL**, three models, JS included (M4/M5, ADR-017/018/028/029) |
+| Reverse, facts | `discover`, `golden-diff` (+ the `/uscha-characterize` skill) | system map + mechanically captured golden; typed candidate observations with evidence class (M1, ADR-013) |
+| Reverse, the human gate | `curate`, `promote`, `curation-check`, `bench-curate` | one verdict per candidate, append-only ledger verified against git; unjudged → `pr-ready` blocked naming it (ADR-009/010, INV-CURATION-01) |
+| Fidelity, honestly | `fidelity`, `roundtrip`, `bench-roundtrip`, `bench-r2` | per-compiler fidelity vector, id-level round trip, recoverability **0.062**, and the **noise floor** under every variance claim (ADR-014/022/027/030) |
+
+**Read the numbers the way the repo does.** 9 of 12 archetypes regenerate to the same system
+under an oracle the compilers never saw — that is the closed loop working. 0.062 is the mean
+*recoverability* of the asset from compiled code counting only static and behavioural
+footing, with the behaviour dimension still `UNMEASURED` — it says the reverse organs anchor
+**names, not yet semantics**, and it is published rather than smoothed. And `bench-r2` measured
+that same-model reruns differ structurally about as much as different models do (aggregate
+`NOISY`) — so one earlier variance narrative was **retracted**. Every claim above is a subcommand
+you can run; every unmeasured part is labeled. That honesty is the method applied to itself.
+
+→ The full thesis, with before/after diagrams and the REAL vs VISION table:
+**[uscha.dev/diamond](https://uscha.dev/diamond)** · the mechanism, in three diagrams:
+**[uscha.dev/how](https://uscha.dev/how)**
+
+---
+
 ## The problem it solves
 
 An agent will tell you the tests pass. It will tell you the feature is done. It is often
@@ -68,7 +133,7 @@ and see which file, which test, and when.
 |---|---|
 | `/uscha-discovery` | Idea → spec package (CONTEXT, SPEC, ADRs, CONSTITUTION, ACCEPTANCE) |
 | `/uscha-adr-refine` | Known feature → ADR + ACCEPTANCE, by interrogating you first |
-| `/uscha-reverse-discovery` | Existing system → extracted facts (brownfield migrations) |
+| `/uscha-reverse-discovery` | Existing system → facts + typed candidates in quarantine; never promoted without a human verdict (brownfield) |
 | `/uscha-characterize` | Capture a golden suite of current behavior before touching it |
 | `/uscha-devloop` | Plan → build → severity-gated QA loop → PR (stops at the merge) |
 | `/uscha-rubric` | Grade the non-testable (conventions, ergonomics) against a versioned rubric |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.85.0",
+  "version": "1.85.1",
   "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-devloop/qa_ledger.py

@@ -8231,8 +8231,15 @@ def cmd_readiness(args):
     # hacia adelante (no backfillea). El dashboard lo consume, nunca escribe.
     if getattr(args, "record", False):
         now = _now()
+        # issue #1 (field note 001, limitation 1): persist the CAUSES per entry, not only the
+        # score -- both facts are already computed above; nothing is re-derived. Additive keys:
+        # every existing reader uses .get("at")/.get("score"). None/0 mean "no cap"/"none
+        # discarded", stated rather than absent.
         ledger.setdefault("readiness_history", []).append(
-            {"at": now, "score": round(final, 1)})
+            {"at": now, "score": round(final, 1),
+             "cap_applied": ({"reason": cap_reason, "key": cap_key} if cap_reason else None),
+             "stale_discarded": {"count": len(stale_reports),
+                                 "reports": list(stale_reports)[:8]}})
         # kit 1.46.1: persist a compact MEASURED summary so the statusline (uscha_progress.py)
         # shows MEASURED acceptance -- the same truth this readiness computed -- instead of
         # counting checkboxes (narrated). Write-once/read-many: the fast Stop hook reads this

package/uscha-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.85.0",
+  "version": "1.85.1",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 51 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

package/uscha-kit/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.85.0",
+  "version": "1.85.1",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.85.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.85.1 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.85.0
+uscha-kit 1.85.1

package/uscha-kit/skills/uscha-devloop/qa_ledger.py

@@ -8231,8 +8231,15 @@ def cmd_readiness(args):
     # hacia adelante (no backfillea). El dashboard lo consume, nunca escribe.
     if getattr(args, "record", False):
         now = _now()
+        # issue #1 (field note 001, limitation 1): persist the CAUSES per entry, not only the
+        # score -- both facts are already computed above; nothing is re-derived. Additive keys:
+        # every existing reader uses .get("at")/.get("score"). None/0 mean "no cap"/"none
+        # discarded", stated rather than absent.
         ledger.setdefault("readiness_history", []).append(
-            {"at": now, "score": round(final, 1)})
+            {"at": now, "score": round(final, 1),
+             "cap_applied": ({"reason": cap_reason, "key": cap_key} if cap_reason else None),
+             "stale_discarded": {"count": len(stale_reports),
+                                 "reports": list(stale_reports)[:8]}})
         # kit 1.46.1: persist a compact MEASURED summary so the statusline (uscha_progress.py)
         # shows MEASURED acceptance -- the same truth this readiness computed -- instead of
         # counting checkboxes (narrated). Write-once/read-many: the fast Stop hook reads this

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.85.0",
+  "version": "1.85.1",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,