mirror of https://github.com/allaunthefox/Research-Stack.git synced 2026-07-31 03:05:21 +00:00

Brandon Schneider 3044f36df7 docs(agents): project-wide AGENTS.md audit — cross-refs, baseline, contracts

Actions taken from 5-agent audit sweep (audit date 2026-05-26):

AGENTS.md / docs sync:
- root AGENTS.md: add scripts/qc-flag and lean_expert_agent to Nested Contracts
- All 6 nested AGENTS.md files: append Cross-References section pointing to
  root for Post-Interaction Workflow, Programming Choice Flow, Do Not Sweep,
  Git Remote Hygiene (Lean, Infra, text-to-cad, docs, qc-flag, lean_expert_agent)
- 6-Documentation/docs/AGENTS.md: cross-ref also lists AVMIsa.Emit sole output
  boundary and Compiler surface blessing

Lean build baseline:
- 0-Core-Formalism/lean/Semantics/AGENTS.md: update blessed Compiler Surface
  header to commit 49f0dfb3; correct job count to 3311 (lake build Compiler)

ARCHITECTURE.md:
- §7 repo table: add RRC.Emit, AVMIsa.Emit, RRC.Corpus278 to Lean/Semantics entry
- New §7.1 Compiler Surface: documents 3-root pipeline and sole output boundary
- §4 Data Flow: annotate output with AVMIsa.Emit sole-boundary note

TODO_MAP.md:
- Phase A6: add 3 new Lean deliverables (Corpus278, RRC.Emit, AVMIsa.Emit);
  update status/result with Compiler build baseline; refine next action

Build: Compiler 3311 jobs, 0 errors (no Lean changes).

Generated with Devin (https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

2026-05-26 22:34:46 -05:00

2.8 KiB

Raw Blame History

Lean Expert Agent — AGENTS.md

Purpose

Inspect Lean 4 code for structural integrity, proof correctness, naming conventions, and dependency hygiene. Reports findings as DAG receipts.

Trigger

/inspect <target> where target is a Lean file, directory, or module name.

Inspection Protocol

For every file inspected, the agent MUST report:

1. Structural Health

Count of theorem vs def vs #eval vs #eval!
Count of sorry proof holes and axiom declarations (⚠️ flag if > 0)
Count of native_decide proofs vs hand-written proofs
Count of empty theorem bodies (:= by with no following tactic)
Count of tautological theorems (X = X, v ≤ v)
Count of unused imports (import a module without using it)
Count of set_option linter suppressions

2. Naming Conventions (per AGENTS.md §2)

File names: PascalCase.lean (⚠️ flag if snake_case or kebab-case)
Types: PascalCase (⚠️ flag if not)
Functions: camelCase (⚠️ flag if snake_case or PascalCase)
Theorems: camelCase (⚠️ flag if not)
Namespaces: Semantics.<Domain> (⚠️ flag if not)
Banned: snake_case in any file/type name
Banned: getFoo, setFoo, checkFoo prefixes
Banned: _v2, _final suffixes

3. Q0_16 / Q16_16 Compliance (per AGENTS.md §1.4)

Are dimensionless scalars using Q0_16 (16-bit, pure fraction)?
Are mixed quantities using Q16_16 (32-bit, signed) ONLY when necessary?
Is Float used in hot-path code? (⚠️ flag if yes)
Are Q16_16 operations provably deterministic?

4. Proof Quality

Does every def have a companion theorem or #eval witness?
Do .get! calls have companion .isSome theorems?
Are native_decide proofs used when the problem is decidable?
Are inductive proofs used when the problem is inductive?
Are there unused variables in theorem statements?

5. Dependency Analysis

Does the file import modules it doesn't use?
Does the file use any sorry axiom from imported modules?
Are there circular dependencies between modules?

Output Format

/- DAG Receipt — Lean Expert Inspection
   File: <path>
   Date: <date>
   Pass: <true/false>
   Issues: <count>
-/

Each issue MUST include file:line reference, severity (⚠️ ERROR, 🔶 WARNING, ℹ️ INFO), and a concise fix suggestion.

Agent Resources

AGENTS.md at repo root for naming conventions
6-Documentation/docs/AGENTS.md for strict operating rules
0-Core-Formalism/lean/Semantics/Semantics/Physics/ for target inspection
lake build at 0-Core-Formalism/lean/Semantics/ for compilation verification

Cross-References

See root AGENTS.md for:

Post-Interaction Workflow (mandatory 5-step session-end procedure)
Programming Choice Flow (Lean owns decisions; Python owns I/O)
Do Not Sweep rules (no broad git add .)
Git Remote Hygiene

2.8 KiB Raw Blame History Unescape Escape