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

package/skills/1-aim/references/charter.md

@@ -0,0 +1,96 @@
+# Charter template
+
+One file per goal. Keep it readable by someone who was not in the grilling conversation.
+
+```markdown
+# Scan charter — <goal statement>
+
+- Slug: <goal-slug>
+- Status: draft | approved (<date>)
+- Owner: <human>
+
+## Goal
+
+<One paragraph: where the repository is today, where this campaign takes it, and why now.>
+
+## Metric
+
+| Field | Value |
+| --- | --- |
+| Name | <what is measured> |
+| Command | `<command that prints the number>` |
+| Unit | s / ms / count / percent / bytes |
+| Direction | down / up |
+| Protocol | <cold vs warm, best of three, machine class> |
+| Baseline | <value> (measured <date>) |
+| Target | <value> |
+| Horizon | <rounds or date> |
+
+Baseline evidence:
+
+```text
+<quoted command output>
+```
+
+## Scope
+
+- In scope: <packages, directories, layers>
+- Out of scope: <areas the campaign must not touch>
+- Unacceptable trade-offs: <for example, no public API breaks, no new dependencies>
+
+## Detection rules
+
+| Rule | Query | Matches | Why it moves the metric | Hits |
+| --- | --- | --- | --- | --- |
+| <slug> | `<command>` | <one sentence> | <one sentence> | <n> |
+
+## Exclusions
+
+<Globs never reported on, beyond the defaults in the map-reduce reference.>
+
+## Validity rule
+
+A finding is valid only when <one sentence>.
+
+## Severity rubric
+
+| Severity | Threshold |
+| --- | --- |
+| high | <concrete threshold> |
+| medium | <concrete threshold> |
+| low | <concrete threshold> |
+
+Effort: S = under an hour, M = under a day, L = more than a day or needs design.
+
+## Slice policy
+
+- Maximum <n> files and <n> findings per slice
+- Never mix: <combinations that make review unsafe>
+- Always its own slice: <risky or reviewer-heavy categories>
+
+## Review routing
+
+| Field | Value |
+| --- | --- |
+| Mode | fixed / codeowners / blame / round-robin / none |
+| Reviewers | <@handle, @handle> |
+| Assignee | <@handle> |
+| Teams | <org/team> |
+| Draft | yes / no |
+| Labels | <goal-slug, ...> |
+| Merge policy | human / agent-after-approval (<conditions>) |
+| Notify | PR body mention / none / <channel> |
+
+## Budget
+
+- Rounds: <n>
+- Slices per round: <n>
+- Open PRs at once (`wipLimit`): <n>
+- Minimum metric step per round before reporting diminishing returns: <value>
+
+## Decisions
+
+| Decision | Question that prompted it |
+| --- | --- |
+| <settled decision> | <the exact question asked> |
+```

