mirror of
https://github.com/dtzp555-max/olp.git
synced 2026-07-21 21:15:10 +00:00
b1afcde929
Closes Phase 3. All 15 ADR 0008 § 10 acceptance criteria shipped +
tested across Suite 23/24/25/26/20h-extra-audit. 7 D-day commits
(D48 ADR + D49-D54 implementation) shipped between 2026-05-25 under
the standing-autopilot grant.
Per CLAUDE.md release_kit.phase_close_trigger this PR is the explicit
maintainer-triggered close action (user "go" to start; this commit
to ship).
CHANGES IN THIS COMMIT (release-kit machinery only — no code):
package.json:
- version 0.2.0 → 0.3.0
CLAUDE.md release_kit.phase_rolling_mode:
- current_phase: Phase 3 → Phase 4
- current_pre_release_identifier: "0.3.0-phase3" → "0.4.0-phase4"
CHANGELOG.md:
- Unreleased promoted to "## v0.3.0 — 2026-05-25" with D48-D54
entries intact (already accumulated under phase_rolling_mode
discipline during Phase 3 D-days).
- New Phase 3 release_kit checklist + ADR 0008 § 10 acceptance
criteria final-ship table + Phase 3 D-day index + known-
limitations-beyond-v0.3.0.
- New "## Unreleased\n\n(empty — Phase 4 entries land here once
Phase 4 opens)" sentinel for the next phase. D37
phase_rolling_mode gate will pass (sentinel-only Unreleased).
README.md:
- Status header v0.2.0+v0.3.0-in-progress → v0.3.0 shipped;
Phase 4 next.
- Implementation status note: Phase 3 in-progress → closed at
v0.3.0; ADR 0008 § 10 all 15 acceptance criteria shipped.
- Phase plan Phase 3 marker 🟡 → ✅ Shipped (D48 → D54).
Test count 601 / 601 pass (npm test verified locally; no test or
.mjs file touched in this release commit).
NEXT STEPS (post-merge, auto-triggered):
- git tag v0.3.0 + git push --tags
- release.yml fires: phase_rolling_mode gate passes (Unreleased is
sentinel-only) + GitHub Release auto-published from the CHANGELOG
v0.3.0 section.
ACKNOWLEDGEMENTS:
- Phase 3 executed under maintainer's standing autopilot grant
(~/.cc-rules/memory/auto/standing_autopilot_phase_2.md in
cc-rules bf0ed9a); D-day cadence: 6 implementation D-days + ADR
+ multiple opus-reviewer fold-ins, all in a single session.
- ADR 0008 was authored via D48 with fresh-context opus review
finding 3 P-class items (1 P2 owner_only_block formalization + 2
P3 citation/shape gap). Folded in before ratification.
Authority:
- CLAUDE.md release_kit overlay phase_rolling_mode (Iron Rule 5.5)
governs this commit's shape; phase_close_trigger requires
explicit maintainer action — the user issued "go" to trigger.
- ADR 0008 (Phase 3 design contract) — § 10 acceptance criteria
#1–#15 covered.
- CC 开发铁律 v1.6 § 10 — fresh-context opus reviewer required for
every implementation phase + design ADR (executed on D49, D50,
D51, D52, D53, D54, and D48 ADR draft).
Co-authored-by: dtzp555 <dtzp555@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
142 lines
9.1 KiB
Markdown
142 lines
9.1 KiB
Markdown
@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`](./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.
|
|
|
|
```yaml
|
|
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 4
|
|
current_pre_release_identifier: "0.4.0-phase4"
|
|
phase_close_trigger: explicit maintainer action (not automated)
|
|
```
|