@andresmassello/uscha 1.69.0 → 1.71.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.71.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.71.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 "
@@ -4482,6 +4533,10 @@ def cmd_fidelity(args):
         sys.exit(2)
     obs = (delta.get("observations") or []) if delta else []
     verdicts = _curation_verdicts(ledger, args.repo)
+    # fidelity respects the SAME bound that produced the delta (user decision, FR-001): a
+    # bounded discovery is measured over its own subtree, so unexplained_code and the other
+    # mechanical dimensions never mix the delta's scope with the whole repo's.
+    bound = delta.get("path") if delta else None
     dims = {}
     # traceability: canonical items reachable in code via the uscha-spec id machinery
     canon_items = []
@@ -4492,7 +4547,17 @@ def cmd_fidelity(args):
                 canon_items = json.load(fh).get("items") or []
         except (OSError, ValueError):
             canon_items = []
-    tracked = _tracked_files(repo_path) or []
+    tracked = [f for f in (_tracked_files(repo_path) or []) if _under_bound(f, bound)]
+    _scope = " (bounded to %s)" % bound if bound else ""
+    if bound:
+        # scope the DENOMINATOR too, not just the file scan: promote MERGES into CANONICAL
+        # repo-wide, so an earlier unbounded promote would otherwise count out-of-bound
+        # items as "no longer derives" -- the exact scope-mixing this release kills, half-
+        # done if only the numerator moves (fresh-review LOW). An item is under the bound
+        # when its primary provenance file is.
+        canon_items = [it for it in canon_items
+                       if any(_under_bound(f.split(":")[0].split("#")[0], bound)
+                              for f in (it.get("provenance") or {}).get("files") or [])]
     marked, marker_files = set(), set()
     for f, mid in _scan_spec_markers(repo_path, tracked):
         marked.add(mid)
@@ -4501,8 +4566,8 @@ def cmd_fidelity(args):
         traced = sum(1 for it in canon_items if (it.get("derived_from") or "") in marked)
         dims["traceability"] = _fid_dim(round(traced / len(canon_items), 4),
                                         "uscha-spec marker scan over %d git-tracked "
-                                        "files vs %d canonical item(s)"
-                                        % (len(tracked), len(canon_items)))
+                                        "files%s vs %d canonical item(s)"
+                                        % (len(tracked), _scope, len(canon_items)))
     else:
         dims["traceability"] = _fid_dim(None, "UNMEASURED: no canonical items promoted yet")
     # behavior: the latest ingested golden-diff gate verdict
@@ -4528,9 +4593,9 @@ def cmd_fidelity(args):
         cur_ids = {o["id"] for o in cur_static}
         okc = sum(1 for it in static_canon if it.get("derived_from") in cur_ids)
         dims["contracts"] = _fid_dim(round(okc / len(static_canon), 4),
-                                     "re-ran static extractors; %d/%d canonical static "
+                                     "re-ran static extractors%s; %d/%d canonical static "
                                      "item(s) still derive from the code"
-                                     % (okc, len(static_canon)))
+                                     % (_scope, okc, len(static_canon)))
     else:
         dims["contracts"] = _fid_dim(None, "UNMEASURED: no static-class canonical items")
     # curation_closure: curated OBS / total OBS in the active delta
@@ -4565,14 +4630,15 @@ def cmd_fidelity(args):
         unex = [f for f in prod if f not in lineage]
         dims["unexplained_code"] = _fid_dim(
             round(len(unex) / len(prod), 4),
-            "%d/%d tracked prod source file(s) with no path to a canonical item or "
-            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod)),
+            "%d/%d tracked prod source file(s)%s with no path to a canonical item or "
+            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod), _scope),
             files=unex[:10] + (["(+%d)" % (len(unex) - 10)] if len(unex) > 10 else []))
     else:
         dims["unexplained_code"] = _fid_dim(None, "UNMEASURED: no tracked prod source files")
     dims["semantic"] = _fid_dim(None, "not wired: an LLM-judged comparison enters as "
                                       "advisory only and can NEVER gate (INV-ADVISORY-01)")
     out = {"repo": args.repo,
+           **({"path": bound} if bound else {}),
            "dimensions": {k: dict(dims[k], **{"class": FIDELITY_DIMENSIONS[k]})
                           for k in ("traceability", "behavior", "contracts",
                                     "curation_closure", "unexplained_code", "semantic")}}
@@ -4581,8 +4647,8 @@ def cmd_fidelity(args):
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
     else:
-        print("FIDELITY %s (vector -- no blend; each number stands on its own evidence):"
-              % args.repo)
+        print("FIDELITY %s%s (vector -- no blend; each number stands on its own evidence):"
+              % (args.repo, " [bounded to %s]" % bound if bound else ""))
         for k, d in out["dimensions"].items():
             val = "UNMEASURED" if d["value"] is None else "%.2f" % d["value"]
             print("  %-17s %-10s [%s] %s" % (k, val, d["class"], d["provenance"]))
@@ -8596,6 +8662,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.71.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.71.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.71.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.71.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/reports/junit/.fidelity-cases.json

