@mc-and-his-agents/loom-installer 0.1.17 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mc-and-his-agents/loom-installer",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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": "c3f5933d41b009b1e0537356221c3bcd7fd910be",
+  "source_commit": "3daaced2a93b2f5170fc738bcd631d6323336c82",
   "source_ref": "main",
-  "built_at": "2026-04-25T13:23:16+08:00",
+  "built_at": "2026-04-25T13:30:42+08:00",
   "runtime": {
     "python_minimum": "3.10",
     "python_recommended": "3.11+"
@@ -623,18 +623,18 @@
     },
     {
       "path": "plugin/loom/skills/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_init.py",
@@ -1208,18 +1208,18 @@
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_init.py",
@@ -1823,18 +1823,18 @@
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_init.py",
@@ -2438,18 +2438,18 @@
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_init.py",
@@ -3058,18 +3058,18 @@
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_init.py",
@@ -3673,18 +3673,18 @@
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -4288,18 +4288,18 @@
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_init.py",
@@ -4903,18 +4903,18 @@
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_init.py",
@@ -5518,18 +5518,18 @@
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_init.py",
@@ -6133,18 +6133,18 @@
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/governance_surface.py",
-      "bytes": 48077,
-      "sha256": "ecb24c8c58d978cd9207f8a99881e560c6f64f015cffa527bd221a1cf7cf2e24"
+      "bytes": 51952,
+      "sha256": "ae74631688a91f774f29c54177f7b8477f23d445395e315fb91b24f5412dfcd2"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_check.py",
-      "bytes": 269850,
-      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
+      "bytes": 271781,
+      "sha256": "916036e9f69521168511ca4e30cd7066ae2d9abb22294fb984ebe3d76d199cfa"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 287204,
-      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
+      "bytes": 288183,
+      "sha256": "76fd6610e74672d527f43edd1311dbd6ca571406536d04dae502236eb67a5a38"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_init.py",

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

@@ -146,6 +146,112 @@ MATURITY_LEVELS = {
         "summary": "Host-backed binding, reconciliation, controlled merge, and closeout gates are available.",
     },
 }
