Skip to content

docs: pre-format Markdown code blocks for Ruff 0.16 (prep for #288) - #296

Merged
cryptoxdog merged 2 commits into
mainfrom
claude/pr-repairs-contract-audit-x0juhj
Sep 24, 2026
Merged

docs: pre-format Markdown code blocks for Ruff 0.16 (prep for #288)#296
cryptoxdog merged 2 commits into
mainfrom
claude/pr-repairs-contract-audit-x0juhj

Conversation

@cryptoxdog

@cryptoxdog cryptoxdog commented Sep 23, 2026

Copy link
Copy Markdown
Collaborator

Problem

docs: pre-format Markdown code blocks for Ruff 0.16 (prep for #288)

Ruff 0.16 formats fenced Python blocks in Markdown by default, and the ruff-pre-commit v0.16.8 hook adds markdown to its file types. #288 moves the toolchain to Ruff 0.16.8; landing these formatting-only changes first keeps #288 under the 50-file reviewable-size policy.

Closes #

Fix

docs: pre-format Markdown code blocks for Ruff 0.16 (prep for #288)

Risk

  • Low — additive, reversible, no data or contract change — n/a — not this change
  • Medium — touches shared code, config, or a public interface
  • High — breaking change, migration, IAM/network, or irreversible — n/a — not this change

Blast radius: measured paths in Changes by intent
Rollback: revert this PR

Evidence

gate-receipt.json present: schema=l9.pr_gate_receipt.v2 content_digest=181102876 passed_at=2026-09-23T05:43:32Z
L4 receipt present: phase=release_authorized tree_digest=25bac168eec2cc92b478139e2a4862471e855dc40496121f3d62acf16e58741f kernel_evidence=evidenced

Gates

  • Regression test added that fails without this fix — n/a — not this change
  • No secrets, tokens, or customer data in code, tests, fixtures, or logs
  • semgrep clean, or findings triaged below — n/a — not this change
  • New IAM / workflow permissions are least privilege and enumerated — n/a — not this change
  • Third-party actions pinned to a full commit SHA — n/a — not this change
  • Public interface change is documented and versioned — n/a — not this change
  • Observability exists for the new path (metric, log, trace, or alert) — n/a — not this change

Reviewer focus

See Changes by intent and Protected-root (if any additive_only path).

Changes by intent

Added

  • n/a

Modified

Deleted

  • n/a

Files touched

  • M CLAUDE.md
  • M GUARDRAILS.md
  • M TESTING.md
  • M agents/cursor/README.md
  • M agents/cursor/docs/CURSOR-L9-INTEGRATION.md
  • M agents/cursor/docs/PRODUCTION-SPEED-PACK.md
  • M agents/cursor/perplexity_research_results/01-15-2026 - memory-substrate-stages/PHASE-0-TODO-STAGE-4-BELIEF-REVISION.md
  • M agents/cursor/perplexity_research_results/01-15-2026 - memory-substrate-stages/stage4_belief_revision_system.md
  • M agents/cursor/perplexity_research_results/01-15-2026 - memory-substrate-stages/stage6_multi_agent_consensus.md
  • M agents/cursor/perplexity_research_results/01-16-2026 - predictive-memory-warming/perplexity-deep-research-output.md
  • M agents/cursor/perplexity_research_results/01-16-2026 - predictive-memory-warming/stage5_predictive_memory_warming.md
  • M agents/cursor/perplexity_research_results/01-20-2026-langgraph-checkpoint-postgres/langgraph-checkpoint-postgres-best-practices.md
  • M agents/cursor/prompts/gmp_examples/GMP-Action-Add-Learning-API-Routes.md
  • M agents/cursor/prompts/gmp_examples/GMP-Action-Create-Learning-Tests.md
  • M agents/cursor/prompts/gmp_examples/GMP-Action-Wire-Learning-Engine.md
  • R100 docs/ACTION ITEMS.MD docs/ACTION ITEMS.md
  • M docs/GRAPH-architecture.md
  • M docs/INFERENCE_ENGINE_KG_ROADMAP.md
  • M docs/L9_Contract_Enforcement_System.md
  • M docs/TROUBLESHOOTING.md
  • M docs/contracts/DEPENDENCY_INJECTION.md
  • M docs/contracts/ERROR_HANDLING.md
  • M docs/contracts/FIELD_NAMES.md
  • M docs/contracts/HANDLER_PAYLOADS.md
  • M docs/contracts/KGE_EMBEDDINGS.md
  • M docs/contracts/MEMORY_SUBSTRATE_ACCESS.md
  • M docs/contracts/NODE_REGISTRATION.md
  • M docs/contracts/OBSERVABILITY.md
  • M docs/contracts/PACKET_ENVELOPE_FIELDS.md
  • M docs/contracts/PII_HANDLING.md
  • M docs/contracts/PYDANTIC_YAML_MAPPING.md
  • M docs/contracts/RETURN_VALUES.md
  • M docs/contracts/SCORING_WEIGHT_CEILING.md
  • M docs/contracts/SHARED_MODELS.md
  • M docs/contracts/TEST_PATTERNS.md
  • M reports/hoprag_ceg_enhancement_program.md
  • M tests/README.md
  • M tools/l9_meta_injector.py
  • M tools/research/cognitive-engine-revenue-patterns.md

Commits

Test plan

  • make pr local gate receipt present
  • L4 release receipt present (release_authorized)
  • CI green — not measured by open_pr_after_gate.sh — do not treat as verified

Changed files

  • M CLAUDE.md
  • M GUARDRAILS.md
  • M TESTING.md
  • M agents/cursor/README.md
  • M agents/cursor/docs/CURSOR-L9-INTEGRATION.md
  • M agents/cursor/docs/PRODUCTION-SPEED-PACK.md
  • M agents/cursor/perplexity_research_results/01-15-2026 - memory-substrate-stages/PHASE-0-TODO-STAGE-4-BELIEF-REVISION.md
  • M agents/cursor/perplexity_research_results/01-15-2026 - memory-substrate-stages/stage4_belief_revision_system.md
  • M agents/cursor/perplexity_research_results/01-15-2026 - memory-substrate-stages/stage6_multi_agent_consensus.md
  • M agents/cursor/perplexity_research_results/01-16-2026 - predictive-memory-warming/perplexity-deep-research-output.md
  • M agents/cursor/perplexity_research_results/01-16-2026 - predictive-memory-warming/stage5_predictive_memory_warming.md
  • M agents/cursor/perplexity_research_results/01-20-2026-langgraph-checkpoint-postgres/langgraph-checkpoint-postgres-best-practices.md
  • M agents/cursor/prompts/gmp_examples/GMP-Action-Add-Learning-API-Routes.md
  • M agents/cursor/prompts/gmp_examples/GMP-Action-Create-Learning-Tests.md
  • M agents/cursor/prompts/gmp_examples/GMP-Action-Wire-Learning-Engine.md
  • R100 docs/ACTION ITEMS.MD docs/ACTION ITEMS.md
  • M docs/GRAPH-architecture.md
  • M docs/INFERENCE_ENGINE_KG_ROADMAP.md
  • M docs/L9_Contract_Enforcement_System.md
  • M docs/TROUBLESHOOTING.md
  • M docs/contracts/DEPENDENCY_INJECTION.md
  • M docs/contracts/ERROR_HANDLING.md
  • M docs/contracts/FIELD_NAMES.md
  • M docs/contracts/HANDLER_PAYLOADS.md
  • M docs/contracts/KGE_EMBEDDINGS.md
  • M docs/contracts/MEMORY_SUBSTRATE_ACCESS.md
  • M docs/contracts/NODE_REGISTRATION.md
  • M docs/contracts/OBSERVABILITY.md
  • M docs/contracts/PACKET_ENVELOPE_FIELDS.md
  • M docs/contracts/PII_HANDLING.md
  • M docs/contracts/PYDANTIC_YAML_MAPPING.md
  • M docs/contracts/RETURN_VALUES.md
  • M docs/contracts/SCORING_WEIGHT_CEILING.md
  • M docs/contracts/SHARED_MODELS.md
  • M docs/contracts/TEST_PATTERNS.md
  • M reports/hoprag_ceg_enhancement_program.md
  • M tests/README.md
  • M tools/l9_meta_injector.py
  • M tools/research/cognitive-engine-revenue-patterns.md

Generated by Claude Code

@claude
docs: pre-format Markdown code blocks for Ruff 0.16 (prep for #288)
32315f9 
Ruff 0.16 formats fenced Python blocks in Markdown by default, and the
ruff-pre-commit v0.16.8 hook adds markdown to its file types. #288 moves
the toolchain to Ruff 0.16.8; landing these formatting-only changes first
keeps #288 under the 50-file reviewable-size policy.

- `ruff format` (0.16.8) applied to 37 Markdown files. Only fenced code
  blocks change; the prose is untouched.
- Rename `docs/ACTION ITEMS.MD` -> `docs/ACTION ITEMS.md` and update its
  entry in tools/l9_meta_injector.py. identify tags `.MD` as markdown, but
  Ruff infers the language case-sensitively and parses the file as Python,
  so the v0.16.8 hook fails on it.

Neutral under the current toolchain (Ruff 0.15.12 does not format
Markdown): `ruff check` and `ruff format --check` pass on both 0.15.12 and
0.16.8. Content is byte-identical to the corresponding files on the #288
head (7b3be91), so merging main into #288 afterwards is conflict-free.

Refs: audit finding F-288-001 (contract work unit R1)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JuFGxFjdiHKkGEvxDvADD1
Copilot AI lite review requested due to automatic review settings September 23, 2026 05:43
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 2026

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@github-actions

github-actions Bot commented Sep 23, 2026 •
edited
Loading

Copy link
Copy Markdown

⚠️ Large PR Warning
Reviewable lines changed: 1655
Warning threshold: 300 lines
Consider splitting for easier review

📋 Best Practices for Large Changes

  1. Refactoring + Features: Separate into 2 PRs
  2. Multiple Features: One PR per feature
  3. Database + Code: Separate migration from logic
  4. Generated Code: Exclude it from reviewable-size accounting

✅ This PR passes the blocking limit but is larger than recommended.

@github-actions

github-actions Bot commented Sep 23, 2026 •
edited
Loading

Copy link
Copy Markdown

L9 Audit Harness Report

  • Generated: 2026-09-23T05:47:07.382233+00:00
  • Repo root: /home/runner/work/Cognitive.Engine.Graphs/Cognitive.Engine.Graphs
  • Overall result: ✅ PASSED
  • Exit code: 0

Step Results

Step Status Exit Code Notes
Architecture Audit ✅ Passed 0
Spec Coverage ✅ Passed 0
Contract Wiring ✅ Passed 0

Architecture Audit Findings

Severity Count
🔴 CRITICAL 0
🟠 HIGH 0
🟡 MEDIUM 17
🔵 LOW 0

See artifacts/audit_report.md for full details.

Spec Coverage

  • ✅ Implemented: 37
  • ⚠️ Partial: 9
  • ❌ Missing: 0
  • Total features: 46
Category Implemented Partial Missing Total
gates 10 0 0 10
scoring 7 0 0 7
v1.1_node 2 0 0 2
v1.1_edge 2 0 0 2
v1.1_action 0 2 0 2
v1.1_scoring 1 1 0 2
action_handler 0 6 0 6
gds_algorithm 5 0 0 5
research_pattern 10 0 0 10

See artifacts/coverage_report.md for full details.

Next Steps

All checks passed. Safe to merge.

@cryptoxdog cryptoxdog mentioned this pull request Sep 23, 2026
Merged
Copilot AI reviewed Sep 23, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The PR introduces documentation rendering issues (a stray ====== line and a broken/invalid Python example snippet indentation) that should be fixed before merge.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 Low severity

Open (1)
What changed in this PR

This PR prepares the repository’s Markdown (and embedded code examples) for Ruff 0.16’s default Markdown formatting, to keep the upcoming Ruff toolchain bump (#288) smaller and reviewable.

Changes:

  • Reformat fenced code blocks and surrounding whitespace across docs/ and agent documentation to match Ruff 0.16’s Markdown formatting.
  • Normalize the docs/ACTION ITEMS.md filename casing (and update the meta injector registry accordingly).
  • Minor punctuation/whitespace adjustments in code examples (commas, spacing, line breaks) driven by formatter behavior.
File Description
CLAUDE.md Reformat fenced Python examples for Ruff 0.16 Markdown formatting.
GUARDRAILS.md Reformat fenced code block spacing for Ruff 0.16.
TESTING.md Reformat fenced test examples for Ruff 0.16.
agents/​cursor/​README.md Remove/adjust blank lines in code blocks per Ruff formatting.
agents/​cursor/​docs/​CURSOR-L9-INTEGRATION.md Reformat code examples/comments for Ruff 0.16.
agents/​cursor/​docs/​PRODUCTION-SPEED-PACK.md Reformat code snippets and spacing for Ruff 0.16.
agents/​cursor/​perplexity_research_results/​01-15-2026 - memory-substrate-stages/​PHASE-0-TODO-STAGE-4-BELIEF-REVISION.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​perplexity_research_results/​01-15-2026 - memory-substrate-stages/​stage4_belief_revision_system.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​perplexity_research_results/​01-15-2026 - memory-substrate-stages/​stage6_multi_agent_consensus.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​perplexity_research_results/​01-16-2026 - predictive-memory-warming/​perplexity-deep-research-output.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​perplexity_research_results/​01-16-2026 - predictive-memory-warming/​stage5_predictive_memory_warming.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​perplexity_research_results/​01-20-2026-langgraph-checkpoint-postgres/​langgraph-checkpoint-postgres-best-practices.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​prompts/​gmp_examples/​GMP-Action-Add-Learning-API-Routes.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​prompts/​gmp_examples/​GMP-Action-Create-Learning-Tests.md Reformat code blocks per Ruff 0.16.
agents/​cursor/​prompts/​gmp_examples/​GMP-Action-Wire-Learning-Engine.md Reformat code blocks per Ruff 0.16.
docs/​ACTION ITEMS.md Rename file casing + apply Ruff-compatible Markdown/code formatting.
docs/​GRAPH-architecture.md Reformat code examples per Ruff 0.16.
docs/​INFERENCE_ENGINE_KG_ROADMAP.md Reformat code examples per Ruff 0.16.
docs/​L9_Contract_Enforcement_System.md Reformat embedded Python example for Ruff 0.16.
docs/​TROUBLESHOOTING.md Reformat code examples per Ruff 0.16.
docs/​contracts/​DEPENDENCY_INJECTION.md Reformat code examples per Ruff 0.16.
docs/​contracts/​ERROR_HANDLING.md Reformat code examples per Ruff 0.16.
docs/​contracts/​FIELD_NAMES.md Reformat code examples per Ruff 0.16.
docs/​contracts/​HANDLER_PAYLOADS.md Reformat code examples per Ruff 0.16.
docs/​contracts/​KGE_EMBEDDINGS.md Reformat code examples per Ruff 0.16.
docs/​contracts/​MEMORY_SUBSTRATE_ACCESS.md Reformat code examples per Ruff 0.16.
docs/​contracts/​NODE_REGISTRATION.md Reformat code examples per Ruff 0.16.
docs/​contracts/​OBSERVABILITY.md Reformat code examples per Ruff 0.16.
docs/​contracts/​PACKET_ENVELOPE_FIELDS.md Reformat code examples per Ruff 0.16.
docs/​contracts/​PII_HANDLING.md Reformat code examples per Ruff 0.16.
docs/​contracts/​PYDANTIC_YAML_MAPPING.md Reformat code examples per Ruff 0.16.
docs/​contracts/​RETURN_VALUES.md Reformat code examples per Ruff 0.16.
docs/​contracts/​SCORING_WEIGHT_CEILING.md Reformat code examples per Ruff 0.16.
docs/​contracts/​SHARED_MODELS.md Reformat code examples per Ruff 0.16.
docs/​contracts/​TEST_PATTERNS.md Reformat code examples per Ruff 0.16.
reports/​hoprag_ceg_enhancement_program.md Reformat embedded code snippet per Ruff 0.16.
tests/​README.md Reformat embedded test examples per Ruff 0.16.
tools/​l9_meta_injector.py Update FileMeta registry entry to match renamed docs filename casing.
tools/​research/​cognitive-engine-revenue-patterns.md Reformat embedded code examples per Ruff 0.16.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread docs/contracts/PACKET_ENVELOPE_FIELDS.md Outdated
@claude
docs(contracts): restore class context for PacketEnvelope optional fi…
7d2273d 
…elds

The "Standard Optional Fields" snippet was an indented continuation of
`class PacketEnvelope`. Ruff 0.16 Markdown formatting dedented it into
top-level assignments, which misstates the contract. Repeat the class
header so the block is valid Python and stays stable under ruff format.

Reported by Copilot review on #296.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JuFGxFjdiHKkGEvxDvADD1
cryptoxdog pushed a commit that referenced this pull request Sep 23, 2026
@claude
docs(contracts): restore class context for PacketEnvelope optional fi…
0af6f81 
…elds

The "Standard Optional Fields" snippet was an indented continuation of
`class PacketEnvelope`. Ruff 0.16 Markdown formatting dedented it into
top-level assignments, which misstates the contract. Repeat the class
header so the block is valid Python and stays stable under ruff format.

Reported by Copilot review on #296.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JuFGxFjdiHKkGEvxDvADD1
@sonarqubecloud

sonarqubecloud Bot commented Sep 23, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

cryptoxdog pushed a commit that referenced this pull request Sep 24, 2026
@dependabot @claude
chore(deps)(deps): bump the dev-tools group with 2 updates (#288)
828ffd3 
* chore(deps)(deps): bump the dev-tools group with 2 updates

Bumps the dev-tools group with 2 updates: [ruff](https://github.com/astral-sh/ruff) and [mypy](https://github.com/python/mypy).


Updates `ruff` from 0.15.12 to 0.16.8
- [Release notes](https://github.com/astral-sh/ruff/releases)
- [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md)
- [Commits](astral-sh/ruff@0.15.12...0.16.8)

Updates `mypy` from 1.14.0 to 2.3.1
- [Changelog](https://github.com/python/mypy/blob/master/CHANGELOG.md)
- [Commits](python/mypy@v1.14.0...v2.3.1)

---
updated-dependencies:
- dependency-name: ruff
  dependency-version: 0.16.8
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: dev-tools
- dependency-name: mypy
  dependency-version: 2.3.1
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: dev-tools
...

Signed-off-by: dependabot[bot] <support@github.com>

* fix(deps): converge Ruff 0.16.8 / Mypy 2.3.1 across all toolchain consumers

Closes audit finding F-288-001 (contract work unit R1).

The Dependabot bump moved Ruff to 0.16.8 only in pyproject/poetry.lock,
so CI (which installs from requirements-ci.txt, the declared SSOT) still
ran Ruff 0.15.12 and pre-commit still pinned ruff-pre-commit v0.15.5 and
mirrors-mypy v1.14.0.

- requirements-ci.txt, requirements-dev.txt: ruff 0.15.12 -> 0.16.8
- .pre-commit-config.yaml: ruff-pre-commit v0.15.5 -> v0.16.8,
  mirrors-mypy v1.14.0 -> v2.3.1

No rules, ignores, or excludes changed.

Remediation-Cycle: #288/cycle-1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JuFGxFjdiHKkGEvxDvADD1

* fix(lint): resolve findings newly exposed by Ruff 0.16.8

Scope extension to R1 approved by the operator: fix the findings Ruff
0.16.8 surfaces (0.15.12 was clean) rather than suppressing them. No rule
ignores, per-file ignores, or excludes were added.

PLR0917 (too-many-positional-arguments, 18 sites): parameters that call
sites already pass by keyword become keyword-only (`*`). Call sites that
passed more than five positionals were converted to keywords:
- tools/contract_scanner.py `_rule`: `remediation` is keyword-only (28 rules)
- tests/test_algorithmic_upgrades.py `_make_fp`: `entropy`, `concentration`
- tools/auditors/log_safety.py `_emit_finding`: all keyword-only
Public engine APIs touched (AuditLogger.log_*, measure_health_impact,
track_conversion_event, MultiHopTraverser) keep every required parameter
positional; only optional defaults became keyword-only, and every in-repo
caller already passes them by keyword.

ISC004 (3 sites): parenthesize the implicit string concatenations in
engine/intake/impact_reporter.py format_impact_summary.

Markdown: Ruff 0.16 formats fenced Python blocks in .md by default, and the
ruff-pre-commit v0.16.8 hook now includes markdown files. Applied
`ruff format` to 37 docs (code-fence changes only). Renamed
`docs/ACTION ITEMS.MD` -> `.md` (reference updated in
tools/l9_meta_injector.py): identify tags `.MD` as markdown but Ruff
infers language case-sensitively and parsed it as Python.

Validation: ruff check / ruff format --check clean; mypy engine/ clean
(2.3.1); pre-commit run --all-files all hooks pass; contract scanner clean;
pytest (non-integration) 2134 passed. The 4 tests/performance errors need
a Docker socket and fail the same way on the unmodified tree.

Remediation-Cycle: #288/cycle-1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JuFGxFjdiHKkGEvxDvADD1

* docs(contracts): restore class context for PacketEnvelope optional fields

The "Standard Optional Fields" snippet was an indented continuation of
`class PacketEnvelope`. Ruff 0.16 Markdown formatting dedented it into
top-level assignments, which misstates the contract. Repeat the class
header so the block is valid Python and stays stable under ruff format.

Reported by Copilot review on #296.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JuFGxFjdiHKkGEvxDvADD1

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
@cryptoxdog
cryptoxdog merged commit 1ac258d into main Sep 24, 2026
57 checks passed
@cryptoxdog
cryptoxdog deleted the claude/pr-repairs-contract-audit-x0juhj branch September 24, 2026 16:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@cryptoxdog @claude