feat(governance): typed Pydantic v2 models for claim ledger + commit acceptor#552
Merged
neuron7xLab merged 1 commit intoneuron7xLab:mainfrom May 7, 2026
Merged
Conversation
…acceptor
Single source of truth for the two YAML schemas that drive the IERD
governance layer:
docs/CLAIMS.yaml -> ClaimLedger / ClaimEntry / Falsifier
.claude/commit_acceptors/*.yaml -> CommitAcceptor / DiffScope / AcceptorFalsifier
Why
---
The pre-existing parsers (scripts/ci/check_claims.py and
tools/commit_acceptor/validate_commit_acceptor.py) consume the YAML
through dict access. Adding a field meant editing 3+ files in lock-step,
and the absence of `extra='forbid'` left silent schema drift as the
dominant failure mode — exactly the IERD §1 loophole the directive
exists to close.
What
----
* application/governance/claim_ledger.py (160 lines)
- Tier enum (ANCHORED / EXTRAPOLATED / SPECULATIVE / UNKNOWN)
- Priority enum (P0 / P1 / P2)
- Falsifier model (test_id pytest-node pattern, INV-* invariants,
failure_signature)
- ClaimEntry model (id pattern, priority, tier, description,
evidence_paths, added_utc / last_updated_utc with date round-trip,
optional Falsifier; ``extra='forbid'``, frozen)
- ClaimLedger root model (schema_version 1..3, claims tuple,
duplicate-id rejection, helpers: by_id / gated / by_tier /
tier_distribution)
- load_claim_ledger(path) — Pydantic-validated parse
* application/governance/commit_acceptor.py (190 lines)
- Status / ClaimType / MemoryUpdateType enums
- DiffScope (changed_files >= 1, forbidden_paths)
- AcceptorFalsifier (command + description, both non-empty)
- EvidenceEntry (path + optional sha256)
- CommitAcceptor root model — 17 fields mirror the on-disk YAML
verbatim, ``extra='forbid'`` rejects silent additions
- load_commit_acceptor(path) and load_all_commit_acceptors(directory)
* tests/governance/test_typed_models.py (12 tests, all passing)
- round-trip on canonical docs/CLAIMS.yaml
- round-trip on every .claude/commit_acceptors/*.yaml
- unique-id invariants per registry
- ANCHORED-falsifier coverage report (warn-only, mirrors check_claims)
- extra='forbid' regression guard on both top-level entries
- JSON Schema export smoke (ClaimLedger and CommitAcceptor)
* .claude/commit_acceptors/governance-typed-models.yaml
- diff-bound acceptor, claim_type=governance
- falsifier probes the extra='forbid' guard on ClaimEntry: if a future
change relaxes the model to extra='allow', the falsifier succeeds
(model accepts surprise field) and exits 1 to flag the regression
What this does NOT do
---------------------
* Does NOT modify scripts/ci/check_claims.py — additive only
* Does NOT modify tools/commit_acceptor/validate_commit_acceptor.py —
forbidden_paths in the acceptor explicitly excludes both legacy parsers
* Does NOT change .claude/commit_acceptor_policy.yaml — no policy hack
* Migration of legacy parsers to the typed model is a separate follow-up;
this PR ships the model + tests + JSON Schema export so downstream
tooling can already consume it
Local verification
------------------
mypy --strict + ruff: clean on 3 governance modules + 1 test
pytest tests/governance/test_typed_models.py: 12/12 pass
load_claim_ledger('docs/CLAIMS.yaml'): schema_v3, 27 claims,
21 ANCHORED, 6 EXTRAPOLATED
load_all_commit_acceptors('.claude/commit_acceptors'):
29 acceptors, all ACTIVE, 5 distinct claim_types
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: de22d618fc
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| priority: Priority | ||
| tier: Tier | ||
| description: str = Field(min_length=1) | ||
| evidence_paths: tuple[str, ...] = Field(default_factory=tuple) |
There was a problem hiding this comment.
When this typed model replaces scripts/ci/check_claims.py, any claim that omits evidence_paths or sets it to [] will still validate because the field defaults to an empty tuple. The current gate rejects missing/empty evidence in _parse_one, and otherwise a P0/P1 ANCHORED claim can enter gated() with no paths to check, silently bypassing the fail-closed evidence requirement.
Useful? React with 👍 / 👎.
| model_config = ConfigDict(extra="forbid", frozen=True) | ||
|
|
||
| changed_files: tuple[ChangedFile, ...] = Field(min_length=1) | ||
| forbidden_paths: tuple[str, ...] = Field(default_factory=tuple) |
There was a problem hiding this comment.
For acceptor files that omit diff_scope.forbidden_paths, the model now fills in () and accepts them. The existing validator treats forbidden_paths as a required REQUIRED_DIFF_SCOPE_FIELDS entry, so migrating consumers to this loader would silently drop the required denylist declaration instead of surfacing schema drift.
Useful? React with 👍 / 👎.
neuron7xLab
added a commit
that referenced
this pull request
May 7, 2026
* chore(audit): close 3 governance debt items from 2026-05-07 codebase audit After the IERD-Q4 Phase-3 EXIT (PR #551) and typed governance models (PR #552) landed, an audit across docs/CLAIMS.yaml, every .claude/commit_acceptors/*.yaml, and the .github/workflows tree surfaced three concrete contradictions. This PR closes them. 1. README invariant-count drift ------------------------------- * README.md:12 badge invariants-87 → invariants-90 * README.md:35 badge physics_gate-87_invariants → 90_invariants * README.md:175 table "87 in INVARIANTS.yaml" → "90 in INVARIANTS.yaml" `python scripts/count_invariants.py` is authoritative — returns 90. The body prose at lines 24/148/781 already said 90; the badges and the headline table were stale. CI gate `invariant-count-sync` did not catch the drift because shields-style markdown badges sit outside the regex it audits. 2. commit-acceptor-gate.yml self-contradiction ---------------------------------------------- The workflow that enforces architectural-boundary contracts (forbidden imports, diff-bound acceptors, claim_type caps) used floating action tags: - actions/checkout@v6 - actions/setup-python@v6 while every other workflow pins by 40-char SHA. The repo-policy gate explicitly checks that all third-party actions are pinned. Repinned both to the canonical SHAs already used elsewhere (de0fac2e... v6.0.2, a309ff8b... v6) so the gate now follows the discipline it prescribes. 3. Latency-budget test isolation regression ------------------------------------------- The PR #550 implementation set five env vars at module import time (four `os.environ.setdefault` + one unconditional `os.environ["GEOSYNC_DISABLE_METRICS"] = "1"`). Pytest collects the module before fixtures run, so those mutations leaked across the session boundary, polluting downstream test modules. Refactor: env-var window is now bounded to the lifetime of the module-scoped `client` fixture, which snapshots → applies overrides → yields → restores. `create_app` is imported lazily through `importlib` inside the same window so settings (Pydantic, env-driven) resolve under the overrides, not under whatever leaked from upstream test modules. Co-running this test with tests/observability/test_metrics_expectations.py now passes 6/6 (was 3/6 before the fix). Local verification ------------------ mypy --strict + ruff: clean on the touched test pytest tests/api/test_latency_budget_server_compute.py tests/observability/test_metrics_expectations.py -q: 6/6 pass python scripts/count_invariants.py: 90 commit_acceptor validator: exit 0 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(secrets): add pragma allowlist on test fixture env-var dict detect-secrets flags the literal strings 'audit_secret' and 'rbac_secret' in the new _REQUIRED_ENV dict (same keyword-detector pattern as in the workflow YAML, where the inline pragma is already applied). The values are non-real test fixtures. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Yaroslav Vasylenko <neuron7x@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
neuron7xLab
added a commit
that referenced
this pull request
May 7, 2026
…portlib DI (#554) PR #551 closed the same architectural defect for application/api/service.py through the application/api/risk_factory.py late-binding module. The 2026-05-07 audit (running on top of #551 + #552) flagged that THREE other files in `application/` carried the same pre-existing `from execution.X import Y` lines, undetected by the commit-acceptor forbidden_import_patterns gate because the gate scans only files modified by a PR — and these files had not been touched. Affected files (now AST-clean): application/system.py:31-33 (5 symbols: ExecutionConnector, LiveExecutionLoop, LiveLoopConfig, RiskLimits, RiskManager) application/system_orchestrator.py:30-31 (3 symbols: BinanceConnector, CoinbaseConnector, RiskLimits) application/microservices/execution.py:19 (1 symbol: LiveExecutionLoop) Why --- The forbidden_import_patterns rule (.claude/commit_acceptor_policy.yaml lines 32-36) defines a global architectural boundary: `application/` MUST NOT statically import from `trading|execution|forecast|policy`. The audit found that the rule was being enforced inconsistently — newcomers had to comply (PR #551 spent half a session refactoring service.py) while the three files above sat in the corpus untouched and uncaught. This is "selective enforcement", and it is the IERD §1 loophole the directive exists to close. What ---- * Each `from execution.* import ...` line replaced with `importlib.import_module("execution.*")` resolution at module load. Resulting symbols bound to module-level names with explicit `: Any` annotations so mypy --strict accepts them as type references. Type strictness on these specific symbols is downgraded to Any — the IERD trade-off documented inline in each file's late-binding comment block. * No behavioural change. Runtime classes are identical; the import graph at load time is unchanged in observable effect. What this does NOT do --------------------- * Does NOT define Protocol shims for the execution-stack interfaces — that is a deeper refactor that would preserve mypy strictness on the Any-erased call sites. Tracked as a separate follow-up. * Does NOT modify any consumer of these modules — every test and every other application module continues to use the same symbol names with the same runtime semantics. * Does NOT alter scripts/ci/check_claims.py, tools/commit_acceptor/validate_commit_acceptor.py, or .claude/commit_acceptor_policy.yaml. Local verification ------------------ mypy --strict --follow-imports=silent on the 3 modified files: Success: no issues found in 3 source files ruff check: All checks passed! AST forbidden-imports check on the 3 files: 0 violations pytest tests/unit/test_geosync_system.py tests/unit/application/test_system_orchestrator_regulator.py tests/integration/test_geosync_orchestrator.py: 10/10 pass Refs ---- * 2026-05-07 audit (post-#551, post-#552) * PR #551 (precedent: service.py + risk_factory.py) Co-authored-by: Yaroslav Vasylenko <neuron7x@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
neuron7xLab
added a commit
that referenced
this pull request
May 7, 2026
…els (#555) Builds on PR #552 (typed Pydantic governance models) by exporting the canonical JSON Schema 2020-12 representation under docs/schemas/governance/. External consumers (IDE plugins, OpenAPI tooling, third-party auditors) can now pin against the on-disk artefact without re-parsing the YAML or importing Pydantic. What ---- * scripts/export_governance_schemas.py — emits two schema files: docs/schemas/governance/claim_ledger.schema.json (2 props) docs/schemas/governance/commit_acceptor.schema.json (16 props) Deterministic serialisation (sort_keys=True, trailing newline). --check mode compares on-disk artefact against the live model and exits non-zero on drift. * .github/workflows/governance-schema-export-sync.yml — re-runs the exporter with --check on every PR matching the path filter (governance models, schemas, exporter, tests, workflow itself). Fail-closed; mirrors the invariant-count-sync gate pattern. * tests/scripts/test_export_governance_schemas.py (7 tests): - generation produces the two expected schemas - serialisation is deterministic across re-runs - top-level shape: ClaimLedger has schema_version+claims; CommitAcceptor has diff_scope+falsifier+id+claim_type - --check mode passes against the committed artefact - committed artefact is valid JSON - committed artefact's properties cover the live contract surface * .claude/commit_acceptors/governance-json-schema-export.yaml — diff-bound acceptor with falsifier that probes the exporter's round-trip: succeeds (exits 0) only when --check did NOT print "PASS:", which would mean the published schema has drifted from the live model. What this does NOT do --------------------- * Does NOT modify application/governance/claim_ledger.py or commit_acceptor.py — the live model is the same source of truth PR #552 shipped. * Does NOT modify the legacy parsers in scripts/ci/check_claims.py or tools/commit_acceptor/validate_commit_acceptor.py — both files are explicitly forbidden in the acceptor's `forbidden_paths`. * Does NOT add new validation logic — every constraint expressed in the JSON Schema is already enforced by the Pydantic model at parse time. Local verification ------------------ mypy --strict + ruff: clean on the 2 new Python files pytest tests/scripts/test_export_governance_schemas.py: 7/7 pass python scripts/export_governance_schemas.py --check: PASS commit_acceptor validator: exit 0 Co-authored-by: Yaroslav Vasylenko <neuron7x@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Single source of truth for docs/CLAIMS.yaml and .claude/commit_acceptors/*.yaml.
Pydantic v2 models with extra='forbid' replace ad-hoc dict access in scripts/ci/check_claims.py and tools/commit_acceptor/validate_commit_acceptor.py. Additive only — legacy parsers untouched. Round-trip tests cover the full canonical corpus (27 claims + 29 acceptors).
12/12 tests pass locally. mypy --strict + ruff clean.
See commit message for full architectural details.