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

Files

T

taodengandClaude Opus 4.7 d85a2dcf71 docs: D20 — honest forward-reference annotations across README/ADRs (Finding 9)

cold-audit catch from 2026-05-23

Cold-audit Finding 9 (P3 drift): multiple docs referenced files / paths
/ directories that don't exist at the current implementation state. A
reader following AGENTS.md § "Key files to know" to read lib/keys.mjs
would find no such file; following README architecture to dashboard.html
same; ADR 0005 § D1 described a `~/.olp/cache/<key>/<prefix>/<hash>.json`
layout that doesn't exist (current impl is in-memory Map per
lib/cache/store.mjs). D20 doesn't gut the designs — it adds honest
status callouts so the gap is obvious within seconds.

Files changed (8, docs only, +46 / -14):

1. README.md (+32 / -3):
   - New H2 section "Implementation status (as of 2026-05-24)" with a
     10-row table distinguishing ✅ Shipped vs 📋 Planned, including phase
     numbers (Phase 2 / 6 / 7) matching the existing §"Phase plan"
   - Inline status annotation on the multi-key auth bullet
     (lib/keys.mjs marked planned for Phase 2)
   - Inline status on the cache layer bullet (file-backed storage marked
     Phase 2 — current is in-memory Map)
   - Migration section's Phase 7 placeholder annotated explicitly

2. AGENTS.md (+8 / -3):
   - Inline `📋 Planned (Phase N) — not yet authored` markers on
     lib/keys.mjs and dashboard.html in the "Key files" bullet list
   - Inline marker on setup.mjs reference in the
     "Project-specific constraints" section
   - New "Implementation status note" paragraph at the end of the Key
     files block pointing to README's status table for the full picture

3. ALIGNMENT.md (+6 / -3):
   - docs/openai-spec-pin.md references (Authority 2 + audits section)
     tightened from "deferred" to "deferred, not yet authored; must be
     created before first annual audit (target: v1.0)"
   - docs/alignment-audits/ directory annotated as "directory does not
     exist yet; it is created when the first audit is conducted"

4. CLAUDE.md (+2):
   - release_kit.bootstrap_quirk_policy YAML retains the
     scripts/migrate-from-ocp.mjs reference (forward-looking spec
     compliance) and adds an inline YAML comment explicitly noting
     "is planned (Phase 7), not yet authored. The scripts/ directory
     does not currently exist. References here are forward-looking;
     do not attempt to run this script."

5-8. ADR amendments (status notes only — no Amendment blocks, since
     these are clarifications about implementation state, NOT decision
     changes per se):
   - ADR 0001 (Consequences/Negative): scripts/migrate-from-ocp.mjs
     annotated as Phase 7 planned
   - ADR 0003 § Decision (lossy-translation paragraph): inline note that
     docs/provider-caveats.md is planned; until it exists, lossy edges
     are recorded only in plugin headers. Plus a status mention in
     Consequences/Positive
   - ADR 0004 Mitigations: docs/provider-caveats.md annotated as planned
   - ADR 0005 § Decision (D1 paragraph): the file-backed layout block
     reframed from "Cache directory structure:" to "Designed file-backed
     layout (target for Phase 2 storage adapter):". Added a status
     blockquote explicitly noting "v0.1 implementation in lib/cache/store.mjs
     uses an in-memory Map; no files written to ~/.olp/cache/. The
     file-backed layout described above is the designed shape; it
     transitions in via a Phase 2 storage adapter. Per-key isolation and
     singleflight (D4) are live; file persistence is not."

Note on ADR Decision-section edits (corrected from initial writeup):
two ADR amendments DO touch Decision-section text (ADR 0003 lossy-
translation paragraph, ADR 0005 D1 cache layout). Both edits are
conservative — status caveats that preserve the original prose verbatim
(0003) or reframe section headings without changing the path-shape spec
(0005). No design content is gutted. No Amendment block was added
because the decisions themselves aren't changing; these are clarifications
about what's live today vs designed. The discipline boundary here:
inline-status-note ≠ decision-amendment.

Tests: 328/328 unchanged (sanity check; docs-only changes).

7/7 Finding 9 forward references annotated (confirmed by reviewer
running independent `ls` on each path):
- lib/keys.mjs ❌ doesn't exist → annotated
- dashboard.html ❌ doesn't exist → annotated
- docs/provider-caveats.md ❌ → annotated (2 ADR sites + Consequences)
- docs/openai-spec-pin.md ❌ → annotated (ALIGNMENT.md Authority 2)
- docs/alignment-audits/ ❌ → annotated
- scripts/migrate-from-ocp.mjs ❌ → annotated (README + ADR 0001 + CLAUDE.md release_kit)
- setup.mjs ❌ → annotated (AGENTS.md)

