feat(autonomy): autonomy plugin — category, topology contracts, guided-setup v0 (WP1)

.claude-plugin/marketplace.json

@@ -398,6 +398,12 @@
       "category": "design",
       "tags": ["miro", "mcp", "boards", "sticky-notes", "eventstorming", "diagramming", "visual-collaboration"],
       "defaultEnabled": false
+    },
+    {
+      "name": "autonomy",
+      "source": "./plugins/autonomy",
+      "category": "autonomy",
+      "tags": ["autonomy", "adoption", "governance", "topology", "binding", "guided-setup"]
     }
   ],
   "renames": {

README.md

@@ -116,6 +116,10 @@ user opts in with `/plugin enable`; an existing install is never flipped by cata
 - [`claude-ops`](plugins/claude-ops) — Claude Code operations toolkit. Five skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.
 - [`skill-quality`](plugins/skill-quality) — Skill-authoring QA tooling: a static contract checker that runs seventeen deterministic checks over a Claude Code skill (frontmatter, listing-budget cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence) and a bundled evals.json schema for validation. Runs against any repo's skills directory via the convention-resolution ladder — no baked layout.
 
+### Autonomy
+
+- [`autonomy`](plugins/autonomy) — Governed autonomous agent operation: role-topology, binding-seam, and wiring-vs-advisor contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state and writes its schema-versioned binding.
+
 ### Security
 
 - [`guardrails`](plugins/guardrails) — Eight safety guards that block secret/credential writes, hardcoded machine-specific paths, git hook-bypass attempts, irreversible git operations (force-push, reset --hard, worktree-wide checkout/restore discards), Bash file-write workarounds that circumvent Write/Edit hooks, (advisory) hallucinated CLI flags, (advisory) un-throttled Workflow fan-out that risks burst 529s, and (advisory) direct git commit/gh pr create calls bypassing this marketplace's own commit/pull-request skills — each independently toggleable.

docs/CATALOG-TAXONOMY.md

@@ -47,6 +47,7 @@ Domain-and-cross-cutting tier — filed by subject:
 | Category | Scope |
 |---|---|
 | `claude-code` | Operating Claude Code itself: its config, memory, telemetry, session plumbing, usage playbooks. Membership requires the subject to *be* Claude Code, not merely to run on it. |
+| `autonomy` | Governed autonomous agent operation: adoption discovery, guardrail and sandbox contracts, standing routines, autonomy telemetry and return-accounting conventions. |
 | `security` | Secret, path, and bypass guarding. |
 | `workflow` | Conducting the development session and process: staging, handoff, retrospective, orchestration priming. |
 | `project-management` | Tracking, triaging, and decomposing the work backlog. |
@@ -78,6 +79,7 @@ Category-level:
 |---|---|
 | First deployment plugin lands | Populate the `deployment` category (already reserved above). |
 | A non-music creative plugin lands | Broaden `music` — rename to `creative` or add a sibling creative category — rather than filing the newcomer under `music`. |
+| A broader automation plugin lands (automation that is not governed-autonomy-scoped) | Broaden `autonomy` or add a sibling category rather than filing the newcomer under `autonomy`. |
 
 Plugin-scoped (owned by the named plugin's README):
 

docs/topics/ai-ladder-wp1-packaging/PLAN.md

@@ -71,7 +71,7 @@ topology contract docs only (per-capability contracts land with WP2–WP6); guid
 as a v0 discovery-phase skill; the fleet binding instance lands in the org-policy home
 (`melodic-software/standards`) via a separate small PR that merges after the plugin PR.
 
-### Phase 1: Category vocabulary + generator [TODO]
+### Phase 1: Category vocabulary + generator [DONE]
 
 | File | Action | What changes |
 |---|---|---|
@@ -83,7 +83,7 @@ as a v0 discovery-phase skill; the fleet binding instance lands in the org-polic
 - `grep -c '\`autonomy\`' docs/CATALOG-TAXONOMY.md` ≥ 1
 - `grep -n 'autonomy' scripts/generate-catalog.mjs` shows a `CATEGORY_ORDER` entry
 
-### Phase 2: Plugin scaffold [TODO]
+### Phase 2: Plugin scaffold [DONE]
 
 First work item — migration-gate step 1: re-fetch the official plugins/plugin-manifest docs
 (fresh-docs mandate) before authoring. Migration-gate step 6 (PII/secrets strip) runs before
@@ -102,7 +102,7 @@ the first commit.
 - `node scripts/generate-catalog.mjs` reports in-sync
 - `grep -riE 'melodic-software|ci-workflows|github-iac' plugins/autonomy/ --exclude=plugin.json` returns empty (author metadata in plugin.json is the only allowed occurrence)
 
-### Phase 3: Topology contract docs [TODO]
+### Phase 3: Topology contract docs [DONE]
 
 All three docs in `plugins/autonomy/reference/` are tool-agnostic contract markdown: roles and
 surface classes only. Vendor and fleet names banned outright — real instances live in the
@@ -112,7 +112,7 @@ path) live in SKILL.md/README, never in `reference/`.
 | File | Action | What changes |
 |---|---|---|
 | `plugins/autonomy/reference/role-topology.md` | Create | D1 five roles (capability-distribution, CI-orchestration, settings-as-code, org-policy, runner-execution [unborn; birth trigger = T4 build trigger]); D3 adapter split rule (handler logic → CI-orchestration home; enabling settings incl. admission policy → settings-as-code home); D5 composition stance (composes existing plugin seams — work-item queue/lease/dispatch, deterministic guardrail hooks, verification gates, session observability; near-duplicate skills banned). |
-| `plugins/autonomy/reference/binding-seam.md` | Create | Binding SHAPE + resolution ladder: repo-local binding override → org binding at the org-policy home → setup interview. Must specify: (a) the org-policy-home pointer persists in repo-local/user-global config and is the prerequisite of rung 2; (b) fetch mechanism = the host CLI with the consumer's own auth; (c) no-org terminal default = repo-local binding + free-tier defaults; (d) written bindings carry a schema-version from v0; (e) known limitation: pointer staleness when an org moves its policy home. Layout convention stated as shape only — one contract doc per capability lands in `reference/` with its owning WP; no future-filename enumeration. |
+| `plugins/autonomy/reference/binding-seam.md` | Create | Binding SHAPE + resolution ladder: repo-local binding override → org binding at the org-policy home → setup interview. Must specify: (a) the org-policy-home pointer persists in repo-local/user-global config and is the prerequisite of rung 2; (b) fetch mechanism = the host CLI with the consumer's own auth; (c) no-org terminal default = repo-local binding + free-tier defaults; (d) written bindings carry a `schema_version` field from v0; (e) known limitation: pointer staleness when an org moves its policy home. Layout convention stated as shape only — one contract doc per capability lands in `reference/` with its owning WP; no future-filename enumeration. |
 | `plugins/autonomy/reference/wiring-vs-advisor.md` | Create | D6 verbatim: WIRE when the target surface is machine-editable + local + reviewable, always landing as reviewable changes, never silent mutation; ADVISE (steps + cost surfaced) when org-external, entitlement-gated, paid, or GUI-only; paid anything = advisory + explicit opt-in first, regardless of wireability. |
 
 **Sanity Check:**
@@ -122,11 +122,11 @@ path) live in SKILL.md/README, never in `reference/`.
 - `grep -ci 'reviewable' plugins/autonomy/reference/wiring-vs-advisor.md` ≥ 1 and `grep -ci 'opt-in' …` ≥ 1
 - lychee lane passes (anchors valid; no dead cross-links)
 
