[bokelley]

Summary

Gate slice P9 of the reporting-subscriptions DX plan (§5.3, §6.2), stacked on #1744. Docs only, plus one docstring. Review only docs(reporting): guides, README section and agent notes for reporting subscriptions.

• README. A "Reporting subscriptions (AdCP 3.3, experimental)" section (about 25 lines) with:

  • the seller block (storage=, subscriptions=SubscriptionOptions(...), install);
  • the buyer calls (subscribe, unsubscribe, accounts.ensure);
  • one line each on storage, grants and what comes later;
  • links to every guide.

  It also adds a TOC entry and Documentation links.

• Guides, with the plan's titles and section anchors so cross-links with the TypeScript guides (T10) line up:

  Guide	File
  Serving reporting subscriptions (seller)	docs/reporting-subscriptions-seller.md
  Subscribing to reports (buyer)	docs/reporting-subscriptions-buyer.md
  Coverage, explained	docs/reporting-subscriptions-coverage.md
  Accounts: ensure and change	docs/accounts-ensure-and-change.md
  Migrating from account-level reporting_delivery_configs	docs/reporting-subscriptions-migration.md
  Testing with the reporting test kit	docs/reporting-subscriptions-testing.md
  Error reference	docs/reporting-subscriptions-errors.md

  The seller and buyer guides are filled in for everything that exists in P4–P8. Sections for later betas (reconcile/explain, events, receipts, the test kit, change/use, telemetry, bring-your-own producer) are present with their anchors and say what to use until then. The coverage guide's rule statements follow the spec's reason-codes.json definitions.

• ADCPClient.sync_principal docstring now starts: "Replaces each submitted section. To add a reporting subscription, use client.reporting.subscribe."

• llms.txt gains the buyer calls, the seller block, and the §4.1 anti-patterns in do/don't form.

Anchors (for the TypeScript guides)

• Seller: #prerequisites #what-the-sdk-derives #overrides #bring-your-own-producer-and-ledger #grants-and-wind-down #storage-and-migrations #workers-and-scaling #telemetry #troubleshooting-with-explain
• Buyer: #subscribe #unsubscribe #why-replace-needs-a-flag #operator-domains-for-agencies #destinations #reconcile #events #receipts-for-billing-feeds
• Coverage: #the-owed-rules #reason-codes #worked-traces (with #confirmation-day #cancellation-mid-period #re-grant-gap #timezone-cutover #dst)
• Accounts: #outcomes #pending-actions-for-humans-and-agents #separate-accounts #money-changes-and-revision #cold-start

Deviations from the plan

• File names follow this repo's lowercase docs/*.md convention. The TypeScript repo uses docs/guides/UPPER-CASE.md. Titles and anchors match.
• SKILL.md is not touched. skills/ is synced from the spec repo; the agent notes went into llms.txt instead.
• The coverage guide's worked traces are prose. The CoverageTrace JSON and its template sentences arrive with explain (P11).

Refs #1695

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR (seven new reporting-subscription guides, a README section, llms.txt notes) plus a single sync_principal docstring edit in src/adcp/client.py.

What I checked:

• No critical/high findings (row 1 does not fire).
• gated_paths: false (row 2 n/a).
• high_risk: false (rows 3 and 5 n/a).
• No findings at all, so no medium/data-loss/schema/infra triggers (rows 4, 6, 8 n/a).
• No no-auto-approve team match (row 7 n/a).
• First review of this PR; no sticky escalation.

Reviewer verified every documented symbol against the base checkout — buyer facade (subscribe/unsubscribe/preview/list_subscriptions/replace_subscriptions), accounts.ensure → AccountOutcome, the ReliableReportingService/SubscriptionOptions seller block, storage and wind-down imports, python -m adcp migrate, billing="operator", all 14 error codes, COVERAGE_REASON_CODES/COVERAGE_RULE_ORDER, and the today-path workarounds — all resolve and match. "Later beta" features honestly flagged as unavailable. Docstring-only source change needs no semver signal.

Falls through to row 9: approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — documentation-only delta with no actionable findings.

This PR adds seven AdCP 3.3 reporting-subscription guides, README/llms.txt entries, and a one-line sync_principal docstring refinement in src/adcp/client.py. The reviewer verified every symbol, import path (adcp.reporting, adcp.storage.postgres, adcp.server.wind_down_grant), error code, and the coverage reason-code table against base code — all resolve, and the reason-code table matches vocabulary.py's frozen COVERAGE_REASON_CODES byte-for-byte. No correctness, spec-drift, or accuracy issues.

Decision path: no critical/high findings (row 1 n/a); gated_paths false (row 2 n/a); high_risk false with no deletions (rows 3/5 n/a); no medium findings (rows 4/8 n/a); prior decision was approve (row 6 n/a); no no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve. Consistent with the prior clean approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR documenting already-merged AdCP 3.3 reporting-subscription and accounts features.

What I checked:

