# formulas/run-gardener.toml — Gardener housekeeping formula
#
# Defines the gardener's complete run: grooming (Claude session via
# gardener-run.sh) + blocked-review + AGENTS.md maintenance + final
# commit-and-pr.
#
# No memory, no journal. The gardener does mechanical housekeeping
# based on current state — it doesn't need to remember past runs.
#
# Steps: preflight → grooming → dust-bundling → blocked-review → agents-update → commit-and-pr

name        = "run-gardener"
description = "Mechanical housekeeping: grooming, blocked review, docs update"
version     = 1

[context]
files = ["AGENTS.md", "VISION.md", "README.md"]

# ─────────────────────────────────────────────────────────────────────
# Step 1: preflight
# ─────────────────────────────────────────────────────────────────────

[[steps]]
id    = "preflight"
title = "Pull latest code"
description = """
Set up the working environment for this gardener run.

1. Change to the project repository:
     cd "$PROJECT_REPO_ROOT"

2. Pull the latest code:
     git fetch origin "$PRIMARY_BRANCH" --quiet
     git checkout "$PRIMARY_BRANCH" --quiet
     git pull --ff-only origin "$PRIMARY_BRANCH" --quiet

3. Record the current HEAD SHA for AGENTS.md watermarks:
     HEAD_SHA=$(git rev-parse HEAD)
     echo "$HEAD_SHA" > /tmp/gardener-head-sha
"""

# ─────────────────────────────────────────────────────────────────────
# Step 2: grooming — Claude-driven backlog grooming
# ─────────────────────────────────────────────────────────────────────

[[steps]]
id    = "grooming"
title = "Backlog grooming — triage all open issues"
description = """
Groom the open issue backlog. This step is the core Claude-driven analysis
(Claude performs pre-checks inline before deeper analysis).

Pre-checks (bash, zero tokens — detect problems before invoking Claude):

1. Fetch all open issues:
     curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/issues?state=open&type=issues&limit=50&sort=updated&direction=desc"

2. Duplicate detection: compare issue titles pairwise. Normalize
   (lowercase, strip prefixes like feat:/fix:/refactor:, collapse whitespace)
   and flag pairs with >60% word overlap as possible duplicates.

3. Missing acceptance criteria: flag issues with body < 100 chars and
   no checkboxes (- [ ] or - [x]).

4. Stale issues: flag issues with no update in 14+ days.

5. Blockers starving the factory (HIGHEST PRIORITY): find issues that
   block backlog items but are NOT themselves labeled backlog. These
   starve the dev-agent completely. Extract deps from ## Dependencies /
   ## Depends on / ## Blocked by sections of backlog issues and check
   if each dependency is open + not backlog-labeled.

6. Tech-debt promotion: list all tech-debt labeled issues — goal is to
   process them all (promote to backlog or classify as dust).

For each issue, choose ONE action and write to result file:

ACTION (substantial — promote, close duplicate, add acceptance criteria):
  echo "ACTION: promoted #NNN to backlog — <reason>" >> "$RESULT_FILE"
  echo "ACTION: closed #NNN as duplicate of #OLDER" >> "$RESULT_FILE"

DUST (trivial — single-line edit, rename, comment, style, whitespace):
  echo 'DUST: {"issue": NNN, "group": "<file-or-subsystem>", "title": "...", "reason": "..."}' >> "$RESULT_FILE"
  Group by file or subsystem (e.g. "gardener", "lib/env.sh", "dev-poll").
  Do NOT close dust issues — the dust-bundling step auto-bundles groups
  of 3+ into one backlog issue.

ESCALATE (needs human decision):
  printf 'ESCALATE\n1. #NNN "title" — reason (a) option1 (b) option2\n' >> "$RESULT_FILE"

CLEAN (only if truly nothing to do):
  echo 'CLEAN' >> "$RESULT_FILE"

Dust vs ore rules:
  Dust: comment fix, variable rename, whitespace/formatting, single-line edit, trivial cleanup with no behavior change
  Ore:  multi-file changes, behavioral fixes, architectural improvements, security/correctness issues

Sibling dependency rule (CRITICAL):
  Issues from the same PR review or code audit are SIBLINGS — independent work items.
  NEVER add bidirectional ## Dependencies between siblings (creates deadlocks).
  Use ## Related for cross-references: "## Related\n- #NNN (sibling)"

7. Architecture decision alignment check (AD check):
   For each open issue labeled 'backlog', check whether the issue
   contradicts any architecture decision listed in the
   ## Architecture Decisions section of AGENTS.md.
   Read AGENTS.md and extract the AD table. For each backlog issue,
   compare the issue title and body against each AD. If an issue
   clearly violates an AD:
   a. Post a comment explaining the violation:
        curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<number>/comments" \
          -d '{"body":"Closing: violates AD-NNN (<decision summary>). See AGENTS.md § Architecture Decisions."}'
   b. Close the issue:
        curl -sf -X PATCH -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<number>" \
          -d '{"state":"closed"}'
   c. Log to the result file:
        echo "ACTION: closed #NNN — violates AD-NNN" >> "$RESULT_FILE"

   Only close for clear, unambiguous violations. If the issue is
   borderline or could be interpreted as compatible, leave it open
   and ESCALATE instead.

Processing order:
  1. Handle PRIORITY_blockers_starving_factory first — promote or resolve
  2. AD alignment check — close backlog issues that violate architecture decisions
  3. Process tech-debt issues by score (impact/effort)
  4. Classify remaining items as dust or escalate

Do NOT bundle dust yourself — the dust-bundling step handles accumulation,
dedup, TTL expiry, and bundling into backlog issues.

CRITICAL: If this step fails for any reason, log the failure and move on.
"""
needs = ["preflight"]

