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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mc-and-his-agents/loom-installer",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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": "3e2a33cf1cb7e519d321cb2617b874e285815c5b",
+  "source_commit": "c3f5933d41b009b1e0537356221c3bcd7fd910be",
   "source_ref": "main",
-  "built_at": "2026-04-25T13:01:36+08:00",
+  "built_at": "2026-04-25T13:23:16+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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "plugin/loom/skills/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-adopt/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-handoff/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-init/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-merge-ready/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-pre-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-resume/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-retire/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "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": 265994,
-      "sha256": "77334371c586c5e7247e6b781758cbf656594d4d5b8cff33f16b967b43f7811c"
+      "bytes": 269850,
+      "sha256": "15eecced57199f79c76774b2a629cae291c610d30b64b29a31ef60f4bad65ec7"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_flow.py",
-      "bytes": 279330,
-      "sha256": "ad6d6376a665cdfcd9de2316957e8f36e1ec087de59f29cebe6a6496ac0a555e"
+      "bytes": 287204,
+      "sha256": "d33bde08ceeafa70ddad41ba1c6f8373e0366da08a9b17484ce0ad3683f83960"
     },
     {
       "path": "skills/loom-spec-review/.loom-runtime/shared/scripts/loom_init.py",

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

@@ -93,8 +93,10 @@ CORE_DOCS = (
     "docs/evidence/extraction-ledger.md",
     "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-github-profile-binding-orchestration.md",
     "docs/evidence/validations/validation-github-profile-drift-reconciliation.md",
+    "docs/evidence/validations/validation-github-profile-graphql-budget-guard.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",
@@ -273,6 +275,8 @@ def iter_markdown_files(root: Path) -> list[Path]:
         relative = path.relative_to(root).as_posix()
         if any(relative == part or relative.startswith(f"{part}/") for part in skipped_parts):
             continue
+        if any(part.startswith(".payload-build-") for part in path.relative_to(root).parts):
+            continue
         if relative.startswith("packages/loom-installer/payload/"):
             continue
         results.append(path)
@@ -1326,6 +1330,42 @@ def require_github_binding_payload(
             failures.append(Failure(category, f"{context}.binding findings must fallback to `github-profile-binding`"))
 
 
+def require_governance_upgrade_payload(
+    failures: list[Failure],
+    *,
+    category: str,
+    context: str,
+    payload: object,
+) -> None:
+    if not isinstance(payload, dict):
+        failures.append(Failure(category, f"{context} must be an object"))
+        return
+    if payload.get("command") != "governance-profile":
+        failures.append(Failure(category, f"{context} must report `command: governance-profile`"))
+    if payload.get("operation") != "upgrade":
+        failures.append(Failure(category, f"{context} must report `operation: upgrade`"))
+    if payload.get("schema_version") != "loom-governance-upgrade/v1":
+        failures.append(Failure(category, f"{context} schema_version must be `loom-governance-upgrade/v1`"))
+    if payload.get("result") not in {"pass", "block"}:
+        failures.append(Failure(category, f"{context} result must be pass/block"))
+    if payload.get("target_maturity") not in {"standard", "strong"}:
+        failures.append(Failure(category, f"{context} target_maturity must be standard/strong"))
+    if not isinstance(payload.get("dry_run"), bool):
+        failures.append(Failure(category, f"{context} dry_run must be boolean"))
+    actions = payload.get("actions")
+    if not isinstance(actions, list) or not actions:
+        failures.append(Failure(category, f"{context} must include non-empty actions"))
+        return
+    for action in actions:
+        if not isinstance(action, dict):
+            failures.append(Failure(category, f"{context} actions must be objects"))
+            continue
+        if action.get("owner") not in {"loom-owned", "repo-owned", "profile"}:
+            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"))
+
+
 def require_review_record_contract(
     failures: list[Failure],
     *,
@@ -2312,6 +2352,21 @@ def check_daily_execution_cli(root: Path) -> list[Failure]:
             ["python3", "tools/loom_flow.py", "governance-profile", "upgrade-plan", "--target", "examples/new-project"],
             {"pass", "block"},
         ),
+        (
+            "governance-profile-upgrade",
+            [
+                "python3",
+                "tools/loom_flow.py",
+                "governance-profile",
+                "upgrade",
+                "--target",
+                "examples/new-project",
+                "--to",
+                "standard",
+                "--dry-run",
+            ],
+            {"pass"},
+        ),
         (
             "governance-profile-binding",
             ["python3", "tools/loom_flow.py", "governance-profile", "binding", "--target", "."],
@@ -2571,6 +2626,13 @@ def check_daily_execution_cli(root: Path) -> list[Failure]:
                 context="`governance-profile binding`",
                 payload=payload,
             )
+        if label == "governance-profile-upgrade":
+            require_governance_upgrade_payload(
+                failures,
+                category="daily-execution-cli",
+                context="`governance-profile upgrade`",
+                payload=payload,
+            )
         if label == "flow-pre-review":
             require_runtime_state_payload(
                 failures,
@@ -5559,6 +5621,31 @@ def check_generated_artifacts_untracked(root: Path) -> list[Failure]:
     ]
 
 
+def check_github_cli_budget(root: Path) -> list[Failure]:
+    failures: list[Failure] = []
+    forbidden = tuple(f"gh {kind} view" for kind in ("repo", "issue", "pr"))
+    search_roots = [root / "skills/shared/scripts", root / "tools"]
+    for search_root in search_roots:
+        if not search_root.exists():
+            continue
+        for path in search_root.rglob("*.py"):
+            if path.name == "loom_check.py":
+                continue
+            try:
+                text = path.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            for needle in forbidden:
+                if needle in text:
+                    failures.append(
+                        Failure(
+                            "github-api-budget",
+                            f"`{needle}` must not be used in high-frequency implementation path `{path.relative_to(root)}`",
+                        )
+                    )
+    return failures
+
+
 def is_within(path: Path, root: Path) -> bool:
     try:
         path.relative_to(root)
@@ -5596,6 +5683,7 @@ def collect_failures(root: Path) -> list[Failure]:
     failures.extend(check_repo_interop_contracts(root))
     failures.extend(check_node_installer(root))
     failures.extend(check_generated_artifacts_untracked(root))
+    failures.extend(check_github_cli_budget(root))
     failures.extend(check_markdown_links(root))
     return failures
 

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

@@ -312,8 +312,12 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
         "governance-profile",
         help="Read Loom governance maturity and upgrade requirements",
     )
-    governance_profile.add_argument("operation", choices=("status", "upgrade-plan", "binding"))
+    governance_profile.add_argument("operation", choices=("status", "upgrade-plan", "upgrade", "binding"))
     governance_profile.add_argument("--target", required=True, help="Target repository root")
+    governance_profile.add_argument("--to", choices=("standard", "strong"), help="Target maturity for governance-profile upgrade")
+    governance_profile.add_argument("--dry-run", action="store_true", default=True, help="Preview upgrade actions without writing files; this is the default")
+    governance_profile.add_argument("--apply", dest="dry_run", action="store_false", help="Apply Loom-owned scaffold writes")
+    governance_profile.add_argument("--force", action="store_true", help="Allow replacement of existing Loom-owned scaffold files during upgrade apply")
     governance_profile.add_argument("--owner", help="GitHub owner; auto-detected from origin when omitted")
     governance_profile.add_argument("--repo", dest="repo_name", help="GitHub repository name; auto-detected from origin when omitted")
     governance_profile.add_argument("--phase", type=int, help="GitHub Phase issue number")
@@ -322,7 +326,6 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
     governance_profile.add_argument("--pr", type=int, help="GitHub implementation PR number")
     governance_profile.add_argument("--branch", help="GitHub branch name bound to the work item")
     governance_profile.add_argument("--sync", action="store_true", help="Preview host binding repairs; writes are intentionally disabled in this phase")
-    governance_profile.add_argument("--dry-run", action="store_true", help="Preview binding sync actions without changing GitHub state")
 
     flow = subparsers.add_parser("flow", help="Run a bundled high-frequency Loom flow")
     flow.add_argument("operation", choices=("pre-review", "review", "spec-review", "resume", "handoff", "merge-ready"))
@@ -926,6 +929,21 @@ def gh_graphql(root: Path, query: str, variables: dict[str, Any]) -> tuple[dict[
     return data, []
 
 
+def graphql_budget_guard(scope: str, errors: list[str] | None = None) -> dict[str, Any]:
+    return {
+        "graphql_only": True,
+        "budget_scope": scope,
+        "status": "unavailable" if errors else "guarded",
+        "errors": list(errors or []),
+        "fallback_to": "manual-reconciliation" if errors else None,
+        "recommended_action": (
+            "Retry this GraphQL-only host read with explicit operator intent, or continue with REST-backed issue/PR evidence when ProjectV2/native sub-issue data is not required."
+            if errors
+            else "Use this GraphQL-only host read sparingly; high-frequency repo, issue, and PR reads must stay on REST."
+        ),
+    }
+
+
 def git_dirty_entries(root: Path) -> list[dict[str, str]]:
     result = run_git(root, ["status", "--porcelain=v1"])
     if result is None or result.returncode != 0:
@@ -3558,6 +3576,141 @@ def governance_profile_payload(target_root: Path, operation: str) -> dict[str, A
     }
 
 
+UPGRADE_SCAFFOLD: dict[str, dict[str, str]] = {
+    ".loom/companion/manifest.json": json.dumps(
+        {
+            "schema_version": "loom-repo-companion-manifest/v1",
+            "companion_entry": ".loom/companion/AGENTS.md",
+            "repo_interface": ".loom/companion/repo-interface.json",
+        },
+        ensure_ascii=False,
+        indent=2,
+    )
+    + "\n",
+    ".loom/companion/repo-interface.json": json.dumps(
+        {
+            "schema_version": "loom-repo-interface/v2",
+            "companion_entry": ".loom/companion/AGENTS.md",
+            "repo_specific_requirements": {"review": [], "merge_ready": [], "closeout": []},
+            "specialized_gates": [],
+            "metadata_contract": {"fields": []},
+            "context_schema": {"fields": []},
+        },
+        ensure_ascii=False,
+        indent=2,
+    )
+    + "\n",
+    ".loom/companion/interop.json": json.dumps(
+        {
+            "schema_version": "loom-repo-interop/v1",
+            "host_adapters": [],
+            "repo_native_carriers": [],
+            "shadow_surfaces": {},
+        },
+        ensure_ascii=False,
+        indent=2,
+    )
+    + "\n",
+    ".loom/companion/AGENTS.md": "# Loom Repo Companion\n\n本文件承接 repo-local governance residue；Loom core 与 GitHub profile 规则仍以上游合同为准。\n",
+}
+
+
+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 = missing_by_level.get(target_level, []) if isinstance(missing_by_level, dict) else []
+    actions: list[dict[str, Any]] = []
+    for relative, content in UPGRADE_SCAFFOLD.items():
+        path = target_root / relative
+        owner = "loom-owned" if relative.startswith(".loom/") else "repo-owned"
+        actions.append(
+            {
+                "action": "write_scaffold" if not path.exists() else "keep_existing",
+                "path": relative,
+                "owner": owner,
+                "status": "present" if path.exists() else "planned",
+                "reason": "required by governance profile upgrade path",
+                "bytes": len(content.encode("utf-8")),
+            }
+        )
+    for item in missing if isinstance(missing, list) else []:
+        actions.append(
+            {
+                "action": "satisfy_missing_input",
+                "id": item,
+                "owner": "loom-owned" if str(item) in {"repo_interface", "repo_interop"} else "profile",
+                "status": "planned",
+                "reason": f"`{target_level}` maturity currently reports this missing input.",
+            }
+        )
+    return actions
+
+
+def governance_profile_upgrade_payload(
+    *,
+    target_root: Path,
+    target_level: str | None,
+    dry_run: bool,
+    force: bool,
+) -> dict[str, Any]:
+    if target_level is None:
+        return {
+            "command": "governance-profile",
+            "operation": "upgrade",
+            "result": "block",
+            "summary": "governance profile upgrade requires `--to standard` or `--to strong`.",
+            "missing_inputs": ["to"],
+            "fallback_to": "adoption",
+        }
+    base = governance_profile_payload(target_root, "upgrade-plan")
+    maturity = base.get("maturity") if isinstance(base.get("maturity"), dict) else {}
+    actions = governance_upgrade_actions(target_root, target_level, maturity if isinstance(maturity, dict) else {})
+    blockers: list[str] = []
+    written_files: list[str] = []
+    if not dry_run:
+        for action in actions:
+            if action.get("action") != "write_scaffold":
+                continue
+            relative = action.get("path")
+            if not isinstance(relative, str):
+                continue
+            if action.get("owner") != "loom-owned":
+                blockers.append(f"{relative} is repo-owned")
+                continue
+            path = target_root / relative
+            if path.exists() and not force:
+                blockers.append(f"{relative} already exists; use --force to replace Loom-owned scaffold")
+                continue
+            content = UPGRADE_SCAFFOLD.get(relative)
+            if content is None:
+                blockers.append(f"{relative} has no scaffold content")
+                continue
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+            written_files.append(relative)
+    result = "block" if blockers else "pass"
+    return {
+        "command": "governance-profile",
+        "operation": "upgrade",
+        "schema_version": "loom-governance-upgrade/v1",
+        "result": result,
+        "summary": (
+            f"governance profile upgrade toward `{target_level}` produced a dry-run action plan."
+            if dry_run and result == "pass"
+            else f"governance profile upgrade toward `{target_level}` applied Loom-owned scaffold writes."
+            if result == "pass"
+            else f"governance profile upgrade toward `{target_level}` is blocked by unsafe writes."
+        ),
+        "missing_inputs": blockers,
+        "fallback_to": None if result == "pass" else "adoption",
+        "target_maturity": target_level,
+        "dry_run": dry_run,
+        "force": force,
+        "actions": actions,
+        "written_files": written_files,
+        "maturity": maturity,
+    }
+
+
 def issue_binding_entry(role: str, number: int | None, payload: dict[str, Any] | None, errors: list[str]) -> dict[str, Any]:
     status = "present" if payload is not None else "missing"
     if errors:
@@ -3785,6 +3938,15 @@ def github_binding_payload(
 
 def handle_governance_profile(args: argparse.Namespace) -> int:
     target_root = Path(args.target).expanduser().resolve()
+    if args.operation == "upgrade":
+        return emit(
+            governance_profile_upgrade_payload(
+                target_root=target_root,
+                target_level=args.to,
+                dry_run=args.dry_run,
+                force=args.force,
+            )
+        )
     if args.operation == "binding":
         return emit(
             github_binding_payload(
@@ -3946,6 +4108,7 @@ query($id: ID!) {
             "id": entry.get("id"),
             "content": {"number": None, "type": "Issue"},
             "status": status_name,
+            "budget_guard": graphql_budget_guard("project_v2_item_field_values"),
         }, []
     return None, []
 
@@ -4022,6 +4185,7 @@ query($owner:String!, $name:String!, $number:Int!) {
     issue = repository.get("issue")
     if not isinstance(issue, dict):
         return None, [f"issue #{issue_number} is missing from GraphQL payload"]
+    issue["budget_guard"] = graphql_budget_guard("native_parent_sub_issue_tree")
     return issue, []
 
 
@@ -4131,6 +4295,7 @@ def reconciliation_audit_payload(
                     "status": "unavailable",
                     "reason": "GraphQL-only parent/sub-issue tree could not be read.",
                     "errors": issue_tree_errors,
+                    "budget_guard": graphql_budget_guard("native_parent_sub_issue_tree", issue_tree_errors),
                 }
             elif issue_tree is not None:
                 issue_payload = {**issue_payload, **issue_tree}
@@ -4261,16 +4426,21 @@ def reconciliation_audit_payload(
                     "status": "unavailable",
                     "reason": "GitHub ProjectV2 CLI owner resolution is unavailable in this environment.",
                     "errors": project_errors,
+                    "budget_guard": graphql_budget_guard("project_v2_status_surface", project_errors),
                 }
             else:
                 missing_inputs.extend(f"project: {message}" for message in project_errors)
         else:
             items = project_context["items"]
             issue_item = find_project_item(items, issue_number, "issue") if issue_number is not None else None
+            issue_item_budget_guard: dict[str, Any] | None = None
             if issue_item is None and issue_id is not None and issue_number is not None:
                 issue_item, issue_item_errors = project_item_for_issue(target_root, issue_id, project_number)
                 if issue_item_errors:
-                    missing_inputs.extend(f"project: {message}" for message in issue_item_errors)
+                    issue_item_budget_guard = graphql_budget_guard(
+                        "project_v2_issue_item_lookup",
+                        issue_item_errors,
+                    )
             pr_item = find_project_item(items, pr_number, "pr") if pr_number is not None else None
             project_payload = {
                 "number": project_number,
@@ -4280,6 +4450,8 @@ def reconciliation_audit_payload(
                 "issue_item": issue_item,
                 "pr_item": pr_item,
             }
+            if issue_item_budget_guard is not None:
+                project_payload["issue_item_budget_guard"] = issue_item_budget_guard
 
             if issue_number is not None:
                 expected_done = issue_payload is not None and (issue_payload.get("state") == "CLOSED" or merged_issue_open)
@@ -4872,16 +5044,21 @@ def closeout_payload(
                     "status": "unavailable",
                     "reason": "GitHub ProjectV2 CLI owner resolution is unavailable in this environment.",
                     "errors": project_errors,
+                    "budget_guard": graphql_budget_guard("project_v2_status_surface", project_errors),
                 }
             else:
                 missing_inputs.extend(f"project: {message}" for message in project_errors)
         else:
             items = project_context["items"]
             issue_item = find_project_item(items, issue_number, "issue") if issue_number is not None else None
+            issue_item_budget_guard: dict[str, Any] | None = None
             if issue_item is None and issue_id is not None and issue_number is not None:
                 issue_item, issue_item_errors = project_item_for_issue(target_root, issue_id, project_number)
                 if issue_item_errors:
-                    missing_inputs.extend(f"project: {message}" for message in issue_item_errors)
+                    issue_item_budget_guard = graphql_budget_guard(
+                        "project_v2_issue_item_lookup",
+                        issue_item_errors,
+                    )
             pr_item = find_project_item(items, pr_number, "pr") if pr_number is not None else None
             if issue_number is not None and issue_item is None:
                 missing_inputs.append("issue is missing from project")
@@ -4893,6 +5070,8 @@ def closeout_payload(
                 "issue_item": issue_item,
                 "pr_item": pr_item,
             }
+            if issue_item_budget_guard is not None:
+                project_payload["issue_item_budget_guard"] = issue_item_budget_guard
             for label, item in (("issue", issue_item), ("pr", pr_item)):
                 if item is None:
                     continue