-### Phase 4: guided-setup v0 skill [TODO]
+### Phase 4: guided-setup v0 skill [DONE]
 
 | File | Action | What changes |
 |---|---|---|
-| `plugins/autonomy/skills/setup/SKILL.md` | Create | Setup contract (name `setup`, `disable-model-invocation: true`, `check` + `apply` actions, idempotent, non-interactive when complete arguments supplied). Scope: D7 discovery/interview of the adopting org's state (role homes present, substrate availability, budget posture); `apply` writes the discovered binding as tracked config `.claude/autonomy/` — **concern-named from day one** (concern = governed autonomous operation; a plugin split/rename leaves it valid; the versioned `docs/conventions/autonomy/` contract is deferred with trigger: second plugin consumes the config). Enumerated argument surface + pinned headless defaults (free tier everywhere per Brief cost constraint). Seam-2 obligations: `*.local.*` overlay, recommended `.gitignore` line (`.claude/autonomy/**/*.local.*`), user-global → project → local resolution, infer-and-persist convention ladder. Written binding carries `schema-version`. |
+| `plugins/autonomy/skills/setup/SKILL.md` | Create | Setup contract (name `setup`, `disable-model-invocation: true`, `check` + `apply` actions, idempotent, non-interactive when complete arguments supplied). Scope: D7 discovery/interview of the adopting org's state (role homes present, substrate availability, budget posture); `apply` writes the discovered binding as tracked config `.claude/autonomy/` — **concern-named from day one** (concern = governed autonomous operation; a plugin split/rename leaves it valid; the versioned `docs/conventions/autonomy/` contract is deferred with trigger: second plugin consumes the config). Enumerated argument surface + pinned headless defaults (free tier everywhere per Brief cost constraint). Seam-2 obligations: `*.local.*` overlay, recommended `.gitignore` line (`.claude/autonomy/**/*.local.*`), user-global → project → local resolution, infer-and-persist convention ladder. Written binding carries `schema_version`. |
 | `plugins/autonomy/skills/setup/evals/evals.json` | Create | Warranted (setup precedent: `codebase-health/setup`). Cases: trigger/routing, discovery happy path, no-org terminal default, one non-interactive argument-supplied run, one refusal/guardrail (never assumes fleet shape). |
 
 **Sanity Check:**
