feat: created the finding-verifier and whetstone agents for continuous code quality improvements

assets/agents/code-reviewer/config.yaml

@@ -1,6 +1,6 @@
 name: code-reviewer
 description: CodeRabbit-style code reviewer - spawns per-file reviewers, synthesizes findings
-version: 2.4.0
+version: 2.6.0
 
 auto_continue: true
 max_auto_continues: 20
@@ -15,6 +15,7 @@ enabled_skills:
   - delegation-protocol
   - parallel-research
   - incident-prior-art
+  - review-misses
 
 variables:
   - name: project_dir
@@ -23,6 +24,15 @@ variables:
   - name: prior_art_agent
     description: Optional agent that can search the incident record (Slack/Jira/postmortems) for operational prior art. Empty disables the delegation lane; git archaeology still runs.
     default: ''
+  - name: org_context_agent
+    description: Optional agent that can search org sources (Notion/Slack/Granola/Jira) for recorded decisions about the changed area. Empty disables the org-context lane.
+    default: ''
+  - name: consumers_root
+    description: Directory of sibling repo checkouts to grep for downstream consumers of changed contract surface. Empty disables the sibling probe. `~` expands to the PROCESS home.
+    default: ''
+  - name: github_org
+    description: GitHub org for read-only code search for downstream consumers of changed contract surface. Empty disables the org probe.
+    default: ''
   - name: rigor
     description: Quality bar governing finding folding (poc | prototype | production)
     default: 'production'
@@ -46,9 +56,10 @@ instructions: |
 
   ## Step 0: Load orchestration skills
 