@@ -1 +1 @@
-{"AC-FV-01": true, "AC-FV-02": true, "AC-FV-04": true, "AC-FV-05": true, "AC-FV-03": true, "review-h2": true, "review-m4": true}
+{"AC-FV-01": true, "AC-FV-02": true, "AC-FV-04": true, "AC-FV-05": true, "AC-FV-03": true, "review-h2": true, "AC-FV-06": true, "review-m4": 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 "
@@ -4482,6 +4533,10 @@ def cmd_fidelity(args):
         sys.exit(2)
     obs = (delta.get("observations") or []) if delta else []
     verdicts = _curation_verdicts(ledger, args.repo)
+    # fidelity respects the SAME bound that produced the delta (user decision, FR-001): a
+    # bounded discovery is measured over its own subtree, so unexplained_code and the other
+    # mechanical dimensions never mix the delta's scope with the whole repo's.
+    bound = delta.get("path") if delta else None
     dims = {}
     # traceability: canonical items reachable in code via the uscha-spec id machinery
     canon_items = []
@@ -4492,7 +4547,17 @@ def cmd_fidelity(args):
                 canon_items = json.load(fh).get("items") or []
         except (OSError, ValueError):
             canon_items = []
-    tracked = _tracked_files(repo_path) or []
+    tracked = [f for f in (_tracked_files(repo_path) or []) if _under_bound(f, bound)]
+    _scope = " (bounded to %s)" % bound if bound else ""
+    if bound:
+        # scope the DENOMINATOR too, not just the file scan: promote MERGES into CANONICAL
+        # repo-wide, so an earlier unbounded promote would otherwise count out-of-bound
+        # items as "no longer derives" -- the exact scope-mixing this release kills, half-
+        # done if only the numerator moves (fresh-review LOW). An item is under the bound
+        # when its primary provenance file is.
+        canon_items = [it for it in canon_items
+                       if any(_under_bound(f.split(":")[0].split("#")[0], bound)
+                              for f in (it.get("provenance") or {}).get("files") or [])]
     marked, marker_files = set(), set()
     for f, mid in _scan_spec_markers(repo_path, tracked):
         marked.add(mid)
@@ -4501,8 +4566,8 @@ def cmd_fidelity(args):
         traced = sum(1 for it in canon_items if (it.get("derived_from") or "") in marked)
         dims["traceability"] = _fid_dim(round(traced / len(canon_items), 4),
                                         "uscha-spec marker scan over %d git-tracked "
-                                        "files vs %d canonical item(s)"
-                                        % (len(tracked), len(canon_items)))
+                                        "files%s vs %d canonical item(s)"
+                                        % (len(tracked), _scope, len(canon_items)))
     else:
         dims["traceability"] = _fid_dim(None, "UNMEASURED: no canonical items promoted yet")
     # behavior: the latest ingested golden-diff gate verdict
@@ -4528,9 +4593,9 @@ def cmd_fidelity(args):
         cur_ids = {o["id"] for o in cur_static}
         okc = sum(1 for it in static_canon if it.get("derived_from") in cur_ids)
         dims["contracts"] = _fid_dim(round(okc / len(static_canon), 4),
-                                     "re-ran static extractors; %d/%d canonical static "
+                                     "re-ran static extractors%s; %d/%d canonical static "
                                      "item(s) still derive from the code"
-                                     % (okc, len(static_canon)))
+                                     % (_scope, okc, len(static_canon)))
     else:
         dims["contracts"] = _fid_dim(None, "UNMEASURED: no static-class canonical items")
     # curation_closure: curated OBS / total OBS in the active delta
@@ -4565,14 +4630,15 @@ def cmd_fidelity(args):
         unex = [f for f in prod if f not in lineage]
         dims["unexplained_code"] = _fid_dim(
             round(len(unex) / len(prod), 4),
-            "%d/%d tracked prod source file(s) with no path to a canonical item or "
-            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod)),
+            "%d/%d tracked prod source file(s)%s with no path to a canonical item or "
+            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod), _scope),
             files=unex[:10] + (["(+%d)" % (len(unex) - 10)] if len(unex) > 10 else []))
     else:
         dims["unexplained_code"] = _fid_dim(None, "UNMEASURED: no tracked prod source files")
     dims["semantic"] = _fid_dim(None, "not wired: an LLM-judged comparison enters as "
                                       "advisory only and can NEVER gate (INV-ADVISORY-01)")
     out = {"repo": args.repo,
+           **({"path": bound} if bound else {}),
            "dimensions": {k: dict(dims[k], **{"class": FIDELITY_DIMENSIONS[k]})
                           for k in ("traceability", "behavior", "contracts",
                                     "curation_closure", "unexplained_code", "semantic")}}
@@ -4581,8 +4647,8 @@ def cmd_fidelity(args):
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
     else:
-        print("FIDELITY %s (vector -- no blend; each number stands on its own evidence):"
-              % args.repo)
+        print("FIDELITY %s%s (vector -- no blend; each number stands on its own evidence):"
+              % (args.repo, " [bounded to %s]" % bound if bound else ""))
         for k, d in out["dimensions"].items():
             val = "UNMEASURED" if d["value"] is None else "%.2f" % d["value"]
             print("  %-17s %-10s [%s] %s" % (k, val, d["class"], d["provenance"]))
@@ -8596,6 +8662,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.71.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,