@@ -135,7 +135,7 @@ path) live in SKILL.md/README, never in `reference/`.
 - `claude plugin validate` exit 0
 - `grep -c 'disable-model-invocation: true' plugins/autonomy/skills/setup/SKILL.md` = 1
 
-### Phase 5: Acceptance gates (in-repo) [TODO]
+### Phase 5: Acceptance gates (in-repo) [DONE]
 
 | File | Action | What changes |
 |---|---|---|
@@ -153,7 +153,7 @@ reviewed-and-accepted (first-party, MIT).
 **Sanity Check:**
 
 - All gate scripts exit 0
-- Scratch consumer repo contains `.claude/autonomy/` with a `schema-version` after the non-interactive run, with zero prompts issued
+- Scratch consumer repo contains `.claude/autonomy/` with a `schema_version` field after the non-interactive run, with zero prompts issued
 - Security-review record present in the PR body
 
 ### Phase 6: Fleet binding dogfood — standards PR [TODO]

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

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "autonomy",
+  "version": "0.1.0",
+  "description": "Governed autonomous agent operation: role-topology, binding-seam, and wiring-vs-advisor contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state and writes its schema-versioned binding.",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "license": "MIT",
+  "keywords": ["autonomy", "adoption", "governance", "topology", "binding", "guided-setup"]
+}

plugins/autonomy/README.md

@@ -0,0 +1,44 @@
+# autonomy
+
+Governed autonomous agent operation. This plugin is the capability-distribution home for the
+AI-adoption-ladder contract set: it ships the tool-agnostic contracts an adopting org binds to
+its own repositories, tools, and policies, plus a guided-setup skill that discovers the org's
+state and records that binding.
+
+## Shipped capability (0.1.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
+  wiring-vs-advisor principle governing how setup lands changes.
+- **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.
+
+## Roadmap (deferred, trigger-gated)
+
+Each capability below lands with its own work package; none ships before its contracts are
+locked (no step-skipping — trust before scale).
+
+| Capability | Trigger |
+|---|---|
+| Telemetry contract + setup slice | Telemetry work package build lands. |
+| Return-accounting convention + capture slice | Return-accounting work package build lands. |
+| Trigger/dispatch adapters | Trigger-layer work package build lands. |
+| 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). |
+
+## Trigger register (plugin-scoped)
+
+| Trigger | Action |
+|---|---|
+| Role vocabulary changes in `reference/role-topology.md` | Update the org-policy home's binding instance doc to the new vocabulary version. |
+| A second plugin consumes `.claude/autonomy/` config | Graduate the binding schema to a versioned concern contract per the marketplace's concern-named-folder convention. |
+
+## Configuration
+
+Setup writes tracked config to `.claude/autonomy/` in the consuming repo (concern-named — the
+config outlives any plugin restructure). Personal overlays follow the marketplace overlay
+convention: `.claude/autonomy/**/*.local.*` stays gitignored; layers resolve per the
+binding-seam ladder — user-global → org binding (when pointed) → project → local overlay —
+additively.

plugins/autonomy/reference/binding-seam.md

