olp/CLAUDE.md

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

OLP Project Session Instructions

WARNING — READ BEFORE WRITING ANY CODE IN THIS REPO

Before touching any provider plugin (lib/providers/*.mjs), the entry surface (server.mjs request handlers), or the IR (lib/ir/*), read ./ALIGNMENT.md in full. The constitution is binding. Non-compliant commits are reverted.

---

Before starting any task

1. Read ./ALIGNMENT.md. Internalize the five Rules and the three-authority model (per-provider CLI / OpenAI spec / IR contract).
2. Run /dev-start <task description> to get a pre-flight plan that incorporates the iron rules, SKILL_ROUTING.md, this file, and ALIGNMENT.md.
3. Locate the provider authority before drafting any code:
   • Provider-plugin change → identify the provider CLI documentation page or observed behaviour you are matching, and pin the CLI version.
   • Entry-surface change → identify the OpenAI /v1/chat/completions spec section and URL.
   • IR change → identify the ADR you are amending or co-merging. No code is written ahead of the authority citation.

---

Hard requirements for plugin / server.mjs / IR changes

Every PR that modifies a provider plugin, the entry surface in server.mjs, or the IR in lib/ir/ must satisfy all three of the following. A PR missing any one of them is blocked from merge.

1. Authority citation. The commit message and PR body declare the relevant authority and citation:
   • Provider plugin → <provider> CLI <version> § <section-or-flag> plus URL or transcript reference.
   • Entry surface → OpenAI spec URL plus the specific field, parameter, or behaviour.
   • IR → ADR NNNN § <section> (and the amending ADR if applicable). If the underlying authority does not perform the operation, the PR must state this explicitly and justify scope under ALIGNMENT.md Rule 2 (in practice, this almost always means the PR should be closed).
2. CI alignment.yml pass. The workflow must pass. It greps for known-hallucinated tokens, validates models-registry.json, and soft-checks per-provider commit citations. New blacklist tokens are added via PR amendment to alignment.yml; removing entries requires an ALIGNMENT.md amendment PR. Do not suppress the workflow.
3. Independent reviewer (Iron Rule 10). The implementation author may not self-approve. A separate reviewer — human or a subagent spawned with a fresh context — must read the diff, open the cited authority (provider CLI doc / OpenAI spec / ADR), and explicitly confirm the citation. A review comment that does not confirm the authority was checked is not a valid approval.

---

Iron rules in force

This repo operates under the CC Development Iron Rules (CC 开发铁律) v1.4. Three rules are load-bearing for OLP work:

• Iron Rule 10 (Code Review). Every implementation phase has an independent reviewer. Self-review does not count. See hard requirement #3 above.
• Iron Rule 11 (Incremental Diff Review). Non-trivial work is split into the minimum reviewable unit — one PR per layer per severity. ALIGNMENT.md, this file, the PR template, and the CI workflows are shipped as a single constitutional PR (one layer: governance). Subsequent layers (plugin loader, individual provider plugins, IR serializers, cache layer, fallback engine, dashboard) each land as their own PR.
• Iron Rule 12 (Pre-Brainstorm Prior-Art Search). Before proposing any new IR field, fallback trigger, or provider plugin, search the relevant provider's docs, OpenAI's spec, the local docs/adr/, and the cross-machine ~/.cc-rules/memory/learnings/. The provider-specific search is the decisive one: if the provider CLI does not perform the operation, Rule 2 of the constitution applies.

The full iron rules are at ~/.claude/CC_DEV_IRON_RULES.md (symlinked from the cc-rules repo on the maintainer's workstations). Load them into session context with /cc-rules when needed.

---

Skills relevant to this repo

• /dev-start — pre-flight planning, always first for non-trivial tasks.
• /cc-rules — load the iron rules into context.
• /agent-dispatch — pick the correct model (opus for design and review, sonnet for straightforward edits, haiku for mechanical chores) before spawning any subagent.
• /cc-mem search <keyword> — look up cross-machine memory for prior decisions, especially provider-policy events and CLI-version migrations.

---

Commit message conventions

• Subject line uses Conventional Commits (fix:, feat:, docs:, refactor:, chore:).
• Provider-plugin commits include the citation pattern <provider> CLI <version> or a direct provider docs URL in the body. CI performs a soft check.
• Entry-surface commits include an OpenAI spec URL.
• IR commits cite the authorizing or amending ADR.
• Any assertion of the form "Provider X uses Y" in the body must be immediately followed by a citation (CLI version + section, or docs URL, or observed-transcript reference). CI soft-checks the pattern.
• Co-author trailer is required for LLM-assisted commits (Co-Authored-By: Claude <model> <noreply@anthropic.com>).

---

Project-level escalation

If a design decision cannot be resolved by reference to the relevant authority (provider CLI / OpenAI spec / ADR) and ALIGNMENT.md, escalate to the project maintainer via /cc-chat rather than guessing. Silent guessing is what produced OCP's 2026-04-11 drift; OLP inherits that institutional lesson and does not repeat it.

---

Release kit overlay (CC 开发铁律 第五律 5.5)

This project's overlay per iron rule v1.4's 5.5. Machine-checkable declaration.

release_kit:
  version_source: package.json
  changelog: CHANGELOG.md
  release_channel:
    type: github-release
    tag_format: v{semver}
    auto_create_on_tag_push: true   # via .github/workflows/release.yml
  docs_source: README.md
  resource_lists:
    - name: Supported Providers table
      location: README.md § "Supported Providers"
      source_of_truth: models-registry.json
    - name: Routing chains table
      location: README.md § "Configuration"
    - name: API Endpoints table
      location: README.md § "API Endpoints"
    - name: Environment Variables table
      location: README.md § "Environment Variables"
  new_feature_doc_expectations:
    - new provider plugin → README § "Supported Providers" entry + ADR 0006 inclusion entry + risk-tier classification
    - new fallback trigger → README § "Configuration" + tests in test-features.mjs
    - new IR field → ADR 0003 amendment + README impact note (if user-visible)
    - new env var → README § "Environment Variables" table
    - new endpoint → README § "API Endpoints" table + relevant Config / Troubleshooting §
    - new auto-sync / hook → dedicated §, must document trigger + manual invocation + opt-out + any bootstrap quirk
    - new file / SPOT / schema → Architecture or contributor § with link
  bootstrap_quirk_policy:
    - any first-run migration quirk (e.g., from OCP) → README § "Troubleshooting" + scripts/migrate-from-ocp.mjs if applicable
    # NOTE: scripts/migrate-from-ocp.mjs 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.
  phase_rolling_mode:
    # Iron Rule 5 (release-kit version bump before push) applies at Phase boundaries,
    # NOT to individual D-day commits within a Phase.
    #
    # Rationale: OLP Phase 1 is a single cohesive deliverable (boot layer + provider
    # plugins + cache + fallback engine + hardening). Bumping a version tag for every
    # D-day push would produce 30+ noise tags with no user-facing semantic boundary.
    # ADR 0005 § "Cache key stability" requires that key composition is stable across
    # a release; mid-phase tag churn would falsely signal stability windows.
    #
    # Policy:
    #   - While a Phase is in progress, individual D-day pushes land under "Unreleased"
    #     in CHANGELOG.md. package.json stays at the Phase-N pre-release identifier
    #     (e.g. "0.1.0-bootstrap" during Phase 1 boot; the token may be updated to
    #     "0.1.0-phase1" once Phase 1 implementation starts landing).
    #   - The version bump + git tag fires at Phase CLOSE — a dedicated "Phase N close"
    #     PR that bumps package.json, promotes "Unreleased" to the release version in
    #     CHANGELOG.md, and triggers .github/workflows/release.yml via the tag push.
    #   - The Phase close PR is triggered explicitly by the project maintainer; it is
    #     NOT automatic. No automated tooling bumps the version.
    #   - Cross-Phase discipline: if D-day work touches a boundary already tagged (e.g.
    #     a hotfix to a shipped Phase N deliverable), follow Iron Rule 5 normally — bump
    #     patch, tag, release before pushing.
    #
    # This overlay is the authoritative source. If Iron Rule 5 appears to be silently
    # violated (no version bump after many D-day pushes), check this section first
    # before filing a compliance finding.
    current_phase: Phase 2
    current_pre_release_identifier: "0.2.0-phase2"
    phase_close_trigger: explicit maintainer action (not automated)