Cleanup/consolidate and gap analysis (#64)

* docs: consolidate CLAUDE.md into AGENTS.md

Merge project-specific guidance from CLAUDE.md into AGENTS.md as the
single entrypoint for all coding agents. CLAUDE.md now redirects to
AGENTS.md.

Changes:
- Add 'What This Project Is' section (from CLAUDE.md)
- Merge architecture doc reading list into Required Load Order
- Add Project Rules (Do/Don't) section (from CLAUDE.md)
- Expand Backpressure with build/doc commands under Nix wrappers
- Deduplicate two overlapping architecture sections into one
- Remove 'Related Documents' section (was CLAUDE.md pointer)
- Update CONTRIBUTING.md references from CLAUDE.md to AGENTS.md

* refactor: cleanup dead code, rename EffectExecutor, fix stale READMEs

orch-kit:
- Rename EffectExecutor -> EffectInterpreter (resolves name collision with
  neuron-effects-core::EffectExecutor; they're different abstraction levels)
- Rename LocalEffectExecutor -> LocalEffectInterpreter
- Rename runner_with_executor -> runner_with_interpreter
- Remove unused tracing dependency
- Remove dead _touch_errors placeholder function

op-react:
- Remove dead _tool_uses variable (data collected twice, first unused)

READMEs (5 crates):
- layer0: Fix test-utils names (EchoOperator, InMemoryStore, not Stub*)
- neuron-mcp: Fix type names (McpClient/McpServer, not Bridge variants)
- neuron-hooks: Fix Hook trait signature (on_event, not before_turn/after_turn)
- neuron-tool: Fix trait name (ToolDyn.call, not Tool.invoke)
- neuron-orch-local: Fix type name (LocalOrch, not LocalOrchestrator)

All 393 tests pass. Clippy clean. Formatted.

* chore: remove scratch plan file from tracking

* docs: add Agent Constitution (CONSTITUTION.md)

Normative document deriving from the Agentic Decision Map v3.
Encodes core values (composability, effects boundary, slim defaults,
protocol stability, explicitness) and Neuron's positions on all 23
architectural decisions.

Format follows Anthropic's constitutional style: narrative explanation
of WHY, not just WHAT. Structured as a universal template — other
projects can fork and fill in their own positions.

Also:
- AGENTS.md: added to required reading list (#5), updated truth
  hierarchy (constitution > specs > rules > agent judgment)
- release-please-config.json: excluded from release triggers

* docs: tighten CONSTITUTION.md

Cut from 268 to 155 lines (~42%). Same 5 values, same 23 positions.

- Eliminated formulaic 'The principle / Positions' repetition
- Removed 'orchestration protocol owns X' redundancy (was 8x)
- Cut decision index table (duplicated narrative)
- Varied rhythm across sections instead of rigid template
- Sharpened voice from reference-manual to constitutional

* refactor: reorganize workspace into domain-grouped directories

Move 34 crates from flat repo root into 11 domain groups:

  turn/     neuron-turn, neuron-turn-kit, neuron-context, neuron-tool, neuron-mcp
  op/       neuron-op-react, neuron-op-single-shot
  orch/     neuron-orch-local, neuron-orch-kit
  effects/  neuron-effects-core, neuron-effects-local
  hooks/    neuron-hooks, neuron-hook-security
  state/    neuron-state-memory, neuron-state-fs
  env/      neuron-env-local
  provider/ neuron-provider-anthropic, neuron-provider-openai, neuron-provider-ollama
  secret/   neuron-secret + 6 backends
  auth/     neuron-auth + 4 backends
  crypto/   neuron-crypto + 2 backends

layer0/ and neuron/ (umbrella) stay at root.

Crate names, published package names, and all code unchanged.
Updated: workspace members, 109 path dependencies across 26
Cargo.toml files, release-please-config.json,
.release-please-manifest.json, README.md crate map.

All 393 tests pass. Clippy clean. Formatted.

* docs: update workspace layout in active docs after restructure

- NEURON-REDESIGN-PLAN.md: rewritten workspace tree to match grouped layout
- docs/architecture/validation-and-coordination.md: same
- ralph_queue.md: fixed one path reference

Historical docs/plans/* left untouched (historical record).

* docs: decision map gap analysis — 23→24 decisions, expand D3A/D5/D4B/C1

Deep research across all 23 decisions in the Agentic Decision Map v3:
- 8 parallel research runs covering Turn, Composition, and Lifecycle layers
- Independence-tested 6 proposed new decisions against real architectures

Results:
- Add D3D (Output Shape) as genuinely new decision in inference cluster
- Expand D3A table with two-level routing (model + reasoning effort)
- Expand D5 with 4 new exit strategies (self-assessment, verification,
  loop detection, infeasibility)
- Expand D4B with workload identity and proxy-mediated options
- Expand C1 with trust/permission propagation model
- Add Named Autonomy Configurations sidebar (D4A + C5 composite)
- Add Development Lifecycle open questions (eval gating, versioning)
- Update decision topology diagram and count (23 → 24)

New documents:
- decision-map-gap-analysis-2026.md — full research synthesis
- decision-map-new-decision-audit.md — independence test methodology
- gap-analysis-implementation-roadmap.md — code change spec
- research-2026-03/ — 8 raw research reports + metadata

* chore: delete 11 stub crates, keep neuron-secret-vault as reference

Delete empty backend stubs that added crate count without substance:
- auth: neuron-auth-{static,file,oidc,k8s} (53-69 lines each)
- secret: neuron-secret-{env,aws,gcp,keystore,k8s} (77-121 lines each)
- crypto: neuron-crypto-{vault,hardware} (109 lines each)

Keep neuron-secret-vault as the reference stub for future backends.
Workspace: 37 → 26 crates. Historical docs in docs/plans/ left as-is.

* fix: pre-commit hook uses nix fmt instead of bare treefmt

treefmt binary is not on PATH outside nix develop shell.
Use 'nix fmt && git diff --exit-code' to match CI behavior.

* fix: expose treefmt wrapper in devShell via treefmt-nix

treefmt-nix was already wired as a flake module but config.treefmt.build.wrapper
was not added to devShell buildInputs, so the treefmt binary was never on PATH.

Add the wrapper to devShell so 'treefmt' is available inside nix develop.
Pre-commit hook invokes via 'nix develop --command treefmt --fail-on-change'
since hooks run outside the nix shell.

* fix: correct stale relative links after domain-dir restructure; add lychee pre-commit hook

8 relative file links across 7 READMEs were broken by the workspace
reorganization (crates moved into domain subdirectories):

  ../layer0       -> ../../layer0         (hooks, env, state crates)
  ../neuron-turn  -> ../../turn/neuron-turn (provider crates)
  ../neuron-secret -> ../../secret/neuron-secret (env crate)

Also add lychee (--scheme file) as a pre-commit hook so broken local
links are caught before push, not by CI. HTTP links remain CI-only
(offline, fast, no rate-limit flakiness).

Exclude .direnv from .lychee.toml to avoid scanning nixpkgs READMEs.

* fix: add missing crates to release-please manifest and config

neuron-effects-core, neuron-effects-local, and neuron-turn-kit were
present in the workspace but absent from release-please tracking.
All three are publishable at 0.4.0.

Author: SecBear

.lychee.toml

@@ -19,7 +19,7 @@ exclude = [
 ]
 
 # Exclude build artifacts and dependency docs
-exclude_path = ["target"]
+exclude_path = ["target", ".direnv"]
 
 # Retry transient failures
 max_retries = 3

.pre-commit-config.yaml

@@ -3,11 +3,19 @@ repos:
     hooks:
       - id: treefmt
         name: treefmt
-        entry: treefmt --fail-on-change
+        entry: nix develop --command treefmt --fail-on-change
         language: system
         pass_filenames: false
         stages: [pre-commit]
 
+      - id: lychee-file-links
+        name: lychee (file links)
+        entry: lychee --scheme file --no-progress --config .lychee.toml
+        language: system
+        pass_filenames: true
+        types: [markdown]
+        stages: [pre-commit]
+
       - id: clippy
         name: clippy
         entry: cargo clippy --workspace --all-features -- -D warnings

.release-please-manifest.json

@@ -1,35 +1,27 @@
 {
+  "auth/neuron-auth": "0.4.0",
+  "crypto/neuron-crypto": "0.4.0",
+  "effects/neuron-effects-core": "0.4.0",
+  "effects/neuron-effects-local": "0.4.0",
+  "env/neuron-env-local": "0.4.0",
+  "hooks/neuron-hook-security": "0.4.0",
+  "hooks/neuron-hooks": "0.4.0",
   "layer0": "0.4.0",
-  "neuron-tool": "0.4.0",
-  "neuron-turn": "0.4.0",
-  "neuron-hooks": "0.4.0",
-  "neuron-hook-security": "0.4.0",
-  "neuron-context": "0.4.0",
-  "neuron-op-react": "0.4.0",
-  "neuron-op-single-shot": "0.4.0",
-  "neuron-state-memory": "0.4.0",
-  "neuron-state-fs": "0.4.0",
-  "neuron-orch-kit": "0.4.0",
-  "neuron-orch-local": "0.4.0",
-  "neuron-env-local": "0.4.0",
-  "neuron-secret": "0.4.0",
-  "neuron-secret-env": "0.4.0",
-  "neuron-secret-vault": "0.4.0",
-  "neuron-secret-aws": "0.4.0",
-  "neuron-secret-gcp": "0.4.0",
-  "neuron-secret-keystore": "0.4.0",
-  "neuron-secret-k8s": "0.4.0",
-  "neuron-auth": "0.4.0",
-  "neuron-auth-static": "0.4.0",
-  "neuron-auth-file": "0.4.0",
-  "neuron-auth-oidc": "0.4.0",
-  "neuron-auth-k8s": "0.4.0",
-  "neuron-crypto": "0.4.0",
-  "neuron-crypto-vault": "0.4.0",
-  "neuron-crypto-hardware": "0.4.0",
-  "neuron-provider-anthropic": "0.4.0",
-  "neuron-provider-openai": "0.4.0",
-  "neuron-provider-ollama": "0.4.0",
-  "neuron-mcp": "0.4.0",
-  "neuron": "0.4.0"
+  "neuron": "0.4.0",
+  "op/neuron-op-react": "0.4.0",
+  "op/neuron-op-single-shot": "0.4.0",
+  "orch/neuron-orch-kit": "0.4.0",
+  "orch/neuron-orch-local": "0.4.0",
+  "provider/neuron-provider-anthropic": "0.4.0",
+  "provider/neuron-provider-ollama": "0.4.0",
+  "provider/neuron-provider-openai": "0.4.0",
+  "secret/neuron-secret": "0.4.0",
+  "secret/neuron-secret-vault": "0.4.0",
+  "state/neuron-state-fs": "0.4.0",
+  "state/neuron-state-memory": "0.4.0",
+  "turn/neuron-context": "0.4.0",
+  "turn/neuron-mcp": "0.4.0",
+  "turn/neuron-tool": "0.4.0",
+  "turn/neuron-turn": "0.4.0",
+  "turn/neuron-turn-kit": "0.4.0"
 }

AGENTS.md

@@ -1,15 +1,20 @@
 # AGENTS.md
 
-This file is the entrypoint for any coding agent (Codex, Claude Code, etc.) working in this repo.
-It defines what to load, in what order, and what quality gates must be satisfied before claiming
-work is complete.
+Entrypoint for any coding agent (Codex, Claude Code, etc.) working in this repo.
+Defines what to load, what the project is, and what quality gates must pass before claiming done.
+
+## What This Project Is
+
+Neuron is a Rust workspace implementing a 6-layer composable agentic AI architecture.
+Layer 0 (`layer0` crate) defines the stability contract: four protocol traits
+(Turn, Orchestrator, StateStore, Environment), two cross-cutting interfaces
+(Hook, Lifecycle events), and the message types that cross every boundary.
+Layers 1-5 build implementations on top.
 
 ## Prime Directive: One Task Per Context
 
 Treat the context window like a fixed-size allocation: once you mix tasks, you lose coherence.
 
-Rules:
-
 1. One task per context window. If scope changes, start a fresh session.
 2. When you notice drift (conflicting goals, repeating mistakes, inventing APIs), stop and restart.
 3. Each loop must re-load the same stable stack (specs + rules) deterministically.
@@ -26,18 +31,30 @@ Load these documents in order before doing any implementation work:
 If you are unsure which spec applies, read `specs/00-vision-and-non-goals.md` and
 `specs/01-architecture-and-layering.md` first.
 
+For deep architectural context, continue with:
+
+5. `CONSTITUTION.md` — Agent constitution. Core values, positions on all 23 architectural decisions, authority hierarchy.
+6. `NEURON-REDESIGN-PLAN.md` — Authoritative plan. 6-layer architecture, workspace structure, phased implementation.
+7. `docs/architecture/HANDOFF.md` — Layer 0 implementation spec. Trait signatures, type definitions, module structure.
+8. `docs/architecture/composable-agentic-architecture.md` — Design rationale. 4 protocols + 2 interfaces, gap analysis.
+9. `docs/architecture/platform-scope-mapping.md` — Where features live (Neuron vs platform vs external infra).
+10. `docs/architecture/agentic-decision-map-v3.md` — Full design space. All 23 architectural decisions.
+11. `DEVELOPMENT-LOG.md` — Complete history of all decisions, research, and rationale.
+
 ## Where Truth Lives
 
-1. Requirements and intended behavior live in `specs/`.
-2. Operational constraints (how we work, how to verify, how to avoid repeated failure modes)
+1. Architectural values and positions on the 23 decisions live in `CONSTITUTION.md`.
+2. Requirements and intended behavior live in `specs/`.
+3. Operational constraints (how we work, how to verify, how to avoid repeated failure modes)
    live in `rules/`.
-3. Deep rationale and history live in `docs/` and `DEVELOPMENT-LOG.md`.
+4. Deep rationale and history live in `docs/` and `DEVELOPMENT-LOG.md`.
 
 If there is a conflict:
 
-1. Specs override rules.
-2. Rules override ad-hoc agent behavior.
-3. If the specs are ambiguous, update the specs (do not invent behavior).
+1. Constitution overrides specs.
+2. Specs override rules.
+3. Rules override ad-hoc agent behavior.
+4. If the specs are ambiguous, update the specs (do not invent behavior).
 
 ## Backpressure (Verification Gates)
 
@@ -46,11 +63,40 @@ This repo assumes Rust tooling is provided by Nix. Do not assume `cargo` exists
 Use these commands as your default backpressure:
 
 1. Format: `nix develop -c nix fmt`
-2. Tests: `nix develop -c cargo test --workspace --all-targets`
-3. Lints: `nix develop -c cargo clippy --workspace --all-targets -- -D warnings`
+2. Build: `nix develop -c cargo build --workspace`
+3. Tests: `nix develop -c cargo test --workspace --all-targets`
+4. Lints: `nix develop -c cargo clippy --workspace --all-targets -- -D warnings`
+5. Docs: `nix develop -c cargo doc --no-deps`
+
+All must pass before any commit. For layer0 test-utils features:
+
+```bash
+nix develop -c cargo test --features test-utils -p layer0
+```
 
 Do not claim "done" unless you have fresh evidence from the relevant command(s) for the change.
 
+## Project Rules
+
+### Do
+
+- Follow `NEURON-REDESIGN-PLAN.md` for all structural decisions
+- Match layer0 trait signatures exactly — they are the stability contract
+- Use `#[deny(missing_docs)]` on every public item
+- Test that every message type round-trips through serde_json
+- Test that every trait is object-safe (`Box<dyn Trait>` compiles and is `Send + Sync`)
+- Keep layer0 dependencies minimal (serde, async-trait, thiserror, rust_decimal — that's it)
+- Update `DEVELOPMENT-LOG.md` after each phase
+
+### Do Not
+
+- Add dependencies to layer0 beyond what's already there
+- Add methods to layer0 protocol traits beyond what `HANDOFF.md` defines
+- Change layer0's trait signatures — they are the stability contract
+- Make layer0 traits non-object-safe
+- Skip phases — the phased approach is sequential
+- Make undocumented decisions — update the plan first if deviating
+
 ## TDD Policy
 
 When feasible:
@@ -65,6 +111,65 @@ Exceptions are allowed only for:
 2. Pure documentation changes.
 3. Configuration-only changes where tests are not meaningful (but verification is still required).
 
+## Architecture Principles
+
+### Layer 0 Protocol
+
+- Protocol only: object-safe traits + serde wire types. No execution policy, no technology bindings, no durability semantics.
+- Additive changes preferred; breaking changes planned and versioned.
+
+### Effects Boundary
+
+- Sacred: operators declare, orchestrators/environments execute. No direct writes from operators.
+
+### Hooks vs Steering
+
+- **Hooks**: event-triggered observation/intervention at defined points (pre/post inference/tool, exit) with explicit actions (Halt/Skip/Modify). For policy/observability/redaction, not control flow.
+- **Steering**: operator-initiated control flow. Runtime decides when to poll, may inject messages, may skip current batches. Keep steering out of hooks.
+
+### Execution Mechanics (explicit, opt-in)
+
+- ToolExecutionStrategy (default: sequential). Optional barrier scheduling with Shared/Exclusive + batch flush + parallel shared tools.
+- SteeringSource polled at defined boundaries to inject mid-loop messages and optionally skip remaining tools.
+- Optional streaming tool API; forward chunks via ToolExecutionUpdate hook point. Streaming is observation-only; must not alter control flow.
+
+### Defaults
+
+- Slim for simple use cases. Advanced behavior opt-in via small, composable traits. No boolean soup.
+
+### Turn Engine Decomposition
+
+Prefer composing these primitives over monolithic loops:
+ContextAssembler, ToolExecutionPlanner, ConcurrencyDecider, BatchExecutor, SteeringSource, HookDispatcher, EffectSynthesizer, ExitController.
+
+### Tool Metadata
+
+- Source of truth for concurrency: Shared/Exclusive hints live on tool definition. Deciders read metadata first, may layer policy.
+
+### Limits
+
+- Single authority: budget/time/turns live in ExitController. Planners observe remaining budget/time (read-only).
+
+### Local vs Durable
+
+- LocalEffectExecutor: lean, in-order, best-effort.
+- Durable semantics (idempotency keys, retries, sagas) belong to durable orchestrators, not Layer 0 or local executors.
+- Orchestrator owns the reference effect interpreter and minimal signal/query semantics (local first, durable later).
+
+### Credentials
+
+- Resolved/injected via Environment + secret/auth/crypto backends. Tests must prove no secret leakage.
+
+### Invariants
+
+- Preserve tool_use → tool_result pairing; on steering, emit placeholders for skipped tools.
+- Refactor guardrail: behavior-preserving refactors must pass full test suite before adding new capabilities via decomposed traits.
+
+### Conformance
+
+- Golden tests prove provider swap, state swap, operator swap, and orchestration compose deterministically.
+- Enforce CI backpressure (fmt, clippy -D warnings, tests).
+
 ## Codifying Learnings (Build Your Stdlib)
 
 When a failure mode repeats or an agent needs steering:
@@ -76,47 +181,9 @@ When a failure mode repeats or an agent needs steering:
 
 Goal: make the correct outcome the path of least resistance.
 
-## Related Documents
-
-This repo already includes a deeper, Neuron-specific project guide in `CLAUDE.md`. Agents should
-consult it after the spec/rules stack when doing any substantial work.
-
 ## Loop Files
 
 This repo is designed to be run in a deterministic loop:
 
 1. `PROMPT.md` is the loop prompt.
 2. `ralph_queue.md` is the single prioritized queue.
-
-
-## Composability Philosophy (Neuron v2)
-
-- Layer 0 must stay stable: object-safe traits + serde wire types. Additive changes preferred; breaking changes are planned and versioned.
-- Effects are the side‑effect boundary: operators declare, orchestrators/environments execute. No direct writes from operators.
-- Hooks are for policy/observability/redaction, not control flow. Halt/Skip/Modify are explicit; do not encode scheduling in hooks.
-- Execution mechanics are explicit and opt‑in:
-  - ToolExecutionStrategy (default: sequential). Optional barrier scheduling with Shared/Exclusive + batch flush + parallel shared tools.
-  - SteeringSource polled at defined boundaries to inject mid‑loop messages and optionally skip remaining tools.
-  - Optional streaming tool API; forward chunks via a ToolExecutionUpdate hook point.
-- Defaults must remain slim for simple use cases. Advanced behavior is opt‑in and modular; avoid boolean soup.
-- Orchestrator owns the reference effect interpreter and minimal signal/query semantics (local first, durable later).
-- Credentials are resolved/injected via Environment + secret/auth/crypto backends; tests must prove no secret leakage.
-- Conformance: golden tests prove provider swap, state swap, operator swap, and orchestration compose deterministically.
-
-## Architecture Principles (Execution + Composability)
-
-- Layer 0 is protocol only: object-safe traits + serde wire types. No execution policy, no technology bindings, no durability semantics.
-- Effects boundary is sacred: operators declare; orchestrators/environments execute. Operators must not write state directly.
-- Hooks vs Steering:
-  - Hooks are event-triggered observation/intervention at defined points (pre/post inference/tool, exit) with explicit actions.
-  - Steering is operator-initiated control flow: the runtime decides when to poll, may inject messages, and may skip current batches. Keep steering out of hooks.
-- Defaults stay slim: sequential tools, no steering, no streaming, local best-effort effects. Advanced behavior is opt-in via small, composable traits (no boolean soup).
-- Turn engine decomposition: prefer composing these primitives over monolithic loops:
-  - ContextAssembler, ToolExecutionPlanner, ConcurrencyDecider, BatchExecutor, SteeringSource, HookDispatcher, EffectSynthesizer, ExitController.
-- Tool metadata is source of truth: concurrency hints (Shared/Exclusive) live on the tool definition; deciders read metadata first and may layer policy.
-- Single authority for limits: budget/time/turns live in ExitController; planners only observe remaining budget/time (read-only).
-- Local vs durable: keep LocalEffectExecutor lean (in-order, best-effort). Durable semantics (idempotency keys, retries, sagas) belong to durable orchestrators, not Layer 0 or local executors.
-- Streaming is observation-only: ToolExecutionUpdate is read-only; it must not alter control flow.
-- Invariants: preserve tool_use → tool_result pairing; on steering, emit placeholders for skipped tools.
-- Refactor guardrail: behavior-preserving refactors must pass the full test suite before adding new capabilities via decomposed traits.
-- Conformance: prove composition patterns (provider/state/operator/orchestration swaps) with golden tests; enforce CI backpressure (fmt, clippy -D warnings, tests).

CLAUDE.md

@@ -1,50 +1 @@
-# CLAUDE.md
-
-## What This Project Is
-
-Neuron is a Rust workspace implementing a 6-layer composable agentic AI architecture. Layer 0 (`layer0` crate) defines the stability contract — four protocol traits (Turn, Orchestrator, StateStore, Environment), two cross-cutting interfaces (Hook, Lifecycle events), and the message types that cross every boundary. Layers 1-5 build implementations on top.
-
-## Required Reading
-
-Before doing ANY work, read these documents IN ORDER:
-
-1. **NEURON-REDESIGN-PLAN.md** — The authoritative plan for the workspace redesign. 6-layer architecture, workspace structure, design decisions, phased implementation.
-2. **docs/architecture/HANDOFF.md** — Layer 0 implementation spec. Trait signatures, type definitions, module structure, layer definitions.
-3. **docs/architecture/composable-agentic-architecture.md** — Design rationale. 4 protocols + 2 interfaces, gap analysis, coverage map.
-4. **docs/architecture/platform-scope-mapping.md** — Where features live (Neuron vs platform vs external infra).
-5. **docs/architecture/agentic-decision-map-v3.md** — Full design space. All 23 architectural decisions.
-6. **DEVELOPMENT-LOG.md** — Complete history of all decisions, research, and rationale across all sessions.
-
-## Build & Test
-
-```bash
-cargo build
-cargo test
-cargo clippy -- -D warnings
-cargo doc --no-deps
-```
-
-All four must pass before any commit. For layer0 test-utils features:
-
-```bash
-cargo test --features test-utils -p layer0
-```
-
-## Rules
-
-### Do
-- Follow NEURON-REDESIGN-PLAN.md for all structural decisions
-- Match layer0 trait signatures exactly — they are the stability contract
-- Use `#[deny(missing_docs)]` on every public item
-- Test that every message type round-trips through serde_json
-- Test that every trait is object-safe (Box<dyn Trait> compiles and is Send + Sync)
-- Keep layer0 dependencies minimal (serde, async-trait, thiserror, rust_decimal — that's it)
-- Update DEVELOPMENT-LOG.md after each phase
-
-### Do Not
-- Add dependencies to layer0 beyond what's already there
-- Add methods to layer0 protocol traits beyond what HANDOFF.md defines
-- Change layer0's trait signatures — they are the stability contract
-- Make layer0 traits non-object-safe
-- Skip phases — the phased approach is sequential
-- Make undocumented decisions — update the plan first if deviating
+See [AGENTS.md](./AGENTS.md).