Authority:
- README/AGENTS.md/ADR/ALIGNMENT.md/CLAUDE.md self — the doc set is
  its own authority for what it documents; D20 brings each statement
  into honest agreement with the current implementation
- CC 开发铁律 v1.6 § 10.x — Cold Audit Finding 9

Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent
of drafter): APPROVE_WITH_MINOR. Verified each Finding 9 path doesn't
exist via independent `ls`; cross-checked phase numbers match the
existing §"Phase plan" listing; ran `npm test` to confirm 328/328
unchanged. Two non-blocking minors:

1. Implementer's initial writeup overstated "ADR decision text NOT
   edited" — reality is two Decision-section paragraphs got inline
   status caveats. Commit message above is corrected.

2. Reviewer found an additional drift D20 didn't address: ADR 0002 §
   Decision filesystem layout lists `vibe.mjs` for the Mistral plugin,
   but the shipped file is `mistral.mjs` (the binary is `vibe`, the
   plugin file is `mistral`). Different drift class from Finding 9
   (file exists, just named differently in the ADR). Filed as
   follow-up issue.

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

2026-05-24 12:26:02 +10:00

7.7 KiB

Raw Blame History

Inherits: @~/.cc-rules/AGENTS.md

OLP — Open LLM Proxy — Agent Guidelines

Scope: the dtzp555-max/olp repository. Audience: any AI coding agent (Claude Code / Cursor / OpenCode / Copilot / Codex / Gemini) touching OLP source.

What this project is

OLP (Open LLM Proxy) is a personal- and family-scale multi-provider LLM proxy. It exposes a single OpenAI-compatible HTTP endpoint (/v1/chat/completions) and routes each request to one of N provider plugins, each of which spawns the corresponding provider CLI (e.g. claude -p, codex exec --json, vibe --prompt). An IR (Intermediate Representation) normalizes between the entry surface and each provider's native shape. Intelligent fallback chains advance one provider at a time on configured triggers; content-addressed caching minimizes quota consumption.

OLP supersedes OCP (Open Claude Proxy) as of v1.0. The trigger was the 2026-05-14 Anthropic announcement (effective 2026-06-15) splitting CLI/Agent SDK traffic out of the Pro/Max subscription pool — OCP's foundational assumption ("subscription = unlimited within rate limits") broke for Anthropic on that date. Spreading risk across multiple providers is the structural response.

OLP is not a commercial multi-tenant SaaS, not an enterprise gateway competing with LiteLLM/OpenCode/CLIProxyAPI on breadth, not a model-capability router ("route to the smartest model"), and not a conversation-state store (clients manage their own state). See ALIGNMENT.md Core Principle and docs/adr/0001-project-founding.md.

Runtime: Node.js (ESM, .mjs throughout). No build step. No bundler. server.mjs is the single executable entrypoint. The architecture is spawn-binary: OLP spawns the real provider CLI for every uncached request.

Stack

