docs: clean up the three drift items flagged in #112

.build/dune-project

@@ -25,7 +25,7 @@
  (description
   "AffineScript combines Rust-style ownership (affine types), compile-time size verification (dependent types), extensible records (row polymorphism), and trackable side effects (extensible effects). It compiles to WebAssembly for efficient, portable execution.")
  (depends
-  (ocaml (>= 5.1))
+  (ocaml (>= 4.14))
   (dune (>= 3.14))
   (menhir (>= 20231231))
   (sedlex (>= 3.2))

AI.a2ml

@@ -2,21 +2,36 @@
 
 # Machine-Readable Metadata
 
-Project metadata and AI agent configuration files are located in `.machine_readable/`:
+Project metadata and AI agent configuration files live under `.machine_readable/`. All metadata files use the `.a2ml` extension; the `.scm` extension is reserved for Guix (`guix.scm`, `.guix-channel`).
 
-- **STATE.scm** - Current project state, progress, blockers, next actions
-- **ECOSYSTEM.scm** - Position in ecosystem, relationships to other projects
-- **META.scm** - Architecture decisions, governance, development practices
-- **PLAYBOOK.scm** - Operational runbook, procedures, alerts
-- **AGENTIC.scm** - AI agent interaction patterns and constraints
-- **NEUROSYM.scm** - Neurosymbolic integration configuration
+## Core 6a2 metadata (`.machine_readable/6a2/`)
+
+- **STATE.a2ml** - Current project state, progress, blockers, next actions, session notes
+- **ECOSYSTEM.a2ml** - Position in ecosystem, relationships to sibling projects
+- **META.a2ml** - Architecture decisions, governance, development practices
+- **PLAYBOOK.a2ml** - Operational runbook, procedures, alerts
+- **AGENTIC.a2ml** - AI agent interaction patterns and constraints
+- **NEUROSYM.a2ml** - Neurosymbolic integration configuration
+
+## Top-level contractile files (`.machine_readable/`)
+
+- **ADJUST.contractile**, **INTENT.contractile**, **MUST.contractile**, **TRUST.contractile** - Trident-shape commitments
+- **CLADE.a2ml** - Phylogenetic context within the estate
+- **anchors/ANCHOR.a2ml** - Stable references for tooling
+
+## Agent guidance (`.machine_readable/agent_instructions/`)
+
+- **methodology.a2ml** - Required checks (dune build / dune runtest must pass; see for the full list)
+- **coverage.a2ml**, **debt.a2ml** - Tracked metrics
+- **README.adoc** - Human-readable summary of agent instructions
 
 **These files are the canonical source of truth for project metadata.**
 
 ## Workflow
 
-1. Read `.machine_readable/*.scm` files at session start
-2. Check STATE.scm for current phase, blockers, next actions
-3. Follow patterns and constraints from AGENTIC.scm
-4. Update STATE.scm after completing work
-5. Sync to database: `~/sync-language-tracker.sh`
+1. Read `.machine_readable/6a2/*.a2ml` files at session start
+2. Check `STATE.a2ml` for current phase, blockers, next actions
+3. Follow patterns and constraints from `AGENTIC.a2ml`
+4. Follow methodology gates from `agent_instructions/methodology.a2ml`
+5. Update `STATE.a2ml` after completing work
+6. Sync to database: `~/sync-language-tracker.sh`

CONTRIBUTING.md

@@ -1,48 +1,59 @@
-# Clone the repository
-git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git
-cd {{REPO}}
+# Contributing to AffineScript
 
-# Using Nix (recommended for reproducibility)
-nix develop
+Thank you for your interest in AffineScript — a practical language for resource-safe systems, compiling to typed WebAssembly. This guide covers how to set up a working tree, file useful bugs, and submit changes.
 
-# Or using toolbox/distrobox
-toolbox create {{REPO}}-dev
-toolbox enter {{REPO}}-dev
-# Install dependencies manually
+For the language itself, start from [`README.adoc`](README.adoc). For project state, blockers, and next-actions, see [`.machine_readable/6a2/STATE.a2ml`](.machine_readable/6a2/STATE.a2ml).
+
+---
+
+## Quick Start
+
+```bash
+git clone https://github.com/hyperpolymath/affinescript.git
+cd affinescript
+
+# Provision the OCaml toolchain (one-shot). See README.adoc "Getting Started"
+# for the full list of opam packages and the `eval $(opam env)` note for
+# non-interactive shells.
+opam install -y \
+  sedlex menhir ppx_deriving ppx_sexp_conv sexplib0 fmt cmdliner yojson \
+  alcotest ocamlformat \
+  js_of_ocaml js_of_ocaml-ppx js_of_ocaml-compiler
+eval "$(opam env --switch=default --set-switch)"
 
 # Verify setup
-just check   # or: cargo check / mix compile / etc.
-just test    # Run test suite
+dune build
+dune runtest
 ```
 
+Tested on OCaml 4.14.2 (the constraint in `dune-project` is `>= 4.14`).
+
 ### Repository Structure
+
 ```
-{{REPO}}/
-├── src/                 # Source code (Perimeter 1-2)
-├── lib/                 # Library code (Perimeter 1-2)
-├── extensions/          # Extensions (Perimeter 2)
-├── plugins/             # Plugins (Perimeter 2)
-├── tools/               # Tooling (Perimeter 2)
-├── docs/                # Documentation (Perimeter 3)
-│   ├── architecture/    # ADRs, specs (Perimeter 2)
-│   └── proposals/       # RFCs (Perimeter 3)
-├── examples/            # Examples (Perimeter 3)
-├── spec/                # Spec tests (Perimeter 3)
-├── tests/               # Test suite (Perimeter 2-3)
-├── .well-known/         # Protocol files (Perimeter 1-3)
-├── .github/             # GitHub config (Perimeter 1)
-│   ├── ISSUE_TEMPLATE/
-│   └── workflows/
-├── CHANGELOG.md
+affinescript/
+├── lib/                 # Compiler core (lexer, parser, typechecker, codegen, verifier)
+├── bin/                 # CLI driver — `_build/default/bin/main.exe`
+├── stdlib/              # Standard library `.affine` modules
+├── test/                # Alcotest suites (lexer, golden, e2e fixtures)
+├── tests/               # Topic-grouped tests (borrow, codegen, effects, parser, …)
+├── examples/            # Self-contained example programs
+├── conformance/         # Conformance test corpus
+├── docs/                # Specs, decisions, guides
+├── packages/            # Aggregate JS/TS/ReScript binding packages
+├── editors/             # Editor integrations
+├── js/                  # `js_of_ocaml` playground (built into `playground.bc.js`)
+├── .machine_readable/   # Machine-readable metadata (`.a2ml`) — see AI.a2ml
+├── .github/             # CI workflows, issue templates
 ├── CODE_OF_CONDUCT.md
 ├── CONTRIBUTING.md      # This file
-├── GOVERNANCE.md
-├── LICENSE
-├── MAINTAINERS.md
+├── LICENSE / LICENSES   # MIT OR AGPL-3.0-or-later
+├── MAINTAINERS.adoc
 ├── README.adoc
+├── ROADMAP.adoc
 ├── SECURITY.md
-├── flake.nix            # Nix flake (Perimeter 1)
-└── justfile             # Task runner (Perimeter 1)
+├── dune-project
+└── justfile
 ```
 
 ---
@@ -51,66 +62,95 @@ just test    # Run test suite
 
 ### Reporting Bugs
 
-**Before reporting**:
-1. Search existing issues
-2. Check if it's already fixed in `{{MAIN_BRANCH}}`
-3. Determine which perimeter the bug affects
+**Before reporting:**
+1. Search [existing issues](https://github.com/hyperpolymath/affinescript/issues).
+2. Check that the bug reproduces against `main` (`git pull && dune build`).
 
-**When reporting**:
+**When reporting:** use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include:
 
-Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include:
-
-- Clear, descriptive title
-- Environment details (OS, versions, toolchain)
-- Steps to reproduce
-- Expected vs actual behaviour
-- Logs, screenshots, or minimal reproduction
+- Clear, descriptive title.
+- Environment: OCaml version, opam switch, OS.
+- Steps to reproduce, ideally as a minimal `.affine` file plus the exact `dune exec affinescript -- <subcommand> <file>` invocation.
+- Expected vs actual behaviour (compiler output, generated Wasm, runtime trap, etc.).
 
 ### Suggesting Features
 
-**Before suggesting**:
-1. Check the [roadmap](ROADMAP.md) if available
-2. Search existing issues and discussions
-3. Consider which perimeter the feature belongs to
-
-**When suggesting**:
+**Before suggesting:**
+1. Skim [`ROADMAP.adoc`](ROADMAP.adoc) and `.machine_readable/6a2/STATE.a2ml`.
+2. Search existing issues and discussions.
 
-Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include:
+**When suggesting:** use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include:
 
-- Problem statement (what pain point does this solve?)
-- Proposed solution
-- Alternatives considered
-- Which perimeter this affects
+- Problem statement — what pain point does this solve?
+- Proposed solution and any alternatives considered.
+- Whether the change touches the core language, a face (frontend surface), a backend, or the stdlib.
 
 ### Your First Contribution
 
 Look for issues labelled:
 
-- [`good first issue`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks
-- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed
-- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements
-- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/perimeter-3) — Community sandbox scope
+- [`good first issue`](https://github.com/hyperpolymath/affinescript/labels/good%20first%20issue)
+- [`help wanted`](https://github.com/hyperpolymath/affinescript/labels/help%20wanted)
+- [`documentation`](https://github.com/hyperpolymath/affinescript/labels/documentation)
 
 ---
 
 ## Development Workflow
 
 ### Branch Naming
+
 ```
-docs/short-description       # Documentation (P3)
-test/what-added              # Test additions (P3)
-feat/short-description       # New features (P2)
-fix/issue-number-description # Bug fixes (P2)
-refactor/what-changed        # Code improvements (P2)
-security/what-fixed          # Security fixes (P1-2)
+docs/short-description       # Documentation
+test/what-added              # Test additions
+feat/short-description       # New features
+fix/issue-number-description # Bug fixes
+refactor/what-changed        # Code improvements
+security/what-fixed          # Security fixes
+ci/what-changed              # CI / tooling
 ```
 
+Branch from `main` and target `main` in your PR.
+
 ### Commit Messages
 
 We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
 ```
 <type>(<scope>): <description>
 
 [optional body]
 
-[optional footer]
+[optional footer, e.g. closes #N or Co-Authored-By: ...]
+```
+
+Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`. Common scopes: `lexer`, `parser`, `typecheck`, `codegen`, `verify`, `stdlib`, `cli`, `readme`.
+
+### Required Checks
+
+Before opening a PR, locally:
+
+```bash
+dune build       # must exit 0
+dune runtest     # must be green
+dune fmt         # optional — auto-formats with ocamlformat
+```
+
+The `methodology.a2ml` file lists the canonical gate set. CI will rerun `build` + `runtest` plus the security, lint, and policy workflows in `.github/workflows/`.
+
+### Pull Requests
+
+1. Push your branch and open a PR against `main`.
+2. Use a Conventional-Commit-shaped title.
+3. In the body, summarise the change and link the issue it closes.
+4. Keep PRs focused — split unrelated changes into separate PRs.
+5. CI must be green. Maintainers squash-merge by default; commit message lineage is preserved in the PR body.
+
+---
+
+## Code of Conduct
+
+This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). By participating you agree to abide by it.
+
+## License
+
+By contributing you agree your contribution is licensed under the project's dual licence (MIT OR AGPL-3.0-or-later), as recorded in [`LICENSE`](LICENSE) and per-file SPDX headers.

README.adoc

@@ -387,7 +387,7 @@ Games are one place where the language’s properties are easy to demonstrate. T
 
 === Prerequisites
 
-- OCaml 4.14.2+ (dune-project lists `>= 5.1`, but the current tree also builds clean on 4.14.2; the constraint is stricter than the actual code requires)
+- OCaml 4.14.2+
 - Dune 3.14+
 - opam packages: `sedlex`, `menhir`, `ppx_deriving`, `ppx_sexp_conv`, `sexplib0`, `fmt`, `cmdliner`, `yojson`, `alcotest` (test), `ocamlformat` (test), `js_of_ocaml`, `js_of_ocaml-ppx`, `js_of_ocaml-compiler`
 

affinescript.opam

@@ -22,7 +22,7 @@ homepage: "https://github.com/hyperpolymath/affinescript"
 doc: "https://github.com/hyperpolymath/affinescript"
 bug-reports: "https://github.com/hyperpolymath/affinescript/issues"
 depends: [
-  "ocaml" {>= "5.1"}
+  "ocaml" {>= "4.14"}
   "dune" {>= "3.14" & >= "3.14"}
   "menhir" {>= "20231231"}
   "sedlex" {>= "3.2"}