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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flourish Health, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# Terreno Loop plugin for Claude Code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Goal-driven loops for Claude Code. Give it an outcome an agent can measure on its own,
+such as CI wall time, bundle size, or lint count, and it charters the goal, finds the work,
+slices it into pull requests, and re-measures after each one lands until the metric hits
+target or the budget runs out. Each slice goes through the `terreno` lifecycle plugin, so
+install that plugin too.
+
+Reference: https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/scan-plugin.md
+
+## Install
+
+Pick one channel and register only that one. Each channel provides a plugin named
+`terreno-loop`, so two channels give duplicate commands.
+
+Latest stable release, installed from npm as `@terreno/agent-plugin-loop`:
+
+```text
+/plugin marketplace add https://raw.githubusercontent.com/TerrenoLabs/terreno/master/plugins/claude-release/.claude-plugin/marketplace.json
+/plugin install terreno-loop@terreno-releases
+```
+
+Every merge to `master`:
+
+```text
+/plugin marketplace add TerrenoLabs/terreno
+/plugin install terreno-loop@terreno-plugins
+```
+
+One release, pinned: add `TerrenoLabs/terreno#<version>` as the marketplace instead.
+
+Then run `/terreno-loop:run <goal>`. Claude Code does not auto-update third-party marketplaces by
+default; run `/plugin update terreno-loop@<marketplace>` to pick up a new release.
+
+## What you get
+
+| Command | Does |
+| --- | --- |
+| `/terreno-loop:1-aim` | Charter the goal: metric, baseline, rules, budget |
+| `/terreno-loop:2-sweep` | Run the rules and map parallel workers into candidate findings |
+| `/terreno-loop:3-sift` | Dedupe, verify, and rank findings |
+| `/terreno-loop:4-plot` | Slice findings into PR-sized plans |
+| `/terreno-loop:5-track` | Re-measure the metric and choose the next move |
+| `/terreno-loop:campaign` | Run bounded rounds, stopping at each gate |
+| `/terreno-loop:run` | Stay resident: keep the goal moving and tend every open PR |
+
+Loops can run for hours and use many tokens. Set a budget or stop condition in the charter.
+
+## Maintainers
+
+This directory is generated. Do not hand-edit it; run `bun run skills:sync`.
+
+Claude Code resolves a plugin skill's command from the frontmatter `name`, so the
+shortened names live here instead of in the shared skill files. Cursor, Codex, and
+`npx skills` keep the canonical names from `plugins/terreno-loop/`.
+
+| Source | Owns |
+| --- | --- |
+| `plugins/terreno-loop/skills/` | Aim, Sweep, Sift, Plot, Track, and the outer loops |
+| `plugins/terreno-loop/references/` | Scan contract, map-reduce, goal tracking, schemas |

package/package.json

@@ -1,6 +1,33 @@
 {
+  "description": "Goal-driven code scans for Terreno: charter a measurable long-term goal, map-reduce the repository into verified findings, slice them into IPs and tasks, and drive each slice through the Terreno lifecycle until the metric hits target.",
+  "files": [
+    ".claude-plugin/",
+    "references/",
+    "skills/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://github.com/TerrenoLabs/terreno/blob/master/plugins/README.md",
+  "keywords": [
+    "claude-code",
+    "claude-plugin",
+    "terreno",
+    "scan",
+    "codebase-health",
+    "map-reduce",
+    "refactoring",
+    "sdlc"
+  ],
+  "license": "MIT",
   "name": "@terreno/agent-plugin-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "plugins/terreno-loop-claude",
+    "type": "git",
+    "url": "git+https://github.com/TerrenoLabs/terreno.git"
+  },
+  "version": "58.0.0-beta.2"
+}

