@andresmassello/uscha 1.61.0 → 1.62.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.61.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.62.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.61.0",
+  "version": "1.62.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/qa_ledger.py

@@ -3026,7 +3026,7 @@ def _sd_governs(path):
         return None
     if not lines or lines[0].strip() != "---":
         return None
-    globs, in_governs = None, False
+    globs, in_governs, explicit_empty = None, False, False
     # scan runs to the CLOSING fence, not an arbitrary window -- a governs: key late in a
     # long frontmatter block must not silently read as UNMAPPED (fresh-review finding).
     for ln in lines[1:]:
@@ -3038,6 +3038,8 @@ def _sd_governs(path):
             if rest.startswith("[") and rest.endswith("]"):
                 globs = [x.strip().strip("\x27\x22")
                          for x in rest[1:-1].split(",") if x.strip()]
+                # only an INLINE [] is a declaration of "nothing to govern"
+                explicit_empty = not globs
                 in_governs = False
             elif rest:
                 # bare scalar (`governs: src/**`) -- a plausible authoring shorthand;
@@ -3051,6 +3053,11 @@ def _sd_governs(path):
                 globs.append(s[2:].strip().strip("\x27\x22"))
             elif s and not ln.startswith((" ", "\t")):
                 in_governs = False
+    if globs == [] and not explicit_empty:
+        # a `governs:` key with nothing usable under it (a placeholder, a comment, a typo) is
+        # an UNFINISHED declaration, not a statement that this spec governs nothing. Report it
+        # as UNMAPPED, which is what it is (fresh-review finding).
+        return None
     return globs
 
 
@@ -3111,6 +3118,16 @@ def cmd_spec_drift(args):
             row.update({"verdict": "UNMAPPED", "reason": "no governs: frontmatter"})
             results.append(row)
             continue
+        if not governs:
+            # An EXPLICIT empty list is a declaration, not an omission: this decision governs
+            # no code and never will. Negative ADRs ("we are NOT doing X, and why") are a
+            # documented practice in this kit, and reporting them UNMAPPED forever turns a
+            # correct state into permanent noise -- which is how an advisory gets ignored.
+            # Found by running spec-drift on this repo's own ADR-004.
+            row.update({"verdict": "NO-CODE",
+                        "reason": "declares governs: [] -- a decision that governs no code"})
+            results.append(row)
+            continue
         matched = []
         pats = [_fp_glob_re(g) for g in governs]
         for f in tracked:
@@ -3171,7 +3188,8 @@ def cmd_spec_drift(args):
         print("SPEC-DRIFT %s (advisory, lag > %dd):" % (args.repo, lag_days))
         if not results:
             print("  no spec documents found (SPEC.md / docs/adr/*.md)")
-        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--"}
+        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--",
+                "NO-CODE": "ok"}
         for r_ in results:
             line = "  %s %s: %s" % (mark.get(r_["verdict"], "??"), r_["file"],
                                     r_["verdict"])

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

@@ -71,7 +71,7 @@ than inventing a step. Keep the CONTENT in the conversation's language and the l
   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
+  run (per-document verdicts: SPEC_STALE / CLEAN / UNMAPPED / UNTRACKED / NO-CODE) — 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

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.61.0",
+  "version": "1.62.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, 32 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.61.0",
+  "version": "1.62.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.61.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.62.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`,
@@ -123,7 +123,8 @@ 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
+spec has no commit date to compare; **`NO-CODE`** when it declares `governs: []`, i.e. a
+decision that governs no source (negative ADRs) — a declaration, not an omission. 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.
 

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.61.0
+uscha-kit 1.62.0

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

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

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

@@ -3026,7 +3026,7 @@ def _sd_governs(path):
         return None
     if not lines or lines[0].strip() != "---":
         return None
-    globs, in_governs = None, False
+    globs, in_governs, explicit_empty = None, False, False
     # scan runs to the CLOSING fence, not an arbitrary window -- a governs: key late in a
     # long frontmatter block must not silently read as UNMAPPED (fresh-review finding).
     for ln in lines[1:]:
@@ -3038,6 +3038,8 @@ def _sd_governs(path):
             if rest.startswith("[") and rest.endswith("]"):
                 globs = [x.strip().strip("\x27\x22")
                          for x in rest[1:-1].split(",") if x.strip()]
+                # only an INLINE [] is a declaration of "nothing to govern"
+                explicit_empty = not globs
                 in_governs = False
             elif rest:
                 # bare scalar (`governs: src/**`) -- a plausible authoring shorthand;
@@ -3051,6 +3053,11 @@ def _sd_governs(path):
                 globs.append(s[2:].strip().strip("\x27\x22"))
             elif s and not ln.startswith((" ", "\t")):
                 in_governs = False
+    if globs == [] and not explicit_empty:
+        # a `governs:` key with nothing usable under it (a placeholder, a comment, a typo) is
+        # an UNFINISHED declaration, not a statement that this spec governs nothing. Report it
+        # as UNMAPPED, which is what it is (fresh-review finding).
+        return None
     return globs
 
 
@@ -3111,6 +3118,16 @@ def cmd_spec_drift(args):
             row.update({"verdict": "UNMAPPED", "reason": "no governs: frontmatter"})
             results.append(row)
             continue
+        if not governs:
+            # An EXPLICIT empty list is a declaration, not an omission: this decision governs
+            # no code and never will. Negative ADRs ("we are NOT doing X, and why") are a
+            # documented practice in this kit, and reporting them UNMAPPED forever turns a
+            # correct state into permanent noise -- which is how an advisory gets ignored.
+            # Found by running spec-drift on this repo's own ADR-004.
+            row.update({"verdict": "NO-CODE",
+                        "reason": "declares governs: [] -- a decision that governs no code"})
+            results.append(row)
+            continue
         matched = []
         pats = [_fp_glob_re(g) for g in governs]
         for f in tracked:
@@ -3171,7 +3188,8 @@ def cmd_spec_drift(args):
         print("SPEC-DRIFT %s (advisory, lag > %dd):" % (args.repo, lag_days))
         if not results:
             print("  no spec documents found (SPEC.md / docs/adr/*.md)")
-        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--"}
+        mark = {"SPEC_STALE": "!!", "CLEAN": "ok", "UNMAPPED": "--", "UNTRACKED": "--",
+                "NO-CODE": "ok"}
         for r_ in results:
             line = "  %s %s: %s" % (mark.get(r_["verdict"], "??"), r_["file"],
                                     r_["verdict"])

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

@@ -71,7 +71,7 @@ than inventing a step. Keep the CONTENT in the conversation's language and the l
   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
+  run (per-document verdicts: SPEC_STALE / CLEAN / UNMAPPED / UNTRACKED / NO-CODE) — 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

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.61.0",
+  "version": "1.62.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,