@andresmassello/uscha 1.65.0 → 1.67.0

package/README.md

@@ -40,7 +40,7 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.65.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.67.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.65.0",
+  "version": "1.67.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",

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

@@ -488,6 +488,19 @@ count, plateau flag per repo — to `ledger["measured"]` (what the statusline re
 Without it the trail starves: the mirador shows "no history yet" and the statusline
 falls back to counting checkboxes. Recording is append-only facts, never a gate.
 
+Right after readiness, run the spec-maintenance advisory (kit 1.66.0):
+
+```bash
+python3 $QL spec-drift --repo <REPO>
+```
+
+Milliseconds, deterministic, exit 0 always — it never gates, so running it every pass
+adds zero ceremony. What it adds is VISIBILITY: the run lands in the ledger, so the
+mirador card and `/uscha-status` show drift without anyone remembering the command —
+the user this advisory exists for is precisely the one who never types it. If any doc
+reads `SPEC_STALE`, mention it in the close block's `Blocks:` line as advisory context
+(it blocks nothing; it informs the human's next conversation).
+
 **Single-verdict view (kit 1.25.0, anti-ceremony).** By default `readiness` is ONE
 screen: the verdict line, any conditional warning that actually fired (it speaks only
 when it matters), and a `--- gates:` line that COLLAPSES every persisted gate record —

package/uscha-kit/.claude/skills/uscha-devloop/qa_ledger.py

@@ -1868,6 +1868,15 @@ def _origin_label(origin):
     return "%s/%s" % (sha, state)
 
 
+def _scope_path(ledger, name):
+    """Repo path for a scope, guarding the SYNTHETIC `integration` scope -- never present
+    in config["repos"], where _repo_cfg exits on unknown names. This crash class shipped
+    once (the clean-room gate, 1.63.0) and nearly shipped twice (spec-drift at pass close,
+    caught by fresh review): two recurrences make it a helper, not a per-site pattern."""
+    cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": "."}
+    return cfg.get("path", ".")
+
+
 def _evidence_origin(repo_path):
     """WHERE the evidence came from: the commit it was measured at, and whether the tree
     was clean (ADR-007). The engine's freshness check compares file MTIMES, so until now a
@@ -3145,7 +3154,7 @@ def cmd_spec_drift(args):
     cfg = ledger["config"].get("defaults", {}).get("spec_drift") or {}
     lag_days = int(args.max_lag_days if args.max_lag_days is not None
                    else cfg.get("max_lag_days", 30))
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
 
     # The spec surface is fixed by ADR-005: the repo SPEC.md plus every ADR.
     spec_files = []
@@ -3756,7 +3765,7 @@ def cmd_roundtrip(args):
     (ADR-011). Advisory end to end: exit 0 always, a report, never a gate."""
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
     st = _curation_state(repo_path)
     if st is None:
         print("ROUNDTRIP %s: no %s/ directory -- feature unused, nothing to trace."
@@ -3790,6 +3799,12 @@ def cmd_roundtrip(args):
     out = {"repo": args.repo, "promoted": len(promoted), "covered": len(covered),
            "missing": missing, "advisory": True,
            "coverage_pct": round(100.0 * len(covered) / len(promoted), 1) if promoted else None}
+    # Latest-state record so the mirador/status can surface it without anyone re-running the
+    # command (the spec_drift pattern). A report that evaporates on exit is invisible to
+    # every read surface -- which defeats the point of an advisory (found by auditing which
+    # features actually REACH the user). Advisory data: no step counter, no gate record.
+    ledger["roundtrip"] = dict(out, at=_now())
+    _save(args.ledger, ledger)
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
     else:
@@ -3812,7 +3827,7 @@ def cmd_curation_check(args):
     candidate judged, or the feature unused."""
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
     st = _curation_state(repo_path)
     if st is None:
         if args.json:
@@ -4896,6 +4911,8 @@ def cmd_dashboard(args):
     if ledger.get(CLEAN_ROOM_KEY):
         out["clean_room"] = {r: [e for e in ledger[CLEAN_ROOM_KEY] if e.get("repo") == r][-1]
                              for r in {e.get("repo") for e in ledger[CLEAN_ROOM_KEY]}}
+    if ledger.get("roundtrip"):
+        out["roundtrip"] = ledger["roundtrip"]
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return

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

@@ -665,8 +665,8 @@ function renderModes(){
      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 fp=DATA.fast_path,sd=DATA.spec_drift,cr=DATA.clean_room;
+  if(!fp&&!sd&&!cr){card.hidden=true;return;}
   const host=$("#modes");host.replaceChildren();
   const parts=[];
   if(fp){
@@ -677,6 +677,16 @@ function renderModes(){
         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(cr){
+    const cls={GREEN:"st-done",RED:"st-block"};
+    Object.keys(cr).forEach(r=>{const e=cr[r]||{};
+      const sha=(e.ref||"").slice(0,8)||"?";
+      const wall=(typeof e.wall_ms==="number")?(" · "+(e.wall_ms/1000).toFixed(1)+"s"):"";
+      append(host,append(node("div","spec"),node("span","id","clean-room"),
+        node("span","t",r+" @ "+sha+wall),
+        node("span","chip "+(cls[e.status]||"st-prog"),String(e.status||"?"))));});
+    parts.push("clean-room ×"+Object.keys(cr).length);
+  }
   if(sd){
     const cls={SPEC_STALE:"st-block",CLEAN:"st-done",UNMAPPED:"st-todo",UNTRACKED:"st-todo"};
     const res=sd.results||[];

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

@@ -100,6 +100,15 @@ nothing and gates nothing.
 `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.
 
+**Clean-room (ADR-008):** if the ledger carries `clean_room` runs, add ONE line with the
+latest run per repo: `clean-room: GREEN @ <sha8> (12.3s)` / `RED @ <sha8>`. When the gate is
+declared (`mode: "final"`) and the latest run does not match the current HEAD, append
+`(stale for gate)`. Absent key → no line.
+
+**Roundtrip (ADR-009 slice 2):** if the ledger carries a `roundtrip` run, add ONE line:
+`roundtrip: N/M promoted traceable by uscha-spec id (advisory)`. Absent key → no line —
+silence is honest when the loop was never measured.
+
 ## Degradation (honest, specific)
 
 - `measured` missing entirely → print: *"No measurement recorded yet — the trail

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.65.0",
+  "version": "1.67.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, 35 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.65.0",
+  "version": "1.67.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.65.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.67.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.65.0
+uscha-kit 1.67.0

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

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

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

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

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

@@ -488,6 +488,19 @@ count, plateau flag per repo — to `ledger["measured"]` (what the statusline re
 Without it the trail starves: the mirador shows "no history yet" and the statusline
 falls back to counting checkboxes. Recording is append-only facts, never a gate.
 
+Right after readiness, run the spec-maintenance advisory (kit 1.66.0):
+
+```bash
+python3 $QL spec-drift --repo <REPO>
+```
+
+Milliseconds, deterministic, exit 0 always — it never gates, so running it every pass
+adds zero ceremony. What it adds is VISIBILITY: the run lands in the ledger, so the
+mirador card and `/uscha-status` show drift without anyone remembering the command —
+the user this advisory exists for is precisely the one who never types it. If any doc
+reads `SPEC_STALE`, mention it in the close block's `Blocks:` line as advisory context
+(it blocks nothing; it informs the human's next conversation).
+
 **Single-verdict view (kit 1.25.0, anti-ceremony).** By default `readiness` is ONE
 screen: the verdict line, any conditional warning that actually fired (it speaks only
 when it matters), and a `--- gates:` line that COLLAPSES every persisted gate record —

package/uscha-kit/skills/uscha-devloop/qa_ledger.py

@@ -1868,6 +1868,15 @@ def _origin_label(origin):
     return "%s/%s" % (sha, state)
 
 
+def _scope_path(ledger, name):
+    """Repo path for a scope, guarding the SYNTHETIC `integration` scope -- never present
+    in config["repos"], where _repo_cfg exits on unknown names. This crash class shipped
+    once (the clean-room gate, 1.63.0) and nearly shipped twice (spec-drift at pass close,
+    caught by fresh review): two recurrences make it a helper, not a per-site pattern."""
+    cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": "."}
+    return cfg.get("path", ".")
+
+
 def _evidence_origin(repo_path):
     """WHERE the evidence came from: the commit it was measured at, and whether the tree
     was clean (ADR-007). The engine's freshness check compares file MTIMES, so until now a
@@ -3145,7 +3154,7 @@ def cmd_spec_drift(args):
     cfg = ledger["config"].get("defaults", {}).get("spec_drift") or {}
     lag_days = int(args.max_lag_days if args.max_lag_days is not None
                    else cfg.get("max_lag_days", 30))
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
 
     # The spec surface is fixed by ADR-005: the repo SPEC.md plus every ADR.
     spec_files = []
@@ -3756,7 +3765,7 @@ def cmd_roundtrip(args):
     (ADR-011). Advisory end to end: exit 0 always, a report, never a gate."""
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
     st = _curation_state(repo_path)
     if st is None:
         print("ROUNDTRIP %s: no %s/ directory -- feature unused, nothing to trace."
@@ -3790,6 +3799,12 @@ def cmd_roundtrip(args):
     out = {"repo": args.repo, "promoted": len(promoted), "covered": len(covered),
            "missing": missing, "advisory": True,
            "coverage_pct": round(100.0 * len(covered) / len(promoted), 1) if promoted else None}
+    # Latest-state record so the mirador/status can surface it without anyone re-running the
+    # command (the spec_drift pattern). A report that evaporates on exit is invisible to
+    # every read surface -- which defeats the point of an advisory (found by auditing which
+    # features actually REACH the user). Advisory data: no step counter, no gate record.
+    ledger["roundtrip"] = dict(out, at=_now())
+    _save(args.ledger, ledger)
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
     else:
@@ -3812,7 +3827,7 @@ def cmd_curation_check(args):
     candidate judged, or the feature unused."""
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
     st = _curation_state(repo_path)
     if st is None:
         if args.json:
@@ -4896,6 +4911,8 @@ def cmd_dashboard(args):
     if ledger.get(CLEAN_ROOM_KEY):
         out["clean_room"] = {r: [e for e in ledger[CLEAN_ROOM_KEY] if e.get("repo") == r][-1]
                              for r in {e.get("repo") for e in ledger[CLEAN_ROOM_KEY]}}
+    if ledger.get("roundtrip"):
+        out["roundtrip"] = ledger["roundtrip"]
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return

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

@@ -665,8 +665,8 @@ function renderModes(){
      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 fp=DATA.fast_path,sd=DATA.spec_drift,cr=DATA.clean_room;
+  if(!fp&&!sd&&!cr){card.hidden=true;return;}
   const host=$("#modes");host.replaceChildren();
   const parts=[];
   if(fp){
@@ -677,6 +677,16 @@ function renderModes(){
         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(cr){
+    const cls={GREEN:"st-done",RED:"st-block"};
+    Object.keys(cr).forEach(r=>{const e=cr[r]||{};
+      const sha=(e.ref||"").slice(0,8)||"?";
+      const wall=(typeof e.wall_ms==="number")?(" · "+(e.wall_ms/1000).toFixed(1)+"s"):"";
+      append(host,append(node("div","spec"),node("span","id","clean-room"),
+        node("span","t",r+" @ "+sha+wall),
+        node("span","chip "+(cls[e.status]||"st-prog"),String(e.status||"?"))));});
+    parts.push("clean-room ×"+Object.keys(cr).length);
+  }
   if(sd){
     const cls={SPEC_STALE:"st-block",CLEAN:"st-done",UNMAPPED:"st-todo",UNTRACKED:"st-todo"};
     const res=sd.results||[];

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

@@ -100,6 +100,15 @@ nothing and gates nothing.
 `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.
 
+**Clean-room (ADR-008):** if the ledger carries `clean_room` runs, add ONE line with the
+latest run per repo: `clean-room: GREEN @ <sha8> (12.3s)` / `RED @ <sha8>`. When the gate is
+declared (`mode: "final"`) and the latest run does not match the current HEAD, append
+`(stale for gate)`. Absent key → no line.
+
+**Roundtrip (ADR-009 slice 2):** if the ledger carries a `roundtrip` run, add ONE line:
+`roundtrip: N/M promoted traceable by uscha-spec id (advisory)`. Absent key → no line —
+silence is honest when the loop was never measured.
+
 ## Degradation (honest, specific)
 
 - `measured` missing entirely → print: *"No measurement recorded yet — the trail

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.65.0",
+  "version": "1.67.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,