@r1z4x/tezgah 1.0.0

package/statusline.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Status line segment for every host that supports one.
+
+  python3 statusline.py            # Claude Code (or any Claude-format status line)
+  python3 statusline.py --cursor   # Cursor CLI (same stdin shape, no Orca passthrough)
+
+Claude Code's statusLine pipes session JSON on stdin; Cursor's spec is aligned
+with it. This wraps Orca's own status line for Claude, then appends the tezgah
+checklist from hooks/tezgah_context.health_lines - the single source every host
+renders - so the segment is identical on Claude, Cursor, Codex and opencode.
+Used-tool marks come from the Claude transcript on Claude, and from tezgah's own
+recorder (written by the Codex/Cursor/dsh/opencode adapters) elsewhere.
+"""
+import glob
+import json
+import os
+import subprocess
+import sys
+
+# installed as a ~/.claude/statusline.py (or ~/.cursor) symlink, so resolve the
+# real file to find the plugin it ships with before importing the shared core
+sys.path.insert(0, os.path.join(
+    os.path.dirname(os.path.realpath(__file__)), "hooks"))
+from tezgah_guard import import_failed  # noqa: E402
+try:
+    from tezgah_context import (GRAPH_TOOL_MARK, LEGEND,  # noqa: E402
+                                TOOL_USE_MEASURES, color_default,
+                                health_segments, render_line, shell_kind,
+                                skill_read_kind, used as used_kinds)
+except Exception as exc:
+    # the status line is the one surface the user always sees: say the core is
+    # down there, rather than drawing nothing
+    print("tezgah \u2717 core import failed (%s)" % type(exc).__name__)
+    import_failed(exc)
+
+HOME = os.path.expanduser("~")
+ORCA = os.path.join(HOME, ".orca", "agent-hooks", "claude-statusline.sh")
+HOST = "cursor" if ("--cursor" in sys.argv or
+                    os.environ.get("TEZGAH_STATUS_HOST") == "cursor") else "claude"
+
+data = sys.stdin.read()
+try:
+    payload = json.loads(data or "{}")
+except Exception:
+    payload = {}
+
+orca_out = ""
+if HOST == "claude" and os.access(ORCA, os.X_OK):
+    try:
+        orca_out = subprocess.run(
+            ["/bin/sh", ORCA], input=data, capture_output=True,
+            text=True, timeout=5,
+        ).stdout.strip()
+    except Exception:
+        orca_out = ""
+
+cwd = ((payload.get("workspace") or {}).get("current_dir")
+       or payload.get("cwd") or "")
+try:
+    real = os.path.realpath(cwd) if cwd else ""
+except OSError:
+    real = ""
+
+
+def claude_used():
+    """Tool kinds used this session, parsed from the Claude transcript.
+
+    A substring scan would flag the tool NAME appearing in chat text, so parse
+    tool_use blocks; subagent transcripts are included so delegated graph/consult
+    use still counts.
+    """
+    used = set()
+    tp = payload.get("transcript_path")
+    files = [tp] if tp and os.path.exists(tp) else []
+    if tp:
+        files += glob.glob(os.path.splitext(tp)[0] + "/subagents/**/*.jsonl",
+                           recursive=True)
+    lines = []
+    for fp in files:
+        try:
+            size = os.path.getsize(fp)
+            with open(fp, encoding="utf-8", errors="ignore") as fh:
+                if size > 2_000_000:
+                    fh.seek(size - 2_000_000)
+                lines += fh.read().splitlines()
+        except OSError:
+            pass
+    for line in lines:
+        try:
+            content = (json.loads(line).get("message") or {}).get("content")
+        except Exception:
+            continue  # partial first line after seek, or non-message row
+        if not isinstance(content, list):
+            continue
+        for b in content:
+            if not isinstance(b, dict) or b.get("type") != "tool_use":
+                continue
+            name = b.get("name", "")
+            read_kind = skill_read_kind(name, b.get("input"))
+            if read_kind:
+                used.add(read_kind)
+            elif name.startswith("mcp__") and GRAPH_TOOL_MARK in name.lower():
+                used.add("graph")
+            elif name in ("Task", "Agent"):
+                used.add("orch")
+            elif name == "Bash":
+                # The shared tokenizer, not a substring: the same call the other
+                # hosts make, so an `orx` run marks `research` and a command that
+                # merely mentions the word does not mark anything.
+                kind = shell_kind((b.get("input") or {}).get("command"))
+                if kind:
+                    used.add(kind)
+    return used
+
+
+seen = used_kinds(payload.get("session_id")) if HOST == "cursor" else claude_used()
+# Cursor's line reads tezgah's store, which sees the tool calls its hook fires on
+# and nothing else; Claude's transcript carries the skill reads too.
+observable = TOOL_USE_MEASURES if HOST == "cursor" else None
+segs = health_segments(real or os.getcwd(), payload.get("session_id"),
+                       used_override=seen, observable=observable)
+# Claude Code and Cursor render ANSI; let a user or a plain terminal opt out.
+color = color_default()
+seg = render_line(segs, color=color)
+parts = [p for p in (orca_out, seg) if p]
+out = "  |  ".join(parts)
+if os.environ.get("TEZGAH_STATUS_LEGEND") == "1":
+    out += "\n" + LEGEND.rstrip()
+print(out)

package/workflows/graph-impact.js

@@ -0,0 +1,153 @@
+export const meta = {
+  name: 'graph-impact',
+  description: 'Blast radius of a change: pull every caller from the codegraph index, plan the edit per module, then have a critic hunt for missed call sites.',
+  whenToUse: 'Renaming or changing a shared symbol, migrating an API, deleting suspected dead code - anything where "did I get all the call sites" is the real question.',
+  phases: [
+    { title: 'Trace', detail: 'codegraph callers of the target, grouped by module' },
+    { title: 'Plan', detail: 'one planner per affected module' },
+    { title: 'Sweep', detail: 'critic hunts call sites the graph missed' },
+  ],
+}
+
+const target = (typeof args === 'string' && args) ? args : (args && args.target) || ''
+if (!target) return { error: 'graph-impact needs a target: pass a symbol, file, or git ref as args' }
+const direction = (args && args.direction) || 'inbound'
+const MAX_MODULES = 6
+
+const GRAPH = `On Claude the MCP server exposes one tool by default: load it with
+ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore")
+before the first query (a plugin install uses the plugin_tezgah_ name). The rest of the surface is the CLI:
+\`codegraph callers <symbol>\` walks inbound call paths, \`codegraph callees <symbol>\` outbound,
+\`codegraph impact <symbol>\` gives a symbol's blast radius - for a git ref, run it per changed symbol of
+\`git diff <ref>\` - \`git diff --name-only <ref> | codegraph affected --stdin\` names the test files the
+changed files reach, \`codegraph node <symbol>\` pulls a definition with its body, \`codegraph query <text>\` finds symbols,
+\`codegraph files\` dumps what the index holds. The index is the repo's own \`.codegraph/codegraph.db\`.
+codegraph ships no coverage report, so what the index does NOT know about is measured by diffing
+\`codegraph files\` against \`git ls-files\`.`
+
+
+const TRACE = {
+  type: 'object',
+  required: ['resolved_target', 'call_sites'],
+  properties: {
+    resolved_target: { type: 'string', description: 'the symbol(s) the target actually resolves to, with file:line' },
+    kind: { type: 'string', description: 'function, method, type, route, config key, ...' },
+    call_sites: { type: 'array', items: {
+      type: 'object',
+      required: ['module', 'file', 'symbol'],
+      properties: {
+        module: { type: 'string' },
+        file: { type: 'string' },
+        line: { type: 'integer' },
+        symbol: { type: 'string', description: 'the calling symbol' },
+        hops: { type: 'integer', description: 'distance from the target' },
+      },
+    } },
+    unindexed_risk: { type: 'string', description: 'from codegraph files vs git ls-files: what the index cannot see' },
+  },
+}
+
+const PLAN = {
+  type: 'object',
+  required: ['module', 'edits'],
+  properties: {
+    module: { type: 'string' },
+    edits: { type: 'array', items: {
+      type: 'object',
+      required: ['file', 'what', 'why'],
+      properties: {
+        file: { type: 'string' },
+        line: { type: 'integer' },
+        what: { type: 'string', description: 'the concrete edit' },
+        why: { type: 'string' },
+        breaks_if_skipped: { type: 'string' },
+      },
+    } },
+    order_note: { type: 'string', description: 'must this module change before or after others' },
+    tests_to_run: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+phase('Trace')
+const trace = await agent(
+  `Find every place affected by changing: ${target}
+${GRAPH}
+Resolve what the target actually is with \`codegraph query\` / \`codegraph node\`, then walk callers with
+\`codegraph ${direction === 'outbound' ? 'callees' : 'callers'}\` (and, when the target is a git ref,
+\`codegraph impact\` per changed symbol of \`git diff <ref>\`) until the frontier stops growing. Group call sites by module. Then diff \`codegraph files\`
+against \`git ls-files\` and state plainly what the graph cannot see - unindexed files, generated code,
+dynamic dispatch, string-keyed lookups, config and templates that reference the symbol by name, and the
+extensionless scripts under \`bin/\` that only their \`.py\` twin puts in the graph. Do not plan any edit yet.`,
+  { label: 'trace', schema: TRACE, effort: 'high' },
+)
+
+if (!trace) return { error: 'the trace agent failed - nothing was traced; unknown, not clean', target, unknown: ['trace'] }
+if (!trace.call_sites) return { error: 'trace returned no call-site list - is the repo indexed? run `codegraph init` first', target, unknown: ['trace'] }
+if (!trace.call_sites.length) {
+  return { target, resolved_target: trace.resolved_target, call_sites: [], modules_skipped: [], graph_blind_spots: [], note: 'no callers in the graph - possible dead code, but confirm against unindexed_risk: ' + (trace.unindexed_risk || 'n/a') }
+}
+
+const byModule = {}
+for (const cs of trace.call_sites) (byModule[cs.module] = byModule[cs.module] || []).push(cs)
+const modules = Object.keys(byModule).sort((a, b) => byModule[b].length - byModule[a].length)
+const picked = modules.slice(0, MAX_MODULES)
+if (modules.length > picked.length) {
+  log(`${trace.call_sites.length} call sites across ${modules.length} modules; planning the ${picked.length} heaviest. NOT planned: ${modules.slice(MAX_MODULES).join(', ')}`)
+}
+log(`target resolves to: ${trace.resolved_target}`)
+
+phase('Plan')
+const plansPending = parallel(picked.map(m => () => agent(
+  `Plan the edits inside module "${m}" for this change: ${target}
+Target resolves to: ${trace.resolved_target} (${trace.kind || 'unknown kind'})
+Call sites in your module: ${JSON.stringify(byModule[m])}
+${GRAPH}
+Read the actual lines before proposing an edit. For each call site say the concrete edit, why, and what
+breaks if it is skipped. Flag ordering constraints against other modules. Name the tests that cover it.
+Do not edit anything - plan only.`,
+  { label: `plan:${m}`, phase: 'Plan', schema: PLAN, effort: 'high' },
+)))
+
+// the sweep prompt reads only the trace, so it starts now instead of waiting
+// out the slowest planner
+phase('Sweep')
+const sweepPending = agent(
+  `A graph-based trace found these call sites for "${target}" (resolved: ${trace.resolved_target}):
+${JSON.stringify(trace.call_sites)}
+The graph itself warned: ${trace.unindexed_risk || 'nothing'}
+
+Your job: find the call sites it MISSED. The graph is blind to string-keyed dispatch, reflection, generated
+code, config files, templates, docs, SQL, CI definitions, and anything in unindexed files. Hunt with Grep and
+Glob across the repo - including non-source files - for the symbol name and its plausible spellings
+(snake_case, kebab-case, quoted string, partial match). Report only hits absent from the list above.`,
+  { label: 'sweep', schema: {
+    type: 'object',
+    required: ['missed'],
+    properties: {
+      missed: { type: 'array', items: { type: 'object', required: ['file', 'why_it_matters'], properties: {
+        file: { type: 'string' }, line: { type: 'integer' }, snippet: { type: 'string' }, why_it_matters: { type: 'string' },
+      } } },
+      searched: { type: 'string', description: 'the patterns and paths actually searched' },
+    },
+  }, effort: 'high' },
+)
+
+const planned = await plansPending
+const sweep = await sweepPending
+// a failed planner or sweep is unknown: its module is unplanned, its blind spots unsearched
+const unknown = picked.filter((m, i) => !planned[i]).map(m => `plan:${m}`).concat(sweep ? [] : ['sweep'])
+const plans = planned.filter(Boolean)
+if (unknown.length) log(`failed, reported as unknown: ${unknown.join(', ')}`)
+
+return {
+  target,
+  resolved_target: trace.resolved_target,
+  call_site_count: trace.call_sites.length,
+  modules_planned: picked,
+  modules_skipped: modules.slice(MAX_MODULES),
+  plans,
+  graph_blind_spots: sweep ? (sweep.missed || []) : 'unknown - the sweep agent failed',
+  sweep_coverage: sweep ? sweep.searched : 'none - the sweep agent failed',
+  unindexed_risk: trace.unindexed_risk,
+  unknown,
+}

package/workflows/graph-map.js

@@ -0,0 +1,158 @@
+export const meta = {
+  name: 'graph-map',
+  description: 'Map a subsystem off the codegraph index: survey, one reader per module, synthesize, then gap-check.',
+  whenToUse: 'Before changing unfamiliar code, or when asked how a subsystem works / where things live / for an architecture map.',
+  phases: [
+    { title: 'Survey', detail: 'codegraph status + module inventory from the index' },
+    { title: 'Read', detail: 'one reader agent per module, in parallel' },
+    { title: 'Synthesize', detail: 'merge into one map' },
+    { title: 'Gap check', detail: 'critic names what the map still misses' },
+  ],
+}
+
+const focus = (typeof args === 'string' && args) ? args : (args && args.focus) || 'the whole repository'
+const MAX_MODULES = 8
+
+const GRAPH = `Use codegraph, not grep, for structure. On Claude the MCP server exposes one tool by
+default: load it with ToolSearch("select:mcp__codegraph__codegraph_explore") before the first query.
+The rest of the surface is the CLI, which is also what every other host uses:
+\`codegraph status\`, \`codegraph files\`, \`codegraph node <symbol>\`, \`codegraph callers <symbol>\`,
+\`codegraph callees <symbol>\`, \`codegraph impact <target>\`, \`codegraph query <text>\`. The index is the
+repo's own \`.codegraph/codegraph.db\`. Fall back to Read/Grep only for something the graph genuinely
+cannot answer, and say so when you do.`
+
+const SURVEY = {
+  type: 'object',
+  required: ['modules'],
+  properties: {
+    modules: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['name', 'path', 'why'],
+        properties: {
+          name: { type: 'string' },
+          path: { type: 'string' },
+          why: { type: 'string', description: 'why this module matters to the focus' },
+          rank: { type: 'integer', description: '1 = most central to the focus' },
+        },
+      },
+    },
+    entrypoints: { type: 'array', items: { type: 'string' } },
+    stack: { type: 'string', description: 'languages, frameworks, storage, transport' },
+  },
+}
+
+const READING = {
+  type: 'object',
+  required: ['module', 'responsibility', 'key_symbols'],
+  properties: {
+    module: { type: 'string' },
+    responsibility: { type: 'string' },
+    key_symbols: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['symbol', 'file', 'role'],
+        properties: {
+          symbol: { type: 'string' },
+          file: { type: 'string' },
+          line: { type: 'integer' },
+          role: { type: 'string' },
+        },
+      },
+    },
+    collaborators: { type: 'array', items: { type: 'string' }, description: 'modules it calls or is called by, from codegraph callers/callees' },
+    data_flow: { type: 'string' },
+    risks: { type: 'array', items: { type: 'string' }, description: 'coupling, dead code, missing tests - graph-evidenced only' },
+  },
+}
+
+phase('Survey')
+const survey = await agent(
+  `Survey this repository so other agents can split it up. Focus: ${focus}.
+${GRAPH}
+Start with \`codegraph status\` and \`codegraph files\`. Return the modules that matter for the
+focus, ranked, with the real directory path for each. Do not read file bodies - stay at graph level.`,
+  { label: 'survey', schema: SURVEY, effort: 'medium' },
+)
+
+if (!survey || !survey.modules || !survey.modules.length) {
+  return { error: 'survey returned no modules - is the repo indexed? run `codegraph init` in it first' }
+}
+
+const ranked = survey.modules.slice().sort((a, b) => (a.rank || 99) - (b.rank || 99))
+const picked = ranked.slice(0, MAX_MODULES)
+if (ranked.length > picked.length) {
+  log(`${ranked.length} modules found, reading top ${picked.length}: dropped ${ranked.slice(MAX_MODULES).map(m => m.name).join(', ')}`)
+}
+
+phase('Read')
+const readings = (await parallel(picked.map(m => () => agent(
+  `Read module "${m.name}" at ${m.path}. It matters because: ${m.why}. Overall focus: ${focus}.
+${GRAPH}
+Answer: what it is responsible for, its key symbols with file and line, which other modules call it or
+it calls (use \`codegraph callers\` and \`codegraph callees\` both directions), how data moves through it,
+and any graph-evidenced risk (dead code, a symbol with many inbound callers, missing test coverage).
+Cite file:line for every claim.`,
+  { label: `read:${m.name}`, phase: 'Read', schema: READING },
+)))).filter(Boolean)
+
+log(`${readings.length}/${picked.length} modules read`)
+
+phase('Synthesize')
+const map = await agent(
+  `Write one coherent map of this codebase for focus "${focus}".
+Stack: ${survey.stack || 'unknown'}. Entrypoints: ${(survey.entrypoints || []).join(', ') || 'unknown'}.
+Per-module readings (JSON):
+${JSON.stringify(readings)}
+
+Produce markdown: a one-paragraph orientation, a module table (module - responsibility - key entry symbol as
+\`file:line\`), the request/data path end to end naming the symbol at each hop as \`file:line\`, then "Sharp
+edges" where every bullet ends in the \`file:line\` it refers to. Every file:line comes from the readings -
+copy them, never reconstruct or guess one. Do not invent anything absent from the readings. If the readings
+carry no code symbols (a docs-only or config-only repo), say so in one line at the top instead of dressing
+document headings up as code.`,
+  { label: 'synthesize', effort: 'high' },
+)
+
+if (!map) {
+  return { focus, modules_read: readings.map(r => r.module),
+           modules_dropped: ranked.slice(MAX_MODULES).map(m => m.name),
+           map: null, gaps: [], error: 'the synthesize agent returned nothing' }
+}
+
+phase('Gap check')
+const gaps = await agent(
+  `Here is a codebase map produced from graph-derived module readings. Focus was "${focus}".
+
+${map}
+
+Your job is to find what it MISSES, not to praise it. Verify against the graph yourself.
+${GRAPH}
+Name concretely: a module in the repo absent from the map, a claimed call path that \`codegraph callers\`
+does not support, an entrypoint never traced, a file:line citation that does not resolve. codegraph ships
+no coverage report of its own, so measure it: diff \`codegraph files\` against \`git ls-files\` and name the
+files the index does not hold - an extensionless script under \`bin/\` is in the graph only through its
+\`.py\` twin, and dot-directories are skipped unless a \`.gitignore\` negation opts them in. Return a short
+list; empty list if genuinely clean.`,
+  { label: 'gap-check', schema: {
+    type: 'object',
+    required: ['gaps'],
+    properties: {
+      gaps: { type: 'array', items: { type: 'object', required: ['gap', 'evidence'], properties: {
+        gap: { type: 'string' }, evidence: { type: 'string' }, severity: { type: 'string' },
+      } } },
+      coverage_note: { type: 'string' },
+    },
+  }, effort: 'high' },
+)
+
+return {
+  focus,
+  modules_read: readings.map(r => r.module),
+  modules_dropped: ranked.slice(MAX_MODULES).map(m => m.name),
+  map,
+  gaps: (gaps && gaps.gaps) || [],
+  coverage_note: gaps && gaps.coverage_note,
+}

package/workflows/graph-review.js

@@ -0,0 +1,170 @@
+export const meta = {
+  name: 'graph-review',
+  description: 'Review a diff with graph-derived blast radius: scope, dimension fan-out, then adversarial verification of every finding.',
+  whenToUse: 'Reviewing uncommitted work, a branch, or a PR when you want findings that survive a skeptic rather than a plausible-sounding list.',
+  phases: [
+    { title: 'Scope', detail: 'git diff + codegraph impact per changed symbol: the blast radius' },
+    { title: 'Review', detail: 'one reviewer per dimension, in parallel' },
+    { title: 'Verify', detail: 'two refuters per finding, distinct lenses' },
+  ],
+}
+
+const target = (typeof args === 'string' && args) ? args : (args && args.target) || 'uncommitted changes vs HEAD'
+const MAX_VERIFIED = 4
+
+const GRAPH = `On Claude the MCP server exposes one tool by default: load it with
+ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore")
+before the first query (a plugin install uses the plugin_tezgah_ name). The rest of the surface is the CLI:
+\`codegraph impact <symbol>\` gives a symbol's transitive callers - run it per changed symbol of \`git diff\`;
+that blast radius is the point, a diff alone hides it - \`git diff --name-only <ref> | codegraph affected --stdin\`
+names the test files the changed files reach, \`codegraph callers\` and \`codegraph callees\` walk one hop, \`codegraph node <symbol>\` gives a definition
+with its body, \`codegraph query <text>\` searches symbols. The index is the repo's own
+\`.codegraph/codegraph.db\`. Read files for exact lines.`
+
+const SCOPE = {
+  type: 'object',
+  required: ['changed_files'],
+  properties: {
+    project: { type: 'string' },
+    changed_files: { type: 'array', items: { type: 'string' } },
+    changed_symbols: { type: 'array', items: { type: 'string' } },
+    impacted_modules: { type: 'array', items: { type: 'string' }, description: 'from codegraph impact per changed symbol, inbound direction' },
+    blast_radius_note: { type: 'string' },
+    diff_summary: { type: 'string' },
+  },
+}
+
+const FINDINGS = {
+  type: 'object',
+  required: ['findings'],
+  properties: {
+    findings: { type: 'array', items: {
+      type: 'object',
+      required: ['title', 'file', 'summary', 'failure_scenario', 'severity'],
+      properties: {
+        title: { type: 'string' },
+        file: { type: 'string' },
+        line: { type: 'integer' },
+        summary: { type: 'string' },
+        failure_scenario: { type: 'string', description: 'concrete inputs or state -> wrong output or crash' },
+        severity: { type: 'string', enum: ['high', 'medium', 'low'] },
+      },
+    } },
+  },
+}
+
+const VERDICT = {
+  type: 'object',
+  required: ['refuted', 'reasoning'],
+  properties: {
+    refuted: { type: 'boolean', description: 'true = the finding does not hold' },
+    reasoning: { type: 'string' },
+    evidence: { type: 'string', description: 'file:line or tool output that settles it' },
+  },
+}
+
+const DIMENSIONS = [
+  { key: 'correctness', ask: 'logic errors, wrong boundary conditions, unhandled nil/empty/error paths, off-by-one, inverted conditions, state mutated under the wrong assumption' },
+  { key: 'callers', ask: 'callers this change breaks: signature/contract/return-shape changes, callers in impacted_modules that were not updated, dynamic or reflective call sites text search would miss' },
+  { key: 'security', ask: 'injection, missing authz on a newly reachable path, secrets in code or logs, unvalidated external input, unsafe deserialization, TOCTOU' },
+  { key: 'tests', ask: 'behavior changed with no test touching it - name the exact untested branch and the test file that should have covered it' },
+]
+
+phase('Scope')
+const scope = await agent(
+  `Establish the review scope for: ${target}.
+${GRAPH}
+Take the changed files and lines from \`git diff\` (against the ref when the target is a git ref -
+a base branch, a commit range - or HEAD for "uncommitted changes vs HEAD"), then run
+\`codegraph impact <symbol>\` for each changed symbol (or the one symbol, when the target is a
+symbol) to get their transitive callers. Return the changed files, changed symbols, the
+impacted modules, and one honest sentence on how far the blast radius reaches. No
+opinions on quality yet.`,
+  { label: 'scope', schema: SCOPE, effort: 'medium' },
+)
+
+if (!scope) {
+  return { target, findings: [], confirmed: [], refuted: [], unverified: [], unknown: ['scope'], note: 'the scope agent failed - nothing was reviewed; unknown, not clean' }
+}
+if (!scope.changed_files || !scope.changed_files.length) {
+  return { target, findings: [], confirmed: [], refuted: [], unverified: [], unknown: [], note: 'no changes detected for this target - nothing to review' }
+}
+log(`${scope.changed_files.length} changed files, impacted modules: ${(scope.impacted_modules || []).join(', ') || 'none reported'}`)
+
+const CONTEXT = `Target: ${target}
+Changed files: ${scope.changed_files.join(', ')}
+Changed symbols: ${(scope.changed_symbols || []).join(', ') || 'unknown'}
+Impacted modules (transitive callers): ${(scope.impacted_modules || []).join(', ') || 'none'}
+Diff summary: ${scope.diff_summary || 'read it yourself with git diff'}`
+
+phase('Review')
+const reviewed = await parallel(DIMENSIONS.map(d => () => agent(
+  `Review this change through one lens only: ${d.key}.
+Look for: ${d.ask}
+
+${CONTEXT}
+${GRAPH}
+Report only defects in or newly caused by the changed code. A finding needs a concrete failure scenario -
+inputs or state that produce the wrong result. No style notes, no "consider maybe", no praise. Empty list
+is the correct answer when the lens finds nothing.`,
+  { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS, effort: 'high' },
+)))
+// a failed dimension is unknown, never clean: its silence is not a finding
+const unknown = DIMENSIONS.filter((d, i) => !reviewed[i]).map(d => `review:${d.key}`)
+const reviews = reviewed.filter(Boolean)
+
+const rank = { high: 0, medium: 1, low: 2 }
+const all = reviews.flatMap(r => r.findings || []).sort((a, b) => rank[a.severity] - rank[b.severity])
+if (!all.length) {
+  const note = !unknown.length ? 'all four dimensions came back clean'
+    : !reviews.length ? 'every dimension failed - nothing was reviewed; unknown, not clean'
+    : `${unknown.join(', ')} failed - unknown, not clean; the other dimensions found nothing`
+  return { target, scope, findings: [], confirmed: [], refuted: [], unverified: [], unknown, note }
+}
+
+const toVerify = all.slice(0, MAX_VERIFIED)
+if (all.length > toVerify.length) {
+  log(`${all.length} findings raised; verifying the ${toVerify.length} most severe. NOT verified (reported as unverified): ${all.slice(MAX_VERIFIED).map(f => f.title).join('; ')}`)
+}
+
+phase('Verify')
+const LENSES = [
+  'Re-read the actual code at the cited location. Does the code say what the finding claims it says?',
+  'Assume the finding is wrong. Find the guard, caller contract, type constraint, or existing test that already prevents this failure scenario.',
+]
+const verified = await parallel(toVerify.map(f => () => parallel(LENSES.map((lens, i) => () => agent(
+  `Try to REFUTE this review finding. Default to refuted=true when the evidence is not clear.
+
+Finding: ${f.title}
+Location: ${f.file}${f.line ? ':' + f.line : ''}
+Claim: ${f.summary}
+Claimed failure: ${f.failure_scenario}
+
+Your lens: ${lens}
+${GRAPH}
+Cite the file:line or tool output that settles it. A finding that cannot be tied to real code is refuted.`,
+  { label: `verify:${f.title.slice(0, 28)}#${i + 1}`, phase: 'Verify', schema: VERDICT, effort: 'high' },
+))).then(votes => {
+  const live = votes.filter(Boolean)
+  const kills = live.filter(v => v.refuted)
+  // "survived two refuters" means zero refutations; a 1-1 split is a kill.
+  // No live vote at all settles nothing: the finding stays unverified.
+  return { finding: f, settled: live.length > 0, survived: live.length > 0 && kills.length === 0, votes: live }
+})))
+
+const settled = verified.filter(v => v && v.settled)
+const confirmed = settled.filter(v => v.survived)
+const killed = settled.filter(v => !v.survived)
+const unsettled = verified.filter(v => v && !v.settled)
+for (const v of unsettled) unknown.push(`verify:${v.finding.title}`)
+log(`${confirmed.length} findings survived verification, ${killed.length} refuted, ${unsettled.length} unverified (every refuter failed)`)
+
+return {
+  target,
+  scope: { changed_files: scope.changed_files, impacted_modules: scope.impacted_modules, blast_radius_note: scope.blast_radius_note },
+  confirmed: confirmed.map(v => ({ ...v.finding, verdict: 'CONFIRMED', why_it_held: v.votes.filter(x => !x.refuted).map(x => x.evidence || x.reasoning) })),
+  refuted: killed.map(v => ({ title: v.finding.title, refuted_because: v.votes.filter(x => x.refuted).map(x => x.reasoning) })),
+  unverified: unsettled.map(v => ({ ...v.finding, verdict: 'UNVERIFIED - every refuter failed' }))
+    .concat(all.slice(MAX_VERIFIED).map(f => ({ ...f, verdict: 'UNVERIFIED - budget cap' }))),
+  unknown,
+}