@terreno/agent-plugin 0.0.0-stage → 57.21.0

package/references/independent-review.md

@@ -0,0 +1,31 @@
+# Independent review
+
+Review a pinned branch diff without changing code. Keep two axes separate:
+
+1. **Repository standards:** applicable instructions/project skills, behavior,
+   architecture, security, maintainability, and test quality.
+2. **IP/spec:** missing, partial, incorrect, or unrequested behavior; promised tests/docs
+   absent; acceptance criteria not met.
+
+Resolve the fixed point. The **parent** builds one [task-scoped briefing](subagent-briefing.md):
+current task, criteria, file list, and the patch for those files only. Give each axis
+to a fresh reviewer **with that briefing** when the harness supports it. Reviewers must
+not rediscover skills, load unnamed lifecycle references, run a full-branch `git diff`,
+or spawn nested reviewers. Require the rule or quoted requirement plus concrete
+file/hunk evidence for every finding. Tool-enforced formatting is not a review finding.
+
+Rank severity only within an axis. A clean review has no unresolved material finding in
+either available axis. If no spec exists, state that; never invent one.
+
+Return:
+
+```markdown
+## Standards
+<findings or "No material findings">
+
+## Spec
+<findings, "No material findings", or "No spec available">
+
+Summary: <count> standards finding(s); <count> spec finding(s).
+```
+

package/references/lifecycle-contract.md

