@andresmassello/uscha 1.60.1 → 1.61.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.61.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.61.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')}")
@@ -4319,6 +4373,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-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.61.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.61.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.61.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`,
@@ -127,6 +127,27 @@ spec has no commit date to compare. The latest run lands in the ledger (`spec_dr
 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.61.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/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')}")
@@ -4319,6 +4373,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-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.61.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,