@andresmassello/uscha 1.69.0 → 1.70.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.69.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.70.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.69.0",
+  "version": "1.70.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

@@ -58,6 +58,7 @@ import hashlib
 import json
 import math
 import os
+import posixpath
 import re
 import shutil
 import subprocess
@@ -3913,6 +3914,14 @@ _DELTA_BANNER = ("GENERATED by qa_ledger.py discover (ADR-013). Rendered view of
                  + CANDIDATE_DELTA_FILE + " -- hand edits are overwritten on regeneration.")
 
 
+def _delta_seal(observations, repo, path):
+    """The seal covers everything semantically load-bearing that the content-addressed OBS
+    ids do NOT: the full observation set, the repo, and the bound. `path` changes what the
+    delta MEANS (a partial discovery), so it must be sealed -- a hand edit of any of these is
+    a named malformation (fresh-review MEDIUM)."""
+    return _integrity_hash({"observations": observations, "repo": repo, "path": path})
+
+
 def _obs_id(otype, statement, primary_prov):
     """Content-addressed: OBS-sha256(type + LF + normalized statement + LF + primary
     provenance)[:12]. Normalization = lowercase + whitespace collapse. Re-running discovery
@@ -3998,7 +4007,11 @@ def _extract_static_py(repo_path, tracked):
     return obs, unsupported
 
 
-def _golden_backed_obs(ledger, repo, repo_path):
+def _under_bound(rel, bound):
+    return bound is None or rel == bound or rel.startswith(bound + "/")
+
+
+def _golden_backed_obs(ledger, repo, repo_path, bound=None):
     """Measured observations: one per approved golden fixture, backed by the LATEST ingested
     golden-diff gate record (AC-DD-03). Only source: real, ledger-ingested execution. No
     ingested run -> no measured OBS; a fixture on disk that nothing executed is not evidence."""
@@ -4016,6 +4029,8 @@ def _golden_backed_obs(ledger, repo, repo_path):
             if ".approved." not in f:
                 continue
             rel = os.path.relpath(os.path.join(root, f), repo_path).replace(os.sep, "/")
+            if not _under_bound(rel, bound):
+                continue
             stmt = "behavior frozen by golden fixture %s matches the approved baseline" % rel
             obs.append({"id": _obs_id("behavior", stmt, rel), "type": "behavior",
                         "statement": stmt, "evidence_class": "measured",
@@ -4108,9 +4123,16 @@ def _match_canonical(statement, canon_ids):
 
 def _render_delta_md(delta, verdicts):
     lines = ["<!-- %s -->" % _DELTA_BANNER, "",
-             "# CANDIDATE-DELTA (rendered view)", "",
-             "| id | type | class | verdict | statement | provenance |",
-             "|----|------|-------|---------|-----------|------------|"]
+             "# CANDIDATE-DELTA (rendered view)", ""]
+    if delta.get("path"):
+        # the bound is the artifact the HUMAN curates from -- a partial discovery must not
+        # read as a complete one, or the shrunk INV-CURATION-01 surface is undisclosed
+        # (fresh-review HIGH). The JSON recorded it; the human-facing view must too.
+        lines += ["> **BOUNDED discovery** — mechanical scans were restricted to "
+                  "`%s`. Files outside this path were NOT scanned; this delta is PARTIAL "
+                  "by construction." % delta["path"], ""]
+    lines += ["| id | type | class | verdict | statement | provenance |",
+              "|----|------|-------|---------|-----------|------------|"]
     for o in delta["observations"]:
         v = verdicts.get(o["id"], "(uncurated)")
         files = ", ".join(o["provenance"].get("files") or []) or "-"
@@ -4177,10 +4199,10 @@ def _load_delta(repo_path):
     # launders narrated inference into measured evidence (fresh-review MEDIUM, reproduced)
     if not errors:
         seal = delta.get("_integrity")
-        want = _integrity_hash({"observations": obs})
+        want = _delta_seal(obs, delta.get("repo"), delta.get("path"))
         if seal != want:
-            errors.append("integrity seal %s does not match the observations -- the delta "
-                          "is derived, never hand-edited (regenerate via `discover`)"
+            errors.append("integrity seal %s does not match the delta content -- observations, "
+                          "repo or path was hand-edited (regenerate via `discover`)"
                           % ("missing" if seal is None else repr(seal)))
     return delta, errors
 
@@ -4224,8 +4246,36 @@ def cmd_discover(args):
               "from tracked files and cannot proceed without it." % repo_path,
               file=sys.stderr)
         sys.exit(2)
+    bound = None
+    if args.path is not None:
+        # the bound restricts the MECHANICAL scans (static, measured); narrated input stays
+        # the skill's to scope. Field-found before the first run (AC-DD-07): "real, bounded"
+        # is unimplementable without it.
+        raw = args.path.replace("\\", "/").strip()
+        if not raw:
+            # an empty --path is the silent-degrade trap (a wrapper passing an unset var):
+            # falsy would mean "no bound" and quietly scan the whole repo (fresh-review MED)
+            print("[qa_ledger] discover: --path is empty -- omit --path to scan the whole "
+                  "repo; an empty bound is not a bound.", file=sys.stderr)
+            sys.exit(2)
+        bound = posixpath.normpath(raw).strip("/")     # ./src, src/ , /src -> src
+        if bound in (".", "") or bound == ".." or bound.startswith("../"):
+            print("[qa_ledger] discover: --path %r does not name a subtree inside the repo."
+                  % args.path, file=sys.stderr)
+            sys.exit(2)
+        if _gc_rel(os.path.join(repo_path, bound.replace("/", os.sep)), repo_path) is None:
+            print("[qa_ledger] discover: --path %r escapes the repo tree." % args.path,
+                  file=sys.stderr)
+            sys.exit(2)
+        tracked = [f for f in tracked if _under_bound(f, bound)]
+        if not tracked:
+            # a typo'd bound silently emitting an empty delta is the silent-degrade trap
+            print("[qa_ledger] discover: --path %r matches no tracked file -- refusing to "
+                  "emit an empty delta for a bound that points at nothing." % args.path,
+                  file=sys.stderr)
+            sys.exit(2)
     static_obs, unsupported = _extract_static_py(repo_path, tracked)
-    measured_obs = _golden_backed_obs(ledger, args.repo, repo_path)
+    measured_obs = _golden_backed_obs(ledger, args.repo, repo_path, bound)
     narrated_obs, nerrs = ([], [])
     if args.narrated:
         narrated_obs, nerrs = _load_narrated(args.narrated, repo_path)
@@ -4244,10 +4294,11 @@ def cmd_discover(args):
         o["canonical_match"] = _match_canonical(o["statement"], canon)
     observations = sorted(by_id.values(), key=lambda o: o["id"])
     delta = {"_generated_by": "qa_ledger.py discover (ADR-013) -- machine-canonical; "
-                              "never hand-edit (ids are content-addressed, the seal "
-                              "covers the rest)",
-             "_integrity": _integrity_hash({"observations": observations}),
+                              "never hand-edit (ids are content-addressed; the seal "
+                              "covers observations, repo and path)",
+             "_integrity": _delta_seal(observations, args.repo, bound),
              "repo": args.repo,
+             **({"path": bound} if bound else {}),
              "observations": observations,
              "static_unsupported": {"files": unsupported,
                                     "note": "static extractors are Python-only in v0 "
@@ -8596,6 +8647,10 @@ def build_parser():
     pdd.add_argument("--narrated", default=None,
                      help="JSON list of skill-supplied observations {type, statement, files}; "
                           "the engine classifies them narrated -- it never calls an LLM")
+    pdd.add_argument("--path", default=None,
+                     help="bound the mechanical scans to one subtree/file (repo-relative); "
+                          "a bound matching nothing is a refusal, and it is recorded in "
+                          "the delta")
     pdd.add_argument("--acceptance", default=None,
                      help="acceptance file for canonical_match (default: config "
                           "defaults.acceptance_file, else ACCEPTANCE.md)")

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.69.0",
+  "version": "1.70.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, 40 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.69.0",
+  "version": "1.70.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.69.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.70.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.69.0
+uscha-kit 1.70.0

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

@@ -1 +1 @@
-{"AC-DD-01": true, "AC-DD-02": true, "AC-DD-03": true, "AC-DD-04": true, "AC-DD-05": true, "AC-DD-06": true, "AC-CU-06": true, "AC-CU-01": true, "AC-CU-02": true, "AC-CU-03": true, "AC-CU-04": true, "AC-CU-05": true, "review-m1": true, "review-m3": true, "review-h1": true}
+{"AC-DD-01": true, "AC-DD-02": true, "AC-DD-03": true, "AC-DD-04": true, "AC-DD-05": true, "AC-DD-06": true, "AC-CU-06": true, "AC-CU-01": true, "AC-CU-02": true, "AC-CU-03": true, "AC-CU-04": true, "AC-CU-05": true, "AC-DD-07": true, "review-m1": true, "review-m3": true, "review-h1": true}

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

@@ -58,6 +58,7 @@ import hashlib
 import json
 import math
 import os
+import posixpath
 import re
 import shutil
 import subprocess
@@ -3913,6 +3914,14 @@ _DELTA_BANNER = ("GENERATED by qa_ledger.py discover (ADR-013). Rendered view of
                  + CANDIDATE_DELTA_FILE + " -- hand edits are overwritten on regeneration.")
 
 
+def _delta_seal(observations, repo, path):
+    """The seal covers everything semantically load-bearing that the content-addressed OBS
+    ids do NOT: the full observation set, the repo, and the bound. `path` changes what the
+    delta MEANS (a partial discovery), so it must be sealed -- a hand edit of any of these is
+    a named malformation (fresh-review MEDIUM)."""
+    return _integrity_hash({"observations": observations, "repo": repo, "path": path})
+
+
 def _obs_id(otype, statement, primary_prov):
     """Content-addressed: OBS-sha256(type + LF + normalized statement + LF + primary
     provenance)[:12]. Normalization = lowercase + whitespace collapse. Re-running discovery
