@terreno/agent-plugin-loop 0.0.0-stage → 58.0.0-beta.2

package/skills/campaign/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: campaign
+description: Drive a long-term codebase goal to its target — charter it, sweep and sift the repository into findings, plot PR-sized slices, run each slice through the Terreno lifecycle, then re-measure and repeat until the metric hits target or a genuine human decision is required. Not a scan stage — an outer loop that invokes the scan stages and the lifecycle. Use when asked to run a scan campaign, work toward a long-term engineering goal, or keep scanning and fixing until an outcome is reached.
+---
+
+# Scan campaign (outer driver)
+
+Not a stage. The five scan stages stay Aim, Sweep, Sift, Plot, Track. This skill walks
+them round after round and hands each plotted slice to the Terreno lifecycle, until the
+goal metric reaches its target or a genuine human decision is required.
+
+For a session that stays resident — heartbeating over open PRs, answering review, and
+refilling work as PRs merge — use `run` instead. This skill runs the rounds
+and stops at each gate; the loop wraps it and keeps going.
+
+Read the shared [`scan contract`](../../references/scan-contract.md),
+[`agentic map-reduce`](../../references/mapreduce.md),
+[`goal tracking`](../../references/goal-tracking.md), and
+[`PR routing`](../../references/pr-routing.md). The campaign state must conform to
+[`scan-state.schema.json`](../../references/scan-state.schema.json).
+
+## Scope
+
+- Included: the five scan stages, campaign-state persistence, lifecycle handoff for each
+  plotted slice, bounded retries, and one accumulated report.
+- Excluded: implementing findings, editing product code, committing, pushing, opening or
+  merging PRs. The lifecycle owns all of that.
+- Requires the Terreno lifecycle plugin (`1-grow` … `5-taste`). If it is
+  not installed, stop at Plot and report the missing dependency.
+
+## Preconditions
+
+- A goal, outcome, or existing charter is available with a repository.
+- The campaign-state location is resolvable and can be preserved between invocations.
+
+If a charter exists but is unapproved, stop at a human gate. Do not invent a goal, a
+target, or a metric.
+
+## Round shape
+
+```text
+Aim (once per goal)
+  → Sweep → Sift
+      → dry round → Track
+      → findings → Plot → handoff
+          → 1-grow (slice brief → approved IP + tasks)
+          → pick-roast-loop, or 2-pick once
+          → 4-brew → 5-taste
+      → Track
+          → plot  (backlog remains)
+          → sweep (backlog empty, rounds remain)
+          → null  (target reached, budget spent, regression, or diminishing returns)
+```
+
+## Drive
+
+1. **Reconstruct once.** Read the charter and campaign state. Verify goal, round, branch,
+   findings, and slice PR status against reality. Identify the stage named by
+   `next.stage`; default to Aim when no charter exists, otherwise Sweep.
+2. **Invoke the named scan stage** in a fresh context with the charter, campaign state,
+   the previous result, and this round's artifacts. Never ask the stage to rediscover the
+   campaign from conversation.
+3. **Consume the result.** Update campaign state, then classify:
+   - `PASS` with `next` set → invoke that stage next.
+   - `PASS` with `handoff: grow` → run the lifecycle for the top slice (below), then
+     invoke Track.
+   - `PASS` with `next: null` → finish and report.
+   - `FAIL` with a concrete action → reinvoke the named stage with the exact evidence and
+     a new hypothesis.
+   - `BLOCKED` with `kind: human` or `next.human: true` → present the human gate.
+   - `BLOCKED` for environment/access/external → attempt safe remediation or one bounded
+     retry when a new hypothesis exists. Never relabel it `human` merely to stop.
+   - `PENDING` → wait per `wait`, preferring the harness's native completion hook or the
+     provider's watch hook; use a timer only when no hook applies. Then reinvoke.
+4. **Run the handed-off slice.** For the slice Plot names:
+   - Invoke `1-grow` with the slice brief. Grow owns the IP, the task list, and
+     human approval.
+   - On Grow `PASS`, invoke `pick-roast-loop` when it is installed, otherwise
+     `2-pick` once — Pick owns the pick → roast → next-task inner loop.
+   - On completion, invoke `4-brew`, then `5-taste`, honoring their
+     `PENDING` waits exactly as the lifecycle's own loops do.
+   - As soon as Brew reports the PR, apply the charter's routing per `pr-routing.md` and
+     record the reviewer and assignee. An unrouted PR is not a finished handoff.
+   - Record the slice's branch, PR, reviewer, and outcome in campaign state. A slice the lifecycle
+     blocks is recorded and skipped; the campaign continues with the next slice rather
+     than stalling the goal, unless the blocker applies to every slice.
+5. **Bound retries by evidence.** A retry must add a new hypothesis, changed setup, or
+   new evidence. Never repeat a failed approach. After two focused failures of the same
+   stage with no new hypothesis, classify the underlying decision honestly instead of
+   looping.
+6. **Continue quietly.** Repeat steps 2–5 without narrating each cycle. Keep details in
+   campaign state and report once at completion or at a human gate.
+
+## Budget and safety
+
+- Honor the charter's budget: rounds, slices per round, and open PRs at once (`wipLimit`).
+- Never exceed the open-PR limit; wait on Track instead of stacking review load.
+- Stop and report when the horizon passes, even mid-backlog.
+- Never run a campaign that edits code the charter marked out of scope.
+
+## Recurring campaigns
+
+A campaign is resumable by design: every invocation reconstructs from the charter and
+campaign state. To run it on a cadence, schedule this skill with the goal slug and let it
+pick up the next move — a fresh sweep, the next slice, or a report. Repeated invocations
+must not restart Aim or re-baseline a goal that already has one.
+
+## Genuine human gate
+
+Ask for input only for:
+
+- the goal statement, metric, or target itself
+- destructive or irreversible remediation
+- public API, data-format, or compatibility changes a finding requires
+- scope growth beyond the approved charter
+- a metric regression or two rounds below the charter's minimum step
+- credentials or permissions no authorized alternative can supply
+- a reviewer handle that cannot be verified or requested
+
+Before the question, give this overview in plain language:
+
+1. **Goal and trajectory:** statement, metric, baseline → previous → current vs target.
+2. **What happened:** rounds run, findings found/fixed/reopened, slices merged, decisive
+   evidence.
+3. **Why input is needed:** the exact decision and why evidence cannot choose it.
+4. **Options:** two to four concrete choices with impact and risk.
+5. **Recommendation:** one default and its rationale.
+
+End with **one exact question** the human can answer in one message. Then close with PR
+deployment URLs when a slice's PR has them. Do not expose chain-of-thought, worker
+transcripts, or unexplained stage YAML.
+
+## Completion report
+
+When the target is reached, lead with:
+
+`PASS — <metric> <baseline> → <current> <unit> (target <target>) across <n> rounds.`
+
+Then report:
+
+- `Trajectory`: metric per round with the command output for the final measurement
+- `Fixed`: findings closed with evidence, grouped by slice and PR
+- `Open`: findings still open or deferred, with the reason
+- `Dismissed`: dropped findings and why
+- `Regressions`: anything that moved the wrong way, or `None identified`
+- `Residual risk`: explicit remaining risk, or `None identified`
+- `Next`: the recommended follow-up, such as a cadence for re-sweeping
+
+When stopped early, use the same report plus `Blocker`. Include everything from the round
+records once; do not duplicate per-round narration.
+
+## Stop conditions
+
+- `PASS`: the metric reached target and held after the last slice landed.
+- `PASS` with a question: budget or horizon exhausted, or diminishing returns.
+- `BLOCKED` (human): a genuine human gate above.
+- `BLOCKED` (non-human): retries exhausted and no safe autonomous action exists.
+- `FAIL`: campaign state is inconsistent or corrupt, or the named stage cannot be invoked.
+
+Ordinary rule failures, empty shards, dry rounds, and lifecycle test failures are not
+terminal while a concrete action remains.
+
+## Emit
+
+After the human-facing report, include one collapsed scan-result payload. Since outer
+loops are not stages, set `stage` to the last scan stage invoked.
+
+```yaml
+v: 2
+stage: track
+status: PASS
+goal: reduce-cold-build-time
+round: 3
+metric:
+  value: 28.4
+  unit: s
+  delta: -30.2
+  ev: "bun run compile (cold, best of 3): 28.4s"
+next: null
+action: Target reached; re-sweep quarterly to hold the gain
+```
+
+For a human gate, use `status: BLOCKED`, `next: null`, and an `ask` entry with the exact
+question, recommendation, and options. For a non-human terminal blocker, use a `block`
+entry with `kind: environment`, `access`, or `external`, and omit `ask`.

