Merge pull request 'chore: gardener housekeeping' (#606) from chore/gardener-20260323-1247 into main

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Disinto — Agent Instructions
 
 ## What this repo is

action/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Action Agent
 
 **Role**: Execute operational tasks described by action formulas — run scripts,

dev/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Dev Agent
 
 **Role**: Implement issues autonomously — write code, push branches, address

gardener/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Gardener Agent
 
 **Role**: Backlog grooming — detect duplicate issues, missing acceptance

gardener/pending-actions.json

@@ -1,12 +1,12 @@
 [
   {
     "action": "edit_body",
-    "issue": 598,
+    "issue": 466,
-    "body": "## Problem\n\nThe gardener promotes tech-debt issues to backlog by swapping labels, but does not enrich the issue body. The quality gate (#483) then strips the backlog label because required sections are missing. Circular loop — issue bounces between tech-debt and backlog.\n\nExample: #435 — \"monitor_phase_loop docstring lists 'break' as possible value but never set.\" Body is a bare review finding with no `## Acceptance criteria` or `## Affected files`. The gardener promotes it, quality gate strips it, repeat.\n\n## Fix\n\nWhen the gardener promotes an issue to backlog (from tech-debt or any other label), it must also enrich the issue body to meet the quality gate requirements.\n\nDuring the grooming step, for each issue being promoted:\n\n1. **Infer affected files** from the issue body. The information is usually there — #435 mentions `lib/agent-session.sh:266` explicitly. Use AGENTS.md knowledge to fill gaps.\n\n2. **Write acceptance criteria** based on the problem description.\n\n3. Append both sections to the issue body via the `edit_body` manifest action before adding the backlog label.\n\n## Affected files\n\n- `formulas/run-gardener.toml` — grooming step: add body enrichment logic before writing add_label backlog to manifest\n\n## Acceptance criteria\n\n- [ ] Gardener enriches issue body (appends `## Affected files` + `## Acceptance criteria`) when promoting to backlog\n- [ ] Promoted issues pass the quality gate on the same gardener run (backlog label not stripped)\n- [ ] Affected files are inferred from existing issue body text when possible"
+    "body": "## Problem\n\nVISION.md Adoption milestone calls for an \"Example project that demonstrates the full lifecycle\" but no such project exists. New developers evaluating disinto have no reference for what the end-to-end flow looks like — from `disinto init` through issue creation, dev-agent implementation, CI, review, merge, and deployment.\n\n## Why it matters\n\nDocumentation (#394) and the landing page need a concrete example to reference. Abstract descriptions of the agent loop are less convincing than a working repo where people can see real PRs, real CI runs, and real reviews. This is the \"show, don't tell\" for adoption.\n\n## Approach\n\n1. Create a minimal example repo (e.g., `johba/disinto-example` or a directory within this repo) with:\n   - A simple web app (e.g., Express/Flask hello world)\n   - A `projects/*.toml` config pointing at the example repo\n   - A VISION.md with 3-4 simple goals\n   - CI pipeline (.woodpecker.yml)\n2. Run the factory against it: let the planner create issues, dev-agent implement them, review-agent review.\n3. Document the results: link to merged PRs, show the issue lifecycle, capture agent conversations.\n4. Reference from the docs site (#394) and landing page.\n\n## Dependencies\n\n- #393 (disinto init would make bootstrapping the example trivial)\n\n## Affected files\n\n- `projects/disinto-example.toml.example` — new example project config template\n- `README.md` or `docs/` — documentation referencing the example project\n\n## Acceptance criteria\n\n- [ ] A working example repo exists with at least 3 merged PRs from the factory\n- [ ] The docs site references the example with links to real PRs and issues\n- [ ] A new developer can follow the example to understand the full lifecycle"
   },
   {
     "action": "add_label",
-    "issue": 598,
+    "issue": 466,
     "label": "backlog"
   }
 ]

lib/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Shared Helpers (`lib/`)
 
 All agents source `lib/env.sh` as their first action. Additional helpers are

planner/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Planner Agent
 
 **Role**: Strategic planning using a Prerequisite Tree (Theory of Constraints),
@@ -11,12 +11,15 @@ project-specific formulas (`$PROJECT_REPO_ROOT/formulas/*.toml`). Phase 1
 Predictor — for each prediction: promote to action, promote to backlog, watch
 (relabel to prediction/backlog), or dismiss with reasoning. Phase 2
 (update-prerequisite-tree): scan repo state + open/closed issues, mark resolved
-prerequisites, discover new ones, update the tree. Phase 3
+prerequisites, discover new ones, update the tree. **Also scans comments on
+referenced issues for bounce/stuck signals** (BOUNCED, ESCALATED, LABEL_CHURN)
+to detect issues ping-ponging between backlog and underspecified. Phase 3
 (file-at-constraints): identify the top 3 unresolved prerequisites that block
-the most downstream objectives — file issues at these constraints as either
+the most downstream objectives — file issues as either `backlog` (code changes,
-`backlog` (code changes, dev-agent) or `action` (run existing formula,
+dev-agent) or `action` (run existing formula, action-agent). **Stuck issues
-action-agent). Action issues count toward the 3-issue constraint budget — they
+(detected BOUNCED/LABEL_CHURN) are dispatched to the `groom-backlog` formula
-are strategic investments, not maintenance.
+in breakdown mode instead of being re-promoted** — this breaks the ping-pong
+loop by splitting them into dev-agent-sized sub-issues.
 Phase 4 (journal-and-memory): write updated prerequisite tree + daily journal
 entry (committed to git) and update `planner/MEMORY.md` (committed to git).
 Phase 5 (commit-and-pr): one commit with all file changes, push, create PR.
@@ -41,6 +44,9 @@ issues — the planner is a nervous system component, not work.
   prediction-triage, update-prerequisite-tree, file-at-constraints,
   journal-and-memory, commit-and-pr) with `needs` dependencies. Claude
   executes all steps in a single interactive session with tool access
+- `formulas/groom-backlog.toml` — Dual-mode formula: grooming (default) or
+  breakdown (dispatched by planner for bounced/stuck issues — splits the issue
+  into dev-agent-sized sub-issues, removes `underspecified` label)
 - `planner/prerequisite-tree.md` — Prerequisite tree: versioned constraint
   map linking VISION.md objectives to their prerequisites. Planner owns the
   tree, humans steer by editing VISION.md. Tree grows organically as the

predictor/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Predictor Agent
 
 **Role**: Risk oracle and opportunity spotter (the "goblin"). Runs a 4-step

review/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Review Agent
 
 **Role**: AI-powered PR review — post structured findings and formal

supervisor/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Supervisor Agent
 
 **Role**: Health monitoring and auto-remediation, executed as a formula-driven

vault/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: f6fb79d94badca6ef2d3a7a8545ad701ff2b6cfc -->
+<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
 # Vault Agent
 
 **Role**: Dual-purpose gate — action safety classification and resource procurement.