mirror of
https://github.com/dtzp555-max/ocp.git
synced 2026-07-21 21:15:09 +00:00
1dd6fb9440
Introduces an explicit two-class taxonomy of OCP endpoints to resolve the structural ambiguity surfaced by PR #99 (external response_format honoring on /v1/chat/completions): - Class A: cli.js-mirror endpoints. Rules 1-5 of ALIGNMENT.md apply verbatim. Citation requirement unchanged (cli.js:NNNN). The 2026-04-11 drift discipline is preserved without weakening. - Class B: OCP-owned compatibility endpoints. Anchored to OpenAI's /v1/chat/completions specification (B.1) or to an authorizing ADR (B.2). Citation shifts to spec section + ADR number. Class B inherits the same anti-invention discipline; the anchor differs. Grandfather provision in ADR 0006 retroactively authorizes the 12 existing B.2 administrative endpoints at v3.16.4 behaviour (one-time, contract-frozen). New B.2 endpoints or any new method on a grandfathered endpoint requires its own ADR per Rule 4 (Class B mapping). Changes: - new: docs/adr/0006-openai-shim-scope.md - new: docs/openai-compat-pin.md (placeholder for first B.1 audit) - mod: ALIGNMENT.md (Class B section, rule mapping table, updated Unalignable Policy and Annual Audit scope; Rules 1-5 byte-identical) - mod: .github/PULL_REQUEST_TEMPLATE.md (Endpoint Class radio, separate evidence sections for A vs B, reviewer checklist updated) - mod: docs/adr/README.md (index entry for ADR 0006) Independent reviewer (fresh-context opus per Iron Rule 10) verified: all 12 load-bearing checks pass — Rules 1-5 byte-identical to origin/main, 2026-04-11 drift narrative unchanged, explicit non-relitigation safeguard present in ADR 0006, grandfather provision narrowly scoped, Class B inventory matches server.mjs reality (14/14), single governance layer per Iron Rule 11 (no server.mjs touch), alignment.yml unmodified. Verdict: APPROVE_WITH_MINOR with 3 of 5 non-blocking suggestions folded in (operations-vs-endpoints precision, PR template Hybrid wording, openai-compat-pin.md stub). Triggering incident: PR #99 by external contributor (response_format honoring on /v1/chat/completions). This governance PR ships separately per Iron Rule 11 (IDR); the feature PR #99 will rebase on this and declare Class B with ADR 0006 citation. Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2.6 KiB
2.6 KiB
Architecture Decision Records
This directory holds the OCP Architecture Decision Records (ADRs) — short documents that capture the why behind structural choices.
Read these before proposing governance, SPOT (single-source-of-truth), or process changes.
Numbering
ADRs start at 0002. The first one (0001) was reserved for an early
internal proposal that was superseded before publication; 0002 is
deliberately the first published record so the archived 0001 slot
remains a placeholder rather than being silently renumbered.
New ADRs increment from the highest existing number. Filenames are
NNNN-<short-slug>.md.
Index
| ADR | Title | What it covers |
|---|---|---|
| 0002 | Alignment Constitution | The ALIGNMENT.md constitution: why every server.mjs change requires cli.js citation + independent reviewer + CI blacklist pass. Background: the 2026-04-11 drift incident. |
| 0003 | models.json as SPOT |
Why model IDs / aliases / context windows live in a single JSON file (not duplicated in server.mjs and setup.mjs arrays). v3.11.0 refactor. |
| 0004 | OpenClaw Auto-Sync | Why scripts/sync-openclaw.mjs runs on ocp update, what its scope boundary is (writes only models.providers["claude-local"].models and agents.defaults.models["claude-local/*"]), and the idempotency contract. |
| 0005 | No Multi-Provider | Why OCP stays single-provider (Anthropic-via-cli.js) and does not extend to OpenAI / Gemini / OpenRouter. Cost estimate: ~7 weeks for a v1 that buys neither moat nor commercial readiness. Separate commercial work starts in a separate repo. |
| 0006 | OpenAI Shim Scope | The Class A / Class B taxonomy. Class A endpoints (cli.js-mirror) keep Rules 1–5 verbatim; Class B endpoints (OCP-owned compatibility surface — /v1/chat/completions, /v1/models, admin endpoints) are anchored to OpenAI's spec (B.1) or to an authorizing ADR (B.2). Triggered by PR #99 (external response_format honoring). Grandfathers the existing B.2 inventory at v3.16.4. |
When to write a new ADR
Open one whenever:
- A structural rule is being added or changed (e.g., new SPOT, new boundary, new CI guardrail).
- A decision encodes a lesson from an incident or drift.
- 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 is the standard skeleton. Cite incidents, PRs, or commits where useful.