@agentproto/apps 0.12.0 → 0.13.0

package/repo-maintenance/README.md

@@ -0,0 +1,79 @@
+# Repo Maintenance
+
+A built-in agentproto app on top of `@agentproto/worktree`'s `branch_gc` /
+`branch_gc_verdict` / `worktree_gc` tools. It ships as a hand-authored
+bundled app (`.agentproto/APP.md` + `agents/` + `workflows/`) rather than a
+`defineApp()`/`.emit()`-generated one, because the `maintain` workflow's
+`review` map step needs a real run-time function to pick the reviewer's
+model per candidate — see `workflows/maintain/entry.mjs`'s docblock for why
+that requires the `entry:` loader path.
+
+## What it does
+
+The `maintain` workflow, one run:
+
+1. `worktree_gc` + `branch_gc` plan (dry run — nothing is touched).
+2. Fans the `@agentproto/repo-maintenance-reviewer` agent out over the
+   unmerged branch candidates with no stored verdict yet — at most
+   `maxReviews` (default 40) per run, newest tip first, then the larger
+   residual; the rest wait for the next run (one turn per unique tip sha,
+   parallelism 4, each reviewer in its own disposable detached worktree
+   under the OS tmp dir, never the live checkout): haiku when the
+   candidate's residual is 3 files or fewer, sonnet otherwise. Three spawn
+   failures in a row stop the fan-out (the engine's circuit breaker) and
+   the report lists every distinct failure reason. Each turn records a verdict via `branch_gc_verdict` —
+   recording a verdict never deletes anything. A turn that ends without a
+   stored verdict for its tip (checked via `branch_gc_verdict_get`) gets
+   one re-prompt in the same session, then one retry on the large model.
+3. Re-plans `branch_gc` to confirm every candidate got a verdict, and
+   reports any gap, the verdict tally, and the `salvage` branches by name.
+4. If `applyMerged` is true: `branch_gc` applies with `includeReviewed:
+   false` (reclaim-class refs only — merged / squash-merged / patch-merged /
+   content-merged) and `worktree_gc` applies (`salvageDirty: false`).
+   **A `review`-class branch is never reclaimed by this workflow, agreed
+   verdict or not** — see "Out of scope" below.
+5. Reports a markdown summary, and (only when `notify` is set AND there's a
+   reclaimable ref or a review candidate) sends it to an agentpush target.
+
+## Out of scope: the approval gate
+
+Recording a verdict via `branch_gc_verdict` is a report, not a license to
+delete. Reclaiming a `review`-class branch whose stored verdict agreed
+(`branch_gc`'s `includeReviewed: true`) needs a human-in-the-loop
+approval/escalation gate — deliberately not built here. `approve-reviewed`
+is the documented, unwired seam for that gate; the workflow applies nothing
+beyond `reclaim` refs, and only when `applyMerged` is true.
+
+## Installing
+
+```bash
+agentproto app install packages/apps/repo-maintenance
+```
+
+(or wherever this directory lands once installed from an npm-published
+`@agentproto/apps` — see that package's README for the general install
+story.) Then run it once ad-hoc:
+
+```bash
+agentproto maintain --repo <path>              # dry run: plan + review
+agentproto maintain --repo <path> --apply-merged
+```
+
+or via the daemon directly:
+
+```bash
+agentproto workflow run-file \
+  packages/apps/repo-maintenance/.agentproto/workflows/maintain/WORKFLOW.md \
+  --input-json '{"repoRoot": "<path>", "applyMerged": false}'
+```
+
+## Routines
+
+`routines/repo-maintenance-daily` (plan + review, `applyMerged: false`) and
+`routines/repo-maintenance-weekly` (`applyMerged: true`) are AIP-41
+`ROUTINE.md` templates targeting the `maintain` workflow, shipped
+`enabled: false`. Each documents its own enabling steps — copy the directory
+into a workspace's `.routines/`, point `target.workflow.file` at wherever
+`maintain/WORKFLOW.md` lives in that environment, set `enabled: true`, and
+reload routines. Enable the daily one first and watch it run clean a few
+times before enabling weekly — only weekly deletes anything.

package/repo-maintenance/routines/repo-maintenance-daily/ROUTINE.md

@@ -0,0 +1,77 @@
+---
+schema: routine/v1
+id: repo-maintenance-daily
+description: |
+  Daily plan + review pass of the `maintain` workflow — `applyMerged: false`,
+  so it only classifies branches/worktrees and fans the reviewer agent out
+  over unmerged candidates; nothing is ever deleted by this routine. Notifies
+  only when there's something to report (a reclaimable ref or a review
+  candidate) and `notify` is configured. Ships DISABLED (`enabled: false`) —
+  install it into a workspace's `.routines/` and flip `enabled: true` to
+  activate.
+version: "1.0.0"
+schedule:
+  kind: cron
+  cron: "0 5 * * *"
+  timezone: "UTC"
+  catchup: skip
+target:
+  workflow:
+    file: <absolute-path-to-agentproto-ts>/packages/apps/repo-maintenance/.agentproto/workflows/maintain/WORKFLOW.md
+  inputs:
+    applyMerged: false
+    notify:
+      channel: telegram
+      address: "<REPLACE_WITH_YOUR_TELEGRAM_CHAT_ID>"
+retry:
+  max_attempts: 1
+  backoff: fixed
+on_failure:
+  create_work_item: true
+  fire_event: repo-maintenance.daily.failed
+fires_events:
+  - repo-maintenance.daily.completed
+  - repo-maintenance.daily.failed
+enabled: false
+tags: [repo-maintenance, branch-gc, worktree-gc, maintenance]
+---
+
+# Repo maintenance — daily plan + review
+
+Runs daily at **05:00 UTC**, firing the `maintain` workflow
+(`../../.agentproto/workflows/maintain/WORKFLOW.md`) via `workflow_run_file`
+with `applyMerged: false`. Every run:
+
+1. Plans `worktree_gc` and `branch_gc` (dry run — nothing is touched).
+2. Fans the `@agentproto/repo-maintenance-reviewer` agent out over every
+   unmerged branch candidate (haiku when its residual is 3 files or fewer,
+   sonnet otherwise), one turn per unique tip sha. Each turn records a
+   verdict via `branch_gc_verdict` — recording never deletes anything.
+3. Re-plans to confirm every candidate got a verdict, and reports the gaps.
+4. Reports a markdown summary, and notifies (when `notify` is configured)
+   ONLY if there was a reclaimable ref or a review candidate — a clean sweep
+   over an already-tidy repo doesn't page anyone.
+
+Nothing this routine does can delete a branch, a worktree, or apply a
+recorded verdict — see `repo-maintenance-weekly/ROUTINE.md` for the
+apply-enabled sibling, and the `maintain` WORKFLOW.md's own doc for the
+documented-but-unwired `approve-reviewed` seam.
+
+## Enabling
+
+1. Copy this directory to `<workspace>/.routines/repo-maintenance-daily/`.
+2. Set `enabled: true`, update `target.workflow.file` to wherever this repo's
+   `maintain/WORKFLOW.md` actually lives in that environment, and either
+   replace `target.inputs.notify` with your own agentpush target or delete
+   the `notify` key entirely to run silently (report only, no page).
+3. If `notify` is kept, allowlist `bash` in that workspace's
+   `.agentproto/allowed-commands.json` (the workflow's `notify` step needs
+   it) and set `AGENTPUSH_API_KEY` in the daemon's environment.
+4. Reload routines so the daemon registers the schedule, or fire it once
+   ad-hoc via `routine_trigger` without waiting for the schedule.
+
+## Failure routing
+
+One retry attempt (no backoff), then `on_failure` opens a work item and
+fires `repo-maintenance.daily.failed`. A clean run fires
+`repo-maintenance.daily.completed`.

package/repo-maintenance/routines/repo-maintenance-weekly/ROUTINE.md

@@ -0,0 +1,82 @@
+---
+schema: routine/v1
+id: repo-maintenance-weekly
+description: |
+  Weekly plan + review + APPLY pass of the `maintain` workflow —
+  `applyMerged: true`, so after the review agent runs, `branch_gc` (reclaim
+  class only, includeReviewed false) and `worktree_gc` execute their plans:
+  merged/squash-merged/patch-merged/content-merged branches and
+  merged-or-fresh+clean worktrees are reclaimed. `review`-class branches and
+  anything `hold` are NEVER touched by this routine — recording a verdict
+  does not by itself reclaim a branch (see the maintain workflow's
+  documented, unwired `approve-reviewed` seam). Ships DISABLED
+  (`enabled: false`) — install it into a workspace's `.routines/` and flip
+  `enabled: true` to activate.
+version: "1.0.0"
+schedule:
+  kind: cron
+  cron: "0 5 * * 0"
+  timezone: "UTC"
+  catchup: skip
+target:
+  workflow:
+    file: <absolute-path-to-agentproto-ts>/packages/apps/repo-maintenance/.agentproto/workflows/maintain/WORKFLOW.md
+  inputs:
+    applyMerged: true
+    notify:
+      channel: telegram
+      address: "<REPLACE_WITH_YOUR_TELEGRAM_CHAT_ID>"
+retry:
+  max_attempts: 1
+  backoff: fixed
+on_failure:
+  create_work_item: true
+  fire_event: repo-maintenance.weekly.failed
+fires_events:
+  - repo-maintenance.weekly.completed
+  - repo-maintenance.weekly.failed
+enabled: false
+tags: [repo-maintenance, branch-gc, worktree-gc, maintenance]
+---
+
+# Repo maintenance — weekly plan + review + apply
+
+Runs weekly, Sunday **05:00 UTC**, firing the same `maintain` workflow as
+`repo-maintenance-daily/ROUTINE.md` but with `applyMerged: true`. Every run
+does everything the daily routine does (plan, review fan-out, verdict-gap
+check), then:
+
+- `branch_gc` applies with `includeReviewed: false` — only `reclaim`-class
+  refs (merged / squash-merged / patch-merged / content-merged, by the same
+  ladder `branch_gc`'s own doc describes) are deleted. Every entry is
+  re-classified from scratch immediately before it's touched, so a plan that
+  went stale between the review pass and the apply is refused rather than
+  acted on. A restore log (sha + exact re-create command per deleted ref) is
+  written before the first delete.
+- `worktree_gc` applies with `salvageDirty: false` — only merged/fresh AND
+  clean worktrees are reclaimed; a dirty-but-integrated worktree is left in
+  place.
+
+**A `review`-class branch is never reclaimed by this routine, agreed verdict
+or not.** Recording a verdict via `branch_gc_verdict` is a report, not a
+license to delete — reclaiming a reviewed branch needs a human-in-the-loop
+gate this codebase deliberately hasn't built yet (`approve-reviewed`, see the
+`maintain` WORKFLOW.md's own doc).
+
+## Enabling
+
+Same steps as `repo-maintenance-daily/ROUTINE.md`: copy this directory to
+`<workspace>/.routines/repo-maintenance-weekly/`, set `enabled: true`, point
+`target.workflow.file` at wherever `maintain/WORKFLOW.md` lives in that
+environment, set or drop `target.inputs.notify`, allowlist `bash` +
+`AGENTPUSH_API_KEY` if `notify` is kept, then reload routines.
+
+Enable ONLY after you've watched `repo-maintenance-daily` run clean a few
+times — this routine deletes branches and worktrees, the daily one never
+does.
+
+## Failure routing
+
+Same convention as the daily routine: one retry attempt (no backoff), then
+`on_failure` opens a work item and fires `repo-maintenance.weekly.failed`. A
+clean run fires `repo-maintenance.weekly.completed`.