@terreno/agent-plugin-loop 0.0.0-stage → 57.22.0

package/references/scan-contract.md

@@ -0,0 +1,195 @@
+# Scan contract
+
+Aim, Sweep, Sift, Plot, and Track are **transitions**, not the orchestration loop.
+`terreno-loop-campaign` is the invocable outer loop; it must never be recorded as a
+`stage` value.
+
+A scan is not a code change. Scan stages discover, prioritize, and shape work; the
+Terreno lifecycle (`terreno-1-grow`, `terreno-2-pick`, `terreno-3-roast`,
+`terreno-4-brew`, `terreno-5-taste`) implements and ships it. No scan stage edits
+product code, commits, pushes, or opens a PR.
+
+Two outer loops drive the stages. `terreno-loop-campaign` runs bounded rounds and stops
+at each gate. `terreno-loop-run` stays resident: it keeps the campaign moving, routes
+every PR to a named human per [`pr-routing.md`](pr-routing.md), and heartbeats over open
+PRs per [`heartbeat.md`](heartbeat.md) so review comments, red CI, and merges are handled
+without a person restarting anything.
+
+| Owner | Responsibility |
+| --- | --- |
+| Campaign loop | when to invoke, which agent, persistence, retry, stop, escalation, lifecycle handoff |
+| Resident loop | the same, plus PR routing, the heartbeat over open PRs, and scheduling |
+| Scan stage | one bounded transition plus its evidence |
+| Lifecycle stages | implementing, proving, submitting, and landing one plotted slice |
+| Repository skills | repository commands, architecture, safety rules, and domain conventions |
+| Campaign state | what a fresh invocation needs from previous rounds |
+
+Every stage reads durable inputs, performs one bounded transition, writes campaign
+state, emits one result document, and exits. Never rely on conversational memory.
+
+## Stages
+
+| Stage | Transition | PASS next |
+| --- | --- | --- |
+| `aim` | Goal, metric, baseline, detection rules, exclusions, validity rule, severity rubric, slice policy; human approval | `sweep` |
+| `sweep` | Shard the rule hits and map parallel workers over the shards into candidate findings | `sift` |
+| `sift` | Reduce: dedupe, verify, drop unfounded, rank, write the findings report | `plot`, or `track` when the round is dry |
+| `plot` | Turn ranked findings into PR-sized slices and hand the top slice to the lifecycle | `track` with `handoff: grow` |
+| `track` | Re-measure the goal metric, close or reopen findings, record the round, choose the next move | `plot`, `sweep`, or `null` |
+
+## Goal before findings
+
+A campaign exists to move one measurable goal, not to collect observations. Aim must
+produce a metric with a command that prints it, a baseline captured by running that
+command, and a target. Every later stage justifies its output by that metric:
+
+- A detection rule that cannot plausibly move the metric does not belong in the charter.
+- A finding that cannot be tied to the metric is dismissed in Sift, not deferred.
+- A slice that lands without a metric re-measurement in Track is unproven work.
+
+See [`goal-tracking.md`](goal-tracking.md).
+
+## Evidence
+
+Every candidate and every finding carries reproducible evidence: a `path:line`
+anchor plus the command, query, probe output, or artifact that produced it. Findings
+without evidence are dropped in Sift, never carried forward with a caveat. Never persist
+chain-of-thought, worker transcripts, or speculative narration.
+
+## Discover supporting skills
+
+At the start of every stage:
+
+1. Inspect skills exposed by the harness and repository.
+2. Match their descriptions to **this round's rules, files, and findings**, not the
+   whole catalog.
+3. Load applicable `SKILL.md` files before acting and record their names in `skills`.
+4. If repository instructions require a capability and it is unavailable, return
+   `BLOCKED`; never silently skip it.
+5. If no skill applies, infer conventions from repository instructions, existing code,
+   tests, package scripts, and recent analogous changes.
+
+The lifecycle plugin's stages perform their own discovery once a slice is handed off.
+Scan stages do not pre-resolve implementation skills for them.
+
+## Map workers
+
+Sweep spawns fresh workers with no parent memory. Each worker receives a
+**shard briefing** and returns schema-valid findings only. Workers never reconstruct the
+repository, never run a full-branch diff, never spawn nested workers, and never edit
+files. See [`mapreduce.md`](mapreduce.md).
+
+## Documentation
+
+Scan stages write scan artifacts (charter, findings report, round records). They do not
+write product architecture docs. The plotted slices carry documentation work: every task
+Plot writes names the docs to create or update, and the lifecycle's documentation
+contract applies when that slice runs.
+
+## Stage result
+
+The machine-readable result is for the next skill and the campaign loop. It is **not**
+the human-facing answer.
+
+Lead the chat with `status`, `next`, and `action` in one or two lines, plus the current
+metric when the stage measured one. Put the YAML only in a collapsed details block.
+
+The schema is [`scan-result.schema.json`](scan-result.schema.json) (`v: 2`). Required
+keys are `v`, `stage`, `status`, `next`, and `action`. Omit nulls and empty arrays.
+Status values are exactly `PASS`, `FAIL`, `BLOCKED`, or `PENDING`.
+
+Wrap the YAML:
+
+```html
+<details>
+<summary>Scan result</summary>
+</details>
+```
+
+Example payload:
+
+```yaml
+v: 2
+stage: sift
+status: PASS
+goal: reduce-cold-build-time
+round: 2
+found: 31
+kept: 12
+metric:
+  value: 48.2
+  unit: s
+  ev: "bun run compile (cold): 48.2s"
+artifacts:
+  - docs/scans/reduce-cold-build-time/round-2-findings.md
+next: plot
+action: Slice the four high-severity findings into the first PR-sized unit of work
+```
+
+| Key | Meaning |
+| --- | --- |
+| `goal` | campaign goal slug |
+| `round` | current sweep round |
+| `metric` | measured metric value, unit, delta, and the command that produced it |
+| `found` / `kept` / `closed` | candidate, surviving, and resolved finding counts |
+| `skills` | supporting skills loaded |
+| `artifacts` | charter, candidate file, findings report, slice briefs |
+| `handoff` | lifecycle stage the campaign must invoke next (`grow` or `pick`) |
+| `fail` | `need` / `want` / `got` / `ev` |
+| `block` | `kind` / `why` / optional `ev` |
+| `ask` | human questions: `q` / `rec` / optional `opts` |
+| `next` | recommended next scan stage or `null` |
+| `action` | concrete next action |
+| `wait` | seconds until the campaign should check a handed-off slice again |
+
+## Campaign state
+
+The charter and the findings report remain authoritative for scope and evidence.
+Campaign state is a small loop-owned handoff, not a third plan.
+
+Use an existing repository convention when present. Otherwise use
+`.terreno/scan/<goal-slug>.json`, conforming to
+[`scan-state.schema.json`](scan-state.schema.json). The campaign loop must preserve or
+transport this file between fresh invocations. Do not commit it unless the repository
+explicitly tracks scan state; lifecycle Brew must exclude loop-owned state from PR
+commits.
+
+Each invocation:
+
+1. Read state and verify its goal, round, branch, and findings against reality.
+2. Increment `attempt` for the invoked stage.
+3. Consume `last` and prior `tried` approaches; do not repeat a failed approach without
+   new evidence.
+4. Perform the stage.
+5. Replace `last`, merge artifact references, and set `next`.
+6. Emit the same result to the caller so the loop can persist it elsewhere.
+
+These six operations are mandatory whenever a stage says "update campaign state." Every
+result also includes a concrete `action`, even when `next` is `null`.
+
+If no writable artifact exists, still emit the result. If the campaign loop cannot
+preserve that result for the next fresh invocation, return `BLOCKED` and name the
+missing state transport.
+
+## Failures, blockers, and pending
+
+- `FAIL`: objective failure of this stage — an unproven detection rule, a malformed
+  candidate set, a findings report that contradicts its evidence. Preserve exact
+  evidence and recommend the smallest retry.
+- `BLOCKED`: no safe action exists now. Classify `human`, `environment`, `access`, or
+  `external`; include the exact action or decision required.
+- `PENDING`: a handed-off slice is still moving through the lifecycle, a PR is waiting on
+  review or CI, or a long measurement has not finished. Include `wait`; the **campaign or
+  resident loop** waits and invokes again. Prefer the harness's native completion hook or the provider's watch hook over
+  sleep polling; use a timer only when no hook applies.
+- `PASS`: this stage's success conditions are proven for the recorded round.
+
+Human gates include the goal statement and target, destructive or irreversible
+remediation, public API or data-format changes surfaced by findings, scope growth beyond
+the approved charter, and policy-required approval. Include options, tradeoffs,
+evidence, and a recommended default.
+
+A campaign requesting human input must first summarize goal state, metric movement,
+completed rounds, decisive evidence, options and impact, and a recommended default. It
+ends with one exact question, then the Demo section when a handed-off PR has deployment
+URLs. Objective failures are not human gates while a concrete safe action remains.

