docs(topics): ai-adoption-ladder contract set + WP1-WP3 plans#330
Merged
Conversation
Design-handoff gate passed 2026-07-17: all seven design threads (T1 trigger layer, T2 sandbox bar, T3 guardrail matrix, T4 runner charter, T5 return accounting, T6 telemetry unification, T7 standing routines) RESOLVED with recorded rationale; all seven work-package Briefs locked with every deferred question tagged and routed (/architect, build stage, or USER-RESERVED). Plan sections intentionally unfilled - the architect stage fills them next. Graduates the durable design artifacts from gitignored session memory into the topic's design slice: design-threads.md (contract record), nine RESEARCH-*.md evidence files, and the captured Boris Cherny "Steps of AI Adoption" source artifact (Jul 16 2026; live endpoint unreliable, capture is the re-anchor copy). Session working memory (checklists, drafts) stays in .work/. Live pointers updated in index.md and the WP3 Brief; provenance notes inside dated research snapshots left verbatim. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Six sequential phases: autonomy category + generator, plugin scaffold, topology contract docs (role-topology, binding-seam, wiring-vs-advisor), guided-setup v0 discovery skill, in-repo acceptance gates, fleet binding dogfood via standards PR (plugin-first merge ordering). Stress-tested: fresh-context plan review (D6 drop + CATEGORY_ORDER caught) and devils-advocate (3 HIGH folded: whole-tree fleet-name sweep as standing gate, concern-named .claude/autonomy/ from day one, binding-ladder pointer/fetch/terminal-default mechanics). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Telemetry (WP2) and return-accounting (WP3) Plan sections filled and approved: join key autonomy.work_item.url (canonical item URL, resource-scoped on sessions, span-scoped on CI), semconv pin v1.43.0, free-default file-artifact path incl. ephemeral per-job collector and emission-conformance check, six-band effort scale, async attestation lifecycle with record-integrity and attestation-rate clauses. design-threads T5/T6 carry dated supersession notes (band set, join attribute sharpening). Both stress-tests folded: fresh-context plan review (1 CRITICAL - cost join undemonstrable) and devils-advocate (3 CRITICAL / 4 HIGH), with two user-locked reversals (six bands; keep-URL plus hardening rules). Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e3888830eb
ℹ️ 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".
"mis-attributed" tripped the typos lane; the boris capture carried a UTF-8 BOM, CRLF endings, tab indentation, and no final newline. Whitespace/encoding normalization only - capture content unchanged. Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: df99f701eb
ℹ️ 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".
Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 62be3261a6
ℹ️ 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".
kyle-sexton
added a commit
to melodic-software/ci-workflows
that referenced
this pull request
Jul 18, 2026
## Summary The `do-not-merge-gate` reusable's live label refetch ran `gh api` in a run step. The gate executes on whatever runner the caller selects, and a self-hosted image is not guaranteed to ship the gh CLI — observed on melodic-software/claude-code-plugins#330: exit 127 `gh: command not found` failed the required check with no blocking label present. This ports the step to `actions/github-script` (same SHA-pinned v9.0.0 the `pr-issue-linkage` reusable already uses on the same runners). The merge_group PR-number parse, live-refetch semantics, and error messages are unchanged; the runtime is the action's bundled Node, removing the runner-image tooling dependency. Other reusables still call `gh` (claude-review, link-check, queue-monitor-liveness, tool-version-drift-check); they are out of scope here — this fixes the one gate observed failing as a required consumer check. No linked issue ## Related - Failure observed on melodic-software/claude-code-plugins#330 (`do-not-merge / do-not-merge`, exit 127) ## Verification - `actionlint` clean; `zizmor` no findings on the edited workflow - Logic port is 1:1 (parse → live refetch → label test → identical error strings) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 (1M context) <noreply@anthropic.com>
Five review-thread fixes: attestation-preserving upsert/dedup (a re-fired close never downgrades an attested record); Brief D4 carries the dated six-band supersession instead of silently disagreeing with the Plan; interactive sessions covered on the free-default telemetry path (local collector to a query-on-read store); attested_by captured from the attestation source event since the comment-floor upsert actor is the bot; WP3 demo substitutes the committed fixture's join URL with the live demo item URL as input prep. Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b68f0baaf0
ℹ️ 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".
… DET dead-code) WP1 D3 marks its fleet parentheses as binding-instance data excluded from the role-topology derivation (Phase 5 gate enforces); WP3's captured assumption carries the six-band supersession instead of the stale five-band claim; WP6 D4 strikes dead-code sweep from the v1 routine roster per the DET-detect classification (research row 25) — detection is cron + work-item filing, judgment folds into tech-debt. Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 218c903385
ℹ️ 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".
T7's v1 roster drops dead-code sweep with the dated DET-detect correction (matching WP6 D4), and WP3's gate-passed decisions row now states the attestation-preserving dedupe rule instead of the superseded latest-record-wins wording. Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c67a92c03d
ℹ️ 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".
WP1 D3 speaks surface-class vocabulary (platform-event signal adapter) with the vendor qualifier moved into the binding-instance parentheses; the WP2 conformance check matches the OTLP JSON lowerCamelCase schemaUrl key, not proto snake_case, per the OTLP JSON encoding. Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8ebe1343f4
ℹ️ 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".
…r gate, governed namespace extension) WP3 Brief D3 resolves its work-item-ID wording to the locked canonical URL; WP1 Phase 5 promotes the vendor deny-list to a standing validator check over reference/; WP2's minimality clause permits sibling contracts governed additions under autonomy.* instead of forbidding the WP7 escalation fields outright. Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b123a0ba13
ℹ️ 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".
Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bc5e75eda4
ℹ️ 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".
|
|
||
| | File | Action | What changes | | ||
| |---|---|---| | ||
| | `plugins/autonomy/reference/telemetry.md` | Create | The T6 contract as tool-agnostic normative text: (1) every execution context class (interactive session, CI, autonomous runner) emits standard OTLP pinned to the OTel CI/CD + VCS semantic conventions — pin recorded as semconv release `v1.43.0` with `schema_url: https://opentelemetry.io/schemas/1.43.0` on every emission; attributes cited by registry reference, never hand-copied lists; RC caveat + reviewed-migration policy for upstream renames (D4). (2) The work-item join attribute: single custom attribute `autonomy.work_item.url`, value = the work item's canonical web URL in normalized form (the tracker's own canonical item URL: https scheme, no trailing slash, no query string or fragment) — string equality is the join operation, so the normalization rule is normative. Selection rule: the key is always the WORK ITEM's URL, never a PR/change URL; a change closing N items yields N per-item associations; an agent session keys on its leased item. Attribute SCOPE pinned per context: RESOURCE-scope on agent-session emission (so cost/token metrics and session spans all carry it), span-scope on the CI pipeline/task spans. Granularity guarantee: conforming autonomous dispatch runs ONE leased work item per emitting session/process (the trigger-layer lease contract is the guarantor); multi-item batch sessions get session-granular cost only — stated as a known limitation, not silently misattributed. Known join-epoch limitations stated normatively: repo rename/transfer and tracker migration change the canonical URL; the join is query-time, so sinks MAY remap historical values; a secondary immutable-ID attribute is deferred with trigger (rename churn proves material). Confidentiality clause: the attribute value inherits the confidentiality class of the referenced repo/tracker — any sink or artifact carrying it must enforce access controls at least as strict as the item's home. No other custom namespace is defined by THIS contract; a sibling capability contract in the same home MAY define its own additions under the same `autonomy.*` prefix and governance (reviewed contract changes, no-parallel-schema rule) — minimality binds this contract, it does not forbid governed extension. No-parallel-schema migration rule if upstream ships a tracker namespace; contract migrations (including the semconv-Stable rename wave when cicd/vcs graduate) are reviewed changes owned by the contract home, trigger recorded in the plugin's trigger register. (3) W3C TRACEPARENT propagation trigger → CI → agent session forms one causal tree; headless/CI-only property — interactive contexts explicitly excluded from inbound trace joining. Sink binding out of contract: three sink classes only (existing observability stack / OTLP-file-artifact free default with query-on-read / opt-in network backend), adapter obligations per class stated as shape, no vendor picks. Native-surface principle (D7): prefer each tool's native telemetry export; reimplementations of native surfaces are non-conforming. Telemetry-is-not-return boundary note (T5 seam). Zero vendor/fleet names — tool-specific mechanics live in SKILL.md. | |
There was a problem hiding this comment.
When a PR/CI run closes multiple work items, this contract requires a singular string-valued autonomy.work_item.url and a string-equality join, but also says the change yields N associations. Without a repeatable association shape (array with explode semantics, one child span per URL, etc.), implementers must either record one URL and lose N-1 joins or duplicate run/session cost across items, which breaks WP3 cost joins for multi-item changes.
Useful? React with 👍 / 👎.
|
|
||
| | File | Action | What changes | | ||
| |---|---|---| | ||
| | `plugins/autonomy/reference/return-accounting.md` | Create | The T5 convention as tool-agnostic normative text. Three-layer data model (D2) with the never-estimate rule and its conditional revisit trigger. Record schema (D3): `schema_version` (string, from v1 — hook-envelope precedent), `work_item_url` (the join key; value contract defined by the telemetry contract's `autonomy.work_item.url` — pointer, not restated), `attested` (boolean), `counterfactual` (`yes` \| `no` \| `partial`), `effort_band` (six contiguous ordinal tokens: `<1h`, `1-4h`, `4h-1d`, `1d-1w`, `1w-1mo`, `>1mo` — user-locked 2026-07-18 on stress-test evidence, superseding D4's five-band set: the open `>1w` top band erased the largest avoided-effort signal; serialized as those exact strings, ordinal order defined by the contract, never lexical), `attested_at` (ISO 8601 UTC), `attested_by` (the attesting human's platform identity, captured from the attestation action), `attestor_role` (`requester` \| `reviewer` \| `maintainer` \| `other`). Composition rule: `effort_band` answers the manual-cost question for the WHOLE delivered item regardless of `counterfactual` value; `partial` qualifies the counterfactual only — aggregation derives avoided cost from the pair, the attestor never prorates. Presence rules: an unattested record carries `attested: false` with `counterfactual`/`effort_band`/`attested_at`/`attested_by`/`attestor_role` ABSENT (never null-imputed); an attested record carries all fields. Record lifecycle — attestation is ASYNCHRONOUS by construction (autonomous-class work has no human at the close boundary): the machine posts the unattested record at close plus an attestation request routed to the accountable human; attestation later upserts the same record to `attested: true`. A never-attested record stays visible as unattested. Attestation routing for requester-less classes (standing routines, scheduled sweeps): the binding declares a standing attestation owner per class, or marks the class attestation-exempt with its cost reported separately — never a perpetually-unattested default. Record integrity: a conforming record is authored by the deployment's bound automation identity; consumers MUST ignore marker-matching records from any other author; attestor identity derives from the PLATFORM actor of the attestation action — on the comment floor the upsert itself is bot-authored, so the record's `attested_by` MUST be copied from, and the record MUST cite, the attestation source event (the human's reply/reaction whose platform actor answered) — the self-declared `attestor_role` field is descriptive, never the trust anchor. Aggregation guidance: report the attestation rate as a first-class health signal (a collapsed rate invalidates the dataset as promotion evidence) and separate requester-attested from independently-attested rows (self-attested counterfactual is a conflict of interest). Duplicate tolerance: the standalone capture path's find-then-create has an inherent create-create race — dedupe on read is ATTESTATION-PRESERVING: an attested bot-authored record outranks any unattested one; only among equally-attested records does the latest win. Write rule, same property: the close trigger creates the unattested record only when no marker-matching bot-authored record exists — a re-fired or retried close NEVER overwrites or downgrades an existing record's attestation fields. Capture point: task boundary (work-item close / PR merge); scope: autonomous-class work per the T3 class vocabulary. Tracker binding seam: record surface resolves per tracker class — native fields where the class supports them (org-managed issue fields, project-scheme fields, work-item fields), structured comment as the universal floor: hidden marker `<!-- autonomy:return-accounting:v1 -->` + one fenced JSON block, marker-keyed upsert (find-then-edit, else create — established in the wider bot ecosystem; NEW to this repo's seams). Prompt: Boris's two questions near-verbatim ("Would you have spent engineering effort on this anyway?" yes/no/partial; "What would it have cost in manual eng-hours?" band), exactly two fields, non-blocking, explicit skip affordance. Join is query-side by the join key only against cost telemetry (resource-scoped on agent-session signals per the telemetry contract); cost values never duplicated into the tracker record (D6). Zero vendor/fleet names; tracker-product specifics live in SKILL.md. | |
There was a problem hiding this comment.
When the attestor selects partial, the record only has a whole-item effort_band; there is no fraction or rule for the would-have-done portion. This says aggregation derives avoided cost from that pair while forbidding attestor proration, so any implementation has to invent a proration, count the whole band, or drop the row, all of which corrupt ROI/promotion evidence for partial items.
Useful? React with 👍 / 👎.
kyle-sexton
added a commit
that referenced
this pull request
Jul 18, 2026
The prior pin ran `gh api` on the caller-selected runner; the self-hosted image ships no gh CLI, so the check failed exit 127 with no blocking label present (observed on #330). The bumped revision refetches labels via actions/github-script (ci-workflows#144). Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 18, 2026
…d-setup v0 (WP1) (#333) ## 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` (#330) - Effort index: `docs/topics/ai-adoption-ladder/index.md` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 (1M context) <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 18, 2026
## Summary Bumps the `do-not-merge-gate` reusable pin to ci-workflows `90f1c54` (melodic-software/ci-workflows#144): the label refetch now runs via `actions/github-script` instead of `gh api`, so the required-context no longer fails `exit 127: gh: command not found` on self-hosted runners without the gh CLI (observed on #330). This PR's own `do-not-merge / do-not-merge` check still runs the OLD pin from main (`pull_request_target` evaluates the base-branch definition) and may fail the same way — expected until this merges; the check is not in the required set. No linked issue ## Related - melodic-software/ci-workflows#144 (the gate fix) - #330 (where the failure surfaced) ## Verification - actionlint clean 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 (1M context) <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 18, 2026
…live-proven demo (WP2) (#343) ## Summary WP2 (`ai-ladder-wp2-telemetry`) implementation, phases 1–4 per its approved PLAN (`docs/topics/ai-ladder-wp2-telemetry/PLAN.md`, #330): - **Telemetry contract** (`reference/telemetry.md`): OTLP pinned to semconv v1.43.0 with `schema_url` on contract-authored emissions (native tool output consumed as-is — empirically corrected during the demo); the `autonomy.work_item.url` join attribute (normalized canonical item URL, selection rule, resource-scope on sessions / span-scope on CI, 1:1-lease granularity guarantee, join-epoch limitations, confidentiality clause, governed `autonomy.*` extension); one causal tree via W3C context propagation with the interactive exclusion; three sink classes with the file-artifact free default; native-surface principle; telemetry-is-not-return boundary. - **Setup telemetry slice**: existing-stack wiring, free default (pipeline-span JSON-lines writer + ephemeral per-job collector into one artifact directory, interactive coverage via a local collector store), `OTEL_RESOURCE_ATTRIBUTES` join wiring (vendor honoring verified against the official monitoring doc), paid sinks advisory-first, additive `telemetry` binding section. - **Emission-conformance check** (`scripts/check-emission-conformance.mjs`): pinned `schemaUrl` (OTLP JSON lowerCamelCase), join-attribute presence + normalization — the contract's enforcement surface. - Templates, three new eval cases, v0.2.0 manifest + catalog. ## Conforming-path demo (executed live) Trigger stub emitted its own root span and propagated TRACEPARENT → template writer emitted the pipeline span → a real headless agent session inherited the context with the join attribute at resource scope. Results: DuckDB over the single artifact directory shows **1 distinct trace across 4 spans** (trigger + pipeline + 2 session spans); `claude_code.cost.usage`/`token.usage` carry `autonomy.work_item.url` string-identical to the pipeline span; conformance check exit 0. Sanitized fixture committed (`skills/setup/evals/fixtures/otlp-demo/`) as the WP3 demo interface. Demo capture used an equivalent OTLP/HTTP-JSON receiver (same JSON-lines output shape as the template's collector fileexporter) — the adopter template keeps the collector. ## Audits - Near-duplicate: the slice composes the fleet's existing observability pipeline as one conforming existing-stack instance; the demo exercised the file-artifact class without touching it. No native telemetry surface reimplemented. - Gates: validate-plugins, contract validator (fleet + vendor sweeps), catalog check, plugin validate --strict, skill-quality PASS, evals schema ok, run-plugin-tests exit 0, markdownlint/typos clean. No linked issue ## Related - Plan record: `docs/topics/ai-ladder-wp2-telemetry/PLAN.md` (#330); WP1: #333 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 (1M context) <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 19, 2026
…ven demo (WP3) (#356) ## Summary WP3 return-accounting package (T5), on the merged WP2 telemetry contract (#343): - **Convention doc** `plugins/autonomy/reference/return-accounting.md`: three-layer data model (machine/deterministic, human-attested, agent/LLM), the two Boris questions verbatim as the human fields (counterfactual would-have-done-anyway + manual-effort band), six-band effort scale `<1h / 1-4h / 4h-1d / 1d-1w / 1w-1mo / >1mo` (user-locked), capture at the task boundary (work-item close / PR merge) as tracker-resident marker records, autonomous-class scope only, agents never estimate the return fields. - **Guided-setup capture slice**: close-boundary templates + marker-record shape, idempotent at-close capture, attestation upsert. - **WP1 PLAN Phase 6 → [DONE]** (fleet binding doc merged in melodic-software/standards#196). ## Live demo evidence (executed this effort) Throwaway private repo `kyle-sexton/autonomy-demo-scratch` issue #1: unattested marker record written at close; a re-fired close stayed idempotent (count 1, no downgrade); attestation upsert recorded with platform actor + source citation; DuckDB join against the WP2 committed OTLP fixture matched the join key string-identically (`autonomy.work_item.url`). Near-duplicate audit: the capture slice composes the work-item tracker seam and the WP2 telemetry contract — no second telemetry or tracker surface created. No linked issue ## Related - #343 (WP2 telemetry — join-key contract this package consumes) - melodic-software/standards#196 (WP1 Phase 6 fleet binding) - #330 (WP2+WP3 plans) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 (1M context) <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 19, 2026
…ils, routines, runner design pack) (#359) ## Summary Architect-round Plans for the four remaining ai-adoption-ladder work packages, on the merged WP1-WP3 foundations (#330, #343, #356): - **WP4 trigger-dispatch** (`docs/topics/ai-ladder-wp4-trigger-dispatch/PLAN.md`): T1 contract — four signal-surface classes (`tracker-vcs-event`/`temporal`/`agent-internal`/`channel-feed`), six adapter obligations, signal envelope (`signal.*` marker record incl. `signal.work_class` stamped from the security surface), kick + drain dispatch through the one work-item queue entrypoint, `check-signal-envelope.mjs` enforcement surface, scratch-repo demo. - **WP5 guardrails** (`ai-ladder-wp5-guardrails/PLAN.md`): T2+T3+#241 — matrix hub + 4 leaves, two-surface binding split (security binding in settings-as-code home, `executor_class`, admission decision table + classification rules), `check-security-binding.mjs` with eval-mode promotion-ceiling semantics, probe-before-bind isolation slice, free-tier CI positive probe + fail-closed demo. - **WP6 routines** (`ai-ladder-wp6-routines/PLAN.md`): T7 — catalog hub (39 classes) + 10 v1 leaves (dead-code sweep excluded per D4 correction), contract-owned catalog-to-matrix mapping rules, setup slice with detect-diff-reconcile of existing schedulers, novel-class derivation probe. - **WP7 runner design pack** (`ai-ladder-wp7-runner/PLAN.md`): T4 graduation — spine + 8 seam specs, lifecycle state model, two-family stop criteria, terminal-handoff escalation with severity/ack knobs, topology seam map. ZERO build artifacts; build stays trigger-gated; birth decisions USER-RESERVED. Merge order pinned: WP4 before WP5 (absent admission binding fail-closes to human-gated — no ungoverned window), WP6 after both, WP7 last. Review: WP4+WP5 stress-tested by a fresh-context reviewer (14 findings, all folded — headline: work-class classification obligation + `executor_class` on the security binding). WP6+WP7 stress-tested by a second fresh-context pass (10 findings, FIX-THEN-SHIP both, all folded — headline: routine→class mappings land on the WP5 security surface, never the repo-local agent-writable section; D2 gains a hybrid DET+AGT branch, a `not-a-routine` catalog flag, and provenance/structural axes reaching C4/C5; WP7's escalation severity refinement adds the WP5 schema+validator edits it requires as genuinely additive optional keys, C5→L3 cited from the matrix cell, vendor-hosted merge cap restated on the cloud-backend path). No linked issue ## Related - #330 (contract set + WP1-WP3 plans) - #343 (WP2 telemetry), #356 (WP3 return accounting) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ai-ladder-wp1-packaging) Plan locked:autonomyplugin + category, topology contract docs, guided-setup v0, fleet binding via standards PRai-ladder-wp2-telemetry) + WP3 (ai-ladder-wp3-return-accounting) Plans locked in a batched architect round: join keyautonomy.work_item.url, semconv v1.43.0 pin, free-default file-artifact sink path, six-band return-accounting schema, async attestation lifecycleDocs-only: contract-slice planning artifacts under
docs/topics/; no plugin code changes.No linked issue
Related
Verification
🤖 Generated with Claude Code