package/references/finding.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terreno.dev/schemas/scan-finding.schema.json",
+  "title": "Terreno scan finding",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "rule", "title", "severity", "confidence", "anchors", "why", "ev"],
+  "properties": {
+    "id": {"type": "string"},
+    "rule": {"type": "string"},
+    "title": {"type": "string"},
+    "severity": {"enum": ["high", "medium", "low"]},
+    "confidence": {"enum": ["high", "medium", "low"]},
+    "effort": {"enum": ["S", "M", "L"]},
+    "anchors": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path"],
+        "properties": {
+          "path": {"type": "string"},
+          "line": {"type": "integer", "minimum": 1},
+          "symbol": {"type": "string"}
+        }
+      }
+    },
+    "why": {"type": "string"},
+    "fix": {"type": "string"},
+    "ev": {"type": "string"},
+    "dedupe": {"type": "string"},
+    "round": {"type": "integer", "minimum": 1},
+    "shard": {"type": "string"},
+    "slice": {"type": "string"},
+    "status": {"enum": ["open", "planned", "fixed", "dismissed", "reopened"]},
+    "dismissed": {"type": "string"}
+  }
+}

package/references/goal-tracking.md

@@ -0,0 +1,71 @@
+# Goal tracking
+
+A campaign is a long-term goal plus the evidence that the repository is moving toward
+it. Without a measured metric a scan degrades into an opinion backlog.
+
+## Goal shape
+
+| Field | Rule |
+| --- | --- |
+| `statement` | One outcome sentence in the repository's language: "cold `bun run compile` finishes in under 30s". |
+| `metric.name` | What is counted or timed. |
+| `metric.command` | The exact command that prints the value. It must run in this repository, unattended, and print a number. |
+| `metric.unit` | `s`, `ms`, `count`, `percent`, `bytes`. |
+| `metric.direction` | `down` or `up` — which way is better. |
+| `baseline` | The value captured by running the command during Aim, with its output quoted. |
+| `target` | The value that ends the campaign. |
+| `horizon` | Rounds or calendar bound after which the campaign reports instead of continuing. |
+| `budget` | Maximum rounds, maximum slices per round, and maximum open PRs at once (`wipLimit`). |
+| `review` | Who reviews campaign PRs and how they are routed; see [`pr-routing.md`](pr-routing.md). |
+
+If no command can produce the metric, the goal is not yet measurable. Either pick a
+proxy that is measurable and say so in the charter, or return `BLOCKED` with the exact
+instrumentation the repository is missing. Do not proceed with a metric that is scored by
+judgment alone.
+
+Sanity rules for a metric command:
+
+- It must be reproducible on a clean checkout of the current branch.
+- It must not depend on the campaign's own artifacts.
+- Time-based metrics are measured the same way every round (same warm/cold state, same
+  machine class); record which in the charter.
+- If a metric is noisy, record the measurement protocol (for example, best of three) in
+  the charter and use it every round.
+
+## Round record
+
+Track appends one record per round:
+
+- round number and the shard/rule set used
+- metric at round start and round end, each with the command output
+- findings found, kept, planned, fixed, dismissed, and reopened
+- slices landed, with their IP slug, PR, reviewer, and merge state
+- time each PR spent waiting on review, when the host reports it
+- residual risk and anything deliberately deferred
+
+The round record is the campaign's memory. A fresh Track invocation must be able to state
+the whole trajectory from state alone.
+
+## Deciding the next move
+
+After re-measuring, Track picks exactly one:
+
+| Condition | Next |
+| --- | --- |
+| Backlog still has planned findings within budget | `plot` |
+| Backlog empty, rounds remaining, metric short of target | `sweep` |
+| Metric reached target and held after the last slice landed | `null` — campaign complete |
+| Two consecutive rounds moved the metric less than the charter's minimum step | `null` — report diminishing returns and ask |
+| Metric moved the wrong way after a landed slice | `null` — report the regression with evidence and ask |
+| Budget or horizon exhausted | `null` — report progress and ask |
+
+Diminishing returns, regressions, and exhausted budgets are **reports with a question**,
+not silent stops. Each includes the trajectory, what was fixed, what remains, options,
+and a recommended default.
+
+## Re-baselining
+
+Do not move the baseline to make progress look better. Re-baseline only when the metric
+command or measurement protocol changes, and then record both the old and new values, the
+reason, and the round it changed in. A campaign whose baseline was rewritten without that
+record is not trustworthy and Track must say so.

package/references/heartbeat.md