package/references/scan-result.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terreno.dev/schemas/scan-result.schema.json",
+  "title": "Terreno scan stage result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["v", "stage", "status", "next", "action"],
+  "properties": {
+    "v": {"const": 2},
+    "stage": {"enum": ["aim", "sweep", "sift", "plot", "track"]},
+    "status": {"enum": ["PASS", "FAIL", "BLOCKED", "PENDING"]},
+    "goal": {"type": "string"},
+    "round": {"type": "integer", "minimum": 1},
+    "attempt": {"type": "integer", "minimum": 1},
+    "branch": {"type": "string"},
+    "sha": {"type": "string"},
+    "pr": {"type": "string"},
+    "skills": {"type": "array", "items": {"type": "string"}},
+    "rules": {"type": "array", "items": {"type": "string"}},
+    "shards": {"type": "integer", "minimum": 0},
+    "found": {"type": "integer", "minimum": 0},
+    "kept": {"type": "integer", "minimum": 0},
+    "closed": {"type": "integer", "minimum": 0},
+    "metric": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "ev"],
+      "properties": {
+        "value": {"type": "number"},
+        "unit": {"type": "string"},
+        "delta": {"type": "number"},
+        "ev": {"type": "string"}
+      }
+    },
+    "done": {"type": "array", "items": {"type": "string"}},
+    "artifacts": {"type": "array", "items": {"type": "string"}},
+    "slices": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["slug", "findings", "status"],
+        "properties": {
+          "slug": {"type": "string"},
+          "ip": {"type": "string"},
+          "tasks": {"type": "string"},
+          "findings": {"type": "array", "items": {"type": "string"}},
+          "status": {"enum": ["planned", "running", "merged", "abandoned"]},
+          "pr": {"type": "string"}
+        }
+      }
+    },
+    "prs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pr", "bucket"],
+        "properties": {
+          "pr": {"type": "string"},
+          "bucket": {
+            "enum": ["unrouted", "answered", "broken", "bot-pending", "merged", "closed", "waiting"]
+          },
+          "who": {"type": "string"},
+          "slice": {"type": "string"}
+        }
+      }
+    },
+    "fail": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["need", "want", "got", "ev"],
+        "properties": {
+          "need": {"type": "string"},
+          "sev": {"enum": ["blocking", "non_blocking"]},
+          "want": {"type": "string"},
+          "got": {"type": "string"},
+          "ev": {"type": "string"}
+        }
+      }
+    },
+    "block": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "why"],
+        "properties": {
+          "kind": {"enum": ["human", "environment", "access", "external"]},
+          "why": {"type": "string"},
+          "ev": {"type": "string"}
+        }
+      }
+    },
+    "ask": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["q", "rec"],
+        "properties": {
+          "q": {"type": "string"},
+          "opts": {"type": "array", "items": {"type": "string"}},
+          "rec": {"type": "string"}
+        }
+      }
+    },
+    "handoff": {
+      "type": ["string", "null"],
+      "enum": ["grow", "pick", null]
+    },
+    "next": {
+      "type": ["string", "null"],
+      "enum": ["aim", "sweep", "sift", "plot", "track", null]
+    },
+    "action": {"type": "string"},
+    "wait": {"type": "integer", "minimum": 1}
+  }
+}

