// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
= AffineScript Agent Instructions
:toc: preamble

Methodology-aware configuration for AI agents working in this repository.
Read at session start by any AI agent (Claude, Gemini, Copilot, etc.).

== Critical: read before touching code

1. **ANCHOR.a2ml is authoritative for scope.** The thesis is fixed. New features require a new ADR, not a code change. Bot scope creep has been a recurring problem (see manhattan-recovery 2026-04-10).
2. **No `.ml` edits without reading ANCHOR.a2ml + META.a2ml first.** The type system has interdependencies that are not obvious from reading individual files.
3. **dune build must pass** before and after every change. Run it.
4. **Thesis is the authority; code must conform.** If code contradicts thesis, code is wrong.

== Files

[cols="1,3"]
|===
| File | Purpose

| `methodology.a2ml`
| Default mode, ring ceiling, priority weights, wave cap

| `coverage.a2ml`
| Session coverage tracking — what was visited, what was skipped

| `debt.a2ml`
| Meander debt — things found but not fixed, carried between sessions
|===

== Open bugs (from ANCHOR.a2ml)

BUG-001 through BUG-004 are tracked in STATE.a2ml. Check before starting any type-system work — one of these may already cover the issue you found.

== Faces architecture

AffineScript supports multiple surface-syntax dialects (canonical, python-face, js-face, pseudocode-face). New faces follow the pattern in `lib/face.ml`. Do NOT add face-specific logic directly to the parser or type checker.
