Merge pull request 'fix: fix: gardener enforces AGENTS.md size limit + progressive disclosure split (#480)' (#488) from fix/issue-480 into main

formulas/run-gardener.toml

@@ -261,16 +261,19 @@ CRITICAL: If this step fails, log the failure and move on.
 needs = ["dust-bundling"]
 
 # ─────────────────────────────────────────────────────────────────────
-# Step 5: agents-update — AGENTS.md watermark staleness check
+# Step 5: agents-update — AGENTS.md watermark staleness + size enforcement
 # ─────────────────────────────────────────────────────────────────────
 
 [[steps]]
 id    = "agents-update"
-title = "Check AGENTS.md watermarks, update stale files"
+title = "Check AGENTS.md watermarks, update stale files, enforce size limit"
 description = """
-Check all AGENTS.md files for staleness and update any that are outdated.
+Check all AGENTS.md files for staleness, update any that are outdated, and
+enforce the ~200-line size limit via progressive disclosure splitting.
 This keeps documentation fresh — runs 2x/day so drift stays small.
 
+## Part A: Watermark staleness check and update
+
 1. Read the HEAD SHA from preflight:
      HEAD_SHA=$(cat /tmp/gardener-head-sha)
 
@@ -288,12 +291,93 @@ This keeps documentation fresh — runs 2x/day so drift stays small.
    - Read the AGENTS.md and the source files in that directory
    - Update the documentation to reflect code changes since the watermark
    - Set the watermark to the HEAD SHA from the preflight step
-   - Conventions: max ~200 lines, architecture and WHY not implementation details
+   - Conventions: architecture and WHY not implementation details
 
-6. Stage ONLY the AGENTS.md files you changed — do NOT commit yet.
+## Part B: Size limit enforcement (progressive disclosure split)
-   All git writes happen in the commit-and-pr step at the end.
 
-7. If no AGENTS.md files need updating, skip this step entirely.
+After all updates are done, count lines in the root AGENTS.md:
+     wc -l < "$PROJECT_REPO_ROOT/AGENTS.md"
+
+If the root AGENTS.md exceeds 200 lines, perform a progressive disclosure
+split. The principle: agent reads the map, drills into detail only when
+needed. You wouldn't dump a 500-page wiki on a new hire's first morning.
+
+6. Identify per-directory sections to extract. Each agent section under
+   "## Agents" (e.g. "### Dev (`dev/`)", "### Review (`review/`)") and
+   each helper section (e.g. "### Shared helpers (`lib/`)") is a candidate.
+   Also extract verbose subsections like "## Issue lifecycle and label
+   conventions" and "## Phase-Signaling Protocol" into docs/ or the
+   relevant directory.
+
+7. For each section to extract, create a `{dir}/AGENTS.md` file with:
+   - Line 1: watermark <!-- last-reviewed: <HEAD_SHA> -->
+   - The full section content (role, trigger, key files, env vars, lifecycle)
+   - Keep the same markdown structure and detail level
+
+   Example for dev/:
+   ```
+   <!-- last-reviewed: abc123 -->
+   # Dev Agent
+
+   **Role**: Implement issues autonomously ...
+   **Trigger**: dev-poll.sh runs every 10 min ...
+   **Key files**: ...
+   **Environment variables consumed**: ...
+   **Lifecycle**: ...
+   ```
+
+8. Replace extracted sections in the root AGENTS.md with a concise
+   directory map table. The root file keeps ONLY:
+   - Watermark (line 1)
+   - ## What this repo is (brief overview)
+   - ## Directory layout (existing tree)
+   - ## Tech stack
+   - ## Coding conventions
+   - ## How to lint and test
+   - ## Agents — replaced with a summary table pointing to per-dir files:
+
+     ## Agents
+
+     | Agent | Directory | Role | Guide |
+     |-------|-----------|------|-------|
+     | Dev | dev/ | Issue implementation | [dev/AGENTS.md](dev/AGENTS.md) |
+     | Review | review/ | PR review | [review/AGENTS.md](review/AGENTS.md) |
+     | Gardener | gardener/ | Backlog grooming | [gardener/AGENTS.md](gardener/AGENTS.md) |
+     | ... | ... | ... | ... |
+
+   - ## Shared helpers — replaced with a brief pointer:
+     "See [lib/AGENTS.md](lib/AGENTS.md) for the full helper reference."
+     Keep the summary table if it fits, or move it to lib/AGENTS.md.
+
+   - ## Issue lifecycle and label conventions — keep a brief summary
+     (labels table + dependency convention) or move verbose parts to
+     docs/PHASE-PROTOCOL.md
+
+   - ## Architecture Decisions — keep in root (humans write, agents enforce)
+
+   - ## Phase-Signaling Protocol — keep a brief summary with pointer:
+     "See [docs/PHASE-PROTOCOL.md](docs/PHASE-PROTOCOL.md) for the full spec."
+
+9. Verify the root AGENTS.md is now under 200 lines:
+     LINE_COUNT=$(wc -l < "$PROJECT_REPO_ROOT/AGENTS.md")
+     if [ "$LINE_COUNT" -gt 200 ]; then
+       echo "WARNING: root AGENTS.md still $LINE_COUNT lines after split"
+     fi
+   If still over 200, trim further — move more detail into per-directory
+   files. The root should read like a table of contents, not an encyclopedia.
+
+10. Each new per-directory AGENTS.md must have a watermark on line 1.
+    The gardener maintains freshness for ALL AGENTS.md files — root and
+    per-directory — using the same watermark mechanism from Part A.
+
+## Staging
+
+11. Stage ALL AGENTS.md files you created or changed — do NOT commit yet.
+    All git writes happen in the commit-and-pr step at the end:
+      find . -name "AGENTS.md" -not -path "./.git/*" -exec git add {} +
+
+12. If no AGENTS.md files need updating AND root is under 200 lines,
+    skip this step entirely.
 
 CRITICAL: If this step fails for any reason, log the failure and move on.
 Do NOT let an AGENTS.md failure prevent the commit-and-pr step.