feat: P1: Run truthful opt-in Ruff lint and format checks

.github/workflows/ci.yml

@@ -59,6 +59,11 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Provision pinned Ruff proof artifact
+        run: |
+          python -m pip install --disable-pip-version-check ruff==0.6.9
+          test "$(ruff --version)" = "ruff 0.6.9"
+
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
         with:

AGENTS.md

@@ -91,6 +91,7 @@ Opcore is the code-intelligence and robustness monorepo for graph context, edit
 - #17 Python export metadata is best-effort: `__all__` wins when present, otherwise the leading-underscore convention marks module-level public names; file `exports[]` entries must include policy and supportedSymbol - WHY: Python has no enforced export boundary.
 - #244 `python.syntax` resolves one concrete interpreter through the Python project resolver, executes that exact interpreter with an isolated versioned JSON compile protocol over sorted `.py`/`.pyi` after-state content, and reports ranged/provenanced compiler diagnostics plus fine-grained outcomes. Parser-success overrides and hand-written grammar heuristics are forbidden; malformed output, nonzero exits, signals, and timeouts fail closed - WHY: syntax truth, target-version truth, and tool provenance must come from the same compiler invocation without mutating the source repo.
 - #246 makes `@the-open-engine/opcore-validation-python` the sole dynamic owner of `opcore.python.project-context.v1`: every Python target resolves against its nearest project boundary through an injected read/list/exists/realpath workspace view, smol-toml AST config/build metadata, exact interpreter/tool/build probes, and after-state content. Missing realpath evidence is ambiguous, deleted overlays cannot remain discovery markers, and declared constraints never become invented exact versions. Validation, status, scan, init/install preview, metrics, ASP, and installed execution must reuse the resulting project key, context fingerprint, outcome, and provenance; ASP workspace/config reads must remain host-callback-only. Static descriptors advertise only the schema, outcome vocabulary, read-only behavior, and no-install guarantee - WHY: root-scoped and duplicate project/environment discovery validates nested monorepo files with the wrong interpreter and makes surfaces disagree. #256/#257 make `python.types` select and execute exactly one mypy or Pyright authority per canonical project. Mypy uses first-match config precedence and strict NDJSON. Pyright preserves `pyrightconfig.json` precedence over `[tool.pyright]`, recursive repo-confined extends, and config-driven source/stub semantics while consuming only complete `--outputjson`. Both authorities use the same isolated exact after-state, portable receipt, selected interpreter, bounded process-tree runner, and sanitized HOME/XDG/cache/temp environment. Availability never selects an authority or permits fallback. Malformed, partial, contradictory, version/count-mismatched, out-of-repo, fatal, or stderr protocol evidence fails closed, and every project attempt emits `opcore.python.validation-capability-run` evidence - WHY: host config/imports, source mutation, orphaned checker descendants, availability, human-output parsing, or check-level summaries cannot prove which project/config/after-state produced type evidence.
+- #258 keeps `python.ruff-lint` and `python.ruff-format` separate from `python.source-hygiene` and opt-in through explicit selection or `.opcore/config` defaults. They execute the #246-selected Ruff over a temporary #245 after-state workspace with fixes, writes, and caches disabled; lint consumes JSON and format uses bounded exit-code refinement. Closest target-applicable `.ruff.toml`, `ruff.toml`, or `[tool.ruff]` configuration searches through the repository root across nested Python project boundaries, partitions project execution, requires non-symlink realpath evidence for every selected or recursively extended config, and materializes only that config closure. Python types and Ruff share the `packages/validation-python/src/python-execution-workspace.ts` primitive and sanitized HOME/XDG/TMP/PATH runtime for after-state fingerprinting, materialization, execution isolation, and cleanup while capability code selects its own support files. Ruff receipts use the shared `afterStateManifestFingerprint` field and portable executable/argv locators. Missing Ruff degrades status only while a Ruff check is active, and metrics require executed capability receipts - WHY: optional source tooling must never be probed, invoked, counted, or reported as enforced when policy did not select it, target-local configuration must not leak across files, host state must not affect results, and parallel materializers can make tool inputs diverge from receipts.
 - #209 makes Rust graph-core the sole parser/resolver for Python repo imports. `@the-open-engine/opcore-graph` materializes supplied `.py`/`.pyi` after-state files only in an isolated temporary repo and returns canonical directed `IMPORTS_FROM` file edges; validation-python owns only the structural analyzer contract, visible-file enumeration, cached target/transitive closure, and edge consumption. Opcore, advanced validation, validation-policy, and ASP inject the graph adapter; missing/failed/malformed analysis is an infrastructure failure, never empty success - WHY: a second TypeScript import grammar/resolver diverges on multiline syntax, overlays, packages, stubs, namespaces, and src layouts.
 - #197 makes hypothetical graph evaluation exact-state: validation creates one `ValidationFileView` per before/after state and owns one disposable graph session for that view; graph materializes the complete visible TS/TSX/JS/JSX, Python `.py`/`.pyi`, and Rust `.rs` universe into a bounded isolated root, builds graph-core once, shares the immutable session across checks, and removes it on every exit. Introduced mode must use distinct before/after snapshots, ASP listings must preserve host truncation, and exact-state construction/query failure is non-pass even when persistent graph mode is optional - WHY: a persistent target-repo graph or incomplete listing cannot describe hypothetical file contents and must never produce a false clean pre-write result.
 - #19 requires graph status to preserve real WAL checkpoint evidence from the latest pipeline summary and release gates to fail missing/fabricated WAL evidence - WHY: freshness and checkpoint pressure must remain host-visible provider facts.