@@ -0,0 +1,91 @@
+# Heartbeat
+
+A campaign spends most of its wall-clock time waiting on humans and CI. The heartbeat is
+how one resident session stays useful during that wait without spamming anyone.
+
+One tick = one bounded pass over the campaign's open PRs and its backlog. A tick that
+finds nothing to do produces **no output** and schedules the next one.
+
+## Tick procedure
+
+1. **Snapshot.** One listing of the campaign's PRs, by the charter's label when it has
+   one, otherwise by the recorded PR numbers in campaign state:
+
+   ```bash
+   gh pr list --author @me --label <goal-slug> --state open \
+     --json number,title,headRefOid,isDraft,mergeable,reviewDecision,statusCheckRollup,reviewRequests,comments,updatedAt
+   ```
+
+   Reconcile the result against campaign state: a PR that merged, closed, or gained a new
+   head since the last tick has changed status regardless of what state remembers.
+
+2. **Classify each PR** into exactly one bucket:
+
+   | Bucket | Signal |
+   | --- | --- |
+   | `unrouted` | PR exists with no recorded reviewer/assignee |
+   | `answered` | A human comment, review, or requested change arrived after the last tick |
+   | `broken` | CI failed on the current head, the PR conflicts with its base, or a review-bot thread is unanswered |
+   | `bot-pending` | Review bots or CI still running on the current head |
+   | `merged` | Merged since the last tick |
+   | `closed` | Closed without merging |
+   | `waiting` | Green, routed, no new human input — waiting on review |
+
+3. **Act in priority order**, at most one PR per bucket per tick unless the tick budget
+   allows more:
+
+   1. `unrouted` → apply [`pr-routing.md`](pr-routing.md).
+   2. `answered` → invoke the lifecycle's Taste for that PR in a fresh subagent. Taste
+      owns reading the threads, making the fix, running the pre-push gate, pushing, and
+      watching CI. The loop does not answer review comments itself.
+   3. `broken` → same: one Taste invocation for that PR. Taste counts fix rounds across
+      ticks; when it returns `BLOCKED` after three, mark the PR `blocked` and surface it
+      at the top of the next report. A blocked PR is never left as a quiet `waiting`.
+   4. `merged` → invoke the scan Track stage for that slice: re-measure, close findings
+      with evidence, record the round.
+   5. `closed` → mark the slice `abandoned` with the closing reason, return its findings
+      to `open`, and surface it in the next report.
+   6. `bot-pending` and `waiting` → nothing. These are why the next tick exists.
+
+4. **Refill capacity.** After acting, if open campaign PRs are below `wipLimit` and the
+   backlog has planned findings, advance the campaign one step (Plot the next slice, or
+   Sweep when the backlog is empty).
+
+5. **Persist and schedule.** Update campaign state — including `lastTick`, each PR's
+   bucket, and the comment ids already answered — then choose the next interval and exit
+   the tick.
+
+## Answering exactly once
+
+Record the id of every comment, review, and thread the campaign has already acted on. A
+tick answers a human only when that id is new. Re-reading an old thread and replying again
+is the single most common way a resident agent becomes noise.
+
+Never post a status comment on a PR just because a tick ran. The only comments the
+campaign writes are the ones the lifecycle's own contracts call for.
+
+## Choosing the interval
+
+Match the wait, not the clock:
+
+| State | Interval |
+| --- | --- |
+| CI running on a head the campaign just pushed | Prefer the provider's watch hook (`gh pr checks --watch`, `circleci run watch`); fall back to 2–5 minutes |
+| Review bots queued on a new head | 2–5 minutes |
+| Everything green, waiting on a human reviewer | 15–30 minutes |
+| Nothing open and backlog work remains | No wait; continue the campaign immediately |
+| Nothing open, nothing planned, goal not met | 30–60 minutes, or stop and report if the charter's horizon passed |
+
+Prefer the harness's native scheduling or completion hooks over sleeping. Use a timer
+only when no hook applies. Never busy-poll a PR that is waiting on a person.
+
+## Tick safety
+
+- One tick never spawns more than one lifecycle stage per PR.
+- A tick that fails to reach the host (network, auth, rate limit) records the failure,
+  backs off to double the current interval up to the maximum, and tries again. Three
+  consecutive host failures is `BLOCKED` with `kind: access`.
+- A tick never rewrites history on a PR a human is reviewing: no force-push beyond what
+  the lifecycle's own push gate does, no branch deletion, no closing a human's PR.
+- Ticks are idempotent. A tick that dies mid-way leaves state consistent enough that the
+  next tick re-derives everything from the host snapshot.

