docs: bound documentation and comment length in template AGENTS.md

Ports the added-fact rule from agentic-engineering-loop#434. The template
enforces docstring presence (ruff D, numpy convention) but nothing bounded
their length, so agents in a generated project produced Parameters/Returns
blocks that restate annotations and docstrings that only grow.

The new Documentation and Comment Style section states the rule: past the
summary line, a line must carry a fact the code cannot.

Also assert AGENTS.md and CLAUDE.md land in the generated project, and that
AGENTS.md has no unresolved Jinja placeholders.

Author: mariushelf

template/AGENTS.md.jinja

@@ -70,3 +70,40 @@ those blocks once you start modelling your own domain.
 {%- else %}
 - `make lint` runs ruff and the `ty` type checker.
 {%- endif %}
+
+## Documentation and Comment Style
+
+Brevity is not tidiness — it is what gets the text read. A docstring, comment,
+or page nobody reads still has to be maintained, so it is worse than none.
+
+Docstring *presence* is enforced by ruff's `D` rules (numpy convention) in
+`pyproject.toml`. This section bounds their *length*.
+
+The unit of judgement is the *added fact*: after the summary line, every line
+must tell the reader something they cannot get from the name, the signature,
+the type hints, or the code itself.
+
+Earns more than a summary line:
+
+- a contract the signature doesn't show — preconditions, invariants, what it
+  raises
+- units, bounds, or formats a type can't carry (`timeout: float` — seconds or
+  milliseconds?)
+- caller-visible behaviour that would surprise — mutation, ordering,
+  idempotency, blocking, retries, cost (a network round-trip, an LLM call)
+- a pointer to the *why* when it isn't obvious (link the issue or ADR, don't
+  restate it)
+
+Does not:
+
+- restating the signature, or a numpy `Parameters`/`Returns` section where the
+  name and type already say it
+- narrating the implementation step by step — that's the code
+- history ("previously…", "refactored to…") — that's git
+- examples for a function whose use is obvious from its name
+
+The same rule governs prose: the README covers what a reader needs to install,
+run, and maintain the project; implementation detail belongs in the code.
+Prefer a list, table, or short code example over paragraphs. When editing an
+existing docstring, comment, or page, it must not get longer unless behaviour
+was added.

tests/test_template.py

@@ -63,6 +63,10 @@ def test_template_renders(project):
     assert (project.path / "src" / "test_project" / "__init__.py").is_file()
     assert (project.path / "src" / "test_project" / "main.py").is_file()
     assert (project.path / "tests" / "test_test_project.py").is_file()
+    assert (project.path / "AGENTS.md").is_file()
+    assert (project.path / "CLAUDE.md").is_file()
+    # AGENTS.md is rendered from a .jinja source, so placeholders must resolve.
+    assert "{{" not in (project.path / "AGENTS.md").read_text(encoding="utf-8")
 
     domain = project.path / "src" / "test_project" / "domain"
     example_test = project.path / "tests" / "test_example_notes.py"