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

[kyle-sexton]

Summary

WP1 (ai-ladder-wp1-packaging) implementation, phases 1–5 per its PLAN (in docs/topics/ai-ladder-wp1-packaging/PLAN.md, approved on #330):

• NEW marketplace category autonomy (domain-and-cross-cutting tier; singleton per the taxonomy's own governance clause, broaden-on-trigger row recorded) + CATEGORY_ORDER entry
• plugins/autonomy scaffold: manifest v0.1.0 scoped to shipped capability, marketplace entry, README with trigger-gated roadmap, regenerated catalog
• Topology contract docs in reference/: role-topology (five roles incl. unborn runner-execution), binding-seam (schema-versioned binding, three-rung resolution ladder, no-org free-tier terminal default), wiring-vs-advisor — tool-agnostic, vendor + fleet names banned
• Guided-setup v0 discovery skill (/autonomy:setup): check + apply, disable-model-invocation, enumerated argument surface with pinned headless free-tier defaults, writes schema-versioned .claude/autonomy/binding.json; five eval cases
• Standing validator gates: fleet-name sweep over plugins/autonomy/** + vendor deny-list over plugins/autonomy/reference/

Phase 6 (fleet binding instance doc) lands as a separate melodic-software/standards PR after this merges (dead-link avoidance, per plan).

Verification

• claude plugin validate --strict exit 0 (marketplace + plugin); node scripts/generate-catalog.mjs --check in sync
• node scripts/validate-plugin-contracts.mjs exit 0 (incl. the two new autonomy gates); bash scripts/run-plugin-tests.sh exit 0
• /skill-quality:check PASS on setup (1 advisory warning: no Gotchas surface — new skill, no failure history); check-jsonschema validates evals.json
• Migration-gate step 9 (scratch consumer repo, --plugin-dir, non-interactive apply --org-policy-home none --budget-posture free): completed with ZERO prompts, wrote schema-versioned .claude/autonomy/binding.json (schema_version: "1.0", org_policy_home: null, budget_posture: "free")
• markdownlint + typos clean over the new tree

Audits

• Near-duplicate audit: no autonomy skill duplicates an existing plugin capability — the plugin composes the work-item queue/lease, guardrail hooks, verification gates, and observability seams (role-topology composition stance); v0 ships only contracts + discovery setup.
• Security review (plugin-acceptance): no hooks, no MCP servers, no code execution, no network egress, no credential handling — markdown contracts + one interview skill writing tracked consumer config; MIT, first-party. Surfaces reviewed and accepted.

No linked issue

Related

• Plan record: docs/topics/ai-ladder-wp1-packaging/PLAN.md (docs(topics): ai-adoption-ladder contract set + WP1-WP3 plans #330)
• Effort index: docs/topics/ai-adoption-ladder/index.md

🤖 Generated with Claude Code

PLAN (published at effort-end close-out)

ai-ladder-wp1-packaging

Brief

TLDR

Packaging and topology for the AI-adoption-ladder machinery (T1–T7 contract set): role-vocabulary
repo topology, one new plugin as the single home composing existing plugin seams, and a
surface-based wiring-vs-advisor principle for guided setup.

Goal

Every ladder artifact has one owning home named by ROLE in contract text; fleet repo names appear
only in the binding-seam instance doc; the new plugin ships the contract docs and capabilities and
composes existing plugins without duplicating them.

Locked decisions

#	Decision
D1	Role vocabulary for repo topology: capability-distribution home, CI-orchestration home, settings-as-code home, org-policy home, runner-execution home (unborn; born only when the T4 build trigger fires).
D2	Contract docs + capabilities ship in the capability-distribution home. Fleet binding: claude-code-plugins marketplace.
D3	The platform-event signal adapter splits by role: handler logic = CI-orchestration home (fleet: ci-workflows reusables, GitHub events); enabling settings incl. labels, permissions, runner-policy admission = settings-as-code home (fleet: github-iac). The parenthesized fleet/vendor instances are binding-instance data for the Phase 6 binding doc ONLY — Phase 3's derivation of role-topology.md from this row copies the role sentences in surface-class vocabulary, never the parentheses; the Phase 5 standing gate and the vendor deny-list fail any leak.
D4	One new plugin (working name autonomy; final name via naming pass) is the single home for: contract docs, guided-setup capability, guardrail-matrix + org-binding seam, sandbox-ladder setup, telemetry contract, return-accounting convention, routine catalog + v1 definitions.
D5	The new plugin composes existing plugin seams — work-items (queue/lease/dispatch), guardrails (deterministic hooks), verification (gates), claude-ops (observability). Orchestration-composing-plugins is the sanctioned model; near-duplicate skill variants are banned.
D6	Wiring-vs-advisor principle: WIRE when the target surface is machine-editable + local + reviewable (repo files, settings, workflow files, IaC code) — wiring always lands as reviewable changes, never silent mutation. ADVISE (steps + cost surfaced) when the surface is org-external, entitlement-gated, paid, or GUI-only. Paid anything = advisory + explicit opt-in first, regardless of wireability.
D7	Adoption starts with discovery/exploration/interview of the adopting org's state — guided-setup owns that phase and never assumes fleet shape. Fleet = first adopting instance (dogfood).

Constraints

• Any fleet repo name in normative contract text is a defect; fleet names live only in the
  binding-seam instance doc.
• No new repos until the T4 build trigger fires.
• Plugin format is Claude-Code-specific; contract docs inside remain tool-agnostic markdown any
  org/tool can consume.
• Boris-alignment is the standing acceptance criterion (no step-skipping, trust before scale).
• No new cost without discussion; free defaults, paid = explicit opt-in surfaced first.

Acceptance criteria

• Contract text names roles only; a binding-seam doc maps each role to the fleet instance.
• New plugin clears the plugin-acceptance gates (plugin validate, contract tests, security review
  per MIGRATION-PLAYBOOK).
• No near-duplicate skill of an existing plugin capability exists in the new plugin.
• Every wiring path lands as a reviewable change.

Captured assumptions

• Split-later is cheap: renames map is append-only and many-to-one is verified legal, so the
  single-plugin decision is reversible.
• Marketplace distribution suffices for universality: any org can install from the marketplace;
  non-Claude-Code orgs consume the contract markdown directly.

Out-of-scope (deferred with triggers)

• Runner-execution home creation — trigger: T4 build trigger fires (WP7 owns the design pack).
• Org-enablement track beyond fleet dogfood — trigger: day-job adoption becomes concrete.

Deferred questions

• Final plugin name + category assignment (category possibly new and broader — not article-tied;
  D22 category vocabulary governs) — /architect.
• Contract-doc file layout inside the plugin (docs/ vs skill context/) — /architect.
• Per-capability wiring depth — resolved per-package in WP2–WP6 Briefs.

Plan

Interview-locked this round: plugin name autonomy; NEW marketplace category autonomy
(singleton, justified by the taxonomy's own singleton-governance clause); WP1 materializes
topology contract docs only (per-capability contracts land with WP2–WP6); guided-setup ships
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 [DONE]

File	Action	What changes
docs/CATALOG-TAXONOMY.md	Modify	Add autonomy to the domain-and-cross-cutting tier — gloss: governed autonomous agent operation (adoption discovery, guardrails, standing routines, autonomy telemetry/return contracts). Singleton justified via the doc's singleton-governance clause (honest distinct label; label predicts member). Trigger-register row: a broader automation plugin lands → broaden or add a sibling category then.
scripts/generate-catalog.mjs	Modify	Add autonomy to CATEGORY_ORDER (line 23), position mirroring the taxonomy doc's tier ordering.

Sanity Check:

• grep -c '\autonomy`' docs/CATALOG-TAXONOMY.md` ≥ 1
• grep -n 'autonomy' scripts/generate-catalog.mjs shows a CATEGORY_ORDER entry

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
the first commit.

File	Action	What changes
plugins/autonomy/.claude-plugin/plugin.json	Create	v0.1.0, MIT, first-party author. Description scoped to what 0.1.0 ships (topology contracts + adoption discovery) — NOT the full D4 roadmap (no-step-skipping in catalog copy). No fleet repo names.
.claude-plugin/marketplace.json	Modify	Entry: source: ./plugins/autonomy, category: autonomy.
plugins/autonomy/README.md	Create	Shipped capability; D4 seven-capability roadmap as deferred-with-WP-triggers (repo trigger-register idiom); trigger row: role vocabulary changes → update the org-policy-home binding doc.
README.md	Modify	Regenerated catalog (node scripts/generate-catalog.mjs).

Sanity Check:

• claude plugin validate --strict <repo-root> exit 0
• 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 [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
org-binding doc (Phase 6); tool-specific materialization details (e.g. the .claude/autonomy/
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 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:

• grep -riE 'melodic-software|ci-workflows|github-iac' plugins/autonomy/reference/ empty
• Vendor deny-list grep empty over reference/ — grep -riE 'github|gitlab|bitbucket|slack|anthropic|claude|openai|copilot|cursor|devin' plugins/autonomy/reference/ (surface classes replace all of these; list pairs with PR review for completeness)
• 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 [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/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:

• /skill-quality:check and validate-evals pass with skills_root = plugins/autonomy/skills
• claude plugin validate exit 0
• grep -c 'disable-model-invocation: true' plugins/autonomy/skills/setup/SKILL.md = 1

Phase 5: Acceptance gates (in-repo) [DONE]

File	Action	What changes
scripts/validate-plugin-contracts.mjs	Modify	Promote the fleet-name sweep to a standing gate scoped to plugins/autonomy/**: org token melodic-software + bare repo names (ci-workflows, github-iac), excluding plugin.json author metadata. Also gate the Phase 3 vendor deny-list as a standing check scoped to plugins/autonomy/reference/ — the tool-agnostic guarantee must not depend on one-off greps.

Gate run: scripts/validate-plugins.sh; scripts/run-plugin-tests.sh (verified: no per-plugin
test file required); node scripts/validate-plugin-contracts.mjs; markdown/typos/lychee lanes;
claude plugin validate --strict. Migration-gate step 9: clean consumer repo (NOT this repo),
claude --plugin-dir ./plugins/autonomy, exercise /autonomy:setup on its argument-supplied
non-interactive path — must complete without prompting and write a schema-versioned
.claude/autonomy/ binding. Near-duplicate audit: statement that no autonomy skill duplicates
an existing plugin capability. Security review: surfaces 2/5/7 untouched; surface 6
reviewed-and-accepted (first-party, MIT).

Sanity Check:

• All gate scripts exit 0
• 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 [DONE]

Runs AFTER the plugin PR merges (dead-cross-repo-link avoidance). First work item —
pre-flight: read standards' own conventions/docs layout and pick the target path per ITS
rules (no agent-operations section exists today; placement follows that repo's charter, not an
assumption).

Deliverable: the fleet binding instance doc in melodic-software/standards — each D1 role →
fleet instance (capability-distribution → the claude-code-plugins marketplace;
CI-orchestration → ci-workflows; settings-as-code → github-iac; org-policy → standards itself;
runner-execution → unborn, T4 birth trigger recorded). The doc records the role-vocabulary
version it binds and cites role-topology.md. Fleet names appear ONLY here among WP1
deliverables.

Sanity Check:

• Doc exists in the standards PR; one grep hit per D1 role name
• Doc contains the role-vocabulary version marker
• grep -riE 'ci-workflows|github-iac' plugins/autonomy/ still empty (post-merge re-check)

Blast radius

MEDIUM — ~12 files across 2 repos; new category + contract docs constrain WP2–WP6 (each of
which has its own architect round); fully git-revertible; automated gates (validate, contract
tests, CI lanes) cover the shared surfaces.

Stress-test summary

Step 3 fresh-context plan review: 10 findings (1 CRITICAL — D6 dropped; fixed by
wiring-vs-advisor.md). Step 4 /devils-advocate: 0 CRITICAL / 3 HIGH / 5 MEDIUM / 3 LOW — all
folded into the phases above (whole-tree fleet-name sweep + standing gate; concern-named
config folder from day one; resolution-ladder pointer/fetch/terminal-default mechanics;
argument surface + headless defaults + non-interactive eval; schema-versioned binding;
description scoped to shipped capability; standards pre-flight + drift trigger + plugin-first
merge ordering). Residuals accepted: vendor deny-list completeness pairs with review;
cross-repo drift recheck is trigger-based (deferred-with-trigger: mechanical cross-repo check
when a second binding consumer exists); bare word "standards" ungrepable — org-qualified
token + review covers it.

Execution shape

Fully sequential 1 → 2 → 3 → 4 → 5 → 6 — Phase 2's marketplace entry needs Phase 1's category;
Phase 4 cites Phase 3's binding shape; Phase 5 gates the authored tree; Phase 6 waits on the
plugin PR merge. Parallel saving immaterial (small doc volume).

Phase	Surface	Basis
1–4	main-session	judgment-heavy contract/doc authoring, tightly coupled to design threads
5	main-session	gate runs + one shared-script edit
6	main-session	cross-repo PR with pre-flight judgment

Open questions

None blocking. Deferred with triggers: docs/conventions/autonomy/ versioned config contract
(trigger: second plugin consumes .claude/autonomy/); mechanical cross-repo drift check
(trigger: second binding consumer); per-capability wiring depth (WP2–WP6 Briefs, per Brief).

Handoff to implementation

User-approval gates

• Phase 5's validate-plugin-contracts.mjs edit adds a standing CI gate — flagged
  [EXEC-SHAPE]; surface before landing if scope beyond plugins/autonomy/** is proposed.
• Phase 6 pre-flight outcome: if standards' conventions resist the binding doc (charter
  mismatch), STOP and re-surface placement rather than improvising a location.
• Any scope expansion beyond the six phases re-enters /architect review.

Execution shape ([EXEC-SHAPE] tagged)

Sequential, all main-session (table above). Decisions made under the confidence gate:
reference/ as contract-doc home (10 in-repo precedents + reference-vs-context semantic split);
concern-named .claude/autonomy/ (extensibility-contract rationale: plugin boundaries are the
volatile axis); full vendor+fleet name ban in reference/ with tool-specific details in
SKILL.md/README (Brief tool-agnostic constraint); description scoped to shipped capability
(Boris no-step-skipping); schema-versioned binding (version-pinning rules + standards-contract
precedent); two-PR split with plugin-first ordering (dead-link avoidance).

Mechanical work

Commit per phase on the implementation branch (suggest feat/autonomy-plugin); PLAN.md phase
tags advance [TODO] → [DOING] → [DONE] in the same commit as the phase; gates re-run at
Phase 5 even if run earlier; no commits without the repo's commit conventions.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c9a59c9cae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 14s —— View job

---

PR Review — feat(autonomy) WP1

• Gather context and understand the request
• Read changed files
• Review binding-seam schema key mismatch (flagged by Codex)
• Review plugin manifest and marketplace entry
• Review topology contract docs
• Review guided-setup skill and evals
• Review standing validator gates
• Post findings

---

Summary

Overall the PR is well-structured and the design is sound — tool-agnostic contracts, correct plugin-form isolation (${CLAUDE_PLUGIN_ROOT}), zero egress/execution surface, and the validator gates are a nice addition. One correctness bug needs fixing before merge; two minor observations follow.

---

Correctness Bug — Schema Key Mismatch

The Codex finding is accurate and this needs a fix before merge.

plugins/autonomy/reference/binding-seam.md:12 uses schema-version (hyphen):

Bindings carry a schema-version field from v0 — consumers read the version before the body…

But the writer (SKILL.md:55) and every eval expectation consistently use schema_version (underscore):

• plugins/autonomy/skills/setup/SKILL.md:55: "apply writes … carrying schema_version (from "1.0")"
• evals.json:22: "Written binding carries schema_version" (eval fix: correct plugin-system inaccuracies and harden references #2)
• evals.json:39: "Writes or idempotently updates .claude/autonomy/binding.json with schema_version" (eval feat: markdown-formatter plugin (pilot migration) #3)

The normative contract is the authority — when a downstream reader follows binding-seam.md and looks for schema-version, it won't find the field the skill wrote as schema_version. The fix is one word in the contract doc:

-Bindings carry a `schema-version` field from v0 — consumers read the version before the body,
+Bindings carry a `schema_version` field from v0 — consumers read the version before the body,

Fix this →

---

Minor Observations

1. No validator asserts schema-key consistency going forward.
scripts/validate-plugin-contracts.mjs doesn't assert that binding-seam.md uses the same field name as SKILL.md. Fixing the doc now removes the immediate bug, but a future edit could silently re-introduce the divergence. A one-line grep gate in the validator (e.g. checking schema_version appears in both files) would close the gap permanently. This is a suggestion, not a blocker.

2. vendorTokens regex includes claude — potential future false positive on reference/ docs.
validate-plugin-contracts.mjs:209: /github|gitlab|bitbucket|slack|anthropic|claude|openai|copilot|cursor|devin/i would trigger on ${CLAUDE_PLUGIN_ROOT} or similar runtime variables if a future reference/ doc ever uses them (e.g. to link to the setup skill). Not a problem today since all three reference docs avoid those tokens, but worth noting for anyone extending the contract set.

---

Everything else looks clean

• Plugin manifest (plugin.json) is correctly minimal — skills are discovered by convention, no explicit listing needed.
• Marketplace entry correctly sets "category": "autonomy" with a matching CATEGORY_ORDER entry in generate-catalog.mjs — consistent with CATALOG-TAXONOMY.md ordering.
• disable-model-invocation: true is present in SKILL.md frontmatter; the standing validator at line 39 enforces this.
• Fleet-name and vendor-name gates are scoped correctly: fleet check covers all plugins/autonomy/** except plugin.json; vendor check covers only reference/.
• Resolution-ladder rung-3 fallthrough on stale org-policy-home (re-run setup to re-record pointer) is the correct fail-open design.
• No hooks, no MCP servers, no code execution, no network egress — plugin-acceptance security review criteria met.
• ${CLAUDE_PLUGIN_ROOT} used correctly in SKILL.md cross-links; no ../ reach-outs, no hardcoded paths.

Verdict: merge after fixing the schema-version → schema_version typo in binding-seam.md.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 27312c8298

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 24s —— View job

---

• Verify schema_version fix in binding-seam.md
• Assess Codex P2 finding chore: initialize marketplace scaffold #1: check mode missing org-policy-home rung (SKILL.md:24)
• Assess Codex P2 finding fix: correct plugin-system inaccuracies and harden references #2: binding write uses relative path (SKILL.md:55)
• Assess Codex P2 finding feat: markdown-formatter plugin (pilot migration) #3: plugin.json fleet-token exemption too broad (validate-plugin-contracts.mjs:212)
• Post findings

---

Round 2 Review — commit 27312c8

The schema_version fix is correct — binding-seam.md:12 now reads schema_version (underscore), matching the writer and all evals. That blocker is resolved.

---

Codex P2 Assessment

Finding #1 — SKILL.md:24: check mode description overstates completeness

PLAUSIBLE — not a hard bug, but the description is inaccurate for org adopters.

The check action is described as resolving "the effective binding" across user-global → project → local overlay. But binding-seam.md rung 2 (org-policy-home fetch via the host platform CLI) is absent from check mode. An org adopter with org_policy_home set in their local binding and role values only in the remote org-policy doc would see all those role values reported as "missing" — not because they're absent, but because check never fetches rung 2.

This is a v0 scoping decision: fetching remote org-policy requires the host CLI and consumer auth, which is out of scope for v0. But describing the result as "the effective binding" is misleading. A one-line doc fix resolves this:

- resolve the effective binding across layers — user-global
+ resolve the effective binding from local layers — user-global

And a follow-up sentence: "Rung 2 (org-policy-home) is not fetched in check mode; its pointer is shown if present."

Fix this →

---

Finding #2 — SKILL.md:55: binding write uses relative path — CONFIRMED

This one is real. SKILL.md:55:

apply writes .claude/autonomy/binding.json

This is a skill instruction to Claude. If Claude invokes a file-write tool with a relative path, the anchor is wherever Claude Code's CWD is at the time — which is not guaranteed to be the repo root when invoked from a subdirectory, a monorepo package, or certain IDE contexts. The binding lands in the wrong place and consumers resolving from ${CLAUDE_PROJECT_DIR} silently miss it.

The fix is one word — anchor it explicitly:

-`apply` writes `.claude/autonomy/binding.json`, carrying `schema_version` (from `"1.0"`),
+`apply` writes `${CLAUDE_PROJECT_DIR}/.claude/autonomy/binding.json`, carrying `schema_version` (from `"1.0"`),

The same correction should apply to the mention of .claude/autonomy/binding.local.json two lines later (line 57) and the check layer paths at lines 22–23 (~/.claude/autonomy/ is absolute; .claude/autonomy/ is not). The lines in question:

Line	Current	Fix
55	.claude/autonomy/binding.json	${CLAUDE_PROJECT_DIR}/.claude/autonomy/binding.json
57	.claude/autonomy/binding.local.json	${CLAUDE_PROJECT_DIR}/.claude/autonomy/binding.local.json
23	.claude/autonomy/ (project layer)	${CLAUDE_PROJECT_DIR}/.claude/autonomy/
24	.claude/autonomy/**/*.local.*	${CLAUDE_PROJECT_DIR}/.claude/autonomy/**/*.local.*

Fix this →

---

Finding #3 — validate-plugin-contracts.mjs:212: fleet-token exemption too broad — PLAUSIBLE, low risk today

The continue at line 212 skips the entire plugin.json from fleet-token checking. The exemption exists because "author": {"name": "Melodic Software", "email": "info@melodicsoftware.com"} legitimately contains melodic-software. But it also silently exempts description and keywords from fleet-token checks.

Current plugin.json is clean — description and keywords contain no fleet tokens. But a future "keywords": ["github-iac"] would pass unchallenged.

A targeted fix parses the manifest and only exempts author fields:

if (path.endsWith(`${sep}.claude-plugin${sep}plugin.json`)) {
  // Author block is allowed to contain publisher identifiers; description/keywords are not.
  const { description = '', keywords = [] } = JSON.parse(read(path));
  const checkText = [description, ...keywords].join(' ');
  if (fleetTokens.test(checkText)) {
    fail(path, "autonomy plugin manifest description/keywords must not name the org or fleet repos");
  }
  continue;
}

Not a blocker given the current content, but closes a gap that would otherwise require a human to catch.

---

Verdict

Finding	Verdict	Blocker?
schema_version fix	✅ Fixed	was blocking, now resolved
check mode description overstates completeness	PLAUSIBLE	No — v0, doc-only fix
Relative .claude/autonomy/ paths in SKILL.md	CONFIRMED	Recommend fix before merge
plugin.json fleet-token exemption too broad	PLAUSIBLE	No — current content is clean

Recommend: fix the relative-path anchoring in SKILL.md (finding #2) before merge — it's a two-minute change that prevents a silent misplacement. The other two are improvements worth making but not blocking.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0f0d012918

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d5003371b3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 4m 4s —— View job

---

Round 3 Review — commit d500337

• Read changed files in their current state
• Assess Codex P2 finding: org binding document location not standardized (SKILL.md:39)
• Assess Codex P2 finding: unborn roles need null/unbound support in binding shape (binding-seam.md:10)
• Verify all prior findings are resolved
• Post findings

---

Prior findings — all resolved

Round	Finding	Status
R1	schema_version key mismatch in binding-seam.md	✅ Fixed in 27312c8
R2	check description overstated completeness (no org rung)	✅ Fixed in 0f0d012
R2	Relative .claude/autonomy/ write paths in apply	✅ Fixed in 0f0d012
R2	plugin.json fleet-token exemption too broad	✅ Fixed in 0f0d012
R3-Codex	Binding ladder was winner-takes-all instead of additive merge	✅ Fixed in d500337

The binding-seam.md resolution ladder now correctly describes a four-layer additive merge (user-global → org → repo-local → local overlay), matching SKILL.md and matching the terminal-default solo-adopter case.

---

Outstanding Codex P2 Findings

Finding #1 — Org binding document location (SKILL.md:39) — PLAUSIBLE, deferred

When check resolves rung 2, it needs to know which file within the org-policy-home repo to fetch. binding-seam.md:21 names "the org's binding instance document" but never standardizes its path. An implementation following the contract — without reading the Phase 6 standards PR — can't know whether to look for .claude/autonomy/binding.json, autonomy-binding.json, or something else at the org-policy home.

Disposition: intentionally deferred per plan. The PR description explicitly states "Phase 6 (fleet binding instance doc) lands as a separate melodic-software/standards PR after this merges (dead-link avoidance, per plan)." That Phase 6 document is where the filename convention is established. The gap is real but acknowledged.

A small doc improvement would close the gap without a blocker: add one sentence to binding-seam.md's existing Known Limitation section noting that the org binding filename convention is defined in the org-policy-home's own instance document (standardized in the binding instance doc, Phase 6). This is a suggestion, not a blocker.

---

Finding #2 — Unborn roles must be representable in the binding shape — CONFIRMED

binding-seam.md:9 reads:

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…

But role-topology.md:16 marks runner-execution home as Unborn — it has no repository until the runner charter fires. And evals.json:62 already expects the skill to handle this correctly: "Asks or records unbound for role homes it cannot infer."

The three-way inconsistency is real: the normative contract says "each role → a repository" with no carve-out; the topology contract says one role may have no repository; the eval expects "unbound" to be a valid binding state. A downstream consumer implementing binding resolution from binding-seam.md alone would have no basis to emit runner_execution_home: null — they'd be forced to either invent a repo or reject the binding as malformed.

Recommend fixing before merge — it's a single-sentence clarification:

-each topology role to a repository, each capability's seam to the org's chosen instance,
+each topology role to a repository (or an explicit unbound marker when the role is not yet
+instantiated — see `role-topology.md`), each capability's seam to the org's chosen instance,

Fix this →

---

Everything else looks clean

After four rounds of review the PR is in good shape:

• Binding ladder in binding-seam.md is now additive merge, identical semantics to SKILL.md — the d500337 fix resolved the Codex finding cleanly.
• apply path anchoring in SKILL.md explicitly resolves ${CLAUDE_PROJECT_DIR} before writing — subdirectory invocations can't create nested .claude/autonomy/.
• Fleet-token gate now strips only the author block from plugin.json before testing; description, keywords, and all other fields stay gated.
• check mode correctly describes all four resolution rungs including the org fetch with auth, and correctly warns on unreachable org-policy-home rather than silently skipping it.
• Validator gates (disable-model-invocation, fleet-name sweep, vendor deny-list) all look correct.

Verdict: Fix the unbound-role carve-out in binding-seam.md (Finding #2) before merge — it's a one-sentence change that removes a genuine inconsistency between the normative contract and the topology + eval behavior. Finding #1 (org binding filename) is phase-6-deferred and acceptable as-is.

[claude]

Claude finished @kyle-sexton's task in 2m 36s —— View job

---

Round 4 Review

• Check current state of changed files
• Confirm R3 outstanding finding still present
• Prepare fix (note: push access not granted — diff below for manual apply)
• Post findings

---

One remaining fix needed — binding-seam.md:10

The unborn-role carve-out identified in Round 3 is still unaddressed. The normative contract at binding-seam.md:9-10 reads:

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…

This remains inconsistent with:

• role-topology.md:16 — runner-execution home is Unborn until the runner charter fires; no repository exists for it yet
• evals.json:62-65 — eval feat(hook-telemetry): marketplace-wide telemetry contract + markdown-formatter producer #5 expects the skill to "Asks or records unbound for role homes it cannot infer"

A downstream consumer implementing binding resolution from this contract alone has no basis to emit runner_execution_home: null — the contract as written says every role maps to a repository.

Apply this diff:

-each topology role to a repository, each capability's seam to the org's chosen instance, plus
+each topology role to a repository (or an explicit unbound marker when the role is not yet
+instantiated — see `role-topology.md`), each capability's seam to the org's chosen instance, plus

Fix this →

---

Everything else is clean

All prior findings from rounds 1–3 are resolved:

Round	Finding	Status
R1	schema_version key mismatch in binding-seam.md	✅ Fixed
R2	check description overstated completeness (no org rung)	✅ Fixed
R2	Relative .claude/autonomy/ write paths in apply	✅ Fixed
R2	plugin.json fleet-token exemption too broad	✅ Fixed
R3	Binding ladder was winner-takes-all instead of additive merge	✅ Fixed
R4	Unborn roles not representable in the binding shape	⬛ Pending

Verdict: one-line fix to binding-seam.md:10 and this is mergeable.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 01a24bb62c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 057fcef60f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9fa88cdd3f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a168c1858

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 15s —— View job

---

Round 5 Review

• Read current SKILL.md and binding-seam.md
• Assess Codex P2 finding chore: initialize marketplace scaffold #1: serialized role-map keys not defined (SKILL.md:67)
• Assess Codex P2 finding fix: correct plugin-system inaccuracies and harden references #2: user-global binding file not standardized (SKILL.md:22)
• Post findings

---

Prior findings — all resolved

All findings from rounds 1–4 are confirmed resolved in the current state of the branch:

Round	Finding	Status
R1	schema_version key mismatch in binding-seam.md	✅ Fixed
R2	check description overstated completeness (no org rung)	✅ Fixed
R2	Relative .claude/autonomy/ write paths in apply	✅ Fixed
R2	plugin.json fleet-token exemption too broad	✅ Fixed
R3	Binding ladder was winner-takes-all instead of additive merge	✅ Fixed
R3/R4	Unborn roles not representable in the binding shape	✅ Fixed — null explicitly allowed
R4	Org binding document path not standardized	✅ Fixed — #<path> locator syntax added
(later)	Check eval missing org rung	✅ Fixed
(later)	Layer summary in SKILL.md omitted org rung	✅ Fixed
(later)	Purpose sentence referenced wrong ladder position	✅ Fixed
(later)	README missing org layer in merge order	✅ Fixed

---

Round 5 Codex P2 Assessment

Finding #1 — SKILL.md:67: Serialized role-map keys not defined — PLAUSIBLE, v0-deferred

The finding is accurate: SKILL.md:64-70 describes the written binding payload in prose ("the role→instance map") but never gives a concrete JSON shape or enumerates field names. A downstream consumer asking "does runner-execution home serialize as runner_execution_home or runner-execution-home or runnerExecutionHome?" gets no answer from this contract alone.

That said, this is correctly v0-deferred for three reasons:

1. No compiled consumers exist yet. The PR explicitly states capability slices (telemetry, capture, adapters) land in later work packages and will extend this skill when they ship — each of those PRs is the natural gate for standardizing the key encoding they read.
2. The skill is disable-model-invocation: true. Claude implements both apply (writer) and check (reader) — the same model writes and reads the keys within v0, so encoding drift can't occur between now and WP2.
3. schema_version is present. When WP2 defines the schema concretely, it can bump schema_version and document the encoding migration cleanly.

The gap is real and worth tracking, but it is not a correctness bug today. Suggest adding a JSON example to binding-seam.md's Binding shape section when the first capability consumer PR lands — that PR is the natural milestone.

---

Finding #2 — SKILL.md:22: User-global binding file not standardized — PLAUSIBLE, v0-deferred

SKILL.md:21-22 names ~/.claude/autonomy/ as the user-global layer directory but no file within it. binding-seam.md:27 describes rung 1 as "the consumer's own machine-level binding config" without naming a file.

The gap is latent but not active today:

• No user-global binding writer exists in v0. apply writes only ${CLAUDE_PROJECT_DIR}/.claude/autonomy/binding.json. No code or skill creates ~/.claude/autonomy/<anything> — so there is nothing to read yet at rung 1.
• Claude implementing check naturally looks for binding.json by analogy with the project layer, which is named explicitly. The non-determinism risk is real for future compiled consumers but not for the current AI-implemented skill.

Like finding #1, the right fix arrives with the first PR that writes to the user-global layer (presumably a user-scoped defaults command in a later work package). That PR should standardize ~/.claude/autonomy/binding.json and the pattern is already visible from the project-local convention.

---

Verdict

Both Codex P2 findings from the latest round are PLAUSIBLE but correctly v0-deferred — no active correctness bug exists in the shipped behavior, and both gaps are naturally resolved by the first work-package PR that either writes a user-global binding or introduces a compiled capability consumer. The schema_version mechanism provides the migration path when the schema is concretized.

The PR is clean for merge in its current state.