feat(aiignore): add .aiignore and the recursive-read convention

Agents (and any future inventory tool) doing a naive recursive read of a project pick up node_modules, __pycache__, build output, and token artifacts even when those are gitignored, because a recursive read sees the disk, not git. I added a gitignore-syntax .aiignore at the repo root with the default skip list, and a protocols.org "Recursive Reads" subsection documenting the convention, the defaults to assume absent a file, and the lockfile policy (skip on agent reads, independent of git-tracking).

I did not wire the walking scripts (audit.sh, diff-lang.sh, sync-language-bundle.sh): they do targeted finds over .ai/.claude/bundle dirs, never whole-tree walks, so honoring .aiignore there would be dead code. That belongs in a future catalog tool.

4 files changed, 61 insertions, 1 deletions

diff --git a/.ai/protocols.org b/.ai/protocols.org
index 25e634a..cf1b7f6 100644
--- a/.ai/protocols.org
+++ b/.ai/protocols.org
@@ -190,6 +190,14 @@ Check =inbox/= at every task boundary (after finishing a unit of work, before re
 
 Exit 1 means handoffs are pending — process them per =process-inbox.org=. For each accepted handoff, the act-vs-file rule: *act now* when it's clear, bounded, low-risk, in-scope, and cheaper than deferring — just do it, no asking; *file* otherwise — ask first, with filing as option 1 and "do it now" as option 2; *ask* if unsure. Always reply to a handoff's sender (confirm on accept, the why on reject). Full process, the reply discipline, and the opt-in background-monitor =/loop= recipe live in =monitor-inbox.org=.
 
+** Recursive Reads — Honor =.aiignore=
+
+Before a naive recursive read or glob of a project tree (file inventories, "what's in this repo", broad greps), skip the noise: dependency trees (=node_modules/=, =.venv/=), build output (=dist/=, =build/=, =coverage/=), language caches (=__pycache__/=, =.pytest_cache/=, =*.pyc=), editor/OS cruft, and generated token/OAuth artifacts. These waste tokens and skew project summaries even when gitignored — a recursive read sees the disk, not git.
+
+If the project root has a =.aiignore= (gitignore syntax), honor its patterns; it carries project-specific additions. rulesets ships one as the canonical example. Absent a file, assume the defaults above.
+
+Lockfile policy: skip lockfiles on agent reads (large and low-signal). That's about what agents read, not what git tracks for reproducibility.
+
 * Important Terminology
 
 ** "Let's run the [X] workflow" vs "I want to create an [X] workflow"
diff --git a/.aiignore b/.aiignore
new file mode 100644
index 0000000..903f5f1
--- /dev/null
+++ b/.aiignore
@@ -0,0 +1,42 @@
+# .aiignore — paths agents and inventory tooling should skip on recursive reads.
+#
+# Same syntax as .gitignore. These are noise during exploration (machine-
+# specific caches, dependency trees, build output) that waste tokens and skew
+# project summaries even when gitignored — a recursive read sees the disk, not
+# git. This file is rulesets' own copy and the canonical example; a project may
+# add its own patterns. The convention and defaults are documented in
+# .ai/protocols.org ("Recursive Reads").
+
+# Dependency trees
+node_modules/
+.venv/
+venv/
+vendor/
+
+# Python build / cache
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# JS/TS build + coverage
+dist/
+build/
+coverage/
+.next/
+.cache/
+
+# Editor / OS cruft
+.DS_Store
+*.swp
+
+# Generated auth / token artifacts
+token.json
+*.token.json
+
+# Lockfiles: skipped on agent reads (large, low-signal). This is about what
+# agents read, not what git tracks — a project still tracks these for
+# reproducibility where that matters.
+package-lock.json
+uv.lock
diff --git a/claude-templates/.ai/protocols.org b/claude-templates/.ai/protocols.org
index 25e634a..cf1b7f6 100644
--- a/claude-templates/.ai/protocols.org
+++ b/claude-templates/.ai/protocols.org
@@ -190,6 +190,14 @@ Check =inbox/= at every task boundary (after finishing a unit of work, before re
 
 Exit 1 means handoffs are pending — process them per =process-inbox.org=. For each accepted handoff, the act-vs-file rule: *act now* when it's clear, bounded, low-risk, in-scope, and cheaper than deferring — just do it, no asking; *file* otherwise — ask first, with filing as option 1 and "do it now" as option 2; *ask* if unsure. Always reply to a handoff's sender (confirm on accept, the why on reject). Full process, the reply discipline, and the opt-in background-monitor =/loop= recipe live in =monitor-inbox.org=.
 
+** Recursive Reads — Honor =.aiignore=
+
+Before a naive recursive read or glob of a project tree (file inventories, "what's in this repo", broad greps), skip the noise: dependency trees (=node_modules/=, =.venv/=), build output (=dist/=, =build/=, =coverage/=), language caches (=__pycache__/=, =.pytest_cache/=, =*.pyc=), editor/OS cruft, and generated token/OAuth artifacts. These waste tokens and skew project summaries even when gitignored — a recursive read sees the disk, not git.
+
+If the project root has a =.aiignore= (gitignore syntax), honor its patterns; it carries project-specific additions. rulesets ships one as the canonical example. Absent a file, assume the defaults above.
+
+Lockfile policy: skip lockfiles on agent reads (large and low-signal). That's about what agents read, not what git tracks for reproducibility.
+
 * Important Terminology
 
 ** "Let's run the [X] workflow" vs "I want to create an [X] workflow"
diff --git a/todo.org b/todo.org
index 2535a36..218a1ba 100644
--- a/todo.org
+++ b/todo.org
@@ -1276,7 +1276,9 @@ Three wins: handoff is one paste not a re-read; forces specs to be implementable
 
 If the spec lacks an =Implementation phases= section, the step is the prompt to ask the author to add one before =Ready=.
 
-** TODO [#C] Add =.aiignore= for agent inventory exclusions :chore:solo:
+** DONE [#C] Add =.aiignore= for agent inventory exclusions :chore:solo:
+CLOSED: [2026-05-31 Sun]
+Shipped a gitignore-syntax =.aiignore= at the rulesets root (deps, build output, language caches, editor cruft, token artifacts, lockfiles-as-agent-read-skip) and documented the convention + defaults + lockfile policy in protocols.org ("Recursive Reads"). Per Craig's scope call (2026-05-31): did NOT wire audit.sh / diff-lang.sh / sync-language-bundle.sh — they do targeted finds over .ai/.claude/bundle dirs, never naive whole-tree walks, so honoring .aiignore there would be dead code. Script-side honoring belongs in a future catalog/inventory tool if one ships; the real consumer today is agent recursive reads (the protocols guidance).
 :PROPERTIES:
 :CREATED: [2026-05-28 Thu]
 :LAST_REVIEWED: 2026-05-28