docs(autonomy): autonomous-runner design pack (WP7)

README.md

@@ -118,7 +118,7 @@ user opts in with `/plugin enable`; an existing install is never flipped by cata
 
 ### Autonomy
 
-- [`autonomy`](plugins/autonomy) — Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, per-work-class guardrail-matrix, and standing-routine-catalog contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state, writes its schema-versioned binding, wires standards-pinned OTLP emission with a zero-cost file-artifact default, wires human-attested return capture at the task boundary, wires signal adapters with one governed dispatch entrypoint, binds the five-class guardrail matrix to an org's isolation substrates with an in-boundary live-validation probe before recording each fail-closed binding, and stands up standing-routine-catalog classes as scheduled temporal signal adapters behind the one governed queue with free scheduling defaults wired as reviewable changes and each routine's work-class mapping homed on the security surface.
+- [`autonomy`](plugins/autonomy) — Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, per-work-class guardrail-matrix, standing-routine-catalog, and design-only runner-charter contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state, writes its schema-versioned binding, wires standards-pinned OTLP emission with a zero-cost file-artifact default, wires human-attested return capture at the task boundary, wires signal adapters with one governed dispatch entrypoint, binds the five-class guardrail matrix to an org's isolation substrates with an in-boundary live-validation probe before recording each fail-closed binding, and stands up standing-routine-catalog classes as scheduled temporal signal adapters behind the one governed queue with free scheduling defaults wired as reviewable changes and each routine's work-class mapping homed on the security surface.
 
 ### Security
 

docs/topics/ai-ladder-wp7-runner/PLAN.md

@@ -119,7 +119,7 @@ Design-pack docs live under `reference/runner/` (hub `reference/runner.md`).
 Prerequisites: WP4 + WP5 + WP6 implementation PRs merged (this pack imports their contracts
 by citation). Design only — zero build artifacts; the runner-execution home stays unborn.
 
-### Phase 1: Charter import + spine and seam specs [TODO]
+### Phase 1: Charter import + spine and seam specs [DONE]
 
 | File | Action | What changes |
 |---|---|---|
@@ -133,7 +133,7 @@ by citation). Design only — zero build artifacts; the runner-execution home st
 - Seam count: `grep -cE '^## ' plugins/autonomy/reference/runner/seams.md` = 8
 - Vendor+fleet deny-list sweep exit 0; lychee lane passes
 
-### Phase 2: Lifecycle + stop-criteria + escalation leaves [TODO]
+### Phase 2: Lifecycle + stop-criteria + escalation leaves [DONE]
 
 | File | Action | What changes |
 |---|---|---|
@@ -149,7 +149,7 @@ by citation). Design only — zero build artifacts; the runner-execution home st
 - `grep -c 'USER-RESERVED' plugins/autonomy/reference/runner/topology.md` ≥ 1
 - Vendor+fleet deny-list sweep exit 0
 
-### Phase 3: Setup note + WP5 escalation-route join [TODO]
+### Phase 3: Setup note + WP5 escalation-route join [DONE]
 
 | File | Action | What changes |
 |---|---|---|
@@ -166,7 +166,7 @@ by citation). Design only — zero build artifacts; the runner-execution home st
 - Schema additivity: `grep -c 'escalation_severity_routes' …schema.json` ≥ 1 and a pre-WP7 fixture binding still passes `check-security-binding.mjs` unchanged (no major bump proven, not asserted)
 - `/skill-quality:check` + `validate-evals` pass; `claude plugin validate --strict` exit 0
 
-### Phase 4: Zero-build audit + gates [TODO]
+### Phase 4: Zero-build audit + gates [DONE]
 
 Acceptance probe (mechanical): the package introduces no executable/runtime artifact — the
 diff contains no new files outside `reference/`, `skills/setup/`, README, and plugin

plugins/autonomy/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "autonomy",
-  "version": "0.6.0",
-  "description": "Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, per-work-class guardrail-matrix, and standing-routine-catalog contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state, writes its schema-versioned binding, wires standards-pinned OTLP emission with a zero-cost file-artifact default, wires human-attested return capture at the task boundary, wires signal adapters with one governed dispatch entrypoint, binds the five-class guardrail matrix to an org's isolation substrates with an in-boundary live-validation probe before recording each fail-closed binding, and stands up standing-routine-catalog classes as scheduled temporal signal adapters behind the one governed queue with free scheduling defaults wired as reviewable changes and each routine's work-class mapping homed on the security surface.",
+  "version": "0.7.0",
+  "description": "Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, per-work-class guardrail-matrix, standing-routine-catalog, and design-only runner-charter contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state, writes its schema-versioned binding, wires standards-pinned OTLP emission with a zero-cost file-artifact default, wires human-attested return capture at the task boundary, wires signal adapters with one governed dispatch entrypoint, binds the five-class guardrail matrix to an org's isolation substrates with an in-boundary live-validation probe before recording each fail-closed binding, and stands up standing-routine-catalog classes as scheduled temporal signal adapters behind the one governed queue with free scheduling defaults wired as reviewable changes and each routine's work-class mapping homed on the security surface.",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"
@@ -17,6 +17,7 @@
     "otlp",
     "return-accounting",
     "routines",
