test(docs): keep Claude runtime guidance executable

[seonghobae]

Scope

Close one bounded #621 documentation-fitness defect with an executable contract rather than a prose-only correction.

Package metadata declares Python >=3.12, and resolve_backend("auto") fails closed when the compiled Rust core is unavailable, while protected-main CLAUDE.md advertised >=3.10 and a silent NumPy fallback. The branch now also exposes those facts as one machine-readable TOML contract so equivalent-but-contradictory prose cannot silently become the only guidance authority.

TDD lineage

• RED 154c644091c9ec6c0fce6bd62383cbb810d160e5 derives the supported Python floor from pyproject.toml and prohibits the stale automatic NumPy fallback claim.
• GREEN 2de7ef19e1c687138ab929af9d9e27020746261f aligns CLAUDE.md with shipped Python/backend behavior.
• 65f2f0c1822a385cd63394004aac662fb491df68 hardens the prose test against Markdown line wrapping.
• 11937780b00cb7b9c142868fa6755beef538984a removes an unrelated marginal-reference assertion.
• RED bad0e9f3bc8df2cd13a100270c7bbb5ddaef48a5 requires exactly one parseable runtime_contract block bound to package metadata and the Rust-required auto/reference-only NumPy ownership policy. Focused replay before the document change produced 1 failed, 2 passed because the block was absent.
• GREEN / exact current head 09dcd09b261567557e888a6232ca618ed5ffab57 publishes the contract. Focused verification produced 3 passed, and the test module compiles successfully.

Machine-readable contract

[runtime_contract]
requires_python = ">=3.12"
auto_backend = "rust_required"
numpy_role = "reference_parity_only"

The executable test requires exactly one marked TOML block, parses it with tomllib, requires string-valued fields, and compares the complete mapping to package/runtime ownership policy. Existing human-readable assertions remain as defense in depth.

Boundaries

No runtime code, numerical formula, estimator, dependency, security gate, hosted-product ownership, release policy, or Psychometrics Commons boundary changes.

Exact current state

• Protected base at the latest refetch: fb67ced09d8ee00542c05d56374537a9a7239751.
• Exact source head: 09dcd09b261567557e888a6232ca618ed5ffab57.
• GitHub reports the PR open, mergeable, and Draft.
• Exact-head CI/security/package/coverage/review evidence is being recomputed. Queued or running checks are non-passing, and predecessor-head evidence does not transfer.
• The prior OpenCode CHANGES_REQUESTED was submitted against predecessor head 11937780b00cb7b9c142868fa6755beef538984a; it remains historical review evidence and is not silently dismissed. A fresh exact-head decision is required.

Protected integration still requires every then-live exact-head gate, resolved review threads, and a qualifying independent non-author approval. No self-approval or gate weakening is used.

Advances #621.

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c2542bbb-44eb-45c6-9463-507f2b2c6607

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

@opencode-agent review the current exact PR head. Preserve all protected-main gates; do not merge or update the branch.

[seonghobae]

@coderabbitai review

[coderabbitai]

Rate Limit Exceeded

@seonghobae have exceeded the limit for the number of chat messages per hour. Please wait 6 minutes and 58 seconds before sending another message.

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 11937780b00cb7b9c142868fa6755beef538984a.

• Head SHA: 11937780b00cb7b9c142868fa6755beef538984a

• Workflow run: 31848864764

• Workflow attempt: 1

Coverage evidence

Coverage evidence job did not run or did not publish coverage evidence.

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file: CLAUDE.md"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file: CLAUDE.md"]
  R1 --> V1["required checks"]
  Evidence --> S2["Test: test_claude_runtime_contract.py"]
  S2 --> I2["regression suite"]
  I2 --> R2["Review risk: Test: test_claude_runtime_contract.py"]
  R2 --> V2["targeted test run"]

Loading

[opencode-agent]

OpenCode Review Overview

• Head SHA: 11937780b00cb7b9c142868fa6755beef538984a
• Workflow run: 31848864764
• Workflow attempt: 1
• Gate result: REQUEST_CHANGES (approval step)

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 11937780b00cb7b9c142868fa6755beef538984a.

• Head SHA: 11937780b00cb7b9c142868fa6755beef538984a

• Workflow run: 31848864764

• Workflow attempt: 1

Coverage evidence

Coverage evidence job did not run or did not publish coverage evidence.

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file: CLAUDE.md"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file: CLAUDE.md"]
  R1 --> V1["required checks"]
  Evidence --> S2["Test: test_claude_runtime_contract.py"]
  S2 --> I2["regression suite"]
  I2 --> R2["Review risk: Test: test_claude_runtime_contract.py"]
  R2 --> V2["targeted test run"]

Loading

[seonghobae]

@opencode-agent Please review exact current head 09dcd09b261567557e888a6232ca618ed5ffab57. The predecessor CHANGES_REQUESTED was bound to 11937780b00cb7b9c142868fa6755beef538984a; this head adds the RED/GREEN machine-readable runtime-contract regression described in the updated PR body. Review only; do not update the branch or merge.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[cursor]

Exact-head review of #833

Head 5c349bc5192177a5bf3e9747fb9bb7f62e318a7e correctly publishes the Claude runtime_contract TOML and stops CLAUDE.md from advertising a silent NumPy auto fallback. That slice matches shipped resolve_backend("auto") and pyproject.toml requires-python = ">=3.12".

The predecessor OpenCode CHANGES_REQUESTED on 11937780 is stale coverage-evidence for an older head. It is not a code defect in the current CLAUDE.md contract.

Buyer-facing gap that still blocks treating #833 as the #621 landing vehicle

README still tells a purchaser that auto "transparently falls back to the NumPy reference implementation when the extension is unavailable," and docs/commercial_readiness.md still names NumPy as the default runtime path. Those sentences are the opposite of shipped fail-closed ownership. A buyer following README would expect production to keep running without fast_mlsirm._core.

Issue #621 requires README / AGENTS / CLAUDE / PRD / TRD consistency and rejection of silent Python-production-fallback claims. CLAUDE.md alone is not enough.

Next action

Use #945 (16407195 on cursor/bc-4ace8e61-25c0-4757-9d00-18631c0d61d6-c3a0). It keeps the #833 contract and locks README, commercial-readiness, PRD, TRD, and ADR-0002 to fail-closed auto plus explicit backend="numpy" for parity only.

Do not merge #833 in parallel. Review #945 after its exact-head checks. Install a wheel or editable build that compiles fast_mlsirm._core before running backend="auto".

Local verification on the successor: 7 tests in tests/test_claude_runtime_contract.py passed, including the new README and commercial-readiness locks. No runtime, formula, or dependency changes.

CodeRabbit CLI is not installed in this runner (coderabbit: command not found). The GitHub CodeRabbit check on this PR is the skip-review SUCCESS marker, not a full diff review.

View PR

  

_{Sent by Cursor Automation: Fix Issues}