package/references/mapreduce.md

@@ -0,0 +1,90 @@
+# Agentic map-reduce
+
+One agent reading a whole repository finds shallow problems and forgets the first file by
+the last. A scan instead **plans** detection rules, **shards** their hits into small
+batches, **maps** a fresh worker over each batch, and **reduces** the returned candidates
+into one ranked findings list.
+
+```text
+Aim   → rules, exclusions, validity rule, severity rubric   (plan)
+Sweep → rule hits → deterministic shards → parallel workers (shard + map)
+Sift  → dedupe → verify → drop → rank → report              (reduce)
+```
+
+## Plan (Aim)
+
+Each detection rule records:
+
+| Field | Meaning |
+| --- | --- |
+| `name` | stable slug used by every later stage |
+| `query` | the exact command: `rg` pattern, AST query, dependency query, build probe |
+| `matches` | what a hit means in one sentence |
+| `why` | how a fix moves the goal metric |
+| `exclude` | globs this rule must not report on |
+
+A rule is not approved until it has been **dry-run** and its hit count recorded. A rule
+with zero hits is removed or rewritten in Aim, never carried into Sweep as an empty
+promise. A rule with hits in the tens of thousands is narrowed before it ships.
+
+Default exclusions unless the charter says otherwise: dependency directories, build
+output, generated trees, lockfiles, snapshots, vendored code, and fixtures.
+
+## Shard (Sweep)
+
+Sharding is deterministic so a re-run of the same round produces the same shards:
+
+1. Run every approved rule and collect hits as `path:line:rule`.
+2. Group hits by their nearest meaningful unit — package, then directory, then file.
+3. Pack groups into shards up to the charter's shard budget (default: at most 25 files
+   or 80 hits per shard, whichever is reached first). Never split one file across shards.
+4. Sort shards by path so the manifest is stable, and write the manifest to the round's
+   artifact directory.
+5. Cap the number of shards at the charter's limit. When the cap truncates coverage,
+   record exactly which groups were dropped and why in the result — silent truncation
+   reads as "we looked everywhere" when the scan did not.
+
+## Map (Sweep)
+
+Each shard gets one fresh worker with no parent conversation. The briefing contains only:
+
+- the goal statement and metric, in one sentence each
+- the rules in play for this shard, with their `matches` and `why`
+- the shard's file list and the hit lines
+- the validity rule and severity rubric, quoted
+- the named commands the worker may run
+- the findings schema and the instruction to return that JSON and nothing else
+
+Worker rules:
+
+1. Treat the briefing as the working set. Do not scan outside the shard's files except
+   to read a definition or caller the shard's hits point at.
+2. Do not run a full-repository search, a full-branch diff, or the skill catalog.
+3. Do not spawn nested workers.
+4. Do not edit files, stage changes, or run anything destructive.
+5. Every candidate carries a `path:line` anchor plus the evidence that proves it.
+6. Report "no valid candidates" plainly; an empty shard is a normal outcome, and
+   inventing a marginal finding to look productive is a defect.
+
+Run workers concurrently up to the harness's practical limit. A worker that fails is
+retried once with the same briefing; a second failure records the shard as failed in the
+result and does not fail the whole sweep.
+
+## Reduce (Sift)
+
+1. **Normalize.** Give every candidate a dedupe key of `rule + path + symbol`. Merge
+   candidates that describe the same defect at different anchors into one finding with
+   all anchors listed.
+2. **Verify.** Re-check each surviving candidate against the charter's validity rule.
+   For `high` severity, verify adversarially: try to refute the finding, and keep it only
+   when refutation fails. Re-run the candidate's evidence command where one exists.
+3. **Drop.** Remove candidates whose evidence does not reproduce, whose anchor no longer
+   exists, that the validity rule excludes, or that cannot be tied to the goal metric.
+   Record the drop count and the top drop reasons.
+4. **Rank.** Order by goal impact × confidence ÷ effort. Severity is the charter's
+   rubric, not the worker's opinion.
+5. **Report.** Write the findings report: goal and metric header, one row per finding
+   with severity, effort, anchors, and evidence, then the dropped-candidate summary.
+
+A round that keeps zero findings is a valid result. Report it as a dry round and let
+Track decide whether to re-aim, widen the rules, or declare the goal met.

