Lint and Semgrep hygiene policy¶

This policy records the Slice 18 review of every current lint suppression, Semgrep exception, and repository-owned rule. It is deliberately specific: new suppressions must either be removed or added here with a concrete owner and reason. tests/test_quality_policy.py prevents a new # noqa location from appearing without this inventory.

`# noqa` inventory¶

src/codira/family_runtime.py:468 PLR0913 — federation query options expose the independently selectable operation, member filter, pagination, direction, and explicit partial-results policy at the shared CLI/MCP boundary.

src/codira/mcp/family_server.py:171 PLR0913 — MCP reference-tool parameters remain separate discoverable request-schema fields rather than an opaque request object, preserving declared-member filtering and strict SDK validation.

scripts/run_agent_efficiency_phase6_review.py:2 EM101, S607, TRY003, TRY301 — the review-only transport uses explicit Git command vectors and public-safe failure messages; its credentials are supplied only by the SOPS-scoped child process.

scripts/run_agent_efficiency_phase6_reviewer_evaluation.py:3 EM101, S310, S607, TRY003 — the bounded evaluator invokes explicit Git vectors and the fixed public OpenRouter catalog/key endpoints; response bodies and credentials remain outside tracked records.

scripts/run_agent_efficiency_phase6_review.py:382 S310 — the review-only transport makes one explicit HTTPS request to the fixed OpenRouter endpoint; the supplied request is constructed locally and the SOPS-scoped credential is never logged.

scripts/run_agent_efficiency_phase6_review.py:308 C901, PLR0913 — the bounded review transport keeps each request-control boundary explicit so the immutable model, token, timeout, and reasoning controls are independently auditable.

The review removed two obsolete E501 suppressions from tests/test_contracts.py. All remaining suppressions name the narrow rule they suppress.

scripts/scriptlib.py:270 PLR0913 — public process runner keeps explicit
    command, environment, and failure-boundary inputs for reusable scripts.
scripts/run_manifest_baseline.py:131 PLR0913 — benchmark invocation inputs are
    independently selectable for reproducible comparisons.
scripts/agent_efficiency/oracles.py:133 PLR0913 — the protected trace writer
  keeps command metadata, complete output streams, and trace identity explicit
  so forensic evidence remains deterministic and auditable.
scripts/agent_efficiency/oracles.py:750 PLR0913 — oracle-node evaluation keeps
  evaluation context and trace propagation explicit so grading remains
  deterministic and auditable.
scripts/agent_efficiency/oracles.py:859 PLR0913 — composite evaluation keeps
  recursive trace propagation explicit alongside the grader inputs.
scripts/agent_efficiency/oracles.py:1006 PLR0913 — the public oracle boundary
  keeps result format, protected root, evaluator registry, and optional trace
  root explicit.
scripts/run_retrieval_quality_benchmark.py:617,913 PLR0913 — result rows and
    benchmark groups preserve explicit provenance and execution inputs.
scripts/run_final_embedding_model_campaign.py:432,577,642,793 PLR0913 — the
    release-campaign artifact functions retain independently auditable inputs.
scripts/run_final_embedding_model_campaign.py:860 C901,PLR0912 — CLI phase
    dispatch is intentionally linear so every restart/checkpoint branch remains visible.
scripts/characterize_similarity_indexes.py:306 PLR0913 — the reproducible
    corpus runner keeps independently selectable corpus and timing inputs.
scripts/generate_github_snapshot.py:118 S607 — the fixed `gh` executable is
    intentionally invoked by argument vector; there is no shell interpolation.
src/codira/indexer.py:1272 PLR0913 — bulk indexing keeps backend, transaction,
    artifact, coverage, and embedding ownership explicit at the orchestration seam.
src/codira/contracts.py:3317 PLR0913 — the plugin protocol signature is a
    public compatibility contract and cannot be bundled without breaking providers.
src/codira/contracts.py:17 EM101,TRY003 — public contract validation keeps
    short, consistent exception messages at the typed boundary.
src/codira/config_validation.py:574 C901 — configuration semantics remain deliberately
    centralized so versioned breaking-change guidance is deterministic.
src/codira/daemon/service_spec.py:110 PLR0913 — one factory records the full,
    immutable workspace service identity needed by all platform adapters.
src/codira/daemon/launchd.py:159 PLR0913 — injected platform/process seams keep
    launchd rendering deterministic and testable.
