[Reconciliation][P2] Reconcile credit-shortfall recovery across research, content and catalog skills #350

Parent workstream: #322
Epic: #318

Priority: P2 · Audit findings: SP-04

Customer story and completed published-example repair — October 20, 2026

Customer: an artist or manager whose research task stops for billing. “Show the correct next step, and let me decide what to do. Do not retry or buy credits automatically.”

Skills #211 merged as b6fa3655f274fdb4096c1fd52e1c47630c3b6d25. Credit shortfalls preserve billingUrl; separate payment-method gates preserve checkoutUrl. Missing/malformed expected links produce controlled account-billing guidance without substituting a different operation's link. Both shipped examples stop without following links, creating sessions, changing accounts or buying credits. Source acceptance records 35 example tests and all five Skills gates passing.

Automatic release 2026.1020.33 published at 08:20:41 UTC from that actual merge. All three downloaded ZIP checksums match the release manifest. Customer/full/workspace contain 40/120/40 skills; customer/workspace exclude internal skills. Every changed shipped research guide and estimator helper is byte-identical to approved source, as are the generated Claude directory's files/version/source metadata.

Seven focused methods execute the actual extracted customer guide/helper with synthetic responses and stubbed shell/HTTP calls. They pass shortfall/card-setup distinction, wrong-link exclusion, missing/malformed links, non-object errors, controlled stopping and successful read behavior. No real payment/provider request is made. This completes the published-example/source-fixture correction; installed-host, directory approval and live-account acceptance remain separate under #361.

Outcome and problem

The API's insufficient_credits response now contains billingUrl, and one shared research reference was updated, but multiple skill bodies and other shared references still require checkoutUrl. Agents following them cannot present the returned recovery destination. A separate payment-method gate legitimately still uses checkoutUrl, so a blind replacement would create another mismatch.

Scope and ownership

• Owning repository: recoupable/skills; update maintained recoupable/recoup-research-plugin copies or its explicit legacy support guidance.
• Correct current research weekly-brief, talent, contact, playlist and web skill bodies; content-asset-pack; canonical content-api and copies; release-plan-rollout; and catalog estimate/review references.
• Map recovery by actual error/operation: insufficient_credits billingUrl versus payment-method checkoutUrl versus explicit credits-session response.
• Add response-fixture checks for recovery instructions so canonical references and skill-level summaries cannot contradict.

Planning is tracked in Mono. Implementation and release PRs belong in the owning repositories under their current branch rules.

Acceptance criteria

• All active insufficient_credits instructions read and present the returned billingUrl; no missing checkoutUrl field is treated as a disconnected account.
• Payment-method and explicit checkout-session guidance keeps its real contract and is distinguished by error/operation.
• Agents report a credit shortfall without automatic retry, account switching, session creation or purchase.
• Representative fixtures cover insufficient credits, payment-method-required and malformed/missing recovery links, with no Stripe or provider calls.
• Canonical and vendored references match, affected standalone support status is explicit, and all five Skills gates pass.

Evidence and existing work

Baseline: October 10, 2026 audit of July 10–October 10 merges. Recheck current source and existing tracker comments before implementation. Source findings do not establish authenticated production behavior.

• Source evidence 1
• Source evidence 2
• Source evidence 3
• Source evidence 4
• Source evidence 5
• Source evidence 6

Related existing work:

• fix(credits): stop minting a Checkout Session on every credit-gated 402 api#836 — merged billingUrl credit-shortfall contract.
• fix(research): 402 envelope carries billingUrl, not checkoutUrl skills#115 — partial research-reference correction already merged.

Continue or reconcile the linked implementation work; this ticket owns the stated audit correction and does not replace the original feature tracker.

Execution status — October 11, 2026

Released billingUrl recovery and stop-without-retry/purchase behavior in canonical/vendored research, creative, catalog and release guidance through Skills #183, Content #2, Research #5, Marketing #149 and Docs #372. Historical measurement card setup correctly retains checkoutUrl; subscription Checkout returns url.

Five Skills gates and fourteen mocked workflow regressions passed: shortfalls surface recovery links, rate limits defer, transient retries are bounded and optional enrichment preserves gaps. Skills package 2026.1011.7 and Content 0.3.1 / Research 0.2.1 are published/pinned; downloaded selected guides match source. Canonical credits guidance returns 200.

Hosting work remains deferred by Sidney. October 12 readback now confirms the retained host publishes Research availability, its Markdown, research search Markdown and both LLM catalogs at HTTP 200, without research-provider branding. The human GET https://docs.recoupable.dev/mcp still returns 405; /mcp.md and the canonical Marketing human guide return 200. The October 11 restored-page 404s are historical rather than the current state of these checked pages. Final route/host compatibility and complete publication verification remain open.

Historical follow-up: fresh installed-host and actual-account behavior remain unverified under #361. Published-file fixture acceptance is completed by the October 20 release receipt above. No payment operation was used.