docs(governance): D31 — ADR amendment trio (F5 ADR 0003 + F11 ADR 0005 § D2 + F13/F14 ALIGNMENT Speculative-Candidate class)

cold-audit catch from 2026-05-24 (round 3)

Three coordinated governance amendments per the major-decisions already
made (per "继续吧 unless major decision" + my F5/F11/F13+F14 option-(b)
calls earlier in the session). All P3-class, all docs-only. Single
PR per IDR cleanup-batch convention given the unified theme
("spec was aspirational; reality is X; amend spec to match").

Changes (3 docs files, +52 / -2):

1. docs/adr/0003-intermediate-representation.md — Amendment 1 (NEW
   Amendments section, first ever for ADR 0003):
   - F5 closure: removes the unimplemented `__irRoundTripTest()`
     export-name claim from § Mitigations. The mental model
     (symmetric irToNative+nativeToIR pair on each plugin) does NOT
     fit the actual plugin shape (asymmetric spawn-wrappers:
     request→CLI-args+stdin, response-stream→IR-chunks). Zero plugins
     export this function.
   - Documents the substitute test strategy that IS live at v0.1:
     · Suite 3 covers entry-surface IR↔OpenAI round-trip
     · Per-plugin spawn-with-mock test blocks cover IR→CLI→IR-chunk
     · Lossy-translation edges documented inline in each plugin's
       header comment (mistral.mjs DOCS-N markers being the most
       thorough; anthropic.mjs + codex.mjs carry equivalent tables)
   - Future plugins MUST satisfy both (a) spawn-with-mock test block
     and (b) header lossy-field documentation — the enforcement
     mechanism replacing the original export-name aspiration.
   - Original § Mitigations bullet replaced with a pointer to
     Amendment 1 (preserves history).

2. docs/adr/0005-cache-cross-provider.md — Amendment 5 (after D27
   Amendment 4):
   - F11 closure: acknowledges that the "Anthropic's own prompt cache
     is consulted at the provider" half of § D2 is structurally
     impossible at v0.1.
   - Root cause: Anthropic plugin uses `claude -p --output-format text`
     (verified at anthropic.mjs:196), a plain-text wire surface that
     has no Messages-API field for cache_control markers. The markers
     are also stripped at IR construction (openai-to-ir.mjs:45-89
     whitelists fields, drops cache_control) per ADR 0003 IR design
     reaffirmed in D27 Amendment 4 (F10).
   - Clarifies v0.1 effective behavior: OLP-cache-bypass works
     correctly (no double-caching when Anthropic + markers); the
     delegate-to-Anthropic-prompt-cache half does not fire.
   - Forward path (v1.x): switch Anthropic plugin to --output-format
     json (NDJSON wire) or direct Messages API spawn — substantial
     parser rewrite; deferred since no user has requested delegation.
   - § D2 paragraph stays intact; an inline parenthetical reference
     to Amendment 5 is added immediately after the affected sentence.

3. ALIGNMENT.md — new "Rule 4 exception class — Speculative-Candidate
   Plugin" sub-section after Rule 5, before § Authorities:
   - F13+F14 closure: formalizes the gap between strict ALIGNMENT
     Rule 2 (no speculative shape assumptions) + Rule 4 (unalignable
     plugins are deleted, not feature-flagged) and the actual practice
     where Codex (D6) + Mistral (D8) plugins ship with explicit
     UNPINNED assumptions documented in their headers, gated as
     Candidate-not-Enabled.
   - 5 precise conditions for a Speculative-Candidate plugin:
     (1) STATIC_REGISTRY entry present, (2) candidate: true in
     models-registry, (3) NOT in any user's providers.enabled config,
     (4) header has explicit UNPINNED assumption section with labeled
     IDs and planned-pin triggers, (5) defensive multi-shape parsers
     tied to UNPINNED markers (greppable for future single-shape
     replacement).
   - Enablement criteria (Speculative-Candidate → Enabled): 3 explicit
     requirements (remove UNPINNED labels from header; replace
     multi-shape parsers with single-shape; file pin ADR amendment).
   - Currently-in-class table:
     · codex.mjs (D6) — A3 (auth token field name), A4 (NDJSON event
       schema)
     · mistral.mjs (D8) — A4 (JSON output event schema), A5 (model
       flag), A6 (exact model IDs), A7 (streaming vs json output
       mode), A8 (stdin prompt passing)
   - Anthropic explicitly NOT in this class (CLI version pinned at
     @anthropic-ai/claude-code v2.1.89 per Provider Authority Pins
     table).
   - CI enforcement noted as deferred (reviewer obligation today; a
     future PR may add grep-based gate).

Pre-commit fold-in (per evidence-first checkpoint #4):
- **D31 reviewer flagged wording precision** ("Provider Inventory
  table above" was structurally wrong — the table is BELOW the new
  sub-section). Folded in: 1-word fix "above" → "below" on the
  Speculative-Candidate condition #2.

Tests: 400/400 unchanged (docs-only).

Authority:
- ADR 0003 § Mitigations (modified) + new Amendment 1 (self-amendment)
- ADR 0005 § D2 (annotated) + new Amendment 5 (self-amendment)
- ALIGNMENT.md § Rules (extended with Rule 4 exception class)
- D27 F10 Amendment 4 of ADR 0005 (cited for cache_control IR-strip
  precedent)
- CC 开发铁律 v1.6 § 10.x — Round-3 Cold Audit caught all 3 items

Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent
of drafter): APPROVE_WITH_MINOR. Verified:
- Suite 3 + 3 plugin spawn-with-mock blocks + 3 plugin lossy-field
  header tables all present (F5 substitute test strategy claims
  match implementation)
