Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/drain-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@stainless-code/verdict": minor
---

`drain` is a hidden CLI verb that refreshes threads, plans the review threads waiting on a verdict reply, and pins the plan with a digest. `drain --agent <name>` launches one agent through the same launcher `run` uses and validates its `drain.replies.json` against the plan. No host writes or reply posting ship in this slice.
20 changes: 10 additions & 10 deletions apps/docs/content/04-roadmap/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,16 @@ Planned means it is not built yet, and says so on its own line.

## Shipped today

| Stage | Commands | What they own |
| ------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Bundle | `fetch`, `fetch-local`, `index` | One diff per review target, from a host PR or your working tree, into `.verdict/state/`, plus the local code index (`index build`) the impact answers read. Chunking and a budget gate are opt-in. |
| Review | `run`, `record`, `panel`, `ingest`, `adopt`, `fix`, `handoff` | Launch your own agent on the bundle (`run`), validate its review and merge it into findings, plan independent disprove attempts (`panel`), ingest SARIF lint findings, carry local findings onto a PR, loop on one finding without escaping scope, and hand the fix brief to someone else. |
| Decide | `report`, `triage`, `threads`, `risk`, `next`, `show`, `trend`, `gate` | Render the bundle, gate on severity (`--check`), compose the gate dimensions (`gate`), emit SARIF (`--sarif`), queue the portfolio risk score (`risk`), and read trend across runs. |
| Post | `post`, `pr-wait` | Exactly one review, with anchor validation, stale-SHA and duplicate guards, `--dry-run`, and `--bind` for an approval; `pr-wait` waits on a PR's checks, review, or merge state without writing anything. |
| Trust | `verify`, `check-tree`, `doctor`, `calibrate`, `backtest`, `ready` | Check the bundle, the tree, the host login, past calibration, and readiness in one place, and mine, replay, and score bug-introducing candidates from your own history (`backtest`). |
| Agent surface | `skill`, `mcp` | The embedded skill (`skill`, `skill files`, `skill install`) and the review verbs as MCP tools over stdio. |
| Dashboard | `serve` | One read-only HTTP surface over `.verdict/state/`, with the browser inbox, review detail, threads, cost, precision, and gate panel; `report --html` exports the same views as static files. |
| Housekeeping | `init`, `config`, `pack`, `learn`, `upgrade`, `uninstall` | Repo config, explain policy, lens packs (`pack list`, `pack test`, `pack add`), project rules with provenance, and channel-aware upgrades and removals. |
| Stage | Commands | What they own |
| ------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Bundle | `fetch`, `fetch-local`, `index` | One diff per review target, from a host PR or your working tree, into `.verdict/state/`, plus the local code index (`index build`) the impact answers read. Chunking and a budget gate are opt-in. |
| Review | `run`, `record`, `panel`, `ingest`, `adopt`, `fix`, `handoff` | Launch your own agent on the bundle (`run`), validate its review and merge it into findings, plan independent disprove attempts (`panel`), ingest SARIF lint findings, carry local findings onto a PR, loop on one finding without escaping scope, and hand the fix brief to someone else. |
| Decide | `report`, `triage`, `threads`, `drain`, `risk`, `next`, `show`, `trend`, `gate` | Render the bundle, gate on severity (`--check`), compose the gate dimensions (`gate`), list review threads waiting on verdict and draft replies with your agent (`drain`, plan and draft only — posting lands later), queue the portfolio risk score (`risk`), and read trend across runs. |
| Post | `post`, `pr-wait` | Exactly one review, with anchor validation, stale-SHA and duplicate guards, `--dry-run`, and `--bind` for an approval; `pr-wait` waits on a PR's checks, review, or merge state without writing anything. |
| Trust | `verify`, `check-tree`, `doctor`, `calibrate`, `backtest`, `ready` | Check the bundle, the tree, the host login, past calibration, and readiness in one place, and mine, replay, and score bug-introducing candidates from your own history (`backtest`). |
| Agent surface | `skill`, `mcp` | The embedded skill (`skill`, `skill files`, `skill install`) and the review verbs as MCP tools over stdio. |
| Dashboard | `serve` | One read-only HTTP surface over `.verdict/state/`, with the browser inbox, review detail, threads, cost, precision, and gate panel; `report --html` exports the same views as static files. |
| Housekeeping | `init`, `config`, `pack`, `learn`, `upgrade`, `uninstall` | Repo config, explain policy, lens packs (`pack list`, `pack test`, `pack add`), project rules with provenance, and channel-aware upgrades and removals. |