@@ -0,0 +1,211 @@
+# Lifecycle contract
+
+Grow, Pick, Roast, Brew, and Taste are **transitions**, not the orchestration loop.
+`terreno-pick-roast-loop`, `terreno-planning-loop`, and `terreno-taste-sweep` are
+invocable outer loops; they must not be recorded as `stage` values.
+
+| Owner | Responsibility |
+| --- | --- |
+| Outer loop | when to invoke, which agent, persistence, Taste `PENDING` reinvocation, retry, stop, escalation |
+| Pick–Roast inner loop | one task Pick, Roast that task, next task, until the list is done |
+| Lifecycle stage | how to perform one stage correctly and emit evidence |
+| Repository skills | repository commands, architecture, safety rules, and domain conventions |
+| Roast | whether the implementation satisfies the approved IP |
+| State + evidence | what a fresh invocation needs from previous attempts |
+
+Every stage reads durable inputs, performs one bounded transition, writes the execution
+state, emits one result document, and exits. Never rely on conversational memory.
+Pick is the exception that still stays bounded: it continues the
+[`pick-roast loop`](pick-roast-loop.md) in-process (one task, then Roast, then the next
+task) until the approved list is done, a `FAIL` that cannot continue, or `BLOCKED`.
+Roast never invokes Pick. Roast proves the current task and returns. Brew and Taste
+include one in-process wait for
+[`async review bots`](async-review-bots.md) (Bugbot, CodeQL, and similar) before that
+exit, so they can react to those results. Taste then waits in-process for product CI
+with [`product-ci.md`](product-ci.md) on every discovered host, using GitHub CLI or
+CircleCI CLI in a watch loop until jobs are terminal or the wait times out. Before any
+push, Taste fetches the latest `master` and merges it only when the PR conflicts, a failure
+traces to base drift, or the branch is otherwise merge-ready, then records last-run failed
+tests from the CI snapshot and re-verifies them locally, then spawns a fresh subagent
+with no parent conversation. The subagent runs the root package's `prepush` script when
+present; that script is the repository-owned gate for lint, typecheck, static analysis,
+tests, and other local policy. When it is absent, Taste falls back to lint, typecheck,
+and locally affected tests in each affected package. Taste then pushes and watches
+product CI. Hosts and tokens are on the product-CI page.
+
+Every stage that pushes follows push ownership (`push-ownership.md`, bundled with
+Brew, Taste, and the outer loops): the PR stays
+owned until CI is green on every host and every review-bot comment is addressed, or
+until three fix rounds fail and the human is told. A pushed PR is never left red or
+unwatched.
+
+## Discover supporting skills
+
+At the start of every stage:
+
+1. Inspect skills exposed by the harness and repository (for example skill catalogs and
+   repository skill directories).
+2. Match their descriptions to the **files and criteria in this slice**, not the whole
+   catalog.
+3. Load applicable `SKILL.md` files before acting. Record their names in `skills`.
+   Do not load sibling lifecycle references this stage did not name.
+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.
+
+Do not assume any particular supporting skill name exists. Lifecycle skills describe
+portable method; repository skills describe the repository.
+
+When spawning a fresh subagent, pass a [task-scoped briefing](subagent-briefing.md)
+instead of asking the child to rediscover the repository.
+
+## Documentation
+
+Every stage follows the [`documentation contract`](documentation-contract.md):
+
+- Read architecture and domain docs before acting.
+- Treat docs as the architecture source; code implements them.
+- Update docs in the same slice as the behavior.
+- Write with standard headings, tables, and one minimal example.
+- Missing docs for a user-visible or architectural change is `FAIL`.
+
+## Stage result
+
+Machine-readable result is for the next skill and the outer loop. It is **not** the
+human-facing answer.
+
+Lead the chat with `status`, `next`, and `action` in one or two lines. Put the YAML
+only in a collapsed details block. On a PR, put it only in the Details toggle from the
+[`GitHub attention contract`](github-attention-contract.md). Never paste the YAML in
+visible PR body, comments, or the main chat.
+
+When a PR has GitHub Deployments, close every wait-for-human or done message with those
+demo URLs as the **last visible section**, per [`pr-deployments.md`](pr-deployments.md).
+Omit the section when no `environmentUrl` exists. Do not comment the links on the PR.
+
+The schema is [`stage-result.schema.json`](stage-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>Stage result</summary>
+</details>
+```
+
+Example payload:
+
+```yaml
+v: 2
+stage: roast
+status: FAIL
+ip: example-feature
+task: T2
+attempt: 2
+sha: abc123
+checks:
+  - name: cursor-pagination
+    status: FAIL
+    ev: "bun test: expected 2 records, received 3"
+fail:
+  - need: Cursor pagination is backwards compatible
+    want: No duplicate records across pages
+    got: Final page repeats one record
+    ev: test output
+next: pick
+action: Fix duplicate cursor boundary and rerun the failing test
+```
+
+Evidence in `ev` must be reproducible: command plus outcome, artifact path, API
+response, log location, or PR/check URL. Never persist chain-of-thought or conversational
+transcripts.
+
+| Key | Meaning |
+| --- | --- |
+| `sha` | current head |
+| `skills` | supporting skills loaded |
+| `done` | completed work |
+| `fail` | `need` / `want` / `got` / `ev`; optional `sev` |
+| `block` | `kind` / `why` / optional `ev` |
+| `ask` | human questions: `q` / `rec` / optional `opts` |
+| `next` | recommended next stage or `null` |
+| `action` | concrete next action |
+| `wait` | seconds until the next Taste check (`PENDING` after bot timeout, product-CI wait timeout, or a second post-fix push) |
+
+## Execution state
+
+The IP and task file remain authoritative for design and scope. Execution state is a
+small loop-owned handoff, not another plan.
+
+The focused Pick–Roast outer loop may add the schema-defined `ledger` array. Each entry
+records one Pick or Roast task attempt, head, status, summary/evidence, and optional
+files, checks, artifacts, docs, hypothesis, and risks. It is the source for the single
+completion or human-gate report.
+
+Use an existing repository convention when present. Otherwise use
+`.terreno/pipeline/<ip-or-task-slug>.json`, conforming to
+[`execution-state.schema.json`](execution-state.schema.json). The outer loop must preserve
+or transport this file between fresh invocations. Do not commit it unless the repository
+explicitly tracks execution state; Brew must exclude loop-owned state from PR commits.
+
+Each invocation:
+
+1. Read state and verify its branch/sha/PR 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.
+
+When `terreno-pick-roast-loop` is driving, append the schema-defined `ledger` entry
+between steps 5 and 6.
+
+These six state operations are mandatory whenever a stage says “update execution state.”
+Every result also includes a concrete `action`, even when `next` is `null`. For
+`BLOCKED`, set `next.human: true` only when the blocker is a human decision/policy gate;
+access/environment/external blockers remain false unless human action is genuinely
+required.
+
+If no writable artifact exists, still emit the result. If the outer loop cannot preserve
+that result for the next fresh invocation, return `BLOCKED` and name the missing state
+transport.
+
+## Failures, blockers, and retries
+
+- `FAIL`: objective engineering or verification failure. Preserve exact evidence and
+  recommend the smallest evidence-driven retry.
+- `BLOCKED`: no safe engineering action exists now. Classify `human`, `environment`,
+  `access`, or `external`; include the exact action or decision required.
+- `PENDING`: changing external state is not terminal (primarily Taste). Include `wait`;
+  the **outer loop** waits and invokes again. With no outer loop (a human invoked
+  Taste or Brew directly), Taste's standalone entry waits and reacts again itself.
+  `PENDING` is never the final answer to a human. Use `PENDING` for review-bot timeout,
+  product-CI wait-loop timeout (jobs still pending on GitHub Actions, CircleCI,
+  Buildkite, and similar), and after Taste's second post-fix push. Do not emit
+  `PENDING` while Bugbot, CodeQL, or similar review bots are still queued or in
+  progress; wait per the async-review-bots procedure first. Do not emit `PENDING` for
+  unfinished product CI until Taste has run the product-CI wait loop to completion or
+  timeout, preferring `gh` / `circleci` watch hooks.
+- `PASS`: this stage's success conditions are proven for the recorded head.
+
+Human gates include unresolved product semantics, architecture/security/data ownership,
+destructive or irreversible operations, permissions, public compatibility, significant
+scope growth, and policy-required approval. Include options, tradeoffs, evidence, and a
+recommended default when appropriate.
+
+An outer loop requesting human input must first summarize the overall plan state,
+completed work, failed/recovered attempts, decisive evidence, options and impact, and a
+recommended default. It ends with one exact question, then the Demo section when the PR
+has deployment URLs. Objective engineering failures are not human gates while a concrete
+safe action remains.
+
+A PR that is still red after three fix rounds is `BLOCKED` and escalated per push
+ownership (`push-ownership.md`, Escalation). No stage or loop ends silently on a red PR.
+
+Bounded engineering retries must be hypothesis-driven. Taste waits in-process for
+async review bots and for product CI (bounded watch loop). The outer loop reinvokes
+Taste after `PENDING`. Brew waits in-process only for async review bots.

package/references/loop-engineering.md

@@ -0,0 +1,125 @@
+# Loop engineering
+
+This file describes orchestration for a runner, human, or automation. The lifecycle
+skills do not implement Grow → Brew → Taste. Pick and Roast **do** implement the
+[`pick-roast inner loop`](pick-roast-loop.md) in-process.
+
+```text
+Grow PASS → Pick/Roast inner loop → Brew PASS → Taste
+              Pick one task → Roast that task
+              Roast FAIL → Pick (same task, exact evidence)
+              Roast PASS + remaining tasks → Pick (next frontier task)
+              Roast PASS + no remaining tasks → Brew
+Brew PENDING (review-bot timeout) ───→ outer loop waits → Taste
+Taste PENDING (CI wait timeout / bot timeout / second push) ───→ outer loop waits → fresh Taste
+Taste waits in-process for Bugbot/CodeQL and product CI (`gh` / `circleci`) ───→ same invocation reacts
+Taste PASS ────────────→ merge-ready
+Any BLOCKED ───────────→ human/external gate
+```
+
+The loop persists the execution state, starts a fresh agent for Grow, for the first
+Pick or Roast entry, and for Brew/Taste, honors `next`, waits on `PENDING` (`wait`
+seconds), and stops on `PASS` or `BLOCKED` according to policy. It must not turn a human
+decision into retries. It must not reinvoke Pick or Roast between tasks while the inner
+loop can continue. Stage YAML is loop/skill data; keep it collapsed for humans. Brew and
+Taste themselves wait until async review bots on the current head have reported,
+preferring provider CLI watch hooks or harness subscriptions. Taste then waits in a loop
+for product CI using GitHub CLI or CircleCI CLI until jobs are terminal or the wait
+times out. The loop does not need to reinvoke for those in-process waits.
+
+Three invocable outer-loop skills ship beside the five stages. They are not stages:
+
+| Skill | Loop |
+| --- | --- |
+| `terreno-pick-roast-loop` | Drive an approved plan through recoverable Pick/Roast failures, accumulate one run ledger, and stop only at completion or a genuine human gate. |
+| `terreno-planning-loop` | Walk Grow/Pick/Brew/Taste. Default Grow once, then Pick once (Pick owns the pick-roast inner loop). Pass `phases=` (`grow`, `pick`, `roast`, `brew`, `taste`) to restrict. |
+| `terreno-taste-sweep` | Find the author's open non-draft PRs that are conflicting or failing, isolate each one, and reinvoke Taste until mergeable or blocked. |
+
+## Invocation packet
+
+Give each fresh agent a [task-scoped briefing](subagent-briefing.md):
+
+1. lifecycle skill path/name
+2. IP and task path
+3. execution-state artifact
+4. branch and current PR (if any)
+5. previous stage result and referenced evidence
+6. pointer to repository architecture docs for the affected area
+7. this slice's criteria, file list, and patch — not a request to rediscover the catalog
+
+The stage discovers repository skills itself, matching this slice's files. The loop may
+suggest known skills but must not replace stage-level discovery. Roast and its children
+must not spawn two unconstrained reviewers.
+
+Invoking Pick is enough to run the inner loop until the approved task list is done.
+Invoking Roast proves the current task only and emits `next: pick` or `next: brew`.
+Roast never invokes Pick. Do not start the next task until Roast PASS. Exactly one driver continues after each current-task Roast: Pick owns the inner loop.
+
+`terreno-pick-roast-loop` adds recovery around those bounded invocations. It reinvokes
+the named stage when a concrete engineering action remains, but it does not repeat a
+failed approach without a new hypothesis. It keeps cycle details in execution state and
+presents one complete report at the end. At a human gate, the report must explain the
+overall goal/state, completed work, decisive evidence, options and impact, recommendation,
+then one exact question, then PR deployment URLs when a PR has them. It never invokes Grow, Brew, Taste, or product CI.
+
+## Feature profile (formerly Grind)
+
+For one bounded feature, the loop may use a compact approved task file instead of a full
+IP when repository policy permits:
+
+1. Invoke Grow to research/grill and write the compact task contract.
+2. Invoke Pick once. It implements one unblocked task, roasts it, then picks the next
+   until the list is done. Do not dispatch parallel Picks and roast once at the end.
+3. When the inner loop emits `PASS` with `next: brew`, invoke Brew, then fresh Taste
+   iterations.
+
+The inner loop, not a long-lived parent agent outside Pick/Roast, marks tasks, persists
+per-task results in execution state, and continues to the next frontier task.
+
+## Backend/API scenario
+
+- Grow shapes the model/API contract, acceptance criteria, and discoverable supporting
+  skills.
+- Pick loads applicable API, schema, and test-environment skills and implements with TDD
+  one task at a time.
+- Roast independently exercises that task's routes, integration/database behavior, and
+  regressions before the next task starts.
+- Brew submits only after every in-scope task has Roast `PASS`.
+- Taste reacts to the current CI/review state until the loop receives `PASS`. It waits
+until Bugbot, CodeQL, and similar review bots have reported, then waits in a loop for
+product CI with `gh` or `circleci`, then acts. Before any push it fetches latest
+`master` (merging it only when needed), then spawns a fresh subagent with no parent conversation. When the repository
+root defines a `prepush` package script, the subagent runs that authoritative local gate.
+Otherwise it falls back to lint, typecheck, and locally affected tests in affected
+packages. Before that gate, Taste records last-run failed tests from the CI snapshot and
+re-verifies them locally. Taste then pushes and watches CI.
+
+## UI scenario
+
+- Grow shapes UX, API, state, and observable verification criteria.
+- Pick loads applicable UI conventions and implements/tests one task's behavior.
+- Roast loads the repository's UI verification capability, launches the real app,
+  exercises the changed workflow, and records media evidence before the next task.
+- Brew attaches evidence after the inner loop completes.
+- A Taste fix that changes UI reruns the required UI verification, pushes, and returns
+  `PENDING` for the new head.
+
+## CI/review scenario
+
+1. Brew pushes the PR, uses native watch/subscription hooks where available until
+   Bugbot/CodeQL (if running) are terminal, records outcomes, and exits with
+   `next: taste` without implementing fixes.
+2. Taste waits if those bots are still running, then runs the product-CI wait loop
+   (`gh pr checks --watch` / `gh run watch` / `circleci run watch`) until jobs on SHA A
+   are terminal. It sees a branch-caused CI failure, fixes it, fetches latest
+   `master` (merging it only when needed), records last-run failed tests and re-verifies them locally, then runs the
+   root `prepush` script (or fallback lint, typecheck, and affected
+   tests) in a fresh subagent with no parent conversation, pushes SHA B, then watches
+   review bots and product CI on B, and acts once on those results. A further push emits
+   `PENDING` and exits.
+3. The outer loop uses the same native watch hook only when Taste timed out or pushed a
+   second fix (falling back to the requested timer), then invokes fresh Taste. It sees
+   green jobs plus an actionable human review comment, fixes it, waits for review bots
+   and product CI on the new head, and emits `PENDING` or `PASS`.
+4. When all jobs on every discovered host are terminal/pass, no conflicts, and no
+   actionable comments remain, Taste emits `PASS`.

package/references/pick-roast-loop.md

@@ -0,0 +1,112 @@
+# Pick–Roast inner loop
+
+Pick and Roast run as one automated inner loop until the approved task list is done.
+The outer loop still owns Grow, Brew, Taste, persistence, Taste `PENDING` reinvocation,
+and escalation. Taste waits in-process for product CI on the current head. The outer
+loop does not wait between Pick and Roast, and it does not wait for a human to reinvoke
+the next frontier task.
+
+```text
+Grow PASS
+    → Pick (one unblocked task)
+    → Roast (that task only)
+         FAIL → Pick (same task, exact evidence)
+         PASS + remaining unblocked tasks → Pick (next frontier task)
+         PASS + no remaining unblocked tasks → Brew
+Any BLOCKED → emit and exit to the named gate
+```
+
+## Bounds
+
+The inner loop is bounded by the approved task graph, not by CI or wall-clock:
+
+- One Pick implements exactly one current unblocked task.
+- Roast proves that task before any later task starts.
+- Do not start the next task until Roast PASS.
+- Roast FAIL retries the same task with a new hypothesis; do not repeat a failed
+  approach without new evidence.
+- Exhausted retries, human/environment/access/external gates, or missing mandatory
+  verifiers emit `FAIL` or `BLOCKED` and **exit**. The inner loop does not invent scope.
+- Terminal inner-loop `PASS` requires every in-scope task to have a Roast `PASS` on the
+  recorded head. Only then is `next: brew`.
+
+Do not pick every task first and roast once at the end. Do not roast the whole IP after
+the first Pick. Do not run independent frontier tasks in parallel inside this loop.
+
+## Who executes whom
+
+Invoking **Pick** enters this loop. Invoking **Roast** proves the current task only.
+Roast never invokes Pick. Pick owns the inner loop. Exactly one driver continues after
+each current-task Roast — that driver is always Pick. Do not let a parent Pick and a
+Roast subagent both start the next task. A fresh Roast subagent has no conversational
+"who invoked me" signal; prove-only Roast is the durable driver.
+
+- After Pick records a completed slice, **invoke Roast to prove that task only**. Prefer
+  a fresh context or subagent when the harness allows. Pass a
+  [task-scoped briefing](subagent-briefing.md): this task's criteria, file list, and
+  patch. Do not ask Roast or its children to rediscover the skill catalog or diff the
+  whole branch. Roast must not spawn two unconstrained reviewers. If a fresh context is
+  unavailable, execute Roast from durable artifacts only and ignore Pick's completion
+  claims.
+- Roast proves, records, and **returns**. It does not reconstruct Pick, does not invoke
+  Pick, and does not start the next task. `PASS` with remaining tasks emits `next: pick`.
+  `PASS` with none remaining emits `next: brew`. `FAIL` emits `next: pick`.
+- When Pick invoked Roast, returning to Pick is enough. Pick then continues: Reconstruct
+  the next frontier task, including architecture docs and supporting skills for that
+  slice, or emit `next: brew` when none remain.
+- When Roast is the entry skill, emit `next: pick` or `next: brew`. The caller (human or
+  outer loop) runs Pick. Roast still never invokes Pick.
+- After Roast `FAIL`, return evidence to the parent Pick, or emit `next: pick` with the
+  exact `need` / `want` / `got` / `ev` evidence when Roast is the entry.
+- Pick never skips Roast. Roast never implements the next slice itself.
+
+Each cycle writes execution state (`task`, `attempt`, `last`, `tried`, `next`) before
+continuing. The invocation emits one terminal stage result: the last cycle that stops
+the loop. Intermediate cycle results live in execution state, not as extra human-facing
+YAML dumps.
+
+## Commits and pushes
+
+Every commit a harness pushes starts a full CI run, so commits track proven behavior,
+not loop bookkeeping:
+
+- One behavior-scoped commit per task, made after that task's Roast `PASS`. It carries
+  the code, tests, docs, and task-file mark together.
+- Roast-driven fixes amend or squash into the task's unpushed commit. Do not add
+  "harden", "strengthen", "prove", or "mark roasted" follow-up commits.
+- Progress lives in execution state (`.terreno/pipeline/<slug>.json`), which is
+  git-ignored. Do not commit task-file checkbox edits on their own.
+- Pick and Roast do not push. Brew pushes once after the whole list has Roast `PASS`.
+  Taste pushes at most once per reaction. Whoever pushes follows push ownership
+  (`push-ownership.md`, bundled with Brew and Taste).
+- Do not start the next task while product CI on the pushed head reports a
+  branch-caused failure. Fix it first. Never wait on pending CI, and record
+  failures the branch did not cause for Taste instead of blocking on them.
+
+## Independence
+
+Roast remains the authoritative verifier. Pick's internal reviews are not proof. Roast
+reconstructs the head and artifacts independently, maps in-scope criteria for **the
+current task**, and classifies each with evidence. It does not fix implementation
+defects.
+
+When Roast runs in-process after Pick, it still must not trust conversational memory of
+the implementation. Fresh context is preferred, not optional when the harness can spawn
+one.
+
+## Entry and exit
+
+| Entry | Behavior |
+| --- | --- |
+| Grow `PASS` / human invokes Pick | Start at the next unblocked incomplete task |
+| Human invokes Roast after a Pick cycle | Prove the current task, emit `next: pick` or `next: brew`, return |
+| Roast `FAIL` from a prior invocation | Pick retries that task, then Roast, then continue |
+
+| Stop | `next` |
+| --- | --- |
+| All in-scope tasks have Roast `PASS` | `brew` |
+| Pick or Roast objective failure after focused retry | `pick` or `roast` as named by evidence, and **exit** when the invocation cannot continue safely |
+| Unresolved gate | `null` (`BLOCKED`) |
+
+Brew preconditions require this terminal Roast `PASS` across the in-scope task list, not
+a Roast of only the last slice while earlier slices are unproven.

package/references/pr-deployments.md

@@ -0,0 +1,69 @@
+# PR deployments in chat
+
+When a pull request has GitHub Deployments attached, the human must see those demo
+URLs without hunting through CI, comments, or the middle of a long reply.
+
+This is **chat-only**. Do not post the links as a PR comment. Do not wait for
+deployments to become ready just to print them. Print what is attached now.
+
+## When to print
+
+Close with the Demo section on every **user-visible** message that either:
+
+- waits for human input (grilling round, confirm-and-write, `BLOCKED` human gate,
+  `ask`, or any other stop that needs a reply), or
+- ends the invocation (`PASS`, `FAIL`, `BLOCKED`, `PENDING`, completion report)
+
+Skip the section when there is no PR, GitHub access cannot list deployments, or the
+PR/head has no `environmentUrl` values. Do not write "no deployments."
+
+Do not print this on intermediate tool-only work. Print it on the message the human
+reads.
+
+## Where it goes
+
+Lead with `status` / `next` / `action` (or the grilling/gate question). Put stage YAML
+in a collapsed Details block. **The last visible section is Demo** whenever URLs exist.
+
+A human-gate question still appears in the body. Demo follows it so the links are the
+last thing on screen.
+
+## Discover
+
+1. Resolve the current PR number and head SHA (`gh pr view --json number,url,headRefOid`
+   on this branch, or the PR already in execution state).
+2. List GitHub Deployments for that PR/head. Prefer GraphQL on the pull request:
+
+   ```bash
+   gh api graphql -F owner=<owner> -F name=<repo> -F number=<pr> -f query='
+   query($owner:String!,$name:String!,$number:Int!){
+     repository(owner:$owner,name:$name){
+       pullRequest(number:$number){
+         deployments(last:20){
+           nodes{
+             environment
+             latestStatus{state environmentUrl createdAt}
+           }
+         }
+       }
+     }
+   }'
+   ```
+
+   REST fallback: `gh api "repos/<owner>/<repo>/deployments?sha=<headSha>&per_page=20"`,
+   then each deployment's statuses for `environment_url`.
+3. Keep rows whose latest status has a non-empty `environmentUrl` (success, in-progress,
+   or queued with a preview URL already assigned). Skip statuses that only have a log URL.
+4. Deduplicate by URL. For the same environment name, keep the newest `createdAt`.
+5. Do not invent URLs from job names. Do not scrape PR comments for previews.
+
+## How to print
+
+```markdown
+## Demo
+
+- **<environment>**: <environmentUrl>
+```
+
+Use the deployment environment name as the label. One bullet per unique URL. No extra
+prose. No CI log links in this section.