@andresmassello/uscha 1.60.1 → 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.60.1** <!-- 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.60.1",
+  "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

@@ -1858,6 +1858,58 @@ def cmd_init(args):
           f"coverage_threshold={defaults.get('coverage_threshold')})")
 
 
+def _origin_label(origin):
+    """Render an origin for humans. An unmeasurable tree state reads `unknown`, never
+    `clean` -- the whole reason the field distinguishes False from None."""
+    o = origin or {}
+    sha = (o.get("commit") or "")[:8] or "no-commit"
+    dirty = o.get("dirty")
+    state = "unknown" if dirty is None else ("dirty" if dirty else "clean")
+    return "%s/%s" % (sha, state)
+
+
+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
+    snapshot could say "tests green" without being able to say green AT WHAT -- provenance
+    true of the tree, not of the commit that will merge.
+
+    Absence is NAMED, never guessed: no git, no repo, unreadable -> both None. `dirty is
+    None` must never read as clean; that distinction is the entire point of recording it.
+    Advisory only -- nothing here scores or blocks.
+
+    Untracked files COUNT as dirty (plain --porcelain): an untracked file the suite depends
+    on is exactly the contamination this records, and treating untracked as invisible is a
+    mistake this engine already paid for once (fast-path, 1.57.0)."""
+    origin = {"commit": None, "dirty": None}
+
+    def _git(*args):
+        # OSError covers BOTH ways this used to take the whole snapshot down: git absent
+        # from PATH (FileNotFoundError) and a repo_path that does not exist or is a file
+        # (NotADirectoryError). Every sibling measurement in _snapshot already tolerates a
+        # missing path; provenance must not be the one field that can crash the command it
+        # only annotates. Same posture as _spike_branch. (Both found by fresh review, both
+        # reproduced: an unconfigured or not-yet-cloned repo path is ordinary, not exotic.)
+        try:
+            return subprocess.run(["git"] + list(args), cwd=repo_path,
+                                  capture_output=True, text=True, encoding="utf-8",
+                                  errors="replace")
+        except OSError:
+            return None
+
+    rev = _git("rev-parse", "HEAD")
+    if rev is not None and rev.returncode == 0 and rev.stdout.strip():
+        origin["commit"] = rev.stdout.strip()
+    # `-- .` scopes the answer to repo_path. Without it, a repo entry pointing at a
+    # SUBDIRECTORY of a larger working tree reports the whole outer repo's state, so an
+    # unrelated edit elsewhere would mark this repo's evidence dirty -- and the ADR would
+    # be claiming a per-path fact the code did not deliver.
+    st = _git("status", "--porcelain", "--", ".")
+    if st is not None and st.returncode == 0:
+        origin["dirty"] = bool(st.stdout.strip())
+    return origin
+
+
 def _snapshot(ledger, name):
     node = _repo_node(ledger, name)
     cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": ".", "type": "maven"}
@@ -1868,6 +1920,7 @@ def _snapshot(ledger, name):
         "coverage": coverage(path, rtype),
         "tests": test_count(path, rtype),
         "loc": count_loc(path, rtype),
+        "origin": _evidence_origin(path),
     }
     node["snapshots"].append(snap)
     return snap
@@ -1887,6 +1940,7 @@ def cmd_snapshot(args):
           f"coverage={cov['pct']}% (found={cov['report_found']}), "
           f"tests={tests['total']} (found={tests['report_found']}), "
           f"freshness={freshness.get('status', 'unknown')}, "
+          f"origin={_origin_label(snap.get('origin'))}, "
           f"prod_loc={loc['prod_loc']}, test_loc={loc['test_loc']}")
     if freshness.get("status") == "stale":
         print(f"  test evidence stale: {freshness.get('reason')}")
@@ -2972,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:]:
@@ -2984,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;
@@ -2997,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
 
 
@@ -3057,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:
@@ -3117,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"])
@@ -4319,6 +4391,16 @@ def cmd_dashboard(args):
                             for r in {e.get("repo") for e in ledger["fast_path"]}}
     if ledger.get("spec_drift"):
         out["spec_drift"] = ledger["spec_drift"]
+    # evidence_origin: the latest snapshot's origin per repo, and ONLY when one exists --
+    # a ledger predating ADR-007 keeps the exact prior schema (same conditional-key rule
+    # fast_path and spec_drift already follow).
+    _org = {}
+    for _rn, _rnode in ledger["repos"].items():
+        _snaps = _rnode.get("snapshots") or []
+        if _snaps and _snaps[-1].get("origin"):
+            _org[_rn] = _snaps[-1]["origin"]
+    if _org:
+        out["evidence_origin"] = _org
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return

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/skills/uscha-status/SKILL.md

@@ -90,6 +90,12 @@ Line guide:
 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.
 
+**Evidence origin (ADR-007):** if the latest snapshot was measured on a DIRTY tree, add ONE
+line: `evidence: measured dirty at <sha8> - not from the commit alone`. Say nothing when the
+tree was clean (the normal case needs no words) and nothing when it is `null` (unmeasurable,
+and inventing a state is worse than silence). This never explains a blocked phase: it scores
+nothing and gates nothing.
+
 **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.

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.60.1",
+  "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.60.1",
+  "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.60.1 <!-- 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,10 +123,32 @@ 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.
 
+## Evidence origin (ADR-007) - green, but green at *what*?
+
+Freshness compares file mtimes, so the ledger could say "tests green" without being able to
+say which commit that was true of. Every snapshot now stamps where it came from:
+
+```json
+"origin": { "commit": "5d17cf4...", "dirty": false }
+```
+
+Measured with `git rev-parse HEAD` and `git status --porcelain` in the repo path. **Untracked
+files count as dirty** - an untracked file the suite depends on is exactly the contamination
+worth recording. **No git, no repo -> both `null`**, and `dirty: null` never reads as clean:
+a tree state nobody could measure is not a clean one.
+
+Advisory throughout: `snapshot` prints `origin=<sha8>/<clean|dirty|unknown>`,
+`dashboard --json` carries `evidence_origin` when a snapshot has one, `/uscha-status` says one
+line when the latest evidence was dirty. Readiness, phase and convergence are untouched -
+knowing a tree was dirty does not tell you the evidence is wrong, only that it was not
+produced from a commit alone. The git-worktree clean-room that would answer the stronger
+question is deliberately deferred; ADR-007 records why.
+
 ## 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.60.1
+uscha-kit 1.62.0

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

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

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

@@ -1858,6 +1858,58 @@ def cmd_init(args):
           f"coverage_threshold={defaults.get('coverage_threshold')})")
 
 
+def _origin_label(origin):
+    """Render an origin for humans. An unmeasurable tree state reads `unknown`, never
+    `clean` -- the whole reason the field distinguishes False from None."""
+    o = origin or {}
+    sha = (o.get("commit") or "")[:8] or "no-commit"
+    dirty = o.get("dirty")
+    state = "unknown" if dirty is None else ("dirty" if dirty else "clean")
+    return "%s/%s" % (sha, state)
+
+
+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
+    snapshot could say "tests green" without being able to say green AT WHAT -- provenance
+    true of the tree, not of the commit that will merge.
+
+    Absence is NAMED, never guessed: no git, no repo, unreadable -> both None. `dirty is
+    None` must never read as clean; that distinction is the entire point of recording it.
+    Advisory only -- nothing here scores or blocks.
+
+    Untracked files COUNT as dirty (plain --porcelain): an untracked file the suite depends
+    on is exactly the contamination this records, and treating untracked as invisible is a
+    mistake this engine already paid for once (fast-path, 1.57.0)."""
+    origin = {"commit": None, "dirty": None}
+
+    def _git(*args):
+        # OSError covers BOTH ways this used to take the whole snapshot down: git absent
+        # from PATH (FileNotFoundError) and a repo_path that does not exist or is a file
+        # (NotADirectoryError). Every sibling measurement in _snapshot already tolerates a
+        # missing path; provenance must not be the one field that can crash the command it
+        # only annotates. Same posture as _spike_branch. (Both found by fresh review, both
+        # reproduced: an unconfigured or not-yet-cloned repo path is ordinary, not exotic.)
+        try:
+            return subprocess.run(["git"] + list(args), cwd=repo_path,
+                                  capture_output=True, text=True, encoding="utf-8",
+                                  errors="replace")
+        except OSError:
+            return None
+
+    rev = _git("rev-parse", "HEAD")
+    if rev is not None and rev.returncode == 0 and rev.stdout.strip():
+        origin["commit"] = rev.stdout.strip()
+    # `-- .` scopes the answer to repo_path. Without it, a repo entry pointing at a
+    # SUBDIRECTORY of a larger working tree reports the whole outer repo's state, so an
+    # unrelated edit elsewhere would mark this repo's evidence dirty -- and the ADR would
+    # be claiming a per-path fact the code did not deliver.
+    st = _git("status", "--porcelain", "--", ".")
+    if st is not None and st.returncode == 0:
+        origin["dirty"] = bool(st.stdout.strip())
+    return origin
+
+
 def _snapshot(ledger, name):
     node = _repo_node(ledger, name)
     cfg = _repo_cfg(ledger, name) if name != "integration" else {"path": ".", "type": "maven"}
