<!-- task=m-principal-provider-credential-slot-routing/10+08,09_verification_contracts plan=4 tag=REVIEW_REVIEW_TEST milestone-task=slot-smoke,contract-ops -->

# Repair managed API-key qualification documentation and complete S16 live evidence

## For the Implementing Agent

Implement only this follow-up scope. Preserve unrelated dirty-worktree changes. Correct the identified runbook claim, rerun deterministic qualification, and execute the single explicitly authorized no-retry provider request exactly as specified below. Fill every implementation-owned section in `CODE_REVIEW-*-G??.md`, then leave the active pair in place and report ready for review. Do not write `complete.log`, archive active files, classify the verdict, or change roadmap state.

## Background

The previous deterministic implementation/review loop repaired the managed API-key path and passed the local credential-slot qualification, but the final review found that `docs/openai-usage-grafana.md` still treats an Anthropic Messages Prometheus slot series as mandatory. The contract and implementation currently emit canonical OpenAI usage slot/revision series only for OpenAI attempts, while the managed Chat and Messages routes are both qualified through safe credential-slot evidence. User authorization has now resolved the SDD S16 external-evidence stop; this follow-up closes the documentation drift and records exactly one sanitized representative OpenAI request.

## Archive Evidence Snapshot

- Prior plan: `agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/plan_cloud_G08_3.log`.
- Prior review: `agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/code_review_cloud_G08_3.log`.
- Resolved user review: `agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/user_review_0.log`.
- Verdict: FAIL, with 2 Required findings: correct the Grafana qualification wording and obtain the one explicitly authorized representative provider result required by S16. `review_rework_count=3`; `evidence_integrity_failure=false`.
- Existing evidence: deterministic tests, race tests, affected package tests/vet, full credential smoke, contract/spec pointers, stale-claim checks, and preflight safety checks passed; no provider request was attempted before authorization.
- Required documentation correction: qualification proves both managed routes with exact auth and safe slot attribution, but OpenAI canonical Prometheus slot/revision series remain OpenAI-attempt-only until Anthropic metering exists. The deterministic packet is one initial Chat call plus one rotated Chat call; it is not evidence of an Anthropic Messages Prometheus series.
- User action: explicit approval was received for exactly one no-retry OpenAI request using the recorded `gpt-5.6-luna` command. No decrypted credential may appear in any output or artifact.
- Roadmap carryover: milestone `principal-provider-credential-slot-routing`, task ids `slot-smoke,contract-ops`, SDD scenarios S16-S17. Do not write `complete.log` or change roadmap state.

## Roadmap Targets

- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/principal-provider-credential-slot-routing.md`
- SDD: `agent-roadmap/sdd/operational-observability-provider-management/principal-provider-credential-slot-routing/SDD.md`
- Task ids: `slot-smoke`, `contract-ops`
- Acceptance: S16 deterministic vendor/profile/two-slot qualification plus one authorized representative live request with safe evidence; S17 canonical contract/spec/runbook drift checks and no raw-secret evidence.

## Analysis

### Files Read

- `agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/plan_cloud_G08_3.log`
- `agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/code_review_cloud_G08_3.log`
- `agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/user_review_0.log`
- `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
- `agent-roadmap/phase/operational-observability-provider-management/milestones/principal-provider-credential-slot-routing.md`
- `agent-roadmap/sdd/operational-observability-provider-management/principal-provider-credential-slot-routing/SDD.md`
- `agent-contract/outer/anthropic-compatible-api.md`
- `agent-spec/input/openai-compatible-surface.md`
- `docs/openai-usage-grafana.md`

### SDD Criteria

- The SDD is approved and implementation-unlocked. First-line metadata preserves `milestone-task=slot-smoke,contract-ops`.
- S16 requires deterministic credential-free fixture qualification and one opt-in representative provider request whose retained evidence contains only provider, model, safe credential-slot reference, revision, date, and sanitized result.
- S17 requires contract/spec/runbook pointer consistency and a repository evidence scan that does not expose raw credential material.
- The contract/spec boundary is explicit: Anthropic handlers do not currently emit OpenAI canonical usage series. Documentation must describe this implementation boundary instead of inferring a missing Anthropic series as failure.

### Verification Context