package/skills/2-sweep/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: 2-sweep
+description: Run an approved scan charter across the repository — execute detection rules, shard the hits deterministically, and map fresh parallel workers over the shards into schema-valid candidate findings. Use after a scan charter is approved, or to re-sweep a later campaign round; not for shaping goals, ranking findings, or writing code.
+---
+
+# Sweep — shard and map
+
+Execute the approved charter across the repository and return raw candidate findings with
+reproducible evidence. Sweep discovers; it does not judge, rank, or fix.
+
+Read the shared [`scan contract`](../../references/scan-contract.md) and
+[`agentic map-reduce`](../../references/mapreduce.md), plus the
+[`worker briefing`](references/worker-briefing.md), before acting.
+
+## Preconditions
+
+- An approved charter and campaign state exist for this goal.
+- The working tree is clean enough that `path:line` anchors are stable; record the head
+  SHA the sweep ran against.
+- This invocation owns discovery only. It never edits files.
+
+## Inputs
+
+- Charter: rules, exclusions, validity rule, severity rubric, effort scale
+- Campaign state: goal, round, prior findings and their status
+- Repository code, tests, build output, and available skills
+
+## Procedure
+
+1. **Reconstruct.** Read the charter and campaign state. Verify the branch and head, and
+   increment the round when the previous round is closed.
+2. **Discover supporting skills.** Load repository skills matching the rules in play.
+3. **Run the rules.** Execute each rule's query with its exclusions. Record hit counts per
+   rule and compare them to the charter's dry-run counts. A rule that now returns zero or
+   an order of magnitude more hits is reported in the result — the repository moved, and
+   Sift must know.
+4. **Shard.** Group and pack the hits into deterministic shards per the map-reduce
+   reference. Write the shard manifest to the round's artifact directory. When the shard
+   cap truncates coverage, name exactly what was dropped.
+5. **Map.** Spawn one fresh worker per shard with no parent conversation, using the
+   worker briefing. Run them concurrently up to the harness's practical limit. Each worker
+   returns candidates conforming to
+   [`finding.schema.json`](../../references/finding.schema.json) and nothing else.
+6. **Collect.** Validate every returned candidate against the schema. Drop malformed
+   entries and record how many and from which shard. Retry a failed worker once with the
+   same briefing; record a second failure as a failed shard without failing the sweep.
+7. **Persist.** Write the candidate set to the round's artifact directory, update campaign
+   state with the round, rules, shard count, and candidate count, and emit the result.
+
+## Constraints
+
+- Never edit, stage, or commit files. Never run destructive commands.
+- Never let a worker roam outside its shard beyond following a hit's definition or caller.
+- Never fabricate a candidate to make a shard look productive; empty shards are normal.
+- Never silently truncate. Dropped shards, capped groups, and malformed returns all appear
+  in the result.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Typical matches are static-analysis, build,
+performance-measurement, or domain skills named by the charter's rules.
+
+## Evidence produced
+
+- Head SHA, round number, and per-rule hit counts with drift against the charter
+- Shard manifest path and shard count
+- Candidate findings artifact path and candidate count
+- Failed shards, malformed candidates, and any coverage the caps dropped
+
+## Success conditions
+
+- Every approved rule ran, or a `FAIL` names the rule that could not.
+- Every shard was mapped or explicitly recorded as failed.
+- Every candidate validates against the finding schema and carries a `path:line` anchor.
+- Emit `PASS` with `next: sift`.
+
+## Failure conditions
+
+A rule that cannot execute, a shard manifest that does not cover the hits, or a candidate
+set that fails schema validation emits `FAIL` with exact evidence, `next: sweep`, and the
+smallest retry — usually re-running the named rule or re-mapping the named shards.
+
+## Blocked conditions
+
+Missing tooling, unreadable paths, or a harness that cannot spawn workers emits `BLOCKED`
+with the exact capability required.
+
+## Recommended next stage
+
+- `PASS` → Sift
+- `FAIL` → Sweep with the named rule or shard
+- `BLOCKED` → campaign loop routes the named environment/access gate

package/skills/2-sweep/references/worker-briefing.md

@@ -0,0 +1,70 @@
+# Worker briefing
+
+One briefing per shard. The worker has no parent memory and must not rediscover the
+repository. Send exactly these sections.
+
+```markdown
+## Goal
+
+<goal statement>. Metric: <metric name>, currently <value><unit>, target <value><unit>.
+
+## Rules in play
+
+| Rule | Matches | Why it moves the metric |
+| --- | --- | --- |
+| <slug> | <one sentence> | <one sentence> |
+
+## Validity rule
+
+A finding is valid only when <charter sentence, quoted verbatim>.
+
+## Severity rubric
+
+<charter rubric table, quoted verbatim, plus the effort scale>
+
+## Your shard
+
+Files:
+- <path>
+- <path>
+
+Hits:
+- <path>:<line> — <rule>
+- <path>:<line> — <rule>
+
+## Commands you may run
+
+- `<named command>`
+- `<named command>`
+
+## Rules of engagement
+
+1. Work only inside the shard's files. You may read a definition or caller a hit points
+   at; do not search the repository at large.
+2. Do not edit, stage, or commit anything. Do not run destructive commands.
+3. Do not spawn other agents.
+4. Every candidate needs a `path:line` anchor and reproducible evidence: the command you
+   ran and its output, or the exact code excerpt that proves the claim.
+5. If the shard has no valid candidates, return an empty array. That is a correct answer.
+
+## Return this and nothing else
+
+A JSON array of objects conforming to the finding schema:
+
+[
+  {
+    "id": "<shard>-<n>",
+    "rule": "<rule slug>",
+    "title": "<one line>",
+    "severity": "high|medium|low",
+    "confidence": "high|medium|low",
+    "effort": "S|M|L",
+    "anchors": [{"path": "<path>", "line": 42, "symbol": "<optional>"}],
+    "why": "<how fixing this moves the metric>",
+    "fix": "<the smallest change that would resolve it>",
+    "ev": "<command + output, or the proving excerpt>"
+  }
+]
+```
+
+No prose, no transcript, no restated instructions.