# ─────────────────────────────────────────────────────────────────────
# Step 3: dust-bundling — accumulate, expire, and bundle dust items
# ─────────────────────────────────────────────────────────────────────

[[steps]]
id    = "dust-bundling"
title = "Accumulate dust, expire stale entries, and bundle groups"
description = """
Process DUST items emitted during grooming. This step maintains the
persistent dust accumulator at $PROJECT_REPO_ROOT/gardener/dust.jsonl.

IMPORTANT: Use $PROJECT_REPO_ROOT/gardener/dust.jsonl (the main repo
checkout), NOT the worktree copy — the worktree is destroyed after the
session, so changes there would be lost.

1. Collect DUST JSON lines emitted during grooming (from the result file
   or your notes). Each has: {"issue": NNN, "group": "...", "title": "...", "reason": "..."}

2. Deduplicate: read existing dust.jsonl and skip any issue numbers that
   are already staged:
     DUST_FILE="$PROJECT_REPO_ROOT/gardener/dust.jsonl"
     touch "$DUST_FILE"
     EXISTING=$(jq -r '.issue' "$DUST_FILE" 2>/dev/null | sort -nu || true)
   For each new dust item, check if its issue number is in EXISTING.
   Add new entries with a timestamp:
     echo '{"issue":NNN,"group":"...","title":"...","reason":"...","ts":"YYYY-MM-DDTHH:MM:SSZ"}' >> "$DUST_FILE"

3. Expire stale entries (30-day TTL):
     CUTOFF=$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ)
     jq -c --arg c "$CUTOFF" 'select(.ts >= $c)' "$DUST_FILE" > "${DUST_FILE}.tmp" && mv "${DUST_FILE}.tmp" "$DUST_FILE"

4. Bundle groups with 3+ distinct issues:
   a. Count distinct issues per group:
        jq -r '[.group, (.issue | tostring)] | join("\\t")' "$DUST_FILE" | sort -u | cut -f1 | sort | uniq -c | sort -rn
   b. For each group with count >= 3:
      - Collect issue details and distinct issue numbers for the group
      - Look up the backlog label ID:
          BACKLOG_LABEL_ID=$(curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
            "$CODEBERG_API/labels" | jq -r '.[] | select(.name == "backlog") | .id')
      - Create a bundled backlog issue:
          curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \
            -H "Content-Type: application/json" "$CODEBERG_API/issues" \
            -d '{"title":"fix: bundled dust cleanup — GROUP","body":"...","labels":[LABEL_ID]}'
      - Close each source issue with a cross-reference comment:
          curl ... "$CODEBERG_API/issues/NNN/comments" -d '{"body":"Bundled into #NEW"}'
          curl ... "$CODEBERG_API/issues/NNN" -d '{"state":"closed"}'
      - Remove bundled items from dust.jsonl:
          jq -c --arg g "GROUP" 'select(.group != $g)' "$DUST_FILE" > "${DUST_FILE}.tmp" && mv "${DUST_FILE}.tmp" "$DUST_FILE"

5. If no DUST items were emitted and no groups are ripe, skip this step.

CRITICAL: If this step fails, log the failure and move on to blocked-review.
"""
needs = ["grooming"]

# ─────────────────────────────────────────────────────────────────────
# Step 4: blocked-review — triage blocked issues
# ─────────────────────────────────────────────────────────────────────