- Runner: local Linux/aarch64 at `/config/workspace/iop-s0`; observed branch `agent/dispatcher-work-log-artifact-loop`, HEAD `89ae148c`; the checkout is intentionally dirty with broader milestone work and must not be synchronized or reset.
- Tool preflight: Go `go1.26.2 linux/arm64` at `/config/.local/bin/go`; `sops 3.13.1` at `/config/.local/bin/sops`; encrypted input `/config/.config/sops/iop/openai.sops.yaml` and age key `/config/.config/sops/age/keys.txt` are readable.
- User review resolution authorizes exactly one external request. The dispatcher must supply `IOP_ALLOW_LIVE_PROVIDER=1`; the command below must run once, with retries disabled by the script, and must not be repeated for any reason.
- Deterministic qualification must make no external provider request. Use a fresh executable temporary root below `/config/workspace` and preserve only sanitized evidence in the active review file.

### Test Coverage Gaps

- The documentation statement has no executable semantic test; the contract/spec pointer check, stale-claim search, deterministic smoke, diff check, and final no-secret scan are the applicable drift oracles.
- S16 remained incomplete only because the authorized representative provider result was missing. The one-shot command below closes that evidence gap if its sanitized result and exact exit status are captured.
- No source or test behavior change is planned in this loop. If deterministic or live output exposes a new implementation defect, record the exact blocker and leave the pair for the official review flow; do not broaden scope.

### Symbol References

- None. This follow-up changes one operator-facing documentation paragraph and evidence records only.

### Split Judgment

Keep this as one plan. The documentation correction and the authorized S16 evidence close the same qualification boundary; splitting them would allow a qualification statement to be accepted without the evidence that defines its scope.

### Scope Rationale

- Modify only `docs/openai-usage-grafana.md` for the stale interpretation. Keep `agent-contract/outer/anthropic-compatible-api.md` and `agent-spec/input/openai-compatible-surface.md` as authoritative references; do not rewrite them because the reviewed implementation boundary already matches them.
- Run the existing deterministic smoke and the exact authorized one-shot without changing scripts, credentials, provider profiles, runtime code, or roadmap files.
- Retain only sanitized provider/model/slot/revision/date/result evidence. Never paste decrypted input, access tokens, response bodies, headers, prompts, lease IDs, or private-key material.

### Final Routing

- `evaluation_mode=isolated-reassessment`; `finalizer=finalize-task-policy.sh`; `finalizer_mode=pair`.
- Build route: recovery-boundary cloud `G07`; active plan `PLAN-cloud-G07.md`.
- Review route: official-review cloud `G07`; active review `CODE_REVIEW-cloud-G07.md`.
- `large_indivisible_context=false`; loop-risk signature `boundary_contract` count 1; recovery boundary is true because `review_rework_count=3` while `evidence_integrity_failure=false`.
- The plan/review pair must preserve the exact first-line `milestone-task=slot-smoke,contract-ops` metadata.

## Implementation Checklist

- [ ] Correct the Grafana guide so managed Chat/Messages qualification, OpenAI-only Prometheus series, and the deterministic initial/rotated Chat packet are described accurately.
- [ ] Rerun deterministic credential-slot qualification and S17 pointer/stale-claim/no-secret checks with fresh output.
- [ ] Execute the exact authorized OpenAI one-shot once with no retry and record only sanitized provider/model/slot/revision/date/result evidence plus exit status.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## [REVIEW_REVIEW_TEST-1] Correct managed API-key qualification and metric wording

### Problem

`docs/openai-usage-grafana.md` currently says a healthy deterministic run produces both Chat and Messages credential-slot Prometheus series and calls a missing Messages series anomalous. `agent-contract/outer/anthropic-compatible-api.md` and `agent-spec/input/openai-compatible-surface.md` define the opposite boundary for the current implementation: Anthropic handlers do not emit OpenAI canonical usage series.

### Solution

Update the managed API-key interpretation paragraph to retain the canonical `X-Api-Key` lease-scope explanation, state that qualification proves both managed routes complete with exact auth and safe slot attribution in the qualification record, and state that OpenAI canonical Prometheus slot/revision series are emitted only for OpenAI attempts. Explain that an Anthropic Messages series is therefore not expected until Anthropic metering is implemented. Also state that the deterministic packet contains one initial Chat call and one rotated Chat call, and retain the fail-closed/no-fallback behavior for lease failure.

### Modified Files and Checklist

- [ ] `docs/openai-usage-grafana.md`: replace the stale metric expectation without changing the contract/spec links or fail-closed guidance.

### Test Strategy

Use targeted stale-claim and contract/spec pointer searches, then run `git diff --check`. No code test is introduced because this is a documentation interpretation correction and the existing deterministic qualification is the behavior oracle.

### Verification

```bash
rg -n "managed API-key|X-Api-Key|OpenAI canonical|Anthropic|initial Chat|rotated Chat|fail closed" docs/openai-usage-grafana.md agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md
! rg -n "both a Chat and a Messages slot series|Absence of a Messages slot series is therefore an anomaly" docs/openai-usage-grafana.md
git diff --check
```

Expected: the corrected paragraph is present, the stale claim is absent, and the diff has no whitespace errors.

## [REVIEW_REVIEW_TEST-2] Complete deterministic S16/S17 qualification and one authorized provider request

### Problem

The previous review established deterministic qualification and safe preflight but could not close S16 because no authorized representative provider request had been attempted. The user has now authorized exactly one no-retry OpenAI request using the recorded command.

### Solution

Run the deterministic smoke with a fresh executable temporary root, then run the exact live command once only after checking the explicit opt-in and readable encrypted inputs. Capture the exact exit status and a sanitized result record containing only provider, model, safe credential-slot reference, credential revision, date, and result. If the preflight or one-shot fails, record the exact output boundary and blocker in the implementation-owned review sections without retrying or substituting a provider.

### Modified Files and Checklist

- [ ] `CODE_REVIEW-cloud-G07.md`: record fresh deterministic output, exact one-shot exit status, and sanitized evidence without any secret or response body.

### Test Strategy

The deterministic smoke must remain external-I/O-free. The live command is the sole authorized external request and must not be repeated. Run contract/spec pointer checks, stale-claim checks, and a repository no-secret scan after the evidence is recorded.

### Verification

```bash
credential_smoke_parent="$(mktemp -d /config/workspace/iop-credential-slot-followup.XXXXXX)"
trap 'rmdir "$credential_smoke_parent" 2>/dev/null || true' EXIT
TMPDIR="$credential_smoke_parent" make test-credential-slot-smoke
rmdir "$credential_smoke_parent"
trap - EXIT

test "${IOP_ALLOW_LIVE_PROVIDER:-}" = "1"
test -r /config/.config/sops/iop/openai.sops.yaml
test -r /config/.config/sops/age/keys.txt
scripts/e2e-credential-slot-smoke.sh --live --secret-stdin --profile openai --model gpt-5.6-luna --reasoning-effort high --max-completion-tokens 128
```

Expected: deterministic qualification exits 0 with no external request; all live preflight checks pass; the exact live command executes once with no retry and exits 0 with sanitized evidence only. The implementation-owned review must record the command's exact exit status and safe fields, never its decrypted input or provider body.

## Modified Files Summary

| File | Item |
|---|---|
| `docs/openai-usage-grafana.md` | REVIEW_REVIEW_TEST-1 |
| `agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/CODE_REVIEW-cloud-G07.md` | REVIEW_REVIEW_TEST-2 |

## Final Verification

Run from `/config/workspace/iop-s0` after implementation:

```bash
git diff --check
rg -n "managed API-key|X-Api-Key|OpenAI canonical|Anthropic|initial Chat|rotated Chat|fail closed" docs/openai-usage-grafana.md agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md
! rg -n "both a Chat and a Messages slot series|Absence of a Messages slot series is therefore an anomaly" docs/openai-usage-grafana.md
git check-ignore -q agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/PLAN-cloud-G07.md && git check-ignore -q agent-task/m-principal-provider-credential-slot-routing/10+08,09_verification_contracts/CODE_REVIEW-cloud-G07.md
```

The deterministic smoke and the exact authorized one-shot from REVIEW_REVIEW_TEST-2 must also be fresh and recorded in the active review. The final repository scan must show no raw credential, private key, provider body, prompt, lease id, or decrypted configuration in tracked evidence. If all implementation and verification work is complete, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.

After completing all code changes, fill implementation-owned sections in CODE_REVIEW-*-G??.md.
