From 0a5c88bb026a13a46d43a3cb1e254044642fcf99 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 22 Jun 2026 17:56:40 +0000 Subject: [PATCH] docs: nest organ-level AGENTS.md, root states the hierarchy AGENTS.md is hierarchical (nearest-file-wins), so the root is the map and each organ owns a scoped AGENTS.md with local build/run/invariants: src/ichor (Pony bus, S1 membrane), src/endocrine (R/Octave organ tests), mafiabot_core (Ada border + COBOL vault, alr-not-gprbuild, S3). Scopes kept non-overlapping to avoid the divergence trap rather than sprinkling sync notes. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_015hmgREHNsxYCuim33yUF2c --- AGENTS.md | 14 ++++++++++++++ mafiabot_core/AGENTS.md | 43 +++++++++++++++++++++++++++++++++++++++++ src/endocrine/AGENTS.md | 30 ++++++++++++++++++++++++++++ src/ichor/AGENTS.md | 28 +++++++++++++++++++++++++++ 4 files changed, 115 insertions(+) create mode 100644 mafiabot_core/AGENTS.md create mode 100644 src/endocrine/AGENTS.md create mode 100644 src/ichor/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 4ef9c00..953561b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,20 @@ to. | Onboard a new teammate | `ONBOARDING.md` | | Find which doc covers a topic | this file | +## Scope & nesting + +`AGENTS.md` is **hierarchical** — an agent reads the *nearest* one walking up +from the file it's editing. So this root file is the **map**; each organ owns a +scoped `AGENTS.md` with its *local* build/run/invariants: + +- `src/ichor/AGENTS.md` — the Ichor bus (Pony). +- `src/endocrine/AGENTS.md` — the endocrine organs (R / Octave). +- `mafiabot_core/AGENTS.md` — the Ada border (D1) + the COBOL vault under + `src/trust`. + +Keep scopes **non-overlapping**: the root maps, the organs detail. Don't restate +the root in an organ file (that's how the two drift) — link up instead. + ## Rules of the road - **Design before code.** The design docs are the source of truth; code follows. diff --git a/mafiabot_core/AGENTS.md b/mafiabot_core/AGENTS.md new file mode 100644 index 0000000..e1809f9 --- /dev/null +++ b/mafiabot_core/AGENTS.md @@ -0,0 +1,43 @@ +# AGENTS.md — Ada border (D1) + invariant vault + +Local guide for `mafiabot_core`. Repo-wide map and rules: [`../AGENTS.md`](../AGENTS.md); +working agreements: [`../CLAUDE.md`](../CLAUDE.md). + +## What this is + +The **Ada/SPARK border — D1**. All traffic to the inner brain crosses here +first. Built with **Alire**. Internal modules under `src/`: `trust` (incl. the +COBOL invariant-law vault), `organs`, `network`, `protocol`, `daemons`, `core`, +`types`, `payloads`. These are modules, not separate organs — they share this +file. + +## Build & test + +Use **Alire**, not bare `gprbuild` (the project imports an Alire-generated +config gpr): + +```bash +cd mafiabot_core && alr -n build +./bin/trust_tests && ./bin/config_tests && ./bin/engine_tests +``` + +`engine_tests` prints nothing on success (clean exit). Or run the whole repo +via `.claude/skills/run-sica-fondt/smoke.sh`. + +## The COBOL invariant vault (`src/trust`) + +`src/trust/invariants-architecture.cobol` is **E1, the constitution** — +Invariant 0 (the culpability anchor) and 01 (minimize harm). Compile/run free +format: + +```bash +cobc -x -free -o /tmp/inv src/trust/invariants-architecture.cobol && /tmp/inv +``` + +## Local invariants + +- **S1:** this is the border — never add a route that lets traffic reach the + inner brain without crossing here. +- **S2:** never reclassify a message's provenance. +- **S3:** the invariant vault is **immutable at runtime** — don't edit it + casually; it's the constitution, not config. diff --git a/src/endocrine/AGENTS.md b/src/endocrine/AGENTS.md new file mode 100644 index 0000000..e290d9e --- /dev/null +++ b/src/endocrine/AGENTS.md @@ -0,0 +1,30 @@ +# AGENTS.md — endocrine organs (R / Octave) + +Local guide for `src/endocrine`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). + +## What this is + +The **endocrine array** — slow-signal organs that modulate the system: the R +**Drive-Box** (`drive_box.R`, `driver_*.R`, `endocrine_array.R`, `priors.R`) and +the Octave **ETR** under `etr/`. See `Plan.md` here and `etr/etr_invariants.md` +for design. + +## Build & run + +Toolchains (R 4.3.3, Octave 8.4) are installed each session by the SessionStart +hook. Run the organ tests directly: + +```bash +src/endocrine/run_tests.sh # R Drive-Box + drivers +src/endocrine/etr/run_etr_tests.sh # Octave ETR +``` + +(Not yet wired into the top-level `run-sica-fondt` smoke driver — run them here.) + +## Local notes + +- Pure R/Octave; no compile step. Each `test_*.R` / `test_etr.m` pairs with its + `driver`/source file. +- ETR invariants are documented in `etr/etr_invariants.md` — read before + changing `etr.m`. diff --git a/src/ichor/AGENTS.md b/src/ichor/AGENTS.md new file mode 100644 index 0000000..0dd352b --- /dev/null +++ b/src/ichor/AGENTS.md @@ -0,0 +1,28 @@ +# AGENTS.md — Ichor bus (Pony) + +Local guide for `src/ichor`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). + +## What this is + +The **Ichor perfusion bus** — the outer transport that perfuses organs with +messages. Pony. This is where inbound external traffic is first screened before +anything reaches the Ada border (D1). + +## Build & run + +Run from the **repo root** (ponyc resolves the path from there): + +```bash +export PATH=/root/.local/share/ponyup/bin:$PATH # if ponyc not found +ponyc src/ichor -o build && ./build/ichor +``` + +Or via the smoke driver: `.claude/skills/run-sica-fondt/smoke.sh`. + +## Local invariants + +- **S1 lives here.** The bus must `D1 REJECT` unscreened external payloads — + external traffic only reaches an organ via the Ada border. Never add a path + that perfuses an inner organ directly from `world`. +- **S2:** never reclassify a message's provenance as it crosses the bus.