@@ -3998,7 +4007,11 @@ def _extract_static_py(repo_path, tracked):
     return obs, unsupported
 
 
-def _golden_backed_obs(ledger, repo, repo_path):
+def _under_bound(rel, bound):
+    return bound is None or rel == bound or rel.startswith(bound + "/")
+
+
+def _golden_backed_obs(ledger, repo, repo_path, bound=None):
     """Measured observations: one per approved golden fixture, backed by the LATEST ingested
     golden-diff gate record (AC-DD-03). Only source: real, ledger-ingested execution. No
     ingested run -> no measured OBS; a fixture on disk that nothing executed is not evidence."""
@@ -4016,6 +4029,8 @@ def _golden_backed_obs(ledger, repo, repo_path):
             if ".approved." not in f:
                 continue
             rel = os.path.relpath(os.path.join(root, f), repo_path).replace(os.sep, "/")
+            if not _under_bound(rel, bound):
+                continue
             stmt = "behavior frozen by golden fixture %s matches the approved baseline" % rel
             obs.append({"id": _obs_id("behavior", stmt, rel), "type": "behavior",
                         "statement": stmt, "evidence_class": "measured",
@@ -4108,9 +4123,16 @@ def _match_canonical(statement, canon_ids):
 
 def _render_delta_md(delta, verdicts):
     lines = ["<!-- %s -->" % _DELTA_BANNER, "",
-             "# CANDIDATE-DELTA (rendered view)", "",
-             "| id | type | class | verdict | statement | provenance |",
-             "|----|------|-------|---------|-----------|------------|"]
+             "# CANDIDATE-DELTA (rendered view)", ""]
+    if delta.get("path"):
+        # the bound is the artifact the HUMAN curates from -- a partial discovery must not
+        # read as a complete one, or the shrunk INV-CURATION-01 surface is undisclosed
+        # (fresh-review HIGH). The JSON recorded it; the human-facing view must too.
+        lines += ["> **BOUNDED discovery** — mechanical scans were restricted to "
+                  "`%s`. Files outside this path were NOT scanned; this delta is PARTIAL "
+                  "by construction." % delta["path"], ""]
+    lines += ["| id | type | class | verdict | statement | provenance |",
+              "|----|------|-------|---------|-----------|------------|"]
     for o in delta["observations"]:
         v = verdicts.get(o["id"], "(uncurated)")
         files = ", ".join(o["provenance"].get("files") or []) or "-"
@@ -4177,10 +4199,10 @@ def _load_delta(repo_path):
     # launders narrated inference into measured evidence (fresh-review MEDIUM, reproduced)
     if not errors:
         seal = delta.get("_integrity")
-        want = _integrity_hash({"observations": obs})
+        want = _delta_seal(obs, delta.get("repo"), delta.get("path"))
         if seal != want:
-            errors.append("integrity seal %s does not match the observations -- the delta "
-                          "is derived, never hand-edited (regenerate via `discover`)"
+            errors.append("integrity seal %s does not match the delta content -- observations, "
+                          "repo or path was hand-edited (regenerate via `discover`)"
                           % ("missing" if seal is None else repr(seal)))
     return delta, errors
 
@@ -4224,8 +4246,36 @@ def cmd_discover(args):
               "from tracked files and cannot proceed without it." % repo_path,
               file=sys.stderr)
         sys.exit(2)
+    bound = None
+    if args.path is not None:
+        # the bound restricts the MECHANICAL scans (static, measured); narrated input stays
+        # the skill's to scope. Field-found before the first run (AC-DD-07): "real, bounded"
+        # is unimplementable without it.
+        raw = args.path.replace("\\", "/").strip()
+        if not raw:
+            # an empty --path is the silent-degrade trap (a wrapper passing an unset var):
+            # falsy would mean "no bound" and quietly scan the whole repo (fresh-review MED)
+            print("[qa_ledger] discover: --path is empty -- omit --path to scan the whole "
+                  "repo; an empty bound is not a bound.", file=sys.stderr)
+            sys.exit(2)
+        bound = posixpath.normpath(raw).strip("/")     # ./src, src/ , /src -> src
+        if bound in (".", "") or bound == ".." or bound.startswith("../"):
+            print("[qa_ledger] discover: --path %r does not name a subtree inside the repo."
+                  % args.path, file=sys.stderr)
+            sys.exit(2)
+        if _gc_rel(os.path.join(repo_path, bound.replace("/", os.sep)), repo_path) is None:
+            print("[qa_ledger] discover: --path %r escapes the repo tree." % args.path,
+                  file=sys.stderr)
+            sys.exit(2)
+        tracked = [f for f in tracked if _under_bound(f, bound)]
+        if not tracked:
+            # a typo'd bound silently emitting an empty delta is the silent-degrade trap
+            print("[qa_ledger] discover: --path %r matches no tracked file -- refusing to "
+                  "emit an empty delta for a bound that points at nothing." % args.path,
+                  file=sys.stderr)
+            sys.exit(2)
     static_obs, unsupported = _extract_static_py(repo_path, tracked)
-    measured_obs = _golden_backed_obs(ledger, args.repo, repo_path)
+    measured_obs = _golden_backed_obs(ledger, args.repo, repo_path, bound)
     narrated_obs, nerrs = ([], [])
     if args.narrated:
         narrated_obs, nerrs = _load_narrated(args.narrated, repo_path)
@@ -4244,10 +4294,11 @@ def cmd_discover(args):
         o["canonical_match"] = _match_canonical(o["statement"], canon)
     observations = sorted(by_id.values(), key=lambda o: o["id"])
     delta = {"_generated_by": "qa_ledger.py discover (ADR-013) -- machine-canonical; "
-                              "never hand-edit (ids are content-addressed, the seal "
-                              "covers the rest)",
-             "_integrity": _integrity_hash({"observations": observations}),
+                              "never hand-edit (ids are content-addressed; the seal "
+                              "covers observations, repo and path)",
+             "_integrity": _delta_seal(observations, args.repo, bound),
              "repo": args.repo,
+             **({"path": bound} if bound else {}),
              "observations": observations,
              "static_unsupported": {"files": unsupported,
                                     "note": "static extractors are Python-only in v0 "
@@ -8596,6 +8647,10 @@ def build_parser():
     pdd.add_argument("--narrated", default=None,
                      help="JSON list of skill-supplied observations {type, statement, files}; "
                           "the engine classifies them narrated -- it never calls an LLM")
+    pdd.add_argument("--path", default=None,
+                     help="bound the mechanical scans to one subtree/file (repo-relative); "
+                          "a bound matching nothing is a refusal, and it is recorded in "
+                          "the delta")
     pdd.add_argument("--acceptance", default=None,
                      help="acceptance file for canonical_match (default: config "
                           "defaults.acceptance_file, else ACCEPTANCE.md)")

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.69.0",
+  "version": "1.70.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,