@@ -214,8 +215,6 @@ Opcore is the code-intelligence and robustness monorepo for graph context, edit
 ## Commands
 
 - Setup and wrappers: `npm run setup`, `npm run setup:tools`, `source scripts/dev-env.sh`, `npm run ace:install`, `npm run ace:sync`, `npm run ace:validate`.
-- Core proof: `npm run ci`, targeted `node --test tests/...`, `npm run rust:check`, `npm run ci:local` or `npm run verify`.
-- Release proof: `npm run graph:artifact`, `npm run descriptor:artifact`, `npm run asp-provider:manifest`, `npm run graph-release:check`, `npm run release-receipt:check`, `npm run cutover:check`, `npm run asp-dogfood:check`, `npm run pack:check`, `npm run release:hygiene`.
-- Current-tool guardrails: `npm run current-tools:validate-changed`, `npm run current-tools:validate-all`, `npm run current-tools:validate-rust-graph`.
+- Proof: core `npm run ci`, targeted `node --test tests/...`, `npm run rust:check`, `npm run ci:local` or `npm run verify`; release `npm run graph:artifact`, `npm run descriptor:artifact`, `npm run asp-provider:manifest`, `npm run graph-release:check`, `npm run release-receipt:check`, `npm run cutover:check`, `npm run asp-dogfood:check`, `npm run pack:check`, `npm run release:hygiene`; retained guardrails `npm run current-tools:validate-changed`, `npm run current-tools:validate-all`, `npm run current-tools:validate-rust-graph`.
 - Public scan/readiness: `opcore --repo . --json`, `opcore status --repo . --json`, `opcore --version --json`, `opcore doctor --repo . --json`, `opcore measure --repo . --json`, `opcore try --json`.
 - Public setup/check/provider: `opcore install --repo . --json`, `opcore install --repo . --yes --json`, `opcore uninstall --repo . --yes --json`, `opcore check --changed --json`, `opcore-asp-provider --stdio`.

CLAUDE.md

