@andresmassello/uscha 1.63.0 → 1.65.0

package/uscha-kit/.claude/skills/uscha-reverse-discovery/SKILL.md

@@ -5,8 +5,10 @@ description: >
   inverse of discovery: the system already exists and its behavior IS the truth, so you
   EXTRACT facts instead of proposing shape. Produce ONLY facts — a system map (endpoints,
   contracts, dependency graph, module candidates via static analysis) and a golden suite
-  captured mechanically at the boundaries. NEVER author an inferred SPEC or ADR of the old
-  system; the human writes those reading your facts. Invoke for "reverse-discovery",
+  captured mechanically at the boundaries — plus CANDIDATE specs in quarantine
+  (discovery/, evidence + confidence mandatory), which NEVER promote without a human
+  verdict in BEHAVIOR-LEDGER.md (ADR-009, INV-CURATION-01: the engine measures the gate).
+  Invoke for "reverse-discovery",
   "migrar/modernizar este sistema", "caracterizar el sistema viejo antes de tocarlo".
 allowed-tools: Read, Write, Glob, Grep, Bash
 disable-model-invocation: false
@@ -15,8 +17,9 @@ disable-model-invocation: false
 # reverse-discovery — extract the facts of an existing system before migrating it
 
 `uscha-discovery` is greenfield: you only have an idea, so you PROPOSE the shape. This is the
-opposite. The system already runs; its observable behavior is the ground truth. **You do
-not invent anything — you characterize what is already there, as facts.**
+opposite. The system already runs; its observable behavior is the ground truth. **Facts
+first, always — and what cannot be fact yet becomes a CANDIDATE in quarantine: evidenced,
+confidence-tagged, and promoted to the contract only by a human verdict (ADR-009).**
 
 ## First contact (show ONCE, then never again)
 
@@ -29,11 +32,11 @@ breadcrumb. Repeating it every run would be exactly the ceremony the method forb
 [uscha · reverse-discovery · START]
 Method: you bring the idea, the method builds the rest. Facts block, guesses advise;
         nothing closes on a checkbox, and the human approves the merge.
-Here:   I EXTRACT facts from the system that already exists. I never invent its spec -- you write that reading my facts.
+Here:   I EXTRACT facts and CANDIDATES from the system that already exists. Candidates stay quarantined until YOUR verdict promotes them.
 Output: SYSTEM-MAP.md · DISCOVERY-SUMMARY.md -- endpoints, contracts, dependency graph,
-        module candidates. Facts only: the SPEC and the ADRs are yours to write.
+        module candidates + discovery/ candidates + BEHAVIOR-LEDGER.md. The verdicts are yours.
 Next:   `/uscha-characterize` freezes current behavior and a HUMAN approves the golden;
