workflow-toolkit 1.0.1

package/.agents/skills/wtk-deep-review/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: wtk-deep-review
+description: "Review diffs, worktrees, or PRs in depth, including spec conformance and requested finding publication. Use for deep review; not fixes, spec edits, or quick feedback."
+disable-model-invocation: true
+argument-hint: "[--pr N | --base <ref> | --staged | --worktree] [--files p1,p2] [--spec <path>] [--subagent native|claude-opus|grok|codex] [--max-cohort-files N] [--publish] [--full] [--out <dir>] [--no-workflow]"
+---
+
+# Deep Review
+
+Review at CodeRabbit grade with no file cap and one assertive posture: funnel the diff, discover root/nested project instructions and relevant local skills, shard the diff into defect cohorts, fan out reviewers, then merge with complete hunk/rule accounting. Defects require causal evidence and control the verdict; advisories require a concrete improvement and always remain visible.
+
+Steps 1–4 drive an idempotent artifact pipeline under `<out>`: every stage gate is a bundled-script exit 0, valid agent outputs are never re-run, and an interrupted round resumes by re-running the same commands.
+
+`<skill-dir>` below means the directory containing this SKILL.md; run every bundled command from the repo root.
+
+## Inputs (all optional)
+
+| Flag | Meaning | Default |
+| --- | --- | --- |
+| `--pr <n>` | Review a GitHub PR (requires authenticated `gh`; head fetched locally) | — |
+| `--base <ref>` / `--staged` | Local diff scope | merge-base with the origin default branch |
+| `--worktree` | Review uncommitted + untracked work against the base ref (always a full round) | — |
+| `--files <p1,p2>` | Restrict review to these paths | full diff |
+| `--concurrency <n>` | Override repository reviewer concurrency (`1`–`6`) while building the manifest | `.wtk-deep-review.yaml` or `3` |
+| `--spec <path>` | Spec file or directory; its contract-bearing artifacts are available as reviewer context | — |
+| `--subagent <runtime>` | Step 3 reviewer runtime: `native` \| `claude-opus` \| `grok` \| `codex` — non-native runs cross-LLM via `compozy exec` | `native` |
+| `--max-cohort-files <n>` | Maximum files assigned to one cohort; the ~6,000 changed-line cap still applies | `100` |
+| `--publish` | Post walkthrough + review to the PR | off — local report only |
+| `--full` | Ignore prior state; review the whole diff again | incremental when state exists |
+| `--out <dir>` | Artifact directory | `.wtk-deep-review/<target>/` |
+| `--no-workflow` | Skip the Workflow tool; use Agent execution | Named native `deep-reviewer` when the host supports it; role-free Workflow fallback |
+| `--metrics` | Observe compatible provider usage when an adapter is configured | unavailable without a compatible adapter |
+| `--metrics-db <path>` | Provider telemetry source supplied by an adapter | none |
+| `--metrics-ledger <path>` | Content-safe observational metrics path | `<out>/runs/review-metrics.json` |
+| `--metrics-reviewer-prefix <path>` | Explicit provider reviewer path for the adapter | none |
+
+## Repo config — `.wtk-deep-review.yaml`
+
+Optional repo-root file, the skill-native config standard. Any key absent there falls back to its `.coderabbit.yaml` counterpart (`reviews.*`), so repos migrating from CodeRabbit work unconfigured. Top-level keys, all optional:
+
+| Key | Meaning |
+| --- | --- |
+| `concurrency` | Maximum simultaneous reviewer jobs, an integer from `1` through `6`; defaults to `3` and is pinned in `manifest.json` |
+| `path_filters` | Globs over repo-relative paths: `!pat` excludes; bare patterns, when present, restrict review to their matches and beat any exclude; built-in excludes (locks, vendor, generated, testdata, snapshots) always append |
+| `path_instructions` | `path` glob + verbatim `instructions` entries — the highest-precedence rubric source (Step 2) |
+| `request_changes_workflow` | publish-mode review-event gate |
+
+The manifest builder resolves `path_filters` into manifest.json; the knowledge stage ingests `path_instructions` together with project instructions and skills.
+
+## Hard rules
+
+- Source is read-only and **frozen**: the manifest pins `worktree_snapshot`, and run_jobs.py / render_review.py refuse a drifted checkout. Writes go only to `<out>`, `.wtk-deep-review/` state, and — with `--publish` — the target PR.
+- No file-count cap: a large selection means more cohorts, never a skipped or silently truncated review. Every selected file lands in exactly one cohort.
+- Every defect starts with `Premise → Path → Verdict`; every advisory starts with `Premise → Improvement → Fix`. Investigated rejections remain visible in the suppression ledger.
+- Every selected hunk line receives defect-lane coverage. Every bound rule receives an explicit compliant/violated/not-applicable assessment.
+- Run the repo's linters first and record every overlapping candidate as `linter-overlap` rather than reporting it again.
+- Cite rubric rules verbatim with their source path; severity comes from the taxonomy, never inflated.
+- Publishing needs `--publish` or the user's explicit go-ahead in this session; otherwise the review stays local.
+- Every review ends with a **SHIP / FIX_BEFORE_SHIP / REWORK** verdict derived by render_review.py and stated only after that script exits 0.
+- `FIX_BEFORE_SHIP` is actionable, not a prompt for approval: in an approved loop, follow `docs/toolkit/guidelines/REVIEW-ROUNDS.md`: fix every defect from its Repair plan, run the scoped gate, then the remediation check below, until no Critical/Major is open or `stall_attempts` halts.
+- Optional metrics snapshot provider totals and cumulative checkpoints without changing dispatch,
+  retries, outputs, or exits. The main thread records serialized cumulative checkpoints without
+  per-job token attribution; totals finalize only after the full scope completes. Hosts without a
+  compatible adapter record `unavailable` and continue the review normally. The pinned Graft adapter
+  runs before prompts are materialized; a failed or absent Graft falls back to ordinary repository
+  inspection.
+- Native execution uses the configured named `deep-reviewer` when the host supports it; otherwise use the role-free Workflow fallback or prompt-only Agent fallback described in orchestration.md.
+- Reviewer concurrency is resolved before dispatch: `--concurrency N` overrides `.wtk-deep-review.yaml`, which overrides the default `3`; valid values are `1` through `6`. The resolved value is frozen in `manifest.json`. The legacy no-op `--workers` option is rejected.
+- External `--subagent` runtimes spend `compozy exec` credit.
+
+## Procedure
+
+**Step 1: Funnel — build the manifest**
+
+1. Run the bundled manifest builder (bootstrap helper; reads the repo and `gh`, writes only under `--out`):
+
+   ```bash
+   python3 <skill-dir>/scripts/build_manifest.py --out <out> \
+     [--pr N | --base REF | --staged | --worktree] [--files p1,p2] [--full] [--concurrency N]
+   ```
+
+   It resolves repo path filters, detects generated / trivial / renamed files, scopes to the incremental delta when prior state exists, and pins the source-freeze snapshot.
+2. Read the printed summary. For `--pr`, the manifest base is the merge-base of the fetched PR base/head, so base-only changes stay outside the review. If the head is missing, run the printed fetch command and retry; if the base/history is missing, fetch it before retrying.
+
+*Done when:* `<out>/manifest.json` exists, every changed file is accounted for as selected, ignored(reason), or skipped(reason), and every selected file carries its hunk list (the units of judgment and the publish anchors).
+
+**Step 2: Knowledge + plan — project rules, cohorts, walkthrough**
+
+1. STOP. Read `<skill-dir>/references/context-pack.md` and `<skill-dir>/references/taxonomy.md` in full before extracting rules or defining reviewer lanes. Run the bootstrap helper (reads the repo, writes only under `<out>`):
+
+   ```bash
+   python3 <skill-dir>/scripts/build_knowledge.py --out <out>
+   ```
+
+   Read every source left pending in `<out>/rules.template.json` in full, including direct references of selected project skills. Write `<out>/rules.json` with every source marked applied or not-applicable (reason required), then extract verdict-bearing rules verbatim with scope globs. Assemble `<out>/context-pack.md` and run/fold the detected linter lanes.
+2. Read `<skill-dir>/references/orchestration.md` (cohort rules, sweep triggers) and `<skill-dir>/references/output-contracts.md` (walkthrough anatomy, effort scale) in full. Write `<out>/plan.json` — cohorts of up to `<max-cohort-files>` files (default 100) / ~6,000 changed lines plus any sweep whose trigger fires — and `<out>/walkthrough.md`.
+3. Run the bootstrap plan gate (reads repo artifacts, writes only under `<out>`):
+
+   ```bash
+   python3 <skill-dir>/scripts/build_jobs.py --out <out> \
+     [--max-cohort-files N]
+   ```
+
+   It rejects incomplete source accounting and over-split plans, proves defect ownership, injects bound rules into every cohort and sweep, and materializes `<out>/jobs.json`. Test-adequacy and spec-parity proof remain Technical Verifier responsibilities.
+
+*Done when:* build_jobs.py exits 0, every discovered source has an audited decision in rules.json, context-pack.md lists applied source/rule and linter outcomes without copying the full registry, and walkthrough.md satisfies its contract.
+
+**Step 3: Fan-out — parallel review**
+
+Execute `<out>/jobs.json` with the mutating runner and engine contract loaded in Step 2. When `--subagent` is not `native`, read `<skill-dir>/references/subagent-runtimes.md` in full before execution. Completion is engine-independent — re-dispatch whatever is listed as pending/invalid until exit 0:
+
+```bash
+python3 <skill-dir>/scripts/run_jobs.py --out <out> --validate-only
+```
+
+*Done when:* run_jobs.py `--validate-only` exits 0 — every cohort and sweep output matches the schema and completely accounts for assigned hunks and rules. Execute materialized jobs with the bounded concurrency pinned in the manifest, keeping retries inside their worker slot; refill slots after completion, stop refilling after a provider block, and preserve manifest-order status.
+
+**Step 4: Merge + report**
+
+Run the bootstrap merger, mutating state/report renderer, and bootstrap HTML hydrator:
+
+```bash
+python3 <skill-dir>/scripts/merge_findings.py --out <out>
+python3 <skill-dir>/scripts/render_review.py --out <out> [--rework "<structural rationale>"]
+python3 <skill-dir>/scripts/render_html.py --out <out>
+```
+
+merge_findings.py emits `<out>/findings.json` plus `<out>/review-stats.json`, deduplicates both result classes, reconciles rounds, and fails unless every selected hunk line has defect coverage. render_review.py derives the verdict from defects only. render_html.py shows defects, advisories, suppressions, and coverage separately in `<out>/review.html`.
+
+When ReportFindings is available, report defects first and every advisory afterward. The user-facing summary states the verdict, defect/advisory counts, every Critical/Major defect, coverage status, and artifact paths.
+
+*Done when:* render_review.py and render_html.py exit 0 and the final message states the verdict, every Critical and Major defect, and the review.html path.
+
+**Step 5: Publish (only with `--publish`)**
+
+1. Read `<skill-dir>/references/publish-github.md` in full and execute its recipes: upsert the walkthrough, publish every anchorable in-diff defect and advisory inline, keep only unanchorable/outside-diff results in the body, and edit resolved prior-round comments.
+
+*Done when:* the PR shows the updated walkthrough and the new review, and both URLs are cited in the final message.
+
+**Step 6: Learnings**
+
+1. state.json was already written at Step 4. When the user — or a PR reply — rebuts or dismisses a result, read `<skill-dir>/references/state-and-learnings.md` in full, distill the correction into `.wtk-deep-review/learnings.md`, and mark that fingerprint `dismissed` in the state ledger.
+
+*Done when:* every user correction from the session is captured as a learning or explicitly declined.
+
+## Incremental rounds
+
+With prior state (or fingerprints recovered from the PR thread), Step 1 scopes to commits since the last reviewed head and archives the prior round's artifacts under `<out>/rounds/`. Step 2 emits one defect-lane remediation job whose prompt requires one evidence-bearing `prior_findings` disposition per open prior fingerprint; absence never resolves it. Unresolved prior results re-surface once under Duplicates; dismissed fingerprints stay suppressed; resolved ones receive the ✅ edit in publish mode. `--full` reviews the whole diff again. Each round's Step 4 regenerates `<out>/review.html`, so a browser tab left open on it tracks the rounds by itself.
+
+## Error handling
+
+- `--pr` or `--publish` without a passing `gh auth status` → stop and name the gap; publishing by any other transport is out of scope.
+- Workflow tool unavailable → automatic Agent fallback; record the mode in walkthrough.md's Review details.
+- External `--subagent` failure (model not available, missing/invalid output file, non-zero exit) → apply the failure handling loaded in Step 3.
+- Empty selection after the funnel → report "nothing reviewable" with the manifest counts; write no findings.
+- A linter lane unavailable → proceed and state in review.md that overlap suppression did not run for that lane.
+- A bootstrap gate failing (build_manifest.py, build_knowledge.py, build_jobs.py, merge_findings.py) → stop and surface stderr. Missing knowledge accounting or incomplete defect coverage is a review failure, not a warning.
+- run_jobs.py exit 2 (blocked) → a provider limit interrupted the fan-out; valid outputs are preserved and `<out>/run-blocker.json` lists the pending jobs — resume by re-running the same command once the limit clears. Providers that signal limits differently need extra `--block-on` patterns.
+- run_jobs.py exit 3 or a render_review freeze failure → the checkout drifted mid-round; findings would anchor to stale lines. Restart from Step 1 — the round increments and prior artifacts are archived.
+- More than 75 publishable results → use the Step 5 batching contract.
+
+## Bundled implementation
+
+`assets/PROMPT.md`, `assets/findings.schema.json`, and `assets/REVIEW_UI.html` are author-tooling sources consumed by the bundled scripts; agents use their rendered prompt/schema/report artifacts rather than loading these assets directly. `<skill-dir>/scripts/_common.py` is a read-only library imported by the CLIs and is never invoked directly.

