diff --git a/AGENTS.md b/AGENTS.md index 953561b..b9bdbd5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,54 +1,28 @@ # AGENTS.md -How to use the documents in this repo. This is the map: read it first, then go -to the right doc for your task. Keep this file under **200 lines** (aim for -**100**) — it's a signpost, not a manual. The depth lives in the docs it points -to. - -## Read in this order - -1. **`README.md`** — what sica-fondt is. -2. **`SOUL.md`** — intent and principles; the "why." -3. **`docs/`** — the architecture in detail: - - `bus-topology.md` — the Ichor bus and organ wiring. - - `gen03_state_of_architecture.md` — current architectural state. - - `gen03_body.md`, `gen03_self.md` — body/self model. - - `plans/` — forward-looking plans. -4. **`CLAUDE.md`** — working agreements, build/run, invariants. Read before - making changes. -5. **`ONBOARDING.md`** — setup checklist and first-task walkthrough (for people). - -## Which doc for which task - -| If you want to… | Go to | -|---|---| -| Understand the system at a high level | `README.md`, `SOUL.md` | -| Understand the architecture / organ model | `docs/` (start: `bus-topology.md`) | -| Build, run, or smoke-test | `run-sica-fondt` skill → `smoke.sh` | -| Know the rules before editing | `CLAUDE.md` (working agreements + invariants) | -| Onboard a new teammate | `ONBOARDING.md` | -| Find which doc covers a topic | this file | +How to use the documents in this repo — the prose signpost. The full +directory/document index lives in [`docmap.yaml`](docmap.yaml) (machine-readable; +start there to find which file covers what, the newcomer read-order, and the +organ list). Working agreements and invariant text: [`CLAUDE.md`](CLAUDE.md). +Keep this file lean (≤100 lines) — depth lives in the docs it points to. ## 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: +scoped `AGENTS.md` with its *local* build/run/invariants (see `docmap.yaml` → +`organs` for the list and paths). -- `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. +Keep scopes **non-overlapping**: the root signposts, 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. - **Honor the invariants** (S1/S2/S3 in `CLAUDE.md`) — the Ada border and the COBOL vault are not optional. -- **Verify, then commit.** Run the smoke driver; commit + push before leaving - (the container is ephemeral). -- **Keep the docs honest.** If you change behavior, update the doc that - describes it — and keep `CLAUDE.md` ≤200 lines and this file ≤200 (≤100 pref). +- **Verify, then commit.** Run the smoke driver (`docmap.yaml` → `smoke`); commit + + push before leaving (the container is ephemeral). +- **Keep the docs honest.** If you change behavior, update the doc — and the + `docmap.yaml` entry — that describes it. Keep `CLAUDE.md` ≤200 lines and this + file ≤100. diff --git a/CLAUDE.md b/CLAUDE.md index 526623d..22be6b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,4 +50,5 @@ Per-unit commands and gotchas live in that skill's `SKILL.md`. Toolchains - `README.md`, `SOUL.md` — the project and its intent. - `docs/` — architecture (`bus-topology.md`, `gen03_state_of_architecture.md`, …). - `ONBOARDING.md` — new-teammate setup and walkthrough. -- `AGENTS.md` — which document to read for what. +- `AGENTS.md` — prose signpost for how the docs fit together. +- `docmap.yaml` — machine-readable index: read-order, doc routing, organ list. diff --git a/docmap.yaml b/docmap.yaml new file mode 100644 index 0000000..077f643 --- /dev/null +++ b/docmap.yaml @@ -0,0 +1,56 @@ +# docmap.yaml — directory & document index for sica-fondt. +# +# The independent, machine-readable map referenced by AGENTS.md. AGENTS.md stays +# prose (scope + rules); this stays data (where things are). Keep in sync with +# the tree. Invariant text is authoritative in CLAUDE.md — mirrored here as a +# pointer only. + +docs: + read_order: # newcomer reading path + - README.md # what sica-fondt is + - SOUL.md # intent and principles — the "why" + - docs/ # architecture in detail + - CLAUDE.md # working agreements, build/run, invariants + - ONBOARDING.md # newcomer setup + first task + + routing: # which doc for which task + high_level_overview: [README.md, SOUL.md] + architecture: [docs/bus-topology.md, docs/gen03_state_of_architecture.md] + build_run_test: .claude/skills/run-sica-fondt/ # smoke.sh + rules_before_editing: CLAUDE.md + onboard_teammate: ONBOARDING.md + find_which_doc: AGENTS.md # the prose signpost; this file is its index + + design_docs: + docs/bus-topology.md: Ichor bus and organ wiring + docs/gen03_state_of_architecture.md: current architectural state + docs/gen03_body.md: body model + docs/gen03_self.md: self model + docs/plans/: forward-looking plans + +# Organs — deployable units, each with its own scoped AGENTS.md (nearest-wins). +organs: + - path: src/ichor + agents_md: src/ichor/AGENTS.md + lang: pony + role: Ichor perfusion bus (outer transport); S1 membrane screens external traffic + build: "ponyc src/ichor -o build && ./build/ichor" # from repo root + - path: src/endocrine + agents_md: src/endocrine/AGENTS.md + lang: [r, octave] + role: endocrine array — R Drive-Box + Octave ETR + build: "src/endocrine/run_tests.sh ; src/endocrine/etr/run_etr_tests.sh" + - path: mafiabot_core + agents_md: mafiabot_core/AGENTS.md + lang: [ada, cobol] + role: Ada border (D1) — all traffic crosses here first; COBOL invariant vault in src/trust + build: "cd mafiabot_core && alr -n build" # not bare gprbuild + +# Repo-wide invariants — authoritative text in CLAUDE.md. +invariants: + S1: all external traffic crosses the Ada border (D1) first + S2: never reclassify a message's provenance + S3: the COBOL invariant-law vault is immutable at runtime + +# One harness builds and runs every executable unit; want "smoke: ALL GREEN". +smoke: .claude/skills/run-sica-fondt/smoke.sh