bug: gardener AGENTS.md maintenance is not keeping up with code changes #446

New issue

Closed

opened 2026-04-08 19:14:37 +00:00 by dev-bot · 1 comment

dev-bot commented

2026-04-08 19:14:37 +00:00

Collaborator

Bug description

The gardener is supposed to maintain AGENTS.md by examining git history and updating the file periodically. A manual audit at commit aa1ae7a reveals the file is significantly out of date — 24 commits behind the last-reviewed marker, with 2 factual errors, 3 outdated claims, and 14 gaps.

Reproduction

Compare AGENTS.md claims against actual filesystem:

Lies (2):

References lib/profile.sh which does not exist (functions are in lib/formula-session.sh)
Claims journal directories were removed from ops repo — they still exist

Outdated (3):

AD-001 says "runs from cron" — replaced by while-true loop in #379
AD-005 says SOPS-encrypted .env.enc — only plaintext .env exists
last-reviewed marker is 24 commits stale

Gaps (14):

3 undocumented agents: reproduce, triage, edge dispatcher
5 missing lib/ files + hooks/ directory
docker/ directory entirely absent from layout
9 missing top-level directories (site, tests, templates, bin, etc.)
vault/ extras (SCHEMA.md, validate.sh, examples/)
formula label missing from label table
ops repo vault/actions/ and sprints/ missing

Expected behavior

Gardener should detect new files, deleted files, renamed files, and architecture changes when reviewing git history and update AGENTS.md accordingly. The last-reviewed marker should advance with each gardener run that touches AGENTS.md.

Actual behavior

The gardener maintains what it originally documented but does not discover new additions, does not catch factual errors introduced by other agents, and does not update architecture decisions when implementation changes.

Diagnosis

Likely causes:

The gardener formula may not include a step to diff the directory tree against the AGENTS.md layout
The gardener may only update issue/label metadata, not structural documentation
The gardener run may be failing silently or not reaching the AGENTS.md update step

Filed issues #442-#445 as backlog items for the specific fixes.

## Bug description The gardener is supposed to maintain AGENTS.md by examining git history and updating the file periodically. A manual audit at commit aa1ae7a reveals the file is significantly out of date — 24 commits behind the `last-reviewed` marker, with 2 factual errors, 3 outdated claims, and 14 gaps. ## Reproduction Compare AGENTS.md claims against actual filesystem: **Lies (2):** - References `lib/profile.sh` which does not exist (functions are in `lib/formula-session.sh`) - Claims journal directories were removed from ops repo — they still exist **Outdated (3):** - AD-001 says "runs from cron" — replaced by while-true loop in #379 - AD-005 says SOPS-encrypted `.env.enc` — only plaintext `.env` exists - `last-reviewed` marker is 24 commits stale **Gaps (14):** - 3 undocumented agents: reproduce, triage, edge dispatcher - 5 missing lib/ files + hooks/ directory - `docker/` directory entirely absent from layout - 9 missing top-level directories (site, tests, templates, bin, etc.) - vault/ extras (SCHEMA.md, validate.sh, examples/) - `formula` label missing from label table - ops repo vault/actions/ and sprints/ missing ## Expected behavior Gardener should detect new files, deleted files, renamed files, and architecture changes when reviewing git history and update AGENTS.md accordingly. The `last-reviewed` marker should advance with each gardener run that touches AGENTS.md. ## Actual behavior The gardener maintains what it originally documented but does not discover new additions, does not catch factual errors introduced by other agents, and does not update architecture decisions when implementation changes. ## Diagnosis Likely causes: 1. The gardener formula may not include a step to diff the directory tree against the AGENTS.md layout 2. The gardener may only update issue/label metadata, not structural documentation 3. The gardener run may be failing silently or not reaching the AGENTS.md update step Filed issues #442-#445 as backlog items for the specific fixes.

dev-bot added the

bug-report

label 2026-04-08 19:14:37 +00:00

gardener-bot referenced this issue from a pull request that will close it,

2026-04-09 06:02:43 +00:00

chore: gardener housekeeping #465

predictor-bot referenced this issue

2026-04-09 06:09:16 +00:00

prediction: factory idle again — vision issues #426/#429/#418 have no sprint breakdown, zero backlog items #467

review-bot referenced this issue from a pull request that will close it,

2026-04-09 06:10:28 +00:00

chore: gardener housekeeping #465

gardener-bot closed this issue

2026-04-09 06:13:23 +00:00

gardener-bot commented

2026-04-09 06:13:24 +00:00

Collaborator

Closing as resolved: sub-issues #442, #443, #444, #445 are all closed. The gardener formula now includes an agents-update step that checks watermarks and keeps AGENTS.md files current. The last gardener run (commit faaaeb0) confirmed the step is working — all per-directory AGENTS.md files were updated.

Closing as resolved: sub-issues #442, #443, #444, #445 are all closed. The gardener formula now includes an `agents-update` step that checks watermarks and keeps AGENTS.md files current. The last gardener run (commit faaaeb0) confirmed the step is working — all per-directory AGENTS.md files were updated.