Clients and actions over those verbs: the Go SDK (`pkg/verdict`), the TypeScript
client (`@stainless-code/verdict/client`), the JSON schemas in `skills/verdict/schemas/`, and
Expand Down
3 changes: 3 additions & 0 deletions clients/ts/src/refusal-codes.gen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,9 @@ export type RefusalCode =
| "diff-failed"
| "diff-too-large"
| "download-failed"
| "drafts-invalid"
| "drafts-stale"
| "drain-failed"
| "duplicate-payload"
| "fetch-failed"
| "filtered-out"
Expand Down
4 changes: 3 additions & 1 deletion cmd/verdict/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ import (
"github.com/stainless-code/verdict/internal/core"
"github.com/stainless-code/verdict/internal/core/upgrade"
"github.com/stainless-code/verdict/internal/doctor"
drainverb "github.com/stainless-code/verdict/internal/drain"
"github.com/stainless-code/verdict/internal/fetch"
"github.com/stainless-code/verdict/internal/fix"
"github.com/stainless-code/verdict/internal/gate"
Expand Down Expand Up @@ -65,7 +66,7 @@ const (

const verbsHint = "fetch|fetch-local|run|panel|record|adopt|ingest|fix|post|triage|report|next|show|" +
"check-tree|verify|doctor|calibrate|ready|pr-wait|gate|threads|trend|risk|handoff|index|backtest|" +
"learn|pack|init|skill|upgrade|uninstall|mcp|serve|config"
"learn|pack|init|skill|upgrade|uninstall|mcp|serve|config|drain"

func main() {
//nolint:forbidigo // GO-LAYOUT-02: main is the only os.Exit caller by design
Expand Down Expand Up @@ -182,6 +183,7 @@ var readVerbs = map[string]readHandler{
"pr-wait": prwait.Run,
"gate": gate.Run,
"threads": threads.Run,
"drain": drainverb.Run,
cmdTrend: trend.Run,
cmdRisk: risk.Run,
"calibrate": calibrate.Run,
Expand Down
11 changes: 10 additions & 1 deletion cmd/verdict/usage.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ package main
func usageText() string {
return "usage: verdict fetch|post|triage|report|next|show|verify|doctor|calibrate|" +
"fetch-local|run|panel|record|adopt|ingest|fix|check-tree|ready|pr-wait|gate|threads|trend|risk|handoff|index|" +
"backtest|learn|pack|init|skill|upgrade|uninstall|mcp|serve|config [opts]\n" +
"backtest|learn|pack|init|skill|upgrade|uninstall|mcp|serve|config|drain [opts]\n" +
" fetch <owner/repo> <pr> [--base-sha|--since <sha>] [--provider github|gitlab|gitcafe|forgejo|bitbucket|azure] " +
"[--index <ref|dir>] [--context <file|dir>] [--ignore <glob>] [--no-default-excludes] " +
"[--consent-over-budget] [--show-prompts] [--chunk] [--json]\n" +
Expand Down Expand Up @@ -276,6 +276,15 @@ func usageText() string {
" --dry-run lists what would be resolved and makes zero writes; a real run\n" +
" makes one host write per thread and writes threads-resolve.json. GitHub and\n" +
" GitLab carry it; Forgejo refuses typed (no documented resolve endpoint).\n" +
" drain <owner/repo> <pr> [--provider <p>] [--max-threads <1-100>] [--json]\n" +
" [--agent <name> [--timeout <secs>] [-- <agent args>...]]\n" +
" answer every review thread waiting on verdict: refresh threads, then write\n" +
" .verdict/state/<pr>/drain.json with the pending list, typed skips, and a plan digest.\n" +
" Zero pending is success and launches no agent. --max-threads defaults to 20;\n" +
" older questions are taken first and the rest are deferred. --agent drafts one\n" +
" drain.replies.json through the run launcher; no host write happens in this\n" +
" build (there is no --post yet). A truncated feed or unreadable login refuses\n" +
" drain-failed before the plan is written.\n" +
" trend <owner/repo> [--rules] [--overlap] [--incidents] [--resolution] [--json]\n" +
" portfolio rollup over existing bundle stores (no network, writes nothing):\n" +
" findings opened/addressed/closed over time, broken down by severity tier\n" +
Expand Down
13 changes: 13 additions & 0 deletions docs/manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,19 @@ write per thread, marks them resolved in `threads.json`, and writes
`threads-resolve.json` (provider, repo, PR, head, timestamp, `resolved[]`,
`skipped[]` with reasons). GitHub and GitLab carry the mutation; Forgejo
refuses typed because its API has no documented resolve endpoint.

`verdict drain owner/repo N [--provider p] [--max-threads 1-100] [--agent name]
[--timeout s] [-- args...] [--json]` plans one pass over the threads waiting on
verdict. It refreshes the feed, reads the login once, joins findings, and writes
`drain.json`: `pending[]`, typed `skipped[]` reasons, `other_threads`, and a
`plan_digest` over the pending list. A thread is pending when it is a review
comment verdict authored, unresolved, and its last comment is a human question
with no ledger entry answering it; the oldest questions come first and the rest
are `deferred`. `--max-threads` defaults to 20. Zero pending is success and
launches no agent. `--agent` drafts one `drain.replies.json` through the `run`
launcher; `drafts-invalid` and `drafts-stale` name a bad site or a moved plan.
This build makes no host writes and has no `--post`.

`post.json` and `record.json` carry `schema_version: "1"`.

### Bundle namespace (core files vs `x-*`)
Expand Down
18 changes: 18 additions & 0 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -585,6 +585,24 @@ Cause: the release download failed (bad version, no download directory, or a fet

Fix: pass a concrete `X.Y.Z` (or `vX.Y.Z`) version with a writable download dir, then re-run `upgrade`.

## `drafts-invalid`

Cause: `drain.replies.json` names an unknown thread or comment, repeats a thread, carries a bad disposition or body, or has an unknown key; the message names the site.

Fix: edit the named site to match the plan, then re-run `drain --agent <name>`. With no drafts file at all, run the agent first.

## `drafts-stale`

Cause: the drafts `plan_digest` differs from the plan's; the feed or the pending list moved after drafting.

Fix: re-run `drain` for a fresh plan, then draft replies against its digest.

## `drain-failed`

Cause: the bundle, `threads.json`, the login, or the reply ledger could not be read, or the refreshed feed is truncated.

Fix: refresh threads and confirm host auth, then re-run `drain`.

## `duplicate-payload`

Cause: every rendered summary part and comment is present in the live remote lists for this reviewed head.
Expand Down
Loading
Loading