Agent-Proof AGENTS.md

AGENTS.md — Multi-Agent Development & Mechanical Governance Protocol

Welcome to Agent-Proof (@heretek-ai/agent-proof). This document establishes the multi-agent operational standards, mechanical hard-gate execution rules, and architecture guidelines for autonomous AI coding agents operating within this repository.

🎯 Primary Directives for AI Agents

1. Deterministic Mechanical Governance Over Soft Prompts:

   • Never attempt to bypass, disable, or modify mechanical hard gates (lefthook.yml, .claude/hooks.json, biome.json, ruff.toml, .aislop/config.yml).
   • Governance files are intentionally locked with read-only permissions (chmod 0444). Do not attempt to overwrite or change their permissions unless explicitly instructed by a human administrator.
   • Never bypass git hooks with git commit --no-verify. All commits must pass mechanical pre-commit validation in < 2.0s.

2. Proof-Loop Role Separation & Specification Freezing:

   • When acting in the Builder role, all test suites (tests/**, __tests__/**), specifications (spec.md), and acceptance criteria are frozen.
   • Modifying test assertions to force failing code to pass is strictly blocked by ByteFence with SPEC_TEST_FROZEN.

3. Zero-Tolerance for AI Slop & Unsafe Casting:

   • No Empty Catch Blocks / Swallowed Errors: Always handle exceptions explicitly, log with context, rethrow with cause (new Error(msg, { cause: err })), or return explicit typed failure results.
   • Strict Type Safety: Avoid as any or unchecked type assertions. Use TypeScript type guards, interfaces, or validated schemas (e.g. Zod).
   • No Hallucinated Imports: Only import from installed packages declared in package.json / pyproject.toml or verified relative paths within the project.
   • Clean ASTs & Formatting: Ensure code adheres to Biome / Ruff formatting standards without lint violations or dead code.

4. Strict Suppression Hygiene Protocol:

   • Never insert blind suppression comments (// @ts-ignore, // @ts-nocheck, # noqa, // biome-ignore, // eslint-disable) to bypass mechanical gates.
   • Newly introduced suppression comments without documented human rationale will trigger blocking Severity 1 failures (AI_SLOP_UNAUTHORIZED_SUPPRESSION).