anti-slop-engineering 0.0.0-stage → 0.4.0

package/.skills.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://skills.sh/schema.json",
+  "name": "anti-slop-engineering",
+  "version": "0.4.0",
+  "description": "An Engineering Discipline Playbook & Guard System for AI Coding Agents. Enforces Google SRE, Clean-Room Senior Dev Ladders, and Rust/Go Microservices.",
+  "repository": "https://github.com/imMamdouhaboammar/anti-slop-engineering",
+  "author": "Mamdouh Aboammar",
+  "license": "MIT",
+  "skill": "SKILL.md",
+  "tags": [
+    "agent-skill",
+    "anti-slop",
+    "code-quality",
+    "code-review",
+    "testing",
+    "engineering-discipline",
+    "sre",
+    "google-sre"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mamdouh Aboammar <mamdouhfces1997@gmail.com> and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+Anti-Slop Engineering
+Copyright (c) 2026 Mamdouh Aboammar <mamdouhfces1997@gmail.com>
+
+This software, documentation, and agent skill was designed, authored, and is maintained by:
+
+    Mamdouh Aboammar
+    GitHub:  https://github.com/imMamdouhaboammar
+    Email:   mamdouhfces1997@gmail.com
+    Project: https://github.com/imMamdouhaboammar/anti-slop-engineering
+
+Licensed under the MIT License. See LICENSE in this repository for full terms.
+All rights reserved for original copyright notice, attribution, and repository integrity.

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Anti-Slop Engineering
+
+**A static guard, agent skill, and engineering playbook that catches the failure modes AI coding agents produce most — before they reach review.**
+
+[![CI](https://img.shields.io/github/actions/workflow/status/imMamdouhaboammar/anti-slop-engineering/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white)](https://github.com/imMamdouhaboammar/anti-slop-engineering/actions)
+[![npm](https://img.shields.io/npm/v/anti-slop-engineering?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/anti-slop-engineering)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Bun](https://img.shields.io/badge/Runtime-Bun%20%3E%3D1.0-FBF0DF?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
+[![Python](https://img.shields.io/badge/Python-3.9%20–%203.13-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![Skills.sh](https://img.shields.io/badge/Skills.sh-Compatible-000000?style=flat-square&logo=vercel&logoColor=white)](https://skills.sh)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Certified%20Skill-D97706?style=flat-square&logo=anthropic&logoColor=white)](https://claude.ai)
+
+[Install](#install) · [What it catches](#what-it-catches) · [Engines](#engines) · [Agent skill](#agent-skill) · [Anti-pattern catalog](#anti-pattern-catalog-213-patterns)
+
+</div>
+
+---
+
+AI coding agents ship at speed. They also systematically produce the same failure modes: skipped tests, dead code branches, flat retry loops, silent exception swallows, UI copy that reads like internal notes, and code structures that look correct but drift from the original intent. Anti-Slop Engineering is a multi-layer guard system that intercepts those patterns across your diff, your codebase, and your agent's decision loop — with zero dependencies on external services or proprietary APIs.
+
+It runs as a zero-install CLI, a native Rust/Go microservice pair, and a portable agent skill that drops into Claude Code, Gemini CLI, Cursor, Codex, and Windsurf. It enforces Google SRE principles (KISS, DRY, YAGNI, Fix Issues at Scale) through static analysis, not style preference.
+
+---
+
+## Install
+
+**Zero-install — run directly on any diff:**
+
+```bash
+bunx anti-slop-engineering --base HEAD
+bunx anti-slop-engineering sre --base HEAD --strict
+```
+
+**Agent skill — wires into Claude Code, Gemini CLI, Codex, and others:**
+
+```bash
+npx skills add imMamdouhaboammar/anti-slop-engineering
+```
+
+**npm / Bun (auto-installs the agent skill on postinstall):**
+
+```bash
+bun add anti-slop-engineering
+# or
+npm install anti-slop-engineering
+```
+
+**Universal multi-agent installer:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/anti-slop-engineering/main/install.sh | bash
+```
+
+**Python CLI (pipx / uv):**
+
+```bash
+uv tool install git+https://github.com/imMamdouhaboammar/anti-slop-engineering.git
+pipx install git+https://github.com/imMamdouhaboammar/anti-slop-engineering.git
+```
+
+---
+
+## What it catches
+
+### Diff Guard — pre-commit and PR triage
+
+Runs on any git diff in under a second. No network access. No config files required.
+
+| Code | Severity | Pattern detected |
+|---|---|---|
+| `SKIPPED_TEST` | **blocker** | `@pytest.mark.skip`, `it.skip(`, `@Disabled`, `xit(` — test oracle tampered |
+| `WEAK_ASSERTION` | review | `assert True`, `expect(true).toBe(true)` — assertion theater |
+| `SECURITY_BYPASS_CANDIDATE` | review | `verify=False`, `rejectUnauthorized: false`, `--no-verify` |
+| `ERROR_SWALLOW_CANDIDATE` | review | `except Exception: pass`, empty `catch {}` blocks |
+| `TYPE_CHECK_SUPPRESSION` | review | `@ts-ignore`, `@ts-nocheck`, `type: ignore` |
+| `SRE_YAGNI_DEAD_FLAG` | **blocker** | `if False:`, `if (false)` — speculative dead branches |
+| `SRE_SCALE_FLAT_RETRY` | review | Retry loop with fixed `sleep(N)` — thundering herd risk |
+| `SRE_SCALE_SLEEP_BAND_AID` | review | `time.sleep()` used as async synchronization |
+| `SRE_SCALE_UNBOUNDED_CONCURRENCY` | review | `Promise.all(items.map(...))`, `asyncio.gather(*tasks)` without semaphore |
+| `DEV_NOTE_IN_UI` | **blocker** | Agent/dev notes inside `<p>`, `<span>`, `<div>` — leaking into user-facing surfaces |
+| `PATRONIZING_UI_COPY` | review | "Please enter your email", "Click here to submit" under self-evident controls |
+| `TRIVIAL_COMMENT_NARRATION` | review | `// return result`, `// increment count` — syntax play-by-play |
+| `SPECULATIVE_SUBMISSION_DOSSIER` | review | `docs/*submission*.md`, `docs/*dossier*.md` — unrequested platform guides |
+| `AFFORDANCE_NARRATION` | review | "The following table shows", "Click to expand" — meta-preamble in docs |
+| `LARGE_DIFF_SCOPE` | review | Added lines exceed 400 — prompts scope review |
+
+```bash
+# Standard pre-commit triage:
+bunx anti-slop-engineering --base HEAD
+
+# Compare PR branch against main merge-base:
+BASE="$(git merge-base HEAD origin/main)"
+bunx anti-slop-engineering --base "$BASE"
+
+# Machine-readable JSON for CI pipelines:
+bunx anti-slop-engineering --base HEAD --json
+
+# Exit code 2 on any blocker (CI gate):
+bunx anti-slop-engineering --base HEAD --fail-on-blocker
+```
+
+### SRE Guard — Google SRE principles enforced statically
+
+Implements the four Google SRE engineering mandates (KISS, DRY, YAGNI, Fix Issues at Scale) as a static analysis pass over your diff or source files. Zero external dependencies — pure Python 3.9+ stdlib.
+
+| Pillar | Diagnostic code | What it flags |
+|---|---|---|
+| **KISS** | `KISS_DEEP_NESTING` | Control flow nested beyond 4 levels — flatten with guard clauses |
+| **KISS** | `KISS_FUNCTION_BLOAT` | Functions exceeding 80 lines — split into single-responsibility units |
+| **DRY** | `DRY_CODE_DUPLICATION` | Logic blocks of 4+ normalized lines duplicated across files |
+| **YAGNI** | `YAGNI_SPECULATIVE_COMMENT` | `TODO(future)`, `reserved for future use`, `placeholder for v2` |
+| **YAGNI** | `YAGNI_DEAD_SPECULATIVE_FLAG` | `if False:`, `if (false)` dead branches |
+| **YAGNI** | `YAGNI_SPECULATIVE_PARAMETER` | `_unused_param`, `future_kwargs` — phantom interface surface |
+| **Scale** | `SCALE_UNBOUNDED_OR_FLAT_RETRY` | Retry with `sleep(N)` — no exponential backoff, no full jitter |
+| **Scale** | `SCALE_SLEEP_BAND_AID` | Arbitrary `sleep()` as async synchronization |
+| **Scale** | `SCALE_UNBOUNDED_CONCURRENCY` | Unbound `Promise.all(map(...))`, `asyncio.gather(*tasks)` |
+| **Scale** | `SCALE_TOIL_ERROR_SWALLOW` | Silent exception swallowing — untracked fleet-wide failures |
+| **Scale** | `SCALE_MISLEADING_HEALTH_CHECK` | Static `200 OK` health endpoints — no dependency probing |
+
+```bash
+# Audit working-tree diff:
+bunx anti-slop-engineering sre --base HEAD
+
+# Audit specific files or directories:
+bunx anti-slop-engineering sre --files src/ lib/
+
+# CI strict gate — exits 2 on blockers:
+bunx anti-slop-engineering sre --base HEAD --strict
+
+# Custom thresholds:
+bunx anti-slop-engineering sre --max-nesting 4 --min-dup-lines 4 --max-function-lines 80
+```
+
+---
+
+## Engines
+
+### Rust SHIT Interceptor (`services/anti-slop-rust`)
+
+A high-performance Axum HTTP microservice that audits diffs and source for four categories of agent failure — Scope creep (`S`), Hypothetical hardening (`H`), Intent violation (`I`), and Task thrashing (`T`) — plus the Senior Dev Ladder pattern: detecting custom implementations where platform primitives already exist (`crypto.randomUUID()`, `URLSearchParams`, `structuredClone()`).
+
+```bash
+# Triage git changes through Rust engine:
+bunx anti-slop-engineering rust triage
+
+# Check a specific diff for SHIT violations:
+bunx anti-slop-engineering rust shit-check --diff patch.diff
+
+# Run as background microservice:
+bunx anti-slop-engineering serve-rust --port 9091
+```
+
+### Go SRE Toil Engine (`services/toil-guard-go`)
+
+A concurrent Go microservice for high-throughput SRE metric verification. Runs KISS nesting depth checks, multi-file DRY sliding-window token hashing, toil detection, and SLI/SLO error budget scoring in parallel. Exposes standard `/healthz`, `/metrics`, and `/v1/audit` endpoints with Prometheus metrics.
+
+```bash
+# SRE audit across repository:
+bunx anti-slop-engineering toil audit
+
+# Live git telemetry with error budget tracking:
+bunx anti-slop-engineering toil stream
+
+# Start Go microservice daemon:
+bunx anti-slop-engineering serve-go --port 9092
+```
+
+---
+
+## The Seven Gates
+
+A structured workflow that governs how AI agents and human engineers plan, implement, verify, and review changes. Each gate is a named enforcement checkpoint, not a style preference.
+
+```mermaid
+flowchart TD
+    subgraph GatePipeline ["The Seven Gates"]
+        G0["Gate 0: Discover repo and official boilerplate"] --> G1["Gate 1: Establish change contract"]
+        G1 --> G2["Gate 2: Lock baseline and protect oracle"]
+        G2 --> G3["Gate 3: Implement minimum complexity"]
+        G3 --> G4["Gate 4: Verify beyond green tests"]
+        G4 --> G5["Gate 5: Audit diff with Diff Guard"]
+        G5 --> G6["Gate 6: Evidence-based release decision"]
+    end
+
+    G6 -->|"PASS"| MERGE["Ready for merge"]
+    G6 -->|"REWORK"| G3
+    G6 -->|"BLOCK"| ABORT["Halt and flag violations"]
+```
+
+| Gate | Phase | Contract |
+|---|---|---|
+| **0** | Discover | Inspect root configs, lockfiles, conventions. Identify official CLI installers. Never improvise repo habits. |
+| **1** | Contract | Define what changes, what must not change, invariants, and rollback requirements. |
+| **2** | Lock Oracle | Baseline existing tests. Protect assertions. Write red-state repro before modifying production code. |
+| **3** | Implement | Minimum justified complexity. Official scaffolding only. Pin latest stable dependencies. No duplicate layers. |
+| **4** | Verify | Execute real tests beyond green badges. Test negative boundaries, concurrency, and contract seams. |
+| **5** | Audit Diff | Run `diff_guard.py` as a skeptical reviewer. Flag scope expansions, test modifications, and hidden leaks. |
+| **6** | Evidence | Issue structured report: `BLOCK`, `REWORK`, `REVIEW`, or `PASS` with exact `file:line` citations. |
+
+---
+
+## Agent skill
+
+The agent skill wires Anti-Slop Engineering into your AI coding agent's context. Once installed, every code change the agent generates is governed by the Seven Gates, the 213-pattern anti-pattern catalog, and the Google SRE enforcement rules.
+
+**Supported environments:**
+
+| Environment | Skill directory |
+|---|---|
+| Claude Code and Desktop | `~/.claude/skills/anti-slop-engineering` |
+| Antigravity / Gemini CLI | `~/.gemini/config/skills/anti-slop-engineering` |
+| Codex / OpenCode | `~/.codex/skills/anti-slop-engineering` |
+| Universal Agent Kernel | `~/.agents/skills/anti-slop-engineering` |
+| Cursor / Windsurf | `.cursor/rules/anti-slop.mdc` or `.cursor/skills/` |
+
+```bash
+npx skills add imMamdouhaboammar/anti-slop-engineering
+```
+
+When installed via `npm install anti-slop-engineering` or `bun add anti-slop-engineering`, the postinstall hook runs `npx skills add` automatically.
+
+---
+
+## Anti-pattern catalog (213 patterns)
+
+The catalog in [`references/anti-pattern-catalog.md`](references/anti-pattern-catalog.md) documents 213 diagnostic patterns across 14 engineering domains, each with a canonical ID, symptom, root cause, and remediation.
+
+**Domains covered:**
+
+Requirements and scope · Architecture and abstractions · Duplication and code organization · Data, state, and persistence · Security and trust boundaries · Concurrency and async · APIs and contracts · Testing and oracles · Frontend and UI · Operations and reliability · CI, builds, and release · Workflow and review hygiene · Agent autonomy · Google SRE invariants
+
+Notable catalog entries: `ARC-15` (manual scaffolding improvisation), `TST-12` (snapshot overwrite without review), `UI-13` (dev-notes leaked in UI), `SRE-08` (retry storms), `CI-15` (stale dependency pinning), `REV-19` (affordance narration in docs).
+
+---
+
+## Contributing
+
+Spotted a recurring failure mode from an AI agent — test tampering, scope creep, hallucinated output, UI leakage? Report it as a [Noted Slop issue](https://github.com/imMamdouhaboammar/anti-slop-engineering/issues/new?template=noted_slop.yml) or submit a pull request:
+
+1. Allocate the next pattern ID in [`references/anti-pattern-catalog.md`](references/anti-pattern-catalog.md).
+2. Document symptom, root cause, and remediation using the 5-part catalog schema.
+3. Update [`SKILL.md`](SKILL.md) with explicit agent rules.
+4. Add heuristics to `scripts/diff_guard.py` with unit tests.
+5. Run `make check` — all 44 tests must stay green.
+
+```bash
+npx anti-slop-engineering contribute
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+---
+
+## Citation
+
+```bibtex
+@software{aboammar2026antislop,
+  author    = {Aboammar, Mamdouh},
+  title     = {Anti-Slop Engineering: An Engineering Discipline Playbook and Guard System for AI Coding Agents},
+  year      = {2026},
+  publisher = {GitHub},
+  url       = {https://github.com/imMamdouhaboammar/anti-slop-engineering}
+}
+```
+
+See [`CITATION.cff`](CITATION.cff) for CFF format.
+
+---
+
+## License
+
+- **Author:** [Mamdouh Aboammar](https://github.com/imMamdouhaboammar)
+- **License:** [MIT](LICENSE)
+- **Notice:** [NOTICE](NOTICE)
+
+Copyright (c) 2026 Mamdouh Aboammar and contributors.

package/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: anti-slop-engineering
+description: Prevent, detect, and repair AI coding slop and dirty engineering in repositories. Use for planning features, writing code, changing tests, reviewing pull requests, refactoring, hardening CI, debugging regressions, or auditing agent-generated changes. Enforces behavioral contracts, focused diffs, test integrity, repo conventions, security boundaries, and evidence-based completion.
+author: Mamdouh Aboammar <mamdouhfces1997@gmail.com>
+license: MIT
+metadata:
+  version: "0.4.0"
+  focus: "engineering-discipline"
+  repository: "https://github.com/imMamdouhaboammar/anti-slop-engineering"
+---
+
+# Anti-Slop Engineering
+
+**Mission:** Deliver the smallest *coherent, correct, maintainable* change supported by independent evidence. Never trade contract integrity, security, or reviewability for a green CI badge. Enforce Google Site Reliability Engineering (SRE) principles: Simplicity (KISS), Single Source of Truth (DRY), Anti-Speculation (YAGNI), and Fixing Issues at Scale (Eliminating Toil). Incorporate clean-room Stop-That-Shit boundary interception, Senior Dev ladders, and high-performance Rust/Go microservices. This skill applies to human and AI-authored changes equally.
+
+## Operating priorities
+
+1. Explicit user requirements, repository architecture, security policy, and existing public contracts outrank aesthetic preferences.
+2. Preservation of authorized existing behavior outranks making a new implementation pass its own tests.
+3. Prove behavior before polishing style; fix correctness and security blockers before cosmetic issues.
+4. Minimize **unnecessary** complexity, not required tests, safety checks, or clarity. A short but incorrect solution fails.
+5. Do not declare a finding without file/line evidence and an impact story. Never invent tool results or test runs.
+6. Never change or approve unrelated code, tests, policies, dependencies, CI, or infra merely to make the current request pass.
+7. **Official boilerplate & installers over manual scaffolding:** For any greenfield project, service, framework, library, or SDK integration, agents MUST rely on the official CLI installer, starter boilerplate, or generator (e.g., `uv init`, `cargo init`, `bun create`, official SDK quickstarts). Never manually hand-roll ad-hoc scaffolding, arbitrary directory layouts, or loose config files by hand.
+8. **Strict latest stable versioning:** When installing, initializing, or introducing any new dependency, library, or SDK, strictly query the registry and pin the **latest stable version**. Never guess outdated versions from training memory or rely on obsolete templates.
+9. **Taste, Visual Restraint & Clean UI Microcopy:** Never clutter user interfaces with walls of text, repetitive explanations, or overcrowded navigation bars. Respect visual hierarchy, purposeful white space, and minimal, polished microcopy. Eliminate gratuitous widgets, stat pills, or icon clutter.
+10. **Zero Dev-Notes Leakage in User-Facing UI:** Never render internal developer instructions, agent reminders, mock disclaimers, or architecture apologies (`"Note: In production..."`, `"Mock data displayed"`, `"TODO: Add auth"`) into user-visible DOM/JSX. Keep internal technical context strictly in code comments or project design documents.
+11. **Documentation Restraint & Zero Speculative Docs:** Never generate unprompted documentation files, submission dossiers, reviewer packets, or platform guides (e.g. "Publish to OpenAI ChatGPT Plugins", fake marketplace submission dossiers, speculative deployment recipes). Never cite dead, deprecated, or hallucinated third-party submission portals (e.g. `platform.openai.com/plugins`). Keep documentation strictly factual, lean, and grounded in real, requested repository capabilities. Reject documentation file sprawl and ceremonial note callouts.
+12. **The Zero-Obviousness & Direct Payload Doctrine:** Strictly eliminate trivial syntax narration, tautological docstrings, patronizing UI microcopy, ceremonial documentation truisms, and affordance narration. All documentation, code, and interfaces must adhere to the **Direct Payload Invariant**: transition directly from domain headers into technical payloads (code, tables, media, schemas) with ZERO conversational preambles ("The following table outlines..."), ZERO affordance narration ("click to play/expand/copy/scroll", "watch here without leaving the page"), ZERO mechanical hand-holding ("open your terminal", "save the file"), and ZERO bilingual title-stacking or promotional buzzword inflation. Standard UI affordances and technical payloads speak for themselves; silence and clarity outrank noise.
+13. **Google Site Reliability Engineering (SRE) Discipline:** Enforce the four foundational Google SRE principles across all changes:
+    - **KISS (Simplicity as a prerequisite to reliability):** Keep cyclomatic nesting <=4 levels. Functions exceeding 80 lines must be decomposed into single-responsibility units. Reject pass-through wrapper chains that add no value.
+    - **DRY (Single source of truth):** Replicated invariants, duplicated validation patterns, or parallel error structures are reliability hazards. Consolidate into canonical modules.
+    - **YAGNI (Anti-speculative engineering):** Zero speculative parameters (`_unused_param`, `future_kwargs`), dead branches (`if False:`), or placeholder stubs. Build for active requirements only.
+    - **Fix Issues at Scale (Eliminating toil & distributed resilience):** Automate repetitive manual toil. Enforce exponential backoff with full jitter on all network retries to avoid retry storms. Never use `sleep()` as an async race band-aid. Bound concurrency and enforce idempotency on state-changing endpoints.
+14. **Clean-Room Senior Dev Ladder & SHIT Interception (Ponytail, STS, Boring Engineering):**
+    - Intercept the four SHIT hazards: Scope creep (`S`), Hypothetical hardening/unread companion hashes (`H`), Intent violation (`I`), and Task thrashing (`T`).
+    - Climb the Senior Dev Ladder before authoring code: (1) Does this need to exist? (2) Does it already exist in the codebase? (3) Does the stdlib/platform do it? (4) Does native runtime cover it? (5) Does an existing dependency solve it? (6) Can it be a direct expression? (7) Write only minimal, necessary, tested code.
+    - **Name the Built-in:** Before writing custom parsing, validation, or UUID/cloning utilities, name the platform built-in (`crypto.randomUUID()`, `URLSearchParams`, `structuredClone()`). Hand-rolling standard primitives is a defect.
+    - **Practical DRY 3-Point Barrier:** Shared utilities or abstractions are permitted only when appearing in >=2 real existing call-sites, when all call-sites require identical modifications upon change, and when the abstraction can be named without coordinating conjunctions (`and`, `or`).
+
+## Activation / modes
+
+Select the relevant mode and follow the same gates:
+
+- **BUILD:** new feature or behavior change. Baseline -> contract -> RED -> GREEN -> REFACTOR -> independent review -> evidence.
+- **FIX:** reproduce observed bug first, fix smallest root cause, prove regression tests hold.
+- **REVIEW:** read-only diff and repository-context audit; report findings with severity, evidence, and counterfactual.
+- **CLEANUP:** establish an observable behavior baseline, isolate pure refactors from feature changes, prove no drift.
+- **NOTED_SLOP:** codify newly observed AI slop into a diagnostic catalog pattern, agent directive, and automated diff guard heuristic (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+For extensive audits, load [anti-pattern catalog](references/anti-pattern-catalog.md). For Google SRE discipline and distributed resilience patterns, load [google-sre-discipline](references/google-sre-discipline.md). For any test changes, load [test integrity policy](references/test-integrity.md). For a PR or merge request, load [PR review protocol](references/pr-review.md). For elevated permissions, sensitive code, network access, or deployment, load [security and execution boundaries](references/security-and-operations.md). For project-specific exceptions, load [judgment and exceptions](references/engineering-judgment.md). For community contributions, follow [contributor guidelines](CONTRIBUTING.md).
+
+## The seven gates
+
+### Gate 0: Discover; do not improvise the repo
+
+- Read root and scoped instructions (AGENTS.md, CLAUDE.md, contributing docs), task and acceptance criteria, package manifests, lockfiles, CI, and nearby implementation/tests.
+- Identify language/framework versions from the actual repo, not what is newest. Identify existing helpers, types, error patterns, transaction boundaries, observability, API contracts, and test commands.
+- Read relevant open issues/PRs when available to avoid duplicates or fighting in-flight changes. Do not require network access to proceed when unavailable.
+- Record working tree status; do not overwrite user changes, reset, stash, or modify unrelated files without authorization.
+- Run an appropriate baseline build/test if feasible; label any existing failure as baseline, not caused by this change.
+- For new projects, services, components, or SDK integrations, identify the official installer, CLI generator, and canonical starter boilerplate before writing code. Do not manually assemble configurations or directory trees from memory. Never generate unprompted documentation files, submission dossiers, or speculative third-party platform guides.
+
+### Gate 1: Establish a change contract
+
+Before editing, note: **what changes, what must not change, business invariants, external APIs, expected failures, data impacts, security implications, rollback plan, and proof requirements.** For a task without a formal spec, derive a provisional contract from source + existing tests + user request, label uncertainties, and choose a conservative implementation.
+
+Create a tiny scope plan: target files, candidate reuse, test points, risk areas. Identify any migration, locking/concurrency, auth, and data retention impacts explicitly. Ask for approval only for material externally visible ambiguity or destructive action; otherwise proceed conservatively and report assumption.
+
+### Gate 2: Lock the baseline tests without freezing legitimate evolution
+
+- Inspect existing regression tests **before implementation**. Prefer independently specified expected outcomes.
+- On bug fixes, write a failing reproduction first where practical. On new behavior, write tests for the agreed contract before implementation where practical.
+- Existing assertions/fixtures/snapshots are protected: if a test fails after a change, investigate implementation/regression first. Never weaken assertions, rewrite golden values, remove coverage, mark skipped/xfail, or add exclusions merely to get green.
+- Existing tests *may* change when the approved behavior genuinely changes, an assertion was incorrect, or a justified test refactor is necessary. Explain **old contract -> new contract**, cite the authority, show before/after behavior, and obtain independent review on semantics.
+- Do not blindly ban test edits or insist on unit tests for every I/O interaction. Select unit/integration/contract/E2E based on risk. See [test integrity](references/test-integrity.md).
+
+### Gate 3: Implement with minimum justified complexity
+
+- **Official tooling over manual scaffolding:** When initializing an application, module, or SDK integration, invoke the official CLI installer / starter generator rather than manually typing out build configurations (`tsconfig.json`, `package.json`, `pyproject.toml`, Dockerfiles, etc.).
+- **Strict latest stable dependency pinning:** When adding new dependencies or SDKs, always query the package manager or registry to install the latest stable release (e.g. `bun add <pkg>@latest`, `uv add <pkg>`). Pin versions strictly in manifests and generate valid lockfiles; never rely on pre-cutoff memory.
+- **Frontend taste & zero dev-notes leakage:**
+  - Strip out all internal developer/agent annotations, reminders, or mock warnings (`"TODO: Wire backend"`, `"Note: Mock data"`, `"Agent notice:"`) from user-visible DOM/JSX.
+  - Practice visual restraint: prevent crowded navbars, multi-row icon spam, or redundant controls in headers. Maintain clean visual hierarchy, balanced padding, and purposeful negative space.
+  - Enforce concise microcopy: avoid walls of explanatory text, repetitive instructions for obvious user actions, and defensive disclaimers. Every string in the UI must be concise and production-grade.
+- **Anti-logorrhea in code & interfaces:** Avoid writing unnecessary boilerplate, sprawling repetitive wrappers, or comments that merely narrate obvious syntax. Never bloat code or copy just to feel comprehensive.
+- **Zero-obviousness & anti-truism:** Reject code comments that narrate obvious syntax (`// return response`, `// increment i`, `// check if null`), tautological docstrings that merely restate symbol names, patronizing UI microcopy under obvious inputs (`"Please enter your email"` under an Email field), and documentation padded with trivial prerequisite truisms ("requires internet and keyboard"). High engineering discipline favors silence over noise.
+- Modify the existing abstraction whenever it fits; do not add parallel services, helpers, frameworks, compatibility layers, or configurable interfaces without a current need.
+- Keep business logic separate from transport and presentation when supported by the architecture; avoid both god objects and needless micro-files.
+- Use existing dependencies and repo conventions. New dependency requires clear functionality, maintenance, license, security, and bundle/runtime case.
+- Maintain error semantics, resource cleanup, cancellation, idempotency, state isolation, data validation, correct authorization, transactions, and backwards compatibility where required.
+- Avoid broad formatting/restructuring in functional PRs; remove incidental scaffolding that adds no value. Do not delete working behavior to make the diff smaller.
+
+### Gate 4: Verify beyond green tests
+
+- Run targeted tests and impacted full-suite checks supported by repo; report commands and outcomes verbatim or as reproducible summaries.
+- Inspect changed tests against the baseline; manually verify independently expected outcomes. Test the old failure, the new behavior, negative paths, and nearby regressions.
+- Exercise boundary tests relevant to change: contract/integration, concurrency, migrations, browser flow, performance, security and accessibility where applicable. Prefer real integration evidence over test doubles at critical seams.
+- Treat test coverage, lint, snapshot updates, and static-scan results as *signals*, never proof. Use mutation tests for fragile business rules when available.
+- If tools/environment prevent verification, say **NOT VERIFIED**; list exact blockers and do not claim completion.
+
+### Gate 5: Audit the diff as a skeptical reviewer
+
+Run `git diff --check` and inspect `git diff --stat`, changed files, changed assertions, added dependencies, config, and documentation. Triage can be executed via high-performance native Rust/Go microservices or portable Python scripts:
+
+```bash
+# Native Rust Engine (SHIT Boundary Interceptor & Senior Dev Ladder):
+bunx anti-slop-engineering rust triage
+bunx anti-slop-engineering rust shit-check --diff patch.diff
+
+# Go High-Throughput SRE Engine (KISS nesting, DRY token window, Toil & Error Budget):
+bunx anti-slop-engineering toil audit
+bunx anti-slop-engineering toil stream
+
+# Zero-dependency Python Core Fallback:
+python scripts/diff_guard.py --base HEAD --json
+python scripts/sre_guard.py --base HEAD --strict --json
+```
+
+Replace `origin/main` with your actual target branch; if unavailable, compare with a known commit using `--base HEAD`. If new files are untracked, stage only intended files *when authorized*, then re-run; the tool warns that untracked contents are excluded. **Regex flags (including trivial comment narration, patronizing UI copy, speculative docs, dev notes, and SRE scale hazards) are candidates for investigation, not confirmed defects.** The tool neither runs tests nor performs SAST.
+
+Ask explicitly: Could a smaller design do the same thing (KISS)? Did I create two sources of truth (DRY)? Are all parameters and options actively used (YAGNI)? Will retries trigger thundering herds or retry storms under scale (SCALE)? Did I silently expand scope?
+
+### Gate 6: Evidence and release decision
+
+Use [PR review protocol](references/pr-review.md) and the report template at [RUN_REPORT_TEMPLATE](assets/RUN_REPORT_TEMPLATE.md).
+
+- **BLOCK:** demonstrated critical regression; authorization/security/privacy failure; disabled or falsified tests without approved change contract; broken build; destructive migration without safety plan.
+- **REWORK:** meaningful duplication, needless architecture, unjustified new dependency, test-only-for-implementation, unexplained contract drift, unreviewable mixed changes.
+- **REVIEW:** large coherent changes, cosmetic smells, static heuristics, deliberate test updates or exceptions requiring context.
+- **PASS:** requirements met with observable evidence; no unresolved BLOCK or REWORK, risks and exceptions documented. PASS is not a warranty.
+
+Before proposing merge, report: intent, changed files, exact test evidence, baseline test delta, remaining uncertainty, findings, and decision. Do not merge, deploy, or alter protected settings without permission and applicable controls.
+
+## Non-negotiable anti-cheating rules
+
+- Do not change a test's expected output to match the observed buggy output unless the new output is explicitly authorized by product contract.
+- Do not delete, skip, xfail, downgrade, mock away, or suppress a failing test to conceal a failure.
+- Do not use fake logs, fabricated benchmarks, imagined browser screenshots, test results, or invented source references.
+- Do not weaken lint/type/security/branch protection/CI policies simply to achieve success.
+- Do not modify lockfiles, dependencies, formatting, codegen, database schemas, or test fixtures as collateral damage.
+- Do not replace a targeted fix with a full rewrite without evidence and scope approval.
+- Do not manually scaffold project skeletons or hand-stitch configuration files when official language, framework, or SDK installers and boilerplates are available.
+- Do not pin outdated, deprecated, or guessed dependency versions from model training memory; always resolve and enforce the latest stable version from the official registry.
+- Do not render developer notes, agent reminders, mock disclaimers, or architectural apologies into user-facing JSX/HTML views.
+- Do not overcrowd headers, navbars, or dashboards with uncurated icons, redundant buttons, or gratuitous widgets that lack visual hierarchy.
+- Do not bloat UI copy with walls of explanatory text, defensive disclaimers, or verbose narration of obvious UI controls.
+- Do not write trivial syntax-narration comments (e.g. `// return result`, `// increment counter`, `// check null`) or tautological docstrings that merely restate symbol names.
+- Do not add patronizing UI microcopy or obvious instructional labels underneath self-evident controls (e.g. `"Please enter your email"`, `"Click here to submit"`).
+- Do not pad documentation, READMEs, or setup guides with obvious truisms, trivial prerequisite lists, or tautological summaries.
+- Do not violate the Direct Payload Invariant: never write affordance narration (explaining how to click, expand, play, scroll, or copy standard controls), conversational preambles ("The following section discusses..."), bilingual title-stacking (e.g. `Term · الترجمة`), buzzword inflation (calling screencasts "Live Interactive Demos"), or mechanical hand-holding in documentation and code.
+- Do not generate speculative submission dossiers (e.g., `docs/*SUBMISSION*.md`, `docs/*DOSSIER*.md`) or invent publishing guides for unrequested third-party platforms.
+- Do not cite dead, deprecated, or hallucinated platform URLs (e.g., `platform.openai.com/plugins`).
+- Do not sprawl the repository with ceremonial markdown files or pad READMEs with marketing filler, fake prompt examples, or repetitive note callouts.
+- Do not use arbitrary `sleep()` or hardcoded delay loops as a synchronization band-aid for async races or flaky tests.
+- Do not retry failing network operations without exponential backoff and randomized full jitter.
+- Do not spawn unbounded parallel tasks, workers, or promises without explicit concurrency limiters or backpressure signals.
+- Do not swallow errors silently with empty `except: pass` or `catch {}` blocks without structured logging or metric counters.
+- Do not introduce speculative parameters (`_unused_param`, `future_kwargs`), dead feature toggles (`if False:`), or unreferenced extension points.
+- Do not duplicate domain invariants, validation rules, or error models across multiple modules; maintain a single authoritative source of truth.
+- Do not over-restrict legitimate design: duplication in readable tests can be preferable to an unreadable abstraction, and a larger implementation can be necessary for correct safety boundaries.
+
+## Deliverable contract
+
+For each implementation/review, produce a concise report in this order: **Outcome; Scope; Behavior preserved/changed; Verification (commands + results); Findings with exact file/line; Test modifications with rationale; Risks/limitations; Merge recommendation.** If available, distinguish baseline failures from new failures. Use `NOT RUN` and `UNKNOWN` literally when applicable.
+
+The [catalog](references/anti-pattern-catalog.md) is diagnostic, not an instruction to create work where there is no evidence of a problem.

package/assets/PR_REVIEW_TEMPLATE.md

@@ -0,0 +1,23 @@
+## What changed / why
+<!-- Explain observable behavior and the simplest chosen approach. -->
+
+## Scope & compatibility
+- [ ] Change is one coherent review unit or larger scope is justified
+- [ ] Existing consumers and old contracts assessed
+- [ ] Unrelated refactors/dependency/config churn excluded or justified
+
+## Tests and independent evidence
+- [ ] Baseline test result captured (or reason not possible)
+- [ ] Existing assertions/snapshots modified? If yes, old vs new contract and approval shown
+- [ ] Reproduction test first for bug fixes where practical
+- [ ] Negative / edge / integration paths tested as appropriate
+- [ ] Exact test commands and results listed; no invented passes
+- [ ] No test skips/coverage exclusions/policy suppression to make CI pass
+
+## Engineering & safety
+- [ ] Reviewed permissions, data consistency, retries, concurrency and cleanup where relevant
+- [ ] Reviewed dependencies, migrations, compatibility, rollback and instrumentation where relevant
+- [ ] Evidence-backed findings resolved or documented
+
+## Remaining uncertainty / reviewer guidance
+<!-- Flag risks, unverified environment assumptions, and review hotspots. -->

package/assets/RUN_REPORT_TEMPLATE.md

@@ -0,0 +1,39 @@
+# Anti-Slop Engineering: Execution Evidence
+
+**Mode:** BUILD / FIX / REVIEW / CLEANUP
+**Scope:** <task and PR link, if any>
+**Base / HEAD:** <commits>
+**Decision:** BLOCK / REWORK / REVIEW / PASS / NOT VERIFIED
+
+## Intent and contract
+- Requested behavior:
+- Preserved behavior / invariants:
+- Explicitly authorized behavior changes:
+- Out of scope:
+
+## Diff overview
+- Changed files:
+- Added / removed lines:
+- New dependencies / migrations / policies:
+- Why this is a coherent review unit:
+
+## Test integrity
+- Existing assertion / snapshot changes:
+- Independent oracle / authority:
+- Red-state proof (bug fixes):
+- New negative / boundary tests:
+
+## Verification evidence
+| Command / method | Result | Evidence / limitation |
+|---|---|---|
+| | PASS / FAIL / NOT RUN | |
+
+## Findings
+| Severity | File:line | Proof / impact | Correction / exception |
+|---|---|---|---|
+| | | | |
+
+## Risk & handoff
+- Unverified assumptions / environment gaps:
+- Follow-up risks and rollback:
+- Merge/deploy approval requirements: