mirror of
https://github.com/dtzp555-max/olp.git
synced 2026-07-19 09:45:07 +00:00
Second batch of pre-Phase-2 cleanup. 6 GitHub issues closed in one cohesive docs/governance commit with 1 small code addition (#2 debug log line in server.mjs) and 1 transcript artifact (#15 new file). Changes (7 files modified, 1 file created, +470 / -13): **Code changes** 1. **#2 — cache_control partial-noop debug log** (server.mjs) ADR 0005 § D2 says: "for non-Anthropic targets, the bypass markers are noop'd (logged once per request at debug level so users can see they were ignored)". Pre-D36 logEvent fired only when an Anthropic hop actually bypassed; non-Anthropic hops with markers present were silently noop'd. New 12-line block in handleChatCompletions right after hasCacheControlMarkers is computed. Fires logEvent('debug', 'cache_control_partial_noop', { chain: [<provider names>], marker_count: <count> }) when: - hasCacheControlMarkers === true AND - chain.some(hop => hop.provider !== 'anthropic') Fires at most once per request (top-level if, not in a loop). No log when no markers, or when every chain hop is Anthropic. The existing cache_bypass debug log inside shouldBypassCacheForHop is untouched. marker_count sums body-side and IR-side extractCacheControlMarkers results. At v0.1 the IR term is structurally 0 (openAIToIR strips cache_control); inline comment marks this as a revisit point for the future ADR 0003 amendment that activates cache_control in the IR whitelist. **Documentation amendments** 2. **#5 — ADR 0002 vibe.mjs → mistral.mjs** (docs/adr/0002-plugin-architecture.md) § Decision filesystem layout: `vibe.mjs` corrected to `mistral.mjs` (file named after provider key per the convention anthropic.mjs/codex.mjs). The vibe.mjs entry was an early-draft naming choice that never landed. Amendment 5 prepended above Amendment 4 documenting the filename correction + explicit convention statement (file named after provider key, not CLI binary) for future contributors. 3. **#6 — mistral.mjs A5 flip + ALIGNMENT.md table update** (lib/providers/mistral.mjs + ALIGNMENT.md) Pre-D36: header A5 (model flag) status was UNPINNED-D-later-verifies but function body lines 376-380 said CONFIRMED-NOT-APPLICABLE (DeepWiki enumeration already confirmed `--model` does not exist on vibe CLI). Header now reflects CONFIRMED-NOT-APPLICABLE with DeepWiki citation (DOCS-4). ALIGNMENT.md Speculative-Candidate table mistral row: A5 removed from UNPINNED list; A4, A6, A7, A8 preserved with parenthetical descriptions intact. No code change to function body (already correct). 4. **#13 — /v1/models alias entries — ALIGNMENT.md + spec-pin governance** (ALIGNMENT.md + docs/openai-spec-pin.md) Round-6 F10 flagged D27 F15's alias entries on /v1/models as borderline Rule 2(b) violation (OpenAI spec does not enumerate aliases as separate entries). Option C selected: keep current behavior, document the controlled deviation. - ALIGNMENT.md: new "Controlled deviations (entry-surface scope)" subsection under "Class-specific Exceptions". Entry 1 documents the /v1/models alias deviation with rationale (D27 F15 onboarding), formal contract reference, field constraints (owned_by matches canonical, created matches canonical, no invented fields), SPOT reference (getAliasMap()), and re- evaluation trigger. - docs/openai-spec-pin.md: new alias-surfacing subsection under GET /v1/models with full 4-field contract table (id/object/ created/owned_by), rationale, sourcing explanation, forward path. - server.mjs handleModels: NO CHANGE — behavior preserved. 5. **#15 — Anthropic v2.1.89 transcript artifact** (docs/provider-audits/anthropic.md NEW; ALIGNMENT.md + lib/providers/anthropic.mjs cross-references) Round-6 F12: ALIGNMENT.md anthropic row pin (v2.1.89, observed at D4) cited the plugin header; plugin header cited the observation date but no transcript. Circular per Rule 1 ("observed behaviour, transcript attached"). New file docs/provider-audits/anthropic.md (single living artifact, not version-specific): - Date of capture: 2026-05-24 - Observed `claude --version`: 2.1.132 (Claude Code) — captured today on the project maintainer's primary workstation - Plugin-pinned version: @anthropic-ai/claude-code v2.1.89 (from D4 implementation pin in ALIGNMENT.md Provider Authority Pins) - Version drift: honestly documented — pin is v2.1.89, live is v2.1.132, drift within tolerance, re-audit triggers named - Sample invocation: `claude -p --output-format text --no-session- persistence --model <model> [--debug]` - Flag-surface table: 5 OLP-consumed flags verbatim from `claude -p --help` (-p / --output-format / --no-session- persistence / --model / --debug) - Citation cross-references back to ALIGNMENT.md + plugin header ALIGNMENT.md anthropic row: appended "transcript artifact: docs/ provider-audits/anthropic.md (captured 2026-05-24)" — closes the circular citation. lib/providers/anthropic.mjs header: 5-line pointer to the artifact with version numbers stated explicitly. **Tests** (test-features.mjs): 424 → 431 (+7): - #2 partial-noop log ×3: - Suite 9f case 1: markers + mixed chain → fires once at level=debug - Suite 9f case 2: no markers → suppressed - Suite 9f case 3: anthropic-only chain → suppressed - #14 cache_control slot determinism ×4: - #14a: markers-present IR produces different key from no-markers IR - #14b: same IR computed twice yields identical key - #14c: two independently-constructed IRs with identical payloads yield same key - #14d: both top-level and content-array-nested markers affect the key All 4 tests call computeCacheKey directly on hand-built IRs (bypassing openAIToIR which strips markers at v0.1). Per ALIGNMENT.md Rule 2 (No Invention), no sortMarkers helper added — the slot is dead-code at v0.1 and shipping a helper without a caller authority would be invention. Test comment documents the forward-activation contract. Pre-commit fold-in (per evidence-first checkpoint #4): - **D36 reviewer flagged marker_count latent double-count risk** (Suggestion #1, non-blocking). The sum at server.mjs:435-437 is safe at v0.1 (IR term structurally 0) but will 2× when a future ADR 0003 amendment activates cache_control in the IR whitelist. Folded in a 4-line comment marking the revisit point. Two other non-blocking reviewer suggestions not folded: - Test count brief-vs-deliverable discrepancy (4 not 3 for #14) is informational — the 4-test variant is strictly better (covers content-array nesting which is a real extractCacheControlMarkers contract path). - Recapture-procedure git-add reminder in anthropic.md is low-priority procedure documentation. Authority: - ADR 0005 § D2 — cache_control partial-noop debug log requirement (#2) - ADR 0002 § Decision filesystem layout (Amendment 5) — plugin file naming convention (#5) - DeepWiki vibe CLI flag enumeration — A5 not applicable (#6) - ALIGNMENT.md Rule 2(b) + docs/openai-spec-pin.md GET /v1/models — alias controlled deviation (#13) - ADR 0005 cache key stability invariant + ADR 0003 forward-compat — cache_control slot determinism contract (#14) - ALIGNMENT.md Rule 5 (observed behaviour, transcript attached) + Provider Authority Pins anthropic row — transcript artifact (#15) - CC 开发铁律 v1.6 § 10.x — independent fresh-context reviewer - CLAUDE.md release_kit_overlay phase_rolling_mode — D36 under "Unreleased" against Phase 2; no version bump Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent of drafter): APPROVE. Critical depth checks: - #2: gate condition fires only on (markers AND non-anthropic-hop); pre-existing cache_bypass log inside shouldBypassCacheForHop untouched - #5: lib/providers/ directory verified — mistral.mjs exists, vibe.mjs does not exist - #6: mistral.mjs spawn-site body comment (lines 376-380) already CONFIRMED-NOT-APPLICABLE pre-D36 and unchanged in this diff - #13: server.mjs handleModels unchanged (verified via grep) - #14: all 4 tests pass against current code; no sortMarkers helper shipped (Rule 2 No Invention honored) - #15: live `claude --version` independently run by reviewer → matches artifact (2.1.132); all 5 OLP-consumed flags independently verified present in `claude -p --help` - Hygiene: 0 hits for personal markers, home paths, OAuth tokens, internal IPs across all 8 files - 431/431 tests pass in reviewer's independent npm test run Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.7
@@ -7,6 +7,15 @@
|
||||
|
||||
## Amendments
|
||||
|
||||
### Amendment 5 — 2026-05-24: Correct § Decision filesystem layout — `vibe.mjs` → `mistral.mjs` (D36 #5)
|
||||
|
||||
- **Finding:** Issue #5 (D36) — § Decision filesystem layout (around line 47 of the original ADR) listed the Mistral provider plugin as `vibe.mjs` (named after the CLI binary `vibe`). The shipped file at `lib/providers/mistral.mjs` (D8) is named after the provider key, matching the established convention from the other two plugins: `anthropic.mjs` (provider key `anthropic`, CLI `claude`) and `codex.mjs` (provider key `openai`, CLI `codex`). The ADR's `vibe.mjs` entry was a drafting-time placeholder that did not get corrected when D8 landed `lib/providers/mistral.mjs`.
|
||||
- **Change:** Replace `vibe.mjs # spawn `vibe --prompt --output json`` with `mistral.mjs # spawn `vibe --prompt --output streaming`` in the filesystem layout. The `--output streaming` correction also aligns the example with the actual D8 implementation (`mistral.mjs` line 377 uses `--output streaming`, not `--output json` — see D8 review-2 finding inside the plugin header).
|
||||
- **Naming convention reaffirmed:** Provider plugin files are named after the **provider key** (`anthropic`, `openai`, `mistral`), not the CLI binary (`claude`, `codex`, `vibe`). Future provider plugins must follow this convention. The provider key is the load-bearing identifier — it appears in `models-registry.json`, cache keys, fallback chain configs, and ADR 0006 inclusion tables. The CLI binary name is an implementation detail that may change (e.g., a vendor rename) without affecting the rest of the system.
|
||||
- **Authority:** Issue #5 (D36); naming convention established by `lib/providers/anthropic.mjs` (D4) and `lib/providers/codex.mjs` (D6) which both shipped before `lib/providers/mistral.mjs` (D8).
|
||||
- **No code change:** D36 #5 is a docs-only correction. The plugin file already lives at the correct path.
|
||||
- **Procedural mechanism:** CC 开发铁律 v1.6 § 10.x (D36 batch — ADR drift caught by issue-triage review of bootstrap ADRs).
|
||||
|
||||
### Amendment 4 — 2026-05-24: Ratify `contractVersion` as a required Provider contract field (D32 F5)
|
||||
|
||||
- **Finding:** Round-4 cold-audit F5 (P3 governance omission) — `lib/providers/base.mjs` `validateProvider` enforces `p.contractVersion === '1.0'` and all three shipped plugins declare it, but the Provider contract field list in § Decision (lines ~63-74) does not include `contractVersion`. It was mentioned only in § Mitigations as a forward-looking note ("The contract is versioned. v1.0 is the subset in this ADR; future additions … require ADR amendment plus a contract-version bump. Old provider plugins continue to declare `contractVersion: '1.0'`…"), not as a required field. This is the same class of documentation–implementation gap as Amendment 1 (`maxSpawnTimeMs` retroactive sync).
|
||||
@@ -60,7 +69,9 @@ lib/providers/
|
||||
index.mjs # static registry (enumeration of in-tree providers)
|
||||
anthropic.mjs # spawn `claude -p` — port of OCP server.mjs spawn logic
|
||||
codex.mjs # spawn `codex exec --json`
|
||||
vibe.mjs # spawn `vibe --prompt --output json`
|
||||
mistral.mjs # spawn `vibe --prompt --output streaming` (file named after
|
||||
# provider key per the convention established by
|
||||
# anthropic.mjs / codex.mjs — see Amendment 5)
|
||||
grok.mjs # spawn `grok -p --output-format streaming-json` (optional)
|
||||
kimi.mjs # spawn `kimi -p --output-format stream-json` (optional)
|
||||
minimax.mjs # tier-2 optional, default-disabled
|
||||
|
||||
@@ -136,6 +136,38 @@ Each entry: `{ "id": "<model-id>", "object": "model", "created": <ts>, "owned_by
|
||||
no invented fields (per D27 F15). Alias entries are also surfaced as separate list members
|
||||
(per D27 F15 alias surfacing).
|
||||
|
||||
**Alias surfacing — controlled deviation (D36 #13).** OpenAI's `/v1/models` spec
|
||||
enumerates one entry per canonical model ID; OLP additionally surfaces alias entries
|
||||
(e.g. `claude`, `sonnet`, `opus`, `haiku` alongside their canonical Anthropic targets).
|
||||
This is a documented deviation from strict spec parity. It is governed by
|
||||
`ALIGNMENT.md § Class-specific Exceptions → Controlled deviations (entry-surface scope)`,
|
||||
which references this section as the formal contract.
|
||||
|
||||
The alias-entry contract:
|
||||
|
||||
| Field | Value for alias entry |
|
||||
|---|---|
|
||||
| `id` | the alias string (e.g. `'sonnet'`) — same shape as canonical entries |
|
||||
| `object` | `'model'` — same as canonical entries |
|
||||
| `created` | identical to the canonical target's `created` timestamp (per F12) |
|
||||
| `owned_by` | identical to the canonical target's `owned_by` (i.e. the provider key) |
|
||||
|
||||
The alias list is sourced from `models-registry.json` via `getAliasMap()` in
|
||||
`lib/providers/index.mjs` — the SPOT for alias-aware routing. `server.mjs handleModels`
|
||||
appends alias entries to the canonical list only when the alias's canonical target's
|
||||
provider is currently in `loadedProviders`. No fields beyond the four OpenAI-spec fields
|
||||
are added on alias entries.
|
||||
|
||||
**Rationale (D27 F15):** Onboarding gap. Clients configured with `model: 'sonnet'` (a
|
||||
common alias used by Anthropic's own CLI and OpenClaw-class tools) previously received
|
||||
an empty `/v1/models` response that did not surface the alias as a callable model id.
|
||||
Surfacing the alias makes the discovery loop usable for OpenAI-compatible clients with
|
||||
alias-aware UX.
|
||||
|
||||
**Forward path:** Annual audit (14 May) re-checks whether OpenAI has shipped a formal
|
||||
alias-listing extension to `/v1/models`. If so, OLP migrates the alias surface to that
|
||||
shape. If not, the deviation continues unchanged.
|
||||
|
||||
**`created` field stability (F12 round-5 cold-audit):** OpenAI spec treats `created` as a
|
||||
stable per-model attribute, not a request-time value. `server.mjs handleModels` uses
|
||||
`getModelCreated(modelId)` (from `lib/providers/index.mjs`) which reads the per-entry
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
# Anthropic provider — version-capture artifact
|
||||
|
||||
- **Provider key:** `anthropic`
|
||||
- **Plugin file:** `lib/providers/anthropic.mjs`
|
||||
- **Last capture:** 2026-05-24 (D36 #15)
|
||||
- **Capture host:** project maintainer's primary workstation (home-mac)
|
||||
- **Status:** living artifact — re-capture at every plugin touch, or annually
|
||||
during the 14 May Annual Alignment Audit, whichever comes first.
|
||||
|
||||
This artifact closes the circular-citation finding from Round-6 (issue #15):
|
||||
ALIGNMENT.md § Provider Authority Pins anthropic row cites `@anthropic-ai/claude-code`
|
||||
v2.1.89 (observed at D4) without an independent transcript; the plugin header cited
|
||||
the observation date but pointed back to ALIGNMENT.md. This file is the in-repo
|
||||
transcript artifact that grounds the OLP-side claim.
|
||||
|
||||
---
|
||||
|
||||
## Observed `claude --version`
|
||||
|
||||
The live binary on the maintainer's workstation today is:
|
||||
|
||||
```
|
||||
2.1.132 (Claude Code)
|
||||
```
|
||||
|
||||
Captured by running `claude --version` in a non-interactive shell on 2026-05-24.
|
||||
|
||||
## Plugin-pinned version
|
||||
|
||||
```
|
||||
@anthropic-ai/claude-code v2.1.89
|
||||
```
|
||||
|
||||
Source: ALIGNMENT.md § Authorities § "Provider authority pins" row `anthropic`
|
||||
("OLP-side pin: `@anthropic-ai/claude-code` v2.1.89 (observed at D4 —
|
||||
`lib/providers/anthropic.mjs` header)"). This is the version observed inside
|
||||
the OLP-side D4 work; the plugin was authored against this version's flag
|
||||
surface.
|
||||
|
||||
## Version drift note
|
||||
|
||||
The pinned version (v2.1.89, D4) and the live binary (v2.1.132, today) differ
|
||||
because the `claude` CLI has continued to ship updates since D4. This drift is
|
||||
within tolerance for the v0.1 baseline:
|
||||
|
||||
- The CLI flags OLP consumes — `-p`, `--output-format=text`,
|
||||
`--no-session-persistence`, `--model`, `--debug` — are all still present and
|
||||
semantically unchanged in v2.1.132 (verified today via `claude -p --help`
|
||||
— see "Flag surface captured today" below).
|
||||
- The pin in ALIGNMENT.md is conservative by design — it names the version OLP
|
||||
was authored against, not the highest version known to work. Re-pinning to
|
||||
v2.1.132 (or whichever version is current) is the right action at the next
|
||||
Anthropic-plugin touch, when a reviewer can confirm no regressions.
|
||||
- Re-audit recommended at: (a) next material change to
|
||||
`lib/providers/anthropic.mjs`, OR (b) 14 May 2027 Annual Alignment Audit,
|
||||
OR (c) the post-2026-06-15 one-shot triggered audit (ALIGNMENT.md
|
||||
§ One-shot Triggered Audits) — whichever comes first.
|
||||
|
||||
## Sample invocation
|
||||
|
||||
The Anthropic plugin spawns the CLI with this argument shape (see
|
||||
`lib/providers/anthropic.mjs` § `buildClaudeArgs` and `_spawnAndStream`):
|
||||
|
||||
```
|
||||
claude -p --output-format text --no-session-persistence --model <model> [--debug]
|
||||
```
|
||||
|
||||
- `-p` puts the CLI in non-interactive (print-and-exit) mode.
|
||||
- `--output-format text` selects plain-text stdout. The plugin parses stdout as
|
||||
plain text (no NDJSON envelope).
|
||||
- `--no-session-persistence` disables session storage so OLP remains stateless
|
||||
(per ADR 0001 § Non-mission — OLP is not a conversation-state store).
|
||||
- `--model <model>` is forwarded from the IR's `model` field.
|
||||
- `--debug` is added only when `OLP_DEBUG_CLAUDE` env is set, for development.
|
||||
|
||||
The prompt is written to the CLI's stdin (`messagesToPrompt(ir.messages)` from
|
||||
`anthropic.mjs`), not passed as a positional argument.
|
||||
|
||||
## Flag surface captured today
|
||||
|
||||
Excerpt from `claude -p --help` on host home-mac on 2026-05-24 (v2.1.132). Only
|
||||
the flags relevant to OLP's invocation are reproduced; the full help is much
|
||||
larger.
|
||||
|
||||
| Flag | Description (verbatim, abridged) |
|
||||
|---|---|
|
||||
| `-p, --print` | Print response and exit (useful for pipes). |
|
||||
| `--output-format <format>` | Output format (only works with --print): "text" (default), "json" (single result), or "stream-json" (realtime streaming) — choices: "text", "json", "stream-json". |
|
||||
| `--no-session-persistence` | Disable session persistence — sessions will not be saved to disk and cannot be resumed (only works with --print). |
|
||||
| `--model <model>` | Model for the current session. Provide an alias for the latest model (e.g. 'sonnet' or 'opus') or a model's full name (e.g. 'claude-sonnet-4-6'). |
|
||||
| `-d, --debug [filter]` | Enable debug mode with optional category filtering (e.g., "api,hooks" or "!1p,!file"). |
|
||||
|
||||
All four load-bearing flags (`-p`, `--output-format`, `--no-session-persistence`,
|
||||
`--model`) are present and accept the same value formats the OLP plugin uses.
|
||||
The `--debug` flag is also present with the same semantics.
|
||||
|
||||
## Citation cross-references
|
||||
|
||||
- ALIGNMENT.md § Authorities § "Provider authority pins" anthropic row — names
|
||||
this file as the transcript-artifact pin.
|
||||
- `lib/providers/anthropic.mjs` header lines 1-50 — names this file as the
|
||||
version-capture artifact (D26 F18 follow-up).
|
||||
- ADR 0001 § Mission inheritance — establishes `claude -p` as Authority 1
|
||||
source for the `anthropic` plugin.
|
||||
- ADR 0005 Amendment 5 (D31 F11) — clarifies the wire limitation of
|
||||
`claude -p --output-format text` w.r.t. cache_control marker delegation.
|
||||
|
||||
## Recapture procedure
|
||||
|
||||
When this artifact is next refreshed (per the "Version drift note" trigger
|
||||
list), the maintainer should:
|
||||
|
||||
1. Run `claude --version` on the project maintainer's primary workstation.
|
||||
2. Run `claude -p --help` and verify that `-p`, `--output-format`,
|
||||
`--no-session-persistence`, `--model`, and `--debug` are all still present
|
||||
with the same value formats.
|
||||
3. Update the "Last capture", "Observed `claude --version`", and "Flag surface
|
||||
captured today" sections with the new values.
|
||||
4. If any flag's semantic has changed (not just a version bump), file an ADR
|
||||
amendment on `lib/providers/anthropic.mjs` Authority 1 source and pin the
|
||||
new version in ALIGNMENT.md.
|
||||
5. If `claude -p --help` no longer enumerates one of OLP's load-bearing flags,
|
||||
the plugin is broken against the new CLI — file a deletion or migration PR
|
||||
per ALIGNMENT.md Rule 4 (Unalignable Plugins / Fields Are Deleted).
|
||||
Reference in New Issue
Block a user