@@ -91,6 +91,7 @@ Opcore is the code-intelligence and robustness monorepo for graph context, edit
 - #17 Python export metadata is best-effort: `__all__` wins when present, otherwise the leading-underscore convention marks module-level public names; file `exports[]` entries must include policy and supportedSymbol - WHY: Python has no enforced export boundary.
 - #244 `python.syntax` resolves one concrete interpreter through the Python project resolver, executes that exact interpreter with an isolated versioned JSON compile protocol over sorted `.py`/`.pyi` after-state content, and reports ranged/provenanced compiler diagnostics plus fine-grained outcomes. Parser-success overrides and hand-written grammar heuristics are forbidden; malformed output, nonzero exits, signals, and timeouts fail closed - WHY: syntax truth, target-version truth, and tool provenance must come from the same compiler invocation without mutating the source repo.
 - #246 makes `@the-open-engine/opcore-validation-python` the sole dynamic owner of `opcore.python.project-context.v1`: every Python target resolves against its nearest project boundary through an injected read/list/exists/realpath workspace view, smol-toml AST config/build metadata, exact interpreter/tool/build probes, and after-state content. Missing realpath evidence is ambiguous, deleted overlays cannot remain discovery markers, and declared constraints never become invented exact versions. Validation, status, scan, init/install preview, metrics, ASP, and installed execution must reuse the resulting project key, context fingerprint, outcome, and provenance; ASP workspace/config reads must remain host-callback-only. Static descriptors advertise only the schema, outcome vocabulary, read-only behavior, and no-install guarantee - WHY: root-scoped and duplicate project/environment discovery validates nested monorepo files with the wrong interpreter and makes surfaces disagree. #256/#257 make `python.types` select and execute exactly one mypy or Pyright authority per canonical project. Mypy uses first-match config precedence and strict NDJSON. Pyright preserves `pyrightconfig.json` precedence over `[tool.pyright]`, recursive repo-confined extends, and config-driven source/stub semantics while consuming only complete `--outputjson`. Both authorities use the same isolated exact after-state, portable receipt, selected interpreter, bounded process-tree runner, and sanitized HOME/XDG/cache/temp environment. Availability never selects an authority or permits fallback. Malformed, partial, contradictory, version/count-mismatched, out-of-repo, fatal, or stderr protocol evidence fails closed, and every project attempt emits `opcore.python.validation-capability-run` evidence - WHY: host config/imports, source mutation, orphaned checker descendants, availability, human-output parsing, or check-level summaries cannot prove which project/config/after-state produced type evidence.
+- #258 keeps `python.ruff-lint` and `python.ruff-format` separate from `python.source-hygiene` and opt-in through explicit selection or `.opcore/config` defaults. They execute the #246-selected Ruff over a temporary #245 after-state workspace with fixes, writes, and caches disabled; lint consumes JSON and format uses bounded exit-code refinement. Closest target-applicable `.ruff.toml`, `ruff.toml`, or `[tool.ruff]` configuration searches through the repository root across nested Python project boundaries, partitions project execution, requires non-symlink realpath evidence for every selected or recursively extended config, and materializes only that config closure. Python types and Ruff share the `packages/validation-python/src/python-execution-workspace.ts` primitive and sanitized HOME/XDG/TMP/PATH runtime for after-state fingerprinting, materialization, execution isolation, and cleanup while capability code selects its own support files. Ruff receipts use the shared `afterStateManifestFingerprint` field and portable executable/argv locators. Missing Ruff degrades status only while a Ruff check is active, and metrics require executed capability receipts - WHY: optional source tooling must never be probed, invoked, counted, or reported as enforced when policy did not select it, target-local configuration must not leak across files, host state must not affect results, and parallel materializers can make tool inputs diverge from receipts.
 - #209 makes Rust graph-core the sole parser/resolver for Python repo imports. `@the-open-engine/opcore-graph` materializes supplied `.py`/`.pyi` after-state files only in an isolated temporary repo and returns canonical directed `IMPORTS_FROM` file edges; validation-python owns only the structural analyzer contract, visible-file enumeration, cached target/transitive closure, and edge consumption. Opcore, advanced validation, validation-policy, and ASP inject the graph adapter; missing/failed/malformed analysis is an infrastructure failure, never empty success - WHY: a second TypeScript import grammar/resolver diverges on multiline syntax, overlays, packages, stubs, namespaces, and src layouts.
 - #197 makes hypothetical graph evaluation exact-state: validation creates one `ValidationFileView` per before/after state and owns one disposable graph session for that view; graph materializes the complete visible TS/TSX/JS/JSX, Python `.py`/`.pyi`, and Rust `.rs` universe into a bounded isolated root, builds graph-core once, shares the immutable session across checks, and removes it on every exit. Introduced mode must use distinct before/after snapshots, ASP listings must preserve host truncation, and exact-state construction/query failure is non-pass even when persistent graph mode is optional - WHY: a persistent target-repo graph or incomplete listing cannot describe hypothetical file contents and must never produce a false clean pre-write result.
 - #19 requires graph status to preserve real WAL checkpoint evidence from the latest pipeline summary and release gates to fail missing/fabricated WAL evidence - WHY: freshness and checkpoint pressure must remain host-visible provider facts.
@@ -214,8 +215,6 @@ Opcore is the code-intelligence and robustness monorepo for graph context, edit
 ## Commands
 
 - Setup and wrappers: `npm run setup`, `npm run setup:tools`, `source scripts/dev-env.sh`, `npm run ace:install`, `npm run ace:sync`, `npm run ace:validate`.