package/references/scan-state.schema.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terreno.dev/schemas/scan-state.schema.json",
+  "title": "Terreno scan campaign state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["v", "goal", "stage", "round", "attempt", "next"],
+  "properties": {
+    "v": {"const": 2},
+    "goal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "statement", "metric", "baseline", "target"],
+      "properties": {
+        "slug": {"type": "string"},
+        "statement": {"type": "string"},
+        "charter": {"type": "string"},
+        "metric": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "command", "unit", "direction"],
+          "properties": {
+            "name": {"type": "string"},
+            "command": {"type": "string"},
+            "unit": {"type": "string"},
+            "direction": {"enum": ["up", "down"]},
+            "protocol": {"type": "string"}
+          }
+        },
+        "baseline": {"type": "number"},
+        "target": {"type": "number"},
+        "current": {"type": "number"},
+        "horizon": {"type": "string"},
+        "review": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": {
+            "mode": {"enum": ["fixed", "codeowners", "blame", "round-robin", "none"]},
+            "reviewers": {"type": "array", "items": {"type": "string"}},
+            "assignees": {"type": "array", "items": {"type": "string"}},
+            "teams": {"type": "array", "items": {"type": "string"}},
+            "draft": {"type": "boolean"},
+            "labels": {"type": "array", "items": {"type": "string"}},
+            "wipLimit": {"type": "integer", "minimum": 1},
+            "mergePolicy": {"enum": ["human", "agent-after-approval"]},
+            "notify": {"type": "string"},
+            "rotation": {"type": "integer", "minimum": 0}
+          }
+        },
+        "budget": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "rounds": {"type": "integer", "minimum": 1},
+            "slicesPerRound": {"type": "integer", "minimum": 1},
+            "openPrs": {"type": "integer", "minimum": 1},
+            "minStep": {"type": "number"}
+          }
+        }
+      }
+    },
+    "stage": {"enum": ["aim", "sweep", "sift", "plot", "track"]},
+    "round": {"type": "integer", "minimum": 1},
+    "attempt": {"type": "integer", "minimum": 1},
+    "branch": {"type": "string"},
+    "skills": {"type": "array", "items": {"type": "string"}},
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "query", "matches", "why"],
+        "properties": {
+          "name": {"type": "string"},
+          "query": {"type": "string"},
+          "matches": {"type": "string"},
+          "why": {"type": "string"},
+          "exclude": {"type": "array", "items": {"type": "string"}},
+          "hits": {"type": "integer", "minimum": 0}
+        }
+      }
+    },
+    "exclude": {"type": "array", "items": {"type": "string"}},
+    "findings": {
+      "type": "array",
+      "items": {"$ref": "finding.schema.json"}
+    },
+    "slices": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["slug", "findings", "status"],
+        "properties": {
+          "slug": {"type": "string"},
+          "ip": {"type": "string"},
+          "tasks": {"type": "string"},
+          "findings": {"type": "array", "items": {"type": "string"}},
+          "status": {"enum": ["planned", "running", "merged", "abandoned"]},
+          "branch": {"type": "string"},
+          "pr": {"type": "string"},
+          "reviewer": {"type": "string"},
+          "assignee": {"type": "string"},
+          "routedBy": {"enum": ["fixed", "codeowners", "blame", "round-robin", "none"]},
+          "bucket": {
+            "enum": ["unrouted", "answered", "broken", "bot-pending", "merged", "closed", "waiting"]
+          },
+          "answered": {"type": "array", "items": {"type": "string"}},
+          "closedReason": {"type": "string"},
+          "round": {"type": "integer", "minimum": 1}
+        }
+      }
+    },
+    "rounds": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["round", "metricStart", "ev"],
+        "properties": {
+          "round": {"type": "integer", "minimum": 1},
+          "metricStart": {"type": "number"},
+          "metricEnd": {"type": "number"},
+          "found": {"type": "integer", "minimum": 0},
+          "kept": {"type": "integer", "minimum": 0},
+          "planned": {"type": "integer", "minimum": 0},
+          "fixed": {"type": "integer", "minimum": 0},
+          "dismissed": {"type": "integer", "minimum": 0},
+          "reopened": {"type": "integer", "minimum": 0},
+          "slices": {"type": "array", "items": {"type": "string"}},
+          "risks": {"type": "array", "items": {"type": "string"}},
+          "ev": {"type": "string"}
+        }
+      }
+    },
+    "artifacts": {"type": "array", "items": {"type": "string"}},
+    "heartbeat": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "lastTick": {"type": "string"},
+        "interval": {"type": "integer", "minimum": 1},
+        "ticks": {"type": "integer", "minimum": 0},
+        "hostFailures": {"type": "integer", "minimum": 0},
+        "overrides": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "reviewers": {"type": "array", "items": {"type": "string"}},
+            "assignee": {"type": "string"},
+            "wipLimit": {"type": "integer", "minimum": 1},
+            "rounds": {"type": "integer", "minimum": 1},
+            "until": {"type": "string"},
+            "tick": {"type": "integer", "minimum": 1}
+          }
+        }
+      }
+    },
+    "last": {
+      "anyOf": [
+        {"type": "null"},
+        {"$ref": "scan-result.schema.json"}
+      ]
+    },
+    "tried": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["stage", "attempt", "why", "status", "ev"],
+        "properties": {
+          "stage": {"enum": ["aim", "sweep", "sift", "plot", "track"]},
+          "attempt": {"type": "integer", "minimum": 1},
+          "why": {"type": "string"},
+          "status": {"enum": ["PASS", "FAIL", "BLOCKED", "PENDING"]},
+          "ev": {"type": "string"}
+        }
+      }
+    },
+    "next": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stage", "why", "human"],
+      "properties": {
+        "stage": {
+          "type": ["string", "null"],
+          "enum": ["aim", "sweep", "sift", "plot", "track", null]
+        },
+        "handoff": {
+          "type": ["string", "null"],
+          "enum": ["grow", "pick", null]
+        },
+        "why": {"type": "string"},
+        "human": {"type": "boolean"}
+      }
+    }
+  }
+}