+    "runner",
     "telemetry",
     "topology"
   ]

plugins/autonomy/README.md

@@ -5,7 +5,7 @@ AI-adoption-ladder contract set: it ships the tool-agnostic contracts an adoptin
 its own repositories, tools, and policies, plus a guided-setup skill that discovers the org's
 state and records that binding.
 
-## Shipped capability (0.6.0)
+## Shipped capability (0.7.0)
 
 - **Topology contracts** (`reference/`): role topology for the repositories an adoption spans,
   the binding-seam shape that maps contract roles to an org's real instances, and the
@@ -44,6 +44,14 @@ state and records that binding.
   that discovers scheduling surfaces, wires the free CI-cron/local-scheduler defaults as reviewable
   changes, homes each routine's work-class mapping on the security surface, and
   detect-diff-reconciles existing org schedulers and bots instead of duplicating them.
+- **Runner design pack** (`reference/runner.md`): the architect-ready design contract for the
+  autonomous-drain runner — the composition spine and its eight seams, the lifecycle state
+  model, the two-family stop-criteria taxonomy with terminal-handoff escalation and
+  severity-routed notification fan-out, the matrix-derived launch backend set, and the topology
+  ownership seam map, as a progressive-disclosure hub with `reference/runner/` leaves. Design
+  only — the build stays gated on the charter's own triggers and the runner-execution home
+  stays unborn; setup records nothing runner-specific beyond the escalation notification routes
+  (severity axis + personal-push tier) bound through the security binding.
 - **Guided setup** (`/autonomy:setup`): discovery-first interview of the adopting org's state —
   role homes, substrate availability, budget posture — writing a schema-versioned binding under
   `.claude/autonomy/` as reviewable changes. Never assumes any particular org or repo shape.
@@ -56,7 +64,7 @@ locked (no step-skipping — trust before scale).
 | Capability | Trigger |
 |---|---|
 | Fleet adapter materializations (reusable workflows, labels, drain routine) | Work-item backlog, post trigger-package graduation. |
