taodeng/ocp

Fork 0

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

Files

T

2853088261 [Constitution] Alignment principle + CI guardrails (addresses b87992f drift) (#20 )

* docs(constitution): establish OCP alignment constitution + CI guardrails (PR A)

Introduces the OCP project constitution to structurally prevent the kind
of scope drift that produced commit b87992f on 2026-04-11 (the fabricated
"/api/oauth/usage" endpoint, which does not appear in cli.js and broke
the dashboard usage bar for nine days).

This PR is governance-only. It does not modify server.mjs, package.json,
or any runtime code. It is intentionally shipped as one reviewable unit
per Iron Rule 11 (governance is one layer).

Files added:
  - ALIGNMENT.md
      Supreme scope document. Core principle: OCP is a proxy layer for
      Claude Code, not an extension layer. Five binding Rules: grep
      cli.js first; no invention; match the implementation; unalignable
      features are deleted; commits cite cli.js line numbers. Includes
      the 2026-04-11 drift postmortem, the Unalignable Policy, and an
      Annual Alignment Audit fixed to 11 April each year.

  - CLAUDE.md
      Project session instructions. Flags ALIGNMENT.md as required
      reading before any code. Codifies three hard requirements for
      server.mjs changes: cli.js citation, CI blacklist pass, and an
      independent reviewer per Iron Rule 10. References CC 开发铁律
      Rules 10, 11, and 12.

  - .github/PULL_REQUEST_TEMPLATE.md
      Mandatory "Claude Code Alignment Evidence" section. Three author
      checkboxes (cli.js citation, scope justification if cli.js does
      not perform the op, commit-message citations). Reviewer checklist
      requires opening cli.js at the cited lines before approval. A PR
      with this section blank receives request-changes.

  - .github/workflows/alignment.yml
      Hard-fail blacklist on server.mjs for tokens "api/oauth/usage"
      and "api/usage" (scan restricted to server.mjs; ALIGNMENT.md and
      CLAUDE.md may quote them as historical references). Soft check
      over all PR commit messages for "Claude Code uses X" / "cli.js
      uses X" assertions lacking a cli.js:NNNN or cli.js vE4 <fn>
      citation.

Historical reference: b87992f ("fix: use dedicated /api/oauth/usage
endpoint for reliable plan data") asserted the endpoint was used by
Claude Code CLI. The string does not occur in cli.js. Root cause was
LLM hallucination accepted without grep verification. See ALIGNMENT.md
-> Historical Lesson for the full record.

Merge precondition: this PR must be approved by an independent reviewer
(Iron Rule 10). The drafter of this commit may not self-approve.

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

* docs(alignment): pin first audit to 2026-04-20 (cli.js 2.1.89, SHA-256 a9950ef6)

First annual alignment audit pin. Records the cli.js version and content
hash that the current ALIGNMENT.md codified implementations mirror.

- Claude Code version: 2.1.89
- cli.js SHA-256: a9950ef6407fdc750bddb673852485500387e524a99d42385cb81e7d17128e01
- Audit date: 2026-04-20
- Auditor: Tao Deng

Next audit: 2027-04-11 (drift anniversary).

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

* ci(alignment): narrow blacklist to full host+path + strip comments before grep

Two false positives discovered during PR #20 bootstrap CI:
1. /api/usage is a legitimate OCP dashboard route (per-key quota, added
   in v3.8, server.mjs:1472). The bare token "api/usage" was too broad.
2. The ANCHOR warning comment in server.mjs (added by PR #21) references
   /api/oauth/usage as a DO-NOT-USE example, triggering the scanner.

Fix: require full host "api.anthropic.com/api/oauth/usage" to ensure
only real outbound fetch calls trip the guard, and strip line comments
with sed before grep so historical ANCHOR warnings pass.

Amendment procedure (ALIGNMENT.md) still governs future blacklist
changes.

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

---------

Co-authored-by: Oracle Public Cloud User <opc@instance-20230820-1333.subnet07301351.vcn07301351.oraclevcn.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-20 13:15:34 +10:00

4.2 KiB

Raw Blame History

OCP Project Session Instructions

WARNING — READ BEFORE WRITING ANY CODE IN THIS REPO

Before touching server.mjs or any network-facing surface, read ./ALIGNMENT.md in full. The constitution is binding. Non-compliant commits are reverted.

Before starting any task

Read ./ALIGNMENT.md. Internalize the five Rules and the 2026-04-11 drift lesson.
Run /dev-start <task description> to get a pre-flight plan that incorporates the iron rules, SKILL_ROUTING.md, this file, and ALIGNMENT.md.
If the task touches server.mjs, locate the corresponding cli.js reference before drafting any code. No code is written ahead of the grep cli.js evidence.

Hard requirements for `server.mjs` changes

Every PR that modifies server.mjs must satisfy all three of the following. A PR missing any one of them is blocked from merge.

cli.js citation. The commit message and PR body declare the corresponding cli.js function name and line number range, using the format cli.js:NNNN or cli.js vE4 <functionName>. If cli.js 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).
CI blacklist pass. The alignment.yml workflow must pass. The workflow greps server.mjs for known-hallucinated tokens (including api/oauth/usage and api/usage) and fails the build on any hit. Do not suppress the workflow. Do not add allowlist entries without an amendment PR to ALIGNMENT.md.
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, verify the cli.js citation by opening cli.js at the cited lines, and explicitly approve. A review comment that does not confirm the cli.js citation was checked is not a valid approval.

Iron rules in force

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

Iron Rule 10 (Code Review). Every implementation phase has an independent reviewer. Self-review does not count. See server.mjs 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, CLAUDE.md, the PR template, and the CI workflow are therefore shipped as the same constitutional PR (they are one layer: governance), but any subsequent server.mjs remediation lands as its own PR.
Iron Rule 12 (Pre-Brainstorm Prior-Art Search). Before proposing any new endpoint or header, search GitHub, Anthropic docs, and the cli.js bundle. For OCP specifically, the cli.js grep is the decisive search: if it does not hit, 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 Tao's workstations). Load them into session context with /cc-rules when needed.

Skills relevant to this repo

/dev-start — pre-flight planning, always first.
/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 prior drift incidents.

Commit message conventions

Subject line uses Conventional Commits (fix:, feat:, docs:, refactor:, chore:).
Any assertion of the form "Claude Code uses X" or "cli.js uses X" in the body must be immediately followed by a citation in the form cli.js:NNNN or cli.js vE4 <functionName>. CI performs a soft check for this pattern on all commits in the PR.
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 cli.js and ALIGNMENT.md, escalate to Tao (老大) via /cc-chat rather than guessing. Silent guessing is what produced the 2026-04-11 drift.

4.2 KiB Raw Blame History