@andresmassello/uscha 1.40.1

package/uscha-kit/skills/uscha-mirador/telemetry-extract.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""telemetry-extract.py -- vendor telemetry for the mirador (uscha-kit 1.33.0).
+
+Parses a Claude Code session transcript (*.jsonl) and appends ONE line to the
+telemetry sidecar (.uscha/telemetry.jsonl) summarizing that session's token and
+wall-time cost, broken down by model.
+
+This is VENDOR telemetry (Claude Code), NOT engine measurement. It lives in the
+mirador skill (the vendor adapter), NEVER in qa_ledger.py -- the engine stays
+model-agnostic and never sees a token. The mirador shows this in a segregated
+strip; it is never gated and never feeds readiness (measured beats narrated).
+
+Usage:
+  python3 telemetry-extract.py <transcript.jsonl> [--sidecar .uscha/telemetry.jsonl] [--note "..."]
+
+Best-effort: unknown/older transcript schemas degrade (missing fields -> 0/None),
+never crash. If no usage data is found, nothing is appended.
+"""
+import argparse
+import json
+import os
+import sys
+from datetime import datetime
+
+
+def _ts(v):
+    if not v:
+        return None
+    try:
+        return datetime.fromisoformat(str(v).replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return None
+
+
+def extract(transcript_path):
+    """Returns (by_model: {model: [tin, tout]}, t_min, t_max, seen: bool)."""
+    by_model = {}
+    t_min = t_max = None
+    seen = False
+    with open(transcript_path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except ValueError:
+                continue
+            ts = _ts(rec.get("timestamp"))
+            if ts:
+                t_min = ts if (t_min is None or ts < t_min) else t_min
+                t_max = ts if (t_max is None or ts > t_max) else t_max
+            msg = rec.get("message") or {}
+            usage = msg.get("usage")
+            if not isinstance(usage, dict):
+                continue
+            model = msg.get("model") or rec.get("model") or "unknown"
+            tin = ((usage.get("input_tokens") or 0)
+                   + (usage.get("cache_read_input_tokens") or 0)
+                   + (usage.get("cache_creation_input_tokens") or 0))
+            tout = usage.get("output_tokens") or 0
+            if tin == 0 and tout == 0:
+                continue
+            agg = by_model.setdefault(model, [0, 0])
+            agg[0] += tin
+            agg[1] += tout
+            seen = True
+    return by_model, t_min, t_max, seen
+
+
+def main():
+    ap = argparse.ArgumentParser(description="append a Claude Code session's token/time cost to the mirador telemetry sidecar")
+    ap.add_argument("transcript", help="path to a Claude Code session transcript (*.jsonl)")
+    ap.add_argument("--sidecar", default=os.path.join(".uscha", "telemetry.jsonl"),
+                    help="append-only telemetry file (default: .uscha/telemetry.jsonl)")
+    ap.add_argument("--session", default=None,
+                    help="session key for idempotent upsert (default: transcript basename); "
+                         "re-running replaces this session's line instead of appending -- "
+                         "so a watch/refresh loop does not inflate the totals")
+    ap.add_argument("--note", default=None, help="optional label for this session line")
+    args = ap.parse_args()
+
+    by_model, t_min, t_max, seen = extract(args.transcript)
+    if not seen:
+        print("[telemetry-extract] no usage data found -- nothing appended", file=sys.stderr)
+        return 0
+
+    bm = [{"model": m, "tokens_in": v[0], "tokens_out": v[1]}
+          for m, v in sorted(by_model.items())]
+    total_in = sum(v["tokens_in"] for v in bm)
+    total_out = sum(v["tokens_out"] for v in bm)
+    ms = int((t_max - t_min).total_seconds() * 1000) if (t_min and t_max) else None
+    at = t_max.isoformat() if t_max else None
+    rec = {
+        "at": at,
+        "model": bm[0]["model"] if len(bm) == 1 else "+".join(v["model"] for v in bm),
+        "tokens_in": total_in, "tokens_out": total_out, "ms": ms,
+        "by_model": bm,
+    }
+    session = args.session or os.path.basename(args.transcript)
+    rec["session"] = session
+    if args.note:
+        rec["note"] = args.note
+
+    os.makedirs(os.path.dirname(args.sidecar) or ".", exist_ok=True)
+    # upsert by session: re-running (watch mode) REPLACES this session's line instead of
+    # appending a duplicate -> a refresh loop never inflates the aggregated totals.
+    kept = []
+    if os.path.isfile(args.sidecar):
+        for line in open(args.sidecar, encoding="utf-8"):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                prev = json.loads(line)
+            except ValueError:
+                continue
+            if prev.get("session") != session:
+                kept.append(prev)
+    kept.append(rec)
+    with open(args.sidecar, "w", encoding="utf-8") as f:
+        for r in kept:
+            f.write(json.dumps(r, ensure_ascii=False) + "\n")
+    print(f"[telemetry-extract] {session}: {total_in} in / {total_out} out "
+          f"across {len(bm)} model(s) -> {args.sidecar} (upsert)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,116 @@
+---
+name: uscha-reverse-discovery
+description: >
+  Brownfield front of the methodology, for migrating/modernizing an EXISTING system. The
+  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",
+  "migrar/modernizar este sistema", "caracterizar el sistema viejo antes de tocarlo".
+allowed-tools: Read, Write, Glob, Grep, Bash
+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.**
+
+## The one non-negotiable: produce ONLY facts
+
+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.
+
+## Phase 1 — Map (fact)
+
+Static analysis only. Extract, and write to `SYSTEM-MAP.md`:
+- **Boundaries**: every public endpoint / operation / message topic, with its contract
+  (request/response schema, status codes, idempotency where observable).
+- **Dependency graph**: who calls whom (service→service, module→module, DB, external APIs).
+  Flag cycles and hubs.
+- **Module candidates**: current package/service structure and natural seams (this is
+  observation of the CURRENT layout, NOT a proposal for the new one).
+Everything here must be traceable to code. No "this seems to…", no guessed intent.
+
+## Phase 2 — Characterize (fact)
+
+Capture the golden at the system boundaries by running the ORIGINAL code with REAL inputs.
+Delegate to the `uscha-characterize` skill; if it is not installed, follow its contract inline:
+- Write a deterministic capture harness (you MAY author the harness).
+- Normalize every non-determinism source before serializing: timestamps, seeds, map/set
+  iteration order, GUIDs/auto-increment, concurrency, **the target locale**, and use
+  deterministic serialization (sorted keys, fixed float precision, explicit encoding).
+- Run the capture → `.received`. **STOP.** Return control to the human to review and
+  approve the `.approved`.
+- **You NEVER create, rename, or edit a `.approved` file** (INV-GOLDEN-01). It is field
+  truth; only a human approves it.
+- Corpus in order of value: real/recorded production inputs → hand-built edge cases →
+  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)
+
+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
+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 decide the NEW structure (module boundaries, shared kernel, sync vs events). Those
+  are forward decisions → `/uscha-adr-refine`.
+
+## Guardrails
+
+- `.approved` files are sacred and human-approved; the agent is mechanically forbidden from
+  writing them (a `PreToolUse` hook on `**/*.approved.*` should enforce it).
+- `.gitattributes`: `*.approved.* binary` (line endings must not create false diffs).
+- Corpus insufficient → PARTIAL. Never claim coverage you did not exercise.
+
+## 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
+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."
+
+Flow (migration): `uscha-reverse-discovery` (facts) → human writes SPEC + `/uscha-adr-refine` (forward
+module decisions) → `/uscha-devloop` (restructure; `golden-diff` + `ApplicationModules.verify()`
+stay green the whole way) → readiness + human gate.
+
+## Relationship to the other skills
+
+- **discovery** (greenfield): you PROPOSE the shape from an idea. **reverse-discovery**
+  (brownfield): you EXTRACT facts from a running system. Opposite direction, opposite trust
+  model.
+- **characterize**: the golden-capture sub-step this skill orchestrates in Phase 2.
+- **adr-refine**: where the FORWARD decisions (the new module boundaries) are taken — this
+  skill deliberately does not.
+
+## Why this skill is safe by construction
+
+It lives entirely on the FACTS side of the facts-vs-prose line: static analysis and
+byte-capture, both verifiable. Unlike a prose-heuristic gate, there is no interpretation to
+get wrong — so there is nothing fragile to break. If a step would require guessing, it has
+left this skill's scope.
+
+## Tracked-markdown protocol
+
+If `SYSTEM-MAP.md` / `DISCOVERY-SUMMARY.md` already exist and are tracked, ask for the
+current version before overwriting — never silently replace real progress.

package/uscha-kit/skills/uscha-rubric/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: uscha-rubric
+description: >
+  Grade the change against the versioned RUBRIC.md (the ACCEPTANCE of the
+  non-testable: conventions, error-handling sanity, API ergonomics, doc quality)
+  and ingest the verdict into the ledger. This skill is a THIN ADAPTER for
+  Claude Code: the portable core is templates/rubric-grader-prompt.md (works on
+  Codex, Gemini CLI, Cursor, raw API, or a human) + the vendor-neutral JSON
+  contract that `qa_ledger.py rubric-ingest` validates. Advisory by default;
+  gates only when the human declares it. Invoke for "grade the rubric",
+  "evaluá la rúbrica", "rubric pass".
+allowed-tools: Read, Write, Glob, Grep, Bash
+disable-model-invocation: false
+---
+
+# uscha-rubric — grade the non-testable against versioned criteria (adapter)
+
+**Architecture note (read this first).** You are the Claude Code ADAPTER of a
+vendor-neutral layer. The core is: `RUBRIC.md` (versioned criteria) + the JSON
+contract + `qa_ledger.py rubric-ingest` (stdlib, runs anywhere). ANY runner can be
+the grader — this skill just wraps the neutral prompt so Claude Code users get it
+in one command. Never add Claude-specific behavior to the contract.
+
+## Protocol
+
+1. **Locate the rubric**: `defaults.rubric.file` in `uscha.config.json`, else
+   `./RUBRIC.md`. If absent, offer to create one from `templates/RUBRIC.md` and STOP
+   (the criteria are the human's to approve — propose, don't impose).
+2. **Validate structure first** (facts block):
+
+```bash
+QL="./.claude/skills/uscha-devloop/qa_ledger.py"
+[ -f "$QL" ] || QL="$HOME/.codex/skills/uscha-devloop/qa_ledger.py"
+[ -f "$QL" ] || QL="$HOME/plugins/uscha/skills/uscha-devloop/qa_ledger.py"
+[ -f "$QL" ] || QL="$HOME/.claude/skills/uscha-devloop/qa_ledger.py"
+python3 $QL spec-check --rubric RUBRIC.md    # exit 1 = fix the rubric before grading
+```
+
+3. **Grade with ISOLATED context** — follow `templates/rubric-grader-prompt.md` to
+   the letter: read ONLY the diff + RUBRIC.md (not the maker's reasoning, not the PR
+   body). For every criterion emit `pass|fail`; **evidence `file:line` is mandatory
+   for any verdict that affects the score** (a positive's pass, a negative's fail) —
+   without it the engine discards the verdict. Anchors calibrate you; when in doubt,
+   fail (the optimist bias is the failure mode this layer exists to counter).
+4. **Write the contract JSON** to `reports/rubric-grade.json`:
+
+```json
+{"criteria": [{"id": "RB-01", "verdict": "pass",
+               "evidence": "src/x.py:42 — ...", "note": "..."}]}
+```
+
+5. **Ingest** (the ledger validates IDs, applies evidence-or-nothing, computes the
+   weighted score vs threshold, and persists — advisory by default):
+
+```bash
+python3 $QL rubric-ingest --repo <REPO> --report reports/rubric-grade.json \
+  --iteration <N>            # add --gate ONLY if the human declared it
+```
+
+A below-threshold score with the gate declared (config `defaults.rubric.gate: true`
+or `--gate`) blocks convergence and caps readiness ≤65 through the existing ledger
+plumbing. Without the declaration it advises — never silently escalate it yourself.
+
+## Non-negotiables
+
+- **Maker ≠ grader**: never grade a change you authored in this same context. Run
+  the grade in a fresh/isolated pass (that separation is the entire value).
+- **Evidence-or-nothing**: a verdict without a `file:line` citation does not count —
+  the engine enforces it, you comply with it.
+- The rubric file is the HUMAN's criterion: propose edits, never rewrite it silently
+  (tracked-markdown protocol applies).
+- This layer never replaces the hard gates (tests, golden, gate-check, simplicity):
+  it is the structured-guess layer — facts block, guesses advise.
+
+## Relationship to the other skills
+
+- `uscha-devloop` runs this in Phase 3b alongside gate-check when a rubric exists.
+- `uscha-discovery` / `uscha-adr-refine` are where the human's quality criteria
+  crystallize — a RUBRIC.md can be drafted there (step: quality bar).

package/uscha-kit/skills/uscha-sysdoc/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: uscha-sysdoc
+description: >
+  Generate a single self-contained, navigable HTML deck (PowerPoint-style, keyboard +
+  click navigation) documenting a system in two parallel tracks: a commercial/CEO view
+  and a technical view. Pulls real metrics from QA-LEDGER.json, includes inline SVG
+  diagrams, dark control-room aesthetic. Invoke for "document this system",
+  "make the system deck", "commercial + tech doc". Pairs with the dev-loop skill.
+allowed-tools: Read, Write, Glob, Grep, Bash
+disable-model-invocation: false
+---
+
+# sys-doc — two-view system deck generator
+
+Produce ONE self-contained `.html` file (no external assets, no CDN, no localStorage)
+that reads like a slide deck and documents the system on two tracks the reader can
+switch between at any time:
+
+- **Commercial / CEO track** — what the system does, the value, the risk posture, the
+  status. No code. Plain business language. Money/time/reliability framing.
+- **Technical track** — architecture, modules, data flow, contracts, QA results,
+  coverage, known deferred issues.
+
+## Inputs
+
+1. **Metrics (authoritative):** run the ledger summary and use its numbers verbatim —
+   never invent figures.
+
+```bash
+QL="./.claude/skills/uscha-devloop/qa_ledger.py"                      # instalacion por proyecto
+[ -f "$QL" ] || QL="$HOME/.codex/skills/uscha-devloop/qa_ledger.py"   # Codex raw-skills install
+[ -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 summary --json > /tmp/qa-summary.json
+python3 $QL readiness --json > /tmp/qa-readiness.json
+```
+
+   From the summary use: `total_steps`, `by_tool`, `by_repo`, `aggregate`, `escalations`.
+   From readiness use: `score`, `status`, `cap_reason`, `dimensions`, `acceptance`,
+   `by_repo`. Render readiness as a **semaphore widget** at the top of slide 5 and as a
+   per-repo readiness column on the technical QA slide: green ≥80, amber 50–79, red <50,
+   and always print the `cap_reason` when a hard cap is active.
+
+2. **System understanding:** read the ADR/PLAN, CLAUDE.md, module layout, and key
+   contracts to describe architecture and value. If no ledger exists, ask whether to
+   proceed without QA metrics (the deck still works, just without the QA section).
+
+3. **Tracked-markdown protocol:** the HTML output itself is not tracked markdown, so
+   generate freely. But if asked to also update a tracked `.md`, ask for its current
+   version first.
+
+## Structure (each is one navigable slide)
+
+1. **Title** — system name, one-line purpose, date, run id.
+2. **Track switcher** — persistent toggle: Commercial ⇄ Technical (affects which
+   slides/sections show; default Commercial).
+3. Commercial: **What it does** (plain language, the job it removes).
+4. Commercial: **Value & status** (what's done, what's in flight, risk posture).
+5. Commercial: **Quality at a glance** — coverage %, tests count, a simple
+   "issues found and resolved" readout from `by_tool`. No jargon.
+6. Technical: **Architecture** — inline SVG: modules/repos as boxes, data flow as
+   arrows, external systems (DB, external APIs, devices) distinct.
+7. Technical: **Key contracts / interfaces** — the seams between repos/modules.
+8. Technical: **QA results** — per-tool table (reported / fixed / %fixed / deferred /
+   suppressed), coverage per repo, tests/kLOC, escalations list.
+9. Technical: **Deferred issues** — summarize `ISSUES-DEFERRED.md` honestly.
+10. **Smoke checklist** — the manual verification steps.
+
+## Build constraints
+
+- Single `.html`, all CSS/JS inline. Works opened directly from disk and deployable to
+  Cloudflare Pages / S3 as-is.
+- **No localStorage / sessionStorage** (won't run in some sandboxes). Hold nav state in
+  JS variables only.
+- Navigation: arrow keys (← →), on-screen prev/next, a slide index/dots, and Esc for an
+  overview grid. Slide counter visible.
+- Diagrams are hand-authored inline `<svg>` using `currentColor`/CSS variables so they
+  theme with the deck. No raster images, no external diagram libs.
+- Aesthetic: dark control-room (deep neutral background, one accent, high-contrast
+  mono for technical figures), but keep the Commercial track clean and uncluttered.
+- Accessible: semantic headings, `aria-label`s on nav controls, visible focus, contrast
+  AA. Readable when printed (print stylesheet flattens slides to a linear document).
+
+## Output
+
+Write to `docs/system-deck.html` (or the path the human gives). Then state the file
+path and the two or three things the reader should look at first. Do not paste the HTML
+into chat — present the file.

package/uscha-kit/templates/.gitattributes

@@ -0,0 +1,6 @@
+# Golden / approval fixtures: treat as binary so line-ending normalization can NEVER
+# create false diffs (critical on Windows / SQL Server). See INV-GOLDEN-01.
+*.approved.* binary
+*.received.* binary
+*.approved   binary
+*.received   binary

package/uscha-kit/templates/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md — repo protocol (Uscha)
+
+**Permanent** rules for this repo. Claude Code reads them at every session. What is specific to
+each change lives in `SPEC.md` / `docs/adr/` / `ACCEPTANCE.md`, not here.
+
+> If you use other agents besides Claude Code, copy this file as `AGENTS.md`
+> (same content) so they read it too.
+
+## Non-negotiable rules
+
+1. **Don't code from a vague idea.** If there is no `SPEC.md` + `ACCEPTANCE.md`, model
+   first: `/uscha-discovery` (new system) or `/uscha-adr-refine` (known feature). Only once the
+   package is written do you build.
+2. **Truth lives in files, not in the chat.** Before touching code, read `SPEC.md`,
+   `ACCEPTANCE.md` and `docs/adr/*.md`. Don't rely on the conversation: context
+   resets, and sub-agents and CI read the repo.
+3. **Converge, don't chase zero.** Apply only the findings ≥ severity gate; the rest
+   goes to `ISSUES-DEFERRED.md`. The loop ends when it converges, not when "there are no issues".
+4. **ADR + CONSTITUTION discipline during the build.** Before touching an area, read
+   `CONSTITUTION.md` (inviolable invariants) and the ADRs for the area. Stop and propose an ADR if
+   you are going to: introduce a new dependency, create a new pattern, choose between non-obvious
+   alternatives, or contradict an accepted ADR. **A CONSTITUTION violation is a BLOCKER: it is
+   escalated, never worked around.** Link the code with `// ADR: <slug> — see docs/adr/...`.
+5. **Evidence captured, not narrated.** Evidence is produced by execution (tests,
+   gates, coverage) — it is not transcribed by hand. Absent = no evidence, never "OK".
+6. **Legacy baseline.** In old code: 0 new HIGH/CRITICAL findings, 0 regressions,
+   no new warnings in touched files. Old debt is frozen, new debt is blocked.
+7. **Change budget.** Max iterations/files per the plan; 0 schema changes without an
+   ADR; 0 new dependencies without approval. If the scope is exceeded or a fix reverts another
+   → escalate (don't keep going alone).
+8. **Never edit the SPEC/ADR to make the implementation look correct.** If reality
+   forces a SPEC change, version it and go back to Ready.
+9. **Human gate.** Don't merge or release automatically. You stop at the PR; the merge and
+   the smoke test in a real environment are decided by a person.
+
+## Truth hierarchy
+
+`CONSTITUTION.md` (what is never acceptable) ▸ `SPEC.md` (what must happen) ▸ `docs/adr/` (why this shape). The CONSTITUTION sits above the ADRs: no ADR or SPEC may violate it. `/uscha-discovery`, `/uscha-adr-refine` and `/uscha-devloop` read it before proposing or touching anything.
+
+## Commands (skills)
+
+- `/uscha-discovery` — idea → CONTEXT/DOMAIN-MODEL/CONSTITUTION/SPEC/ADR/ACCEPTANCE/RISKS/HANDOFF
+- `/uscha-adr-refine` — known feature → SPEC + ADR + ACCEPTANCE
+- `/uscha-devloop` — plan → build → QA loop → PR (stops at the merge)
+- `/uscha-sysdoc` — documents the system from the ledger
+
+## Project adapter (TO COMPLETE per repo)
+
+> This is the only stack-specific part. Complete it and delete this reminder.
+
+- **Build:** `<e.g. mvn -q compile>`
+- **Tests:** `<e.g. mvn -q test>`
+- **Static gate:** `<e.g. mvn -q verify -Pqa  → checkstyle-result.xml, pmd.xml, spotbugsXml.xml>`
+- **Coverage:** `<e.g. target/site/jacoco/jacoco.xml>`
+- **No-go zones:** `<folders/files that are not touched>`
+- **Secrets / credentials:** `<where they are and what NOT to log>`

package/uscha-kit/templates/CONSTITUTION.md

@@ -0,0 +1,149 @@
+# CONSTITUTION.md — project invariants (Uscha)
+
+The layer **above the ADRs**. It records what **no ADR or SPEC may violate**,
+whatever trade-off wins. An ADR *chooses* between alternatives; the CONSTITUTION *forbids*.
+
+> Truth hierarchy: **SPEC** = what must happen · **ADR** = why this shape ·
+> **CONSTITUTION** = what is never acceptable.
+
+Versioned, one per project. `/discovery`, `/adr-refine` and `/dev-loop` read it **before**
+proposing or touching anything. A violation is a **BLOCKER** finding (non-negotiable): the agent
+MUST record it — `qa_ledger.py flag-blocker --kind constitution` — and once recorded it
+blocks convergence and caps readiness ≤65 until `--resolve` (a human decision). The engine
+does not read this file: the obligation to detect and record the violation belongs to the agent/human;
+enforcing the record is the engine's job. It is never resolved by "working around it" in code.
+
+## Security (non-negotiable)
+
+- [ ] Secrets never in logs or in the repo            <!-- CWE-532 / CWE-798 -->
+- [ ] Every external input validated before use      <!-- CWE-20 -->
+- [ ] Only parameterized SQL, never concatenated        <!-- CWE-89 -->
+- [ ] Credentials / certificates encrypted at rest
+- [ ] Never cross environments or credentials (dev / prod)
+
+## Domain (TO COMPLETE per project)
+
+> Business rules that can never be broken. Examples (replace with those of your domain):
+
+- [ ] Mandatory idempotency on critical operations
+- [ ] Sequential numbering with no logical gaps
+- [ ] Exactness to the cent; never two effects for the same `requestId`
+
+## Operation (non-negotiable)
+
+- [ ] No destructive migration without an explicit rollback
+- [ ] No automatic merge or release — human gate always
+- [ ] Evidence captured by execution, never narrated
+
+## Simplicity — "Reduce" (non-negotiable)
+
+> Maeda's law 1 and Karpathy's "Simplicity First", made a deterministic gate.
+> It is not CC by AST: they are measurable *proxies* over the diff. Measured by
+> `qa_ledger.py simplicity-check`; an **OVERBUILT** verdict is a **BLOCKER** finding.
+
+- [ ] Minimal code that solves what was asked — no unrequested features, layers or "flexibility" <!-- YAGNI / speculative generality -->
+- [ ] No speculative abstractions — every new type/layer is justified against the SPEC <!-- YAGNI -->
+- [ ] Bounded nesting — flatten with guard clauses / extract function <!-- CWE-1124 -->
+- [ ] Change bounded to the budget (`defaults.simplicity`) — subtract before adding
+- [ ] "Would a senior say this is overbuilt?" If yes, it is trimmed before converging
+
+## Reuse — "REUSE-FIRST" (principle; the proxy ADVISES, gates if declared)
+
+> Waste of duplication (Poppendieck ch. 4): AI code reinvents instead of reusing
+> (GitClear *Maintainability Gap*: +81% duplication since 2023). `simplicity-check`
+> does NOT see it — it scores the diff in ISOLATION, never against what already exists. Measured by
+> `qa_ledger.py waste-check` (Type-1/2 clones of the diff vs the repo). The FACT —a block
+> of 5+ lines already exists at `file:line`— is measured; the "wasteful" VERDICT is a
+> heuristic with known false positives (boilerplate, DTOs, embedded SQL/JSON), so
+> it **advises by default** and gates ONLY with `defaults.waste.gate: true` or `--gate`
+> (provenance: the committed config IS the declaration). CWE-1041 / DRY.
+
+- [ ] Don't reimplement what already exists in the repo — reuse before cloning
+- [ ] Duplication within the change bounded — extract a helper before cloning
+- [ ] A WASTEFUL, if the human declared the gate, is reused/refactored, not converged
+
+## Effective tests — "coverage lies" (non-negotiable)
+
+> Coverage says the line *ran*; not that a test *verifies* it. Effectiveness is
+> measured with mutation testing (PIT): if mutating the code doesn't break the test, the test
+> doesn't assert. Measured by `qa_ledger.py pit-check` over `mutations.xml`.
+
+- [ ] Tests ASSERT behavior, not just execute code <!-- assertion-gap -->
+- [ ] Test-strength above the gate (`--min-score`) in the touched area
+- [ ] Zero live mutants in domain logic / critical path without explicit justification
+- [ ] High coverage with live mutants = false safety; the gap is closed, not ignored
+
+## Gate integrity — "don't game the meter" (non-negotiable)
+
+> A maker-optimizer takes the cheapest path to "green", and editing the gate is usually
+> the cheapest. The apparatus that measures correctness is NOT modified by the change that it measures,
+> without explicit human sign-off. (Osmani lists the red-flags; the rule is the kit's synthesis.)
+
+- [ ] The change does not weaken the gate: no deleting or skipping tests, no disabling lint, no lowering thresholds
+- [ ] Mass rewrite of existing asserts = flag (the safety net edited to accept what is broken)
+- [ ] No new helper duplicating an existing one <!-- reuse / Reduce -->
+- [ ] High blast-radius: the checker is uncorrelated with the maker (another family/profile); the loop that produced the change is not its only approver
+- [ ] Test diffs are read more strictly than production ones
+
+## Golden — pre-change behavior (non-negotiable)
+
+> **INV-GOLDEN-01.** In migrations/modernizations, no module enters the change phase without
+> a golden suite captured and committed over its PRE-change behavior. The golden is captured by
+> a script running the ORIGINAL code with real inputs; the agent **NEVER** generates or edits
+> the `.approved` files — it is the one piece the agent cannot author, and that is its reason to exist.
+> **CWE-440** (Expected Behavior Violation).
+
+- [ ] Migration: golden suite captured + committed BEFORE touching the module
+- [ ] The `.approved` files are field truth; approved by a HUMAN, never by the agent
+- [ ] `golden-diff` clean (byte for byte) = hard closing condition of the touched module
+- [ ] Corpus documented; a module with insufficient corpus = PARTIAL, never COVERS
+
+## Anti-ceremony — Lean over the method itself (meta-invariant)
+
+> The risk is not a bad gate: it is the **sum** of good gates turning `/dev-loop` into an
+> audit. That is *over-processing* — the waste of ceremony (Poppendieck ch. 4). It applies to the
+> tool, not the code: if a step does not add value **for the human**, it is waste.
+> It is a **meta-invariant** — the criterion that EVERY future gate must pass before entering.
+> Today only rule 3 is mechanized (the single verdict of `readiness`, kit 1.25.0); the
+> rest is design discipline and review judgment, not something the engine checks.
+
+- [ ] **Runs without the human typing anything** — a script/agent autocompletes it; no routine forms
+- [ ] **Speaks only when it matters** — a failure, or a high-risk profile; if it always speaks, it is silenced by default
+- [ ] **Collapses into `readiness`** — one number + one line, not another screen (`--verbose` opens the detail)
+- [ ] **A trivial change skips it** — gated by risk profile <!-- principle: profiles A–E NOT yet mechanized in the engine -->
+
+## How it is enforced
+
+- `/discovery` and `/adr-refine` read it and derive the **severity gate** from here (the
+  "inviolable constraints" step). Each invariant carries, where it maps, a CWE reference.
+- `/dev-loop` consults it before touching a governed area; a violation is recorded with
+  `qa_ledger.py flag-blocker --kind constitution --note "<invariant>"` and enters the ledger
+  as a **BLOCKER** finding (readiness cap ≤ 65, blocks convergence until `--resolve`).
+  Detecting it is the agent/human's obligation; once recorded, enforcement is the engine's.
+- The **Simplicity** invariant is measured without human judgment: `qa_ledger.py simplicity-check`
+  scores the diff (minimality, nesting, abstraction) and returns `SIMPLE / ACCEPTABLE /
+  OVERBUILT`. **OVERBUILT** = BLOCKER (exit 1): it is trimmed, not converged.
+- The **Reuse (REUSE-FIRST)** invariant is measured by `qa_ledger.py waste-check`: Type-1/2 clones
+  of the diff vs the repo (`dup_vs_repo` is the dominant signal). **Advisory by default** (advises
+  with `file:line` to reuse, exit 0); with `defaults.waste.gate: true` or `--gate` a
+  **WASTEFUL** is exit 1 and is persisted with `log-gate --kind waste --verdict fail` (readiness
+  cap ≤ 65, blocks convergence). An honest Type-1/2 proxy, never semantic nor by AST.
+- The **Effective tests** invariant is measured with `qa_ledger.py pit-check`: if the mutation
+  score falls below the gate or mutants survive on the critical path, it is a **BLOCKER** finding —
+  green coverage is not enough. Expensive → *scheduled / incremental* tier, not in the inner loop.
+- The **Gate integrity** invariant is measured by `qa_ledger.py gate-check`: deleted or
+  disabled tests and lowered thresholds = **BLOCKER** (exit 1); lint suppressions, removed
+  asserts and **new dependencies** (the "0 deps without approval" rule, made visible —
+  kit 1.30.0) = review (or `--strict`). For high blast-radius a checker
+  uncorrelated with the maker (different family/profile) is also required — that is process, not code.
+- The **Golden (INV-GOLDEN-01)** invariant is measured by `qa_ledger.py golden-diff`: any `.received`
+  that does not match its `.approved` (or is unapproved) = **DIVERGE**, cutting the chain before judgment-day.
+  The agent does not touch `.approved` (ideally a `PreToolUse` hook makes it impossible).
+- The **Anti-ceremony** meta-invariant is not measured by any subcommand: it is the admission filter
+  for new gates (does it autorun? does it stay quiet except when it matters? does it collapse into `readiness`? does a
+  trivial change skip it?). Its only mechanized leg today is the single verdict of `readiness` (kit
+  1.25.0): persisted gates are shown collapsed on one line by default and are opened with
+  `--verbose`. A gate that does not pass the four questions does not enter the kit — the reason is documented.
+- **An ADR that contradicts the CONSTITUTION is not valid**: it is escalated, not approved. If a
+  decision would need to violate an invariant, changing the CONSTITUTION is discussed first
+  (an explicit human decision), never "worked around" silently.