[Reconciliation][P2] Add release contract checks that catch drift across docs, skills and packages #360

Parent workstream: #324
Epic: #318

Priority: P2 · Audit findings: Cross-cutting audit follow-up

Outcome and problem

The audit's existing docs-rendering and skill-copy checks pass while published contracts disagree with implementation. Prevention requires checking compatibility with source contracts, not only internal consistency of generated or vendored copies.

Scope and ownership

• Implementation repositories: api, docs, marketing, skills, cli and marketplace, with each check owned where its source lives.
• Build on existing scripts: classify routes public/internal/deprecated/future; validate examples against current schemas; derive auth-specific MCP inventories and CLI help examples.
• Check docs provenance and published discovery, package names/versions/dependencies and maintained instruction paths.
• Add a small release record linking implementation, docs, skills/package updates and user-flow verification; do not require a new service or framework.

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

Acceptance criteria

• Intentional internal/callback routes are explicitly classified rather than forcing all 57 no-spec operations into public docs.
• Representative fixtures from this audit fail before fixes and pass after them: invalid creative payloads, top-up amounts, headless message shape, removed CLI flag and broken skill dependency.
• The chosen docs authority has provenance checks and final HTML/Markdown/LLM discovery checks.
• Package manifests and supported install commands agree, with declared legacy support policy.
• CI and release instructions identify owners and explain which checks establish source compatibility versus live verification.

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

Execution status — October 11, 2026

Released inventories, explicit route dispositions, seven shared examples through actual API validators and OpenAPI source-hash checks via API #1028, fixture-only API #1030 and Marketing #149. Marketing is pinned to released API 2a882dd460ef6757af6d7b1b93bbc1fd8d0c6e86. Inventory fixtures cover root/dotted routes and explicit OPTIONS exports; the snapshot records 406 implemented pairs (166 OPTIONS), 12 unmatched documented pairs and 59 static MCP registrations. Known unmatched/pending routes remain explicit later-package work.

Docs #372 verifies 231 files/navigation against actual Marketing merge 4897009f2007af8ecac0d70535ed53950d1010d3 and rejects stale/unlisted copies. Skills #183 adds fourteen mocked workflow regressions alongside five publishing gates. Both focused-plugin registries pin exact actual merges and matching versions through Marketplace #14; Mono #367 records released references.

Public canonical HTML/Markdown/LLM evidence and checksum-verified released ZIP evidence are linked in epic #318. 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.

Remaining acceptance: broader later-package guards (including removed CLI flag/broken dependency), complete package/install/legacy-support policy, price/response fixtures and fresh host behavior. CI compares a reviewed source pin, not automatically every later API revision. The source comment in getResearchSearchHandler still names /api/research/search; actual/public contract is GET /api/research. Keep that internal-comment cleanup as maintenance work rather than treating the live route as missing.

Source corrections released — October 12, 2026

The branch inventory pins the reviewed API source, records 406 implemented method/path pairs, ten unmatched documented pairs and 59 static registration sites. These are static records, not live endpoint/tool promises. The inventory now requires visible and structured pending/retired availability for unmatched references, handles trailing slash normalization, and respects declared retirement classification.

All five approved source PRs are merged: API #1032, Marketing #152, Docs #373, CLI #26, and App #2242. Mono #373 records the five source references at e650245fe3267a08b94abbb75dc30a8a4108c020. The immutable provenance chain is API 0a590490c0e005045e4cbf399fe552dc41e6b9a3 → Marketing 62cc352c4c90d4578bea4352001fc459b7566e1b → Docs fa6dc9e761056066299dde4525552b0d14442f1f. App source is d13bdcb7b112ff0ed8d9d243ae7c6fd56f9a80d4; CLI source is a11bff0a36e339e94ad6921e55d82ec9472d0e35.

Verified publication: API, App and Marketing main checks pass and their canonical Vercel aliases are READY at those actual merge commits. All 231 merged Docs files/navigation match Marketing. Five representative Markdown pages pass on both public hosts; all 12 downloadable split specs on both hosts exactly match source. Canonical Marketing human pages and both LLM catalogs pass. Both human catalog pages show the 1–366 range; the separate playcount maximum remains 31.

Remaining release gates: CLI build/typecheck/77 tests passed, but npm publication failed with HTTP 404; the registry still serves 0.1.15. The release bot bumped source to 0.1.16 without publishing it. A valid NPM_TOKEN replacement and installed-registry-package verification are required; no token value belongs in an issue. Retained-host normal /llms-full.txt still returns cached v0.1.13/--room-id guidance (cf-cache-status: HIT, max-age=86400); a cache-busted read shows the corrected CLI/Context/Sites content. Its human /mcp still returns 405. Docs main's Mintlify deployment succeeds, but these URL/cache problems are not thereby resolved. Mintlify connection/routing repair and host cutover remain explicitly deferred. No hosted Context, media, OAuth/client, or unresolved-feature acceptance is inferred from this source release.