[[steps]]
id    = "blocked-review"
title = "Review issues labeled blocked"
description = """
Review all issues labeled 'blocked' and decide their fate.
(See issue #352 for the blocked label convention.)

1. Look up the 'blocked' label ID (Gitea needs integer IDs for label removal):
     BLOCKED_LABEL_ID=$(curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/labels" | jq -r '.[] | select(.name == "blocked") | .id')
   If the lookup fails, skip label removal and just post comments.

2. Fetch all blocked issues:
     curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/issues?state=open&type=issues&labels=blocked&limit=50"

3. For each blocked issue, read the full body and comments:
     curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/issues/<number>"
     curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/issues/<number>/comments"

4. Check dependencies — extract issue numbers from ## Dependencies /
   ## Depends on / ## Blocked by sections. For each dependency:
     curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/issues/<dep_number>"
   Check if the dependency is now closed.

5. For each blocked issue, choose ONE action:

   UNBLOCK — all dependencies are now closed or the blocking condition resolved:
   a. Remove the 'blocked' label (using ID from step 1):
        curl -sf -X DELETE -H "Authorization: token $CODEBERG_TOKEN" \
          "$CODEBERG_API/issues/<number>/labels/$BLOCKED_LABEL_ID"
   b. Add context comment explaining what changed:
        curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<number>/comments" \
          -d '{"body":"Unblocked: <explanation of what resolved the blocker>"}'

   NEEDS HUMAN — blocking condition is ambiguous, requires architectural
   decision, or involves external factors:
   a. Post a diagnostic comment explaining what you found and what
      decision is needed
   b. Leave the 'blocked' label in place

   CLOSE — issue is stale (blocked 30+ days with no progress on blocker),
   the blocker is wontfix, or the issue is no longer relevant:
   a. Post a comment explaining why:
        curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<number>/comments" \
          -d '{"body":"Closing: <reason — stale blocker, no longer relevant, etc.>"}'
   b. Close the issue:
        curl -sf -X PATCH -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<number>" \
          -d '{"state":"closed"}'

CRITICAL: If this step fails, log the failure and move on.
"""
needs = ["dust-bundling"]

# ─────────────────────────────────────────────────────────────────────
# Step 5: agents-update — AGENTS.md watermark staleness + size enforcement
# ─────────────────────────────────────────────────────────────────────

[[steps]]
id    = "agents-update"
title = "Check AGENTS.md watermarks, update stale files, enforce size limit"
description = """
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)

2. Find all AGENTS.md files:
     find "$PROJECT_REPO_ROOT" -name "AGENTS.md" -not -path "*/.git/*"

3. For each file, read the watermark from line 1:
     <!-- last-reviewed: <sha> -->

4. Check for changes since the watermark:
     git log --oneline <watermark>..HEAD -- <directory>
   If zero changes, the file is current — skip it.

5. For stale files:
   - 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: architecture and WHY not implementation details

## Part B: Size limit enforcement (progressive disclosure split)

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.
"""
needs = ["blocked-review"]

# ─────────────────────────────────────────────────────────────────────
# Step 6: commit-and-pr — single commit with all file changes
# ─────────────────────────────────────────────────────────────────────

[[steps]]
id    = "commit-and-pr"
title = "One commit with all file changes, push, create PR"
description = """
Collect all file changes from this run (AGENTS.md updates) into a single commit.
API calls (issue creation, PR comments, closures) already happened during the
run — only file changes need the PR.

1. Check for staged or unstaged changes:
     cd "$PROJECT_REPO_ROOT"
     git status --porcelain

   If there are no file changes, skip this entire step — no commit, no PR.

2. If there are changes:
   a. Create a branch:
        BRANCH="chore/gardener-$(date -u +%Y%m%d-%H%M)"
        git checkout -B "$BRANCH"
   b. Stage all modified AGENTS.md files:
        find . -name "AGENTS.md" -not -path "./.git/*" -exec git add {} +
   c. Also stage any other files the gardener modified (if any):
        git add -u
   d. Commit:
        git commit -m "chore: gardener housekeeping $(date -u +%Y-%m-%d)"
   e. Push:
        git push -u origin "$BRANCH"
   f. Create a PR:
        curl -sf -X POST \
          -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/pulls" \
          -d '{"title":"chore: gardener housekeeping",
               "head":"<branch>","base":"<primary-branch>",
               "body":"Automated gardener housekeeping — AGENTS.md updates.\n\nReview-agent fast-tracks doc-only PRs."}'
   g. Return to primary branch:
        git checkout "$PRIMARY_BRANCH"

3. If the PR creation fails (e.g. no changes after staging), log and continue.
"""
needs = ["agents-update"]