package/skills/3-sift/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: 3-sift
+description: Reduce raw scan candidates into a trustworthy findings report — dedupe, adversarially verify, drop what does not reproduce or does not move the goal metric, rank by impact over effort, and write the round's findings report. Use after a sweep returns candidates; not for running detection rules, shaping goals, or writing code.
+---
+
+# Sift — reduce
+
+Turn a pile of worker candidates into a short, ranked, defensible findings list. A
+finding that survives Sift is one an engineer can act on without re-investigating.
+
+Read the shared [`scan contract`](../../references/scan-contract.md),
+[`agentic map-reduce`](../../references/mapreduce.md), and
+[`goal tracking`](../../references/goal-tracking.md) before acting.
+
+## Preconditions
+
+- A sweep for the current round produced a candidate artifact.
+- The charter's validity rule, severity rubric, and effort scale are available.
+- This invocation owns reduction only. It never edits product code.
+
+## Inputs
+
+- Candidate findings artifact and shard manifest for this round
+- Charter: validity rule, severity rubric, effort scale, exclusions, metric
+- Campaign state: prior findings and their status, including previously dismissed ones
+
+## Procedure
+
+1. **Reconstruct.** Read campaign state, the charter, and the round's candidates. Verify
+   the recorded head still matches the working tree; re-anchor or re-sweep if it moved.
+2. **Normalize and dedupe.** Give each candidate the dedupe key `rule + path + symbol`.
+   Merge candidates describing one defect at several anchors into one finding carrying all
+   anchors. Fold candidates matching a previously dismissed finding into that dismissal
+   instead of resurrecting them, unless new evidence contradicts the dismissal.
+3. **Verify.** Re-check each surviving candidate against the validity rule. Re-run the
+   candidate's evidence command when it has one. For every `high` severity candidate,
+   verify adversarially: state the strongest case that the finding is wrong, and keep it
+   only when that refutation fails. Downgrade confidence rather than deleting evidence.
+4. **Drop.** Remove candidates whose evidence does not reproduce, whose anchor no longer
+   exists, that an exclusion covers, or whose link to the metric cannot be stated in one
+   sentence. Count the drops and the top drop reasons.
+5. **Rank.** Score by goal impact × confidence ÷ effort. Apply the charter's severity
+   rubric yourself; a worker's severity is an input, not the verdict.
+6. **Report.** Write the round's findings report to the repository's scan convention
+   (default `docs/scans/<goal-slug>/round-<n>-findings.md`): goal and metric header, the
+   ranked findings table with severity, effort, anchors, and evidence, one short paragraph
+   per high-severity finding, and the dropped-candidate summary with counts and reasons.
+7. **Persist.** Merge surviving findings into campaign state with status `open`, keep the
+   dismissal record for dropped ones, update state, and emit the result.
+
+## Constraints
+
+- No finding ships without reproducible evidence and a stated metric link.
+- No silent deletion: every dropped candidate is counted and its reason categorized.
+- Severity comes from the charter's thresholds, never from adjectives.
+- A round that keeps zero findings is a valid dry round, not a failure.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Verification of a candidate may require the same
+build, test, performance, or domain skills the rules named.
+
+## Evidence produced
+
+- Findings report path, kept count, and dropped count with reasons
+- Per-finding severity, confidence, effort, anchors, and evidence
+- Adversarial verification outcome for every high-severity finding
+- Updated campaign state and structured Sift result
+
+## Success conditions
+
+- Every kept finding is deduped, verified, evidenced, ranked, and tied to the metric.
+- Every high-severity finding survived an explicit refutation attempt.
+- A fresh Plot invocation can slice the work from the report alone.
+- Emit `PASS` with `next: plot`, or `PASS` with `next: track` when the round is dry.
+
+## Failure conditions
+
+Candidates that cannot be read or validated, a report that contradicts its own evidence,
+or unverifiable high-severity claims emit `FAIL` with exact defects and `next: sift`, or
+`next: sweep` when the candidate set itself is unusable.
+
+## Blocked conditions
+
+Missing tooling needed to reproduce evidence, or a metric link that requires a product
+decision, emits `BLOCKED` with the exact decision or capability required.
+
+## Recommended next stage
+
+- `PASS` with findings → Plot
+- `PASS` with no findings → Track (dry round)
+- `FAIL` → Sift, or Sweep when candidates are unusable
+- `BLOCKED` → campaign loop routes the named gate