- anthropic.mjs:196 hardcodes --output-format text + openai-to-ir.mjs
  drops cache_control from messages (F11 wire-limitation technically
  accurate)
- All 8 UNPINNED assumption labels (codex A3/A4 + mistral A4/A5/A6/A7/A8)
  match plugin header text exactly — no invention
- Anthropic-not-in-class claim verified against Provider Authority Pins
  table

Follow-up items (reviewer's non-blocking notes, NOT in this PR):

1. **mistral.mjs A5 internal disconnect** — header lines 145-156 label
   A5 as `UNPINNED-D-later-verifies`, but function body at 371-374
   already cites DeepWiki enumeration as the pin and marks A5
   `CONFIRMED-NOT-APPLICABLE` (no --model flag exists in vibe CLI).
   The disconnect predates D31 and is a per-plugin header cleanup
   (not a constitutional amendment), so it stays out of D31 scope per
   IDR. File as separate follow-up issue — A5 should be moved out of
   the Speculative-Candidate table once the header is updated.

2. **ADR 0005 Amendment ordering cosmetic** — strict reverse-chronological
   would put Amendment 5 above Amendment 4 (current order is 4, 5, 3,
   2 because both 4 and 5 share the 2026-05-24 date and 5 was inserted
   after 4). Not blocking; future cleanup if maintainers want strict
   numeric-descending.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ALIGNMENT.md

@@ -34,6 +34,34 @@ The five Rules below apply to every PR touching a provider plugin, the entry sur
 
 5. **Rule 5 (Cite in Commits).** Every commit touching `lib/providers/<name>.mjs` must cite the provider CLI authority in the commit body. Every commit touching the entry surface must cite the OpenAI spec section URL. Every commit touching the IR must cite the authorizing ADR. CI performs a soft check for the citation pattern; reviewers enforce per `CLAUDE.md`.
 
+### Rule 4 exception class — Speculative-Candidate Plugin (D31 F13+F14)
+
+Rule 4 says "unalignable plugins / fields are deleted, not feature-flagged." This sub-section formalizes a narrow exception: a plugin may ship in `lib/providers/<name>.mjs` with UNPINNED assumptions documented in its header IF AND ONLY IF all five of the following hold:
+
+1. The plugin's `STATIC_REGISTRY` entry is present (so the Provider contract validates at startup).
+2. The plugin is `candidate: true` in `models-registry.json` (or equivalently, the plugin's row in the Provider Inventory table below is in the **Candidate Providers** section, not **Enabled Providers**).
+3. The plugin is NOT in any user's `providers.enabled` config — i.e., it cannot be Enabled in any deployment. `POST /v1/chat/completions` returns 503 for this provider until a Phase E2E audit passes and the enabled flag is explicitly set.
+4. The plugin header contains an explicit section enumerating each speculative shape assumption with a labeled assumption-ID (e.g., A3, A4) and a planned-pin trigger (e.g., "D7 will probe via real CLI capture", "first enable will pin").
+5. The plugin's defensive multi-shape parsers (e.g., trying multiple NDJSON event field names) are tied to the UNPINNED markers — a future implementer can grep the header assumption labels to find every speculative branch and remove all but the actually-observed shape at pin time.
+
+A plugin satisfying all five conditions is a **Speculative-Candidate**. It is Rule 2 / Rule 4 compliant via this exception class.
+
+**Enablement (Speculative-Candidate → Enabled)** requires:
+- Removing the UNPINNED assumption labels from the header (replacing each with `CONFIRMED` or `CONFIRMED-NOT-APPLICABLE` as appropriate).
+- Replacing defensive multi-shape parsers with single-shape implementations matching the observed (now-pinned) wire format.
+- Filing a per-assumption ADR amendment or a single inclusion ADR (per ADR 0006) documenting the primary-source pin for each assumption that was UNPINNED.
+
+**Currently in this class (D31 ratification, 2026-05-24):**
+
+| Plugin file | Phase | Labelled UNPINNED assumptions |
+|---|---|---|
+| `lib/providers/codex.mjs` (D6) | Phase 2 | A3 (auth token field name), A4 (NDJSON event schema) |
+| `lib/providers/mistral.mjs` (D8) | Phase 3 | A4 (JSON output event schema), A5 (model flag), A6 (exact model IDs), A7 (streaming vs json output mode), A8 (stdin prompt passing) |
+
+The Anthropic plugin (`lib/providers/anthropic.mjs`, D4–D5) is NOT in this class — its CLI authority is pinned (`@anthropic-ai/claude-code` v2.1.89 per the Provider Authority Pins table above). It conforms to the standard Rule 4 path.
+
+**CI enforcement note:** The `alignment.yml` workflow does not currently enforce the Speculative-Candidate annotation requirement automatically. The five-condition check is a reviewer obligation. A future PR may add a grep-based gate requiring any file in `lib/providers/` that contains the string `UNPINNED` to also contain the five-condition annotations. D31 establishes the class; automated enforcement is deferred.
+
 ---
 
 ## Authorities