auto-harness

Auto Harness

Overview

Design the project harness so repository rules become executable. Start by mapping where semantics can drift, then convert the risky ones into generated artifacts, contract tests, type or layer guards, and CI checks.

Workflow

1. Build a harness map before proposing fixes.

   • Read entrypoint materials first: AGENTS.md, repo-root docs, Makefile, package scripts, CI workflows, API specs, codegen config, lint config, type-check config, and test runners.
   • Avoid bulk-loading every doc. Follow progressive disclosure: read only the references needed for the current risk.
   • Record the harness surfaces that already exist: documentation rules, generated files, test suites, CI gates, architecture constraints, observability standards, and debt tracking.

2. Load the matching reference files.

   • Read references/checklist.md to score the current harness and find missing guardrails.
   • Read references/guide.md when you need the design principles and recommended repository shapes.
   • Read references/guard-patterns.md when you need concrete enforcement strategies.
   • Read references/fix-plan.md when you need a staged remediation plan or a deliverable template.
   • Read references/upstream.md when you need the builtin bundle provenance or manual sync guidance.

3. Diagnose drift as a systems problem, not a single bug.

   • Search for the same semantic repeated across layers: permissions, routes, CLI commands, OpenAPI, generated clients, frontend assumptions, docs, logging fields, config, and tests.
   • Flag any semantic that is declared in multiple places without a hard synchronization mechanism.
   • Treat "scope list says yes, runtime path says no" and similar mismatches as harness failures, not just implementation bugs.
   • Write the diagnosis in terms of duplicated authority, missing invariants, missing generated artifacts, or missing tests.

4. Prefer hard guardrails over policy prose.

   • Establish a single source of truth for drift-sensitive semantics.
   • Generate downstream artifacts instead of hand-maintaining parallel definitions.
   • Add failing checks in CI for zero-drift contracts: OpenAPI parity, generated client freshness, import-layer guards, JSON schema checks, snapshot parity, or table-driven route or scope coverage.
   • Add type-level or package-boundary checks when architecture depends on layering.
   • Add structured logs when the real system is expensive to exercise and deterministic tests are limited.