@andresmassello/uscha 1.56.1 → 1.60.1

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

@@ -67,6 +67,17 @@ than inventing a step. Keep the CONTENT in the conversation's language and the l
   `review_trigger`, `experiment_valid`, `experiment_missing`, and `expired`; top-level
   `adr_experiments` summarizes open/malformed/expired experiments. This is advisory
   visibility for measured hypotheses, not readiness scoring.
+- **Fast-path (ADR-003):** `dashboard --json` carries `fast_path` — the latest verdict per
+  repo straight from the ledger, or null when none was requested. The template degrades when
+  absent, like every other field.
+- **Spec-drift (ADR-005):** `dashboard --json` carries `spec_drift` — the latest advisory
+  run (per-document verdicts: SPEC_STALE / CLEAN / UNMAPPED / UNTRACKED) — only when a run
+  exists in the ledger; a virgin ledger keeps the exact prior schema. Advisory visibility of
+  the spec-maintenance tax, never readiness input.
+- **Modes card:** the template draws one card for both modes — fast-path verdict chips per
+  repo (ALLOW green / ESCALATED amber / DENY red) and spec-drift rows per document, labeled
+  advisory. The card is hidden entirely when neither key exists (absent block = identical
+  view, same rule as the JSON).
 - **Session telemetry (optional, vendor-reported):** if `.uscha/telemetry.jsonl` exists,
   the skill aggregates it and MERGES a `telemetry` object into `DATA`. This is the ONE
   panel that is **narrated by the vendor (Claude Code), not measured by the engine** —

package/uscha-kit/.claude/skills/uscha-mirador/mirador-watch.ps1

@@ -1,22 +1,22 @@
-# mirador-watch.ps1 -- live second-screen mirador (uscha-kit 1.34.0), Windows.
-# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
-# with a meta-refresh at the same interval, so a browser open on it updates on its own.
-#
-# Usage (run in a spare terminal, from the project root):
-#   powershell -NoProfile -File <kit>\.claude\skills\uscha-mirador\mirador-watch.ps1 [-Interval 30]
-# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
-#
-# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
-param([int]$Interval = 30)
-$here     = Split-Path -Parent $MyInvocation.MyCommand.Path
-$engine   = if ($env:ENGINE)   { $env:ENGINE }   else { Join-Path $here "..\uscha-devloop\qa_ledger.py" }
-$ledger   = if ($env:LEDGER)   { $env:LEDGER }   else { "QA-LEDGER.json" }
-$template = if ($env:TEMPLATE) { $env:TEMPLATE } else { Join-Path $here "mirador.template.html" }
-$out      = if ($env:OUT)      { $env:OUT }      else { "mirador.html" }
-$py       = if ($env:PYTHON)   { $env:PYTHON }   else { "python" }
-Write-Host "mirador-watch: regenerating $out every ${Interval}s (Ctrl-C to stop). Open $out in a browser."
-while ($true) {
-  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval --no-open
-  if ($LASTEXITCODE -ne 0) { Write-Host "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying" }
-  Start-Sleep -Seconds $Interval
-}
+# mirador-watch.ps1 -- live second-screen mirador (uscha-kit 1.34.0), Windows.
+# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
+# with a meta-refresh at the same interval, so a browser open on it updates on its own.
+#
+# Usage (run in a spare terminal, from the project root):
+#   powershell -NoProfile -File <kit>\.claude\skills\uscha-mirador\mirador-watch.ps1 [-Interval 30]
+# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
+#
+# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
+param([int]$Interval = 30)
+$here     = Split-Path -Parent $MyInvocation.MyCommand.Path
+$engine   = if ($env:ENGINE)   { $env:ENGINE }   else { Join-Path $here "..\uscha-devloop\qa_ledger.py" }
+$ledger   = if ($env:LEDGER)   { $env:LEDGER }   else { "QA-LEDGER.json" }
+$template = if ($env:TEMPLATE) { $env:TEMPLATE } else { Join-Path $here "mirador.template.html" }
+$out      = if ($env:OUT)      { $env:OUT }      else { "mirador.html" }
+$py       = if ($env:PYTHON)   { $env:PYTHON }   else { "python" }
+Write-Host "mirador-watch: regenerating $out every ${Interval}s (Ctrl-C to stop). Open $out in a browser."
+while ($true) {
+  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval --no-open
+  if ($LASTEXITCODE -ne 0) { Write-Host "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying" }
+  Start-Sleep -Seconds $Interval
+}

package/uscha-kit/.claude/skills/uscha-mirador/mirador.template.html

@@ -278,6 +278,11 @@ svg{display:block;width:100%;height:auto}
         The verdict above is all you need to look at. These roll up into it; they're here if you want to dig.
       </p>
     </div>
+
+    <div class="card col6" id="card-modes" hidden>
+      <h2>Fast-path &middot; Spec-drift <span class="n" id="modes-n">&mdash;</span></h2>
+      <div class="speclist" id="modes"></div>
+    </div>
   </section>
 
   <section class="telemetry" id="telemetry" hidden>
@@ -654,6 +659,39 @@ function renderTelemetry(){
   if(sec)sec.hidden=false;
 }
 
+function renderModes(){
+  /* fast_path: latest measured verdict per repo (ADR-003). spec_drift: latest advisory
+     run (ADR-005) -- advisory means it never feeds readiness; this card only makes the
+     ledger fact visible. BOTH keys are conditional in dashboard --json, so a project
+     that never used either sees no card at all (absent block = identical view). */
+  const card=$("#card-modes");if(!card)return;
+  const fp=DATA.fast_path,sd=DATA.spec_drift;
+  if(!fp&&!sd){card.hidden=true;return;}
+  const host=$("#modes");host.replaceChildren();
+  const parts=[];
+  if(fp){
+    const cls={ALLOW:"st-done",ESCALATED:"st-prog",DENY:"st-block"};
+    Object.keys(fp).forEach(r=>{const e=fp[r]||{};
+      append(host,append(node("div","spec"),node("span","id","fast-path"),
+        node("span","t",r+(e.intent?(" — "+e.intent):"")),
+        node("span","chip "+(cls[e.verdict]||"st-todo"),String(e.verdict||"?"))));});
+    parts.push(Object.keys(fp).length+" repo"+(Object.keys(fp).length>1?"s":""));
+  }
+  if(sd){
+    const cls={SPEC_STALE:"st-block",CLEAN:"st-done",UNMAPPED:"st-todo",UNTRACKED:"st-todo"};
+    const res=sd.results||[];
+    res.forEach(d=>{const extra=d.verdict==="SPEC_STALE"
+        ?(" — "+(d.newer_files_total||0)+" file(s) newer than the spec"):"";
+      append(host,append(node("div","spec"),node("span","id","spec-drift"),
+        node("span","t",String(d.file||"")+extra),
+        node("span","chip "+(cls[d.verdict]||"st-todo"),String(d.verdict||"?"))));});
+    const stale=res.filter(d=>d.verdict==="SPEC_STALE").length;
+    parts.push(stale?stale+" stale spec"+(stale>1?"s":""):"no drift measured");
+    host.appendChild(emptyHint("spec-drift is ADVISORY (ADR-005): it prompts a human look, it never gates."));
+  }
+  $("#modes-n").textContent=parts.join(" · ");
+  card.hidden=false;
+}
 /* ==== status story: cómo viene / qué lo traba / qué sigue — all from measured DATA ==== */
 function renderStatus(){
   const sec=$("#status");if(!sec)return;
@@ -741,7 +779,7 @@ function applySnapshot(i){
 scrub.addEventListener("input",()=>applySnapshot(+scrub.value));
 
 /* ==== init ==== */
-renderStatus();renderAcceptance();renderAdrs();renderInv();renderHeat();renderLoops();renderSubs();renderExecutionPolicy();renderTelemetry();
+renderStatus();renderModes();renderAcceptance();renderAdrs();renderInv();renderHeat();renderLoops();renderSubs();renderExecutionPolicy();renderTelemetry();
 $("#asof").textContent=snaps.length?snaps[snaps.length-1].date:"no history yet (readiness --record)";
 renderTrail(null);
 </script>

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

@@ -86,6 +86,14 @@ Line guide:
   WHEN the evidence was captured — facts do not move without new evidence. If the
   field is absent (nothing recorded yet), omit the line; never guess a timestamp.
 
+**Fast-path mode (ADR-003):** if the ledger carries `fast_path` entries, add ONE line to the
+block with the latest verdict per repo (`fast-path: ALLOW (intent...)` / `ESCALATED`). Absent
+entries → no line at all: silence is honest when no mode was requested.
+
+**Spec-drift (ADR-005):** if the ledger carries a `spec_drift` run, add ONE line:
+`spec-drift: N stale / M docs (advisory)` — or `spec-drift: no drift measured` when zero are
+stale. Always label it advisory; it never explains a blocked phase. Absent key → no line.
+
 ## Degradation (honest, specific)
 
 - `measured` missing entirely → print: *"No measurement recorded yet — the trail

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.56.1",
+  "version": "1.60.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, 29 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, 32 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.56.1",
+  "version": "1.60.1",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",

package/uscha-kit/INSTALL.md

@@ -1,128 +1,128 @@
-# Install Uscha
-
-Uscha installs as a machine-level helper for coding agents. The recommended path
-is npm/npx because it works the same on a fresh Codex or Claude Code machine.
-
-The method itself — the paradigm, the five rules, the skills and the library — lives at
-**[uscha.dev](https://uscha.dev)**.
-
-## Quick path
-
-### Codex Desktop
-
-```bash
-npx --yes @andresmassello/uscha@latest version
-npx --yes @andresmassello/uscha@latest install --target codex --dry-run
-npx --yes @andresmassello/uscha@latest install --target codex
-npx --yes @andresmassello/uscha@latest doctor --target codex
-```
-
-Then restart Codex or open a new thread. The installer registers Uscha as a
-personal local plugin under `~/plugins/uscha` and updates
-`~/.agents/plugins/marketplace.json`. It preflights that marketplace before replacing the plugin tree and writes the install marker last.
-
-### Claude Code
-
-```bash
-npx --yes @andresmassello/uscha@latest install --target claude --dry-run
-npx --yes @andresmassello/uscha@latest install --target claude
-npx --yes @andresmassello/uscha@latest doctor --target claude
-```
-
-This installs the `uscha-*` skills and registers a portable Python `PreToolUse` hook under `~/.claude` while preserving unrelated `settings.json` entries. Restart or reload Claude Code after installing.
-
-### Same machine uses both
-
-```bash
-npx --yes @andresmassello/uscha@latest install --target both --dry-run
-npx --yes @andresmassello/uscha@latest install --target both
-npx --yes @andresmassello/uscha@latest doctor --target both
-```
-
-## Prepare a project repo
-
-After the machine install, initialize each project where Uscha should govern the
-workflow:
-
-```bash
-npx --yes @andresmassello/uscha@latest init --repo . --dry-run
-npx --yes @andresmassello/uscha@latest init --repo .
-# Existing differing files are preserved; use --force only to replace them deliberately.
-npx --yes @andresmassello/uscha@latest init --repo . --force
-```
-
-`init` exits nonzero and reports conflicts for differing `uscha.config.json`, `CLAUDE.md`, `CONSTITUTION.md`, or `.gitattributes`; `--dry-run` performs the same conflict check without writing.
-
-`init` also installs the **progress statusline** (kit 1.46.0): it copies
-`.claude/scripts/uscha_{statusline,progress}.py` and merges a `statusLine` + a `Stop` hook into
-`.claude/settings.json` (never clobbering an existing `statusLine`). Add a `label`, `roadmap`
-and `build_priority` to your `repos[]` entry to drive it; with no data it stays hidden.
-
-Project state stays in the project: `uscha.config.json`, `QA-LEDGER.json`,
-`ACCEPTANCE.md`, and approved golden fixtures when used.
-
-## See the dashboard (mirador)
-
-From the root of any project that has a `QA-LEDGER.json`, one command renders the mirador and
-opens it — no python, no paths:
-
-```bash
-npx --yes @andresmassello/uscha@latest mirador           # one glance: render + open
-npx --yes @andresmassello/uscha@latest mirador --watch   # live second-screen view (auto-refresh)
-```
-
-It defaults to the `QA-LEDGER.json` convention in the current directory (pass `--ledger` to
-point elsewhere) and prints the absolute path it wrote. `--watch` re-renders every `--interval`
-seconds (default 30) into one self-reloading tab.
-
-## Requirements
-
-| Requirement | Why |
-|-------------|-----|
-| Node.js + npm | Runs the universal `npx` entrypoint. |
-| Python 3.8+ | Runs the canonical stdlib installer and engine. |
-| Git | Used by the method and by project setup checks. |
-| Codex Desktop and/or Claude Code | The agent runtime you want to install Uscha into. |
-
-No `pip install` is required. The engine is Python stdlib-only.
-
-## Other install options
-
-| Option | Use when | Tradeoff |
-|--------|----------|----------|
-| `npx @andresmassello/uscha@latest ...` | Normal install/update on any machine. | Requires npm registry access. |
-| Git checkout + `python uscha-kit/install-uscha.py ...` | Developing Uscha itself or testing unreleased changes. | You must clone/pull the repo yourself. |
-| `--mode link` from a checkout | This machine develops the kit and installed skills should follow local edits. | Links are great for development, risky for normal users. |
-| Claude Code plugin commands | You specifically want Claude Code's native plugin flow. | Codex still needs the npm/git installer path. |
-| Manual copy | Debugging the installer. | Easy to drift; not recommended for adoption. |
-
-Development checkout example:
-
-```bash
-git clone https://github.com/andresmassello/uscha.git
-cd uscha
-python uscha-kit/install-uscha.py install --target both --mode link --dry-run
-python uscha-kit/install-uscha.py install --target both --mode link
-```
-
-Claude Code plugin option:
-
-```text
-/plugin marketplace add andresmassello/uscha
-/plugin install uscha@uscha
-```
-
-## Update and verify
-
-```bash
-npm view @andresmassello/uscha version
-npx --yes @andresmassello/uscha@latest version
-npx --yes @andresmassello/uscha@latest install --target both
-npx --yes @andresmassello/uscha@latest doctor --target both
-```
-
-`doctor` exits 1 for any unhealthy target in either text or `--json` mode. It checks installed skill presence, manifest/marketplace or hook registration, marker, and version; it does not measure file-content integrity.
-
-If `npm view` returns `404` immediately after a new release, wait a few minutes:
-npm search/dist-tags can propagate before the package metadata endpoint used by
-`npx`. Do not republish the same version while propagation is in progress.
+# Install Uscha
+
+Uscha installs as a machine-level helper for coding agents. The recommended path
+is npm/npx because it works the same on a fresh Codex or Claude Code machine.
+
+The method itself — the paradigm, the five rules, the skills and the library — lives at
+**[uscha.dev](https://uscha.dev)**.
+
+## Quick path
+
+### Codex Desktop
+
+```bash
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target codex --dry-run
+npx --yes @andresmassello/uscha@latest install --target codex
+npx --yes @andresmassello/uscha@latest doctor --target codex
+```
+
+Then restart Codex or open a new thread. The installer registers Uscha as a
+personal local plugin under `~/plugins/uscha` and updates
+`~/.agents/plugins/marketplace.json`. It preflights that marketplace before replacing the plugin tree and writes the install marker last.
+
+### Claude Code
+
+```bash
+npx --yes @andresmassello/uscha@latest install --target claude --dry-run
+npx --yes @andresmassello/uscha@latest install --target claude
+npx --yes @andresmassello/uscha@latest doctor --target claude
+```
+
+This installs the `uscha-*` skills and registers a portable Python `PreToolUse` hook under `~/.claude` while preserving unrelated `settings.json` entries. Restart or reload Claude Code after installing.
+
+### Same machine uses both
+
+```bash
+npx --yes @andresmassello/uscha@latest install --target both --dry-run
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
+```
+
+## Prepare a project repo
+
+After the machine install, initialize each project where Uscha should govern the
+workflow:
+
+```bash
+npx --yes @andresmassello/uscha@latest init --repo . --dry-run
+npx --yes @andresmassello/uscha@latest init --repo .
+# Existing differing files are preserved; use --force only to replace them deliberately.
+npx --yes @andresmassello/uscha@latest init --repo . --force
+```
+
+`init` exits nonzero and reports conflicts for differing `uscha.config.json`, `CLAUDE.md`, `CONSTITUTION.md`, or `.gitattributes`; `--dry-run` performs the same conflict check without writing.
+
+`init` also installs the **progress statusline** (kit 1.46.0): it copies
+`.claude/scripts/uscha_{statusline,progress}.py` and merges a `statusLine` + a `Stop` hook into
+`.claude/settings.json` (never clobbering an existing `statusLine`). Add a `label`, `roadmap`
+and `build_priority` to your `repos[]` entry to drive it; with no data it stays hidden.
+
+Project state stays in the project: `uscha.config.json`, `QA-LEDGER.json`,
+`ACCEPTANCE.md`, and approved golden fixtures when used.
+
+## See the dashboard (mirador)
+
+From the root of any project that has a `QA-LEDGER.json`, one command renders the mirador and
+opens it — no python, no paths:
+
+```bash
+npx --yes @andresmassello/uscha@latest mirador           # one glance: render + open
+npx --yes @andresmassello/uscha@latest mirador --watch   # live second-screen view (auto-refresh)
+```
+
+It defaults to the `QA-LEDGER.json` convention in the current directory (pass `--ledger` to
+point elsewhere) and prints the absolute path it wrote. `--watch` re-renders every `--interval`
+seconds (default 30) into one self-reloading tab.
+
+## Requirements
+
+| Requirement | Why |
+|-------------|-----|
+| Node.js + npm | Runs the universal `npx` entrypoint. |
+| Python 3.8+ | Runs the canonical stdlib installer and engine. |
+| Git | Used by the method and by project setup checks. |
+| Codex Desktop and/or Claude Code | The agent runtime you want to install Uscha into. |
+
+No `pip install` is required. The engine is Python stdlib-only.
+
+## Other install options
+
+| Option | Use when | Tradeoff |
+|--------|----------|----------|
+| `npx @andresmassello/uscha@latest ...` | Normal install/update on any machine. | Requires npm registry access. |
+| Git checkout + `python uscha-kit/install-uscha.py ...` | Developing Uscha itself or testing unreleased changes. | You must clone/pull the repo yourself. |
+| `--mode link` from a checkout | This machine develops the kit and installed skills should follow local edits. | Links are great for development, risky for normal users. |
+| Claude Code plugin commands | You specifically want Claude Code's native plugin flow. | Codex still needs the npm/git installer path. |
+| Manual copy | Debugging the installer. | Easy to drift; not recommended for adoption. |
+
+Development checkout example:
+
+```bash
+git clone https://github.com/andresmassello/uscha.git
+cd uscha
+python uscha-kit/install-uscha.py install --target both --mode link --dry-run
+python uscha-kit/install-uscha.py install --target both --mode link
+```
+
+Claude Code plugin option:
+
+```text
+/plugin marketplace add andresmassello/uscha
+/plugin install uscha@uscha
+```
+
+## Update and verify
+
+```bash
+npm view @andresmassello/uscha version
+npx --yes @andresmassello/uscha@latest version
+npx --yes @andresmassello/uscha@latest install --target both
+npx --yes @andresmassello/uscha@latest doctor --target both
+```
+
+`doctor` exits 1 for any unhealthy target in either text or `--json` mode. It checks installed skill presence, manifest/marketplace or hook registration, marker, and version; it does not measure file-content integrity.
+
+If `npm view` returns `404` immediately after a new release, wait a few minutes:
+npm search/dist-tags can propagate before the package metadata endpoint used by
+`npx`. Do not republish the same version while propagation is in progress.

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.56.1 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.60.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`,
@@ -38,6 +38,95 @@ uscha-kit/
    └─ uscha-rubric/                      # (optional) rubric grading — thin adapter; the core is agnostic
 ```
 
+## Fast-path (ADR-003) — measured entry for trivial changes
+
+A one-line fix should not pay the ceremony of a schema migration. `fastpath-eval` grants the
+shortcut from **measured signals**, never from anyone's opinion of "small":
+
+```bash
+python qa_ledger.py fastpath-eval --repo <name> --json            # dry-run: verdict only
+python qa_ledger.py fastpath-eval --repo <name> --intent "fix: x" # records it in the ledger
+```
+
+Config (`defaults.fast_path`; absent block = feature off, behavior identical to earlier
+releases): `max_files_changed` (3) and `max_loc_delta` (80) measured from
+`git diff --numstat` against the merge-base with `origin/main` (fallback `main`) **plus
+untracked files** — a new file is still a change; `protected_paths` globs deny regardless of
+size; `require_asserting_test` caps readiness while a fast-path run has no measured test.
+
+**Fail-closed:** no git, no resolvable base, no config → `DENY` with the reason named.
+"Could not measure" never grants the shortcut. **Escalation:** re-running `fastpath-eval`
+mid-run (the devloop does, before the PR step) with thresholds now exceeded flips the run to
+`ESCALATED` through the standard escalation machinery — the derived phase blocks `pr-ready`
+and readiness is capped until a human runs `resolve-escalation`, after producing the ADR +
+ACCEPTANCE the change turned out to deserve. **The override is asymmetric (INV-RIGOR-02):**
+you can always force the full path; nothing can force `ALLOW` over a measured `DENY`.
+
+## Golden coverage (ADR-006) — the veto knows what a golden actually covers
+
+A golden freezes behavior. Changing code a golden exercises is never a trivial change — but
+until the engine knew WHICH source files a golden covers, that veto could not be measured, so
+ADR-004 deferred it rather than ship a gate that pretended. `golden-coverage` builds the
+mapping **by measurement**:
+
+```bash
+python qa_ledger.py golden-coverage --harness tests/golden/harness-x.py --golden tests/golden/x.approved.json
+```
+
+It runs the harness under `coverage.py` and records the source files that actually executed
+into `golden.coverage.json` at the repo root (same convention as `golden.scrub.json`). The
+harnesses drive their subject through a **subprocess**, so instrumentation is injected into
+every python they spawn — measuring only the parent would record nothing and produce an empty
+map, which would read as "this golden covers nothing".
+
+Then, **opt-in**, the fast-path grows a `golden_touched` signal:
+
+```json
+"fast_path": { "forbid_when_golden_touched": true }
+```
+
+Absent or `false` → the veto does not exist and behavior is identical to earlier releases.
+Declared → **fail-closed**: touching a mapped file denies (naming the golden and the file), and
+so does a missing manifest, because "could not measure" never grants the shortcut. A malformed
+manifest exits 2 rather than degrading into a silent "no mapping". Every verdict carries the
+capture commit and tool version in the signal's `source` — provenance, not a freshness gate:
+an aged map's real risk is a false negative, which cannot be detected without re-capturing.
+
+Two honest limits (ADR-006): `coverage.py` is Python-only, so a harness in another language
+cannot produce a map — declaring the veto there yields a permanent `DENY`, and the remedy is
+not to declare it. And **file** granularity over-fires on monolithic files: in a repo whose
+engine is one large module, the veto fires on nearly every change to it. When it errs, it errs
+toward more ceremony, never less.
+
+## Spec-drift (ADR-005) — the spec maintenance tax, made visible
+
+Specs rot silently: the code moves and `SPEC.md` stays where it was. `spec-drift` detects
+that lag **mechanically** — and reports it as **advisory, never a gate**, because whether an
+older spec still covers newer code is a relevance judgment, and a guess advises.
+
+```bash
+python qa_ledger.py spec-drift --repo <name> --json   # advisory report; exit 0 always
+```
+
+Map specs to code with a `governs:` glob list in the frontmatter of `SPEC.md` and each
+`docs/adr/*.md`:
+
+```markdown
+---
+governs:
+  - src/payments/**
+  - db/**
+---
+```
+
+Per document: **`SPEC_STALE`** when governed code outran the spec by more than
+`defaults.spec_drift.max_lag_days` (default 30), listing the newer files; **`CLEAN`** when it
+did not; **`UNMAPPED`** when there is no `governs:` frontmatter *or its globs match nothing*
+— absence of a mapping is absence of measurement, not "no drift"; **`UNTRACKED`** when the
+spec has no commit date to compare. The latest run lands in the ledger (`spec_drift`) so the
+mirador can surface it. No readiness impact, no exit-code gate: a stale spec is a prompt for
+a human conversation, not a blocked pipeline.
+
 ## 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.56.1
+uscha-kit 1.60.1

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

@@ -0,0 +1 @@
+{"AC-FP-01": true, "AC-FP-11": true, "AC-FP-07": true, "AC-FP-06": true, "AC-FP-05": true, "AC-FP-02": true, "AC-FP-03": true, "AC-FP-09": true, "AC-FP-10": true, "AC-FP-08": true}

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

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

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

@@ -0,0 +1 @@
+{"AC-SD-01": true, "AC-SD-03": true, "AC-SD-02": true, "AC-SD-04": true}

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

@@ -190,3 +190,21 @@ covered.
 
 Never overwrite an existing approved golden. If a `.received` already exists, regenerate it;
 if a `.approved` exists, it is the human's — leave it untouched and surface the diff.
+
+## Record the coverage map (ADR-006)
+
+After the `.received` is produced and while the harness is still the thing that just ran,
+record WHICH source files it exercised — the mapping that lets the fast-path veto a change
+touching code a golden froze:
+
+```bash
+python qa_ledger.py golden-coverage --harness <harness> --golden <the .approved sibling>
+```
+
+This is **derived measurement, not judgment**: the agent may write `golden.coverage.json`.
+INV-GOLDEN-01 governs the `.approved` bytes, which encode judgment, and nothing here changes
+that — the human still approves the golden itself.
+
+`coverage.py` is a capture-time dependency. Without it the command writes **nothing** and exits
+2: an empty map would read as "this golden covers nothing", which is exactly the lie that would
+let the veto pass. Skipping the map is honest; recording an empty one is not.

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

@@ -169,6 +169,27 @@ install `hooks/block-approved-writes.py` as a `PreToolUse` hook in
 `settings.json`, and add `*.approved.* binary` to `.gitattributes` (ships in
 `templates/.gitattributes`) so line endings can't lie in the byte-compare.
 
+## Phase 0a — Fast-path check (ADR-003; run FIRST, before planning ceremony)
+
+If `defaults.fast_path` exists in config, run the measured classifier before demanding a
+full spec package:
+
+```bash
+python qa_ledger.py fastpath-eval --repo <name> --json          # dry-run first
+```
+
+- **ALLOW** and the operator wants the shortcut: re-run with
+  `--intent "<one sentence: what and why>"` to record it, then skip Phase 0's full-package
+  demand. The micro-contract replaces it: the recorded INTENT plus at least one new/modified
+  asserting test (readiness stays capped until that test shows up in measured evidence).
+- **DENY**: state WHICH measured signal denied it — echo the engine's breakdown verbatim.
+  The skill wires; it never computes and never argues with the verdict. Proceed with the
+  normal full path. The operator may always choose the full path over an ALLOW; nothing —
+  operator, agent or flag — can force ALLOW over a DENY (INV-RIGOR-02).
+- **Re-evaluate before the PR step** (same command, same intent): thresholds exceeded mid-run
+  flip the run to `ESCALATED` — the derived phase blocks pr-ready and readiness is capped.
+  Produce the ADR + ACCEPTANCE the change turned out to deserve, then `resolve-escalation`.
+
 ## Phase 0 — Plan (ADR-first)
 
 - **Read `CONSTITUTION.md` first (if present).** It lists the project invariants no SPEC