feat(agentic-engineering)!: require explicit spend enablement

.claude-plugin/marketplace.json

@@ -27,7 +27,7 @@
     {
       "name": "agentic-engineering",
       "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-      "version": "4.4.29",
+      "version": "5.0.0",
       "source": "./plugins/agentic-engineering"
     },
     {

.github/plugin/marketplace.json

@@ -27,7 +27,7 @@
     {
       "name": "agentic-engineering",
       "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-      "version": "4.4.29",
+      "version": "5.0.0",
       "source": "./plugins/agentic-engineering"
     },
     {

docs/adr/0007-explicit-spend-enablement.md

@@ -0,0 +1,36 @@
+# ADR 0007: Explicit spend enablement
+
+## Context
+
+The engineer's Spend contract describes deployment facts and authority boundaries. Treating the
+presence of those facts as activation makes a complete onboarding document enable cost work without
+a distinct maintainer choice. The shipped desired state needs an explicit disabled state that can
+be validated independently of contract completeness.
+
+## Decision
+
+The desired-state schema requires the boolean
+`spec.roles["agentic-engineer"].spendStewardshipEnabled`, shipped as `false`. Only the maintainer may
+opt in by setting literal `true`; a resolving Spend contract remains a separate prerequisite.
+Missing, malformed, or unreadable enablement disables spend analysis and decisions while ordinary
+operate and advance engineering continues.
+
+The consumer declares one full effective desired-state document in its Spend contract. If no
+effective document is declared, use the shipped disabled default. The engineer resolves that source and value once
+during preflight and keeps them fixed for the run. Consumers that retain an exact upstream mirror
+declare a separate full effective document through native configuration. The plugin defines no
+partial-override merge or search through arbitrary settings.
+
+Onboarding preserves the configured value and reports its source and unresolved prerequisites. Thin
+scheduler pointers refer to the same field and the engineer's canonical policy. A flag does not
+relax the private-channel, protected-outcomes, or money-moving boundaries.
+
+## Consequences
+
+Version 5 is a breaking desired-state change: version 4 documents must add the field and refresh
+their entrypoint digest and scheduler pointers. Existing spend deployments need explicit opt-in;
+contract presence and historical activity do not supply it. Consumer adoption follows the merged
+plugin revision, while runtime-managed caches remain the responsibility of native runtime controls.
+
+The manifest validator accepts both boolean states and rejects missing or malformed values. Tests
+also pin the actual shipped default and require both onboarding and dispatch to consume the field.

docs/resources.md

@@ -12,16 +12,18 @@ trust, cadence, memory, and maintainer-channel configuration. It also requires t
 unsupported native capabilities instead of silently weakening the deployment. The manifest carries
 separate thin schedule prompts for the Agentic Engineer and the Agent Improver; each resolves its
 cadence and deployment facts from the canonical consumer instructions. Spend stewardship has no
-schedule of its own — it runs inside the engineer's loop when the consumer declares a `Spend contract`
-section.
-Existing installations must complete **all three** migrations, in order, before their next scheduled
+schedule of its own. It runs inside the engineer's loop only after explicit maintainer opt-in through
+`spec.roles["agentic-engineer"].spendStewardshipEnabled` and a resolving `Spend contract`.
+Existing installations must complete **all four** migrations, in order, before their next scheduled
 run — the
 [version 2 checklist](../plugins/agentic-engineering/README.md#migrating-from-automated-ai-engineer)
 (plugin identity), **then** the
 [version 3 checklist](../plugins/agentic-engineering/README.md#migrating-to-version-3) (retire the
 `finops-engineer` schedule and adopt the `Spend contract` section), **then** the
 [version 4 checklist](../plugins/agentic-engineering/README.md#migrating-to-version-4)
-(the `automated-ai-engineer` → `agentic-engineer` entrypoint rename). Stopping early would resume
+(the `automated-ai-engineer` → `agentic-engineer` entrypoint rename), **then** the
+[version 5 checklist](../plugins/agentic-engineering/README.md#migrating-to-version-5)
+(explicit default-off spend enablement). Stopping early would resume
 unattended writes with the retired FinOps schedule still armed, or with a schedule pointing at an
 entrypoint that no longer resolves.
 
@@ -102,5 +104,6 @@ improves the engineer itself from measured evidence) — alongside its engineeri
 [ADR 0005](../docs/adr/0005-merge-spend-stewardship-into-the-engineer.md)). Same delivery rules; the
 consuming deployment must define the five contract sections (Portfolio map, Trust gate, Cadence,
 Memory, Maintainer channels) in its `AGENTS.md` — plus **Agent definition locations** and
-**Authority model** if it enables `agent-improver`, and **Spend contract** if it wants the engineer to
-steward spend (see the [plugin README](../plugins/agentic-engineering/README.md)).
+**Authority model** if it enables `agent-improver`, and **Spend contract** plus explicit maintainer
+opt-in if it wants the engineer to steward spend (see the
+[plugin README](../plugins/agentic-engineering/README.md)).

plugins/agentic-engineering/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering",
   "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-  "version": "4.4.29",
+  "version": "5.0.0",
   "author": {
     "name": "devantler-tech",
     "url": "https://github.com/devantler-tech"

plugins/agentic-engineering/README.md

@@ -18,6 +18,36 @@ separate FinOps role and schedule. See
 Version 4 renames that entrypoint from `automated-ai-engineer` to `agentic-engineer`. See
 [ADR 0006](../../docs/adr/0006-rename-agentic-engineer-entrypoint.md).
 
+Version 5 requires explicit, default-off spend enablement. See
+[ADR 0007](../../docs/adr/0007-explicit-spend-enablement.md).
+
+## Migrating to version 5
+
+The desired-state schema now requires the boolean
+`spec.roles["agentic-engineer"].spendStewardshipEnabled`. Start with `false`; the presence of a
+complete Spend contract does not opt a deployment in. Older documents fail validation, and the
+engineer treats missing or malformed enablement as disabled while continuing ordinary engineering.
+
+1. Refresh the complete desired-state document from the reviewed plugin revision, including its
+   entrypoint digest and scheduler pointers. Keep the shipped flag `false` unless the maintainer
+   explicitly enables spend stewardship.
+2. Declare the path to one full effective desired-state JSON document in the consumer's
+   `AGENTS.md` **Spend contract**. That document supplies the flag for every lane. If the consumer
+   keeps a byte-identical upstream mirror, retain it and declare a separate full effective document
+   through its native configuration; do not edit the mirror or invent a partial-override merge.
+3. Reconcile the native scheduler from the updated pointers and verify preflight reports the
+   effective document, boolean value, and any unresolved Spend contract prerequisites. Keep a
+   disabled deployment disabled during reconciliation.
+
+Without a declared document, preflight uses the shipped `false` default. A declared document that
+cannot be read or validated also disables spend and reports the gap. Resolve the document and flag
+once per run; never search unrelated settings for an enabling value or switch sources mid-run.
+
+Only the maintainer may set the flag to literal `true`. This permits spend analysis and decisions
+only when the Spend contract also resolves; it does not bypass the private decision channel,
+protected-outcomes floor, or authority boundaries. Setting it back to `false` disables the cost
+dimension on the next preflight. There is no additional spend schedule.
+
 ## Migrating to version 4
 
 Version 4 renames the primary engineer's agent entrypoint from `automated-ai-engineer` to
@@ -60,8 +90,8 @@ required before the next scheduled run:
    rather than silently deploying two writers over one concern.
 
 A consumer that keeps its FinOps definition as a separate agent is not broken by this release — but it
-is no longer the shape this plugin describes, and the engineer will not perform spend work until a
-`Spend contract` section resolves.
+is no longer the shape this plugin describes. Current spend enablement follows the explicit flag and
+resolving `Spend contract` described in [*Migrating to version 5*](#migrating-to-version-5).
 
 ## Migrating from `automated-ai-engineer`
 
@@ -82,9 +112,10 @@ complete the plugin-name change manually before the next scheduled run:
 3. Copy the [provider-neutral desired state](resources/provider-neutral.desired-state.json) into the
    consumer workspace and reconcile its native agents and schedules. Preserve the consumer's
    canonical `AGENTS.md`; do not copy its organization-specific facts into this plugin.
-4. Before re-enabling unattended writes, verify that the installed plugin reports version `4.0.0` or
-   later — the current major, so **[*Migrating to version 3*](#migrating-to-version-3) and
-   [*Migrating to version 4*](#migrating-to-version-4) must both be complete too**; a stop at `2.0.0`
+4. Before re-enabling unattended writes, verify that the installed plugin reports version `5.0.0` or
+   later, so **[*Migrating to version 3*](#migrating-to-version-3),
+   [*Migrating to version 4*](#migrating-to-version-4), and
+   [*Migrating to version 5*](#migrating-to-version-5) must all be complete too**; a stop at `2.0.0`
    would resume writes with the retired FinOps schedule still armed, and a stop at `3.0.0` with a
    schedule pointing at an entrypoint that no longer resolves — and that it
    exposes `agentic-engineer`, `portfolio-surveyor`, and `agent-improver`, and that every
@@ -99,8 +130,8 @@ the read-only preflight loads the new namespace successfully.
 Three agents:
 
 - **`agentic-engineer`** — the actor that runs the survey → select → act → report loop, operates
-  the portfolio, advances the oldest actionable issue, and — when the consumer declares a **Spend
-  contract** — stewards the portfolio's running cost in the same loop.
+  the portfolio, advances the oldest actionable issue, and — after explicit maintainer opt-in and a
+  resolving **Spend contract** — stewards the portfolio's running cost in the same loop.
 - **`portfolio-surveyor`** — a delegated, read-only agent that returns a compact current-state digest.
 - **`agent-improver`** — a meta-engineer that evaluates deployed instances and improves their shared
   definition from evidence.
@@ -175,10 +206,12 @@ Enabling `agent-improver` adds two required sections:
 - **Authority model** — the separate boundaries for tightening and loosening prose and enforcement
   guardrails.
 
-Enabling the engineer's spend stewardship additionally requires **Spend contract**, which names the
+Enabling the engineer's spend stewardship requires literal `true` in
+`spec.roles["agentic-engineer"].spendStewardshipEnabled` and **Spend contract**, which names the
+single effective desired-state document,
 cost evidence sources and which are actually wired, the protected-outcomes floor and who may change
 it, the run procedure for a cost pass, the private channel a financial decision goes to, and the
-cadence a cost pass runs on. Absent, the engineer runs normally with the **cost dimension failed
+cadence a cost pass runs on. Disabled or unresolved, the engineer runs normally with the **cost dimension failed
 closed** — it does no spend analysis rather than guessing a floor, a price, or a channel.
 
 The `Memory` section must also name the scorecard and open verification-hypothesis store used by the

plugins/agentic-engineering/agents/agentic-engineer.agent.md

@@ -12,7 +12,7 @@ description: >-
   protected outcome) — everything shipped as draft PRs self-promoted on genuine
   readiness, and never a money-moving act. Requires the consuming repository's AGENTS.md to define the
   Portfolio map, Trust gate, Cadence, Memory, and Maintainer channels contract
-  sections, plus a Spend contract section to enable spend stewardship. Use on a
+  sections, plus explicit opt-in and a Spend contract for spend stewardship. Use on a
   schedule or on request whenever a portfolio of repositories should be
   maintained or advanced.
 skills:
@@ -48,7 +48,7 @@ You are parameterized, not hard-coded: the consuming repository's canonical inst
   maintainer's **interactive-session marker** (the literal a PR body carries when it came from the
   maintainer's own hand-driven session, which the surveyor reads to tell that PR from your own).
 
-One further section is **conditionally** required, and it is what turns spend stewardship on:
+One further section is **conditionally** required when spend stewardship is explicitly enabled:
 
 - **Spend contract** — the deployment's money facts: where cost evidence comes from and which of
   those sources are actually wired, the **protected-outcomes floor** (the declared list of outcomes
@@ -164,7 +164,9 @@ instead.
 
 ## Spend stewardship — the money side of the same portfolio
 
-Enabled only when the **Spend contract** section resolves. Running cost is a product property like
+**Spend stewardship is explicitly opt-in.** During preflight, read `spec.roles["agentic-engineer"].spendStewardshipEnabled` from the single effective desired-state document declared in the consumer **Spend contract**. If no effective document is declared, use the shipped `false` default. An unreadable or invalid declared document, a missing field, or a non-boolean value disables spend and reports the gap. Only literal `true` plus a resolving **Spend contract** enables spend analysis and decisions; it bypasses no private-channel, protected-outcomes, or authority requirement. Only the maintainer may opt in. Never infer enablement from contract presence or past activity, and never change the source or value during a run. While disabled, continue ordinary operate and advance engineering.
+
+Running cost is a product property like
 performance or security, so you own it in the same loop, with the same evidence discipline — and you
 never own the act of spending.
 

plugins/agentic-engineering/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering",
   "description": "The autonomous engineering system for repository portfolios — engineer, read-only surveyor, and meta-engineer agents; portfolio, product, spend, and improvement workflows; cross-tool instruction architecture and skill discovery; configured by the consumer AGENTS.md",
-  "version": "4.4.29",
+  "version": "5.0.0",
   "author": {
     "name": "devantler-tech",
     "url": "https://github.com/devantler-tech"

plugins/agentic-engineering/resources/provider-neutral.desired-state.json

@@ -27,7 +27,7 @@
           "executable": true
         }
       ],
-      "entrypointSha256": "9d45e8ae019f75944d70c78f8c82481d2b9af798792c4c008cfe61fa494b8441",
+      "entrypointSha256": "a3d01aa54b2af445aa4a6d07eb406d401824be7db08d5ec4c2f914db7fc9bf39",
       "updatePolicy": "latest-reviewed-default-branch",
       "providerPolicy": "neutral",
       "refreshTiming": "before-starting-each-run",
@@ -55,6 +55,7 @@
     "roles": {
       "agentic-engineer": {
         "enabled": true,
+        "spendStewardshipEnabled": false,
         "mode": "scheduled-and-on-demand"
       },
       "portfolio-surveyor": {
@@ -79,7 +80,7 @@
         "schedules": {
           "agentic-engineer": {
             "definitionFrom": "plugin:agentic-engineering/agentic-engineer",
-            "bootstrapPrompt": "Load native persistent memory, read the consumer's canonical AGENTS.md, load the latest reviewed agentic-engineering plugin, and invoke its agentic-engineer entrypoint. Follow the consumer contract and fail closed on missing deployment facts, including spend stewardship when the Spend contract section does not resolve. Do not duplicate the role in this scheduler prompt."
+            "bootstrapPrompt": "Load native persistent memory, read the consumer's canonical AGENTS.md, load the latest reviewed agentic-engineering plugin, and invoke its agentic-engineer entrypoint. Resolve spec.roles[\"agentic-engineer\"].spendStewardshipEnabled during preflight using the entrypoint's explicit opt-in contract. Follow the consumer contract and fail closed on missing deployment facts. Do not duplicate the role in this scheduler prompt."
           },
           "agent-improver": {
             "definitionFrom": "plugin:agentic-engineering/agent-improver",
@@ -112,7 +113,7 @@
       "steps": [
         "Resolve the canonical consumer repository from the current workspace.",
         "Install or refresh agentic-engineering from the declared marketplace using the runtime's native mechanism. If full plugins are unsupported, load the canonical agent and skill files plus the referenced runtime assets from the declared source without creating divergent copies, including scripts/classify-default-branch-ci-runs.sh and scripts/forge-readonly-guard.sh for the portfolio-surveyor, plus scripts/surveyor-forge-readonly.sh only where the runtime presents a candidate command as structured JSON on standard input rather than as an argument, and verify every declared SHA-256 and executable requirement before use. forge-readonly-guard.sh --command is the portable contract; the wrapper is an input adapter for it, never a second policy. Register the guard at the surveyor's own pre-execution point only, directly or through that adapter, using the runtime's own agent-scoped mechanism; plugin-shipped agent definitions cannot carry that registration themselves, so it is always consumer-side wiring. A deployment that has not installed those assets or has not registered the guard for that agent fails closed (forge reads are QUERY-UNKNOWN).",
-        "Read AGENTS.md and verify every required consumer contract section. Enable agent-improver only when both additional sections are present, and enable the agentic-engineer's spend stewardship only when the Spend contract section resolves its cost evidence sources, protected-outcomes floor, run procedure, and private decision channel; otherwise run the engineer with the cost dimension failed closed.",
+        "Read AGENTS.md and verify every required consumer contract section. Enable agent-improver only when both additional sections are present. Preserve spec.roles[\"agentic-engineer\"].spendStewardshipEnabled from the single effective desired-state document declared in Spend contract, or the shipped false default when none is declared. Apply the engineer entrypoint's explicit opt-in contract before spend work; onboarding never infers or grants maintainer opt-in. Report the effective source, flag value, and unresolved prerequisites while continuing ordinary operate and advance engineering.",
         "Map the declared roles onto native agent capabilities, preserve portfolio-surveyor as read-only, and grant least privilege for each role. Export a disabling GH_TELEMETRY (0 or false) in the environment the surveyor's shell inherits: the read-only forge guard treats a missing value as unproven and refuses every command, including reads, so a runtime that enforces the guard without this variable leaves the surveyor unable to run any forge query at all. It cannot be supplied inside the command string, which the guard also refuses.",
         "Allocate a unique branch namespace for every deployed writer instance and record it in the consumer contract before enabling writes.",
         "Create or update a native schedule only for each entry in runtime.scheduler.schedules whose corresponding role's enabled or enabledWhen condition is satisfied, using AGENTS.md#Cadence and that entry's thin bootstrap prompt.",