-        only then do you write the migration SPEC, reading these facts + that golden.
+        only judged candidates reach the migration SPEC; the golden stays the oracle.
 Stop:   say so at any point -- whatever is already written stays.
 ```
 
@@ -88,17 +91,30 @@ and say exactly what unblocks it.
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
 
-## The one non-negotiable: produce ONLY facts
+## The one non-negotiable: quarantine, not judgment (ADR-009)
 
 A system map (from static analysis) and a golden suite (byte-captured) are FACTS —
-verifiable, not opinions. **You do NOT author a SPEC of "what it does" or ADRs of "why it
-is built this way."** Those are inference, and if the agent writes them it encodes its own
-(mis)reading of the code — the exact blind spot the golden exists to counter. The golden
-is field truth; a SPEC the agent writes about legacy code is a claim. So this skill emits
-facts, and the human infers meaning from them.
-
-If you catch yourself writing a requirement or a rationale, stop: that belongs to the human
-(and to `/uscha-adr-refine` for the FORWARD decisions), not here.
+verifiable, not opinions. What you read out of the code beyond that is a CLAIM, and an
+LLM's claim about legacy code is plausible on the surface and divergent from reality —
+the exact blind spot the golden exists to counter. The old rule banned authoring such
+claims outright; ADR-009 renegotiated it: **you may author them as CANDIDATES, in
+quarantine, and you may NEVER judge or promote them.**
+
+- Every candidate lives in `discovery/`, with mandatory frontmatter: `evidence.type`
+  (`test | code | inference`), `evidence.refs` (real `file:line(s)` — the engine resolves
+  them; a ref that does not resolve makes the candidate invalid, named), and `confidence`
+  (`inference` is ALWAYS `low`).
+- **You capture; you do not judge.** Never decide whether a behavior is bug or feature —
+  that is the verdict (`preserve` / `fix` / `undefined`), it belongs to the human, and it
+  lands in `BEHAVIOR-LEDGER.md` with an ADR per verdict. You may present a candidate with
+  its evidence and ASK; you may write the skeleton row once the human decides; the verdict
+  itself is theirs.
+- The gate is MEASURED, not promised: `qa_ledger.py curation-check` blocks the forward flow
+  while any candidate lacks a verdict (INV-CURATION-01) — and a malformed candidate or a
+  tampered ledger blocks harder (`exit 2`), because "could not validate" must never read
+  as judged.
+- The ledger is append-only (verified against git): reverting a verdict is a NEW row plus a
+  new ADR, never an edit.
 
 ## Phase 1 — Map (fact)
 
@@ -127,7 +143,29 @@ Delegate to the `uscha-characterize` skill; if it is not installed, follow its c
   inputs of past bugs. A boundary whose corpus does not exercise its known branches is
   marked **PARTIAL**, never covered.
 
-## Phase 3 — Summary (facts, no opinion)
+## Phase 3 — Candidates (claims, quarantined)
+
+For every observable behavior the map + golden surface, emit one candidate file in
+`discovery/` (`NNN-short-slug.md`): frontmatter per the section above, then a short
+description of the behavior — what it does, not whether it should. Undesigned edge cases
+are captured too, as `inference`/`low`. Then run:
+
+```bash
+python qa_ledger.py curation-check --repo <name>
+```
+
+Echo its output verbatim — it names invalid candidates and everything awaiting verdict.
+The skill wires; the engine measures.
+
+## Phase 4 — Curation (the human's verdicts)
+
+Present one candidate at a time: the behavior, its evidence refs, its confidence. Ask for
+the verdict. On each answer, append the ledger row (`| # | candidate | evidence |
+confidence | verdict | ADR-RD-NNN |`) and write the skeleton `ADR-RD-NNN` (5-10 lines:
+context, evidence, verdict, consequence) for the human to complete. Re-run `curation-check`
+after the pass: exit 0 means every candidate is judged and the quarantine is clear.
+
+## Phase 5 — Summary (facts, no opinion)
 
 Write `DISCOVERY-SUMMARY.md`: the system map + the golden coverage report (which boundaries
 are captured and approved, which are PARTIAL and why). This is the fact base the human reads
@@ -135,8 +173,9 @@ to write the migration SPEC. Do not editorialize.
 
 ## What you do NOT do (the human's job)
 
-- Do NOT write a SPEC of the old system's behavior — the golden IS the executable spec.
-- Do NOT write ADRs of the old system's implicit decisions.
+- Do NOT record a verdict, promote a candidate, or skip the ledger — the quarantine gate
+  is the human's, and the engine measures it (INV-CURATION-01).
+- Do NOT write the migration SPEC — only judged candidates feed it, and the human writes it.
 - Do NOT decide the NEW structure (module boundaries, shared kernel, sync vs events). Those
   are forward decisions → `/uscha-adr-refine`.
 
@@ -150,15 +189,17 @@ to write the migration SPEC. Do not editorialize.
 ## Convergence — finish when
 
 The map is complete (every boundary and dependency accounted for, or explicitly marked
-unknown), the golden is captured and **human-approved**, and the coverage report states
+unknown), the golden is captured and **human-approved**, every candidate has a verdict
+(`curation-check` exits 0 — measured, not remembered), and the coverage report states
 what is covered vs PARTIAL. State plainly that the facts are ready, then hand off.
 
 ## Handoff
 
-> "Read SYSTEM-MAP.md and DISCOVERY-SUMMARY.md, and inspect the approved golden. These are
-> FACTS about the current system. Now write the migration SPEC — behavior == golden,
-> structure == the new module boundaries — and take the partition decisions via /uscha-adr-refine.
-> Do not treat any of my output as a requirement or a rationale; those are yours to decide."
+> "Read SYSTEM-MAP.md, DISCOVERY-SUMMARY.md and BEHAVIOR-LEDGER.md, and inspect the
+> approved golden. The facts are measured; the verdicts are yours and recorded. Now write
+> the migration SPEC from the JUDGED candidates — `preserve` == golden must match, `fix` ==
+> divergence declared by its ADR, `undefined` == out of contract — and take the partition
+> decisions via /uscha-adr-refine."
 
 Flow (migration): `uscha-reverse-discovery` (facts) → human writes SPEC + `/uscha-adr-refine` (forward
 module decisions) → `/uscha-devloop` (restructure; `golden-diff` + `ApplicationModules.verify()`

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

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.63.0",
+  "version": "1.65.0",
   "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, 33 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
+  "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, 35 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.63.0",
+  "version": "1.65.0",
   "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.63.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.65.0 <!-- 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`,
