workflow-toolkit 1.0.1

package/.agents/skills/wtk-deep-review/assets/findings.schema.json

@@ -0,0 +1,113 @@
+{
+  "type": "object",
+  "required": ["defects", "advisories", "suppressions", "coverage"],
+  "properties": {
+    "defects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "line", "in_diff", "hunk", "category", "severity", "quick_win", "title", "body", "rule_ids", "evidence"],
+        "properties": {
+          "file": { "type": "string" },
+          "line": { "type": "integer" },
+          "end_line": { "type": ["integer", "null"] },
+          "in_diff": { "type": "boolean" },
+          "hunk": { "type": ["string", "null"] },
+          "rule_ids": { "type": "array", "items": { "type": "string" } },
+          "category": { "enum": ["potential-issue"] },
+          "severity": { "enum": ["critical", "major", "minor"] },
+          "quick_win": { "type": "boolean" },
+          "title": { "type": "string", "maxLength": 100 },
+          "body": { "type": "string" },
+          "also_applies": { "type": "array", "items": { "type": "string" } },
+          "guideline": { "type": ["string", "null"] },
+          "suggestion": { "type": ["string", "null"] },
+          "evidence": { "type": "array", "minItems": 1, "items": { "type": "string" } }
+        }
+      }
+    },
+    "advisories": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "line", "in_diff", "hunk", "category", "severity", "quick_win", "title", "body", "rule_ids", "evidence"],
+        "properties": {
+          "file": { "type": "string" },
+          "line": { "type": "integer" },
+          "end_line": { "type": ["integer", "null"] },
+          "in_diff": { "type": "boolean" },
+          "hunk": { "type": ["string", "null"] },
+          "rule_ids": { "type": "array", "items": { "type": "string" } },
+          "category": { "enum": ["refactor", "nitpick"] },
+          "severity": { "enum": ["minor", "trivial"] },
+          "quick_win": { "type": "boolean" },
+          "title": { "type": "string", "maxLength": 100 },
+          "body": { "type": "string" },
+          "also_applies": { "type": "array", "items": { "type": "string" } },
+          "guideline": { "type": ["string", "null"] },
+          "suggestion": { "type": ["string", "null"] },
+          "evidence": { "type": "array", "minItems": 1, "items": { "type": "string" } }
+        }
+      }
+    },
+    "prior_findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["fingerprint", "status", "evidence"],
+        "properties": {
+          "fingerprint": { "type": "string" },
+          "status": { "enum": ["resolved", "open"] },
+          "evidence": { "type": "string" }
+        }
+      }
+    },
+    "suppressions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "line", "hunk", "candidate", "reason", "rule_ids", "note"],
+        "properties": {
+          "file": { "type": "string" },
+          "line": { "type": ["integer", "null"] },
+          "hunk": { "type": ["string", "null"] },
+          "candidate": { "type": "string", "maxLength": 140 },
+          "reason": { "enum": ["linter-overlap", "intentional", "generated-vendored", "formatting", "speculative", "pre-existing", "phantom-knowledge", "duplicate-within-job"] },
+          "rule_ids": { "type": "array", "items": { "type": "string" } },
+          "note": { "type": "string" }
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "required": ["hunks", "rules"],
+      "properties": {
+        "hunks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["file", "hunk", "checks", "outcome"],
+            "properties": {
+              "file": { "type": "string" },
+              "hunk": { "type": "string" },
+              "checks": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+              "outcome": { "enum": ["clear", "reported"] }
+            }
+          }
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["rule_id", "status", "note"],
+            "properties": {
+              "rule_id": { "type": "string" },
+              "status": { "enum": ["compliant", "violated", "not-applicable"] },
+              "note": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/.agents/skills/wtk-deep-review/references/context-pack.md

@@ -0,0 +1,88 @@
+# Context Pack
+
+How to assemble `<out>/context-pack.md` — the shared context every reviewer and sweep receives. **Keep it lean: target ≤ ~10 KB.** Every agent in the fan-out reads it in full, so each extra kilobyte is paid once per agent; reviewers dig into the code themselves (rg, git, file reads), so the pack carries only what they cannot cheaply rediscover — intent, review law, and what the linters already caught.
+
+## 1. Repository knowledge — discover before extracting
+
+Run the read-only discovery/bootstrap helper after the manifest:
+
+```bash
+python3 <skill-dir>/scripts/build_knowledge.py --out <out>
+```
+
+It discovers every repository-local root/nested `AGENTS.md` and `CLAUDE.md`, repo review config/learnings, project `SKILL.md` under conventional local skill roots, and direct markdown references of candidate skills. Nested instructions apply to selected paths in their directory subtree; all ancestors remain applicable and deeper sources have higher precedence.
+
+`knowledge.json` records why every source is or is not a candidate. `rules.template.json` starts every candidate as `pending`. Read each pending source **in full**; for a selected skill, read each pending direct reference in full too. Copy the template to `rules.json` and change every pending row to:
+
+- `applied` — the source was read and governs at least one selected path; or
+- `not-applicable` — include a concrete reason why it does not govern this change.
+
+`build_jobs.py` rejects missing sources, pending statuses, empty reasons, rule sources not marked applied, and rule scopes that match no selected path.
+
+## 2. Rubric — extract the review law
+
+Extract verdict-bearing rules in precedence order (higher wins on conflict):
+
+1. Path instructions from repo review config.
+2. Nested `AGENTS.md` / `CLAUDE.md`, deepest applicable directory first.
+3. Root `AGENTS.md` / `CLAUDE.md`.
+4. Explicitly dispatched or change-relevant project skills and their required references.
+5. `.wtk-deep-review/learnings.md` entries whose scope matches selected files.
+
+Extract only rules that can bind a review result (error handling, testing shape, layering, security, naming, documentation, design tokens, framework patterns). Operational commands can leave an applied source with zero rules when the accounting reason says it was read but contains no review law. Register each rule once and keep its text verbatim:
+
+```json
+{ "sources": [
+    { "source": "AGENTS.md", "kind": "instruction", "status": "applied",
+      "reason": "root rules govern every selected path" }
+  ],
+  "rules": [
+    { "id": "R07", "scope": ["**/*_test.go"], "source": "AGENTS.md",
+      "guideline": "MUST use t.Run(\"Should...\") pattern for ALL test cases" }
+  ]
+}
+```
+
+`scope` is the path-instruction glob, the instruction file's directory subtree, the selected skill's routed paths, or the learning's scope. To preserve the fan-out budget, the pack lists applied sources/rule counts plus one aggregate not-applicable count; complete per-source decisions stay in rules.json. `build_jobs.py` injects bound rules into defect cohorts and sweeps, and each output accounts for every assigned rule.
+
+## 3. Linter lanes — run first, suppress overlaps
+
+Detect what the repo already enforces and run it scoped to selected files; findings a lane reports are suppressed from the review (taxonomy rule 1).
+
+| Signal in repo | Lane command (scope to changed files where supported) |
+| --- | --- |
+| `Makefile` with `lint`/`check` target | `make lint` (authoritative when present — prefer it over raw tools) |
+| `golangci-lint` config / Go modules | `golangci-lint run <changed dirs>` |
+| `package.json` scripts `lint`/`typecheck` | the repo's own script via its package manager |
+| eslint/biome/oxlint config | corresponding tool on changed files |
+| `tsconfig.json` | `tsc --noEmit` (project-wide; cheap signal) |
+| `ruff.toml` / pyproject | `ruff check <files>` |
+| `Cargo.toml` | `cargo clippy` |
+
+Record per lane: `ran` (attach findings on selected files, trimmed) or `unavailable` (tool missing/failed — overlap suppression is off for that lane and review.md must say so). Never install tools to fill a lane.
+
+## 4. PR intent
+
+With `--pr`: title, description, linked issues (`gh pr view N --json title,body,closingIssuesReferences`), and base/head. Locally: `git log --oneline <base>..<head>` plus the user's stated intent. Reviewers judge the diff against *stated intent* — a change that does more than its description says is itself a finding.
+
+## 5. Spec contract (`--spec`)
+
+Resolve the conformance baseline: a file path is itself the artifact; a directory contributes its contract-bearing documents — `_prd.md`, `_techspec.md`, `_tests.md`, `_examples.md`, `_qa.md`, `_user_stories.md`, parity maps, requirement/UX docs, plus any document the spec's own files name as canonical. List every resolved artifact as `path → one-line role` for Technical Verifier context. Deep Review does not dispatch a separate spec-parity proof job; do NOT extract rubric rules from these artifacts: §1 sources are review law, the spec is the contract under test.
+
+## 6. context-pack.md layout
+
+```markdown
+# Context Pack — <target>
+
+## Intent
+<title/description/commits digest>
+
+## Rubric
+<applied source: path → rule count; N other sources classified not-applicable in rules.json; canonical forms: knowledge.json + rules.json>
+
+## Linters
+<lane → ran(findings digest) | unavailable(reason)>
+
+## Spec contract
+<only with --spec: one `- `path`` line per artifact — render_review.py parses these lines for the conformance table>
+```

package/.agents/skills/wtk-deep-review/references/orchestration.md

@@ -0,0 +1,164 @@
+# Orchestration
+
+The pipeline stage map, cohort planning rules, sweep triggers, and the execution engines. Prompt wording is single-sourced in `assets/PROMPT.md` (rendered by `build_jobs.py`); output shape in `assets/findings.schema.json` — this file explains how the stages compose and how jobs get executed.
+
+## Pipeline — stages, gates, artifacts
+
+Every stage materializes jobs with lane ownership (`{label, kind, lane, prompt, output, required_hunks, rule_ids}`), executes them on any engine, and passes a script gate. Valid outputs are preserved, so re-running touches only missing or invalid work.
+
+| Stage | Produce | Execute | Gate (exit 0) |
+| --- | --- | --- | --- |
+| Knowledge | `build_knowledge.py` → knowledge.json + rules.template.json | — | source discovery |
+| Plan | `build_jobs.py` → prompts + jobs.json | — | source accounting + ownership |
+| Review | — | jobs.json (defect cohorts + sweeps) | `run_jobs.py --validate-only` |
+| Merge | `merge_findings.py` → findings.json + review-stats.json | — | complete defect-lane coverage |
+| Report | `render_review.py` → review.md + state.json; `render_html.py` → review.html | — | `render_review.py` |
+
+Both job kinds (`cohort`, `sweep`) return the same schema: defects, advisories, objective suppressions, hunk coverage, and explicit rule accounting. `hunk` is the assigned canonical range (`<side>:<start>-<end>`), null outside the diff. Defects use the causal certificate; advisories use the improvement certificate.
+
+## Cohort rules (Step 2)
+
+1. Group selected files by package/directory and domain: a source file, its tests, and its types travel together; a file pulled apart from its test loses its reviewer the cheapest evidence.
+2. Size: target ~400 changed lines per cohort, so at most `min(concurrency, ceil(changed_lines / 400))` cohorts (fewer is allowed), each ≤ `--max-cohort-files` files (default `100`) **and** ≤ ~6,000 changed lines. Pass the same value to `build_jobs.py`; a single oversized file becomes its own cohort.
+3. **Oversized-file split** — when one file alone exceeds ~6,000 changed lines, divide the search across sibling reviewers: same file, disjoint slices of its manifest hunks (`hunk_scope`), one cohort per slice. Every slice reviewer reads the whole file for context but judges only its slice; build_jobs.py proves the merged slices cover every hunk line exactly once.
+4. Tag each cohort `risk: high|normal|low` — high when it touches storage/migrations, security/auth, public contracts, or concurrency; low for docs/config-only. Risk feeds reviewer emphasis, not selection.
+5. Every selected file in exactly one cohort (or, when sliced, every hunk line in exactly one slice) — build_jobs.py rejects any other shape. `plan.json`:
+
+```json
+{ "cohorts": [
+    { "id": "c01", "name": "store: task queue", "risk": "high",
+      "files": ["internal/store/queue.go", "internal/store/queue_test.go"] },
+    { "id": "c02a", "name": "loop/action.go — hunks 1-14", "risk": "high",
+      "files": ["internal/loop/action.go"],
+      "hunk_scope": { "internal/loop/action.go": [{"start": 12, "lines": 40, "side": "new"}] } }
+  ],
+  "sweeps": ["contracts", {"key": "layering", "lens": "custom lens text"}] }
+```
+
+Sweeps are bare keys from the table below (built-in lens text) or `{key, lens}` objects for a custom lens.
+
+When `manifest.mode` is `incremental` (a remediation check), `build_jobs.py` ignores `cohorts` and `sweeps` (printing `sweeps skipped in incremental mode` when any were planned) and emits one defect-lane job `cohort-rc` over every selected path, carrying `prior_fingerprints` and `prior_anchors` for every `open` ledger entry in `state.json`; the gate demands one `prior_findings` row per fingerprint and rejects a defect at a prior anchor. Write `plan.json` as usual.
+
+`build_jobs.py` rejects a plan with more cohorts than the rule-2 target and prints `cohort target: E for L changed lines at concurrency C`: merge the cohorts.
+
+## Sweep triggers
+
+Sweeps are **opt-in and rare** — default to none. Each sweep is one extra agent that sees the manifest, not one cohort; include it only when its trigger clearly fires and the plan has three or more cohorts (`build_jobs.py` rejects sweeps on smaller plans), and prefer at most one or two per round:
+
+| Key | Trigger | Looks for |
+| --- | --- | --- |
+| `contracts` | exported/wire/API symbol changed contract | breaking changes, drift between spec/impl/clients, missing codegen co-ship |
+| `security` | new endpoint/input path/authz surface/secret handling | injection, missing authn/authz, secret leakage, cross-tenant access |
+| `migrations` | schema/migration files in diff | destructive ops, missing migration for model change, ordering/identity hazards |
+| `consistency` | renames or repeated patterns in diff | incomplete renames, sibling paths not mirroring a fix, duplicated logic |
+| `config` | config keys/flags/env vars changed | unwired or undocumented keys, dead flags, default mismatches |
+
+## Engines
+
+The jobs contract makes engines interchangeable — pick one per run, record it in context-pack.md (`Mode: workflow | agent-fallback | subagent:<runtime>`), and always close the loop with `run_jobs.py --validate-only`. Validation rejects missing coverage rows, in-diff anchors outside job ownership, and unassigned rule ids.
+
+**Named native dispatch (default when host supports it).** Dispatch up to the manifest concurrency
+bound to the custom `deep-reviewer` agent, refill slots as jobs complete, and keep retries inside
+the owning worker slot. After a provider block, let active attempts finish and do not refill. Use
+the host's real selector:
+
+- Claude Code Task: `subagent_type: "deep-reviewer"`.
+- Cursor `cursor/task`: `subagentType: { custom: "deep-reviewer" }`.
+- Native Agent/spawn: custom agent name/type `deep-reviewer`, resolved from the host's local agent
+  configuration.
+
+Metrics are optional provider-neutral hooks. An adapter may call `start_metrics`,
+`checkpoint_metrics`, and `finalize_metrics` around the bounded dispatch; the main thread records
+serialized cumulative snapshots only and never assigns overlapping deltas to jobs or changes exits.
+Record `Mode: native` in context-pack.md, then run the validate-only gate. Provider-specific
+telemetry setup belongs in the runtime adapter guidance, not in this orchestration contract.
+
+Before prompts are materialized, `build_jobs.py` always prepares the pinned Graft context:
+`graft build`, repository-map lookup, blast-radius tracing, and symbol lookup are written to the
+prompt's context artifact. Graft is a non-blocking inspection aid: a missing binary, stale map, or failed
+command falls back to plain repository inspection and does not block review. Graft does not index
+dot-directories, so selected `.agents` paths always carry an explicit plain-inspection fallback.
+
+**Workflow fallback (when named native dispatch is unavailable).** One generic script executes any
+stage's pending jobs — pass the pending list from the validate-only status file as `args.jobs` and
+launch at most the manifest concurrency. Refill completed slots, stop refilling after a provider
+block, and preserve jobs-file order when the stage returns. This path intentionally stays role-free;
+it does not assume a named-agent parameter.
+
+```js
+export const meta = {
+  name: 'wtk-deep-review-jobs',
+  description: 'Execute pending wtk-deep-review jobs; each agent reads a prompt file and writes one output file',
+  phases: [{ title: 'Execute' }],
+}
+// args: { jobs: [{label, prompt, output}], concurrency?: integer } — PENDING jobs only
+phase('Execute')
+let returned = 0
+const inputJobs = [...(args.jobs ?? [])]
+const pending = [...inputJobs]
+const requestedConcurrency = args?.concurrency
+if (requestedConcurrency !== undefined &&
+    (!Number.isInteger(requestedConcurrency) || requestedConcurrency < 1 || requestedConcurrency > 6)) {
+  throw new Error('concurrency must be an integer from 1 through 6')
+}
+const resolvedConcurrency = requestedConcurrency === undefined ? 3 : requestedConcurrency
+const workerLimit = Math.min(resolvedConcurrency, pending.length)
+const active = []
+const resultsByLabel = new Map()
+let providerBlock = null
+while (pending.length || active.length) {
+  while (!providerBlock && pending.length && active.length < workerLimit) {
+    const j = pending.shift()
+    const promise = agent(`Read ${j.prompt} and follow it exactly. It defines the review task, the JSON ` +
+      `schema, and the single file you write (${j.output}). Repo files are read-only. ` +
+      `Reply with one sentence once the artifact is written.`,
+      { label: j.label, phase: 'Execute' }).then(
+        () => ({ label: j.label, status: 'pass' }),
+        (error) => {
+          const message = String(error?.message ?? error)
+          return { label: j.label, status: message.includes('usageLimitExceeded') ? 'blocked' : 'fail', error: message }
+        },
+      )
+    active.push({ label: j.label, promise })
+  }
+  if (!active.length) break
+  const finished = await Promise.race(active.map(({ promise }) => promise))
+  const index = active.findIndex(({ label }) => label === finished.label)
+  active.splice(index, 1)
+  resultsByLabel.set(finished.label, finished)
+  if (finished.status === 'blocked' && providerBlock === null) providerBlock = finished
+  if (finished.status === 'pass') returned += 1
+}
+const orderedJobs = inputJobs.map(({ label }) => resultsByLabel.get(label) ?? ({ label, status: 'pending' }))
+const unfinished = orderedJobs.filter(({ status }) => status !== 'pass')
+return {
+  dispatched: inputJobs.length,
+  returned,
+  jobs: orderedJobs,
+  blocker: providerBlock,
+  pending: unfinished,
+}
+```
+
+After the workflow returns, run the validate-only gate; re-invoke with the still-pending jobs (interrupted runs can also resume via `resumeFromRunId`). Two re-dispatches without progress → inspect a failing output by hand before continuing.
+
+**Agent fallback (`--no-workflow` or no Workflow tool).** Same contract through the Agent tool: use
+the named native selectors above when available. If the host has no named-agent path, use the
+generic prompt-only subagent dispatch ("Read `<prompt>` and follow it exactly…") with the manifest
+concurrency bound; do not add an unsupported role argument. Then run the validate-only gate.
+
+**External runtimes (`--subagent` ≠ `native`).** `run_jobs.py --command` drives `compozy exec` per
+subagent-runtimes.md — the runner owns bounded execution, retries, output validation,
+provider-block detection, and the freeze check.
+
+The orchestrator never reviews inline, regardless of PR size: reviewers spend their own context on their cohort; the orchestrator plans, dispatches, gates, and reports.
+
+### Bounded dispatch
+
+The manifest builder resolves reviewer concurrency once, with precedence `--concurrency N` over
+`.wtk-deep-review.yaml` over the default `3`, validates `1` through `6`, and pins the result in
+`manifest.json`. Every execution engine consumes that pinned value. It launches up to
+`min(concurrency, pending jobs)`, refills a worker slot after completion, and never schedules a
+new job after the first provider block. Active attempts finish; pending and blocked jobs remain in
+the blocker ledger. Results are stored by label and emitted in jobs-file order, regardless of
+completion order. The removed legacy `--workers` option is rejected.

package/.agents/skills/wtk-deep-review/references/output-contracts.md

@@ -0,0 +1,149 @@
+# Output Contracts
+
+Exact templates for every artifact. Placeholders in `<angle brackets>`; keep section order and marker strings byte-stable — fingerprints and upserts depend on them. walkthrough.md is orchestrator-authored; review.md and state.json are rendered from findings.json by `scripts/render_review.py`, which implements these templates and the verdict rule — this file is the contract it must keep.
+
+## Contents
+
+- walkthrough.md
+- Finding block
+- review.md
+- review.html
+- ReportFindings mapping
+- Verdict rule
+
+## walkthrough.md
+
+```markdown
+<!-- wtk-deep-review:walkthrough -->
+## Walkthrough
+
+<one dense paragraph: what the change does across the stack, in prose>
+
+## Changes
+
+| Cohort / File(s) | Summary |
+| --- | --- |
+| **<cohort name>** <br> `<path>`, `<path>`, `<dir>/{a,b}.go` | <what changed there, 1–2 sentences> |
+
+## Sequence Diagram(s)
+
+<only when the change alters a multi-actor flow (request path, event flow, lifecycle);
+one mermaid sequenceDiagram per flow, actors = real components>
+
+## Estimated code review effort
+
+🎯 <1-5> (<label>) | ⏱️ ~<minutes> minutes
+
+## Review details
+
+- **Scope**: <base sha short> → <head sha short> (<incremental round N | full review>)
+- **Files**: <n> selected · <n> ignored by filters · <n> skipped (trivial/similar)
+- **Posture**: assertive · **Mode**: <workflow|agent-fallback|subagent:runtime>
+- **Rubric**: <sources consulted, comma-separated paths>
+- **Linters**: <lane: ran/unavailable, ...>
+```
+
+Effort scale (calibrate on *reviewable surface* — selected source, not raw file count):
+
+| 🎯 | Label | ⏱️ | When |
+| --- | --- | --- | --- |
+| 1 | Trivial | ~5 min | mechanical or config-only |
+| 2 | Simple | ~12 min | small localized change |
+| 3 | Moderate | ~25 min | one subsystem, some cross-file reasoning |
+| 4 | Complex | ~60 min | multiple subsystems or a contract change |
+| 5 | Critical | ~120 min | core invariants, storage, security, or wide blast radius |
+
+## Finding block (used in review.md and PR comments)
+
+```markdown
+_<category badge>_ | _<severity badge>_[ | _<effort badge>_]
+
+**<Imperative one-line claim ending in a period.>**
+
+<Evidence paragraph: the concrete failure mode or improvement, referencing real
+symbols and line numbers. State what happens, under which input/state, and why.>
+
+[Also applies to: <path>:<lines>, <path>:<lines>]
+[As per coding guidelines [R<NN>] (`<source path>`): "<verbatim rule>"]
+Certificate: <defect: Premise → Path → Verdict | advisory: Premise → Improvement → Fix>
+
+<details>
+<summary>📝 Committable suggestion</summary>
+
+> ‼️ **IMPORTANT**: review before committing — generated against lines <X>–<Y>.
+
+```suggestion
+<exact replacement for lines X–Y, only when the fix is mechanical and complete>
+```
+</details>
+
+<details>
+<summary>🛠️ Repair plan</summary>
+
+1. Root cause: <Premise clause of the certificate> → <Path clause of the certificate>
+2. Fix every site: <path:line>, <also_applies anchors...>
+3. Before editing, grep every caller of the symbol at <path:line>; fix at the owning layer.
+4. Extend the nearest test so it fails on the Premise, then fix until it passes.
+5. Suggested change: <suggestion | none>
+</details>
+<!-- wtk-deep-review:fp:<fingerprint> -->
+```
+
+Bracketed lines appear only when they apply. Every result has the certificate for its class. The committable `suggestion` block appears only when the replacement is exact and self-contained; the Repair plan appears on **Critical, Major, and Minor defects**.
+
+## review.md
+
+```markdown
+# Deep Review — <target> (round <N>)
+
+**Verdict: <SHIP | FIX_BEFORE_SHIP | REWORK>** — <one-line rationale>
+**Defects: <n>** (🔴 <n> · 🟠 <n> · 🟡 <n>) · advisories: <n> · duplicates: <n> · resolved since last round: <n> · merged duplicate reports: <n>
+
+<walkthrough.md content, inlined>
+
+## Findings
+
+### <path>
+
+<finding blocks for this file, severity-descending>
+
+## Outside diff range
+
+<finding blocks with in_diff: false, grouped per file; "None.">
+
+## Spec context
+
+<spec artifacts are provided to Technical Verifier; Deep Review does not render a separate spec-parity proof section>
+
+## Duplicates (unresolved from round <N-1>)
+
+<one-line entries: badge · claim · original round; "None.">
+
+## Advisories
+
+<full advisory blocks grouped per file; "None.">
+
+## Review observability
+
+<candidate, suppression, and complete defect hunk coverage counts>
+```
+
+`review.md` orders files by max severity, then path.
+
+## review.html
+
+The human-facing dashboard, emitted by `scripts/render_html.py`, hydrates `assets/REVIEW_UI.html` with defects and advisories in separate sections plus suppression and coverage observability. The fixed template is self-contained (inline CSS/JS, no network) and `review.html` is never hand-edited. Before render_review.py writes the state entry, the verdict remains a neutral "round in progress" state.
+
+## ReportFindings mapping
+
+When the harness exposes the ReportFindings tool, call it once after review.md is written: one entry per defect and advisory, defects first by severity and then advisories by file. Use `file`/`line` from the anchor, `summary` from the claim, and the matching evidence certificate. Omit `verdict`; the certificate and refutation checks are the confidence signal.
+
+## Verdict rule
+
+Derive after Step 4's merge from open **defects only**; advisories never change the verdict:
+
+- **SHIP** — no Critical or Major defect is open; Minor defects enter the mandatory current-feature closeout batch without a remediation check; Trivials and advisories become follow-ups.
+- **FIX_BEFORE_SHIP** — at least one Critical/Major defect is open, and remediation is local: the change's shape is right and each defect names a bounded fix.
+- **REWORK** — defects show structural failure needing redesign: one root cause across ≥3 cohorts or a Critical whose fix rewrites the change's core. REWORK always carries a named rationale; otherwise FIX_BEFORE_SHIP is the ceiling.
+
+The verdict lands in review.md, state.json, and the final message. render_review.py derives SHIP / FIX_BEFORE_SHIP from defects with round status new or duplicate plus prior `open` ledger entries without a `prior_findings` disposition, and accepts REWORK only through `--rework "<rationale>"` backed by structural defects.

package/.agents/skills/wtk-deep-review/references/publish-github.md

@@ -0,0 +1,83 @@
+# Publish to GitHub
+
+Recipes for `--publish`. Everything goes through `gh api`; `R` is `owner/repo`, `N` is the PR number. Bodies come from files (`-F body=@file`) rather than inline shell strings.
+
+## Reviewer identity
+
+GitHub rejects `APPROVE`/`REQUEST_CHANGES` on a PR authored by the authenticated user. Detect identity first:
+
+```bash
+AUTHOR=$(gh api repos/$R/pulls/$N --jq .user.login); ME=$(gh api user --jq .login)
+```
+
+Same login means `event=COMMENT`. For a bot/machine user, `request_changes_workflow: true` permits `REQUEST_CHANGES` only when Critical/Major **defects** are open. Advisories never change the event.
+
+## 1. Upsert the walkthrough comment
+
+One comment per PR, edited in place through its marker:
+
+```bash
+CID=$(gh api repos/$R/issues/$N/comments --paginate \
+  --jq '[.[] | select(.body | contains("<!-- wtk-deep-review:walkthrough -->"))][0].id // empty')
+if [ -n "$CID" ]; then
+  gh api repos/$R/issues/comments/$CID -X PATCH -F body=@"$OUT/walkthrough.md"
+else
+  gh api repos/$R/issues/$N/comments -F body=@"$OUT/walkthrough.md"
+fi
+```
+
+## 2. Anchor defects and advisories
+
+Inline comments must land on changed lines. The valid ranges are in manifest.json. Every in-diff defect **and every in-diff advisory** becomes an inline comment; low severity is not a collapse reason. Outside-diff or drifted anchors move to the matching review-body section. On a GitHub 422 despite the precheck, move that result to the body and continue.
+
+## 3. Post the review submission
+
+`comments.json` has one entry per anchorable defect/advisory. Render `body` from the result block template and preserve its fingerprint marker:
+
+```json
+[{ "path": "internal/store/queue.go", "line": 42, "side": "RIGHT",
+   "start_line": 38, "start_side": "RIGHT", "body": "<rendered result block>" }]
+```
+
+Use `start_line`/`start_side` only for multi-line ranges. The review body starts with `**Defects posted: <n> · Advisories posted: <n>**`, includes Outside diff, Duplicates, and results whose anchors were unavailable, then ends with `Reviewing files that changed between <base> and <head>.`:
+
+```bash
+jq -n --rawfile body "$OUT/review-body.md" --slurpfile c "$OUT/comments.json" \
+  --arg ev "$EVENT" '{event:$ev, body:$body, comments:$c[0]}' > "$OUT/review-payload.json"
+gh api repos/$R/pulls/$N/reviews --input "$OUT/review-payload.json"
+```
+
+More than 75 inline comments means multiple submissions of at most 75. The first carries the full body; continuations state separate defect/advisory counts.
+
+## 4. Resolve prior-round comments
+
+For each prior defect/advisory marked `resolved`, prepend the resolution while preserving the original body:
+
+```bash
+gh api repos/$R/pulls/comments/$COMMENT_ID -X PATCH \
+  -F body=@<(printf '✅ Addressed in commit %s\n\n%s' "$SHORT_SHA" "$ORIGINAL_BODY")
+```
+
+Unresolved prior results are not re-posted inline; they appear once under Duplicates.
+
+## 5. Recover state from the PR
+
+For CI or another machine without local state:
+
+```bash
+gh api repos/$R/pulls/$N/comments --paginate --jq '.[].body' | grep -o 'wtk-deep-review:fp:[a-f0-9]*'
+gh api repos/$R/pulls/$N/reviews --paginate --jq '.[].body' | grep -o 'wtk-deep-review:fp:[a-f0-9]*'
+```
+
+Recover the latest `Reviewing files that changed between <base> and <head>.` line as the prior head. A fingerprint absent from the current defects/advisories remains open unless the incremental reviewer returns a `prior_findings` row with `status: resolved` and evidence; otherwise it remains under Duplicates.
+
+## Order and idempotency
+
+1. Verify `gh auth status` and access; detect identity.
+2. Upsert walkthrough.
+3. Anchor-check every defect/advisory and render fingerprints.
+4. Post submission batches.
+5. Apply resolution edits.
+6. Cite walkthrough and review URLs.
+
+Before posting, check reviews for the same base/head scope line. One review series per round and head SHA is allowed; a match means the publish step already ran.