+MATURITY_REQUIRED_FIELDS = {
+    "light": [
+        {
+            "id": "work_item",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "run loom-init or restore the Work Item carrier",
+        },
+        {
+            "id": "recovery",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "restore the recovery carrier",
+        },
+        {
+            "id": "status_surface",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "restore the status surface carrier",
+        },
+        {
+            "id": "review",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "restore the review carrier",
+        },
+    ],
+    "standard": [
+        {
+            "id": "fr_work_item_layer",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "profile",
+            "recommended_action": "declare the FR -> Work Item split through the GitHub profile upgrade path",
+        },
+        {
+            "id": "spec_path",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "install formal spec scaffold",
+        },
+        {
+            "id": "plan_path",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "install execution plan scaffold",
+        },
+        {
+            "id": "spec_gate",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "record or restore the spec review gate",
+        },
+        {
+            "id": "status_control_plane",
+            "layer": "core",
+            "required": True,
+            "defaulting": "builtin",
+            "recommended_action": "run loom_status or loom_check to rebuild the status control plane",
+        },
+        {
+            "id": "basic_host_binding",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "profile",
+            "recommended_action": "run governance-profile binding and repair missing host bindings",
+        },
+        {
+            "id": "closeout_reconciliation_read",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "profile",
+            "recommended_action": "install repo interop so closeout can consume reconciliation",
+        },
+    ],
+    "strong": [
+        {
+            "id": "repo_interface",
+            "layer": "repo-owned-residue",
+            "required": True,
+            "defaulting": "scaffold",
+            "recommended_action": "install or repair the repo companion interface",
+        },
+        {
+            "id": "repo_interop",
+            "layer": "repo-owned-residue",
+            "required": True,
+            "defaulting": "scaffold",
+            "recommended_action": "install or repair the repo interop contract",
+        },
+        {
+            "id": "github_controlled_merge",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "host",
+            "recommended_action": "enable controlled merge binding and required host gates",
+        },
+    ],
+}
 
 
 def run_process(args: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
@@ -1033,9 +1139,16 @@ def maturity_status(
     }
     achieved: list[str] = []
     missing_by_level: dict[str, list[str]] = {}
+    missing_details_by_level: dict[str, list[dict[str, Any]]] = {}
     for level in ("light", "standard", "strong"):
         missing = [field for field in MATURITY_LEVELS[level]["requires"] if not facts.get(field)]
         missing_by_level[level] = missing
+        field_rows = MATURITY_REQUIRED_FIELDS.get(level, [])
+        missing_details_by_level[level] = [
+            row
+            for row in field_rows
+            if row["id"] in missing
+        ]
         if not missing:
             achieved.append(level)
             facts[level] = True
@@ -1051,7 +1164,9 @@ def maturity_status(
         "achieved": achieved,
         "next": next_level,
         "levels": MATURITY_LEVELS,
+        "required_fields": MATURITY_REQUIRED_FIELDS,
         "missing_by_level": missing_by_level,
+        "missing_details_by_level": missing_details_by_level,
     }
 
 

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-adoption-maturity-upgrade-automation.md",
+    "docs/evidence/validations/validation-adoption-maturity-required-fields.md",
     "docs/evidence/validations/validation-github-profile-binding-orchestration.md",
     "docs/evidence/validations/validation-github-profile-drift-reconciliation.md",
     "docs/evidence/validations/validation-github-profile-graphql-budget-guard.md",
@@ -832,6 +833,25 @@ def require_governance_control_plane(
         strong_requires = levels.get("strong", {}).get("requires") if isinstance(levels, dict) and isinstance(levels.get("strong"), dict) else None
         if not isinstance(strong_requires, list) or "github_controlled_merge" not in strong_requires:
             failures.append(Failure(category, f"{context}.maturity strong level must require GitHub controlled merge"))
+        required_fields = maturity.get("required_fields")
+        if not isinstance(required_fields, dict) or set(required_fields) != {"light", "standard", "strong"}:
+            failures.append(Failure(category, f"{context}.maturity required_fields must define light, standard, and strong"))
+        else:
+            for level, rows in required_fields.items():
+                if not isinstance(rows, list) or not rows:
+                    failures.append(Failure(category, f"{context}.maturity required_fields.{level} must be a non-empty list"))
+                    continue
+                for row in rows:
+                    if not isinstance(row, dict):
+                        failures.append(Failure(category, f"{context}.maturity required_fields.{level} entries must be objects"))
+                        continue
+                    if row.get("layer") not in {"core", "github-profile", "repo-owned-residue"}:
+                        failures.append(Failure(category, f"{context}.maturity required_fields.{level} layer must be stable"))
+                    if not isinstance(row.get("recommended_action"), str) or not row.get("recommended_action"):
+                        failures.append(Failure(category, f"{context}.maturity required_fields.{level} entries must include recommended_action"))
+        missing_details = maturity.get("missing_details_by_level")
+        if not isinstance(missing_details, dict) or set(missing_details) != {"light", "standard", "strong"}:
+            failures.append(Failure(category, f"{context}.maturity missing_details_by_level must define light, standard, and strong"))
 
 
 def require_locator_entry(
@@ -1364,6 +1384,8 @@ def require_governance_upgrade_payload(
             failures.append(Failure(category, f"{context} action owner must stay within the stable set"))
         if action.get("status") not in {"planned", "present"}:
             failures.append(Failure(category, f"{context} action status must be planned/present"))
+        if action.get("action") == "satisfy_missing_input" and not isinstance(action.get("recommended_action"), str):
+            failures.append(Failure(category, f"{context} missing-input actions must include recommended_action"))
 
 
 def require_review_record_contract(

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

@@ -3553,11 +3553,17 @@ def governance_profile_payload(target_root: Path, operation: str) -> dict[str, A
     current = maturity.get("current")
     next_level = maturity.get("next")
     missing_by_level = maturity.get("missing_by_level")
+    missing_details_by_level = maturity.get("missing_details_by_level")
     missing_inputs: list[Any] = []
+    missing_details: list[Any] = []
     if operation == "upgrade-plan" and isinstance(next_level, str) and isinstance(missing_by_level, dict):
         raw_missing = missing_by_level.get(next_level, [])
         if isinstance(raw_missing, list):
             missing_inputs = raw_missing
+        if isinstance(missing_details_by_level, dict):
+            raw_details = missing_details_by_level.get(next_level, [])
+            if isinstance(raw_details, list):
+                missing_details = raw_details
     result = "pass" if not missing_inputs else "block"
     summary = (
         f"governance profile is already at `{current}` maturity."
@@ -3570,6 +3576,8 @@ def governance_profile_payload(target_root: Path, operation: str) -> dict[str, A
         "result": result,
         "summary": summary,
         "missing_inputs": missing_inputs,
+        "missing_details": missing_details,
+        "recommended_action": "run governance-profile upgrade --dry-run" if result == "block" else None,
         "fallback_to": None if result == "pass" else "adoption",
         "maturity": maturity,
         "governance_control_plane": control_plane,
@@ -3617,7 +3625,9 @@ UPGRADE_SCAFFOLD: dict[str, dict[str, str]] = {
 
 def governance_upgrade_actions(target_root: Path, target_level: str, maturity: dict[str, Any]) -> list[dict[str, Any]]:
     missing_by_level = maturity.get("missing_by_level")
+    missing_details_by_level = maturity.get("missing_details_by_level")
     missing = missing_by_level.get(target_level, []) if isinstance(missing_by_level, dict) else []
+    missing_details = missing_details_by_level.get(target_level, []) if isinstance(missing_details_by_level, dict) else []
     actions: list[dict[str, Any]] = []
     for relative, content in UPGRADE_SCAFFOLD.items():
         path = target_root / relative
@@ -3633,12 +3643,19 @@ def governance_upgrade_actions(target_root: Path, target_level: str, maturity: d
             }
         )
     for item in missing if isinstance(missing, list) else []:
+        detail = next((row for row in missing_details if isinstance(row, dict) and row.get("id") == item), {})
         actions.append(
             {
                 "action": "satisfy_missing_input",
                 "id": item,
-                "owner": "loom-owned" if str(item) in {"repo_interface", "repo_interop"} else "profile",
+                "owner": (
+                    "loom-owned"
+                    if str(item) in {"repo_interface", "repo_interop"}
+                    else "profile"
+                ),
                 "status": "planned",
+                "layer": detail.get("layer"),
+                "recommended_action": detail.get("recommended_action"),
                 "reason": f"`{target_level}` maturity currently reports this missing input.",
             }
         )

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

@@ -146,6 +146,112 @@ MATURITY_LEVELS = {
         "summary": "Host-backed binding, reconciliation, controlled merge, and closeout gates are available.",
     },
 }
+MATURITY_REQUIRED_FIELDS = {
+    "light": [
+        {
+            "id": "work_item",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "run loom-init or restore the Work Item carrier",
+        },
+        {
+            "id": "recovery",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "restore the recovery carrier",
+        },
+        {
+            "id": "status_surface",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "restore the status surface carrier",
+        },
+        {
+            "id": "review",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "restore the review carrier",
+        },
+    ],
+    "standard": [
+        {
+            "id": "fr_work_item_layer",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "profile",
+            "recommended_action": "declare the FR -> Work Item split through the GitHub profile upgrade path",
+        },
+        {
+            "id": "spec_path",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "install formal spec scaffold",
+        },
+        {
+            "id": "plan_path",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "install execution plan scaffold",
+        },
+        {
+            "id": "spec_gate",
+            "layer": "core",
+            "required": True,
+            "defaulting": "generated",
+            "recommended_action": "record or restore the spec review gate",
+        },
+        {
+            "id": "status_control_plane",
+            "layer": "core",
+            "required": True,
+            "defaulting": "builtin",
+            "recommended_action": "run loom_status or loom_check to rebuild the status control plane",
+        },
+        {
+            "id": "basic_host_binding",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "profile",
+            "recommended_action": "run governance-profile binding and repair missing host bindings",
+        },
+        {
+            "id": "closeout_reconciliation_read",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "profile",
+            "recommended_action": "install repo interop so closeout can consume reconciliation",
+        },
+    ],
+    "strong": [
+        {
+            "id": "repo_interface",
+            "layer": "repo-owned-residue",
+            "required": True,
+            "defaulting": "scaffold",
+            "recommended_action": "install or repair the repo companion interface",
+        },
+        {
+            "id": "repo_interop",
+            "layer": "repo-owned-residue",
+            "required": True,
+            "defaulting": "scaffold",
+            "recommended_action": "install or repair the repo interop contract",
+        },
+        {
+            "id": "github_controlled_merge",
+            "layer": "github-profile",
+            "required": True,
+            "defaulting": "host",
+            "recommended_action": "enable controlled merge binding and required host gates",
+        },
+    ],
+}
 
 
 def run_process(args: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
@@ -1033,9 +1139,16 @@ def maturity_status(
     }
     achieved: list[str] = []
     missing_by_level: dict[str, list[str]] = {}
+    missing_details_by_level: dict[str, list[dict[str, Any]]] = {}
     for level in ("light", "standard", "strong"):
         missing = [field for field in MATURITY_LEVELS[level]["requires"] if not facts.get(field)]
         missing_by_level[level] = missing
+        field_rows = MATURITY_REQUIRED_FIELDS.get(level, [])
+        missing_details_by_level[level] = [
+            row
+            for row in field_rows
+            if row["id"] in missing
+        ]
         if not missing:
             achieved.append(level)
             facts[level] = True
@@ -1051,7 +1164,9 @@ def maturity_status(
         "achieved": achieved,
         "next": next_level,
         "levels": MATURITY_LEVELS,
+        "required_fields": MATURITY_REQUIRED_FIELDS,
         "missing_by_level": missing_by_level,
+        "missing_details_by_level": missing_details_by_level,
     }