Document recursion rule for agents

Author: code5717

AGENT.md

@@ -20,5 +20,13 @@ Compatibility pointer for tools that look for a singular `AGENT.md`.
 - Package build: `uv build`
 - Docs site build: `cd site && npm install && npm run build`
 
+## Key Rules (short form)
+
+- A7 source recursion is banned; the compiler reports direct and mutual
+  recursion as semantic errors. Use loops, explicit stacks, or index-based
+  worklists in examples and tests.
+- Keep `README.md`, `docs/SPEC.md`, `CHANGELOG.md`, `MISSING_FEATURES.md`,
+  and `TODO.md` aligned with any user-visible change.
+
 See `AGENTS.md` for the full workflow, post-change checklist, and security
 caveats.

AGENTS.md

@@ -27,6 +27,17 @@ backend tests, example e2e, debug + release artifacts, error-stage matrix,
 docs style). Run it before tagging or before reporting a task as done when
 changes are non-trivial.
 
+## A7 Source Rules
+
+- A7 source recursion is banned. Semantic validation rejects both direct and
+  mutual recursion as compile-time errors; do not author examples, tests, or
+  docs that rely on recursive A7 functions.
+- Port recursive algorithms to loops, explicit stacks, or index-based
+  worklists (see `examples/025_linked_list.a7` and
+  `examples/026_binary_tree.a7` for the expected style).
+- This rule applies to A7 source only. Compiler internals already use
+  iterative AST traversals; keep them that way.
+
 ## Post-Change Checklist
 
 After making major changes (new language features, bug fixes, backend
@@ -39,6 +50,10 @@ committing:
 4. **MISSING_FEATURES.md** — mark completed gaps or document new ones
 5. **TODO.md** — check off completed items or add newly discovered work
 
+Keep examples and docs aligned across `README.md`, `docs/SPEC.md`,
+`CHANGELOG.md`, `MISSING_FEATURES.md`, and `TODO.md` — drift between them is
+treated as a bug.
+
 ## Security Caveat
 
 `a7-py` is **not** a sandbox for untrusted source. The compiler emits Zig or C

CLAUDE.md

@@ -26,6 +26,17 @@ the `main.py` wrapper when working from a fresh checkout.
 backend tests, example e2e, debug + release artifacts, error-stage matrix,
 docs style). Run it before reporting a non-trivial task as done.
 
+## A7 Source Rules
+
+- A7 source recursion is banned. Semantic validation rejects both direct and
+  mutual recursion as compile-time errors; do not introduce examples, tests,
+  or docs that rely on recursive A7 functions.
+- Prefer loops, explicit stacks, or index-based worklists when porting
+  recursive algorithms (see `examples/025_linked_list.a7`,
+  `examples/026_binary_tree.a7`).
+- This rule applies to A7 source only. Compiler internals already use
+  iterative AST traversals; keep them that way.
+
 ## Post-Change Checklist
 
 When language features, backends, or user-facing behavior change, update:
@@ -36,6 +47,10 @@ When language features, backends, or user-facing behavior change, update:
 4. `MISSING_FEATURES.md` — close or open gaps
 5. `TODO.md` — check off or add follow-ups
 
+Keep examples and docs aligned across `README.md`, `docs/SPEC.md`,
+`CHANGELOG.md`, `MISSING_FEATURES.md`, and `TODO.md` — drift between them is
+treated as a bug.
+
 ## Security Caveat
 
 `a7-py` is **not** a sandbox for untrusted source. The compiler emits Zig or C