@rallycry/conveyor-skills 1.0.10 → 1.0.12

package/README.md

@@ -17,6 +17,7 @@ normal dependency bumps: no git submodules, no manual syncing.
 | `conveyor-start` | `/conveyor-start <card>` | Hand a planned card to a cloud pod, confirm the environment came up, report where to watch it (local surface only) |
 | `conveyor-build` | `/conveyor-build <card>` | Execute a planned card to a PR — one task or a whole feature-branch pack |
 | `conveyor-review` | `/conveyor-review <card>` | Review the PR against its plan and render one verdict, with risk |
+| `conveyor-release-review` | `/conveyor-release-review [release]` | Audit everything in a pending release, keep only findings backed by evidence that survive an adversarial pass, and file them by priority as a blocker pack and a suggestions pack (local surface only) |
 | `conveyor-consensus` | `/conveyor-consensus <question>` | Sweep the sources a project actually has, count what happened, score the proposals against those counts, and attach an HTML verdict to the card |
 | `conveyor-local-loop` | `/loop /conveyor-local-loop` | Run this machine as a serial local agent: claim Open cards and packs, build to PR, repeat |
 | `conveyor-prune` | `/conveyor-prune [project\|all]` | Sweep every Planning/Open card, give each one disposition (cancel, park on hold, merge into a pack, keep), apply only the confirmed rows (local surface only) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-skills",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Shared Claude Code skills for Conveyor consumer repos, linked into .claude/skills via the conveyor-skills CLI",
   "keywords": [
     "claude",

package/skills/conveyor-build/SKILL.md

@@ -204,7 +204,14 @@ runner: the pod can sleep mid-run and nothing will wake you.
 **A UI-visible change needs visual proof before the PR**, in both environments:
 capture a screenshot (static) or a short recording (interaction) with the host
 repo's own tooling and attach it with `mcp__conveyor__upload_attachment`, then
-embed the returned URL in the PR body. A UI PR without it is incomplete.
+embed the returned URL in the PR body. A UI PR without it is incomplete. Pass
+`showcase: true` for the capture that shows the finished result (the after
+shot, the final recording); leave it off for before shots and scoping captures.
+Showcase files post to chat, render first on the card, and land in the PR body
+under `## Showcase`. A re-capture of something already on the card (a new cut
+of the same recording) passes `supersedes: "<old fileId>"` from
+`list_task_files`: the new file takes the old one's star and tags, and the old
+one collapses under it as history instead of showing twice.
 
 **Manual tests are for human eyes, and few.** Before the PR, record with
 `mcp__conveyor__set_manual_tests` only what a person must see in the running
@@ -262,10 +269,12 @@ Instead: post the answer, config, or findings with
 `mcp__conveyor__upload_attachment` (any file type, up to 25MB), and complete
 the card directly with `force_update_task_status("Complete")` — there is no PR
 or review step for a no-code task. Never publish a deliverable as an off-card
-link; the card is where it belongs. When a revision supersedes an earlier
-upload, remove the old copy with `mcp__conveyor__delete_attachment` (permanent,
-`fileId` from `list_task_files`) so the Files list shows one current version
-of each deliverable.
+link; the card is where it belongs. When a revision replaces an earlier
+upload, upload it with `supersedes: "<old fileId>"` (the id from
+`list_task_files`) so the card shows one current version of each deliverable
+with the history collapsed under it. Reach for
+`mcp__conveyor__delete_attachment` (permanent) only for a copy that should not
+survive at all.
 
 When unsure, check the diff: a real diff means open a PR, no diff means finish
 in chat and mark it Complete.

package/skills/conveyor-release-review/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: conveyor-release-review
+description: Audit a pending release before it ships — evaluate every change in it, back each finding with evidence (production or dev logs, a local reproduction, or a deterministic proof), grade findings by the project's own Priority levels, strike what an adversarial pass finds over-built, and file the survivors as two packs, release blockers and release suggestions. Use when the user says "/conveyor-release-review [release]", "review this release", "is this release safe to ship", "audit what's going out", or asks for a pre-release check of the dev-to-main gap. Local/MCP surface only; inside a pod the skill says so instead of failing. Never fixes, never starts a build, never merges.
+---
+
+# Conveyor Release Review
+
+Every change in a release already passed its own review. This audit exists for
+what that process cannot see: changes that are fine alone and break **in
+combination**, risk that only exists at release scale, and what happens at
+deploy time.
+
+It has two ways to fail and treats them as equal. Missing a real break ships
+it. Manufacturing work from speculation buries the real break under cards
+nobody will build, and teaches the team to ignore the next review. So nothing
+here is a finding until evidence says so, and nothing is filed until a
+reviewer whose job is to strike it has tried.
+
+## Goal and finish line
+
+**Goal:** every change in the release evaluated; every surviving finding
+carrying its evidence and one of the project's Priority levels, filed in at
+most two packs.
+
+**Finish line:** the report — verdict on its first line — posted to the
+conversation, and to the release card's chat when a release card exists.
+
+**A turn may end only when:** (a) the finish line is true, or (b) an
+`AskUserQuestion` is pending because the release scope is genuinely ambiguous.
+Anything else — a ledger with blank rows, findings listed but not filed, packs
+created with no report — is a stalled run, not a paused one.
+
+**Runtime:** *Codex CLI* — before step 0, create a thread goal with your goal
+tool: "Post a release verdict for <release> with every change evaluated and
+every surviving finding filed." Mark it complete only when the finish line is
+true, never because the budget is low. *Claude Code* — there is no goal tool;
+the finish line above is the loop.
+
+> **Environment — this skill does not apply inside a pod.** Filing the packs
+> needs `create_task`, `manage_priorities`, `add_dependency` against another
+> card, and `update_task` with `priorityValue` — all of which exist only on
+> the external `conveyor-mcp` surface. If
+> `mcp__conveyor__get_connection_context` reports a task binding and no user
+> account, you are in a pod: say so and stop. Do not hunt for an equivalent.
+
+## Ground rules
+
+- **All Conveyor tools fully-qualified** — `mcp__conveyor__get_task`, not
+  `get_task`. Most are deferred; load every one you expect to need in a single
+  ToolSearch `select:` up front.
+- **Pass `projectId` explicitly on every call.** The connection's default
+  project may not be the repo you are standing in.
+- **Findings become cards; fixes get their own PRs.** Never fix anything inside
+  the review, however small. A fix made here ships unreviewed in the release
+  you were asked to judge.
+- **This skill never moves a release.** No `start_task`, `create_release`,
+  `add_to_release`, `approve_and_merge_pr`, or verdict tool. Holding or
+  shipping is a human's call; your job is to make the right call obvious.
+- **Production is read-only.** Logs, and SELECT-only data reads through the
+  project's own sanctioned path. Never a write, never a hand-exported
+  credential.
+- **The project's rules outrank this skill.** Gate commands, log queries, data
+  access and any release checklist live in the host repo's CLAUDE.md. A wrapper
+  skill may add dimensions (see the end of this file); it cannot lower the
+  evidence bar.
+
+## 0 — Discover the project
+
+Which levels, branches and evidence sources exist is a per-project fact.
+Guessing wastes the review either way.
+
+1. `mcp__conveyor__get_connection_context`, then match the project to the
+   repo's `git remote` (`mcp__conveyor__list_projects` when there is no
+   default). Copy the project id exactly.
+2. `mcp__conveyor__manage_priorities { action: "list" }` — the priority
+   ladder. The level with the **lowest `value`** is the **blocker level**;
+   every other level is a **suggestion level**. Use the project's own names in
+   every card and in the report. The seeded defaults are High, Medium and Low,
+   and the rest of this skill uses those names for readability. A project with
+   no priorities configured gets High / Medium / Low as text labels and no
+   priority writes.
+3. The dev branch and the default branch, from the repo and its CLAUDE.md.
+4. **Evidence sources — record what exists AND what does not:**
+   `mcp__conveyor__list_project_integrations`, whether
+   `mcp__conveyor__query_gcp_logs` / `mcp__conveyor__query_grafana_logs`
+   answer, the repo's local stack or mock scripts (`package.json` scripts such
+   as `dev:mock` or `dev`, or a repo skill that stands the app up), its scoped
+   test commands, and its sanctioned read-only data path.
+5. `mcp__conveyor__list_tags` once — the vocabulary, and whether a `release`
+   tag exists (step 6 uses it, and never creates it).
+
+Announce one line naming the release, the priority ladder, and the evidence
+sources you have and lack. Then start.
+
+## 1 — Scope the release
+
+Anchor to a concrete diff before reading any code.
+
+1. **Find the release.** An explicit version, branch or range in the argument
+   wins. Otherwise `mcp__conveyor__search_tasks` for the release card
+   (`Release <version>`, or the `release` tag, in ReviewPR or InProgress);
+   `mcp__conveyor__get_task` on it gives the branch and PR number. No release
+   cut → review the dev-to-default gap and label the run **pre-release**.
+2. **Fetch with explicit refspecs.** Many checkouts only track the dev branch,
+   so an unfetched ref silently reviews the wrong range.
+
+   ```bash
+   git ls-remote --heads origin 'release/*'
+   git fetch origin <default>:refs/remotes/origin/<default> \
+     <dev>:refs/remotes/origin/<dev> \
+     'refs/heads/release/*:refs/remotes/origin/release/*'
+   TIP=origin/release/<version>          # or origin/<dev> when pre-release
+   git rev-parse "$TIP"                  # the SHA this verdict is for
+   git log --merges --oneline origin/<default>.."$TIP"
+   git diff origin/<default>..."$TIP" --name-only
+   gh pr list --base <dev> --state merged \
+     --search "merged:>$(git log -1 --format=%cs origin/<default>)"
+   ```
+
+   The `gh pr list` cross-check catches squash and rebase merges the merge log
+   misses. Use `--name-only`, never `--stat`: truncated paths hide files.
+3. **Record the tip SHA.** A full release keeps absorbing the dev branch until
+   it merges, so the tip moves under you. The verdict is for the SHA you
+   recorded. If it moved by report time, review the delta or list the commits
+   you did not review.
+4. **Map every PR to its card.** `conveyor/<slug>-<id>` branch names embed the
+   card slug; otherwise `search_tasks` by PR title. `get_task` gives the plan,
+   which is the intent. Reviewing a diff without its intent is how a
+   single-interpretation solution gets waved through twice. A PR with no card
+   is reviewed on its diff alone and noted as such.
+5. **Build the coverage ledger** — one row per PR or card, one row per
+   dimension in step 2. Every row ends `clean`, `finding`, or
+   `not reviewable (why)`. "Evaluate everything" means the ledger has no blank
+   rows when you finish. On a large release, fan subagents out per area and
+   give each the ground rules and the evidence bar verbatim; the ledger is
+   still the completeness check, and it stays with you.
+
+## 2 — Review every dimension
+
+Work all of them. Each gets a coverage note in the report even when the note
+is "nothing found", so coverage is auditable. What to look for, the cheapest
+evidence, and a worked example of a real finding next to one that should be
+struck are in [references/dimensions.md](references/dimensions.md).
+
+| # | Dimension | The question |
+| --- | --- | --- |
+| 1 | **Cross-PR interaction** | Which files, symbols, tables and shared packages did two or more PRs touch, and what does their combined diff do? This is the headline check. |
+| 2 | **Data and migrations** | Destructive steps, locks on large tables, ordering between migrations, and the window where old code runs against the new schema. |
+| 3 | **Rollback and off-switches** | Which behavior changes have no flag, and what is the rollback for each risky change? |
+| 4 | **Deploy and config** | New env vars or secrets production lacks, CI or workflow changes, infra manifests, dependency major bumps. |
+| 5 | **Contracts and compatibility** | API, socket, MCP or published-package contract changes, against clients that are already deployed. |
+| 6 | **Security and access** | New methods or endpoints without an access check, secrets or personal data in logs, unbounded queries. |
+| 7 | **Stubs and cleanup** | In the diff only: TODO / FIXME / HACK, debug logging, `.only` or skipped tests, commented-out code, placeholder copy, orphaned flags. |
+| 8 | **Documented-contract drift** | `mcp__conveyor__get_tag` on each touched subsystem: did the release make an overview or a pinned invariant false? |
+| 9 | **Verification gaps** | Risky changed paths with no test, manual tests on member cards left unapproved or rejected (`mcp__conveyor__list_manual_tests`), CI state on the release PR. |
+| 10 | **Open signals** | Follow-ups promised in member-card chat that never became a card; incidents filed since the merge that implicate a release change. |
+| + | **Project dimensions** | Whatever a wrapper skill or the invoking prompt added. Same bar. |
+
+What comes out of this step is a list of **candidates**. None of them is a
+finding yet.
+
+## 3 — Evidence, or it is not a finding
+
+A candidate becomes a finding only with at least one of these. Record the
+exact query or command beside the result, so anyone can re-run it.
+
+| Grade | What it is |
+| --- | --- |
+| **Observed** | Logs or data. `env: "dev"` logs show the release's own code running, because its changes already merged to the dev branch. `env: "prod"` logs and read-only data show current traffic, data shape and row counts — what the release will meet. |
+| **Reproduced** | The project's local stack or mocks booted and the failure shown, or a scoped test or script that demonstrates the break. The steps go on the card. Nothing is committed. |
+| **Proven** | A deterministic static proof with both ends cited as `file:line` — a migration drops a column that code still reads. Allowed only when the failure needs no runtime assumption. "If a user happens to…" is not a proof. |
+
+- **Cheapest first:** logs, then a static proof, then a scoped test, then the
+  full local stack.
+- **Evidence downgrades too.** A path with no traffic in thirty days is a
+  reason to lower a finding or strike it.
+- **Time-box it.** A candidate that has cost fifteen minutes with no evidence
+  either way is Unverified. Move on.
+- **Unverified candidates are never filed.** They go in the report's
+  Unverified list, each with the evidence that would settle it. One that would
+  be blocker-level if true is named in the verdict line as an open question,
+  so a human decides with their eyes open.
+- **A missing source is reported, not substituted.** "No log access on this
+  project, so dimensions 4 and 10 rest on static reading" is a caveat the
+  reader needs.
+
+## 4 — Priority
+
+Grade by **consequence and evidence**, never by which dimension surfaced it.
+
+| Level | Test | Filed in |
+| --- | --- | --- |
+| **High** (the blocker level) | Shipping as-is causes data loss or corruption, a security or access hole, a broken live flow with no workaround, or a deploy that fails or cannot be rolled back. Observed, Reproduced or Proven only. | Release blockers |
+| **Medium** | A real user-facing defect or regression with a workaround or limited reach, or a gap that will bite within a release or two. | Release suggestions |
+| **Low** | Real but minor: cleanup, polish, small debt this release introduced. | Release suggestions |
+
+**Priority is not risk.** Priority is how urgently the fix is needed. Risk is
+how much important surface a change touches; identification and review set
+it, and this skill never does.
+
+The test for High is one question: *would I actually hold the release for
+this?* If the honest answer is "no, but it should be fixed soon", it is
+Medium. A blocker pack of twelve gets ignored, and then so does the one card
+in it that mattered.
+
+## 5 — The adversarial pass
+
+Every candidate that reached step 4, **together with the fix you would
+propose**, now faces a reviewer whose only job is to strike it. Use a fresh
+subagent given the finding, its evidence and the tests below, told to argue
+for striking. Where subagents are unavailable, switch stance explicitly and
+write the case against each finding before deciding.
+
+Strike when:
+
+1. **Over-engineering.** The fix is bigger than the problem: a new
+   abstraction, option or framework for something a few lines solve, or a
+   defense against a future nobody has asked for.
+2. **A niche path that already fails gracefully.** The path is rare — the
+   evidence shows little or no traffic — and its failure is already handled:
+   the error surfaces, no data is damaged, a retry works.
+3. **A redundant code path.** The fix adds a second guard, fallback, retry or
+   validation for something already guaranteed upstream. Cite the guard that
+   already exists.
+4. **The evidence does not support the claim.** It shows something nearby, or
+   something smaller.
+5. **The release neither caused nor worsened it.** Pre-existing problems are
+   out of scope. Worth recording → `mcp__conveyor__create_suggestion`, never a
+   release-pack card.
+6. **An open card already tracks it.** `mcp__conveyor__search_tasks`, two or
+   three keyword variants, all statuses. Name that card in the report instead
+   of filing a second one.
+
+Four outcomes: **Keep**, **Downgrade**, **Shrink** — keep the finding, replace
+the fix with the smallest change that removes the consequence — or **Strike**.
+Every struck finding is listed in the report with its reason. Nothing
+disappears silently, and a reader who disagrees with a strike can say so.
+
+## 6 — File the packs
+
+Survivors only. Created without asking, never started. Templates for the pack
+parent and the finding card are in
+[references/report-and-cards.md](references/report-and-cards.md).
+
+**The bar for every card is the `/conveyor-plan` plan format**
+([../conveyor-plan/references/plan-format.md](../conveyor-plan/references/plan-format.md)),
+Builder briefing included, because `/conveyor-build` is what runs these cards.
+Cite that format; do **not** invoke `/conveyor-plan`. You have already done
+the research, and its create-and-promote steps would file each card twice.
+
+`<label>` is `Release <version>` when a release is cut, and
+`Pre-release <YYYY-MM-DD>` otherwise.
+
+| | Release blockers | Release suggestions |
+| --- | --- | --- |
+| Holds | High findings | Medium and Low findings |
+| Parent title | `<label> blockers` | `<label> suggestions` |
+| Parent priority | the blocker level | the highest level among its children |
+| Lands in | **Open** — the release is waiting on it | **Planning** — a human promotes what they want built |
+
+In this order:
+
+1. `mcp__conveyor__create_task` the parent in Planning, with `priorityValue`,
+   and `tags: ["release"]` when step 0 found that tag.
+2. `mcp__conveyor__create_subtask` once per finding, full plan included, with
+   `dependsOn` only where one fix genuinely needs another to land first.
+3. `mcp__conveyor__update_task { taskId: <child>, priorityValue }` per child.
+   `create_subtask` carries no priority field; this is the sanctioned route.
+4. `mcp__conveyor__post_to_chat` on the parent — the sizing recommendation
+   and what the pack is for. Chat goes **before** any status move, because
+   identification reads it when the card leaves Planning.
+5. Blockers only: `mcp__conveyor__update_subtask { status: "Open" }` per
+   child, then `mcp__conveyor__update_task { status: "Open" }` on the parent.
+
+Then:
+
+- **A pack of one is a card.** One survivor at a level → a single card titled
+  `<label> blocker: <finding>` or `<label> suggestion: <finding>`.
+- **No survivors at a level → no pack at that level.** A clean release creates
+  nothing, and saying so is a complete result.
+- **Blocking is advisory.** Nothing in Conveyor stops a release PR from
+  merging. With a release card present, make the hold impossible to miss:
+  `mcp__conveyor__add_dependency { taskId: <release card>, dependsOnSlugOrId: <blocker pack or card> }`,
+  which shows the release as blocked until the fixes merge, and a
+  `post_to_chat` on the release card whose **first line** is the hold notice.
+  If `add_dependency` is refused, report the error once and carry on.
+- **Say how the fixes reach the release.** A full release absorbs whatever
+  merges to the dev branch, so merged fixes ship with it. A cherry-pick
+  release does not: a human adds them with Add to Release. Put the right
+  sentence in the blocker pack's plan.
+- **No `priorityValue` on `update_task`?** The connected MCP server predates
+  the field. Prefix each title with its level — `[High] …` — and say in the
+  report that priorities need setting by hand.
+- **On a tool error, stop and report the card rather than retrying it.** A
+  create that "failed" with a timeout may have landed; check with
+  `search_tasks` before creating it again.
+
+## 7 — Verdict and report
+
+The first line is the verdict, and it names the SHA:
+
+- **`HOLD`** — one or more High findings.
+- **`SHIP`** — none.
+- **`SHIP WITH OPEN QUESTIONS`** — no confirmed High, but at least one
+  Unverified candidate that would be High if true.
+
+Below it, in this order: the reviewed range and tip SHA; the packs, linked,
+with a findings table; the **deploy checklist**; the ledger summary with a
+note per dimension; struck findings with reasons; the Unverified list;
+evidence sources used and unavailable; anything not reviewed.
+
+The **deploy checklist** is every step a human must take at deploy — set a
+secret, run a backfill, flip a flag, apply a manifest — whether or not it is a
+finding. A release that is fine in code and fails because nobody knew to set a
+variable is the most avoidable outage there is.
+
+Post the report to the conversation, and with
+`mcp__conveyor__post_to_chat` to the release card when one exists. Never
+create a release card to hold it.
+
+## Running it again
+
+A release gets reviewed more than once: after the fixes land, or after the tip
+moves.
+
+- Find the existing packs by title (`search_tasks "<label> blockers"`) and add
+  new findings to them. Never create a second pack for the same release.
+- Read the last reviewed SHA from the release card's chat and review the
+  delta, not the whole release again.
+- Post the new verdict with the new SHA. The dependency on the release card
+  clears itself once the blocker pack merges to the dev branch.
+
+## Common mistakes
+
+- Reviewing the hunks. Combination bugs live in the overlap map, not in any
+  one diff.
+- Skipping migrations because CI passed. CI ran them against a schema no
+  production data ever stressed.
+- Grading by dimension. A cleanup item is not High because it touched a
+  migration, and a broken flow is not Low because it surfaced under "stubs".
+- One mega-card of findings. One card per finding, or nothing is
+  independently schedulable.
+- Re-litigating a merged PR. Per-PR review is `/conveyor-review`, and it
+  already happened.
+- Diagnosing an incident here. An incident the release implicates is
+  evidence; its root cause belongs to `/conveyor-triage`.
+
+## Wrapping this skill for one project
+
+A repo with its own release concerns keeps them in a thin project skill that
+invokes this one and names its extra dimensions and evidence tools, rather
+than in a fork. The wrapper's shape is at the end of
+[references/dimensions.md](references/dimensions.md). Project dimensions
+become extra ledger rows, graded by the same rubric and held to the same
+evidence bar and adversarial pass.
+
+## Environment notes
+
+- All Conveyor tools are **fully qualified** and mostly **deferred** — one
+  ToolSearch `select:` with every name you expect to need, up front.
+- `search_tasks` returns 20 rows by default — pass `limit`.
+- `gh` reads its own auth. An empty result with exit 0 from `gh pr list` or
+  `gh pr checks` can mean an expired token rather than "nothing there";
+  re-check before concluding.
+- The log tools appear only for a project with the matching integration. If
+  they are absent, the project has none; say so instead of hunting.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on the Conveyor project: the issue,
+evidence, and proposed fix.

