feat(autonomy): guardrail matrix, security binding, setup slice (WP5)

.github/workflows/ci.yml

@@ -123,8 +123,13 @@ jobs:
         uses: melodic-software/ci-workflows/.github/actions/machine-specific-paths@c2654182bc2d78f7909795df78304d482aa69226 # c265418 2026-07-13
         with:
           # The guardrails plugin bundles a path-detection pattern lib whose
-          # regex bodies self-match this lane's own detector.
-          exclude: ':(exclude)plugins/guardrails/lib/path-detection/**'
+          # regex bodies self-match this lane's own detector. The autonomy
+          # security-binding fixtures carry ADVERSARIAL host paths on purpose
+          # (invented /home users the checker must reject) — sanitizing them
+          # would gut the regressions they pin.
+          exclude: >-
+            :(exclude)plugins/guardrails/lib/path-detection/**
+            :(exclude)plugins/autonomy/skills/setup/evals/fixtures/security-binding/**
 
       - name: Check index-level EOL drift
         id: eol

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, and trigger-dispatch 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, and wires signal adapters with one governed dispatch entrypoint.
+- [`autonomy`](plugins/autonomy) — Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, and per-work-class guardrail-matrix 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, and 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.
 
 ### Security
 

docs/topics/ai-adoption-ladder/index.md

@@ -7,7 +7,10 @@ user-, and tool-agnostic.
 
 Contract set: seven resolved design threads (T1–T7) from wayfind map claude-code-plugins#239
 (closed). Design slice: `design/` (design-threads.md is the contract record; RESEARCH-*.md are
-the evidence base; boris-step-and-your-role.txt is the captured source artifact). Session
+the evidence base; boris-step-and-your-role.txt is the captured source artifact — canonical
+upstream: the [Boris Cherny "Steps of AI Adoption" Google Doc](https://docs.google.com/document/d/1R91ayvj7uvlxgNi--__2-Bf3w8x5r1nF-xIBN7ds8Ns/edit)
+and its [companion Claude artifact](https://claude.ai/code/artifact/bfdfaef9-bc62-4dfe-ba9e-c58a26c9accf)
+(artifact link currently fails to load; kept as the upstream reference)). Session
 working memory (checklists, drafts) stays in gitignored `.work/ai-adoption-ladder/`.
 
 ## Work packages

docs/topics/ai-ladder-wp5-guardrails/PLAN.md

@@ -104,7 +104,7 @@ Prerequisite: the WP4 implementation PR merged (`reference/trigger-dispatch.md`
 admission leaf cites its seam; the interim is safe via WP4's fail-closed absent-binding
 clause).
 
-### Phase 1: Guardrail hub + leaf docs [TODO]
+### Phase 1: Guardrail hub + leaf docs [DONE]
 
 | File | Action | What changes |
 |---|---|---|
@@ -122,7 +122,7 @@ clause).
 - Promotion defaults present: `grep -c '20 autonomous C2 completions' plugins/autonomy/reference/guardrails/work-classes.md` ≥ 1 and `grep -c '14 days' plugins/autonomy/reference/guardrails/work-classes.md` ≥ 1
 - Vendor+fleet deny-list sweep exit 0; lychee lane passes
 
-### Phase 2: Binding schema (two governance surfaces) [TODO]
+### Phase 2: Binding schema (two governance surfaces) [DONE]
 
 | File | Action | What changes |
 |---|---|---|
@@ -138,7 +138,7 @@ clause).
 - Schema `additionalProperties: false` present (`grep -c '"additionalProperties": false' …schema.json` ≥ 1)
 - `claude plugin validate --strict` exit 0
 
-### Phase 3: Guided-setup guardrail slice [TODO]
+### Phase 3: Guided-setup guardrail slice [DONE]
 
 Extends the `setup` skill: detect → bind → live-validate → fail-closed (D4), always
 detect-diff-reconcile against existing org guardrail surfaces (D5 — sandbox configs, branch
@@ -158,7 +158,7 @@ protections, review workflows), never greenfield-assume, never silently overwrit
 - `grep -ci 'detect-diff-reconcile' plugins/autonomy/skills/setup/SKILL.md` ≥ 1
 - Fleet-name sweep exit 0
 
-### Phase 4: Live-validation demonstration + gates [TODO]
+### Phase 4: Live-validation demonstration + gates [DONE]
 
 Acceptance probe, BOTH paths mandatory: (positive) run the Phase 3 probe recipe against a
 REAL, PROVISIONED egress-denied boundary — the CI job on this public repo (free minutes)

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

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "autonomy",
-  "version": "0.4.0",
-  "description": "Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, and trigger-dispatch 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, and wires signal adapters with one governed dispatch entrypoint.",
+  "version": "0.5.0",
+  "description": "Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, and per-work-class guardrail-matrix 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, and 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.",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"

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.4.0)
+## Shipped capability (0.5.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
@@ -25,6 +25,16 @@ state and records that binding.
   one dispatch entrypoint (push kick + scheduled drain through the queue seam's race-safe
   lease) — plus the setup trigger/dispatch slice, its adapter and acknowledgment templates,
   and the signal-envelope conformance check.
+- **Guardrail matrix** (`reference/guardrails.md`): five semantic work classes (`C1`–`C5`)
+  crossed with five enforcement columns — isolation floor, verification layers, merge policy,
+  cost tier, escalation — as one progressive-disclosure hub with on-demand leaves (isolation
+  ladder, work classes, security review, admission policy), human-ratified promotion with
+  automatic fail-closed demotion, and a two-surface binding split by governance sensitivity
+  (security axes on the settings-as-code home outside agent blast radius; non-security remaps
+  repo-local) — plus the contract-owned security-binding schema and its semantic check, and the
+  setup guardrail slice that detects substrates per surface, live-validates isolation with an
+  in-boundary probe before binding, folds in security-review wiring, and fail-closes autonomous
+  dispatch where no `L2` substrate exists.
 - **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.
@@ -37,7 +47,6 @@ locked (no step-skipping — trust before scale).
 | Capability | Trigger |
 |---|---|
 | Fleet adapter materializations (reusable workflows, labels, drain routine) | Work-item backlog, post trigger-package graduation. |
-| Guardrail matrix + sandbox-ladder binding | Guardrails work package build lands. |
 | Standing-routine catalog + v1 definitions | Routines work package build lands. |
 | Runner charter execution pack | The runner build trigger fires (charter's own conditions). |
 

plugins/autonomy/reference/guardrails.md

@@ -0,0 +1,92 @@
+# Guardrails
+
+Normative contract for per-work-class guardrail enforcement: five semantic risk classes
+(`C1`–`C5`) crossed with five guardrail columns, in one matrix. This document is the hub and
+glance layer of a progressive-disclosure contract — the matrix plus the one-line class and
+column definitions below alone answer "what governs class X"; every deeper question routes to
+a named leaf under `guardrails/`, loaded on demand. Vocabulary is contract-owned; every
+concrete instance (isolation substrates, review tooling, model names, escalation routes) is an
+org-binding outcome on the binding seam.
+
+## The matrix
+
+The matrix instantiates the Boris playbook's step-4 sentence verbatim — "enforcing the right
+guardrails for each type of work" — as a table: one row per work class, one column per
+guardrail axis.
+
+| Class | Min isolation (unattended) | Verification | Merge policy | Cost tier | Escalation |
+|---|---|---|---|---|---|
+| C1 | L2 (exfil surface remains) | output-shape checks | n/a; artifacts via queue audit trail | economy | low |
+| C2 | L2 | deterministic blocking | auto-merge ELIGIBLE after per-class promotion trigger; ships human-gated | economy | gate failure → human |
+| C3 | L2 | deterministic blocking + AI review (advisory, promotable per [the security-review policy](guardrails/security-review.md)) | human merge | standard | divergence/failed verify → human |
+| C4 | L2 | deterministic + AI + human review mandatory | human merge always | premium | upfront plan approval |
+| C5 | L3 | full gates + zero secret exposure | human merge always | standard | always |
+
+### Classes
+
+- `C1` read-only — audits, research, reports; no repository mutation (governed-queue and
+  tracker writes are permitted output — scoping in the leaf).
+- `C2` mechanical maintenance — dependency bumps, lint/format, sync; deterministic and
+  trivially reversible.
+- `C3` scoped change — a briefed fix or small feature; bounded, tests exist.
+- `C4` structural — refactors, migrations, contract changes; cross-cutting, hard reversal.
+- `C5` untrusted-provenance — fork PRs, external contributions, unvetted repositories.
+
+### Columns
+
+- **Min isolation (unattended)** — the isolation-ladder level (`L0`–`L3`) that is the floor
+  for running the class unattended.
+- **Verification** — the gate layers a change must pass, with per-layer blocking knobs bound
+  on the governance surface.
+- **Merge policy** — who lands the change; promotion-gated where the cell says so.
+- **Cost tier** — contract vocabulary (`economy` | `standard` | `premium`); the org binds
+  tiers to model instances. Policy vocabulary only — cost enforcement is out of scope.
+- **Escalation** — when a run must summon a human; event classes and routing below.
+
+## Glance-layer rule
+
+The matrix and the one-line definitions above are the whole glance layer: they alone answer
+"what governs class X". Every deeper question routes to a named leaf — depth is never
+answered from this document:
+
+| Deeper question | Leaf |
+|---|---|
+| What each level means, which substrate classes satisfy it, what happens when none does | [isolation-ladder](guardrails/isolation-ladder.md) |
+| What exactly is in each class, and how a promotable cell promotes or demotes | [work-classes](guardrails/work-classes.md) |
+| Which verification layers exist and which block, per class | [security-review](guardrails/security-review.md) |
+| Which signals may enter the queue autonomously, and under what caps | [admission-policy](guardrails/admission-policy.md) |
+
+## Permission posture
+
+Permission posture is not a matrix column: `L1` is the attended ergonomics tier where
+per-action prompts remain the control; at `L2` and above the whole-process boundary is the
+control, replacing per-action prompts. The [isolation-ladder](guardrails/isolation-ladder.md)
+leaf carries this note in context.
+
+## Escalation
+
+Six escalation event classes:
+
+| Event class | Fires when |
+|---|---|
+| `gate-failure` | a blocking verification gate fails |
+| `verification-divergence` | a verification outcome diverges from the expected or claimed result |
+| `admission-rejection` | the admission seam rejects a signal as an audited rejection |
+| `demotion` | contrary evidence automatically demotes a promoted cell |
+| `structural-plan-approval` | a `C4` item requires upfront plan approval before execution |
+| `untrusted-provenance` | always, for every `C5` item |
+
+**Routing obligation.** Every event class has an org-bound route in the security binding —
+escalation routes are a security-sensitive axis, so they bind on the governance surface, and
+an absent or invalid binding fail-closes per the binding contract.
+
+**Payload.** The work-item reference plus the trace link: every escalation carries the item
+it concerns and the trace context joining it into the one causal tree, so the evidence behind
+the escalation is queryable from the event.
+
+**Mechanism.** The governed queue itself: an escalation lands as a human-gated work item on
+the one queue, with an optional channel notification delivered through the trigger contract's
+closed-loop acknowledgment symmetry ([trigger-dispatch](trigger-dispatch.md)). No second
+escalation channel, claim path, or dispatch mechanism exists.
+
+Interactive escalation UX is deferred; its trigger is the runner design pack.

plugins/autonomy/reference/guardrails/admission-policy.md

@@ -0,0 +1,89 @@
+# Admission policy
+
+Normative admission-policy content for the [guardrail matrix](../guardrails.md): the
+decision that turns a
+queued signal into an autonomously dispatchable item, a human-gated item, or an audited
+rejection. The [trigger-dispatch contract](../trigger-dispatch.md) enforces this policy
+at its admission seam — adapters ENFORCE admission, never define it — and this leaf owns
+the content. Serialized rules and caps live in the `admission` object of the security
+binding on the settings-as-code governance surface, outside the blast radius of the
+agents they govern (an agent-writable admission policy is a bypass channel).
+
+## Decision table
+
+One table, three axes, one disposition per decision:
+
+| Axis | Values |
+|---|---|
+| Signal-surface class | `tracker-vcs-event` \| `temporal` \| `agent-internal` \| `channel-feed` — trigger-contract tokens |
+| Initiator provenance | `human` \| `agent` \| `system` |
+| Work class | `C1`–`C5`, stamped per the trigger-dispatch classification rules |
+
+| Disposition | Meaning |
+|---|---|
+| `autonomous-eligible` | May dispatch autonomously, within caps and subject to every other guardrail: [isolation verdict](isolation-ladder.md), execution-surface attestation, verification gates |
+| `human-gated` | Enqueued and held; a human admits the item before any dispatch |
+| `audited-rejection` | Recorded as rejected, with provenance and the matched rule on the audit trail — never a silent drop |
+
+An item the classification rules cannot resolve never reaches table evaluation:
+unclassified is fail-closed `human-gated`, always (trigger-dispatch rule).
+
+### Wildcards and precedence
+
+Any axis in a rule may be the wildcard `"*"`. Matching is most-specific-wins: a rule
+binding the full triple beats one binding two axes, which beats one axis, which beats
+the default disposition. Two matching rules of EQUAL specificity with different
+dispositions make the binding invalid — fail-closed, like any invalid security binding.
+
+A rule may carry an optional `override_justification`. A rule MORE PERMISSIVE than the
+shipped default for its cell — permissiveness decreases `autonomous-eligible` →
+`human-gated` → `audited-rejection` — is invalid without one; tightening needs none.
+
+## Shipped defaults
+
+| Surface class | Provenance | Work class | Disposition |
+|---|---|---|---|
+| `"*"` | `"*"` | `C1` | `autonomous-eligible`, within caps |
+| `"*"` | `"*"` | `C2` | `autonomous-eligible`, within caps |
+| `"*"` | `"*"` | `C3` | `human-gated` — per-item human admission |
+| `"*"` | `"*"` | `C4` | `human-gated` |
+| `"*"` | `"*"` | `C5` | `human-gated` |
+
+Default disposition where no rule matches: `human-gated`.
+
+- `C1`/`C2` are autonomous-eligible within caps REGARDLESS of provenance: blocking
+  `agent` provenance would sever the agent-kicks-off-agent loop the `agent-internal`
+  surface class exists for.
+- Provenance is RECORDED input to gating, never trusted as isolation: provenance is
+  claimable, so isolation decisions key on the work class and surface verdicts. For
+  `agent-internal` signals the trigger-dispatch contract verifies claimed provenance
+  against protected dispatch data before admission consumes the class.
+- No shipped rule produces `audited-rejection`; the disposition exists for org rules —
+  e.g. a surface class or provenance the org bans outright — and every rejection stays
+  on the audit trail.
+
+## Caps
+
+Caps bound TOTAL autonomous fan-out — they apply across all rules and surfaces, never
+per rule:
+
+| Token | Shipped default | Bounds |
+|---|---|---|
+| `autonomous_concurrency` | `1` | Autonomous dispatches in flight at any moment |
+| `items_per_run` | `3` | Items one drain run may dispatch autonomously |
+
+Values are org-bindable; the shipped defaults are a deliberately conservative
+trust-before-scale floor. A cap never changes a disposition: an over-cap
+`autonomous-eligible` item stays enqueued for a later drain run — deferred, not rejected
+and not re-gated.
+
+## Binding and fail-closed behavior
+
+- Serialization home: the security binding's `admission` object — the decision-table
+  rules, the caps, and the signal→work-class classification rules adapters stamp from.
+  The binding schema is contract-owned and ships with the security binding; this leaf
+  owns the semantics it serializes.
+- An ABSENT or invalid admission binding fail-closes at the seam: everything enqueues
+  `human-gated` (the trigger-dispatch contract's absent-binding clause).
+- No repo-local (agent-writable) surface may supply any admission input — rules, caps,
+  or the work class used for admission.