feat: make treasury the governed budget control plane #1905

docs/documentation-manifest.json

@@ -153,7 +153,7 @@
       "name": "Agent Cost Telemetry Contracts",
       "category": "supporting",
       "status": "reference",
-      "description": "Checked-in invoice-turn, per-turn, rollup, operator labor, and blended autonomy cost telemetry contracts, fixtures, helper CLIs, and focused tests used to anchor spend reporting in repo-visible evidence.",
+      "description": "Checked-in invoice-turn, per-turn, rollup, treasury control-plane, operator labor, and blended autonomy cost telemetry contracts, fixtures, helper CLIs, and focused tests used to anchor spend reporting in repo-visible evidence.",
       "files": [
         "docs/knowledgebase/Agent-Cost-Telemetry-Surfaces.md",
         "docs/schemas/agent-cost-private-invoice-metadata-v1.schema.json",
@@ -165,6 +165,8 @@
         "docs/schemas/github-comment-budget-hook-report-v1.schema.json",
         "docs/schemas/operator-cost-profile-v1.schema.json",
         "docs/schemas/pr-spend-projection-v1.schema.json",
+        "docs/schemas/treasury-control-plane-policy-v2.schema.json",
+        "docs/schemas/treasury-control-plane-report-v2.schema.json",
         "tools/priority/__fixtures__/agent-cost-rollup/live-turn-estimated.json",
         "tools/priority/__fixtures__/agent-cost-rollup/background-turn-exact.json",
         "tools/priority/__fixtures__/agent-cost-rollup/invoice-turn-baseline.json",
@@ -173,13 +175,15 @@
         "tools/priority/__fixtures__/agent-cost-rollup/private-invoice-metadata-sample.json",
         "tools/policy/github-comment-budget-hook.json",
         "tools/policy/operator-cost-profile.json",
+        "tools/policy/treasury-control-plane.json",
         "tools/priority/agent-cost-invoice-normalize.mjs",
         "tools/priority/agent-cost-invoice-turn.mjs",
         "tools/priority/agent-cost-turn.mjs",
         "tools/priority/agent-cost-rollup.mjs",
         "tools/priority/average-issue-cost-scorecard.mjs",
         "tools/priority/github-comment-budget-hook.mjs",
         "tools/priority/pr-spend-projection.mjs",
+        "tools/priority/treasury-control-plane.mjs",
         "tools/priority/__tests__/github-comment-budget-hook.test.mjs",
         "tools/priority/__tests__/github-comment-budget-hook-schema.test.mjs",
         "tools/priority/__tests__/average-issue-cost-scorecard.test.mjs",
@@ -192,7 +196,9 @@
         "tools/priority/__tests__/operator-cost-profile-schema.test.mjs",
         "tools/priority/__tests__/pr-spend-projection.test.mjs",
         "tools/priority/__tests__/pr-spend-projection-schema.test.mjs",
-        "tools/priority/__tests__/agent-cost-telemetry-surfaces.test.mjs"
+        "tools/priority/__tests__/agent-cost-telemetry-surfaces.test.mjs",
+        "tools/priority/__tests__/treasury-control-plane.test.mjs",
+        "tools/priority/__tests__/treasury-control-plane-schema.test.mjs"
       ]
     },
     {

docs/knowledgebase/Agent-Cost-Telemetry-Surfaces.md

@@ -265,6 +265,33 @@ Automation-authored GitHub comments now have a checked-in budget attestation
 surface so cost state survives session compaction and comment history remains a
 durable breadcrumb for later agents.
 
+## Treasury Control Plane
+
+The budget hook is now a projection layer, not the authority.
+
+The authoritative spend-governance surface is the treasury control plane:
+
+- schema: `docs/schemas/treasury-control-plane-policy-v2.schema.json`
+- schema: `docs/schemas/treasury-control-plane-report-v2.schema.json`
+- policy: `tools/policy/treasury-control-plane.json`
+- helper: `tools/priority/treasury-control-plane.mjs`
+- npm surface: `priority:cost:treasury`
+
+This surface separates:
+
+- whole-account remaining USD estimate
+- protected reserve USD
+- operational headroom
+- safe spendable lower bound
+- possible spendable upper bound
+- operator budget observed upper bound
+- operator budget spendable status
+- premium/background/non-essential execution controls
+
+The treasury control plane is what governor, portfolio, and handoff surfaces
+should read when deciding whether work is allowed. The GitHub comment hook
+exists to persist that decision visibly on issue and PR history.
+
 - schema: `docs/schemas/github-comment-budget-hook-policy-v1.schema.json`
 - schema: `docs/schemas/github-comment-budget-hook-report-v1.schema.json`
 - policy: `tools/policy/github-comment-budget-hook.json`

docs/schemas/autonomous-governor-portfolio-summary-report-v1.schema.json

@@ -52,6 +52,7 @@
         "queueHandoffNextWakeCondition",
         "queueHandoffPrUrl",
         "queueAuthoritySource",
+        "treasury",
         "executionTopology",
         "executionBundleStatus",
         "executionBundlePlaneBinding",
@@ -71,6 +72,7 @@
         "queueHandoffNextWakeCondition": { "type": ["string", "null"] },
         "queueHandoffPrUrl": { "type": ["string", "null"] },
         "queueAuthoritySource": { "type": ["string", "null"] },
+        "treasury": { "$ref": "#/$defs/treasury" },
         "executionTopology": { "$ref": "#/$defs/executionTopology" },
         "executionBundleStatus": { "type": ["string", "null"] },
         "executionBundlePlaneBinding": { "type": ["string", "null"] },
@@ -280,6 +282,27 @@
         "executionBundlePremiumSaganMode",
         "executionBundleReciprocalLinkReady",
         "executionBundleEffectiveBillableRateUsdPerHour",
+        "treasuryStatus",
+        "treasuryConfidence",
+        "treasurySpendPolicyState",
+        "treasuryBudgetPressureState",
+        "treasuryProtectedReserveUsd",
+        "treasuryAccountRemainingUsdEstimate",
+        "treasuryOperationalHeadroomUsd",
+        "treasurySafeSpendableUsd",
+        "treasuryPossibleSpendableUpperBoundUsd",
+        "treasuryOperatorBudgetObservedRemainingUpperBoundUsd",
+        "treasuryOperatorBudgetObservedRemainingStatus",
+        "treasuryOperatorBudgetSpendableStatus",
+        "treasuryCoreDeliveryAllowed",
+        "treasuryQueueAuthorityAllowed",
+        "treasuryReleaseApplyAllowed",
+        "treasuryPremiumSaganAllowed",
+        "treasuryPremiumAuthorizationPromptRequired",
+        "treasuryPremiumAuthorizationFollowupEstimate",
+        "treasuryBackgroundFanoutAllowed",
+        "treasuryMaxBackgroundSubagents",
+        "treasuryNonEssentialWorkAllowed",
         "viHistoryDistributorDependencyStatus",
         "viHistoryDistributorDependencyTargetRepository",
         "viHistoryDistributorDependencyExternalBlocker",
@@ -327,6 +350,27 @@
         "executionBundlePremiumSaganMode": { "type": "boolean" },
         "executionBundleReciprocalLinkReady": { "type": "boolean" },
         "executionBundleEffectiveBillableRateUsdPerHour": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryStatus": { "type": "string", "enum": ["pass", "warn", "blocked", "missing"] },
+        "treasuryConfidence": { "type": "string", "enum": ["observed", "lower-bound-only", "conflicted", "blocked", "unknown"] },
+        "treasurySpendPolicyState": { "type": "string", "enum": ["healthy", "cautious-delivery", "core-delivery-only", "reserve-protected-only", "blocked"] },
+        "treasuryBudgetPressureState": { "type": "string", "enum": ["healthy", "cautious", "tight", "stop-nonessential-spend", "blocked"] },
+        "treasuryProtectedReserveUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryAccountRemainingUsdEstimate": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryOperationalHeadroomUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasurySafeSpendableUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryPossibleSpendableUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryOperatorBudgetObservedRemainingUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryOperatorBudgetObservedRemainingStatus": { "type": "string", "enum": ["observed", "upper-bound", "unknown"] },
+        "treasuryOperatorBudgetSpendableStatus": { "type": "string", "enum": ["observed", "unreconciled", "unknown"] },
+        "treasuryCoreDeliveryAllowed": { "type": "boolean" },
+        "treasuryQueueAuthorityAllowed": { "type": "boolean" },
+        "treasuryReleaseApplyAllowed": { "type": "boolean" },
+        "treasuryPremiumSaganAllowed": { "type": "boolean" },
+        "treasuryPremiumAuthorizationPromptRequired": { "type": "boolean" },
+        "treasuryPremiumAuthorizationFollowupEstimate": { "type": "integer", "minimum": 0 },
+        "treasuryBackgroundFanoutAllowed": { "type": "boolean" },
+        "treasuryMaxBackgroundSubagents": { "type": "integer", "minimum": 0 },
+        "treasuryNonEssentialWorkAllowed": { "type": "boolean" },
         "viHistoryDistributorDependencyStatus": { "type": "string", "enum": ["ready", "blocked", "unknown"] },
         "viHistoryDistributorDependencyTargetRepository": { "type": ["string", "null"] },
         "viHistoryDistributorDependencyExternalBlocker": { "type": ["string", "null"] },
@@ -345,6 +389,56 @@
     }
   },
   "$defs": {
+    "treasury": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "confidence",
+        "spendPolicyState",
+        "budgetPressureState",
+        "protectedReserveUsd",
+        "accountRemainingUsdEstimate",
+        "operationalHeadroomUsd",
+        "safeSpendableUsd",
+        "possibleSpendableUpperBoundUsd",
+        "operatorBudgetObservedRemainingUpperBoundUsd",
+        "operatorBudgetObservedRemainingStatus",
+        "operatorBudgetSpendableStatus",
+        "coreDeliveryAllowed",
+        "queueAuthorityAllowed",
+        "releaseApplyAllowed",
+        "premiumSaganAllowed",
+        "premiumAuthorizationPromptRequired",
+        "premiumAuthorizationFollowupEstimate",
+        "backgroundFanoutAllowed",
+        "maxBackgroundSubagents",
+        "nonEssentialWorkAllowed"
+      ],
+      "properties": {
+        "status": { "type": "string", "enum": ["pass", "warn", "blocked", "missing"] },
+        "confidence": { "type": "string", "enum": ["observed", "lower-bound-only", "conflicted", "blocked", "unknown"] },
+        "spendPolicyState": { "type": "string", "enum": ["healthy", "cautious-delivery", "core-delivery-only", "reserve-protected-only", "blocked"] },
+        "budgetPressureState": { "type": "string", "enum": ["healthy", "cautious", "tight", "stop-nonessential-spend", "blocked"] },
+        "protectedReserveUsd": { "type": ["number", "null"], "minimum": 0 },
+        "accountRemainingUsdEstimate": { "type": ["number", "null"], "minimum": 0 },
+        "operationalHeadroomUsd": { "type": ["number", "null"], "minimum": 0 },
+        "safeSpendableUsd": { "type": ["number", "null"], "minimum": 0 },
+        "possibleSpendableUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "operatorBudgetObservedRemainingUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "operatorBudgetObservedRemainingStatus": { "type": "string", "enum": ["observed", "upper-bound", "unknown"] },
+        "operatorBudgetSpendableStatus": { "type": "string", "enum": ["observed", "unreconciled", "unknown"] },
+        "coreDeliveryAllowed": { "type": "boolean" },
+        "queueAuthorityAllowed": { "type": "boolean" },
+        "releaseApplyAllowed": { "type": "boolean" },
+        "premiumSaganAllowed": { "type": "boolean" },
+        "premiumAuthorizationPromptRequired": { "type": "boolean" },
+        "premiumAuthorizationFollowupEstimate": { "type": "integer", "minimum": 0 },
+        "backgroundFanoutAllowed": { "type": "boolean" },
+        "maxBackgroundSubagents": { "type": "integer", "minimum": 0 },
+        "nonEssentialWorkAllowed": { "type": "boolean" }
+      }
+    },
     "executionBundle": {
       "type": "object",
       "additionalProperties": false,

docs/schemas/autonomous-governor-summary-report-v1.schema.json

@@ -38,7 +38,8 @@
         "wakeLifecyclePath",
         "wakeInvestmentAccountingPath",
         "deliveryRuntimeStatePath",
-        "releaseSigningReadinessPath"
+        "releaseSigningReadinessPath",
+        "treasuryControlPlanePath"
       ],
       "properties": {
         "queueEmptyReportPath": { "type": "string", "minLength": 1 },
@@ -47,7 +48,8 @@
         "wakeLifecyclePath": { "type": "string", "minLength": 1 },
         "wakeInvestmentAccountingPath": { "type": "string", "minLength": 1 },
         "deliveryRuntimeStatePath": { "type": "string", "minLength": 1 },
-        "releaseSigningReadinessPath": { "type": "string", "minLength": 1 }
+        "releaseSigningReadinessPath": { "type": "string", "minLength": 1 },
+        "treasuryControlPlanePath": { "type": "string", "minLength": 1 }
       }
     },
     "compare": {
@@ -57,6 +59,7 @@
         "queueState",
         "continuity",
         "monitoringMode",
+        "treasury",
         "releaseSigningReadiness",
         "deliveryRuntime",
         "queueAuthority"
@@ -65,6 +68,7 @@
         "queueState": { "$ref": "#/$defs/queueState" },
         "continuity": { "$ref": "#/$defs/continuity" },
         "monitoringMode": { "$ref": "#/$defs/monitoringMode" },
+        "treasury": { "$ref": "#/$defs/treasury" },
         "releaseSigningReadiness": { "$ref": "#/$defs/releaseSigningReadiness" },
         "deliveryRuntime": { "$ref": "#/$defs/deliveryRuntime" },
         "queueAuthority": { "$ref": "#/$defs/queueAuthority" }
@@ -313,6 +317,56 @@
         "netPaybackUsd": { "type": ["number", "null"] }
       }
     },