@@ -1868,6 +1920,7 @@ def _snapshot(ledger, name):
         "coverage": coverage(path, rtype),
         "tests": test_count(path, rtype),
         "loc": count_loc(path, rtype),
+        "origin": _evidence_origin(path),
     }
     node["snapshots"].append(snap)
     return snap
@@ -1887,6 +1940,7 @@ def cmd_snapshot(args):
           f"coverage={cov['pct']}% (found={cov['report_found']}), "
           f"tests={tests['total']} (found={tests['report_found']}), "
           f"freshness={freshness.get('status', 'unknown')}, "
+          f"origin={_origin_label(snap.get('origin'))}, "
           f"prod_loc={loc['prod_loc']}, test_loc={loc['test_loc']}")
     if freshness.get("status") == "stale":
         print(f"  test evidence stale: {freshness.get('reason')}")
@@ -2972,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:]:
@@ -2984,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;
@@ -2997,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
 
 
@@ -3057,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:
@@ -3117,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"])
@@ -4319,6 +4391,16 @@ def cmd_dashboard(args):
                             for r in {e.get("repo") for e in ledger["fast_path"]}}
     if ledger.get("spec_drift"):
         out["spec_drift"] = ledger["spec_drift"]
+    # evidence_origin: the latest snapshot's origin per repo, and ONLY when one exists --
+    # a ledger predating ADR-007 keeps the exact prior schema (same conditional-key rule
+    # fast_path and spec_drift already follow).
+    _org = {}
+    for _rn, _rnode in ledger["repos"].items():
+        _snaps = _rnode.get("snapshots") or []
+        if _snaps and _snaps[-1].get("origin"):
+            _org[_rn] = _snaps[-1]["origin"]
+    if _org:
+        out["evidence_origin"] = _org
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return

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/skills/uscha-status/SKILL.md

@@ -90,6 +90,12 @@ Line guide:
 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.
 
+**Evidence origin (ADR-007):** if the latest snapshot was measured on a DIRTY tree, add ONE
+line: `evidence: measured dirty at <sha8> - not from the commit alone`. Say nothing when the
+tree was clean (the normal case needs no words) and nothing when it is `null` (unmeasurable,
+and inventing a state is worse than silence). This never explains a blocked phase: it scores
+nothing and gates nothing.
+
 **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.

package/uscha-kit/uscha.config.json

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