Ticket acceptance update: New released prevention coverage includes actual-helper social pricing/defaults, catalog bounds, task model/read-status metadata, SSE/status metadata, Sites HTTP method/request validation, Context schema/MCP metadata, unmatched-route availability, CLI invalid-input/type checks and bounded App paths. CI still checks reviewed source pins rather than guaranteeing every future upstream revision; undefined security-scheme regression and broader install/legacy/dependency checks remain open.

Structural prevention merged — October 18, 2026

• API #1037 (e926ffee) routes REST, API-key MCP and delegated OAuth task reads through one authorized operation. Its implementation record reports 11 behavior failures when the ownership predicate is bypassed, while import-boundary checks still pass: structural imports alone are not authorization proof.
• API #1038 (4f721f8e) and Marketing Sync reviewed workspace changes #175 (7febcce4) derive selected response schemas from API-owned definitions and check method/path/status identity and required fields. Message-only Projects errors are accepted only at 401 across all seven operations; other documented error statuses retain error. Docs Sync reviewed workspace changes #376 (616937ef) records the matching 235-file compatibility copy.
• API #1039 (46d1adcb) encodes started/failed scrape attempts and checks the actual constructors/consumers. The implementation record reports that duplicate debit and invalid started-state mutations fail.
• Skills Sync reviewed workspace changes #200 (3b12ce7e) adds internal compiled-CLI/loopback verification with isolated credentials, exact request/output evidence and process cleanup. This is synthetic-backend evidence, not live login or npm publication.
• The undefined-security-scheme outcome was already completed under [Reconciliation][P3] Resolve the undefined callbackSecret OpenAPI scheme #332 on October 14; the older historical “still open” note above is superseded for that specific guard.

Unresolved error-message safety: #1038 deliberately preserves token-verification exception text, and #1039 preserves raw provider exception text. Matching existing response schemas does not prove those messages are safe. Keep sanitization plus generic public messages/server-side diagnostics as an unresolved follow-up under the existing contract/prevention work; the new fixtures do not close it.

Keep broader package/legacy/dependency policy and real-client/host acceptance open. Existing #361 now names database/API/web/MCP prerequisites and the existing-record Context checkpoint.

Evidence boundary: GitHub merge states and final-head checks were refreshed on October 18. Test counts and preview observations above are attributed to the implementation PRs; this pass did not rerun their suites or call customer/provider workflows. No production deployment, database migration, credential cleanup/rotation, paid action, client import, or automatic merge was performed. October 14's live release receipt remains dated evidence for its own versions, not proof of this newer source batch.

Actionable error-message follow-ups — October 19, 2026

API #1038 and #1039 remain merged at 4f721f8e and 46d1adcb. Their relevant review comments remain unresolved, and source inspected at current API main e4d9b6902879936e5a5f159dab85acd4f82cfb48 still exposes caught error text. This is separate from the new assessment viewer and from #346's completed charging outcome.

1. Authentication: #1038 comment, lib/auth/getAuthenticatedAccountId.ts. Replace unexpected caught internal exception text with a stable generic public message while preserving the documented Projects 401 message shape and other status/error contracts. Retain approved diagnostic detail server-side.
2. Scrape start: #1039 comment, lib/apify/scrapeProfileUrl.ts and both response consumers. Return a generic public failure through batch and single routes; replace fixtures that currently require raw provider text. Preserve started/failed billing semantics.
3. Acceptance: inject harmless internal/provider canary strings through existing mocked boundaries and exercise actual route exports. Auth/batch/single public bodies must omit those strings while matching documented status/body shapes. Failed starts remain non-chargeable. No live provider request, real charge, billing redesign or general error framework is required.
4. Ownership: API maintainer implements the bounded repairs through its normal feature-branch/PR workflow, linked back here and [Reconciliation][P2] Verify the reconciled release across public docs, installed clients and original user journeys #361; update affected examples/fixtures if their text changes. No new epic or duplicated queue is needed. Docs has not started this implementation, resolved the review comments, or asserted that schema parity sanitizes messages.

Viewer #2245 was merged outside this assignment as 5bbc42d9c4584b443ffd3fd5906e00aae696e9a6; publication and hosted readback remain unverified; it does not resolve these server error paths. Its packet and controlled write gates are in existing #361.