Engineering Excellence: Enforcing the One Way (Anti-Slop)¶
Status: ACTIVE - first enforcement shipped (CLAUDE.md contract, file-size ratchet, JSON single-library gate). Additive to the Engineering Standards & Toolchain section. That section already owns the deep ratchets (mypy strict expansion, per-module coverage, parse-don't-validate, mutation testing, supply-chain hardening). This doc owns the net-new, enforcement-and-currency layer: keeping a largely AI-assisted codebase tidy, consistent, and current.
Motivation¶
The 2026 literature on AI-assisted development is consistent and unflattering: AI-assisted code ships roughly 2× the critical vulnerabilities of human-written code; about a third of those flaws originate in the model (replicated insecure training patterns); only ~35% of AI-generated backend code is both secure and correct; and the dominant maintainability failure is near-miss syndrome - plausible code with subtle bugs, inconsistent naming, duplicate logic, no coherent architecture, and outdated APIs / hallucinated packages. Sources: OX Security; Kiuwan; DevOps.com; arXiv 2409.19182 ("AI-Generated Code Considered Harmful"); OWASP Top 10 2025 (new A03 Software Supply Chain Failures, A10 Mishandling Exceptional Conditions).
The agreed mitigation is exactly primr's posture: treat generated code as hazardous until reviewed, statically scanned, and tested, behind hard policy-as-code gates. primr already has the gates (Ruff / mypy-ratchet / bandit / pip-audit / Trivy / SBOM / SLSA / coverage-ratchet / Hypothesis). What it lacks is (a) a contract that steers the generator before code is written, (b) enforcement of the single seams it has by convention, and (c) a currency cadence for the dev toolchain itself. This doc adds those.
Decision principle: make the one correct way the easy and enforced way; make slop fail a gate, not a review comment.
Where primr already stands (don't re-litigate)¶
Measured, not assumed. Already in place and load-bearing - see the ROADMAP
standards section for detail: uv.lock + uv sync --locked + 3.12/3.13/3.14
hard supported matrix plus a hard Linux 3.15 pre-release lane; Ruff (14 rule
groups, line-length 100, C901 budget 25); mypy
incremental strict allowlist; bandit + pip-audit + Trivy hard gates;
CycloneDX SBOM + SLSA provenance + OIDC publish per release; 81% branch
coverage ratchet (rise-only); Hypothesis property + stateful tests; SSRF guard
on every egress; secret-redaction log filter; injection red-team corpus;
scoped ATLAS threat model; single-version-truth test; no-real-company-data
rule; docs/design/ ADR convention. This is already top-decile. The work
below is the last mile, not a turnaround.
Net-new workstreams¶
1. AGENTS.md - the anti-slop contract (free) - SHIPPED¶
A dev-facing spec that every coding agent and human reads before contributing. The 2026 standard (agents.md; spec-driven development) is that the spec is the constraint the generator is held to, not documentation written after.
Why AGENTS.md, imported by CLAUDE.md (#264, October 2026). The
cross-tool open standard is AGENTS.md (native in Codex, Cursor, Copilot,
Windsurf, Gemini CLI). Claude Code reads CLAUDE.md and loads AGENTS.md
only when CLAUDE.md imports it with @AGENTS.md; a prose pointer or link
does not load it. The contract first lived in CLAUDE.md because the root
AGENTS.md was the operate-primr product guide. Two files with their own
rules drift, and the copy a given harness does not read goes stale, so the
contract now lives in the root AGENTS.md, CLAUDE.md is exactly
@AGENTS.md, and the operator guide moved to clients/primr-operator.md,
which users copy into their own workspace as AGENTS.md. Tool settings
(permissions, hooks) stay in each tool's configuration, not in prose.
Contents:
- The single seams, named, with their allowed exceptions: async via
utils.async_utils.run_sync(not rawasyncio.run); outbound HTTP via thedata.http_client/ scraping-tier seams (the 5 clients are a closed, documented set - browser → curl_cffi → httpx → requests → urllib - not an open invitation); config viaconfig/; console viautils.console; logging viautils.logging_config.get_logger; JSON via stdlibjsononly. - File-size rule: no new file ships over ~800 lines without a split plan; no existing file may grow (see workstream 3).
- Currency rule: before using a library/API, verify the current version and signature (the hallucinated-package / stale-API guard) - never trust the model's training memory for versions, deprecations, or model IDs.
- Verb convention (workstream 4) and the no-real-company-data rule.
- Pre-PR checklist: the local gate commands (already in CONTRIBUTING) plus "did this add a new way to do something that already has a seam?"
Validation: free - it is documentation that the fitness functions (workstream
2) then enforce, so it cannot rot into aspirational prose. SHIPPED as the
committed root contract, now AGENTS.md with a one-line CLAUDE.md import;
CONTRIBUTING points to it; a fitness test asserts that CLAUDE.md is exactly
@AGENTS.md, that AGENTS.md carries the contract sections, and that the
operator guide exists.
2. Architectural fitness functions (free) - PARTIALLY SHIPPED¶
Turn the single seams from convention into deterministic AST/scan tests
(tests/test_architecture.py) that fail CI on drift. Prefer the test approach
over adding an import-linter dependency (standing new-dependency policy).
- JSON single-library - SHIPPED. No
orjson/ujson/simplejsonimport may appear insrc/(stdlibjsononly). Zero current violations, so it is a clean zero-allowlist gate. - File-size ratchet - SHIPPED (workstream 3, below).
- Async seam - DEFERRED (needs burndown). Enforcing "no
asyncio.run/get_event_loopoutsideutils/async_utils" requires an allowlist of ~11 current sites; that is a burndown gate, not a clean one. Land it after the remaining inline event-loop copies finish migrating torun_syncso the allowlist is small and honest. - HTTP seam - NOT GATED (by design). The audit found raw HTTP clients in
~31 files: that is the intended multi-tier scraping design (browser →
curl_cffi → httpx → requests → urllib), not drift. A single-seam HTTP gate
would fight the architecture, so HTTP stays a documented convention in
CLAUDE.md(the client set is closed; a sixth client is a reviewed exception) rather than a hard gate. - Layer-boundary (config-as-leaf) - DEFERRED.
config/is nearly a leaf butconfig/eval_profiles.pyimportscore.model_eval. Gate it only after that one edge is resolved or explicitly allowlisted; until then it is aCLAUDE.mdrule ("don't add newcore/ai/dataimports toconfig/").
Validation: free; the shipped contracts are pure static checks, no paid calls.
3. Monster-file split ratchet (free to gate) - SHIPPED (ratchet)¶
The #23 refactor extracted perform_fast_research, but four files remain over
2,000 lines: core/research_agent.py (5,265), core/cli.py (4,276),
ai/deep_research.py (3,892), data/scraping/browsers.py (2,036), plus ~10
over 1,000. These are grandfathered, not fixed.
- Gate - SHIPPED: a rise-only per-file line ceiling in
tests/test_architecture.py- the 14 files over 1,000 lines are pinned at their current size and may not grow; any new file must stay under 1,000. Ceilings only ratchet down (a staleness test forces a ceiling to be lowered when a file shrinks). This stops the monsters from growing while splits proceed. - First split (remaining):
research_agent.py- it is also the coverage laggard (~30%), so splitting it serves the per-module coverage target in the standards section simultaneously. Mechanical now that the orchestrator is a thin coordinator; extract by responsibility (collection glue, strategy glue, doctor/utility) behind the existing injectable seams, no behavior change, eval scores unchanged.
Validation: the ratchet is free; each split is verified by the existing suite (no behavior change) - no paid run.
4. CLI verb convention (free, non-breaking)¶
The surface mixes subcommands (primr recon|keys|mcp|skills|update) with
flag-commands (--qa --eval --improve --refine --calibrate --roadmap) - the
"multiple ways to do the same kind of thing" smell, user-facing.
- Convention: noun/verb subcommands are canonical
(
primr <subcommand> [args] [--modifiers]); flags are modifiers, not commands. Document it inCLAUDE.md+ the CLI help. - Migration is non-breaking: new commands use the subcommand form; the existing flag-commands gain subcommand aliases over time while the flags stay as back-compat aliases (deprecation-noted, never removed in 1.x). No flag is broken.
Validation: free - a help-text/alias test pins both spellings dispatch identically.
5. Toolchain & API currency cadence (free)¶
primr already re-audits product model IDs ("Model landscape refresh"). The dev toolchain needs the same discipline, because the model writing the code has no reliable sense of "current." A standing checklist item per release cycle (fold into the existing "Release Cadence → harden lane"):
- Confirm pinned
ruff/mypy/uvagainst latest stable; bump by hand when a gate or this check flags it (no bot PRs, per standards). As of this writing: Ruff current (0.15.x line), mypy 2.x has shipped (primr targets 1.x - evaluate the bump), and Astraltyis beta, not GA (so the standards section's "evaluate, do not gate ontywhile preview" call is correct and stays). - Spot-check that any newly-used third-party API matches current docs (the workstream-1 currency rule, applied at review).
Validation: free - it is a review-cadence checklist, not code.
Exit criteria¶
CLAUDE.mdexists and names every single seam + the file-size, currency, and verb rules; CONTRIBUTING links it.- Fitness functions enforce the async and HTTP seams (CI fails on new drift).
- A rise-only per-file line-count ratchet is in CI; no monster file can grow;
research_agent.pyis split with coverage up and behavior unchanged. - The CLI verb convention is documented; new commands follow it; back-compat aliases are pinned by test.
- The release harden lane includes a dev-toolchain currency check.
Explicitly not¶
- Not a rewrite. No breaking CLI change, no dependency churn, no global
mypy
--strictflip, no blanket file-splitting sprint - everything is a rise-only ratchet or a non-breaking addition. - Not >95% coverage / NASA Power-of-10 literalism / Pydantic-everywhere / structlog-everywhere - already rejected in the standards section; this doc does not reopen them.
- Not a new linter stack. Ruff + mypy stay authoritative;
tystays an evaluate-only local supplement until GA; fitness functions prefer an AST test over a new dependency. - No bot-authored dependency PRs - currency stays manual review-and-bump.
- Not language purity and not a polyglot mandate. Python remains the
product-layer default. A native component or service is allowed only through
the measured gates in
runtime-language-boundaries.md; no line-by-line rewrite or duplicated cross-language business logic.