+    "treasury": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "confidence",
+        "spendPolicyState",
+        "budgetPressureState",
+        "protectedReserveUsd",
+        "accountRemainingUsdEstimate",
+        "operationalHeadroomUsd",
+        "safeSpendableUsd",
+        "possibleSpendableUpperBoundUsd",
+        "operatorBudgetObservedRemainingUpperBoundUsd",
+        "operatorBudgetObservedRemainingStatus",
+        "operatorBudgetSpendableStatus",
+        "coreDeliveryAllowed",
+        "queueAuthorityAllowed",
+        "releaseApplyAllowed",
+        "premiumSaganAllowed",
+        "premiumAuthorizationPromptRequired",
+        "premiumAuthorizationFollowupEstimate",
+        "backgroundFanoutAllowed",
+        "maxBackgroundSubagents",
+        "nonEssentialWorkAllowed"
+      ],
+      "properties": {
+        "status": { "type": "string", "enum": ["pass", "warn", "blocked", "missing"] },
+        "confidence": { "type": "string", "enum": ["observed", "lower-bound-only", "conflicted", "blocked", "unknown"] },
+        "spendPolicyState": { "type": "string", "enum": ["healthy", "cautious-delivery", "core-delivery-only", "reserve-protected-only", "blocked"] },
+        "budgetPressureState": { "type": "string", "enum": ["healthy", "cautious", "tight", "stop-nonessential-spend", "blocked"] },
+        "protectedReserveUsd": { "type": ["number", "null"], "minimum": 0 },
+        "accountRemainingUsdEstimate": { "type": ["number", "null"], "minimum": 0 },
+        "operationalHeadroomUsd": { "type": ["number", "null"], "minimum": 0 },
+        "safeSpendableUsd": { "type": ["number", "null"], "minimum": 0 },
+        "possibleSpendableUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "operatorBudgetObservedRemainingUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "operatorBudgetObservedRemainingStatus": { "type": "string", "enum": ["observed", "upper-bound", "unknown"] },
+        "operatorBudgetSpendableStatus": { "type": "string", "enum": ["observed", "unreconciled", "unknown"] },
+        "coreDeliveryAllowed": { "type": "boolean" },
+        "queueAuthorityAllowed": { "type": "boolean" },
+        "releaseApplyAllowed": { "type": "boolean" },
+        "premiumSaganAllowed": { "type": "boolean" },
+        "premiumAuthorizationPromptRequired": { "type": "boolean" },
+        "premiumAuthorizationFollowupEstimate": { "type": "integer", "minimum": 0 },
+        "backgroundFanoutAllowed": { "type": "boolean" },
+        "maxBackgroundSubagents": { "type": "integer", "minimum": 0 },
+        "nonEssentialWorkAllowed": { "type": "boolean" }
+      }
+    },
     "summary": {
       "type": "object",
       "additionalProperties": false,
@@ -353,6 +407,27 @@
         "executionBundlePremiumSaganMode",
         "executionBundleReciprocalLinkReady",
         "executionBundleEffectiveBillableRateUsdPerHour",
+        "treasuryStatus",
+        "treasuryConfidence",
+        "treasurySpendPolicyState",
+        "treasuryBudgetPressureState",
+        "treasuryProtectedReserveUsd",
+        "treasuryAccountRemainingUsdEstimate",
+        "treasuryOperationalHeadroomUsd",
+        "treasurySafeSpendableUsd",
+        "treasuryPossibleSpendableUpperBoundUsd",
+        "treasuryOperatorBudgetObservedRemainingUpperBoundUsd",
+        "treasuryOperatorBudgetObservedRemainingStatus",
+        "treasuryOperatorBudgetSpendableStatus",
+        "treasuryCoreDeliveryAllowed",
+        "treasuryQueueAuthorityAllowed",
+        "treasuryReleaseApplyAllowed",
+        "treasuryPremiumSaganAllowed",
+        "treasuryPremiumAuthorizationPromptRequired",
+        "treasuryPremiumAuthorizationFollowupEstimate",
+        "treasuryBackgroundFanoutAllowed",
+        "treasuryMaxBackgroundSubagents",
+        "treasuryNonEssentialWorkAllowed",
         "queueHandoffStatus",
         "queueHandoffNextWakeCondition",
         "queueHandoffPrUrl",
@@ -426,6 +501,27 @@
         "executionBundlePremiumSaganMode": { "type": "boolean" },
         "executionBundleReciprocalLinkReady": { "type": "boolean" },
         "executionBundleEffectiveBillableRateUsdPerHour": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryStatus": { "type": "string", "enum": ["pass", "warn", "blocked", "missing"] },
+        "treasuryConfidence": { "type": "string", "enum": ["observed", "lower-bound-only", "conflicted", "blocked", "unknown"] },
+        "treasurySpendPolicyState": { "type": "string", "enum": ["healthy", "cautious-delivery", "core-delivery-only", "reserve-protected-only", "blocked"] },
+        "treasuryBudgetPressureState": { "type": "string", "enum": ["healthy", "cautious", "tight", "stop-nonessential-spend", "blocked"] },
+        "treasuryProtectedReserveUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryAccountRemainingUsdEstimate": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryOperationalHeadroomUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasurySafeSpendableUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryPossibleSpendableUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryOperatorBudgetObservedRemainingUpperBoundUsd": { "type": ["number", "null"], "minimum": 0 },
+        "treasuryOperatorBudgetObservedRemainingStatus": { "type": "string", "enum": ["observed", "upper-bound", "unknown"] },
+        "treasuryOperatorBudgetSpendableStatus": { "type": "string", "enum": ["observed", "unreconciled", "unknown"] },
+        "treasuryCoreDeliveryAllowed": { "type": "boolean" },
+        "treasuryQueueAuthorityAllowed": { "type": "boolean" },
+        "treasuryReleaseApplyAllowed": { "type": "boolean" },
+        "treasuryPremiumSaganAllowed": { "type": "boolean" },
+        "treasuryPremiumAuthorizationPromptRequired": { "type": "boolean" },
+        "treasuryPremiumAuthorizationFollowupEstimate": { "type": "integer", "minimum": 0 },
+        "treasuryBackgroundFanoutAllowed": { "type": "boolean" },
+        "treasuryMaxBackgroundSubagents": { "type": "integer", "minimum": 0 },
+        "treasuryNonEssentialWorkAllowed": { "type": "boolean" },
         "queueHandoffStatus": {
           "type": "string",
           "enum": [