mirror of
https://github.com/dtzp555-max/olp.git
synced 2026-07-19 09:45:07 +00:00
taodengandClaude Opus 4.7
f659e29c09
cold-audit catch from 2026-05-23 Retroactive contract sync addressing cold-audit Finding 4 (P2 governance). D10 (commit2cfd0b1) added `maxSpawnTimeMs` to all three plugins + spawn-timeout enforcement loop but did not amend ADR 0002 § Provider contract in the same merge. ALIGNMENT.md Rule 1 (Cite First) + CLAUDE.md § "Hard requirements" item 1 (Authority citation) both require contract additions to be authority-cited at landing. Changes (single file, ADR 0002 only): 1. New `## Amendments` section after the header block documenting: - Cold-audit Finding 4 as the originating finding - Commit2cfd0b1as the already-landed code - CC 开发铁律 v1.6 § 10.x as the procedural mechanism that caught it - ADR 0004 § Trigger taxonomy — Hard triggers bullet 4 as the authority 2. Expanded `hints` documentation from bare-key list to indented sub-bullets with one-line description per key. All four keys now documented: - requiresTTY (boolean fingerprint) - concurrentSpawnSafe (boolean fingerprint) - maxConcurrent (declarative hint only at v0.1; type-validated at startup, no runtime enforcement wired — separate tracking issue to be filed) - maxSpawnTimeMs (new — milliseconds, default 600000, ADR 0004 cited) Diff-review (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent of drafter) flagged two issues on first pass: - **B1 blocking**: original draft claimed maxConcurrent was "enforced by the spawn-concurrency guard in server.mjs" — grep verified zero such guard exists. Folded in: replaced with honest declarative-only framing. The irony of D11 itself shipping the same class of documentation–implementation drift it was opened to remediate was caught by the reviewer; the fold-in closes the loop cleanly. - **N1 non-blocking**: original draft cited ALIGNMENT.md Rule 2(c) as primary authority, but Rule 2(c)'s literal wording is scoped to IR fields. Folded in: cite Rule 1 (Cite First) + CLAUDE.md § "Hard requirements" item 1 as primary, noting Rule 2(c)'s spirit extends to Provider-contract additions. Follow-up tracked separately: actual runtime enforcement of maxConcurrent (semaphore / in-flight counter / spawn queue) — declarative→actual closure to be filed as GitHub issue. Authority: - ADR 0002 self-amendment (in-place) - ADR 0004 § Trigger taxonomy bullet 4 https://github.com/dtzp555-max/olp/blob/main/docs/adr/0004-fallback-engine.md - ALIGNMENT.md Rule 1 + CLAUDE.md § "Hard requirements" item 1 - CC 开发铁律 v1.6 § 10.x (procedural authority for cold-audit catch tag) https://github.com/dtzp555-max/cc-rules/blob/main/CC_DEV_IRON_RULES.md Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Architecture Decision Records — OLP
This directory holds the OLP Architecture Decision Records (ADRs) — short documents that capture the why behind structural choices.
Read these before proposing governance, plug-in contract, IR, fallback, cache, or provider-inclusion changes.
Numbering
ADRs in OLP start at 0001 (the project's founding decision). OLP did not inherit the 0001 placeholder convention OCP used; the project starts on a fresh numbering line.
New ADRs increment from the highest existing number. Filenames are NNNN-<short-slug>.md.
Index
| ADR | Title | What it covers |
|---|---|---|
| 0001 | Project Founding | Why OLP exists (the 2026-06-15 Anthropic billing-split trigger), mission + non-mission boundaries, explicit supersession of OCP ADR 0005 "No Multi-Provider". |
| 0002 | Plugin Architecture for Providers | The lib/providers/<name>.mjs plug-in model, the Provider contract (name / models / auth / spawn / estimateCost / quotaStatus / healthCheck / hints), static in-tree registry, why-not full external plugin discovery. |
| 0003 | Intermediate Representation (IR) Design | The OLP-internal canonical request/response shape between the OpenAI-compat entry surface and each provider plugin. v1.0 IR fields, IR-vs-OpenAI-vs-native-provider three-shape model, IR is not exposed externally. |
| 0004 | Fallback Engine Semantics & Safety | Trigger taxonomy (Hard / Soft / Deterministic-deferred / Cost-aware-deferred), idempotent-failure safety (first-chunk rule), chain advancement one-at-a-time, observability headers. |
| 0005 | Cache Layer Cross-Provider Design | Cache key composition over (provider, model, messages, …), per-model isolation, D1+D2+D3+D4 port from OCP v3.13.0, cross-provider fallback cache behaviour (correct miss). |
| 0006 | Provider Inclusion / Exclusion + Risk-Tier Framework | The 4-tier classification (A excluded by default / B explicit consent / C opt-in / D eligible-for-default-enabled), Candidate-vs-Enabled distinction, current v0.1 candidate inventory (0 Enabled), Antigravity exclusion rationale (named prohibition + no cost advantage + reinstatement friction; pending primary-source pin), consent UX, future provider addition procedure. |
When to write a new ADR
Open one whenever:
- A structural rule is being added or changed (e.g., new IR field, new trigger type, new cache-key composition).
- A new provider plugin is being proposed (per ADR 0002 + ADR 0006 — ADR is a hard prerequisite for plugin merge).
- A decision encodes a lesson from an external event (provider policy change, drift incident).
- A future contributor reading the code alone could plausibly undo or re-litigate the choice.
Skip ADRs for routine implementation choices (algorithm pick, naming) — those belong in commit messages.
Format
Keep ADRs short — Context / Decision / Consequences / Alternatives is the standard skeleton. Cite incidents, PRs, or commits where useful. Length per ADR ~150–250 lines; longer than that, split.