# formulas/run-planner.toml — Strategic planning formula
#
# Executed by the action-agent via cron-filed action issues.
# planner-poll.sh files an action issue referencing this formula weekly;
# action-poll.sh picks it up and spawns a tmux session where Claude
# executes these steps autonomously.

name        = "run-planner"
description = "Strategic planning: update docs, triage predictions, resource+leverage gap analysis"
version     = 1
model       = "opus"

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

[[steps]]
id    = "preflight"
title = "Pull latest code and load planner memory"
description = """
Set up the working environment for this planning 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 — you will need it for AGENTS.md watermarks:
     HEAD_SHA=$(git rev-parse HEAD)
     echo "$HEAD_SHA" > /tmp/planner-head-sha

4. Read the planner memory file at: $FACTORY_ROOT/planner/MEMORY.md
   If it does not exist, this is the first planning run.
   Keep this memory context in mind for all subsequent steps.
"""

[[steps]]
id    = "agents-update"
title = "Update AGENTS.md documentation tree"
description = """
Check all AGENTS.md files for staleness and update any that are outdated.

1. Read the HEAD SHA from preflight:
     HEAD_SHA=$(cat /tmp/planner-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: max ~200 lines, architecture and WHY not implementation details

6. If you made changes:
   a. Create a branch:
        git checkout -B "chore/planner-agents-$(date -u +%Y%m%d)"
   b. Stage only AGENTS.md files:
        find . -name "AGENTS.md" -not -path "./.git/*" -exec git add {} +
   c. Commit:
        git commit -m "chore: planner update AGENTS.md tree"
   d. Push:
        git push -f origin "chore/planner-agents-$(date -u +%Y%m%d)"
   e. Create a PR (failure here is non-fatal — log and continue):
        curl -sf -X POST \
          -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/pulls" \
          -d '{"title":"chore: planner update AGENTS.md tree",
               "head":"<branch>","base":"<primary-branch>",
               "body":"Automated AGENTS.md update — review-agent fast-tracks doc-only PRs."}'
   f. Return to primary branch:
        git checkout "$PRIMARY_BRANCH"

7. If no AGENTS.md files need updating, 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 prediction triage or strategic planning.
"""
needs = ["preflight"]

[[steps]]
id    = "triage-predictions"
title = "Triage prediction/unreviewed issues"
description = """
Triage prediction issues filed by the predictor (goblin).
Evidence from the preflight step informs whether each prediction is valid
(e.g. "red-team stale since March 12" is confirmed by evidence/ timestamps).

1. Fetch unreviewed predictions:
     curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/issues?state=open&type=issues&labels=prediction%2Funreviewed&limit=50"

   If there are none, note that and proceed to strategic-planning.

2. Read available formulas from $FACTORY_ROOT/formulas/*.toml so you know
   what actions can be dispatched.

3. Fetch all open issues to check for overlap:
     curl -sf -H "Authorization: token $CODEBERG_TOKEN" \
       "$CODEBERG_API/issues?state=open&type=issues&limit=50"

4. For each prediction, read the title and body. Choose one action:

   - PROMOTE_ACTION: maps to an available formula → create an action issue
     with YAML front matter referencing the formula name and vars.
     Close the prediction with comment "Actioned as #NNN".

   - PROMOTE_BACKLOG: warrants dev work → create a backlog issue.
     Close the prediction with comment "Actioned as #NNN".

   - WATCH: not urgent but worth tracking → post a comment explaining
     why it is not urgent, then relabel from prediction/unreviewed to
     prediction/backlog. Do NOT close.

   - DISMISS: noise, already covered by an open issue, or not actionable →
     post a comment with explicit reasoning, then close the prediction.

   Every decision MUST include reasoning in a comment on the prediction issue.

5. Executing triage decisions via API:

   For PROMOTE_ACTION / PROMOTE_BACKLOG:
   a. Create the new issue with the 'action' or 'backlog' label:
        curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" "$CODEBERG_API/issues" \
          -d '{"title":"...","body":"...","labels":[<label_id>]}'
   b. Comment on the prediction with "Actioned as #NNN":
        curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<pred_num>/comments" \
          -d '{"body":"Actioned as #NNN — <reasoning>"}'
   c. Close the prediction:
        curl -sf -X PATCH -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<pred_num>" \
          -d '{"state":"closed"}'

   For WATCH:
   a. Comment with reasoning why not urgent
   b. Replace prediction/unreviewed label with prediction/backlog:
        curl -sf -X DELETE -H "Authorization: token $CODEBERG_TOKEN" \
          "$CODEBERG_API/issues/<pred_num>/labels/<unreviewed_label_id>"
        curl -sf -X POST -H "Authorization: token $CODEBERG_TOKEN" \
          -H "Content-Type: application/json" \
          "$CODEBERG_API/issues/<pred_num>/labels" \
          -d '{"labels":[<backlog_label_id>]}'

   For DISMISS:
   a. Comment with explicit reasoning
   b. Close the prediction issue

6. Track promoted predictions — they compete with vision gaps in the
   strategic-planning step for the per-cycle 5-issue limit.
   Record each promotion (issue number, title, type) for hand-off.

7. Validation: if you reference a formula, verify it exists on disk.
   Fall back to a freeform backlog issue for unknown formulas.

Be decisive — the predictor intentionally over-signals; your job is to filter.

CRITICAL: If this step fails, log the failure and move on to strategic-planning.
"""
needs = ["preflight"]