@@ -0,0 +1,53 @@
+# Binding seam
+
+Normative contract for how an adopting org maps the roles in `role-topology.md` (and every
+per-capability contract that follows) to its real instances — repositories, trackers, tools,
+policies. The contract defines the SHAPE of a binding; every concrete value is org-supplied.
+
+## Binding shape
+
+A binding is a written, schema-versioned record mapping contract vocabulary to org instances:
+each topology role to a repository, each capability's seam to the org's chosen instance, plus
+the org's declared postures (budget, substrate availability). Bindings carry a
+`schema_version` field from v0 — consumers read the version before the body, and schema
+changes are reviewed migrations. A role MAY be bound to null: an unborn role (one whose birth
+trigger has not fired) or a role the org has no instance for stays explicitly unbound —
+consumers treat null as absent capability and never invent an instance.
+
+The org-policy-home pointer is a repository locator that MAY carry an explicit document path
+(`<repo-locator>#<path>`). Absent a path, the consumer discovers the binding instance
+document at bind time (by its schema-versioned binding shape, per the org repo's own layout)
+and PERSISTS the resolved path alongside the pointer so later fetches are deterministic.
+
+## Resolution ladder
+
+A consumer resolves the effective binding as an ADDITIVE layer merge — a later layer adds to
+or refines earlier layers per value, never wholesale replacement:
+
+1. **User-global base** — the consumer's own machine-level binding config.
+2. **Org binding at the org-policy home** — the org's binding instance document. Reaching this
+   layer requires an org-policy-home pointer, which persists in repo-local or user-global
+   config; the fetch mechanism is the hosting platform's own CLI with the consumer's own
+   authentication (the contract grants no credentials).
+3. **Repo-local binding** — tracked config in the consuming repository (the concrete location
+   is a tool-specific detail the setup capability documents). Per value, this layer overrides
+   the org binding.
+4. **Local overlay** — the consumer's untracked personal refinement of the repo-local layer.
+
+A value no layer answers falls to the **setup interview**, which asks and persists the answer
+into the repo-local layer so the next resolution is deterministic.
+
+Terminal default when no org exists (solo adopter, no org-policy home): the merge degenerates
+to the local layers, populated with free-tier defaults — zero paid dependencies.
+
+## Known limitation
+
+The org-policy-home pointer can go stale when an org moves its policy home. A consumer that
+fails to fetch the org layer surfaces that failure (warned as not-considered) and falls to the
+remaining layers or the interview rather than silently reusing a cached org binding; setup
+re-records the pointer.
+
+## Layout convention
+
+Each capability this plugin ships lands exactly one contract document in `reference/` with its
+owning work package. The convention states shape only — it enumerates no future filenames.

plugins/autonomy/reference/role-topology.md

@@ -0,0 +1,38 @@
+# Role topology
+
+Normative contract for the repository roles an autonomy adoption spans. Contract text — here
+and in every sibling contract document — names roles only; the mapping from each role to an
+adopting org's real repository lives in that org's binding instance document (see
+`binding-seam.md`).
+
+## Roles
+
+| Role | Owns |
+|---|---|
+| capability-distribution home | The distributable capabilities and their contract documents — this plugin's own home. |
+| CI-orchestration home | Reusable pipeline execution logic: event handlers, emission steps, verification lanes. |
+| settings-as-code home | Declarative platform settings: labels, permissions, runner-policy admission, repository configuration. |
+| org-policy home | Org-wide policy and conventions, including the org's binding instance document. |
+| runner-execution home | The autonomous-runner execution substrate. **Unborn**: this role is created only when the runner charter's build trigger fires; until then no repository holds it. |
+
+## Adapter split rule
+
+A signal adapter (an event or schedule that starts governed autonomous work) splits by role:
+
+- **Handler logic** — the executable steps a pipeline runs — lands in the CI-orchestration home.
+- **Enabling settings** — labels, permissions, admission policy that let the handler fire —
+  land in the settings-as-code home. Admission-policy changes are reviewed contract changes,
+  never silent edits.
+
+## Composition stance
+
+This plugin composes existing capability seams rather than duplicating them:
+
+- the work-item queue, lease, and dispatch seam;
+- deterministic guardrail hooks;
+- verification gates;
+- session observability.
+
+A capability here that near-duplicates a capability an adopting deployment already has is a
+defect: compose the seam, or route a change to the seam's own home. Orchestration that
+composes existing capabilities is the sanctioned model.