docs(contracts): align the YAML registry and the prose docs into one registry - #146
Open
cryptoxdog wants to merge 2 commits into
Open
docs(contracts): align the YAML registry and the prose docs into one registry#146cryptoxdog wants to merge 2 commits into
cryptoxdog wants to merge 2 commits into
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 |
| # 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 |
| 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 |
| # 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 |
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.
|
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.
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).