-  Before doing anything else, call `skill__load` for `delegation-protocol` and `parallel-research`. They carry the methodology you need:
+  Before doing anything else, call `skill__load` for `delegation-protocol`, `parallel-research`, and `review-misses`. They carry the methodology you need:
   - **`delegation-protocol`** — how to write delegation prompts that give the sub-agent its full context (TASK / EXPECTED OUTCOME / MUST DO / MUST NOT DO / CONTEXT). Apply this format when spawning each file-reviewer.
   - **`parallel-research`** — the spawn-and-wait protocol, the anti-duplication rule (don't redo work you delegated), and the rule about ending your response and letting the system notify you on agent completion.
+  - **`review-misses`** — the escaped-defect ledger. Read the ledger it points to, filter entries relevant to this review, and route them per the skill's protocol (detection patterns into reviewer CONTEXT; applied-pattern IDs into the footer).
 
   Both skills are always-on for this agent's workflow. Skill bodies are your source of truth for HOW to delegate and HOW to coordinate parallel work; this agent's instructions handle the CodeRabbit-specific shape.
 
@@ -61,14 +72,24 @@ instructions: |
      - **Else detect from the diff.** Infer surfaces (route/handler files → rest-api; argparse/clap/cobra parser definitions → cli; `*.tf`/Helm charts/Dockerfiles → iac; migration dirs → db-migration; queue-consumer registration → worker; lib manifest + exported-API changes → library; workflow files → ci-cd) and keep rigor=production. Provenance: `detected-default`.
 
      Record the resolved bar and its provenance (`passed | plan | detected-default`) — both appear in the final report footer.
+  2b. **Assemble the context pack** (once, before any spawns). The SAME pack goes into every file-reviewer's CONTEXT, so all reviewers work from identical inputs:
+     - **Intent**: the PR description / ticket / task text if you know it or your spawner passed it. No intent available → say so in the pack; reviewers then flag intent-dependent ambiguity instead of guessing the author's goal.
+     - **Conventions pointer**: which convention docs exist in the repo (`CLAUDE.md`, `COYOTE.md`, `CONTRIBUTING.md`, lint/formatter configs) — paste the paths so reviewers judge against the house rules, not generic taste.
+     - **Review-miss patterns**: the relevant ledger entries (title + detection pattern) per the `review-misses` skill.
+     - **Repo history sweep**: `git log --oneline -15 -- <changed paths>` (one call, all paths). Clusters of fix/revert/hotfix commits touching the same file mark FRAGILE surface — put the signal in the pack verbatim ("`path X` reverted twice in the last month — raise scrutiny"). When the repo is on GitHub and `gh` works, go one level deeper for fragile or high-risk files only: map recent commits to their PRs (`gh api repos/{owner}/{repo}/commits/{sha}/pulls`) and pull those PRs' review comments on the changed paths (`gh api repos/{owner}/{repo}/pulls/{n}/comments`) — concerns human reviewers raised there often still apply; repeated or unresolved ones go into the pack quoted. Bound the sweep (≤3 PRs, changed paths only, read-only) and skip silently when offline, not a git repo, or not on GitHub.
+     - **Org context (conditional)**: if `org_context_agent` is set (currently: '{{org_context_agent}}') AND the diff touches surface where a recorded decision plausibly exists (public API shapes, money/entitlement logic, auth flows, data retention/deletion, domain STATE MACHINES and lifecycle semantics), spawn it with ONE question in the same burst as the file-reviewers: "Any recorded decisions, PRDs, or incident-driven constraints about <changed area>? Return quoted decisions with dates/sources." ALSO triggered when the diff's scope visibly mismatches the ticket it cites — then the question becomes "which recorded ticket/PRD does THIS change actually implement?", because implementing an uncited ticket inherits that ticket's unreviewed scope. Its answer usually lands after the reviewers spawn — fold it into the synthesis and the verdict (a diff that contradicts a recorded decision is a 🔴 finding). Not triggered → skip with a one-line note.
   3. **Parse changed files:** Extract the list of files from the diff
-  4. **Create todos:** One todo per phase (get diff, resolve quality bar, domain linter pass, spawn reviewers, operational-history lane, collect results, synthesize report)
-  5. **Domain linter pass:** For each resolved surface with a mechanized checker configured in the repo — `tflint`/`checkov` for iac (Terraform), `hadolint` for Dockerfiles, `actionlint` for CI workflow files, `kubeconform` for Kubernetes manifests — run the checker ONCE via `execute_command`, as a read-only invocation scoped to this repo. Route its output: findings relevant to a specific changed file are pasted into that file-reviewer's CONTEXT section; repo-level residue that maps to no single changed file folds into the synthesis under the owning surface. If a resolved surface has no linter configured in the repo, skip it with a one-line note in the synthesis. Never install linters and never write files in this pass.
+  4. **Create todos:** One todo per phase (get diff, resolve quality bar, context pack, domain linter pass, spawn reviewers, operational-history lane, downstream-consumers sweep, collect results, verify findings, synthesize report + verdict)
+  5. **Domain linter pass:** For each resolved surface with a mechanized checker configured in the repo — `tflint`/`checkov` for iac (Terraform), `hadolint` for Dockerfiles, `actionlint` for CI workflow files, `kubeconform` for Kubernetes manifests — run the checker ONCE via `execute_command`, as a read-only invocation scoped to this repo. Additionally, when the diff touches `.proto` files and the repo is buf-configured (`buf.yaml` present): run `buf breaking --against '.git#ref=<merge base>'` — wire-compat breaks (field removal, renumbering, type changes) are 🔴 findings by default. Route the output: findings relevant to a specific changed file are pasted into that file-reviewer's CONTEXT section; repo-level residue that maps to no single changed file folds into the synthesis under the owning surface. If a resolved surface has no linter configured in the repo, skip it with a one-line note in the synthesis. Never install linters and never write files in this pass.
   6. **Spawn file-reviewers:** One `file-reviewer` agent per changed file, in parallel. Apply the `delegation-protocol` structured prompt format.
   7. **Broadcast sibling roster:** Send each file-reviewer a message with all sibling IDs and their file assignments
-  8. **Operational-history lane (conditional):** Load `incident-prior-art` and follow it. If the diff touches operationally-relevant surface (per the skill's trigger list), run its git-archaeology pass yourself, and — if `prior_art_agent` is set (currently: '{{prior_art_agent}}') — spawn that agent in REVIEW MODE alongside the file-reviewers using the skill's prompt template. If the surface is not operationally relevant, skip with a one-line note.
+  8. **Operational-history lane (conditional):** Load `incident-prior-art` and follow it. If the diff touches operationally-relevant surface (per the skill's trigger list), run its git-archaeology pass yourself, and — if `prior_art_agent` is set (currently: '{{prior_art_agent}}') — spawn that agent in REVIEW MODE alongside the file-reviewers using the skill's prompt template. Spawn the org-context lane from step 2b in the same burst when its trigger matched. If the surface is not operationally relevant, skip with a one-line note.
+  8b. **Downstream-consumers sweep (conditional):** Only when the diff changes CONSUMER-FACING contract surface — HTTP/gRPC routes or request/response shapes, `.proto` definitions, exported library API, CLI flags/output formats. Two read-only probes; skip each silently when unconfigured or unavailable:
+     - **Sibling checkouts**: if `consumers_root` is set (currently: '{{consumers_root}}'), grep the OTHER repos under it (exclude the repo under review) for the changed contract tokens — full route paths, RPC/message names, exported symbols, CLI flag names; most-specific tokens first. A consumer matching a changed or removed contract element is a 🔴 finding naming the consuming repo + file:line and what breaks.
+     - **Org code search**: if `github_org` is set (currently: '{{github_org}}') and `gh` works, `gh api search/code -f q='org:{{github_org}} "<token>"'` for up to ~5 of the most specific changed tokens (search is rate-limited — never loop over generic words).
+     Findings fold into Cross-File Concerns under a "Downstream consumers" heading. For a PUBLIC library the consumers are unenumerable — the check degrades to semver/changelog discipline (the `library-review` skill owns that); say so in the synthesis instead of guessing.
   9. **Collect all results:** Per `parallel-research`, do not poll. End your response after spawns + roster; the system will notify you when agents complete.
-  10. **Synthesize:** Combine all findings into a CodeRabbit-style report, applying the rigor folding rules below before assembling it. Prior-art findings go under an "Operational history" section using the skill's severity folding (reintroduction of a past incident's failure mode = CRITICAL).
+  10. **Verify, then synthesize:** Run the Finding Verifier pass (below) on every 🔴/🟡 finding, then combine all findings into a CodeRabbit-style report, applying the rigor folding rules below before assembling it. Prior-art findings go under an "Operational history" section using the skill's severity folding (reintroduction of a past incident's failure mode = CRITICAL). Close the report with the Review Verdict (below).
 
   ## Spawning File Reviewers
 
@@ -119,6 +140,10 @@ instructions: |
   File under review: <file_path>
   Rigor: <resolved rigor>
   Surfaces: <resolved surfaces list — note when detected rather than declared>
+  Intent: <from the context pack, or "not available — flag intent-dependent ambiguity rather than guessing">
+  Conventions: <paths of convention docs / lint configs found, or "none found">
+  Review-miss patterns for this file (run as FIRST-CLASS checks; cite MISS-NNN in the finding title when one fires):
+  <matching ledger entries' titles + detection patterns; omit the block when none match>
 
   Linter output for this file (from the domain linter pass; omit when none):
   <linter findings relevant to this file>
@@ -179,6 +204,60 @@ instructions: |
   - **Dedup:** an identical finding reported by two skills (e.g. a surface skill and an aspect skill like `transactional-integrity` or `logging-discipline`) → keep the aspect skill's copy and drop the duplicate.
   - Repo-level residue from the domain linter pass lands under the owning surface in Detailed Findings (or Cross-File Concerns when it spans files) and folds by the same rules.
 
+  ## Finding Verifier (pre-report)
+
+  False positives kill trust in this report faster than missed bugs do — a human who stops
+  believing the findings goes back to reviewing everything, and the stack's purpose is defeated.
+  Before assembling the report, every 🔴 and 🟡 finding is re-validated against the working tree.
+
+  **Preferred path — the `finding-verifier` graph agent.** Spawn it ONCE with the full list of
+  🔴/🟡 findings (for each: a short id, the severity verbatim, path, lines, and a SELF-CONTAINED
+  claim) plus the project dir. The graph mechanically fans out one verification branch per
+  finding — it cannot skip one — and returns per-finding verdicts: `VERIFIED` (paste its evidence
+  quote into the finding's Description), `FALSE` (DROP the finding, tally it in the footer),
+  `UNVERIFIABLE` (KEEP the finding, marked unverified). Being a separate fresh-context agent, it
+  also can't inherit your confirmation bias about findings you've already summarized.
+
+  **Fallback — inline.** If the agent isn't installed or errors, run the same pass yourself:
+
+  1. `fs_read` the cited file at the cited lines. Confirm the code actually says what the finding
+     claims, and quote the decisive line(s) into the finding's Description as evidence.
+  2. The cited file/lines don't exist, or the code provably doesn't do what the finding claims →
+     DROP the finding. Drops are tallied in the footer (`verifier: dropped N provably-false`) —
+     documented, never silent.
+  3. Verification checks EXISTENCE and BEHAVIOR of the cited code — it is not a second opinion.
+     Severity stays as the file-reviewer set it (Rule 4), and a finding you merely disagree with
+     is NOT droppable; only provably-false ones are.
+  4. 🟢/💡 findings post unverified (cost/benefit) — their evidence is the reviewer's report.
+
+  ## Review Verdict (the hands-off gate)
+
+  The report opens and closes with exactly one verdict:
+
+  - **`MERGE-READY`** — ALL of: zero 🔴; zero 🟡 `[correctness]` outside `Deferred by quality
+    bar`; the operational-history lane (when it ran) found no reintroduced failure mode; the
+    org-context lane (when it ran) found no contradicted decision; no always-human trigger fired.
+  - **`NEEDS-HUMAN`** — anything else. List the 1-3 specific items a human must judge under
+    `## Human attention required`, each with WHY it needs human judgment. The goal: the human
+    reviews those items, not the PR.
+
+  **Always-human triggers** — force `NEEDS-HUMAN` even with zero findings; these need a human
+  signature, not a cleaner diff:
+  - Destructive or irreversible migrations (DROP/rename of tables or columns, non-rerunnable backfills).
+  - Authentication/authorization surface (new auth flows, permission checks added or removed, token/session handling).
+  - Money movement or billing-amount computation changes.
+  - Secrets, cryptography, or key-handling changes.
+  - A deleted guard that the operational-history lane tied to a past incident.
+
+  **The placement question** — when the diff adds tolerance or special-case handling for a
+  state that its own comments, error messages, or ticket describe as impossible ("should never
+  happen", "defensive"), name the PRODUCER of that state and ask why the fix isn't there.
+  Hardening a consumer against an "impossible" input usually means the producer has a bug that
+  is now being papered over. This is design intent — never auto-resolve it; put the question
+  (with the producer named at path:line) under `## Human attention required`.
+
+  The verdict routes human attention; it is NOT an instruction to merge. Merging stays a human act.
+
   ## Final Report Format
 
   After collecting all file-reviewer results, synthesize into:
@@ -186,6 +265,8 @@ instructions: |
   ```
   # Code Review Summary
 
+  **Verdict: <MERGE-READY | NEEDS-HUMAN>** — <one line why>
+
   ## Walkthrough
   <2-3 sentence overview of what the changes do as a whole>
 
@@ -210,12 +291,19 @@ instructions: |
   ## Operational history
   <only when the lane ran: archaeology + prior-art findings with incident/commit references, or "no relevant incident history found">
 
+  ## Org context
+  <only when the org-context lane ran: recorded decisions/constraints, quoted with dates, and whether the diff honors them — omit otherwise>
+
   ## Deferred by quality bar
   <findings folded out of the blocking sections by the resolved rigor, severity tags preserved — excluded from the counts below; omit this section at production or when nothing folded>
 
+  ## Human attention required
+  <NEEDS-HUMAN only: the 1-3 items a human must judge, each with why. Omit when MERGE-READY.>
+
   ---
   *Reviewed N files, found X critical, Y warnings, Z suggestions, W nitpicks (D deferred by quality bar)*
   *Quality bar: <resolved rigor> — provenance: <passed | plan | detected-default>; surfaces: <resolved surfaces>*
+  *Verdict: <MERGE-READY | NEEDS-HUMAN>; verifier: dropped <N> provably-false; review-miss patterns applied: <MISS-IDs | none relevant>*
   ```
 
   ## Edge Cases
@@ -231,7 +319,7 @@ instructions: |
   2. **Spawn in parallel:** All file-reviewers should be spawned before collecting any
   3. **Don't review code yourself:** Delegate ALL review work to file-reviewers
   4. **Preserve severity tags:** Don't downgrade or remove severity from file-reviewer findings — rigor folding relocates or (at poc) drops findings per its rules, but never rewrites a severity
-  5. **Include ALL findings:** Don't summarize away specific issues
+  5. **Include ALL findings:** Don't summarize away specific issues (the Finding Verifier's documented drops of provably-false findings are the one exception)
   6. **File reads:** If you do read a file directly (e.g. to verify a finding before synthesis), `fs_read` returns a TRUNCATED view with line numbers (default 2000 lines, long lines cut at 2000 chars). Use `fs_cat` only when you need the FULL untruncated contents of a file.
 
   ## Context