src/codira/daemon/runtime.py:133 PLR0913 — foreground daemon dependencies are
    explicit runtime controls rather than hidden globals.
src/codira/migration.py:153 PLR0913 — migration preview reports every resolved
    workspace input without mutating registration state.
src/codira/query_daemon_lifecycle.py:580 PLR0913 — service lifecycle inputs are
    explicit to preserve platform-independent restart behavior.
src/codira/query_daemon_ipc.py:902 PLR0913 — IPC server construction exposes its
    authentication, runtime, and connection-boundary dependencies.
src/codira/cli_index.py:150 C901,PLR0912 — index CLI failure/reporting branches are
    deliberately explicit because they are the user-facing command contract.
src/codira/cli_queries.py:2395 PLR0913 — daemon context rendering receives the complete
    explicit query/output/profile request after freshness has been established.
src/codira/cli.py:463 PLR0913 — command dispatch receives parsed arguments and
    resolved routing/runtime state as one explicit integration boundary.
src/codira/cli.py:381 E402 — compatibility re-export import ordering avoids
    cycles while retaining existing `codira.cli` imports.
src/codira/cli.py:390 E402 — compatibility re-export import ordering avoids
    cycles while retaining existing `codira.cli` imports.
src/codira/cli.py:401 E402 — compatibility re-export import ordering avoids
    cycles while retaining existing `codira.cli` imports.
src/codira/cli.py:402 E402 — compatibility re-export import ordering avoids
    cycles while retaining existing `codira.cli` imports.
src/codira/cli.py:419 E402 — compatibility re-export import ordering avoids
    cycles while retaining existing `codira.cli` imports.
src/codira/cli.py:424 E402 — compatibility re-export import ordering avoids
    cycles while retaining existing `codira.cli` imports.
src/codira/query/context_scoring.py:637, src/codira/query/context_scoring.py:779,
    and src/codira/query/context_scoring.py:814 PLR0913 — lexical channel
    functions share an explicit root/query/connection/intent/prefix/profile
    contract so named similarity profiles reach only semantic channels.
src/codira/query/context_channels.py:973,
    src/codira/query/context_channels.py:1076, and
    src/codira/query/context_channels.py:1131 PLR0913 — semantic channel
    functions retain the same explicit retrieval contract.
src/codira/docstring.py:1297, src/codira/docstring.py:1408 PLC0415 — lazy imports avoid a configuration or
    registry import cycle on the optional documentation-plugin path.
src/codira/docstring.py:1351, src/codira/docstring.py:1502 PLR0913 — documentation validation preserves
    source, configuration, visibility, and plugin-routing provenance.
src/codira/query_daemon.py:349,366 BLE001 — worker initialization and operation
    failures must cross the future boundary as their original exception.
src/codira/query_daemon_lifecycle.py:721,738 BLE001 — a long-lived service must
    report any unexpected refresh or foreground failure as degraded state.
src/codira/query_daemon_ipc.py:1282,1372 BLE001 — the IPC boundary converts any
    unexpected implementation failure into a stable protocol/unavailable result.
packages/codira-vector-store-sqlite/tests/test_sqlite_vector_store_package.py:489
    BLE001 — the concurrent-writer regression records every thread failure for
    deterministic assertion in the main test thread.
src/codira/mcp/server.py:223 SLF001 — FastMCP exposes no public transport hook;
    its private server object is the required stdio transport boundary.
src/codira/workspace_registry.py:8 TC003 — `Path` is used at runtime in
    descriptor construction as well as annotations.
src/codira/similarity.py:14 EM101,TRY003 — snapshot validation exposes concise,
    stable derived-index errors at the plugin contract boundary.
src/codira/semantic/search.py:20 TC003 — `Path` is a runtime request field at
    the similarity-index boundary.
src/codira/semantic/search.py:193 PLR0913 — candidate discovery keeps explicit
    root, vector-store, profile, and filtering inputs at the query boundary.
tests/test_workspace_registry.py:9 TC003 — `Path` creates runtime fixture paths.
packages/codira-installer/tests/test_tui.py:8 TC003 — `Path` creates runtime TUI
    fixture paths.
packages/codira-analyzer-python/tests/fixtures/runtime_decoupling_baseline.py:3
    F401 — the unused alias is the intentional import artifact under test.
fixtures/packages/codira-backend-duckdb/src/full_index_bulk_violation.py:39 N802
    — the fixture must imitate the production request constructor name to
    trigger the Semgrep rule.

