mirror of https://github.com/dtzp555-max/olp.git synced 2026-07-21 21:15:10 +00:00

Files

T

taodengandClaude Opus 4.7 e96752a528 docs+fix+test: D36 — pre-Phase-2 batch #2 (issues #2 #5 #6 #13 #14 #15 )

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>

2026-05-24 20:38:16 +10:00

5.8 KiB

Raw Blame History

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:

Run claude --version on the project maintainer's primary workstation.
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.
Update the "Last capture", "Observed claude --version", and "Flag surface captured today" sections with the new values.
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.
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).

5.8 KiB Raw Blame History