-| Runner charter execution pack | The runner build trigger fires (charter's own conditions). |
+| Runner charter execution pack (design pack shipped) | The runner build trigger fires (charter's own conditions). |
 
 ## Trigger register (plugin-scoped)
 

plugins/autonomy/reference/runner.md

@@ -0,0 +1,123 @@
+# Runner
+
+Design-pack hub for the autonomous-drain runner: the charter it graduates from, the
+composition spine that shapes it, and the eight seams that are its interface set. This
+document is the glance layer of a progressive-disclosure design pack — the charter, the spine
+shape, and the seam list here answer "what is the runner, what shape does it take, and what
+must it honor"; every deeper question routes to a named leaf under `runner/`, loaded on
+demand. The pack is a design contract only: it fixes vocabulary and obligations for a runner
+that is not built, so that when a trigger earns the build, the work starts from a resolved
+contract rather than a cold charter.
+
+This document makes no build commitment: no code, no repository, no schedule — no build begins
+until a T4 build trigger fires. Every inherited obligation is cited from its already-shipped
+owning contract, never restated here.
+
+## Charter scope — the autonomous-drain side only
+
+The boundary between plugins and runner IS the governed work-item queue, split
+interactive-upstream from autonomous-downstream:
+
+- **Interactive upstream (plugins own it).** Everything interactive — interview, design,
+  architect, decompose, triage — produces autonomous-eligible items, and the trigger adapters
+  live where their signals natively land ([trigger-dispatch](trigger-dispatch.md)). The
+  runner never decides what to build.
+- **Autonomous downstream (the runner owns it).** The runner is the autonomous drain side
+  only: lease-claim from the work-item queue, execute in isolation, run the verification
+  gates, apply the per-class merge policy, and escalate back to humans. It is one executor
+  behind the [invocation-adapter seam](trigger-dispatch.md#executor-surface-classes) —
+  swapping executors leaves the trigger adapters untouched.
+
+## Build triggers
+
+The runner's graduation to build is gated: either T4 build trigger fires it, and neither is
+assumed to have fired. Restated verbatim in substance (the executor references rendered in the
+shipped surface-class vocabulary, never as vendor names):
+
+- The `C2` promotion trigger fires (per the [guardrail matrix](guardrails.md#the-matrix))
+  AND the existing executors behind the invocation-adapter seam — the self-operated and
+  vendor-hosted surfaces reachable today — demonstrate a clean autonomous drain; **OR**
+- those existing executors hit an isolation, concurrency, or platform wall the runner uniquely
+  solves.
+
+Until one build trigger is satisfied, the runner-execution home stays unborn and this pack
+adds no runtime artifact. The trust loop earns the build; the build never front-runs the trust
+loop (Boris step-3 trap: no agent-count scaling before the loop earns trust).
+
+## Substrate stance — self-run primary, hosted via adapter
+
+- **Self-operated is primary.** The self-operated CLI/SDK surface class is the only class
+  where merge policy is ownable — every vendor-hosted issue-to-change agent keeps a deliberate
+  human-merge-gate — so the `C2` auto-merge promotion is reachable only self-run.
+- **Vendor-hosted is reachable, capped.** Vendor-hosted surfaces stay reachable through the
+  [invocation-adapter seam](trigger-dispatch.md#executor-surface-classes) (it covers
+  local-CLI and cloud-API shapes) but inherit their human-merge-gate: the matrix merge-policy
+  column caps at human-gated on any vendor-hosted executor. Vendor-managed isolation remains a
+  legitimate `L3` instance — untrusted-provenance (`C5`) work is its natural fit.
+- **Classes, never vendors.** The contract names surface classes — self-operated versus
+  vendor-hosted — and never a product.
+
+## Inherited constraints
+
+All imported unchanged; each is enforced by its owning contract, cited never restated:
+
+- Execution substrate is at least `L2`, fail-closed where unavailable
+  ([isolation ladder](guardrails/isolation-ladder.md)).
+- Per-class gates, merge policy, cost tier, and escalation come from the
+  [guardrail matrix](guardrails.md#the-matrix).
+- Queue and lease are reused from the work-item capability's race-safe lease and its
+  autonomous/human-gated classes — no second claim mechanism
+  ([dispatch](trigger-dispatch.md#dispatch)).
+- No queue bypass: every dispatch funnels through the one entrypoint, and the audit trail is
+  the trust loop ([trigger-dispatch](trigger-dispatch.md)).
+
+## Anti-goals
+
+- Set-and-forget framing — the runner is monitored by exception, never unattended-and-trusted.
+- Ungated autonomy — every class keeps its matrix gates; no class drains without them.
+- Privileged-context trigger footguns — the trigger class that runs fork-authored code with
+  write-scoped credentials is never a runner intake path.
+
+## Composition spine
+
+The spine is specified in two layers: a normative layer that fixes its shape in seam
+vocabulary, and a binding layer that records how the shape is realized at build time.
+
+### Normative spine shape
+
+The runner's shape is minimal composable orchestration over two pluggable seams crossed with
+one execution split:
+
+- a **pluggable sandbox-provider seam** — the isolation policy seam, selecting the substrate
+  that satisfies a class's isolation floor;
+- a **pluggable agent-adapter seam** — the invocation adapter seam, normalizing an executor's
+  native surface behind one contract;
+- an **autonomous/interactive split** — the runner drives the autonomous path; the interactive
+  path stays with the plugins.
+
+The [eight seams](runner/seams.md) are this spine's complete interface set — nothing in the
+spine is expressible outside them.
+
+### Binding stance — adopt first
+
+The binding layer records an adopt-first posture: adopt the qualifying composition-spine
+library as a build-stage dependency rather than build orchestration from scratch, absorbing
+its orchestration, sandbox, and lifecycle patterns re-expressed in this pack's vocabulary. The
+choice is re-verified at trigger time on maintenance, license, and seam fit; reimplementing the
+pattern is the named fallback when re-verification fails. No library is named here — the
+qualifying candidate is re-checked when the build trigger fires, not pinned in the design.
+
+## Glance-layer rule
+
+The charter, the spine shape, and the seam list above are the whole glance layer. Every deeper
+question routes to a named leaf under `runner/`; depth is never answered from this document:
+
+| Deeper question | Leaf |
+|---|---|
+| What each seam obligates, what owns it, and its runner-side interface tokens | [seams](runner/seams.md) |
+| The full lifecycle state model and each transition's telemetry | [lifecycle](runner/lifecycle.md) |
+| The stop-criteria taxonomy, terminal-handoff escalation, and severity routing | [escalation](runner/escalation.md) |
+| Ownership seams, the launch backend set, and birth-time decisions | [topology](runner/topology.md) |
+
+The `lifecycle`, `escalation`, and `topology` leaves land with the pack's later phase; their
+forward links are expected within an in-progress design pack.