package/skills/4-plot/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: 4-plot
+description: Turn ranked scan findings into PR-sized slices and hand the top slice to the Terreno IP and task system, writing a Grow-ready brief with metric-linked acceptance criteria and verification methods for each slice. Use after a sift produces a findings report; not for discovering findings, implementing them, or PR operations.
+---
+
+# Plot — findings to IPs and tasks
+
+A findings report is not work. Plot converts ranked findings into ordered, PR-sized
+slices and hands the top one to the lifecycle, which owns the IP, the task list, and the
+implementation.
+
+Read the shared [`scan contract`](../../references/scan-contract.md),
+[`goal tracking`](../../references/goal-tracking.md), and
+[`PR routing`](../../references/pr-routing.md) before acting.
+
+## Preconditions
+
+- A findings report exists for the current round with at least one kept finding.
+- The charter's slice policy and budget are available.
+- The lifecycle skills (`1-grow`, `2-pick`, `3-roast`,
+  `4-brew`, `5-taste`) are installed. If they are not, emit `BLOCKED`
+  naming the missing plugin — Plot must not implement findings itself.
+
+## Inputs
+
+- Findings report and campaign state for this round
+- Charter: slice policy, budget, unacceptable trade-offs, metric
+- Repository IP/task conventions and available skills
+
+## Procedure
+
+1. **Reconstruct.** Read campaign state and the findings report. Resolve the repository's
+   IP and task conventions the same way Grow does; do not invent a second convention.
+   Skip findings already `planned`, `fixed`, or `dismissed`.
+2. **Slice.** Group open findings into units that fit the charter's slice policy: one
+   theme per slice, within the file and finding caps, never mixing combinations the
+   charter forbids, and giving risky or reviewer-heavy findings their own slice. Order
+   slices by rank, then by dependency — a slice that unblocks others goes first.
+3. **Respect the budget.** Plan at most the charter's slices per round and never exceed
+   its open-PR limit (`wipLimit`) counting PRs already open. Findings beyond the budget stay `open` for the next round; say so
+   explicitly rather than quietly dropping them.
+4. **Write a Grow brief per slice.** Each brief is standalone and contains:
+   - the goal statement, the metric, and the current value
+   - the findings in this slice with their anchors, evidence, and proposed fixes
+   - the acceptance criteria, each observable and each paired with a verification method
+     (test, build probe, runtime/API/database check, artifact, regression case)
+   - at least one criterion that ties back to the metric or names why this slice cannot
+     move it alone
+   - an `## E2E tests` section listing the slice's planned specs, or `None — <reason>`.
+     Use the table format of the testing plan contract in the `terreno-planning` plugin
+     (`references/testing-plan.md`, read by `1-grow`). Take each spec's path and
+     layer from the e2e guide that the agent instructions' `## Testing conventions` table
+     names, or from the contract's default. Pair every UI or cross-process criterion with
+     a row or a reason. Leave `Written in` for Grow to fill. When no guide exists at that
+     path, use the contract's layer names and say so; Grow adds the guide task, so this
+     is not `BLOCKED`
+   - a `## Regression cases` section listing the manual cases the slice adds or changes,
+     or `None — <reason>`, in the testing plan's table format with provisional
+     `<AREA>-new-<n>` IDs. Each case meets the contract's regression-step bar. Leave
+     `Added` for Grow to fill
+   - a `## User guide` section listing the end-user guide pages the slice adds, updates,
+     or retires, or `None — <reason>`, in the user-guide table format of the
+     `terreno-planning` plugin (`references/user-guide.md`). Leave `Written in` for Grow
+     to fill. A repository whose `## User guide conventions` table sets `none` writes
+     `None — user guide off`
+   - the unacceptable trade-offs from the charter, quoted
+   - the docs the slice must create or update
+   - known blockers, dependencies on other slices, and residual risk
+   - the reviewer and assignee this slice routes to, resolved from the charter's `review`
+     block; a slice whose routing cannot be resolved is `BLOCKED`, not opened unassigned
+5. **Persist the plan.** Write briefs to the round's artifact directory, record every
+   slice in campaign state with status `planned` and its finding ids, and mark those
+   findings `planned` with their slice slug.
+6. **Hand off.** Emit `PASS` with `next: track` and `handoff: grow`, naming the top
+   slice's brief path. The campaign loop invokes `1-grow` with that brief, then
+   the Pick/Roast inner loop, then Brew and Taste. Plot itself never invokes them, never
+   edits product code, and never opens a PR.
+
+## Constraints
+
+- Plot writes briefs, not IPs. Grow owns the IP, the task list, and human approval.
+- A slice with no metric-linked criterion needs an explicit sentence saying why.
+- Never merge findings from different rules into one slice purely to hit the budget.
+- Never mark a finding `fixed`; only Track does that, and only with evidence.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Slice briefs may name domain skills for the
+lifecycle to load, but Grow and Pick still perform their own discovery.
+
+## Evidence produced
+
+- Slice plan with order, rationale, and the findings in each slice
+- Brief path per slice, its resolved reviewer/assignee, the acceptance-criterion →
+  verification mapping, and its `## E2E tests` and `## Regression cases` sections
+- Findings deferred to a later round, with the budget reason
+- Updated campaign state and structured Plot result
+
+## Success conditions
+
+- Every planned slice fits the slice policy and has a standalone, criterion-complete
+  brief with both testing-plan sections, each holding rows or `None — <reason>`.
+- Every open finding is either planned into a slice or explicitly deferred with a reason.
+- A fresh Grow invocation can produce an approved IP and task list from one brief alone.
+- Emit `PASS` with `next: track` and `handoff: grow`.
+
+## Failure conditions
+
+Slices that violate the policy, briefs missing verification methods or a testing-plan
+section, or findings silently lost between the report and the plan emit `FAIL` with exact
+defects and `next: plot`.
+
+## Blocked conditions
+
+A missing lifecycle plugin, an IP convention that cannot be resolved, or a finding whose
+fix requires a product, security, or compatibility decision emits `BLOCKED` with options,
+tradeoffs, and a recommended default.
+
+## Recommended next stage
+
+- `PASS` → Track, after the campaign loop runs the handed-off slice through Grow, the
+  Pick/Roast inner loop, Brew, and Taste
+- `FAIL` → Plot with defect evidence
+- `BLOCKED` → campaign loop routes the named human/external gate

