@mc-and-his-agents/loom-installer 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mc-and-his-agents/loom-installer",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Node installer for Loom plugin and single-skill installation surfaces.",
   "type": "module",
   "bin": {

package/payload/manifest.json

@@ -2,9 +2,9 @@
   "schema_version": "loom-installer-payload/v1",
   "loom_version": "0.4.0",
   "source_repository": "https://github.com/MC-and-his-Agents/Loom",
-  "source_commit": "f11f0f24401eca30d21786c41e39a74be05bf342",
+  "source_commit": "b07d54d4963a674da0ff2397f4ad244cb3028584",
   "source_ref": "main",
-  "built_at": "2026-04-25T11:57:32+08:00",
+  "built_at": "2026-04-25T12:04:56+08:00",
   "runtime": {
     "python_minimum": "3.10",
     "python_recommended": "3.11+"
@@ -628,13 +628,13 @@
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_init.py",
@@ -1213,13 +1213,13 @@
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_init.py",
@@ -1828,13 +1828,13 @@
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_init.py",
@@ -2443,13 +2443,13 @@
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_init.py",
@@ -3063,13 +3063,13 @@
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_init.py",
@@ -3678,13 +3678,13 @@
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -4293,13 +4293,13 @@
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_init.py",
@@ -4908,13 +4908,13 @@
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_init.py",
@@ -5523,13 +5523,13 @@
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -6138,13 +6138,13 @@
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 256345,
-      "sha256": "5a515322557bf66f21c37e138e3e0302be450842abdf5b42a5c9b94a62012b95"
+      "bytes": 260856,
+      "sha256": "9f9b145158d659764c853f7234dfb7308c96e78031f43741e431905b91a6b7fc"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 260571,
-      "sha256": "47c0437b00572be5cf84125fd5ccde1449afb41c93c493942e6c4c1dbf3462cb"
+      "bytes": 262117,
+      "sha256": "ec49996bbebb9a59fee0f906d301c2c66e13e17ec548ef762f2b0e33e9abbe32"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_init.py",

package/payload/plugin/loom/skills/shared/scripts/loom_check.py

@@ -94,6 +94,7 @@ CORE_DOCS = (
     "docs/evidence/landing-map.md",
     "docs/evidence/validations/validation-closeout-reconciliation-blocking-gate.md",
     "docs/evidence/validations/validation-loom-core-runtime-parity.md",
+    "docs/evidence/validations/validation-shadow-parity-blocking-gate.md",
     "docs/evidence/validations/validation-syvert-strong-governance-parity.md",
     "docs/adoption/rationale.md",
     "docs/adoption/routing-and-checkpoints.md",
@@ -969,10 +970,17 @@ def require_shadow_parity_payload(
         return
     if payload.get("command") != "shadow-parity":
         failures.append(Failure(category, f"{context} must report `command: shadow-parity`"))
-    if payload.get("result") not in {"pass", "warn"}:
-        failures.append(Failure(category, f"{context} result must be `pass` or `warn`"))
-    if payload.get("fallback_to") is not None:
-        failures.append(Failure(category, f"{context} fallback_to must remain `null`"))
+    mode = payload.get("mode", "validation-only")
+    if mode not in {"validation-only", "blocking"}:
+        failures.append(Failure(category, f"{context} mode must be `validation-only` or `blocking`"))
+    if payload.get("blocking") != (mode == "blocking"):
+        failures.append(Failure(category, f"{context} blocking flag must match mode"))
+    allowed_results = {"pass", "block"} if mode == "blocking" else {"pass", "warn"}
+    if payload.get("result") not in allowed_results:
+        failures.append(Failure(category, f"{context} result must stay within the stable mode-specific contract"))
+    expected_fallbacks = {"manual-reconciliation"} if payload.get("result") == "block" else {None}
+    if payload.get("fallback_to") not in expected_fallbacks:
+        failures.append(Failure(category, f"{context} fallback_to must match the shadow parity enforcement mode"))
     if not isinstance(payload.get("summary"), str) or not payload.get("summary"):
         failures.append(Failure(category, f"{context} must include non-empty `summary`"))
     if not isinstance(payload.get("missing_inputs"), list):
@@ -1008,6 +1016,14 @@ def require_shadow_parity_payload(
             failures.append(Failure(category, f"{context} reports[{index}] must declare a known surface"))
         if report.get("result") not in {"match", "mismatch", "unreadable"}:
             failures.append(Failure(category, f"{context} reports[{index}] result must stay within the stable contract"))
+        if report.get("classification") not in {None, "drift", "gate_failure"}:
+            failures.append(Failure(category, f"{context} reports[{index}] classification must stay within the stable contract"))
+        if not isinstance(report.get("blocking"), bool):
+            failures.append(Failure(category, f"{context} reports[{index}] must include boolean `blocking`"))
+        if not isinstance(report.get("recommended_action"), str) or not report.get("recommended_action"):
+            failures.append(Failure(category, f"{context} reports[{index}] must include non-empty `recommended_action`"))
+        if mode == "blocking" and report.get("result") != "match" and report.get("blocking") is not True:
+            failures.append(Failure(category, f"{context} reports[{index}] must block non-matching reports in blocking mode"))
         if not isinstance(report.get("summary"), str) or not report.get("summary"):
             failures.append(Failure(category, f"{context} reports[{index}] must include non-empty `summary`"))
         if not isinstance(report.get("missing_inputs"), list):
@@ -5301,6 +5317,23 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
             if parity_payload.get("result") != "pass":
                 failures.append(Failure("repo-interop", "`shadow-parity` must pass when all declared surfaces match"))
 
+        blocking_match_payload, error = load_command_json(
+            root,
+            ["python3", "tools/loom_flow.py", "shadow-parity", "--target", str(present_target), "--blocking"],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity --blocking` match sample failed: {error}"))
+        else:
+            require_shadow_parity_payload(
+                failures,
+                category="repo-interop",
+                context="`shadow-parity --blocking` match sample",
+                payload=blocking_match_payload,
+                expected_reports=4,
+            )
+            if blocking_match_payload.get("result") != "pass":
+                failures.append(Failure("repo-interop", "`shadow-parity --blocking` must pass when all declared surfaces match"))
+
         mismatch_target = base / "mismatch"
         shutil.copytree(present_target, mismatch_target)
         write_json(mismatch_target / ".loom/shadow/review-repo.json", {"decision": "block"})
@@ -5322,6 +5355,62 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
             if not isinstance(reports, list) or not reports or reports[0].get("result") != "mismatch":
                 failures.append(Failure("repo-interop", "`shadow-parity` mismatch sample must report `mismatch`"))
 
+        blocking_mismatch_payload, error = load_command_json(
+            root,
+            [
+                "python3",
+                "tools/loom_flow.py",
+                "shadow-parity",
+                "--target",
+                str(mismatch_target),
+                "--surface",
+                "review",
+                "--mode",
+                "blocking",
+            ],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity --mode blocking` mismatch sample failed: {error}"))
+        else:
+            require_shadow_parity_payload(
+                failures,
+                category="repo-interop",
+                context="`shadow-parity --mode blocking` mismatch sample",
+                payload=blocking_mismatch_payload,
+                expected_reports=1,
+            )
+            if blocking_mismatch_payload.get("result") != "block":
+                failures.append(Failure("repo-interop", "`shadow-parity --mode blocking` must block mismatches"))
+
+        unreadable_target = base / "unreadable"
+        shutil.copytree(present_target, unreadable_target)
+        (unreadable_target / ".loom/shadow/closeout-repo.json").unlink()
+        blocking_unreadable_payload, error = load_command_json(
+            root,
+            [
+                "python3",
+                "tools/loom_flow.py",
+                "shadow-parity",
+                "--target",
+                str(unreadable_target),
+                "--surface",
+                "closeout",
+                "--blocking",
+            ],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity --blocking` unreadable sample failed: {error}"))
+        else:
+            require_shadow_parity_payload(
+                failures,
+                category="repo-interop",
+                context="`shadow-parity --blocking` unreadable sample",
+                payload=blocking_unreadable_payload,
+                expected_reports=1,
+            )
+            if blocking_unreadable_payload.get("result") != "block":
+                failures.append(Failure("repo-interop", "`shadow-parity --blocking` must block unreadable surfaces"))
+
     return failures
 
 

package/payload/plugin/loom/skills/shared/scripts/loom_flow.py

@@ -276,6 +276,17 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
         default=".loom/bootstrap/init-result.json",
         help="Init-result path relative to the target root",
     )
+    shadow.add_argument(
+        "--mode",
+        choices=("validation-only", "blocking"),
+        default="validation-only",
+        help="Shadow parity enforcement mode; defaults to validation-only.",
+    )
+    shadow.add_argument(
+        "--blocking",
+        action="store_true",
+        help="Shortcut for --mode blocking. This is explicit opt-in and never the default.",
+    )
 
     runtime_parity = subparsers.add_parser(
         "runtime-parity",
@@ -543,8 +554,11 @@ def shadow_parity_report(
     empty_report = {
         "surface": surface,
         "result": "unreadable",
+        "classification": "gate_failure",
+        "blocking": False,
         "summary": "shadow parity could not be evaluated for this surface.",
         "missing_inputs": [],
+        "recommended_action": "restore the declared Loom and repo-native shadow parity locators before treating this surface as authoritative.",
         "host_adapters": [],
         "repo_native_carriers": [],
         "loom_surface": {
@@ -633,8 +647,11 @@ def shadow_parity_report(
         return {
             "surface": surface,
             "result": "match",
+            "classification": None,
+            "blocking": False,
             "summary": "Loom and repo-native surfaces report the same normalized result.",
             "missing_inputs": [],
+            "recommended_action": "no shadow parity action required.",
             "host_adapters": relevant_host_adapters,
             "repo_native_carriers": relevant_repo_native_carriers,
             "loom_surface": loom_surface,
@@ -643,8 +660,11 @@ def shadow_parity_report(
     return {
         "surface": surface,
         "result": "mismatch",
+        "classification": "drift",
+        "blocking": False,
         "summary": "Loom and repo-native surfaces disagree on the normalized result.",
         "missing_inputs": [],
+        "recommended_action": "resolve the parity mismatch or explicitly choose the authoritative surface outside repo interop before enabling blocking consumption.",
         "host_adapters": relevant_host_adapters,
         "repo_native_carriers": relevant_repo_native_carriers,
         "loom_surface": loom_surface,
@@ -6122,6 +6142,7 @@ def handle_shadow_parity(args: argparse.Namespace) -> int:
     governance_surface = build_governance_surface(target_root)
     repo_interop = governance_surface.get("repo_interop")
     requested_surfaces = SHADOW_PARITY_SURFACES if args.surface == "all" else (args.surface,)
+    mode = "blocking" if args.blocking else args.mode
     reports = [
         shadow_parity_report(
             repo_interop,
@@ -6131,9 +6152,18 @@ def handle_shadow_parity(args: argparse.Namespace) -> int:
         for surface in requested_surfaces
     ]
 
-    result = "pass" if reports and all(report["result"] == "match" for report in reports) else "warn"
+    all_match = bool(reports) and all(report["result"] == "match" for report in reports)
+    blocking_reports = [report for report in reports if report.get("result") != "match"]
+    if mode == "blocking":
+        result = "pass" if all_match else "block"
+        for report in blocking_reports:
+            report["blocking"] = True
+    else:
+        result = "pass" if all_match else "warn"
     if result == "pass":
         summary = "shadow parity matches across all requested surfaces."
+    elif mode == "blocking":
+        summary = "shadow parity blocking mode found mismatch or unreadable surfaces."
     else:
         summaries = {report["result"] for report in reports}
         if "mismatch" in summaries:
@@ -6150,10 +6180,12 @@ def handle_shadow_parity(args: argparse.Namespace) -> int:
     return emit(
         {
             "command": "shadow-parity",
+            "mode": mode,
+            "blocking": mode == "blocking",
             "result": result,
             "summary": summary,
             "missing_inputs": missing_inputs,
-            "fallback_to": None,
+            "fallback_to": "manual-reconciliation" if result == "block" else None,
             "runtime_state": runtime_state,
             "governance_surface": governance_surface,
             "reports": reports,

package/payload/skills/loom-adopt/.loom-runtime/shared/scripts/loom_check.py

@@ -94,6 +94,7 @@ CORE_DOCS = (
     "docs/evidence/landing-map.md",
     "docs/evidence/validations/validation-closeout-reconciliation-blocking-gate.md",
     "docs/evidence/validations/validation-loom-core-runtime-parity.md",
+    "docs/evidence/validations/validation-shadow-parity-blocking-gate.md",
     "docs/evidence/validations/validation-syvert-strong-governance-parity.md",
     "docs/adoption/rationale.md",
     "docs/adoption/routing-and-checkpoints.md",
@@ -969,10 +970,17 @@ def require_shadow_parity_payload(
         return
     if payload.get("command") != "shadow-parity":
         failures.append(Failure(category, f"{context} must report `command: shadow-parity`"))
-    if payload.get("result") not in {"pass", "warn"}:
-        failures.append(Failure(category, f"{context} result must be `pass` or `warn`"))
-    if payload.get("fallback_to") is not None:
-        failures.append(Failure(category, f"{context} fallback_to must remain `null`"))
+    mode = payload.get("mode", "validation-only")
+    if mode not in {"validation-only", "blocking"}:
+        failures.append(Failure(category, f"{context} mode must be `validation-only` or `blocking`"))
+    if payload.get("blocking") != (mode == "blocking"):
+        failures.append(Failure(category, f"{context} blocking flag must match mode"))
+    allowed_results = {"pass", "block"} if mode == "blocking" else {"pass", "warn"}
+    if payload.get("result") not in allowed_results:
+        failures.append(Failure(category, f"{context} result must stay within the stable mode-specific contract"))
+    expected_fallbacks = {"manual-reconciliation"} if payload.get("result") == "block" else {None}
+    if payload.get("fallback_to") not in expected_fallbacks:
+        failures.append(Failure(category, f"{context} fallback_to must match the shadow parity enforcement mode"))
     if not isinstance(payload.get("summary"), str) or not payload.get("summary"):
         failures.append(Failure(category, f"{context} must include non-empty `summary`"))
     if not isinstance(payload.get("missing_inputs"), list):
@@ -1008,6 +1016,14 @@ def require_shadow_parity_payload(
             failures.append(Failure(category, f"{context} reports[{index}] must declare a known surface"))
         if report.get("result") not in {"match", "mismatch", "unreadable"}:
             failures.append(Failure(category, f"{context} reports[{index}] result must stay within the stable contract"))
+        if report.get("classification") not in {None, "drift", "gate_failure"}:
+            failures.append(Failure(category, f"{context} reports[{index}] classification must stay within the stable contract"))
+        if not isinstance(report.get("blocking"), bool):
+            failures.append(Failure(category, f"{context} reports[{index}] must include boolean `blocking`"))
+        if not isinstance(report.get("recommended_action"), str) or not report.get("recommended_action"):
+            failures.append(Failure(category, f"{context} reports[{index}] must include non-empty `recommended_action`"))
+        if mode == "blocking" and report.get("result") != "match" and report.get("blocking") is not True:
+            failures.append(Failure(category, f"{context} reports[{index}] must block non-matching reports in blocking mode"))
         if not isinstance(report.get("summary"), str) or not report.get("summary"):
             failures.append(Failure(category, f"{context} reports[{index}] must include non-empty `summary`"))
         if not isinstance(report.get("missing_inputs"), list):
@@ -5301,6 +5317,23 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
             if parity_payload.get("result") != "pass":
                 failures.append(Failure("repo-interop", "`shadow-parity` must pass when all declared surfaces match"))
 
+        blocking_match_payload, error = load_command_json(
+            root,
+            ["python3", "tools/loom_flow.py", "shadow-parity", "--target", str(present_target), "--blocking"],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity --blocking` match sample failed: {error}"))
+        else:
+            require_shadow_parity_payload(
+                failures,
+                category="repo-interop",
+                context="`shadow-parity --blocking` match sample",
+                payload=blocking_match_payload,
+                expected_reports=4,
+            )
+            if blocking_match_payload.get("result") != "pass":
+                failures.append(Failure("repo-interop", "`shadow-parity --blocking` must pass when all declared surfaces match"))
+
         mismatch_target = base / "mismatch"
         shutil.copytree(present_target, mismatch_target)
         write_json(mismatch_target / ".loom/shadow/review-repo.json", {"decision": "block"})
@@ -5322,6 +5355,62 @@ def check_repo_interop_contracts(root: Path) -> list[Failure]:
             if not isinstance(reports, list) or not reports or reports[0].get("result") != "mismatch":
                 failures.append(Failure("repo-interop", "`shadow-parity` mismatch sample must report `mismatch`"))
 
+        blocking_mismatch_payload, error = load_command_json(
+            root,
+            [
+                "python3",
+                "tools/loom_flow.py",
+                "shadow-parity",
+                "--target",
+                str(mismatch_target),
+                "--surface",
+                "review",
+                "--mode",
+                "blocking",
+            ],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity --mode blocking` mismatch sample failed: {error}"))
+        else:
+            require_shadow_parity_payload(
+                failures,
+                category="repo-interop",
+                context="`shadow-parity --mode blocking` mismatch sample",
+                payload=blocking_mismatch_payload,
+                expected_reports=1,
+            )
+            if blocking_mismatch_payload.get("result") != "block":
+                failures.append(Failure("repo-interop", "`shadow-parity --mode blocking` must block mismatches"))
+
+        unreadable_target = base / "unreadable"
+        shutil.copytree(present_target, unreadable_target)
+        (unreadable_target / ".loom/shadow/closeout-repo.json").unlink()
+        blocking_unreadable_payload, error = load_command_json(
+            root,
+            [
+                "python3",
+                "tools/loom_flow.py",
+                "shadow-parity",
+                "--target",
+                str(unreadable_target),
+                "--surface",
+                "closeout",
+                "--blocking",
+            ],
+        )
+        if error:
+            failures.append(Failure("repo-interop", f"`shadow-parity --blocking` unreadable sample failed: {error}"))
+        else:
+            require_shadow_parity_payload(
+                failures,
+                category="repo-interop",
+                context="`shadow-parity --blocking` unreadable sample",
+                payload=blocking_unreadable_payload,
+                expected_reports=1,
+            )
+            if blocking_unreadable_payload.get("result") != "block":
+                failures.append(Failure("repo-interop", "`shadow-parity --blocking` must block unreadable surfaces"))
+
     return failures
 
 

package/payload/skills/loom-adopt/.loom-runtime/shared/scripts/loom_flow.py

@@ -276,6 +276,17 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
         default=".loom/bootstrap/init-result.json",
         help="Init-result path relative to the target root",
     )
+    shadow.add_argument(
+        "--mode",
+        choices=("validation-only", "blocking"),
+        default="validation-only",
+        help="Shadow parity enforcement mode; defaults to validation-only.",
+    )
+    shadow.add_argument(
+        "--blocking",
+        action="store_true",
+        help="Shortcut for --mode blocking. This is explicit opt-in and never the default.",
+    )
 
     runtime_parity = subparsers.add_parser(
         "runtime-parity",
@@ -543,8 +554,11 @@ def shadow_parity_report(
     empty_report = {
         "surface": surface,
         "result": "unreadable",
+        "classification": "gate_failure",
+        "blocking": False,
         "summary": "shadow parity could not be evaluated for this surface.",
         "missing_inputs": [],
+        "recommended_action": "restore the declared Loom and repo-native shadow parity locators before treating this surface as authoritative.",
         "host_adapters": [],
         "repo_native_carriers": [],
         "loom_surface": {
@@ -633,8 +647,11 @@ def shadow_parity_report(
         return {
             "surface": surface,
             "result": "match",
+            "classification": None,
+            "blocking": False,
             "summary": "Loom and repo-native surfaces report the same normalized result.",
             "missing_inputs": [],
+            "recommended_action": "no shadow parity action required.",
             "host_adapters": relevant_host_adapters,
             "repo_native_carriers": relevant_repo_native_carriers,
             "loom_surface": loom_surface,
@@ -643,8 +660,11 @@ def shadow_parity_report(
     return {
         "surface": surface,
         "result": "mismatch",
+        "classification": "drift",
+        "blocking": False,
         "summary": "Loom and repo-native surfaces disagree on the normalized result.",
         "missing_inputs": [],
+        "recommended_action": "resolve the parity mismatch or explicitly choose the authoritative surface outside repo interop before enabling blocking consumption.",
         "host_adapters": relevant_host_adapters,
         "repo_native_carriers": relevant_repo_native_carriers,
         "loom_surface": loom_surface,
@@ -6122,6 +6142,7 @@ def handle_shadow_parity(args: argparse.Namespace) -> int:
     governance_surface = build_governance_surface(target_root)
     repo_interop = governance_surface.get("repo_interop")
     requested_surfaces = SHADOW_PARITY_SURFACES if args.surface == "all" else (args.surface,)
+    mode = "blocking" if args.blocking else args.mode
     reports = [
         shadow_parity_report(
             repo_interop,
@@ -6131,9 +6152,18 @@ def handle_shadow_parity(args: argparse.Namespace) -> int:
         for surface in requested_surfaces
     ]
 
-    result = "pass" if reports and all(report["result"] == "match" for report in reports) else "warn"
+    all_match = bool(reports) and all(report["result"] == "match" for report in reports)
+    blocking_reports = [report for report in reports if report.get("result") != "match"]
+    if mode == "blocking":
+        result = "pass" if all_match else "block"
+        for report in blocking_reports:
+            report["blocking"] = True
+    else:
+        result = "pass" if all_match else "warn"
     if result == "pass":
         summary = "shadow parity matches across all requested surfaces."
+    elif mode == "blocking":
+        summary = "shadow parity blocking mode found mismatch or unreadable surfaces."
     else:
         summaries = {report["result"] for report in reports}
         if "mismatch" in summaries:
@@ -6150,10 +6180,12 @@ def handle_shadow_parity(args: argparse.Namespace) -> int:
     return emit(
         {
             "command": "shadow-parity",
+            "mode": mode,
+            "blocking": mode == "blocking",
             "result": result,
             "summary": summary,
             "missing_inputs": missing_inputs,
-            "fallback_to": None,
+            "fallback_to": "manual-reconciliation" if result == "block" else None,
             "runtime_state": runtime_state,
             "governance_surface": governance_surface,
             "reports": reports,