@@ -178,6 +178,44 @@ Honest limit: this is **not** a substitute for CI. A local worktree runs on your
 OS, your shell - environment variance is invisible to it. Different failure class, different
 instrument.
 
+## Curation (ADR-009/010) - candidates in quarantine, verdicts on the record
+
+Reverse discovery's brownfield entry: the agent may author CANDIDATE specs of a legacy
+system - in `discovery/`, with mandatory `evidence` (`test|code|inference`) and
+`confidence` frontmatter, refs the engine resolves against real files - and **nothing is
+promoted without a human verdict**:
+
+```bash
+python qa_ledger.py curation-check --repo <name> [--json]
+```
+
+Verdicts live in `BEHAVIOR-LEDGER.md` (`preserve` / `fix` / `undefined`, one ADR each) -
+a human-readable table with machine-enforced rules: strict shape (`exit 2` on malformed,
+because under this gate a silent "no verdicts" would UNBLOCK what it guards), append-only
+verified against git (revert = new row + new ADR, never an edit; latest row wins). While
+any candidate lacks a verdict, `pr-ready` is blocked naming it (INV-CURATION-01) - the
+quarantine is measured, not promised. No `discovery/` directory -> the feature does not
+exist and nothing changes.
+
+## Oracle divergences + roundtrip (slice 2)
+
+A `fix` verdict means the new system must NOT match the legacy golden - and that divergence
+is **declared**, never tolerated implicitly:
+
+```json
+// golden.divergences.json
+{ "divergences": { "invoice-totals.approved.json": {
+    "adr": "ADR-RD-003", "reason": "IVA now rounds; legacy truncated" } } }
+```
+
+`golden-diff` then reads the pair as `expected_divergence` (named, with its ADR) instead of
+a blocker - and a declared pair that comes back **identical** goes red: the fix the
+declaration describes is not in the output. Malformed declarations exit 2.
+
+`roundtrip --repo <name>` is the advisory closing of the loop, v1: which promoted
+candidates are traceable in the code via an embedded `uscha-spec: <candidate>` marker -
+coverage by id, deliberately not semantic matching, exit 0 always.
+
 ## End-to-end flow
 
 `uscha-discovery` is the front for something new (you only have the idea); `uscha-adr-refine` is the front

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.63.0
+uscha-kit 1.65.0

package/uscha-kit/reports/junit/.curation-cases.json

@@ -0,0 +1 @@
+{"AC-RD-07": true, "AC-RD-01": true, "AC-RD-02": true, "AC-RD-03": true, "AC-RD-06": true, "AC-RD-04": true, "AC-RD-05": true}

package/uscha-kit/reports/junit/.oracle-cases.json

@@ -0,0 +1 @@
+{"AC-RD-08": true, "AC-RD-09": true, "AC-RD-10": true, "AC-RD-11": true}