package/references/pr-routing.md

@@ -0,0 +1,77 @@
+# PR routing
+
+Every slice PR reaches a named human. A campaign that opens unassigned PRs is producing
+work nobody owns.
+
+Routing is decided once in Aim, recorded in the charter's `review` block, and applied by
+the campaign or the loop immediately after Brew creates the PR. It is never re-decided
+per PR by guesswork.
+
+## The review block
+
+| Field | Meaning |
+| --- | --- |
+| `mode` | `fixed`, `codeowners`, `blame`, `round-robin`, or `none` |
+| `reviewers` | Login handles requested for review |
+| `assignees` | Login handles set as assignee (who owns landing it); defaults to `reviewers` |
+| `teams` | Org team slugs requested for review, when the host supports them |
+| `draft` | Open PRs as drafts and mark ready only when CI on the head is green |
+| `labels` | Labels applied to every campaign PR, for example the goal slug |
+| `wipLimit` | Maximum campaign PRs open at once |
+| `mergePolicy` | `human` (default), or `agent-after-approval` with its exact conditions |
+| `notify` | How to nudge: PR body mention, no mention, or a named external channel |
+
+## Modes
+
+| Mode | Resolve reviewers by |
+| --- | --- |
+| `fixed` | The charter's explicit handles. Simplest, and the default when one person owns the goal. |
+| `codeowners` | The repository's `CODEOWNERS` entries for the slice's touched paths. Let the host apply them; do not duplicate the request. |
+| `blame` | The most frequent recent authors of the slice's touched files, excluding bots and the campaign's own commits. Cap at two. |
+| `round-robin` | Rotate through the charter's handle list, one per slice, recorded in state so the rotation survives a fresh invocation. |
+| `none` | Open the PR unassigned because the repository routes review elsewhere. Valid only when the charter says so explicitly. |
+
+When a mode resolves to nobody — no `CODEOWNERS` match, blame returns only bots, an empty
+handle list — fall back to the charter's `reviewers`, and if that is also empty, stop and
+ask. Do not invent a handle, and do not guess one from a commit email.
+
+## Applying routing
+
+After Brew reports the PR, and before the loop counts the slice as in flight:
+
+```bash
+gh pr edit <pr> --add-reviewer <handle> --add-assignee <handle> --add-label <label>
+gh pr ready <pr>            # only when draft is true and CI on the head is green
+```
+
+Record on the slice in campaign state: `pr`, `reviewer`, `assignee`, and the routing mode
+that chose them. A slice whose PR exists with no recorded reviewer is not routed yet; the
+next heartbeat tick routes it before doing anything else with that PR.
+
+When a push addresses changes that were requested, re-request review from the same
+handles rather than waiting silently:
+
+```bash
+gh pr edit <pr> --add-reviewer <handle>
+```
+
+## Verifying a handle
+
+Before using a handle the campaign has not used before, verify it can be requested:
+
+```bash
+gh api "repos/{owner}/{repo}/collaborators/<handle>" --silent
+```
+
+A handle that fails verification is `BLOCKED` with `kind: human`: name the handle, say it
+could not be requested, and ask who should review instead. Never quietly open the PR
+unassigned when the charter asked for a reviewer.
+
+## What the campaign must not do
+
+- Do not approve its own PRs, dismiss reviews, or resolve another person's review thread.
+- Do not merge when `mergePolicy` is `human`, even with approval and green CI.
+- Do not `@`-mention on every push. One routing action per PR, plus one re-request when
+  requested changes have been addressed.
+- Do not exceed `wipLimit`. Waiting on review is correct behavior, not a reason to start
+  more work.