package/.agents/skills/wtk-deep-review/assets/PROMPT.md

@@ -0,0 +1,56 @@
+# Deep-review prompt templates
+
+The single source of truth for every prompt the fan-out dispatches. `build_jobs.py` renders these blocks — edit wording here, nowhere else. Consistency is enforced twice at render time: the build fails if a template lost a mandatory `{{placeholder}}`, and fails again if any placeholder survives unfilled in a rendered prompt.
+
+Placeholders are `{{snake_case}}` tokens. Mandatory sets live in `build_jobs.py` (`REVIEWER_PLACEHOLDERS`, `SWEEP_PLACEHOLDERS`).
+
+<!-- template:reviewer -->
+Review cohort "{{cohort_name}}" (risk: {{risk}}) of {{target}}. Read-only: never modify product, test, docs, or generated source — your only write is the output file named in the OUTPUT CONTRACT.
+
+{{lane_instruction}}
+
+The unit of judgment is the HUNK; whole files are context.
+
+FILES — you own every listed hunk:
+{{file_list}}
+{{scope_instruction}}
+
+CONTEXT: read `{{context}}` (change intent, knowledge sources, linters, spec contract when present) and `{{taxonomy}}` (defect/advisory grammar and objective suppression rules) in full before judging.
+
+GRAFT CONTEXT: read `{{graft_context}}` for the prepared repository map, relevant symbols, and blast-radius orientation. Verify it against the checkout; use plain repository inspection for any fallback paths.
+
+REPO RULES bound to these files — when a result violates one, include its id in `rule_ids` and quote the rule verbatim in `guideline`:
+{{rules_block}}
+
+REVIEW:
+1. Read every cohort file in full — hunks lie without their surroundings. See each change with `{{diff_command}}`. For status A files the whole file is the new-side hunk. For status D read `git show {{base}}:<file>` and judge the old-side hunk plus surviving callers.
+2. INSPECT every owned hunk through the assigned lane. Check every bound repo rule explicitly. When one pattern repeats, search the cohort and enumerate occurrences under one result's `also_applies`.
+3. REFUTE candidates against the checkout. Defects require a named input/state and causal path; their first evidence entry is `Premise: <fact at file:line> → Path: <caller/input/control flow> → Verdict: <failure>`. Advisories require a concrete local benefit and fix; their first entry is `Premise: <fact at file:line> → Improvement: <specific benefit> → Fix: <bounded change>`. Later entries record `command or file:line → what it showed`.
+4. REPORT every survivor in the lane's result array. This review is always assertive: a small advisory survives when it is specific, actionable, and not owned by a formatter or a linter. Assign impact only after refutation. Set `hunk` on every in-diff result; outside-diff results set `in_diff` false and `hunk` null. Fill `suggestion` only with an exact, self-contained replacement.
+5. REPORT every investigated candidate dropped by an objective taxonomy rule in `suppressions`; never silently discard it. Then complete the exact hunk and rule accounting below. A clear hunk still needs a coverage row.
+
+{{prior_findings}}
+
+{{coverage_contract}}
+
+OUTPUT CONTRACT: write ONLY valid JSON matching this schema to `{{output}}` — no other file, nothing to stdout: `{{schema}}`
+Empty defect/advisory arrays are valid only with complete coverage. Validate the JSON before returning; the final response states only that the artifact was written.
+<!-- /template -->
+
+<!-- template:sweep -->
+Global sweep "{{sweep_key}}" over {{target}}: {{lens}}. Read-only: never modify product, test, docs, or generated source — your only write is the output file named in the OUTPUT CONTRACT.
+
+Read `{{context}}`, `{{manifest}}`, and `{{taxonomy}}` in full. Work from the manifest's selected files and hunks; read any repository file you need and see changes with `{{diff_command}}`.
+
+GRAFT CONTEXT: read `{{graft_context}}` for the prepared repository map, relevant symbols, and blast-radius orientation. Verify it against the checkout; use plain repository inspection for any fallback paths.
+
+REPO RULES applicable across the selected surface — account for every id:
+{{rules_block}}
+
+Find concrete cross-cohort hypotheses through this lens, enumerate every occurrence, then refute each with repository evidence. Put causal failures in `defects` with `Premise → Path → Verdict`; put measurable structural or convention improvements in `advisories` with `Premise → Improvement → Fix`. Record investigated candidates rejected by an objective taxonomy rule in `suppressions`. Cross-cohort results are the point of this sweep — cohort lanes own single-cohort results; a result inside cohort-owned hunks is rejected unless its `also_applies` names anchors in at least two other files.
+
+{{coverage_contract}}
+
+OUTPUT CONTRACT: write ONLY valid JSON matching this schema to `{{output}}` — no other file, nothing to stdout: `{{schema}}`
+Empty result arrays are valid only after the full lens and rule accounting. Validate the JSON before returning; the final response states only that the artifact was written.
+<!-- /template -->