docs(contracts): align the YAML registry and the prose docs into one registry - #146
Merged
Conversation
…registry The 24 machine-readable contracts in contracts/ and the 20 prose docs in docs/contracts/ had drifted: YAML pointed at test files rather than test classes, no YAML named the doc that described it, seven contracts had no prose at all, and several docs referenced modules (l9.core, l9.memory, chassis.metrics) that do not exist in this repo. Splits ownership by concern -- YAML owns identity and wiring, Markdown owns prose -- and adds tests/contracts/test_contract_registry.py as a blocking drift gate so the two cannot diverge again silently. - contracts/*.yaml: verification.test is now a pytest node ID; every contract names its docs; scanner_rules populated and corrected - 7 new docs (C-10, 11, 15, 18, 20, 21, 22) plus 10 partial docs expanded - TestContract21-24 added; all 24 contracts now have a test class - verify_contracts.py reads docs: from YAML on top of its literal floor list, and now also checks AGENTS.md for wiring - STUB-001/002/003 registered for the zero-stub protocol, scoped to engine/ (chassis ABCs legitimately raise NotImplementedError) - resolved two contradictions against the code: gate count is 10, not 14; both logging.getLogger and structlog.get_logger satisfy CONTRACT-04, since the enforced invariant is that the engine never configures logging - contract_report.py now splits node IDs on '::' when checking test existence 1749 passed, 0 failures. ruff and mypy clean. Co-authored-by: Cursor <cursoragent@cursor.com>
|
❌ Too Many Reviewable Files Changed ❌ PR Too Large 📋 Best Practices for Large Changes
🚫 This PR is blocked until reviewable size limits are met. |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| steps: | ||
| # fetch-depth is irrelevant here, but the checkout must be a real git repo: | ||
| # discovery enumerates via `git ls-files -z`, not a filesystem walk. | ||
| - uses: actions/checkout@v6 |
| steps: | ||
| # fetch-depth is irrelevant here, but the checkout must be a real git repo: | ||
| # discovery enumerates via `git ls-files -z`, not a filesystem walk. | ||
| - uses: actions/checkout@v6 |
Collaborator
Author
|
Does this belong in https://github.com/Quantum-L9/Cursor-Governance? |
This was referenced Jul 27, 2026
Adds the CONTRACT-24 resilience section, the contract-suite run commands, and the chassis_app.py path corrections that the registry alignment left unapplied in the prose docs.
Remediation-Cycle: #146/cycle-1 Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Pull request overview
This PR unifies the contract registry by making contracts/*.yaml the source of truth for contract identity/wiring (docs pointers, scanner rule IDs, pytest node IDs) and expanding docs/contracts/*.md to hold the prose, with new/updated tests and tools to prevent YAML↔docs↔scanner↔tests drift.
Changes:
- Converted
contracts/*.yamlto includedocs:pointers and pytest node IDs inverification.test, and updated related tooling to consume them. - Added/expanded multiple contract docs (7 new) and aligned agent guidance/docs to the 24-contract registry.
- Added a drift-gate test (
tests/contracts/test_contract_registry.py) and extended the contract test suite to cover contracts 21–24.
Reviewed changes
Copilot reviewed 69 out of 69 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/verify_contracts.py | Adds YAML-driven doc discovery (docs: pointers) on top of a literal required-doc floor. |
| tools/contract_scanner.py | Updates scanner rule guidance and adds STUB-001..003 rules scoped to engine/. |
| tools/contract_report.py | Treats verification.test as a pytest node id by splitting on ::. |
| TODO.md | Updates preflight checklist text to reflect 27 contract docs wired. |
| tests/contracts/test_contracts.py | Adds L9_META header and new contract test classes for contracts 21–24. |
| tests/contracts/test_contract_registry.py | New drift gate asserting YAML/docs/scanner/tests stay consistent. |
| TESTING.md | Updates documentation on how contract verification is enforced (3 complementary gates). |
| docs/SEL4_UPGRADES.md | Updates contract suite counts/descriptions from 20 → 24. |
| docs/L9_Contract_Enforcement_System.md | Updates contract enforcement narrative/counts and references the new drift gate. |
| docs/FEATURE_GATES.md | Adds additional documented feature gates and sections for outcome persistence/auth flags. |
| docs/contracts/TEST_PATTERNS.md | Adds a “Required Coverage (CONTRACT-17)” section and coverage table. |
| docs/contracts/SHARED_MODELS.md | Updates import guidance from l9.core → engine.packet.* and adds tenant isolation section. |
| docs/contracts/SCORING_WEIGHT_CEILING.md | New contract doc for CONTRACT-22 (default weight ceiling + startup assertion). |
| docs/contracts/README.md | Updates contract docs directory guidance and referenced tools. |
| docs/contracts/PROHIBITED_FACTORS.md | New contract doc for CONTRACT-10 (compile-time prohibited factors). |
| docs/contracts/PII_HANDLING.md | New contract doc for CONTRACT-11 (PII modes + logging rules). |
| docs/contracts/PACKET_TYPE_REGISTRY.md | Updates PacketType enum source path to engine/packet/packet_envelope.py. |
| docs/contracts/PACKET_ENVELOPE_FIELDS.md | Adds “Only Data Container (CONTRACT-06)” prose and boundary function guidance. |
| docs/contracts/OBSERVABILITY.md | Clarifies logging invariant (no engine config) and corrects gate count example. |
| docs/contracts/METHOD_SIGNATURES.md | Adds prose for gate-then-score (CONTRACT-13) and declarative GDS jobs (CONTRACT-19). |
| docs/contracts/MEMORY_SUBSTRATE_ACCESS.md | Updates persistence guidance to engine.packet.packet_store / delegation protocol. |
| docs/contracts/L9_META_HEADERS.md | Adds/updates L9_META header contract prose and examples. |
| docs/contracts/KGE_EMBEDDINGS.md | New contract doc for CONTRACT-20 (KGE subsystem isolation + scoring integration). |
| docs/contracts/HANDLER_PAYLOADS.md | Adds admin subaction registration rules (CONTRACT-23). |
| docs/contracts/FIELD_NAMES.md | Adds “Null semantics are per-gate (CONTRACT-14)” prose. |
| docs/contracts/FEATURE_FLAG_DISCIPLINE.md | New contract doc for CONTRACT-21 (feature flag discipline). |
| docs/contracts/ENV_VARS.md | Adds scope note for CONTRACT-05 and links to feature flag discipline. |
| docs/contracts/DEPENDENCY_INJECTION.md | Updates chassis file reference and adds resilience patterns section (CONTRACT-24). |
| docs/contracts/DELEGATION_PROTOCOL.md | Updates delegation import path to engine.packet.chassis_contract. |
| docs/contracts/config/env-contract.yaml | Updates chassis settings source path references. |
| docs/contracts/BIDIRECTIONAL_MATCHING.md | New contract doc for CONTRACT-15 (invertible + match direction scoping). |
| docs/contracts/BANNED_PATTERNS.md | Adds infrastructure/file-structure/zero-stub protocol prose sections. |
| docs/contracts/api/openapi.yaml | Updates chassis source references and expands description with 2-chassis details. |
| docs/AUDIT_HARNESS.md | Updates harness docs to reflect wiring verification across additional agent files. |
| contracts/README.md | Updates YAML registry documentation (pytest node IDs + docs: pointers) and usage. |
| contracts/contract_24.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_23.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_22.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_21.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_20.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_19.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_18.yaml | Broadens scope paths, adds docs pointer, and changes verification wiring. |
| contracts/contract_17.yaml | Adds engine scope + stub scanner rules + docs pointers + pytest node ID. |
| contracts/contract_16.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_15.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_14.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_13.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_12.yaml | Adds docs: + NAME-001 scanner rule + pytest node ID. |
| contracts/contract_11.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_10.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_09.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_08.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_07.yaml | Adds docs:, removes MEM scanner ids, updates verification.test to pytest node ID. |
| contracts/contract_06.yaml | Adds docs:, adds PKT/MEM scanner ids, updates verification.test to pytest node ID. |
| contracts/contract_05.yaml | Adds docs:, adds ENV-001 scanner id, updates verification.test to pytest node ID. |
| contracts/contract_04.yaml | Updates allowed logger getter invariant, adds ERR scanner ids, updates verification.test. |
| contracts/contract_03.yaml | Adds docs: and updates verification.test to pytest node ID. |
| contracts/contract_02.yaml | Adds docs:, adds DI-001 scanner id, updates verification.test. |
| contracts/contract_01.yaml | Adds docs:, adds SHARED-003 scanner id, updates verification.test. |
| CLAUDE.md | Adds a contract docs lookup table by subsystem. |
| ARCHITECTURE.md | Updates verify_contracts description to doc-wiring purpose. |
| agents/cursor/prompts/action_prompts/CEG PR Review.md | Updates gate type count references (14 → 10). |
| agents/cursor/governance-reference.md | Updates contract doc count and gate type count references. |
| agents/cursor/cursor_workflow_kernel.yaml | Updates contract registry description and L9_META schema/gate count references. |
| agents/cursor/cursor_system_prompt.md | Updates gate type section and contract doc count references. |
| .pre-commit-config.yaml | Updates contract enforcement comment and adds an L9_META header check hook. |
| .github/workflows/contracts.yml | Updates header meta and adds a meta-headers job; updates job dependencies. |
| .cursorrules | Updates schema meta, contract counts, contract docs list, and stub-rule scope notes. |
| .claude/rules/contracts.md | Updates contract 4/18 prose to reflect new invariants and schema guidance. |
Suppressed comments (1)
docs/contracts/SHARED_MODELS.md:70
- The “WRONG” example still says
BANNED — already in l9-core, but this doc was updated to state the canonical shared models live underengine.packet.*. That reference should be updated to avoid pointing readers at a non-existent/external module.
Comment on lines
91
to
96
| - id: l9-contract-files-exist | ||
| name: L9 Contract Files Existence Check | ||
| entry: python tools/verify_contracts.py | ||
| language: python | ||
| pass_filenames: false | ||
| always_run: true |
Comment on lines
+103
to
+111
| - id: l9-meta-check | ||
| name: L9_META Header Check | ||
| entry: python tools/l9_meta_injector.py check | ||
| language: python | ||
| # pre-commit builds an isolated venv, so l9-meta.yaml parsing needs | ||
| # pyyaml declared here — it is not inherited from the repo environment. | ||
| additional_dependencies: [pyyaml] | ||
| pass_filenames: false | ||
| always_run: true |
Comment on lines
27
to
+31
| import sys | ||
| from pathlib import Path | ||
|
|
||
| import yaml | ||
|
|
Comment on lines
+49
to
+61
| meta-headers: | ||
| name: Verify L9_META Headers | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| # fetch-depth is irrelevant here, but the checkout must be a real git repo: | ||
| # discovery enumerates via `git ls-files -z`, not a filesystem walk. | ||
| - uses: actions/checkout@v6 | ||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: "3.12" | ||
| - run: pip install pyyaml | ||
| - run: python tools/l9_meta_injector.py check | ||
|
|
Comment on lines
68
to
+72
| `make agent-check` is the completion gate: it runs `tools/verify_contracts.py` | ||
| (the 20 contract markdown files present and referenced from the agent rule | ||
| files), `tools/contract_scanner.py` (banned pattern scan), lint, types, and the | ||
| full test suite. A green `agent-check` means green CI. | ||
| (the 27 contract markdown files present and referenced from the agent rule | ||
| files), `tools/contract_scanner.py` (banned pattern scan), | ||
| `tools/contract_report.py` (contract-to-verification coverage), lint, types, and | ||
| the full test suite. A green `agent-check` means green CI. |
Comment on lines
+139
to
+140
| orphaned = [d for d in _required_contract_docs() if d not in claimed] | ||
| assert not orphaned, f"Required contract docs not referenced by any YAML docs: field: {orphaned}" |
Comment on lines
246
to
253
| _rule( | ||
| "SHARED-003", | ||
| "SHARED_MODELS.md", | ||
| "HIGH", | ||
| r"class\s+ExecuteRequest\s*\(", | ||
| "Redefining ExecuteRequest - import from l9.core", | ||
| "from l9.core.contract import ExecuteRequest", | ||
| "Redefining ExecuteRequest - the chassis owns this model", | ||
| "from chassis.chassis_app import ExecuteRequest", | ||
| include_dirs=["engine/"], |
Comment on lines
+14
to
+16
| # Every tracked file with a known format, not just engine/ and chassis/. | ||
| # The eligible set is computed by tools/l9_meta/discover.py from the git index | ||
| # minus config `exclude`; enumerating it here would go stale immediately. |
Comment on lines
+36
to
+37
| test: tests/contracts/test_contracts.py::TestContract18L9Meta | ||
| command: python tools/l9_meta_injector.py check |
Comment on lines
+18
to
+32
| Every tracked source file carries an L9_META header (schema version 1). Headers are | ||
| **injected by `tools/l9_meta_injector.py`**, not typed by hand. Run the injector, commit, | ||
| done. | ||
|
|
||
| ## Fields | ||
|
|
||
| | Field | Meaning | | ||
| |---|---| | ||
| | `l9_schema` | Header schema version — always `1` | | ||
| | `origin` | `l9-template` (shared) or `engine-specific` (this repo) | | ||
| | `engine` | `graph` | | ||
| | `layer` | List, e.g. `[config]`, `[docs, contracts]`, `[tools]` | | ||
| | `tags` | List of free-form tags | | ||
| | `owner` | `platform` or `engine-team` | | ||
| | `status` | `active`, `deprecated` | |
- l9-lint-test: mypy engine/ (not SOURCE_DIR=.) - supply-chain: allow-licenses only (action rejects both allow+deny) - l9-analysis: remove semgrep fail-open || true - contracts: install requirements-ci before verify/scan Co-authored-by: Cursor <cursoragent@cursor.com>
… arg) Remediation-Cycle: #146/cycle-2 Co-authored-by: Cursor <cursoragent@cursor.com>
| # fetch-depth is irrelevant here, but the checkout must be a real git repo: | ||
| # discovery enumerates via `git ls-files -z`, not a filesystem walk. | ||
| - uses: actions/checkout@v6 | ||
| - uses: actions/setup-python@v5 |
| with: | ||
| python-version: "3.12" | ||
| - run: pip install pyyaml | ||
| # Default mode is dry-run verification; there is no `check` subcommand. |
Co-authored-by: Cursor <cursoragent@cursor.com>
…cs/contract-alignment
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 72 out of 72 changed files in this pull request and generated no new comments.
Suppressed comments (9)
.pre-commit-config.yaml:97
- The
l9-contract-files-existpre-commit hook runstools/verify_contracts.py, which now importsyaml(PyYAML). Withlanguage: python, pre-commit creates an isolated venv, so this hook will fail unless PyYAML is declared as an additional dependency.
- id: l9-contract-files-exist
name: L9 Contract Files Existence Check
entry: python tools/verify_contracts.py
language: python
pass_filenames: false
always_run: true
.pre-commit-config.yaml:107
tools/l9_meta_injector.pydoes not accept acheckpositional argument (it only supports flags like--apply). As written, this hook will fail with an argparse error. Also, running the injector in dry-run mode currently exits 0 even when it printsPENDING, so this hook won't reliably enforce header drift unless it explicitly fails on pending/missing/errors.
- id: l9-meta-check
name: L9_META Header Check
entry: python tools/l9_meta_injector.py check
language: python
# pre-commit builds an isolated venv, so l9-meta.yaml parsing needs
contracts/contract_18.yaml:37
contracts/contract_18.yamldeclarescommand: python tools/l9_meta_injector.py check, buttools/l9_meta_injector.pyin this repo has nochecksubcommand (only--apply), and it currently usesl9_schema: 1plus anownerfield. The contract’s declared verification command and its stated schema expectations (v2 / owner dropped) are inconsistent with the actual enforcement tool, so the registry will be wiring a non-existent command.
docs/contracts/L9_META_HEADERS.md:32- This doc states L9_META is always schema v1 and includes an
ownerfield, but the updated YAML registry (contracts/contract_18.yaml) now asserts schema v2 withownerdropped, and multiple files in this PR usel9_schema: 2withoutowner. The prose doc and the machine-readable contract need to agree on the schema version and field set, otherwise the new drift gates will oscillate between two incompatible definitions.
docs/contracts/MEMORY_SUBSTRATE_ACCESS.md:72 - The retrieval example uses
PipelineRouter.retrieve(...), butPipelineRouterdoes not exist anywhere in this repository. This makes the contract doc misleading for contributors trying to follow the sanctioned read path.
tools/contract_scanner.py:253 - The SHARED-003 remediation string suggests importing
ExecuteRequestfromchassis.chassis_appinsideengine/code. That conflicts with CONTRACT-02’s boundary (handlers.py is the only engine module expected to import chassis). Since this message is what developers will copy-paste to fix violations, it should recommend removing the redefinition without introducing a new contract violation.
docs/contracts/api/openapi.yaml:3 - The
Source:header listschassis/chassis_app.pytwice, which looks like an accidental duplication and makes the provenance line harder to trust.
.github/workflows/contracts.yml:63 - The
meta-headersCI job runstools/l9_meta_injector.pyin dry-run mode, but that script currently exits 0 even if it printsPENDINGfor files that need updates. This means the new job won’t actually block merges on header drift unless it explicitly fails when the output contains pending/missing/error markers (or the tool grows a real--checkmode).
python-version: "3.12"
- run: pip install pyyaml
# Default mode is dry-run verification; there is no `check` subcommand.
- run: python tools/l9_meta_injector.py
docs/contracts/MEMORY_SUBSTRATE_ACCESS.md:41
- This section says delegation to the memory substrate should be done via the delegation protocol (not by importing), but the example calls
ingest_packet(PacketEnvelopeIn(...)). Neitheringest_packetnorPacketEnvelopeInexist in this repo, so this example is not runnable and contradicts the stated rule.
Co-authored-by: Cursor <cursoragent@cursor.com>
…cs/contract-alignment
|
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 73 out of 75 changed files in this pull request and generated no new comments.
Suppressed comments (8)
.pre-commit-config.yaml:110
- The pre-commit hook calls
python tools/l9_meta_injector.py check, buttools/l9_meta_injector.pyonly defines--apply(nochecksubcommand/arg), so this hook will error and block commits for the wrong reason. Also, the comment referencesl9-meta.yaml, but the current injector uses its internalFILE_REGISTRY(no l9-meta YAML file present).
- id: l9-meta-check
name: L9_META Header Check
entry: python tools/l9_meta_injector.py check
language: python
# pre-commit builds an isolated venv, so l9-meta.yaml parsing needs
# pyyaml declared here — it is not inherited from the repo environment.
additional_dependencies: [pyyaml]
pass_filenames: false
contracts/contract_18.yaml:37
- This contract references tooling and CLI modes that don't exist in the repo (
tools/l9_meta/discover.py,l9-meta.yaml, andpython tools/l9_meta_injector.py check). Currently,tools/l9_meta_injector.pyonly supports--apply, and its metadata source is an in-fileFILE_REGISTRY.
As-is, the contract's wiring and verification command are inaccurate.
docs/contracts/L9_META_HEADERS.md:9
- The L9_META header in this doc still declares
l9_schema: 1and includesowner, but the PR is standardizing many tracked files onl9_schema: 2and droppingownerfrom headers. This doc should match the current contract/system it describes.
docs/contracts/L9_META_HEADERS.md:32 - The body text describes L9_META as “schema version 1” and lists
owneras a required field. That conflicts with this PR’s move tol9_schema: 2headers (and multiple files droppingowner). This doc should describe the schema/version that the repo actually enforces.
docs/contracts/SHARED_MODELS.md:70 - This example still says “BANNED — already in l9-core”, but the surrounding section was updated to make
engine.packetthe canonical import surface in this repo. The comment should match the updated import guidance to avoid implying a dependency that isn’t present here.
docs/contracts/MEMORY_SUBSTRATE_ACCESS.md:45 - This section says delegation must be used “not by importing it”, but the code example shows a direct
await ingest_packet(...)call, which implies importing/calling the substrate node’s function. That’s internally contradictory and could mislead implementers into adding a forbidden import path.
docs/contracts/api/openapi.yaml:6 - The
Source:header listschassis/chassis_app.pytwice; this looks like an accidental duplication and makes the provenance line harder to trust.
.github/workflows/contracts.yml:64 meta-headersis intended as a blocking gate, buttools/l9_meta_injector.pyexits 0 even when it printsPENDING/MISSING/ERRORlines (and it has nocheckmode). As written, this CI job can pass while reporting drift.
- run: pip install pyyaml
# Default mode is dry-run verification; there is no `check` subcommand.
- run: python tools/l9_meta_injector.py
cryptoxdog
added a commit
that referenced
this pull request
Aug 1, 2026
…the scaffold (#151) * fix(docker): install git for VCS deps, fix poetry prod install, align deps - Add git to apt-get install in Dockerfile, chassis/Dockerfile.chassis, and Dockerfile.prod build stages so pip/poetry can resolve git+https dependencies (previously failed with "Cannot find command 'git'"). - Fix Dockerfile.prod poetry install: --no-dev is deprecated, replaced with --only main --no-root (the latter avoids failing on a missing README.md before it's copied into the build context). Removed the silent pip fallback in favor of failing fast. - Align requirements.txt with pyproject.toml (redis, numpy versions) and add openai/asyncpg/python-multipart to pyproject.toml to remove dependency drift between the two manifests. Regenerated poetry.lock. chore(license): replace MIT LICENSE with Quantum AI Partners proprietary license, matching the README's existing "proprietary" claim and the org-wide license standardization applied across other Quantum-L9 repos. Adds license = "LicenseRef-Proprietary" to pyproject.toml. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: add GitHub org-ruleset diagnostic command log Records the diagnostic commands run while investigating org-level GitHub ruleset enforcement for Quantum-L9 (repo/org ruleset state, plan-tier gating, the CI Gate ruleset's invalid empty ref_name.include, CodeQL coverage, and the post-Enterprise-upgrade re-check) for future reference. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(contracts): align the YAML registry and the prose docs into one registry The 24 machine-readable contracts in contracts/ and the 20 prose docs in docs/contracts/ had drifted: YAML pointed at test files rather than test classes, no YAML named the doc that described it, seven contracts had no prose at all, and several docs referenced modules (l9.core, l9.memory, chassis.metrics) that do not exist in this repo. Splits ownership by concern -- YAML owns identity and wiring, Markdown owns prose -- and adds tests/contracts/test_contract_registry.py as a blocking drift gate so the two cannot diverge again silently. - contracts/*.yaml: verification.test is now a pytest node ID; every contract names its docs; scanner_rules populated and corrected - 7 new docs (C-10, 11, 15, 18, 20, 21, 22) plus 10 partial docs expanded - TestContract21-24 added; all 24 contracts now have a test class - verify_contracts.py reads docs: from YAML on top of its literal floor list, and now also checks AGENTS.md for wiring - STUB-001/002/003 registered for the zero-stub protocol, scoped to engine/ (chassis ABCs legitimately raise NotImplementedError) - resolved two contradictions against the code: gate count is 10, not 14; both logging.getLogger and structlog.get_logger satisfy CONTRACT-04, since the enforced invariant is that the engine never configures logging - contract_report.py now splits node IDs on '::' when checking test existence 1749 passed, 0 failures. ruff and mypy clean. Co-authored-by: Cursor <cursoragent@cursor.com> * chore(template): drop .suite6-config.json from the scaffold SETUP_QUICK_START.md already declares this config stale and CANONICAL_LAW.md is headed "Post-Suite-6", but the file stayed in l9_template_manifest.yaml, so every newly scaffolded L9 repo inherited dead configuration. Phase 4 of the Suite-6 cut-over. Scoped deliberately to the config removal; the manifest's other pending edits belong to the L9_META injector work. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(docker): gate the healthcheck on readiness, not just HTTP 200 /v1/health returns 200 while the engine is still warming up, so an unready container was reported healthy. Also ignores the mypy venv. * docs(contracts): fold prose docs onto the aligned registry Adds the CONTRACT-24 resilience section, the contract-suite run commands, and the chassis_app.py path corrections that the registry alignment left unapplied in the prose docs. * fix(docker): gate the prod healthcheck on readiness, not just a 200 The prod image healthcheck only asserted that /v1/health answered, so a container whose Neo4j driver or domain loader failed to come up still reported healthy and took traffic. Matches the dev Dockerfile and Dockerfile.chassis change in this PR. Co-authored-by: Cursor <cursoragent@cursor.com> * feat: dual-chassis SDK migration, research pattern wiring, contract docs Wires the SDK-native chassis (chassis/node_app.py, handler_registration.py, entrypoint.py) into engine/handlers.py by adding ACTION_HANDLERS as the single source of truth for the 8 action handlers (CONTRACT-02). The legacy chassis (chassis/actions.py) now consumes ACTION_HANDLERS directly instead of maintaining a duplicate hardcoded list, so the two chassis implementations can't drift apart. Wires tools/research/top5_leverage_patterns_detailed.json into the spec coverage extractor (tools/spec_extract.py::extract_research_features) so the 5 leverage-pattern engine mappings show up in the coverage matrix. Fixes 4 missing-underscore typos in tools/auditors/*.py contract_file properties that pointed at non-existent docs (METHODSIGNATURES.md -> METHOD_SIGNATURES.md, etc.), caught by the new test_auditor_wiring.py. Adds 7 new contract docs, 5 auditor remediation docs, and 5 new contract tests (test_auditor_wiring, test_chassis_parity, test_research_wiring, test_node_app, test_contract_registry). Defers reconciling contracts/contract_*.yaml (24 files) against the new schema test_contract_registry.py expects -- tracked as DEFERRED-003 in DEFERRED.md and flagged in TODO.md, since it requires per-contract doc/test-class mapping decisions rather than a mechanical fix. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(ci): remediate shared pipeline signals CI-001/003/004/005 - l9-lint-test: mypy engine/ (not SOURCE_DIR=.) - supply-chain: allow-licenses only (action rejects both allow+deny) - l9-analysis: remove semgrep fail-open || true - contracts: install requirements-ci before verify/scan Co-authored-by: Cursor <cursoragent@cursor.com> * fix(ci): install contract deps; use l9_meta dry-run (no invalid check arg) Remediation-Cycle: #146/cycle-2 Co-authored-by: Cursor <cursoragent@cursor.com> * fix(ci): drop semgrep --error so governance can gate findings Co-authored-by: Cursor <cursoragent@cursor.com> * fix(tests): SDK gate-only preflight + ingress expectations; LLM key order Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 73 out of 75 changed files in this pull request and generated 2 comments.
Suppressed comments (3)
.pre-commit-config.yaml:97
tools/verify_contracts.pynow importsyaml, but this pre-commit hook's isolated venv won't have PyYAML installed, so the hook will crash at import time. Addpyyamlas anadditional_dependenciesfor this hook (similar to the l9-meta hook).
- id: l9-contract-files-exist
name: L9 Contract Files Existence Check
entry: python tools/verify_contracts.py
language: python
pass_filenames: false
always_run: true
contracts/contract_18.yaml:37
verification.commandusespython tools/l9_meta_injector.py check, buttools/l9_meta_injector.pyhas nochecksubcommand (it only supports--apply). As written, this command will fail if anyone tries to execute it verbatim.
docs/contracts/L9_META_HEADERS.md:32- This doc hard-codes
l9_schemaas always1and requires anownerfield, but other changes in this PR switch many headers tol9_schema: 2and dropowner(andcontracts/contract_18.yamlclaims schema v2). Also,tools/l9_meta_injector.pycurrently definesL9_SCHEMA_VERSION = 1and still injectsowner, so the doc/contract/tooling are out of sync and the new drift gate will be ambiguous/brittle until they agree.
Comment on lines
+103
to
+111
| - id: l9-meta-check | ||
| name: L9_META Header Check | ||
| entry: python tools/l9_meta_injector.py check | ||
| language: python | ||
| # pre-commit builds an isolated venv, so l9-meta.yaml parsing needs | ||
| # pyyaml declared here — it is not inherited from the repo environment. | ||
| additional_dependencies: [pyyaml] | ||
| pass_filenames: false | ||
| always_run: true |
Comment on lines
+51
to
+63
| meta-headers: | ||
| name: Verify L9_META Headers | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| # fetch-depth is irrelevant here, but the checkout must be a real git repo: | ||
| # discovery enumerates via `git ls-files -z`, not a filesystem walk. | ||
| - uses: actions/checkout@v6 | ||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: "3.12" | ||
| - run: pip install pyyaml | ||
| # Default mode is dry-run verification; there is no `check` subcommand. | ||
| - run: python tools/l9_meta_injector.py |
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
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.
Summary
contracts/(24 machine-readable YAMLs) anddocs/contracts/(20 prose docs) were two halves of one registry that had drifted apart. This makes them a single registry split by concern — YAML owns identity and wiring, Markdown owns prose — and adds a blocking drift gate so they cannot diverge silently again.What was broken:
verification.testpointed at test files, so a contract could lose its test class and still look verified.l9.core,l9.memory,chassis.metrics.Changes
contracts/*.yamlverification.testis now a pytest node ID; every contract carries adocs:pointer;scanner_rulespopulated and correcteddocs/contracts/tests/contracts/test_contract_registry.pytests/contracts/test_contracts.pyTestContract21–24added; all 24 contracts now have a test classtools/verify_contracts.pydocs:from YAML on top of its literal floor list; also checksAGENTS.mdfor wiringtools/contract_scanner.pySTUB-001/002/003registered for the zero-stub protocol, scoped toengine/tools/contract_report.py::when checking test existenceTwo contradictions resolved against the code
Both were cases where the docs asserted something the code does not do. Resolved in favor of the code:
GateTypeinengine/config/schema.pyhas 10 members. Agent files claiming 14 were updated.logging.getLoggerandstructlog.get_loggersatisfy CONTRACT-04. The enforced invariant is that the engine never configures logging, not which getter it calls.engine/uses stdlib in ~80 modules and structlog in a handful;OBSERVABILITY.mdhad prescribed structlog exclusively. There is also nostructlog.configure()anywhere inchassis/— noted in the doc as a chassis gap, not something to fix fromengine/.The
STUB-001scope was also narrowed toengine/: abstract base classes inchassis/raiseNotImplementedErroras their defining contract, which is intended use, not a stub.Test plan
pytest tests/— 1749 passed, 35 skipped, 56 xfailed, 0 failuresruff check .andruff format --check .— cleantools/verify_contracts.py— 27 docs present and wiredtools/contract_scanner.py— no violationstools/contract_report.py— 24/24 contracts have a resolvable test classDeliberately out of scope
Makefileanddocs/contracts/README.mdhad unrelated uncommitted work in the same hunks, so they were left out to keep this reviewable. Two follow-ups remain:tools/contract_report.pyintomake agent-check.docs/contracts/README.md(still says 20; there are now 27).