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

package/skills/2-pick/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: 2-pick
+description: Implement one approved IP/task slice with behavior-focused TDD, then roast it and pick the next unblocked task until the approved list is done. Not for planning, skipping Roast, or PR submission.
+---
+
+# Pick — build
+
+Implement one approved slice carefully, then continue the pick-roast inner loop.
+Pick's internal reviewers ask whether engineering was disciplined; they do **not**
+replace Roast's independent proof. Pick never skips Roast.
+
+Read the shared [`lifecycle contract`](../../references/lifecycle-contract.md),
+[`documentation contract`](../../references/documentation-contract.md),
+[`PR deployments`](../../references/pr-deployments.md),
+[`pick-roast loop`](../../references/pick-roast-loop.md),
+[`testing plan`](../../references/testing-plan.md),
+[`user guide`](../../references/user-guide.md),
+[`testing guidance`](references/testing.md),
+[`mocking guidance`](references/mocking.md), and
+[`subagent briefing`](../../references/subagent-briefing.md).
+
+## Preconditions
+
+- An approved IP/task contract exists.
+- One current unblocked task/slice is identifiable.
+- Branch and prior execution state are available.
+
+## Inputs
+
+- Approved IP, task file, current task, and applicable acceptance criteria
+- Branch/current head and execution state
+- Selected/discoverable repository skills and instructions
+- Prior Pick attempts
+- Exact Roast failures or Taste/CI/review evidence when retrying
+- Known blockers and existing artifacts
+
+## Procedure
+
+1. **Reconstruct.** Verify the approved plan, current task, branch/head, prior result, and
+   already-verified behavior. Do not redo completed work. Resume the inner loop at the
+   next unblocked incomplete task, or at the same task when retrying a Roast `FAIL`.
+   When a harness pushed earlier slices automatically and product CI on that pushed
+   head reports a branch-caused failure, fixing it is the current task.
+   Do not start or continue another slice on a red head. Never wait on pending CI;
+   read the latest terminal results and keep building. Record flaky, infrastructure,
+   or other failures the branch did not cause in execution state for Taste; they do
+   not block the next slice. After Brew, CI reactions belong to Taste.
+2. **Read architecture docs.** Load the current architecture and domain docs for the
+   files/seams in this slice. Implement against that design; if the slice changes it,
+   update those docs in the same slice.
+3. **Discover supporting skills.** Inspect available project skills for this slice's
+   files; load applicable implementation, testing, documentation, safety, and runtime
+   guidance. Do not load the whole catalog.
+4. **Focus retries.** Convert prior failure evidence into a hypothesis and the smallest
+   safe change. Record attempted approaches; do not repeat one without new evidence.
+5. **Specify.** State one caller-visible behavior and the highest public seam that proves
+   it. List its edge cases before writing code: empty, missing, and error inputs;
+   loading and disabled states; boundaries; permissions; web versus native. Take them
+   from the acceptance criteria and repository test rules. Each one becomes a test in
+   this slice, so Roast proves them instead of discovering them. Read the IP's
+   `## E2E tests` rows whose `Written in` names this task, and the e2e guide at the
+   path the testing plan resolves. Each such row is a spec this slice writes. When a
+   row's path or layer no longer fits the code or the guide, edit that row in the IP,
+   add a one-line reason naming the row ID below the table (never a new column), and
+   update any `## Regression cases` `Automated by` cell that names the old path; never
+   skip a row silently. An IP that lacks the section follows the testing-plan legacy rule.
+6. **Encode.** Add one failing test and run the repository's closest test command. Confirm
+   it fails for the intended product reason. When the behavior has a planned row from
+   step 5, write that spec in this cycle at the row's path, following the e2e guide's
+   location, selector, and waiting rules for its layer. Run it when this stage can
+   reach that layer; otherwise record it `deferred` per the testing-plan deferral rule.
+7. **Fulfill.** Implement the minimum code that passes. Prefer real integrations and
+   narrow injected fakes at true external boundaries.
+8. **Clean the Kitchen.** Once the vertical slice is green, refactor names/structure,
+   remove debug/dead code, and rerun the affected repository-prescribed checks.
+9. **Review independently.** Build one task-scoped briefing (criteria, file list, this
+   slice's patch). In fresh contexts, give **that briefing** to:
+   - implementation/spec review
+   - test-quality review (public behavior, independent expected values, realistic
+     boundaries, no leaky/global test doubles)
+   Do not let each reviewer rediscover skills or diff the whole branch. Fix material
+   findings and rerun affected checks.
+10. **Check drift, docs, and runtime.** Compare the diff to the current task/IP. Update
+    architecture and public docs in this slice using the documentation contract. Run any
+    mandatory runtime/UI/safety verification declared by repository instructions or
+    supporting skills; for a user-facing change that is `verify-ui-changes` (own stack,
+    adversarial steps, the required checks, the Maestro flow for mobile-focused work or
+    direct simulator commands when the app has no Maestro, evidence outside the tree). Missing mandatory capability is `BLOCKED`, not skipped.
+    Missing docs for a user-visible or architectural change is `FAIL`. Write or edit
+    each user guide page whose `## User guide` row names this task, at the row's path,
+    in the user-guide page format, from the behavior this slice shipped; update the
+    guide index in the same slice. When a row's page path or change no longer fits,
+    edit that row in the IP with a one-line reason naming the row ID below the table;
+    never skip a guide row silently. Skip this when the repository opts out of the
+    user guide; an IP that lacks the section follows the user-guide legacy rule.
+11. **Record.** Record the completed task/slice in execution state with commands,
+    evidence, artifacts, docs files, attempts, each planned spec written (row ID
+    and path), and each user guide page written (row ID and path). Do not commit a separate task-file edit to mark progress; the
+    task-file mark rides in this slice's commit (step 13).
+12. **Prove this task.** Invoke Roast to prove this task only. Prefer a fresh context
+    and pass the same task-scoped briefing. Roast must not spawn two unconstrained
+    reviewers. Roast must return after classifying this task. Roast never invokes Pick.
+    Do not start the next task until Roast PASS.
+    Exactly one driver continues — that driver is this Pick.
+13. **Commit once.** After Roast `PASS`, make one behavior-scoped commit for the task:
+    code, tests, docs, the task-file mark, and any fixes Roast forced. Fold Roast-driven
+    fixes into the task's unpushed commit instead of adding "harden", "strengthen", or
+    "mark roasted" follow-ups. Do not push during Pick; Brew pushes. When the harness
+    pushes every commit automatically, commit only after Roast `PASS` for the same
+    reason. Follow the [commit and push rules](../../references/pick-roast-loop.md#commits-and-pushes).
+14. **Continue or stop.** After Roast `PASS`, if unblocked incomplete tasks remain,
+    reconstruct the next frontier task and repeat from Reconstruct so architecture docs
+    and supporting skills are rediscovered for that slice. If none remain, emit
+    `PASS` with `next: brew`. Roast `FAIL` retries this task from Focus retries. Emit
+    `FAIL` with `next: pick` only when this invocation must exit for a new hypothesis
+    the current context cannot safely continue. `BLOCKED` exits the loop. Pick owns
+    the inner loop. Do not rely on Roast to start the next Pick.
+
+Repeat Specify → Encode → Fulfill for learned behaviors inside this one slice. Do not
+batch all tests first. Do not expand into the next task until Roast PASS.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Project skills own exact commands, framework
+patterns, schema/data rules, test environment, UI verification, prompt governance,
+generated-code workflows, and repository gotchas.
+
+## Evidence produced
+
+- Files/behavior completed for each task this invocation finished
+- Red and green test evidence plus required lint/type/build/runtime results
+- Each `## E2E tests` row this task owns, with the spec path written or the edited row
+  and its reason
+- Each `## User guide` row this task owns, with the page written or the edited row and
+  its reason
+- Internal review results
+- Drift decision and artifact references
+- Attempted-approach summary (especially on retries)
+- Per-task Pick and Roast results in execution state
+- Terminal structured Pick or inner-loop result
+
+## Success conditions
+
+- Every in-scope task this invocation reached has Roast `PASS` on the recorded head.
+- Required repository checks/runtime gates pass for the current head.
+- No unresolved internal review findings or plan drift remain on completed tasks.
+- Every `## E2E tests` row a completed task owns has a spec at the row's path.
+- Every `## User guide` row a completed task owns has its page written, edited, or
+  retired at the row's path.
+- When unblocked tasks remain, continue the loop rather than exiting.
+- When none remain, emit `PASS` with `next: brew`.
+
+## Failure conditions
+
+Tests, internal reviews, or implementation checks that objectively fail emit `FAIL` with
+expected/actual/evidence and `next: pick` only with a focused next
+hypothesis; otherwise escalate under blocked conditions.
+
+## Blocked conditions
+
+An unresolved product/security/data/public-API decision, unsafe destructive change,
+missing required verifier, inaccessible dependency, or scope expansion emits `BLOCKED`
+with `next: null` and the exact decision/action required.
+
+## Recommended next stage
+
+- Inner-loop `PASS` (all in-scope tasks roasted) → `next: brew`
+- Current task built, Roast not yet run → `next: roast` (invoke Roast in-process)
+- `FAIL` → `next: pick` with preserved evidence and a new hypothesis
+- `BLOCKED` → outer loop routes the named gate

package/skills/2-pick/references/mocking.md

@@ -0,0 +1,34 @@
+# Mocking at boundaries
+
+Mock only a boundary where production leaves the system:
+
+- third-party APIs and provider SDKs
+- time, randomness, or operating-system I/O
+- network transport
+- file storage when a real temporary directory is unsuitable
+
+Use real internal collaborators and integrations when the repository's test environment
+supports them. Repository skills decide whether databases, stores, routers, or framework
+harnesses are real, isolated, or replaced at a boundary.
+
+## Prefer injected fakes
+
+Pass a narrow, domain-specific adapter into production code and provide a local fake in the test. Each adapter operation should have one typed purpose and one response shape.
+
+Keep fake state inside the test or a fresh harness factory. Assert observable results first; inspect fake state only when the boundary interaction itself is the contract.
+
+## Module mocks leak
+
+Some runners implement module mocks as process-wide or hoisted state. Registration may
+survive an individual test and make order significant. Consult repository test guidance.
+
+Design an injectable seam instead of using `mock.module`. When an unchangeable dynamic import makes a module mock unavoidable:
+
+1. isolate it in a dedicated file or test process
+2. document why dependency injection cannot represent the boundary
+3. run it through the repository's isolated-test mechanism
+4. never rely on restoring the module in `afterEach`
+
+## Scoped spies
+
+A test-local `spyOn` is acceptable for a true boundary or for forcing an otherwise unreachable framework error. Restore it in the same test lifecycle. A spy on an internal collaborator is not a substitute for testing public behavior.

package/skills/2-pick/references/testing.md

@@ -0,0 +1,43 @@
+# Behavior-first tests
+
+Tests are executable specifications at public seams. A refactor may replace the implementation without changing the test.
+
+## Choose the seam
+
+Before each slice, record the public seam in the task/working notes:
+
+- HTTP route for backend behavior
+- exported class/function for package behavior
+- rendered component interaction for UI behavior
+- injected adapter contract for external systems
+
+Prefer the highest existing seam that proves the behavior. Add a seam only when the production design needs one.
+
+## Red flags
+
+- asserting private methods, internal call order, or call counts
+- querying storage directly when the public interface can retrieve the result
+- recomputing the expected value with the same algorithm as production
+- writing all imagined tests before any implementation
+- testing a mock's behavior instead of the product behavior
+
+Expected values come from a literal worked example, the IP, or another independent source of truth.
+
+## Planned e2e specs
+
+The IP's `## E2E tests` table is the e2e plan, defined in the
+[`testing plan`](../../../references/testing-plan.md). Pick writes every row whose
+`Written in` names the current task, in that task, at the row's path. Follow the e2e
+guide the testing plan resolves for where specs live, how they find elements, and how
+they wait. A row whose path or layer no longer fits is edited in the IP with a one-line
+reason, never skipped. Running a layer the current stage cannot reach follows the
+testing-plan deferral rule.
+
+## Repository composition
+
+Load applicable repository testing skills before choosing commands, harnesses, fixtures,
+databases, assertion libraries, or runtime probes. In Terreno apps those are
+`terreno-backend-tests`, `terreno-frontend-tests`, and `terreno-mobile-tests`; run
+`terreno-test-setup` first when the layer has no test setup. Match established tests near the
+changed public seam. The lifecycle plugin does not prescribe a framework or package
+layout.

package/skills/3-roast/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: 3-roast
+description: Independently prove or disprove the current task against its IP criteria, then return. Do not pick or start the next task. Pick owns the inner loop. Use after Pick, preferably in a fresh context; not for fixing implementation code.
+---
+
+# Roast — prove
+
+Roast is the authoritative stage-level verifier for the **current task**. It does not
+continue the inner loop. Roast never invokes Pick. Pick owns the inner loop:
+
+```text
+requirement → verification method → evidence → PASS / FAIL / BLOCKED
+```
+
+Read the shared [`lifecycle contract`](../../references/lifecycle-contract.md),
+[`documentation contract`](../../references/documentation-contract.md),
+[`PR deployments`](../../references/pr-deployments.md),
+[`pick-roast loop`](../../references/pick-roast-loop.md),
+[`testing plan`](../../references/testing-plan.md),
+[`user guide`](../../references/user-guide.md), and
+[`subagent briefing`](../../references/subagent-briefing.md).
+
+## Preconditions
+
+- An approved IP/task contract and completed Pick result exist for the current task.
+- Current branch/head and diff are resolvable.
+- Run in a fresh context when the harness permits, with a task-scoped briefing.
+
+## Inputs
+
+- IP, task file, acceptance criteria, and verification requirements for the current task
+- Current branch/head, diff, and PR when present
+- Pick result, execution state, prior Roast attempts, and artifacts
+- Repository instructions and available project/verification skills
+
+## Procedure
+
+1. **Reconstruct independently.** Verify the head and this task's source artifacts from
+   the task-scoped briefing (criteria, file list, patch). Do not trust Pick's completion
+   claims as proof. Do not reload unnamed lifecycle references or the whole skill catalog.
+2. **Discover supporting skills.** Load only skills whose descriptions match this task's
+   files and criteria. Repository-mandatory capabilities are hard requirements.
+3. **Build the matrix.** Map every in-scope criterion **for the current task** to one or
+   more objective methods and the evidence required. Include promised regressions,
+   compatibility, and non-scope that this task could break. Add every IP
+   `## E2E tests` row whose `Written in` names this task, with the command that runs
+   its spec at the row's path, following the e2e guide the testing plan resolves.
+   A missing spec or a failing row is `FAIL` that names the row ID. A row whose layer
+   this invocation cannot reach is `deferred` per the testing-plan deferral rule, unless
+   repository policy makes that layer mandatory here, which is `BLOCKED`. Record a
+   deferred row's exact command in the Roast result and execution state, never in the
+   IP tables, and never count it as passed. Add every IP `## Regression cases` row this
+   task's criteria name, or whose `Automated by` names one of this task's rows or specs;
+   when no unblocked tasks remain, add every row no earlier Roast checked. Check each
+   against the testing-plan regression-step bar. A row without a concrete starting
+   state, a followable action, and an observable Expected is `FAIL` that names the row
+   ID and the missing part; Pick fixes it by rewriting that row in the IP in place.
+   A row an e2e guide layer could cover completely is also `FAIL` (testing-plan
+   "Keep regression minimal"); Pick moves it to `## E2E tests`. Roast never walks a row.
+   An IP that lacks either section follows the testing-plan legacy rule: warn once and
+   do not fail.
+4. **Inspect and execute.** Review this task's patch and run concrete checks in this
+   invocation: repository-prescribed tests, integration/system behavior, lint/type/build
+   checks, runtime/API/database probes, regression reproductions, or real UI interaction.
+   Do not spawn two unconstrained reviewers. Prefer named commands here over a second
+   general-purpose child that rediscovers the repo. Run the gate CI will run on these
+   files, not only this task's test file. Use the root `prepush` package script when
+   present, since it scopes itself to changed files. Otherwise run each touched
+   package's lint, typecheck, and the same test command CI runs, including coverage
+   thresholds. A test that passes alone but fails in the package suite is `FAIL`.
+5. **Exercise changed behavior.** For UI-facing work in **this task's file list**, spawn
+   at most one specialized UI/runtime verifier with the same briefing. Interact with the
+   actual changed workflow and capture required screenshots/video/logs. App launch alone
+   is not proof. The verifier follows `verify-ui-changes`: a stack it owns (ports already
+   taken by something else are a blocker, never a shortcut), adversarial steps, the
+   required checks on every run (right page, not blank, no error overlay, console
+   clean, DOM assertion, interaction proof, screenshot), the matching Maestro flow on the
+   simulator for mobile-focused work (direct simulator commands when the app has no
+   Maestro), and a report with a Result line. It is report-only and never edits the
+   tree; a missing `testID` or flow is `FAIL` for Pick. A flow it could not run is
+   `UNVERIFIED` with the blocker, which is `BLOCKED` here, not `PASS`; so is a required
+   leg, such as the simulator for mobile-focused work, that the report lists only as
+   not run or remaining risk. Skip
+   that child when this task has no UI/runtime files.
+6. **Prove docs.** Confirm architecture and public docs match the shipped behavior. A
+   criterion that is true in code but absent or wrong in docs is `FAIL`. Check each
+   `## User guide` page whose row names this task against the user-guide guide-entry bar
+   and the shipped screens: every label a step names exists, the steps reach the
+   outcome `## What it does` promises, and `audience` and `platforms` match who can
+   reach the feature. When step 5 drives the UI, walk the page's steps there. A missing
+   page, a page that misses the bar, or steps that do not match the shipped screens is
+   `FAIL` that names the row ID. Skip this when the repository opts out of the user
+   guide; an IP that lacks the section follows the user-guide legacy rule.
+7. **Classify each criterion.** Record `PASS`, `FAIL`, or `BLOCKED` with reproducible
+   evidence. Never pass a criterion because the code merely looks reasonable.
+8. **Do not fix.** Report implementation defects to Pick. Only correct verifier setup
+   owned by Roast; if that changes evidence materially, rerun the affected method.
+9. **Record.** Update execution state for this task's Roast result.
+10. **Return.** Follow the pick-roast loop. Do not start the next task until Roast PASS.
+    Roast never invokes Pick. Pick owns the inner loop. Exactly one driver continues —
+    that driver is always Pick. After recording this task, return the result; do not
+    reconstruct Pick, do not invoke Pick, and do not start the next task. `PASS` with
+    remaining unblocked tasks → emit `PASS` with `next: pick`. `PASS` with none remaining
+    → emit `PASS` with `next: brew`. `FAIL` → emit `FAIL` with `next: pick`. `BLOCKED`
+    → emit `BLOCKED` with `next: null`. When Pick invoked this Roast, returning to Pick
+    is enough; still do not invoke Pick.
+
+Do not treat a Roast of the last slice as proof of earlier unroasted tasks. Terminal
+inner-loop `PASS` requires every in-scope task to have Roast `PASS` on the recorded head.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Applicable skills may supply API/database test
+methods, UI/runtime verification, security/safety checks, build commands, or deployment
+probes. If repository policy makes one mandatory and it is unavailable, emit `BLOCKED`.
+
+## Evidence produced
+
+- Requirement-to-evidence matrix for the current task
+- Each `## E2E tests` row this task owns, with its spec path, command, and `PASS`,
+  `FAIL`, or `deferred`
+- Each `## Regression cases` row checked against the regression-step bar, and its result
+- Commands/probes/interactions and outcomes
+- Artifact/log/API response references
+- Exact expected vs actual behavior for every failure
+- Environment/access details for every blocker
+- Docs pages that match or fail against shipped behavior
+- Each `## User guide` row this task owns, with its page and result against the
+  guide-entry bar and the shipped screens
+- Per-task Roast results in execution state
+- Terminal structured Roast or inner-loop result
+
+## Success conditions
+
+- Every in-scope acceptance criterion for the current task has objective passing
+  evidence on the recorded head.
+- Required regression/runtime/UI checks pass.
+- Every `## E2E tests` row this task owns has a spec at its path that passed here, or
+  is recorded `deferred` with its exact command.
+- Every `## Regression cases` row Roast checked meets the regression-step bar.
+- Architecture and public docs match the shipped behavior.
+- Every `## User guide` page this task owns meets the guide-entry bar and matches the
+  shipped screens.
+- Remaining unblocked tasks emit `next: pick`. Roast never invokes Pick.
+- When none remain and every in-scope task has Roast `PASS`, emit `PASS` with
+  `next: brew`.
+
+## Failure conditions
+
+One or more criteria disproven by evidence emits `FAIL` with severity, expected, actual,
+and reproducible evidence. Set `next: pick`. A missing or failing `## E2E tests` row, or
+a `## Regression cases` row that misses the regression-step bar, could be fully
+automated, or repeats an existing case, is `FAIL` that names the row ID. So is a
+`## User guide` row whose page is missing, misses the guide-entry bar, or does not match
+the shipped screens.
+
+## Blocked conditions
+
+Unavailable required environment/capability/access, ambiguous criterion requiring a human
+decision, or external service failure that prevents proof emits `BLOCKED` with exact
+classification, `next: null`, and next action.
+
+## Recommended next stage
+
+- Inner-loop `PASS` (all in-scope tasks roasted) → `next: brew`
+- `PASS` with remaining unblocked tasks → `next: pick`
+- `FAIL` → `next: pick` with exact failure evidence and current head
+- `BLOCKED` → outer loop classifies retryable environment/external vs human gate

package/skills/4-brew/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: 4-brew
+description: "Move a Roast-verified implementation into GitHub review: final checks, branch hygiene, commit/push, PR setup, evidence attachment, confirm product CI on every discovered host (GitHub Actions, CircleCI, Buildkite, and similar), and wait in-process for async review bots (Bugbot, CodeQL) before exit."
+---
+
+# Brew — submit
+
+Move one verified implementation into review, wait for async review bots on that head,
+emit current PR/head state, and exit. The outer loop invokes Taste separately. Brew
+records bot outcomes but does not implement fixes.
+
+Read the shared [`lifecycle contract`](../../references/lifecycle-contract.md),
+[`documentation contract`](../../references/documentation-contract.md),
+[`PR deployments`](../../references/pr-deployments.md),
+[`product CI`](../../references/product-ci.md),
+[`async review bots`](../../references/async-review-bots.md),
+[`push ownership`](../../references/push-ownership.md),
+[`independent review procedure`](../../references/independent-review.md),
+[`testing plan`](../../references/testing-plan.md),
+[`user guide`](../../references/user-guide.md), and
+[`subagent briefing`](../../references/subagent-briefing.md). All GitHub text
+must follow the [`GitHub attention contract`](../../references/github-attention-contract.md).
+
+## Preconditions
+
+- Roast returned `PASS` for every in-scope task on the implementation being submitted.
+- Branch/diff and verification evidence are available.
+- No unresolved human gate remains.
+
+## Inputs
+
+- Approved IP/task and Roast result, including the IP's `## E2E tests` and
+  `## Regression cases` sections and Roast's per-row results
+- Current branch/head/diff and execution state
+- Verification artifacts/evidence
+- Repository instructions, available supporting skills, and PR template
+- Existing PR title/body when updating (human edits are authoritative)
+
+## Procedure
+
+1. **Reconstruct.** Confirm the branch tree corresponds to the Roast-passed
+   implementation. Behavioral changes after Roast return to Roast.
+2. **Discover supporting skills.** Load applicable submission, documentation, commit,
+   changelog, security, and repository verification skills.
+3. **Run final gates.** Resolve the e2e guide and `Regression suites` directory per the
+   testing plan, then gate the IP's two testing-plan sections before the other checks.
+   An IP that lacks either section follows the testing-plan legacy rule: warn once and
+   skip that section's gate.
+   - **Planned specs.** Confirm every `## E2E tests` row has a spec at its path that
+     passed: Roast recorded it `PASS` on the tree being submitted, or Brew reruns its
+     command green now. Only Brew accepts a `deferred` row, and only when its recorded
+     command passed locally in this invocation or in a terminal product-CI run on this
+     branch. A deferred row no local runner can reach, whose command a product-CI job
+     on a discovered host runs, does not block the push; step 10 settles it. A missing
+     spec, a failing row, or a red run of a deferred row's command is `FAIL` with
+     `next: pick` that names the row ID. A deferred row whose command neither a local
+     runner nor any CI job on a discovered host runs is `BLOCKED` naming the row and
+     its command.
+   - **Regression cases.** Skip this gate when `Regression suites` is `none` (the
+     testing-plan opt-out). Otherwise merge every `## Regression cases` row into
+     `<Regression suites>/<area>.md`, finding each file by the `Area:` line its
+     `Destination:` prefix names. Create a missing file from the testing-plan suite
+     format. Give each provisional `<AREA>-new-<n>` row the next free ID, set `Added`
+     to the IP slug, and replace an `E<n>` in `Automated by` with that row's spec path.
+     A row with a real ID edits that case in place and keeps its ID and `Added`. Leave
+     the IP tables unchanged; record each provisional-to-real ID mapping in execution
+     state and the Brew result. On a rerun, find rows already merged from this IP by
+     that mapping or, failing that, as rows this branch added to the suite file (diff
+     against the merge base) whose `Added` is the IP slug, and update them instead of
+     adding duplicates.
+   - **User guide.** Unless the repository opts out, confirm every `## User guide` row
+     has its page at the row's path in the user-guide page format (or, for `retire`,
+     that the page and its index entry are gone), that the guide index lists exactly
+     the pages on disk, and that each changed page sets `added` or `updated` to the IP
+     slug. A missing page or index mismatch is `FAIL` with `next: pick` that names the
+     row ID. An IP that lacks the section follows the user-guide legacy rule.
+
+   Then execute repository-required pre-submit checks, so suite checks see the merged
+   rows. When the root `package.json` defines a `prepush` script, run it in a fresh
+   subagent with no parent conversation before the first push. A red local gate is `FAIL`; do not push it. Confirm docs
+   follow the documentation contract, generated files are current, changelog/release
+   notes exist when required, and verification artifacts are complete. Ship without
+   matching docs is `FAIL`.
+4. **Review independently.** Review the branch on separate standards and IP/spec axes.
+   Pass one task-scoped briefing (file list plus patch) to each reviewer; do not let
+   each child rediscover the repo. Fix material findings outside Brew via Pick/Roast;
+   do not smuggle implementation work into submission.
+5. **Check hygiene.** Review status/diff; exclude loop-owned execution state, debug output,
+   secrets, credentials, customer data, and unrelated files.
+6. **Commit.** Follow repository commit and DCO/sign-off policy. Preserve the existing
+   prohibition on AI attribution. Use behavior-scoped commits, one per roasted task,
+   with no bookkeeping-only commits; do not rewrite pushed history unless explicitly
+   allowed. Suite rows merged in step 3 are a deliverable, not bookkeeping: commit
+   them in one commit per Brew invocation that changes them, named for the cases.
+7. **Push.** Push once with upstream. Resolve only mechanical conflicts needed to update the PR,
+   using repository conflict guidance and rerunning affected checks. A conflict requiring
+   a design/behavior choice is `BLOCKED`.
+8. **Create/update PR.** Apply the GitHub attention contract and any stricter repository
+   template. On create, set the title to `[ticket] Short feature title` (Linear
+   `TEAM-n` or GitHub `#n`; feature only, no `feat:` / `IP Approved` / `Task list`).
+   Initialize `Why` from the IP's original justification and `What changed` from a
+   brief overview of the approved IP and intended outcomes. Keep both stable unless
+   scope or facts change. Always include reproducible testing instructions in
+   `Verification`; update those instructions, evidence, and remaining risks as testing
+   changes without rewriting the body around the latest turn. List every regression
+   case ID the PR adds or changes in one `Verification` row that links its suite file,
+   under `⚠️ Not tested` unless a person walked every listed case on this branch. The
+   visible body uses only `Why`, `What changed`, and `Verification`, stays under 250
+   words, and puts optional detail plus the stage-result YAML in one expandable
+   Details block. Preserve human-edited title/body; make only accurate minimal edits.
+   Attach only decisive UI/runtime artifacts without sensitive data.
+9. **Do not announce.** Do not post a PR comment for creation, readiness, check results,
+   or evidence already present in the body. A top-level comment is allowed only for one
+   blocking human action that cannot live in an existing review thread.
+10. **Confirm product CI, then wait for review bots.** Resolve the PR number/URL and
+    pushed head SHA. Follow the product-CI procedure: discover every CI host on this
+    branch (GitHub Actions, CircleCI, Buildkite, and similar) and confirm each triggered
+    or documented a skip for this SHA on every discovered CI host. Then follow the
+    async-review-bots procedure: prefer provider CLI watch hooks or harness event
+    subscriptions; use bounded sleep/re-fetch only as a fallback. Wait until Bugbot,
+    CodeQL, and similar review bots on this head are terminal, never appeared after the
+    startup grace, or hit the 20-minute timeout. Do not exit while those bots are queued
+    or in progress. Do not wait for ordinary product CI to finish. The one exception
+    is a deferred `## E2E tests` row step 3 left for CI: wait for the job that runs
+    its command to finish on this head. Green accepts the row; red is `FAIL` with
+    `next: pick` naming the row ID.
+11. **Record and exit.** Update execution state and emit:
+    - review-bot timeout → `PENDING` with `next: taste` and `wait`
+    - required host untriggered after grace → `FAIL` with `next: brew`
+    - otherwise `PASS` with the PR/head, bot outcomes, and `next: taste`
+    Collapse per the lifecycle contract. Close the chat with PR deployment URLs when
+    the PR has them. Brew itself never executes Taste inline.
+12. **Hand off.** When an outer loop invoked Brew, exit; the outer loop runs Taste.
+    When a human invoked Brew directly and the result is `PASS` or `PENDING` with
+    `next: taste`, start the Taste skill as the next stage in standalone entry. Do
+    not end the session by telling the human to run Taste later. If the harness cannot
+    continue into Taste, escalate per
+    [`push ownership`](../../references/push-ownership.md#escalation) instead of ending
+    with a pushed PR that nothing watches.
+
+## Supporting skills
+
+Follow the shared discovery procedure. Project skills own exact lint/type/test commands,
+documentation generation, changelog rules, commit/DCO policy, PR templates, conflict
+handling, and mandatory evidence gates.
+
+## Evidence produced
+
+- Final checks and independent-review outcomes
+- Each `## E2E tests` row with its spec path and the passing run Brew accepted
+- Each regression case written to the suite, with its provisional and real ID and
+  suite file
+- Each `## User guide` row with its page path and change
+- Commit and pushed head SHA
+- PR URL/number and preserved template/body state
+- Attached artifact references and sensitive-data check
+- Discovered product-CI hosts and trigger/skip outcome per host
+- Async review-bot names, statuses, and posted findings
+- Updated execution state and structured Brew result
+
+## Success conditions
+
+- Verified implementation is committed/pushed and the PR accurately represents it.
+- Every `## E2E tests` row has a spec at its path with a passing run on this branch.
+- Every `## Regression cases` row is in its suite file under a real ID, and the PR
+  `Verification` section lists those IDs.
+- Every `## User guide` row's page is written, updated, or retired, and the guide index
+  matches the pages on disk.
+- Product CI on every discovered CI host is triggered (or documented skipped) for the
+  recorded current head.
+- Async review bots on this head are terminal or did not appear after the startup grace.
+- Emit `PASS` with `next: taste`, then exit.
+
+## Failure conditions
+
+Failed final checks, a missing or failing `## E2E tests` row, a missing `## User guide`
+page, including a red CI run of
+a deferred row (`next: pick`, naming the row ID), **Brew's own independent-review findings** (step 4), push errors,
+PR setup errors, or a required CI host still untriggered after grace emit `FAIL` with
+evidence and the smallest corrective stage/action:
+behavioral defects use `next: pick`, stale/missing proof uses `next: roast`,
+and submission-only retries use `next: brew`. Do not treat Bugbot, CodeQL, or similar
+async review-bot findings as Brew `FAIL`; record them and emit `PASS` with
+`next: taste`. Do not fix implementation inside Brew.
+
+## Blocked conditions
+
+Missing access, required human approval/decision, unsafe conflict, unavailable mandatory
+submission capability, a deferred `## E2E tests` row nothing can run, or sensitive-data
+risk emits `BLOCKED` with `next: null` and the exact action required.
+
+## Recommended next stage
+
+- `PASS` → outer loop invokes a fresh Taste
+- `PENDING` → outer loop waits, then invokes Taste
+- `FAIL` → stage named by evidence (`pick`, `roast`, or `brew`)
+- `BLOCKED` → outer loop routes the named gate
+
+For standalone compatibility, a human/runner may invoke Taste immediately after Brew
+returns. Brew itself never executes Taste and does not wait for product CI to finish, except
+for the CI job that settles a deferred `## E2E tests` row.