@andresmassello/uscha 1.51.3 → 1.54.0

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

@@ -1,79 +1,147 @@
----
-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).
+---
+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.
+
+## First contact (show ONCE, then never again)
+
+**Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
+`ACCEPTANCE.md`, no `docs/adr/` -- open with this block, then start working. If any of those
+exist, the operator already knows the method: skip it entirely and go straight to the
+breadcrumb. Repeating it every run would be exactly the ceremony the method forbids.
+
+```
+[uscha · rubric · 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 grade what tests cannot: conventions, error handling, API ergonomics, doc quality -- against your versioned RUBRIC.md.
+Output: a graded verdict ingested into the ledger (advisory unless you declared it a gate)
+Next:   back to `/uscha-devloop`, or the human gate if the loop already converged.
+Stop:   say so at any point -- whatever is already written stays.
+```
+
+**Bilingual by construction.** The labels (`START`, `Method`, `Here`, `Output`, `Next`,
+`Stop`) stay VERBATIM in English -- they are the method's vocabulary and the smoke suite checks
+for them mechanically, which is only possible if they never move. The wording after each label
+is the canonical English; **render it in the operator's language**. If they are writing to you
+in Spanish, the whole block reads in Spanish under English labels. Do not translate the labels,
+do not leave the content in English when they are not writing in English.
+
+Unlike the close block, `Next` here MAY name the nominal route: on a first run there is no
+measured state to derive from yet, so the nominal path is the honest answer. From the close
+block onward, derived state wins.
+
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
+They are navigation, not ceremony: one line per turn, one block at the end.
+
+**Open every turn with a breadcrumb**, then the content:
+
+`[uscha · rubric · <step> → <target>]`
+
+- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
+  Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
+  converges, its length is not known in advance, and an invented total is exactly the kind of
+  narrated number the method forbids. **When the ledger already measures the count** (the QA
+  loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
+- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
+  `RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
+
+**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
+without it is a defect, even when the phase converged cleanly:
+
+```
+[uscha · rubric · CLOSED]
+Produced: <files actually written, or "nothing">
+Blocks:   <what stands between here and the next phase, or "nothing">
+Next:     <the next action, and why it is that one>
+Run:      <the exact command or skill to invoke>
+```
+
+This is **not** the implementation handoff some skills also emit: that one is a prompt for
+whoever implements next, this one is navigation for the human operator, and both can appear.
+
+`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
+fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
+open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
+genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
+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.
+
+## 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/.claude/skills/uscha-status/SKILL.md

@@ -19,6 +19,30 @@ skill (**pull** — one screen when the human asks), and the **mirador** (bird's
 HTML). This skill exists because some surfaces never show a statusline; the answer
 is the same data, printed in chat when requested.
 
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?".
+
+This skill is a **one-shot read-only readout**: its block IS the answer. It therefore does NOT
+take the conversational close block — that would be exactly the padding this skill forbids.
+It carries the two minimal markers instead.
+
+**Open with a breadcrumb:**
+
+`[uscha · status · step <n> → <target>]`
+
+**End with the two routing lines, and nothing else:**
+
+```
+Next: <the next action, derived from what this readout just showed>
+Run:  <the exact command or skill to invoke>
+```
+
+`Next` is **derived** from the state you just read — never copied from a fixed route,
+including any `Flow:` line in this file. If nothing is actionable, say that plainly rather
+than inventing a step. Keep the CONTENT in the conversation's language and the labels
+(`Next`, `Run`) verbatim — the smoke suite checks for them.
+
 ## Contract
 
 - **Read-only over persisted facts.** Never run `readiness`, tests, or gates. The

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

@@ -1,88 +1,156 @@
----
-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.
+---
+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.
+
+## First contact (show ONCE, then never again)
+
+**Only when this project has no uscha artifacts yet** -- no `QA-LEDGER.json`, no `SPEC.md` or
+`ACCEPTANCE.md`, no `docs/adr/` -- open with this block, then start working. If any of those
+exist, the operator already knows the method: skip it entirely and go straight to the
+breadcrumb. Repeating it every run would be exactly the ceremony the method forbids.
+
+```
+[uscha · sysdoc · 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 build a two-track deck (commercial + technical) from what the ledger already measured.
+Output: a single self-contained HTML deck
+Next:   nothing -- this is a read-only artifact you share.
+Stop:   say so at any point -- whatever is already written stays.
+```
+
+**Bilingual by construction.** The labels (`START`, `Method`, `Here`, `Output`, `Next`,
+`Stop`) stay VERBATIM in English -- they are the method's vocabulary and the smoke suite checks
+for them mechanically, which is only possible if they never move. The wording after each label
+is the canonical English; **render it in the operator's language**. If they are writing to you
+in Spanish, the whole block reads in Spanish under English labels. Do not translate the labels,
+do not leave the content in English when they are not writing in English.
+
+Unlike the close block, `Next` here MAY name the nominal route: on a first run there is no
+measured state to derive from yet, so the nominal path is the honest answer. From the close
+block onward, derived state wins.
+
+## Orientation markers (non-negotiable)
+
+The operator must never have to ask "where am I?" or "what happens now?". Two markers, always.
+They are navigation, not ceremony: one line per turn, one block at the end.
+
+**Open every turn with a breadcrumb**, then the content:
+
+`[uscha · sysdoc · <step> → <target>]`
+
+- `<step>` — `Q<n>` for a question, `pass <n>` for a loop iteration, `step <n>` otherwise.
+  Count what has actually happened. **Never write a denominator** (`Q4/12`): this phase
+  converges, its length is not known in advance, and an invented total is exactly the kind of
+  narrated number the method forbids. **When the ledger already measures the count** (the QA
+  loop's `loop_count`), use the measured number — never keep a parallel tally of your own.
+- `<target>` — the artifact this turn feeds (`SPEC`, `ADR-003`, `ACCEPTANCE`, `LEDGER`,
+  `RECEIVED`, ...). Drop `→ <target>` only when the turn genuinely feeds none.
+
+**Close with the close block ONCE, when the skill finishes** — not on every turn. Ending
+without it is a defect, even when the phase converged cleanly:
+
+```
+[uscha · sysdoc · CLOSED]
+Produced: <files actually written, or "nothing">
+Blocks:   <what stands between here and the next phase, or "nothing">
+Next:     <the next action, and why it is that one>
+Run:      <the exact command or skill to invoke>
+```
+
+This is **not** the implementation handoff some skills also emit: that one is a prompt for
+whoever implements next, this one is navigation for the human operator, and both can appear.
+
+`Blocks` and `Next` are **derived from the state you just produced** — never copied from a
+fixed route, **including any `Flow:` line in this file**. Those lines are the nominal path;
+open ADR experiments, an unclosed spike, an unapproved golden or a red gate all change what
+genuinely comes next, and the derived answer wins. If the next phase cannot start yet, name it
+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.
+
+## 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/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.51.3",
+  "version": "1.54.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, 29 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.51.3",
+  "version": "1.54.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.51.3 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.54.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`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.51.3
+uscha-kit 1.54.0