package/skills/conveyor-release-review/references/dimensions.md

@@ -0,0 +1,289 @@
+# Review dimensions — what to look for, and what to strike
+
+The per-dimension checklist behind step 2 of
+[conveyor-release-review](../SKILL.md). Read that first: the evidence bar, the
+priority rubric and the adversarial pass all live there.
+
+Each dimension below has four parts:
+
+- **Look for** — the candidates worth raising.
+- **Cheapest evidence** — the first thing to try, because step 3 works
+  cheapest-first.
+- **A finding** — what a real one looks like once the evidence is in.
+- **A strike** — a candidate from the same dimension that the adversarial pass
+  should kill, and why. These matter as much as the findings: most of what a
+  release review turns up belongs here.
+
+The examples are illustrations, not a list to match against. File paths in
+them are invented.
+
+## 1. Cross-PR interaction
+
+The headline check, and the one no single-card review was positioned to make.
+
+**Look for**
+
+- Build the **overlap map** first: from `git diff --name-only`, group files by
+  the PRs that touched them, then widen to symbols, database tables, caches,
+  queues and shared packages. Two PRs that never touch the same file can still
+  meet at a table or a cache key.
+- Two green PRs on one surface: read their combined diff as a single change.
+- A shared-package change rippling into a caller that merged **earlier** in
+  the release, written against the old behavior.
+- Two PRs that each added a default, a retry, or a debounce to the same path.
+
+**Cheapest evidence** — a scoped test that exercises both changes together;
+the dev environment's logs for the shared path since the later PR merged.
+
+**A finding** — PR A renames a status value in the shared package; PR B,
+merged two days earlier, filters a query on the old name. Proven:
+`shared/status.ts:41` no longer exports the value `board/query.ts:118`
+compares against, so the filter matches nothing. High if the board is a live
+flow.
+
+**A strike** — two PRs both edited the same settings page, in different
+sections, with no shared state. Overlap on a file is a reason to look, not a
+finding. Struck: the evidence does not support the claim.
+
+## 2. Data and migrations
+
+Inherently untoggleable. CI runs migrations against a schema no production
+data ever stressed.
+
+**Look for**
+
+- Destructive steps: dropped columns or tables, narrowed types, new `NOT NULL`
+  without a default, unique indexes on columns that may hold duplicates.
+- Lock-heavy operations on large tables: index builds, rewrites, backfills
+  inside the migration transaction.
+- **Ordering between migrations** from different PRs on the same table. They
+  merge cleanly and still break in sequence.
+- The deploy window: old code running against the new schema, or new code
+  against the old one, depending on the project's deploy order.
+- A backfill the code assumes has run.
+
+**Cheapest evidence** — production row counts and a duplicate check through
+the project's sanctioned read-only path; the migration SQL itself.
+
+**A finding** — a migration adds a unique index on `(project_id, slug)`.
+Observed: a read-only count on production returns 14 duplicate pairs. The
+migration fails at deploy. High.
+
+**A strike** — "the index build could lock the table". Observed: the table
+holds 900 rows. Struck: niche path, and the evidence shows the cost is
+milliseconds.
+
+## 3. Rollback and off-switches
+
+**Look for**
+
+- Large behavior changes with no flag, setting or config to turn them off.
+  With a switch, mitigation is a config change; without one it is a rollback
+  or a hotfix.
+- Changes whose rollback is unsafe: a migration with no down path that the
+  previous code cannot run against, a data format the old code cannot read.
+- A flag that exists but defaults on for everyone at once.
+
+**Cheapest evidence** — a static read for the gate; the project's flag or
+settings catalog.
+
+**A finding** — a rewritten notification fan-out ships ungated, and the
+migration beside it drops the column the old implementation read. Proven:
+reverting the code alone leaves it reading a column that no longer exists.
+Rollback needs a restore. High.
+
+**A strike** — "this refactor has no feature flag". The refactor preserves
+behavior and is covered by the existing suite. Struck: over-engineering — a
+flag for a change with no behavior difference is a second code path to
+maintain for nothing.
+
+## 4. Deploy and config
+
+**Look for**
+
+- Environment variables or secrets the code now requires, checked against
+  what the deploy configuration actually provides.
+- CI, workflow and infra-manifest changes that only take effect at release.
+- Dependency major bumps, runtime version requirements, new system packages.
+- Steps a human has to take. These go in the report's **deploy checklist**
+  whether or not they are findings.
+
+**Cheapest evidence** — a grep of the diff for new environment reads, against
+the deploy manifests; startup validation output from a local boot.
+
+**A finding** — the API validates a new required variable at startup, and the
+production deploy manifest does not set it. Proven from the two files:
+the service refuses to boot. High.
+
+**A strike** — a new optional variable with a working default. Not a finding.
+It belongs in the deploy checklist as a note, and nowhere else.
+
+## 5. Contracts and compatibility
+
+**Look for**
+
+- API, socket, webhook or tool contract changes — renamed fields, newly
+  required fields, removed methods — against clients that deploy on a
+  different schedule: a web client cached in a browser, a mobile build, an
+  agent baked into an image, a published package pinned downstream.
+- Strict schemas that now reject what yesterday's client still sends.
+- Published-package changes that are breaking under a patch release.
+
+**Cheapest evidence** — production logs for the old shape still arriving;
+the consumer's pinned version.
+
+**A finding** — a request schema gained `.strict()`. Observed: production
+logs show a client still sending the field it now rejects, 2,100 requests in
+the last day. Those requests fail after the release. High or Medium by what
+the requests are.
+
+**A strike** — an added optional response field. Additive, ignored by old
+clients. Struck: no consequence.
+
+## 6. Security and access
+
+**Look for**
+
+- New methods, endpoints or tools without an access check, or with a check
+  that resolves no entity and so passes for any signed-in user.
+- Secrets, tokens or personal data written to logs.
+- Unbounded queries and unpaginated lists on user-controlled input.
+- Injection: string-built queries, shell commands, unescaped rendering.
+
+**Cheapest evidence** — a local call to the new method as a user who should
+be refused.
+
+**A finding** — a new read method declares member-level access but resolves
+no entry id. Reproduced locally: a user outside the project receives the
+project's data. High.
+
+**A strike** — "this admin-only method should also rate-limit". It sits
+behind an admin check and an existing global limiter, cited. Struck:
+redundant code path.
+
+## 7. Stubs and cleanup
+
+Search the **diff**, not the tree. Pre-existing debt is out of scope.
+
+**Look for** — TODO / FIXME / HACK, debug logging, `.only` and skipped tests,
+commented-out code, placeholder copy, temporary endpoints, flags and
+translation keys the release added and never referenced, or whose last
+reference it removed.
+
+**Cheapest evidence** — `git diff origin/<default>..."$TIP"` piped through a
+search for the markers, added lines only.
+
+**A finding** — a test file gained `.only`. Proven: the rest of that suite
+has not run in CI since the PR merged, and two of its cases fail when run.
+Medium, or High if those cases guard a live flow.
+
+**A strike** — a TODO noting a possible future optimization. Struck: no
+consequence. Twelve of these in a report are how a real finding gets skimmed
+past.
+
+## 8. Documented-contract drift
+
+**Look for**
+
+- For each subsystem the release touched, `mcp__conveyor__get_tag` and read
+  the overview and its linked files. Three findings hide here: a change that
+  silently makes a documented claim false, a change that should have updated
+  the overview and did not, and a renamed or deleted file that a tag still
+  links.
+- Rules and docs in the repo that agents load as context. A rule that now
+  describes removed behavior misleads every future session.
+
+**Cheapest evidence** — a static comparison of the claim against the code;
+the tag's link-verification status.
+
+**A finding** — a tag overview states that one process owns a given write,
+and the release added a second writer. Proven with both `file:line` cites.
+Medium: nothing breaks today, and every future change will be planned on a
+false premise.
+
+**A strike** — an overview that is merely less detailed than the new code.
+Struck: not caused by the release, and nothing in it is false.
+
+## 9. Verification gaps
+
+**Look for**
+
+- Changed paths that are risky and have no test.
+- Manual tests on member cards left unapproved or rejected:
+  `mcp__conveyor__list_manual_tests`.
+- CI state on the release PR, and checks that were skipped or never ran.
+- Suites weakened in the release: assertions removed, a filter added.
+
+**Cheapest evidence** — run the scoped test that should exist; the manual
+test list.
+
+**A finding** — a payment path changed and its only manual test was
+rejected with a note that was never addressed. Observed on the card. Medium,
+or High if a reproduction confirms the rejection.
+
+**A strike** — "this helper has no unit test". It is covered by the
+integration suite, cited. Struck: redundant.
+
+## 10. Open signals
+
+**Look for**
+
+- `mcp__conveyor__read_task_chat` on member cards: a follow-up promised
+  ("I'll handle the empty state in a later card") with no card to show for
+  it, or a reviewer concern that was acknowledged and never resolved.
+- Incidents filed since the changes merged to the dev branch that implicate
+  a release change: `search_tasks` with `typeFilters: ["incident"]`.
+- Errors in the dev environment's logs that began at a merge in this release.
+
+**Cheapest evidence** — dev logs with a start time at the merge; the
+incident's own context.
+
+**A finding** — an error appears in dev logs 410 times, first seen four
+minutes after a release PR merged, with a stack in a file that PR changed.
+Observed. Priority by what the failing call does.
+
+**A strike** — an incident filed during the window whose stack is in code
+the release never touched. Struck: not caused by the release. It already has
+a card.
+
+## Project dimensions
+
+A wrapper skill adds dimensions in the same four-part shape, and each becomes
+a ledger row. The shape to follow:
+
+```markdown
+## <Name>
+
+**Look for** — <the candidates, and where the project's rules for them live>
+**Cheapest evidence** — <the project tool that settles it fastest>
+**A finding** — <one real example>
+**A strike** — <one that should be killed, and which strike test kills it>
+```
+
+Dimensions that tend to be project-specific: multi-tenant assumptions (one
+customer's usage treated as the contract), a project's own authorization
+model, domain invariants, regulated data. They face the same evidence bar and
+the same adversarial pass as everything above.
+
+### The wrapper skill
+
+The project's own skill stays thin. It invokes this one and adds what only
+that project knows:
+
+```markdown
+---
+name: release-review
+description: Review a pending release of <project>.
+---
+Run `/conveyor-release-review` with these additions.
+
+Project dimensions:
+- <name>: <the question>, <where the rules live>, <cheapest evidence>
+
+Evidence tools:
+- Local reproduction: `<the repo's mock or dev stack command>`
+- Read-only production data: `<the repo's sanctioned script>`
+```
+
+A wrapper may add dimensions and name tools. It may not lower the evidence
+bar, skip the adversarial pass, or change what the priority levels mean.

package/skills/conveyor-release-review/references/report-and-cards.md

@@ -0,0 +1,183 @@
+# Report and card templates
+
+The shapes behind steps 6 and 7 of
+[conveyor-release-review](../SKILL.md). Fill them in; do not pad them. A
+section with nothing to say is written as one line saying so, never dropped,
+because a missing section reads as a skipped check.
+
+`<label>` is `Release <version>` when a release is cut, and
+`Pre-release <YYYY-MM-DD>` otherwise.
+
+## The report
+
+Posted to the conversation, and to the release card's chat when one exists.
+
+```markdown
+**HOLD — <label> @ <tip sha, 7 chars>.** 2 High findings. Blockers: <pack link>
+
+Reviewed `origin/<default>...<tip>`: 38 PRs, 214 files. Tip recorded
+<timestamp>; <"unchanged at report time" | "moved to <sha>, N commits not reviewed">.
+
+### Findings
+
+| Priority | Finding | Evidence | Introduced by | Card |
+| --- | --- | --- | --- | --- |
+| High | Unique index fails on 14 duplicate rows | Observed | #4712 | <link> |
+| Medium | Board filter matches nothing after status rename | Proven | #4698 + #4705 | <link> |
+
+Release blockers: <pack link> (2 cards, Open)
+Release suggestions: <pack link> (3 cards, Planning)
+
+### Deploy checklist
+
+- [ ] Set `<VARIABLE>` in production before the API deploys (#4720)
+- [ ] Nothing else requires a human step.
+
+### Coverage
+
+38 of 38 PRs evaluated. 2 without a card, reviewed on the diff alone: #4701, #4733.
+
+| Dimension | Result |
+| --- | --- |
+| Cross-PR interaction | 1 finding. 6 overlapping surfaces read as combined diffs. |
+| Data and migrations | 1 finding. 4 migrations, none lock-heavy at production size. |
+| Rollback and off-switches | Clean. |
+| ... | ... |
+
+### Struck
+
+| Candidate | Struck because |
+| --- | --- |
+| Add a retry to the export job | Redundant: the queue already retries 3 times (`jobs/queue.ts:88`) |
+| Guard against a malformed legacy payload | Niche and graceful: 0 occurrences in 30 days, error already surfaces to the user |
+
+### Unverified
+
+| Candidate | Would be | What would settle it |
+| --- | --- | --- |
+| Webhook handler may double-fire on redelivery | High | A redelivery against the dev environment, or the provider's delivery log |
+
+### Method
+
+Evidence sources used: dev and prod logs, local stack, read-only production data.
+Unavailable: <source>, so <which dimensions rest on static reading>.
+Not reviewed: <anything skipped, and why>.
+```
+
+Rules for the verdict line:
+
+- It is the **first line**, in both destinations. Someone who reads nothing
+  else must still get the verdict.
+- It names the SHA. A verdict without one cannot be checked against what
+  actually shipped.
+- `SHIP WITH OPEN QUESTIONS` names each open question on that same line or the
+  next one. It is not a softer `SHIP`.
+
+## The hold notice
+
+Posted to the release card when the verdict is `HOLD`. The first line carries
+the whole message; the report follows beneath it.
+
+```markdown
+**HOLD — do not ship <label> until the blockers merge.** 2 High findings: <pack link>
+```
+
+## The pack parent
+
+```markdown
+## Objective
+Clear the findings that block <label>, found by the release review of
+`<tip sha>` on <date>.
+
+## Approach
+Each child is one finding with its own evidence and its own smallest fix.
+They are independent unless a `dependsOn` edge says otherwise.
+
+## Implementation Steps
+1. <child title> — <one line>
+2. <child title> — <one line>
+
+## Testing
+Each child carries its own gates and acceptance criteria.
+
+## Notes
+- Release card: <link>. Reviewed SHA: `<tip sha>`.
+- <One of:> This is a full release, so fixes merged to `<dev>` ship with it.
+  <or> This is a cherry-pick release: once these merge, a human adds them with
+  Add to Release.
+- Priority is the urgency of the fix. Risk is set by identification and review.
+
+## Builder briefing
+- **Start here:** the child with the earliest deploy-time consequence.
+- **Already decided:** each fix is the smallest change that removes the
+  consequence. Do not widen it.
+- **Traps:** <what looks right and is not>
+- **Verify in this order:** re-run each child's evidence command first; a
+  finding that no longer reproduces is a finding someone already fixed.
+```
+
+The suggestions pack uses the same shape. Its Objective says these are worth
+doing and do not hold the release, and its Notes say the pack sits in Planning
+until a human promotes it.
+
+## The finding card
+
+One per finding, as a pack child or as a standalone card. It follows the
+`/conveyor-plan` plan format
+([plan-format.md](../../conveyor-plan/references/plan-format.md)) with two
+sections added at the top, because a builder who cannot re-run the evidence
+cannot tell a fixed finding from a wrong one.
+
+```markdown
+## Finding
+<What breaks, for whom, and when. One short paragraph.>
+
+Priority: <level>. Found in <label> @ `<tip sha>`. Release card: <link>.
+Introduced by: #<pr> (<card slug>), #<pr> (<card slug>).
+
+## Evidence
+Grade: <Observed | Reproduced | Proven>
+
+    <the exact query or command>
+
+Result: <what it returned, with the numbers>
+
+## Objective
+<One sentence: the consequence this card removes.>
+
+## Approach
+<The smallest change that removes it, and why nothing larger is needed.>
+
+## Implementation Steps
+1. `path/to/file.ts:120` — `symbolName`: <the change>
+2. ...
+
+## Testing
+- Gates: <the repo's scoped commands for this diff>
+- The evidence command above no longer shows the failure.
+- Manual tests (0-3): <plain sentences, user path only>
+
+## Notes
+- What the adversarial pass considered and rejected: <larger fixes, and why>
+- Blast radius: <callers and consumers of what this touches>
+
+## Builder briefing
+- **Start here:** <file>
+- **Already decided:** <what not to reopen, and why>
+- **Traps:** <what looks right and is not>
+- **Verify in this order:** <cheapest disqualifying check first>
+```
+
+Rules for the card:
+
+- **The description is for a non-engineer**: one or two plain sentences on
+  what goes wrong and for whom. Technical detail goes in the plan.
+- **The title names the consequence, not the dimension.** "Deploy fails on
+  duplicate slugs", not "Migration issue".
+- **Evidence is reproducible or it is not evidence.** An exact command, not
+  "checked the logs".
+- **Never paste a secret, a token or personal data** into a card. Quote the
+  shape of the log line, not the user's email in it.
+- **The fix is the smallest one.** Anything larger that the adversarial pass
+  rejected is recorded under Notes, so the builder does not rediscover it and
+  build it anyway.

package/skills/conveyor-workflows/SKILL.md

@@ -132,6 +132,7 @@ labels. Each tag carries a `description` (≤255 — the summary), an `overview`
   | Hand it to the cloud | `conveyor-start` → starts a pod and confirms it came up (local surface only — `start_task` does not exist in a pod) |
   | Do the work here | `conveyor-build` → follows the plan to a PR |
   | Judge the work | `conveyor-review` → one verdict, with risk |
+  | Audit a release before it ships | `conveyor-release-review` → evidence-backed findings, filed by priority as a blocker pack and a suggestions pack (local surface only — it needs `create_task`, `manage_priorities`, and `add_dependency` on another card) |
   | Work a whole queue locally | `conveyor-local-loop` → selection and pacing over the above |
   | Keep the board honest | `conveyor-prune` → one disposition per open card, applied only after confirmation (local surface only — it needs `set_task_parent`, `create_task`, and the on-hold flag) |
 
@@ -151,6 +152,17 @@ labels. Each tag carries a `description` (≤255 — the summary), an `overview`
   work. The loop idles on `conveyor-wait`, a CLI in `@rallycry/conveyor-mcp`
   that blocks until a card becomes claimable, so an idle loop wakes on a board
   event instead of a timer.
+- **From an app, with a project token (no MCP, no user)**: an external service
+  holding an incident-scoped project token files AND starts a card in one
+  call — `POST /api/incidents/report` with `type: "task"`, a `plan`, and
+  `start: true` (optionally `tags: [<glossary names>]`; an unknown name is a
+  400). The build starts through the same path as `start_task`, as the token's
+  owner, and the response carries `{ taskId, slug, url, status, buildStarted,
+  buildError? }`. A failed start still returns 201 with `buildStarted: false`
+  and leaves the card for a human — do not retry the report, that files a
+  second card. Poll `GET /api/incidents/tasks/<taskId>` with the same token for
+  `{ status, githubPRUrl, githubPRNumber, agentRunnerStatus }`. `start` is
+  rate-limited to 30 per token per 10 minutes.
 - **Reserved-branch trap**: a card with an assigned agent may have a reserved
   `githubBranch`. Check `get_task` before pushing: if set, push to THAT
   branch; a PR from any other branch gets auto-closed and unlinked.