package/skills/1-aim/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: 1-aim
+description: Turn a long-term codebase goal into an approved scan charter — measurable metric, captured baseline, dry-run detection rules, exclusions, validity rule, severity rubric, and slice policy. Use when asked to scan a codebase for an outcome ("improve build time", "find N+1 queries", "reduce maintenance overhead", "make us WCAG-compliant"), to set a long-term engineering goal, or to start or reshape a scan campaign; not for implementation, PR operations, or one-off searches.
+---
+
+# Aim — charter the goal
+
+Turn "make the codebase better at X" into a charter a fresh Sweep agent can execute
+without conversation history, and a metric that proves whether the campaign worked.
+
+Read the shared [`scan contract`](../../references/scan-contract.md),
+[`agentic map-reduce`](../../references/mapreduce.md),
+[`goal tracking`](../../references/goal-tracking.md),
+[`PR routing`](../../references/pr-routing.md), and the
+[`charter template`](references/charter.md) before acting.
+
+## Preconditions
+
+- A goal, outcome, or complaint plus a repository are available.
+- This invocation owns charter shaping only. It never edits product code. After
+  `PASS`, Sweep runs the scan.
+
+## Inputs
+
+- The requested outcome and any linked context
+- Existing charter, campaign state, and prior findings when the goal already exists
+- Repository instructions, code, tests, build scripts, CI config, and available skills
+
+## Procedure
+
+1. **Reconstruct.** Resolve the repository's scan conventions from its instructions and
+   nearby artifacts. If none exists, use `docs/scans/<goal-slug>/charter.md` for the
+   charter and `.terreno/scan/<goal-slug>.json` for campaign state, and record the new
+   convention. Read prior state and verify it against repository reality.
+2. **Read architecture docs.** Load the architecture, domain, and operator docs for the
+   areas the goal touches. They define what "correct" means before any rule is written.
+3. **Discover supporting skills.** Load repository/project skills matching the goal's
+   domains. Record them for downstream stages.
+4. **Make the goal measurable.** Derive the metric, its command, unit, direction,
+   target, horizon, and budget per `goal-tracking.md`. Run the metric command now and
+   quote its output as the baseline. If nothing measurable exists, grill for a proxy or
+   return `BLOCKED` naming the missing instrumentation — never a judgment-only metric.
+5. **Grill the human frontier.** Work one decision frontier at a time using selectable
+   options with a recommended default and the harness's structured question tool when it
+   has one. Settle: the outcome statement, the target and horizon, what is explicitly out
+   of scope, which trade-offs are unacceptable (for example "no public API breaks"), and
+   the budget. Vague or conflicting answers stay on the frontier.
+6. **Settle review routing.** Ask who reviews the campaign's PRs and record the `review`
+   block from `pr-routing.md`: mode, reviewer and assignee handles, teams, draft policy,
+   labels, the open-PR limit, the merge policy, and how to notify. Verify every handle is
+   requestable before writing it. "Whoever is free" is not an answer — resolve it to a
+   mode and a list, or to an explicit `mode: none`. This is the decision that makes an
+   unattended run safe to leave running.
+7. **Write detection rules.** For each rule record `name`, `query`, `matches`, `why`
+   (its link to the metric), and `exclude`. Dry-run every rule, record its hit count, and
+   remove or narrow rules that return nothing or flood. A rule that cannot plausibly move
+   the metric does not ship.
+8. **Define validity and severity.** State in one sentence what makes a finding valid,
+   and give the severity rubric concrete thresholds (`high` / `medium` / `low`) plus the
+   effort scale (`S` / `M` / `L`). Workers and Sift use these words verbatim.
+9. **Set the slice policy.** How findings become PR-sized units: maximum files and
+   findings per slice, what must never be mixed in one slice, and which findings require
+   their own slice because they are risky or reviewer-heavy.
+10. **Write and approve.** Produce the charter from the template, capture the baseline in
+   campaign state, and post the standalone approval brief: where the repository is today,
+   the goal and metric, the rules with their hit counts, the exclusions, the severity
+   rubric, the slice policy, and the decisions table pairing each settled decision with
+   the question that prompted it. Mark the charter approved only after human
+   confirmation. Update campaign state and emit the result collapsed per the scan
+   contract.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Useful skills typically cover build/test tooling,
+static analysis, performance measurement, accessibility, data access, or security,
+depending on the goal. Names are repository-defined; none is universally required.
+
+## Evidence produced
+
+- Charter path and campaign-state path
+- Metric definition plus the baseline command output, quoted
+- Detection rules with dry-run hit counts
+- Exclusions, validity rule, severity rubric, effort scale, slice policy
+- Review block: mode, verified reviewer/assignee handles, draft and label policy,
+  open-PR limit, merge policy
+- Decisions table with the question that prompted each decision
+- Selected supporting skills and the approved `PASS` result
+
+## Success conditions
+
+- The metric has a command that prints a number, and the baseline was measured here.
+- Every rule is dry-run-proven with a recorded hit count and a stated link to the metric.
+- A fresh Sweep invocation can shard and brief workers from the charter alone.
+- Every campaign PR has a named, verified destination, or the charter states `mode: none`.
+- A reviewer with no prior context can approve or push back from the brief alone.
+- Emit `PASS` with `next: sweep`.
+
+## Failure conditions
+
+An unmeasured baseline, an unproven rule, a missing validity rule, or a charter that
+contradicts itself emits `FAIL` with exact defects, `next: aim`, and a focused retry.
+Do not pass an unproven charter to Sweep.
+
+## Blocked conditions
+
+Unresolved goal or target decisions, a metric the repository cannot produce, a reviewer
+handle that cannot be verified, or missing access to build/measurement tooling emit
+`BLOCKED` with `next: null`, options, tradeoffs, and a recommended default.
+
+## Recommended next stage
+
+- `PASS` → Sweep
+- `FAIL` → Aim with defect evidence
+- `BLOCKED` → campaign loop routes the named human/external gate