governance: make ProofPath capability canonicality explicit (FCRP-SELF-005)

[safal207]

Summary

This PR adds the repository-level refactor identified by FCRP-SELF-005: Canonical Reality Drift.

The audit found that ProofPath has two different kinds of reality at once:

• main continues to evolve and already contains promoted capabilities such as SCIG v0.1 (feat: SAFE Causal Incident Graph v0.1 #219);
• a long PoCI → Deploy Guard → Evidence → Control Cloud → Admission → Governance trajectory remains implemented and tested in stacked open PRs, but is not present in canonical main.

The first meaningful divergence is PR #193 (PoCI v0.1 contract). It is the earliest open capability in the current stack, is based directly on main, and later capabilities build transitively on it while it remains unmerged.

This PR does not solve that by mass-merging the stack. It adds an explicit promotion/canonicality contract so branch architecture can no longer be mistaken for ambient ProofPath capability.

Added

• governance/capability-manifest.v0.1.json
  • audited capability identities and dependency graph;
  • exact PR/head SHA for non-canonical work;
  • CANONICAL / PROPOSED / EXPERIMENTAL / SUPERSEDED / ARCHIVED lifecycle states;
  • default-consumer eligibility.
• docs/CAPABILITY_PROMOTION_CONTRACT.md
  • promotion transition and cross-repository consumer rules.
• scripts/validate_capability_manifest.py
  • dependency-free fail-closed validator.
• tests/test_capability_manifest.py
  • canonicality regression tests.
• governance/fcrp-self-005.json
  • machine-readable causal decomposition.
• .github/workflows/proofpath-capability-manifest.yml
  • exact-head validation on changes to the contract.

Current audited state

At audit time:

main: 685d50e256a5125a21f4c4584b326411caaa64ad

CANONICAL:
  proofpath.scig.v0.1

PROPOSED:
  PoCI / Deploy Guard / Evidence / Control Cloud / governance stack
  plus MASTER_CONTEXT documentation

EXPERIMENTAL:
  Gonka Compute Witness pilot (#218)

The manifest records the full audited branch dependency graph rather than treating a successful branch CI run as promotion.

Consumer invariant

A downstream repository may depend by default only on:

status = CANONICAL
consumer_default_allowed = true
canonical_commit = exact commit

A PROPOSED or EXPERIMENTAL capability requires explicit opt-in plus exact PR/head SHA and must not be described as an ambient main capability.

The validator fails closed if:

• non-canonical work becomes a default dependency;
• a canonical capability lacks an exact canonical commit;
• a canonical capability depends on non-canonical work;
• proposed/experimental work lacks an exact head SHA or source PR;
• dependencies are missing or cyclic;
• the policy flags are weakened.

FCRP result

Idea:
  ecosystem-consumable ProofPath capabilities have unambiguous canonical identity

Symptom:
  branch-only architecture can be discussed/consumed as if it were normal ProofPath surface

First Meaningful Divergence:
  #193 PoCI contract became the root of a growing stack while remaining outside main

Refactor Point:
  repository capability promotion / canonicality contract

Decision:
  PASS after making lifecycle state and consumer eligibility explicit

Boundary

This PR does not promote, merge, close, retarget, or rewrite any existing capability PR. It only establishes the contract needed to evaluate those transitions safely and then repeat the same repository-integrity audit across the NEO REZONANS stack.

Summary by CodeRabbit

• New Features

  • Added a capability manifest defining lifecycle statuses, promotion policies, dependencies, and canonical references.
  • Documented the capability promotion lifecycle and canonical identity rules.
  • Added a case record documenting capability identity drift and its resolution.

• Validation & Reliability

  • Added automated validation for manifest structure, references, dependencies, and canonicality rules.
  • Added regression tests covering invalid dependencies, commit references, and dependency cycles.
  • Added continuous checks for pull requests, updates to the main branch, and manual runs.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 266d8c93-759d-4e53-9cbd-0cf7c5844421

📥 Commits

Reviewing files that changed from the base of the PR and between 685d50e and 1e6a95d.

📒 Files selected for processing (6)

• .github/workflows/proofpath-capability-manifest.yml
• docs/CAPABILITY_PROMOTION_CONTRACT.md
• governance/capability-manifest.v0.1.json
• governance/fcrp-self-005.json
• scripts/validate_capability_manifest.py
• tests/test_capability_manifest.py

---

📝 Walkthrough

Walkthrough

The PR adds a capability promotion contract, a 26-capability manifest, and an FCRP-SELF-005 governance record. It adds fail-closed validation, regression tests, and a GitHub Actions workflow that enforces manifest and canonicality checks.

Changes

Capability manifest lifecycle

Layer / File(s)	Summary
Capability lifecycle and governance records docs/CAPABILITY_PROMOTION_CONTRACT.md, governance/capability-manifest.v0.1.json, governance/fcrp-self-005.json	Defines capability statuses, promotion rules, dependency constraints, commit pinning, consumer permissions, and canonicality divergence records.
Fail-closed manifest validator scripts/validate_capability_manifest.py, tests/test_capability_manifest.py	Validates manifest structure, capability status and dependency rules, commit identities, duplicate keys, and dependency cycles. Tests cover valid data and rejected invalid cases.
CI capability enforcement .github/workflows/proofpath-capability-manifest.yml	Runs validation and regression tests on configured events, then checks FCRP-SELF-005 bindings and required capability references.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GitHubActions as GitHub Actions
  participant Validator as validate_capability_manifest.py
  participant Manifest as capability-manifest.v0.1.json
  participant RegressionTests as test_capability_manifest.py
  GitHubActions->>Validator: Validate manifest
  Validator->>Manifest: Load and check manifest
  Validator-->>GitHubActions: Return validation result
  GitHubActions->>RegressionTests: Run regression tests
  RegressionTests->>Validator: Test valid and invalid manifests
  Validator-->>RegressionTests: Return validation outcomes
  GitHubActions->>Manifest: Assert FCRP-SELF-005 bindings and capability references

Loading

Possibly related PRs

• safal207/ProofPath#212: Shares the capability canonicality and fail-closed validation concepts.
• safal207/ProofPath#219: Relates to SCIG canonical capability designation and manifest integration.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch governance/fcrp-self-005-canonicality

---

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.}