-- Core proof: `npm run ci`, targeted `node --test tests/...`, `npm run rust:check`, `npm run ci:local` or `npm run verify`.
-- Release proof: `npm run graph:artifact`, `npm run descriptor:artifact`, `npm run asp-provider:manifest`, `npm run graph-release:check`, `npm run release-receipt:check`, `npm run cutover:check`, `npm run asp-dogfood:check`, `npm run pack:check`, `npm run release:hygiene`.
-- Current-tool guardrails: `npm run current-tools:validate-changed`, `npm run current-tools:validate-all`, `npm run current-tools:validate-rust-graph`.
+- Proof: core `npm run ci`, targeted `node --test tests/...`, `npm run rust:check`, `npm run ci:local` or `npm run verify`; release `npm run graph:artifact`, `npm run descriptor:artifact`, `npm run asp-provider:manifest`, `npm run graph-release:check`, `npm run release-receipt:check`, `npm run cutover:check`, `npm run asp-dogfood:check`, `npm run pack:check`, `npm run release:hygiene`; retained guardrails `npm run current-tools:validate-changed`, `npm run current-tools:validate-all`, `npm run current-tools:validate-rust-graph`.
 - Public scan/readiness: `opcore --repo . --json`, `opcore status --repo . --json`, `opcore --version --json`, `opcore doctor --repo . --json`, `opcore measure --repo . --json`, `opcore try --json`.
 - Public setup/check/provider: `opcore install --repo . --json`, `opcore install --repo . --yes --json`, `opcore uninstall --repo . --yes --json`, `opcore check --changed --json`, `opcore-asp-provider --stdio`.

docs/architecture/runtime-cli-ard.md

@@ -130,6 +130,12 @@ Rust checks read candidate files through `ValidationCheckContext.fileView`. Chec
 
 Python syntax diagnostics carry normalized workspace-relative paths, stable compiler-error codes, 1-based ranges when supplied by the interpreter, and interpreter provenance. Validation run summaries preserve fine-grained `passed`, `findings`, `tool_unavailable`, `invalid_config`, `timeout`, `unsupported_target`, and `tool_failure` outcomes while retaining aggregate validation statuses. Protocol/schema mismatch, unknown nonzero exit, timeout, signal, spawn failure, and mismatched file/provenance output fail closed. Hand-written delimiter, quote, comment, or compound-header grammar checks must not override compiler success; any future supplemental Python policy requires a separate check ID and category.
 
+## Opt-in Ruff Validation
+
+#258 adds `python.ruff-lint` and `python.ruff-format` as validation-python-owned warning checks with no default scopes. Explicit selection or `.opcore/config` validation defaults activate them; disabled policy wins. Unselected and disabled checks emit non-execution receipts and do not probe Ruff or degrade status. `python.source-hygiene` remains an independent Opcore policy check.
+
+Both checks reuse the canonical Python project context, graph-derived source closure, and temporary after-state workspace. Target-applicable Ruff configuration discovery continues through the repository root across nested Python project boundaries. The selected config and every recursive `extend` file require non-symlink realpath evidence before their overlay-aware contents are read or materialized. Ruff configuration, target version, and overlays are materialized without mutating source, configuration, lockfiles, environments, or caches. Lint runs `ruff check --output-format=json --no-fix --no-cache --force-exclude`; format runs bounded `ruff format --check --no-cache --force-exclude` batches and refines exit-1 batches by file without parsing human prose. Every execution carries portable project, context, `afterStateManifestFingerprint`, path, executable/argv, tool, termination, duration, and diagnostic-count evidence; a deleted-only after-state scope emits an explicit non-execution `not_applicable` receipt. Missing tools, invalid selected configuration, malformed output, unsupported targets, timeouts, signals, spawn failures, output overflow, and unknown exits remain explicit non-pass outcomes.
+
 ## Clone Validation Adapter
 
 #151 adds `@the-open-engine/opcore-validation-clone` as the duplicate-code validation adapter package. The stable check id is `clone.duplication`; it requiresGraph:false, reads candidate after-state through `ValidationCheckContext.fileView.readAfter`, and emits line-free duplicate-code diagnostics with stable clone-class identity. The adapter receives its native invocation function from Opcore validation composition, so it does not import graph-core loaders, raw SQLite, graph internals, or the aggregate CLI.