• 10 files changed (+350/-1): README section, six new docs/*.md guides, llms.txt, and one sync_principal docstring clarification in src/adcp/client.py.
• No public-surface signature change, no generated-code edit (src/adcp/types/domains/**, _generated.py untouched), no forward-compat/discriminated-union change, no import-layering change.
• No credentials in ctx_metadata; no CI-gate disable (ruff/mypy/pytest intact).
• Reviewer verified every promised public API (ReliableReportingService, SubscriptionOptions, postgres/memory storage, client.reporting.subscribe/unsubscribe/list_subscriptions/preview, client.accounts.ensure, AccountReady/Pending/Ambiguous/Rejected shapes, next_step, format_pending_action, and the full error-code table) resolves in source; doc field names and error codes match code.
• Largest-file rule not triggered (max 92 net lines; llms.txt/README are adopter-facing but no multi-hundred-line behavior change).

Decision table: no critical/high/medium findings; gated_paths false (review_decision APPROVED regardless); high_risk false; no no-auto-approve team match; prior decision was approve on a clean run. Rows 1–8 do not fire → row 9 approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR with one aligned docstring change; no blocking or medium findings.

This PR adds seven reporting-subscription guides, a README section, llms.txt do/don't notes, and one sync_principal docstring line. The reviewer verified every documented API against the implemented stack (client.reporting.*, accounts.ensure/pending/refresh, next_step/format_pending_action/is_pre_dispatch_error, SubscriptionOptions/ReliableReportingService, wind_down_grant, postgres_storage, the error-code vocabulary, and the python -m adcp migrate CLI) and all resolve. The docstring change matches sync_principal's replace-shaped semantics. No new public export lands unhandled, no generated-code edits, and the largest new file is under threshold.

Gate checks: high_risk=false; gated_paths=false with review_decision=APPROVED; no no-auto-approve team match; no critical/high/medium findings. Prior decision was also approve with no findings. None of rows 1–8 fire, so this falls through to row 9 → approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only delta plus one accurate docstring tweak; no blocking or medium findings.

Checked:

• No critical/high/medium findings surfaced by the reviewer.
• Public surface unchanged: README reporting section, six new docs/reporting-subscriptions-*.md + docs/accounts-ensure-and-change.md guides, llms.txt block, and one docstring tweak on client.sync_principal. No code-behavior drift, no new export missing a handler-table entry.
• Adopter-facing claims verified against shipped code: accounts outcome/next_step table matches account_outcomes.py (incl. none for AccountReady); error-code reference matches reporting error modules; reporting facade signatures/versioning rules match facade.py.
• high_risk: false; gated_paths: false; review_decision: APPROVED; no no-auto-approve team match.

Decision table: rows 1–8 do not fire (no critical/high, no gated-paths gap, no deletions, no medium findings, no team gate). Falls through to row 9 → approve. Prior decision was also approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR with one accurate docstring addition; no blocking or medium findings.

Checked:

• 10 files changed (350 add / 1 del): reporting-subscriptions guides, README/llms.txt sections, and a sync_principal docstring in src/adcp/client.py.
• Reviewer verified every falsifiable claim against the implemented surface: buyer/seller API names, full error-code table, PendingAction/AccountOutcome field lists, and the coverage reason-code table (mirrors COVERAGE_REASON_CODES and COVERAGE_RULE_ORDER code-for-code).
• No new public exports, so the AGENTS.md handler-table rule does not trigger; no semver-signal concern since nothing in the public adcp.* surface changed shape.

Gate checks:

• high_risk: false.
• gated_paths: false; review_decision: APPROVED.
• No no-auto-approve team match.
• Prior decision was approve with no findings; current run also clean.

No critical/high/medium findings → decision table falls through to row 9 (approve).

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only delta documenting the AdCP 3.3 reporting-subscriptions feature that already shipped at base b502e8e.

Checked:

• README section, six new docs/reporting-subscriptions-*.md files, docs/accounts-ensure-and-change.md, and llms.txt.
• src/adcp/client.py change is an accurate sync_principal docstring summary line only — no wire-shape, public-export, or semver surface touched.
• Reviewer verified the error-code vocabulary, the four AccountOutcome variants, next_step() routing, wind_down_grant, expected_subscription_periods, and COVERAGE_REASON_CODES all exist and match the docs' tables; cross-referenced doc targets and anchors resolve.

No critical/high/medium findings. high_risk false; gated_paths false (and review_decision is APPROVED regardless). No no-auto-approve team match. Prior decision was approve with no findings. None of rows 1–8 fire — falls through to row 9.

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR with no blocking or medium findings.

This PR adds seven new reporting-subscription guides, a README section, llms.txt notes, and one sync_principal docstring. The delta since the prior clean pass is a merge of issue-1695-coverage-budget; no doc content changed. The reviewer verified every documented API, error code, and the python -m adcp migrate CLI against the codebase at base — all exist and match (facade subscribe/unsubscribe/list_subscriptions/preview, accounts.ensure, the four Account* outcomes with field lists matching account_outcomes.py, next_step, format_pending_action, is_pre_dispatch_error, expected_subscription_periods, wind_down_grant, storage factories, all SUBSCRIPTION_*/REPORTING_* codes).

No critical/high/medium findings. high_risk is false, gated_paths is false (and review_decision is APPROVED regardless), and no no-auto-approve team match. Rows 1–8 do not fire; falls through to row 9 (approve). Consistent with the prior approve decision — a net-neutral merge with no new concerns.