@andresmassello/uscha 1.40.1

package/uscha-kit/templates/RUBRIC.md

@@ -0,0 +1,38 @@
+# RUBRIC — <name of the change or project>
+
+> The rubric is the ACCEPTANCE of the NON-testable: a versioned qualitative criterion,
+> with weights, anchors and threshold. A grader (any agent, any LLM, or a
+> human) scores it criterion by criterion WITH `file:line` evidence and emits the JSON
+> of the contract (see `templates/rubric-grader-prompt.md`); `qa_ledger.py rubric-ingest`
+> absorbs it. By default it ADVISES; it gates only if you declare it
+> (`defaults.rubric.gate: true` in the config, or `--gate`).
+>
+> Parseable format: `- [ ] RB-01 (peso 3) — criterion`. The weight is optional
+> (default 1). The anchors are for the grader; the engine does not parse them.
+
+threshold: 0.80
+
+## Criteria
+
+- [ ] RB-01 (peso 3) — Sane error handling: every external call has a timeout,
+  the failure is translated into an actionable message and exceptions are not swallowed.
+  - anchor-pass: `client.get(url, timeout=5)` + retry with backoff + log with context.
+  - anchor-fail: `except Exception: pass`, or a `catch` that only re-raises without context.
+- [ ] RB-02 (peso 2) — Repo conventions respected: naming, package structure
+  and style consistent with the neighboring code (not with the author's preference).
+  - anchor-pass: the new file is indistinguishable in style from its siblings.
+  - anchor-fail: a module with camelCase in a snake_case repo.
+- [ ] RB-03 (peso 2) — API/surface ergonomics: names that say what they do,
+  parameters without surprises, the common case is the easy one.
+- [ ] RB-04 (peso 1) — The change's documentation explains the WHY, it does not paraphrase
+  the code.
+
+## Negative criteria
+
+> Things that must NOT appear. If the grader finds them (verdict `fail` WITH
+> evidence), they subtract their weight from the score.
+
+- [ ] RB-NEG-01 (peso 2) — Comments that narrate the correctness of the change itself
+  ("now correctly handles...") instead of documenting the code.
+- [ ] RB-NEG-02 (peso 1) — Speculative abstractions: interfaces/layers with a single
+  use and no request in the SPEC.

package/uscha-kit/templates/docs/adr/README.md

@@ -0,0 +1,19 @@
+# Architecture Decision Records
+
+Durable technical decisions of this repo. One per file:
+`ADR-NNN-<slug>.md`. They are written by `/discovery` or `/adr-refine`, or proposed during the
+build when a real decision appears (see the ADR rules in `CLAUDE.md`).
+
+Format: Status (proposed/accepted/experiment/deprecated/superseded) · Context · Alternatives ·
+Decision · Consequences · Implementation Plan (affected paths, patterns, tests) ·
+Verification (checkboxes).
+
+`Status: Experiment` is for a bounded, reversible hypothesis that needs real feedback.
+It must include: Hypothesis, Feedback Signal, Review By or Review Trigger, Promote
+Criteria, and Rollback / Supersede Criteria. Missing/expired metadata is advisory in
+Mirador/dashboard; it is not a readiness score.
+
+## Index
+
+<!-- add one line per ADR -->
+- _(no ADRs yet)_

package/uscha-kit/templates/rubric-grader-prompt.md

@@ -0,0 +1,63 @@
+# Rubric grader — neutral prompt (works on any agent/LLM, or by hand)
+
+> This is the PORTABLE piece of the rubric layer: instructions for ANY runner —
+> Claude Code, Codex, Gemini CLI, Cursor, a `curl` to any API, or a human.
+> The only coupling with the method is the output JSON CONTRACT, which
+> `qa_ledger.py rubric-ingest` validates and ingests. Who emits the JSON is irrelevant.
+
+## Instructions for the grader
+
+You are an evaluator with an ISOLATED context. You read ONLY two things:
+
+1. `RUBRIC.md` — the criteria (weighted RB-nn, with anchors), the negative
+   criteria (RB-NEG-nn) and the threshold.
+2. The change's diff (or the changed files).
+
+You do NOT read the reasoning of whoever made the change, nor its description, nor its PR body —
+your value is precisely in having no attachment to how the result was produced.
+
+For each rubric criterion:
+
+- Emit a `pass` or `fail` verdict.
+- **Evidence is mandatory for every verdict that affects the score**
+  (a `pass` on a positive criterion; a `fail` on a negative one): a concrete
+  `file:line` citation + a snippet. Without evidence, the verdict does NOT score — the
+  engine discards it and lists it as unsupported.
+- Use the anchors as calibration: if the code looks more like the anchor-fail than
+  the anchor-pass, it is `fail`. When in doubt, `fail` — the optimistic bias is the
+  failure mode this contract exists to counter.
+- In `note`, one line of justification (what you saw, not what you assume).
+
+## The output contract (the only thing that matters)
+
+Write a single JSON:
+
+```json
+{
+  "criteria": [
+    {"id": "RB-01", "verdict": "pass",
+     "evidence": "src/client.py:42 — client.get(url, timeout=5) with retry",
+     "note": "all external calls have a timeout and backoff"},
+    {"id": "RB-02", "verdict": "fail",
+     "evidence": "src/NewModule.py:1 — camelCase in a snake_case repo",
+     "note": "does not follow the neighboring modules' convention"},
+    {"id": "RB-NEG-01", "verdict": "pass", "evidence": "", "note": "does not appear"}
+  ]
+}
+```
+
+- `id`: must exist in `RUBRIC.md` (unknown IDs = ingest error).
+- `verdict`: `pass` | `fail`. On the NEGATIVE ones, `pass` = the forbidden practice does NOT
+  appear; `fail` = it appears (and subtracts its weight from the score, with evidence).
+- Criteria you do not evaluate count as `fail` (not evaluated is not passed).
+
+## How it is ingested (the operator or the loop runs it, not you)
+
+```bash
+python3 <path>/qa_ledger.py rubric-ingest --repo <REPO> --report grader.json \
+  [--rubric RUBRIC.md] [--gate]
+```
+
+Advisory by default; `--gate` (or `defaults.rubric.gate: true` in the config — the
+human's declaration) turns a score below the threshold into a gated record:
+it blocks convergence and caps readiness ≤65 through the ledger's existing machinery.