package/skills/run/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: run
+description: Run a scan campaign as a resident session — keep working toward the goal, open PR-sized slices routed to named reviewers, and heartbeat over every open PR to answer review comments, fix failing CI, and land merges, until the metric hits target or a human decision is required. Use when asked to keep a goal running continuously, leave a scan going in the background, watch and respond to campaign PRs, or run the scan loop; not for a single bounded round.
+---
+
+# Scan loop (resident driver)
+
+One session, running until the goal is met. It alternates between **making progress** —
+sweep, sift, plot, hand a slice to the lifecycle, open a routed PR — and **servicing what
+is already open** — answering human review, fixing red CI, tracking merges. Work happens
+in fresh subagents; this session holds only the goal, the state, and the schedule.
+
+Read [`scan contract`](../../references/scan-contract.md),
+[`heartbeat`](../../references/heartbeat.md),
+[`PR routing`](../../references/pr-routing.md),
+[`goal tracking`](../../references/goal-tracking.md), and
+[`agentic map-reduce`](../../references/mapreduce.md). Campaign state conforms to
+[`scan-state.schema.json`](../../references/scan-state.schema.json).
+
+## Scope
+
+- Included: the five scan stages, PR routing, the heartbeat over open campaign PRs,
+  lifecycle invocation per slice, state persistence, scheduling, and one report per
+  human gate or completion.
+- Excluded: writing product code, committing, pushing, approving, and merging. Every one
+  of those belongs to a lifecycle stage invoked in a fresh subagent — Pick implements,
+  Brew submits, Taste reacts.
+- Requires the lifecycle plugin (`1-grow` … `5-taste`) and a host CLI
+  with PR access (`gh`). Missing either is `BLOCKED`, not a workaround.
+
+## Arguments
+
+Parse from the invocation, in this order: an explicit `goal=<slug>`, a quoted goal
+statement, or the remaining text. Also accept:
+
+| Argument | Meaning |
+| --- | --- |
+| `reviewer=<handle[,handle]>` | Override the charter's reviewers for this run |
+| `assignee=<handle>` | Override the charter's assignee |
+| `wip=<n>` | Override the charter's open-PR limit for this run |
+| `rounds=<n>` | Stop after this many sweep rounds |
+| `until=<ISO timestamp>` | Stop at this time regardless of progress |
+| `tick=<seconds>` | Fixed heartbeat interval instead of the adaptive one |
+
+An override applies to this run only and is recorded in state as an override, never
+written back into the charter.
+
+If no campaign exists for the goal, run Aim first and block for approval — a resident
+loop does not invent a metric, a target, or a reviewer.
+
+## Start
+
+1. **Resolve the campaign.** Read the charter and campaign state for the goal. Verify the
+   branch, round, findings, and every recorded PR against the host. If nothing exists,
+   invoke `1-aim` and stop at its approval gate.
+2. **Resolve routing.** Confirm the charter's `review` block names a reachable reviewer or
+   an explicit `mode: none`. Verify unfamiliar handles per `pr-routing.md`. An unroutable
+   campaign stops here with one question, before any PR exists.
+3. **Announce once.** One short line: goal, metric baseline → current vs target, open PRs
+   and who has them, what this run will do first, and the heartbeat interval. This is the
+   only unprompted status message until something needs a human.
+
+## Run
+
+Repeat until a stop condition:
+
+1. **Heartbeat tick.** Follow `heartbeat.md`: snapshot the campaign's PRs, classify each,
+   and act in priority order — route unrouted PRs, hand answered and broken PRs to Taste
+   in fresh subagents, Track merged ones, retire closed ones. Answer any given comment
+   exactly once.
+2. **Refill capacity.** When open campaign PRs are below the effective `wipLimit` and the
+   backlog has planned findings, advance the campaign one step:
+   - planned findings remain → `4-plot` for the next slice
+   - backlog empty, rounds remain → `2-sweep`, then `3-sift`
+   - a slice is ready to build → `1-grow` with its brief, then
+     `pick-roast-loop` (or `2-pick` once), then `4-brew`
+   - Brew reported a PR → apply routing immediately, then count the slice in flight
+3. **Persist.** Update campaign state after every stage and every tick: stage, round,
+   slices with PR/reviewer/assignee/bucket, answered comment ids, `lastTick`, and the
+   chosen next interval.
+4. **Schedule.** Pick the next interval from the heartbeat table — provider watch hook
+   while CI runs, minutes while bots report, tens of minutes while a human holds the PR,
+   no wait at all while backlog work remains. Prefer the harness's native scheduling or
+   completion hooks; use a timer only when no hook applies.
+5. **Stay quiet.** A tick with nothing to report prints nothing. Do not narrate ticks, do
+   not repeat the plan, and do not post PR comments to show activity.
+
+## Concurrency
+
+- Never exceed the effective `wipLimit` of open campaign PRs.
+- Never run two lifecycle stages against the same slice at once.
+- Never start a new slice while a slice for the same files is open — the second PR will
+  conflict and waste the reviewer's time.
+- One branch per slice, named from the slice slug. Never reuse a branch a human is
+  reviewing.
+
+## Speak only when it matters
+
+Interrupt the human for:
+
+- a genuine gate from `scan-contract.md`: goal or target changes, destructive remediation,
+  public API or data-format changes, scope growth, metric regression, exhausted budget
+- an unroutable or unverifiable reviewer handle
+- a PR a human has held with requested changes the campaign cannot satisfy without a
+  decision
+- three consecutive host failures, lost credentials, or a lifecycle stage blocked on
+  something only a person can supply
+
+Every interruption carries goal and trajectory, what happened, why input is needed,
+two to four options with impact, a recommendation, then **one exact question**, then PR
+deployment URLs when a campaign PR has them.
+
+## Stop conditions
+
+- Metric reached target and held after the last slice merged → complete.
+- `rounds=` or `until=` reached, or the charter's horizon passed → report and ask.
+- Two rounds below the charter's minimum step, or a regression → report and ask.
+- A genuine human gate → `BLOCKED`, with the question above.
+- Three consecutive host failures → `BLOCKED` with `kind: access`.
+- The human says stop → stop immediately, leave every PR routed and state consistent, and
+  report what is in flight and who holds it.
+
+A resident loop never stops quietly. Every stop names what is open, who has it, and what
+the next action would be.
+
+## Report
+
+On completion or at a gate, lead with the trajectory:
+
+`<metric> <baseline> → <current> <unit> (target <target>), <merged> slices merged, <open> open.`
+
+Then: `In flight` (PR, reviewer, bucket, age), `Merged this run`, `Fixed` findings with
+evidence, `Open` and `Dismissed` findings, `Regressions` or `None identified`,
+`Residual risk`, and `Next`.
+
+## Emit
+
+After the human-facing report, one collapsed scan-result payload. The loop is not a
+stage, so set `stage` to the last scan stage invoked.
+
+```yaml
+v: 2
+stage: track
+status: PENDING
+goal: reduce-cold-build-time
+round: 2
+metric:
+  value: 41.7
+  unit: s
+  delta: -16.9
+  ev: "bun run compile (cold, best of 3): 41.7s"
+prs:
+  - pr: "1421"
+    bucket: waiting
+    who: octocat
+  - pr: "1424"
+    bucket: answered
+    who: octocat
+wait: 900
+next: track
+action: Taste is addressing review on #1424; recheck both PRs in 15 minutes
+```
+
+Use `status: PENDING` with a `wait` while PRs are open and progress continues,
+`status: PASS` when the goal is met, and `status: BLOCKED` with one `ask` at a human gate.