Location aliases for the grouped entries above:
scripts/run_final_embedding_model_campaign.py:577,
scripts/run_final_embedding_model_campaign.py:642,
scripts/run_final_embedding_model_campaign.py:793,
scripts/run_retrieval_quality_benchmark.py:913,
src/codira/docstring.py:1019, src/codira/docstring.py:1114,
src/codira/index_generation.py:160,
src/codira/query_daemon.py:366, src/codira/query_daemon_lifecycle.py:738, and
src/codira/query_daemon_ipc.py:1372 retain the same category-specific reasons
as their immediately preceding grouped entries.

Repository-owned Semgrep rules¶

Every rule has a violating fixture and is asserted by scripts/validate_semgrep_rules.py and tests/test_semgrep_rules.py.

Rule family	Current purpose
Analyzer boundaries: `no-storage-import-in-analyzers`, `no-registry-import-in-analyzers`, `no-backend-import-in-analyzers`, `no-sqlite3-in-analyzers`, `require-analyzer-capability-declaration`, `no-host-ast-in-python-analysis`	Keep analyzers storage-, backend-, registry-, and host-parser-independent while requiring a declared capability contract.
Core/backend ownership: `no-sqlite3-outside-allowed-layers`, `no-backend-package-import-outside-allowed-layers`, `no-core-schema-ddl-import-in-backends`	Keep physical SQLite/DuckDB schema and package dependencies in their owning layers.
DuckDB bulk path: `no-duckdb-executemany-in-support`, `no-duckdb-returning-id-in-support`, `no-store-analysis-in-duckdb-full-index-bulk`, `require-fresh-full-index-embedding-flush`, `no-vector-store-normal-path-in-duckdb-full-index-bulk`, `require-duckdb-full-index-vector-preservation`	Preserve the columnar full-index path, correct ID allocation, and vector reuse semantics.
Runtime and plugin boundaries: `no-direct-config-load-in-query-hot-path`, `require-shared-plugin-json-schema-helper`, `no-broad-except-exception`, `no-core-storage-import`	Keep hot paths configuration-free, plugin schemas shared, exceptions narrow, and storage ownership explicit.
Determinism: `no-random-without-explicit-seed`	Reject implicit random behavior from reproducible production workflows.

Semgrep exceptions and exclusions¶

There is no repository .semgrepignore. Semgrep additionally honors the repository .gitignore for generated/cache paths. All repository-owned rule exclusions are rule-local; normal full-tree scans also pass --exclude fixtures because the checked-in fixture corpus intentionally violates every guardrail. Tests are excluded from production architecture rules because fixtures and contract tests intentionally import forbidden dependencies to prove a rule fires; each such rule has a dedicated violating fixture.

no-core-storage-import permits only the SQLite sqlite_storage.py and DuckDB repo_storage.py seams. They centralize the still-required core storage path/bootstrap delegation; remove each exclusion when that ownership is fully package-local.
no-sqlite3-outside-allowed-layers permits only the three SQLite backend modules and the SQLite vector-store module, which own the production SQLite schema and connections.
no-backend-package-import-outside-allowed-layers permits only the SQLite backend implementation/storage seams, the DuckDB backend/query seams, and the demonstration backend. The former import their package-local helpers; the latter intentionally teaches extension by composition.
no-backend-import-in-analyzers permits backend schema imports only. Schema constants are read-only analyzer metadata, not backend execution coupling.
Framework-registry nosemgrep comments suppress only external rules that misclassify Codira DB-API calls as SQLAlchemy/Django sinks. The SQLite and DuckDB backend modules own parameterized SQL execution; query-context calls use the active backend connection; the two formatted-query suppressions are trusted identifier construction inside backend-owned SQL. The DuckDB support benchmark dynamic-import suppression loads a locally selected backend-support module by trusted argument vector. These exceptions do not affect the repository-owned Semgrep rule set. DuckDB call-target naming now lives in a helper module without a suppression because it does not cross a response rendering boundary. DuckDB embedding payload construction is likewise package-local and has no noqa or nosemgrep exceptions. DuckDB bulk transport owns temporary CSV serialization and replacement-scan cleanup with no lint or Semgrep exceptions. DuckDB reference-scan persistence likewise has no lint or Semgrep exceptions. DuckDB index-state inspection has no lint or Semgrep exceptions. DuckDB reusable-embedding state loading has no lint or Semgrep exceptions, including orphan cleanup. DuckDB docstring-audit policy has no lint or Semgrep exceptions. DuckDB index-maintenance cleanup has no lint or Semgrep exceptions. DuckDB graph-rebuild lookup helpers have no lint or Semgrep exceptions. DuckDB graph-rebuild execution has no lint or Semgrep exceptions.