Node.js >=18, native ESM modules
http/https built-ins for the proxy core (no Express, no Fastify)
models-registry.json as the single source of truth for (provider, model) → metadata mappings (analogous to OCP's models.json; SPOT discipline will be codified in a Phase 1 ADR — OLP ADR 0003 is currently the IR design, not the SPOT codification)
GitHub Actions for CI (alignment.yml, release.yml, test.yml)
gh CLI assumed for PR creation and release automation
No TypeScript. No test framework beyond test-features.mjs (run via npm test; CI workflow .github/workflows/test.yml). Keep dependencies minimal.

Key files to know

server.mjs — HTTP listener, entry surface (/v1/chat/completions, /health, /v1/models, etc.), plugin loader, request dispatch. Governed by ALIGNMENT.md.
lib/providers/ — per-provider plugins. Each file (anthropic.mjs, openai.mjs, mistral.mjs, …) implements the Provider contract documented in ADR 0002.
lib/ir/ — Intermediate Representation definition + serializers. Governed by ADR 0003.
lib/cache/ — content-addressed cache layer (per-key isolation, cache_control bypass, chunked stream replay, singleflight). Governed by ADR 0005.
lib/fallback/ — fallback engine (trigger detection, chain advancement, idempotent-failure safety, header annotation). Governed by ADR 0004.
lib/keys.mjs — multi-key auth, per-key namespacing, audit log. Carries OCP's per-key isolation model into OLP. 📋 Planned (Phase 2) — not yet authored.
dashboard.html — owner-only multi-provider dashboard (quota panels, fallback rate, cache hit rate). 📋 Planned (Phase 6) — not yet authored.
models-registry.json — single source of truth for (provider, model) → metadata. SPOT.
ALIGNMENT.md — the constitution. Binding for any plugin / entry-surface / IR change.
docs/adr/ — Architecture Decision Records. Read the index in docs/adr/README.md before proposing governance, SPOT, or contract changes.
.github/workflows/alignment.yml — CI blacklist grep + per-provider citation soft check; fails the build on known-hallucinated tokens.
CLAUDE.md — Claude-Code-specific session instructions + release_kit overlay (Iron Rule 5.5).

Implementation status note (as of 2026-05-24): Files marked 📋 above are designed and documented but not yet on disk. For the full status table see README.md § "Implementation status". Do not attempt to read or import these files — they will not be found. The shipped set as of Phase 1 is: server.mjs, lib/ir/, lib/providers/{anthropic,codex,mistral}.mjs, lib/cache/{keys,store}.mjs, lib/fallback/engine.mjs, models-registry.json, test-features.mjs.

Project-specific constraints

ALIGNMENT.md is binding. Any PR touching a provider plugin, the entry surface, or the IR must cite the relevant authority (provider CLI documentation / OpenAI spec URL / ADR number) in the commit body and PR description. See CLAUDE.md § "Hard requirements for plugin / server.mjs changes" and ALIGNMENT.md Rules 1, 2, 5.
Alignment CI is not suppressible. The alignment.yml workflow greps for known-hallucinated tokens (currently carrying OCP's api.anthropic.com/api/oauth/usage as a transitive guardrail) and runs per-provider sanity checks. Adding new blacklist tokens is done via PR amendment to alignment.yml; removing entries requires an ALIGNMENT.md amendment PR.
No self-approval. Implementation author cannot merge their own PR (Iron Rule 10). A fresh-context reviewer must open the cited authority and confirm in the review comment.
models-registry.json is the only place to add/edit (provider, model) metadata. Do not touch hardcoded model maps in server.mjs, lib/providers/*.mjs, or setup.mjs (📋 setup.mjs is planned, not yet authored). The OLP ADR that codifies this SPOT discipline lands in Phase 1 (OCP's ADR 0003 — models.json SPOT — is the precedent; OLP needs its own SPOT ADR because the registry shape differs).
Provider plugins follow the contract in ADR 0002. A new provider plugin must implement every method on the Provider contract (name, displayName, models, auth, spawn, estimateCost, quotaStatus, healthCheck, hints). Partial implementations are unalignable per ALIGNMENT.md Rule 4.
No anti-fingerprinting. OLP is honest about spawning the real CLI. If a provider detects subscription-spawn proxying and bans it, the response is to drop the provider per ADR 0006, not to mask the spawn.
No conversation state. OLP is a stateless proxy. Memory / continuity is the client's responsibility (see ADR 0001 § Non-mission).

Release protocol

OLP follows the machine-readable release_kit: overlay in CLAUDE.md (Iron Rule 5.5). Before any version bump or tag push, re-read that YAML block and walk every item in new_feature_doc_expectations and bootstrap_quirk_policy. Tag push triggers .github/workflows/release.yml, which creates the GitHub Release automatically — do not create the release manually.

Version is sourced from package.json; changelog from CHANGELOG.md; user-facing docs from README.md. The Supported Providers table in README.md is sourced from models-registry.json per the overlay; do not hand-edit it out of sync.

Handoff expectations

A fresh session picking up OLP work should read, in order:

This file (AGENTS.md).
ALIGNMENT.md — constitution; non-optional.
CLAUDE.md — tool-specific instructions and release_kit overlay.
docs/adr/ — most recent ADRs first; they explain why the current structure exists. Founding ADRs 0001–0006 are the OLP-bootstrap set.
~/.cc-rules/memory/projects/olp_v0_1_spec.md — the v0.1 spec (authoritative for OLP scope until v1.0 ships).
~/.cc-rules/memory/auto/MEMORY.md — cross-machine memory index.

Only after these should the session touch code.

Authors: project maintainer (with AI drafting assistance).

7.7 KiB Raw Blame History Unescape Escape