Skip to content

invariants.md

Latest commit

 

History

History
37 lines (24 loc) · 3.18 KB

invariants.md

File metadata and controls

37 lines (24 loc) · 3.18 KB
Raw

Companion-repo source-of-truth invariants

Top spec: claude-code-parity-apr-poc.md

Four invariants (FALSIFY-CCPA-009..012) online from M0+ as required GitHub Actions status checks on the companion repo's main branch. See falsification-conditions.md for full gate registry.

Companion-repo source-of-truth invariants

The companion repo claude-code-parity-apr is source of truth for enforcement: implementation, fixtures, CI, coverage, pmat-comply config, and the running-binary that consumes the contract. The contract TEXT lives in aprender/contracts/ per the monorepo single-source-of-truth policy (feedback_monorepo_single_source_of_truth.md); the companion repo pins it by commit hash and gates every PR against it.

Four invariants, online from M0 (before any actual parity work), enforced as required GitHub Actions status checks on the companion repo's main:

Invariant 1 — ci/gate green (FALSIFY-CCPA-009)

  • Mechanism: GitHub branch protection on main requires status check ci/gate (matches aprender's policy in CLAUDE.md § "CRITICAL GIT WORKFLOW RULES"). Direct pushes to main blocked.
  • Falsifiable claim: gh api repos/paiml/claude-code-parity-apr/branches/main/protection \| jq '.required_status_checks.contexts | index("ci/gate") != null' returns true.
  • Failure mode caught: a bypassed merge that ships a red build.

Invariant 2 — pmat comply check 100 % (FALSIFY-CCPA-010)

  • Mechanism: CI step pmat comply check --strict runs on every PR; exit code 0 with zero violations is required.
  • Falsifiable claim: pmat comply check --json | jq '.total_violations == 0 and .compliance_pct == 100.0' returns true.
  • Why 100 %: the POC is small (~5 Rust crates) and greenfield. There is no legacy excuse.
  • Academic basis: prior-art compliance auditing literature (cf. arXiv:2102.05351 on coverage-completeness invariants).

Invariant 3 — Line coverage 100 % (FALSIFY-CCPA-011)

  • Mechanism: CI step cargo llvm-cov --workspace --fail-under-lines 100 --fail-uncovered-lines 0. (Branch coverage tracked but not gated until M6.)
  • Falsifiable claim: cargo llvm-cov report --json | jq '.data[0].totals.lines.percent == 100.0' returns true.
  • Tarpaulin policy: cargo tarpaulin is forbidden per aprender CLAUDE.md ("slow, unreliable, causes hangs"); only cargo llvm-cov.
  • Academic basis: coverage-guided test-adequacy literature; specifically the test-adequacy/MC-DC line of work (arXiv:2102.05351 and earlier).

Invariant 4 — pv validate on every commit (FALSIFY-CCPA-012)

  • Mechanism: pre-commit hook (.git/hooks/pre-commit installed by make hooks) AND CI step both run pv validate contracts/claude-code-parity-apr-v1.yaml. Exit 0 required.
  • Falsifiable claim: in CI logs, the line pv validate contracts/claude-code-parity-apr-v1.yaml is followed by exit code 0 within the same job.
  • Bash workarounds rejected per feedback_pv_not_bash_for_contracts.md and CLAUDE.md § "Contract Validation: DOGFOOD pv, NEVER bash" — if pv rejects the contract, fix the contract or extend aprender-contracts/src/schema/, never bypass with shell.