Affected sources are scripts/benchmark_index.py, src/codira/query/context.py, packages/codira-backend-sqlite/src/codira_backend_sqlite/__init__.py, packages/codira-backend-sqlite/src/codira_backend_sqlite/sqlite_support.py, packages/codira-backend-duckdb/src/codira_backend_duckdb/__init__.py, packages/codira-backend-duckdb/src/codira_backend_duckdb/duckdb_support.py, and packages/codira-backend-duckdb/src/codira_backend_duckdb/duckdb_query_backend.py.

Review outcome¶

The external stdio MCP handshake test skips only when Codex declares its network-disabled sandbox. Outside that constrained environment it retains the real child-process coverage and uses a bounded timeout so transport failures cannot leave an orphaned test server.

Slice 18 adds codira.arch.no-host-ast-in-python-analysis: after the completed host-target parser migration, a production ast import would silently violate the package-owned Tree-sitter boundary. Its dedicated fixture proves the rule fires while analyzer tests remain free to compare normalized output with the host parser.

Updated integration locations — 2026-10-01¶

scripts/agent_efficiency/oracles.py:152 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
scripts/agent_efficiency/oracles.py:822 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
scripts/agent_efficiency/oracles.py:933 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
scripts/agent_efficiency/oracles.py:1080 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
src/codira/cli.py:419 (E402): Compatibility imports retain their established initialization order.
src/codira/cli.py:424 (E402): Compatibility imports retain their established initialization order.
src/codira/cli.py:463 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
src/codira/cli_queries.py:2395 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
src/codira/mcp/server.py:272 (SLF001 - required SDK transport boundary): The MCP transport adapter requires the SDK private server boundary.
src/codira/query/context_scoring.py:638 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
src/codira/query/context_scoring.py:787 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.
src/codira/query/context_scoring.py:822 (PLR0913): Explicit query or evaluation inputs preserve the existing integration contract.

Native subscription preparation¶

scripts/agent_efficiency/codex_subscription.py:2: explicit boundary errors use direct diagnostic strings; account data is sanitized before persistence.
scripts/agent_efficiency/subscription_campaign.py:2: immutable scheduler and quota admission errors follow the existing campaign exception convention.
scripts/agent_efficiency/subscription_qualification.py:2: offline admission errors identify retained traces without embedding their contents.
scripts/calibrate_agent_efficiency_panel.py:2: generator errors identify inconsistent frozen calibration cases.
scripts/agent_efficiency/panel_patch_calibration.py:2: curated source-edit and admission errors identify the mismatched case without logging provider or credential data.

Mechanical campaign readiness¶

scripts/agent_efficiency/readiness.py:12, scripts/agent_efficiency/preparation.py:12, and scripts/agent_efficiency/native_tool_qualification.py:12 (EM101, EM102, TRY003): preparation boundary errors use concise public diagnostics, following the existing immutable campaign exception convention.
scripts/agent_efficiency/native_tool_qualification.py:240 (PLR0913): offline qualification keeps the exact runtime, image, workspace, evidence, model, reasoning and exposure bindings explicit rather than obtaining them from ambient state.
scripts/launch_agent_efficiency_pilot.py:1000 and scripts/launch_agent_efficiency_pilot.py:1010 (TRY301): CLI binding errors remain inside the common safe-rejection boundary and cannot reach preparation or launch side effects.
scripts/agent_efficiency/model_tool_qualification.py:12 (EM101, EM102, TRY003): the model canary uses explicit preparation boundary diagnostics and preserves full ignored native evidence.
scripts/agent_efficiency/preparation.py:390 (TRY301): retain a failed boundary record before propagating rejection; changed controls stop before model work.
scripts/agent_efficiency/preparation.py:396 (TRY301): retain a failed boundary record before propagating rejection; changed controls stop before model work.
scripts/run_agent_efficiency_phase6_pilot.py:1787 (PLR0913): readiness supplies an already indexed canary workspace to the same provider executor used by campaign attempts; ordinary attempts retain their original agent workspace.