package/skills/5-track/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: 5-track
+description: Re-measure a scan campaign's goal metric after slices land, close or reopen findings with evidence, record the round, and choose the next move — more slices, a fresh sweep, or a report with one question. Use after a plotted slice finishes in the lifecycle or a round is dry; not for discovering findings, planning slices, or writing code.
+---
+
+# Track — measure and decide
+
+A campaign is only working if the number moved. Track re-measures the goal metric,
+reconciles the findings against reality, records the round, and names the next move.
+
+Read the shared [`scan contract`](../../references/scan-contract.md),
+[`goal tracking`](../../references/goal-tracking.md), and
+[`heartbeat`](../../references/heartbeat.md) before acting.
+
+## Preconditions
+
+- Campaign state exists with a metric, a baseline, and at least one round in progress.
+- Either a plotted slice has finished in the lifecycle, or the round was dry.
+- This invocation owns measurement and routing only. It never edits product code.
+
+## Inputs
+
+- Campaign state: goal, metric, baseline, rounds, findings, slices
+- Findings report and slice briefs for the round
+- Merge state of each slice's PR and the current head
+
+## Procedure
+
+1. **Reconstruct.** Read campaign state. Resolve each running slice's real status — PR
+   open, merged, closed, abandoned — from the repository, not from state's memory.
+2. **Wait when the work is still moving.** If a slice is mid-lifecycle (open PR, CI
+   running, review bots pending), emit `PENDING` with a `wait` and let the campaign loop
+   return. Prefer the harness's native completion hook or the provider's watch hook; use
+   a timer only when no hook applies. Do not close findings against unmerged work.
+3. **Re-measure.** Run the metric command exactly as the charter's protocol specifies, on
+   the branch the charter names (usually the default branch after merge). Quote the output
+   as evidence and compute the delta against both the baseline and the round start.
+4. **Reconcile findings.** For each finding in a landed slice, verify against the current
+   code: re-run its evidence command or re-check its anchor.
+   - Gone and the fix is present → `fixed`
+   - Still reproducible → `reopened`, with the new evidence and a one-line reason
+   - Anchor moved but the defect persists → update anchors, keep it open
+   Never mark a finding `fixed` because a task was checked off; only evidence closes a
+   finding.
+5. **Catch regressions.** If the metric moved the wrong way, or a previously fixed finding
+   is reproducible again, record it with evidence and treat it as the headline of this
+   round, not a footnote.
+6. **Retire closed slices.** A slice whose PR was closed without merging is `abandoned`:
+   record the closing reason, return its findings to `open`, and free its slot against the
+   open-PR limit.
+7. **Record the round.** Append the round record per `goal-tracking.md`: metric at start
+   and end with command output, found/kept/planned/fixed/dismissed/reopened counts, slices
+   landed with their PRs, residual risk, and anything deliberately deferred.
+8. **Choose the next move.** Apply the decision table in `goal-tracking.md`: `plot` while
+   planned findings remain within budget, `sweep` when the backlog is empty and rounds
+   remain, `null` when the target is reached and held, when two rounds moved less than the
+   charter's minimum step, when the metric regressed, or when the budget or horizon is
+   exhausted.
+9. **Report and persist.** Lead with the trajectory in one line — baseline → previous →
+   current against target. Update campaign state and emit the result collapsed. When a
+   slice's PR has GitHub Deployments, close the message with those demo URLs as the last
+   visible section.
+
+## Constraints
+
+- Never re-baseline to flatter the campaign; re-baseline only per the goal-tracking rules
+  and record both values and the reason.
+- Never report a metric value without its command output.
+- Never close a round while a slice's PR is unmerged; emit `PENDING` instead.
+- Diminishing returns, regressions, and exhausted budgets are reports with one question,
+  not silent stops.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Measurement may require the same build, test,
+performance, or analysis skills the charter's metric command depends on.
+
+## Evidence produced
+
+- Metric value with quoted command output, and deltas against baseline and round start
+- Per-finding closure evidence: fixed, reopened, or still open with anchors
+- Round record appended to campaign state
+- Regression report when the metric or a fixed finding moved the wrong way
+- The chosen next move with its reason
+
+## Success conditions
+
+- The metric was re-measured with the charter's protocol and its output is quoted.
+- Every finding in a landed slice was reconciled against current code with evidence.
+- The round record makes the whole trajectory readable from state alone.
+- Emit `PASS` with `next: plot`, `next: sweep`, or `next: null` per the decision table.
+
+## Failure conditions
+
+A metric command that cannot run, a round record that contradicts the repository's real
+merge state, or findings closed without evidence emit `FAIL` with exact defects and
+`next: track`.
+
+## Blocked conditions
+
+Missing measurement tooling or access, or a decision about whether to continue the
+campaign that only a human can make, emits `BLOCKED` with the trajectory, options,
+tradeoffs, and a recommended default.
+
+## Recommended next stage
+
+- `PASS` with planned findings remaining → Plot
+- `PASS` with an empty backlog and rounds remaining → Sweep
+- `PASS` with the target reached, the budget spent, or a regression → `null`, report and
+  ask
+- `PENDING` → campaign loop waits for the running slice and reinvokes Track
+- `BLOCKED` → campaign loop routes the named human/external gate