[[steps]]
id    = "strategic-planning"
title = "Strategic planning — resource+leverage gap analysis"
description = """
This is the core planning step. Reason about leverage and create
the highest-impact issues.

Read these inputs:
  - VISION.md — where we want to be
  - All AGENTS.md files — what exists today
  - $FACTORY_ROOT/RESOURCES.md — what we have (may not exist)
  - $FACTORY_ROOT/formulas/*.toml — what actions can be dispatched
  - Open issues (fetched via API) — what's already planned
  - $FACTORY_ROOT/metrics/supervisor-metrics.jsonl — operational trends (may not exist)
  - Planner memory (loaded in preflight)
  - Promoted predictions from triage-predictions (these count toward the
    per-cycle issue limit — they compete with vision gaps for priority)

Reason through these five questions:

1. **What resources do you need that you don't have?**
   Analytics, domains, accounts, compute, integrations — things required
   by the vision that aren't in RESOURCES.md or aren't set up yet.

2. **What resources are underutilized?**
   Compute capacity idle most of the day. Domains with no traffic.
   CI capacity unused at night. Accounts not being leveraged.

3. **What's the highest-leverage action?**
   The one thing that unblocks the most progress toward the vision.
   Can you dispatch a formula for it?

4. **What task gaps remain?**
   Things in VISION.md not covered by open issues or the current
   project state.

5. **What should be deferred?**
   Things that depend on blocked resources or aren't high-leverage
   right now. Do NOT create issues for these.

Then create up to 5 issues total (including promotions from triage-predictions),
prioritized by leverage:

For formula-matching gaps, include YAML front matter in the body:
  ---
  formula: <name>
  vars:
    key: "value"
  ---
  <explanation of why this matters>

For freeform gaps:
  <problem statement + why it matters for the vision + rough approach>

Create each issue via the API with the 'backlog' label:
  curl -sf -X POST \
    -H "Authorization: token $CODEBERG_TOKEN" \
    -H "Content-Type: application/json" \
    "$CODEBERG_API/issues" \
    -d '{"title":"...","body":"...","labels":[<backlog_label_id>]}'

Rules:
- Max 5 new issues total (promoted predictions + vision gaps) — highest leverage first
- Do NOT create issues that overlap with ANY existing open issue
- Do NOT create issues for items you identified as "deferred"
- Each body: what's missing, why it matters, rough approach
- When deploying/operating, reference the resource alias from RESOURCES.md
- Add ## Depends on section for issues that depend on other open issues
- Only reference formulas that exist in formulas/*.toml
- When metrics show systemic problems, create optimization issues

If there are no gaps, note that the backlog is aligned with the vision.
"""
needs = ["agents-update", "triage-predictions"]

[[steps]]
id    = "memory-update"
title = "Persist learnings to planner/MEMORY.md"
description = """
Reflect on this planning run and write the updated memory file.

Write to: $FACTORY_ROOT/planner/MEMORY.md (replace the entire file)

Include:
- Date of this run
- What was observed (resource state, metric trends, project progress)
- What was decided (issues created, predictions triaged, what was deferred)
- Patterns and learnings useful for future planning runs
- Things to watch for next time

Rules:
- Keep under 100 lines total
- Replace the file contents — prune outdated entries from previous runs
- Focus on PATTERNS and LEARNINGS, not transient state
- Do NOT include specific issue counts or numbers that will be stale
- Most recent entries at top

Format: simple markdown with dated sections.
"""
needs = ["strategic-planning"]