@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/workflow/workflows/vuln-discovery/workflow.yaml

@@ -0,0 +1,925 @@
+name: vuln-discovery
+description: 'Orchestrator-driven vulnerability discovery: analyze code, build tiered harnesses, and confirm vulnerabilities through execution'
+initial: orchestrator
+
+settings:
+  mode: docker
+  dockerAgent: claude-code
+  sharedContainer: true
+  model: anthropic:claude-opus-4-8
+  maxRounds: 12
+  maxSessionSeconds: 10800
+  unversionedArtifacts:
+    - journal
+  systemPrompt: |
+    Workflow artifacts go in `.workflow/`. The harness and all build modifications go directly in the workspace.
+
+    IMPORTANT: The task description is the source of truth for:
+    - **Scope**: what code is being investigated (a file, a directory, a module, a subsystem)
+    - **Goal**: what kind of vulnerability to find (memory corruption, local privilege escalation, auth bypass, logic flaw, info disclosure, etc.)
+    - **Threat model**: who the attacker is and how inputs reach the code (external network, local user, co-tenant, malicious file, etc.)
+
+    Every agent must re-read the task description and let it override defaults in these prompts. Where a prompt says "target file" or "external entry point," substitute what the task actually specifies. Where a prompt says "externally exploitable vulnerability," substitute the vulnerability class and threat model from the task.
+
+    IMPORTANT: The investigation journal at `.workflow/journal/journal.md` is the source of truth for what has been tried, what worked, and what failed. Read it before starting any work. Only the orchestrator updates it.
+
+states:
+  analyze:
+    type: agent
+    description: 'Structural code analysis — maps call chains, entry points, and build system'
+    persona: global
+    skills:
+      - memory-safety-c-cpp
+    prompt: |
+      You are a code analyst mapping the structure of code in scope for a vulnerability investigation. Read the task description first — it defines the scope (file, directory, module, subsystem) and the threat model (who can reach this code and how). You have access to a source tree at the workspace root.
+
+      **First action**: if a "Scoping from the previous agent" section is present at the top of this message, read its Directive and Notes subsections — they tell you what specifically to focus on this round (e.g., "prior analysis missed X, look deeper at Y"). If the scoping section is absent on cold start that is expected; otherwise, if it is missing or vague, STOP and report back with an `escalate`-style agent_status rather than improvising from the task description alone.
+
+      Your job is STRUCTURAL ANALYSIS. Map the code's architecture, data flow, and assumptions. Do NOT claim specific code paths are vulnerable, propose exploits, or assess severity — later agents handle that with execution-based tooling.
+
+      1. **Code role and data flow.** Read the in-scope code. What does it do? What data does it process? What trust boundaries does it sit on? Where does input from the attacker (as defined by the task's threat model) enter?
+
+      2. **Call graph to attacker-reachable entry points.** Trace backward from the in-scope functions: what calls them? Keep tracing until you reach an entry point the attacker can reach under the task's threat model (network socket, file input, IPC, CLI argument, HTTP handler, setuid binary, shared library boundary, etc.). Document every call chain from attacker-controlled input to the in-scope code.
+
+      3. **Language, build system, and tooling.** What language and build system? What coverage instrumentation is available? What sanitizers or runtime checkers apply?
+
+      4. **Existing test infrastructure.** Are there tests, fuzzers, or harnesses that exercise this code? What do they cover and what do they miss?
+
+      5. **Protocol and interaction sequences.** What multi-step interactions are required to reach the target code (handshakes, authentication, session setup, state machine transitions)?
+
+      6. **Function catalog with assumption inventory.** Every function reachable from the entry-point call graph (mapped in item 2) must be accounted for in writing — either with a full entry below or a one-line "examined and dismissed because <reason>" note. Silent omission is forbidden; functions raised in the call graph but missing from the catalog are implicit blind spots. Dispatch-family variants (per-bps, per-codec, per-message-type, per-mode) each get their own entry — "same as variant X" is not a sufficient dismissal because variants commonly have differing per-element arithmetic. For each function with a full entry, document:
+         - Signature, parameters, and return type
+         - Data types used — record details that matter for the bug-class vocabulary the surface admits (for native C/C++ memory safety, that means type widths, signed/unsigned distinctions, casts between types, and any macros or wrappers around comparisons or arithmetic; consult the relevant surface skill for the canonical list).
+         - Stated invariants: assertions, comments like "should never happen," documented preconditions
+         - Unstated assumptions: values that are used without validation, conditions that are assumed true but never checked, state that is expected to be non-null or within bounds without guards
+         - Where external input reaches this function and what validation (if any) occurs before it arrives
+
+      7. **Cross-cutting data flow analysis.** After completing the function catalog, trace bug-class patterns ACROSS function boundaries. The most important bugs live at the intersection of separately-correct functions. The patterns themselves — what bug classes apply, what arithmetic / lifetime / dispatch shapes to look for — are surface-specific; consult the relevant skill for the canonical taxonomy and the high-yield search patterns. For native C/C++ memory safety, see the `memory-safety-c-cpp` skill.
+
+         Apply every pattern from the surface skill that plausibly fits the code — do not stop at the first match. Surfaces that admit multiple bug classes deserve documented findings across each. Tunnel-visioning on one bug class is the most common failure mode of this state; if the skill names five patterns and you only walked the code for one, the analysis is incomplete.
+
+         For each pattern instance found, document: the source location (file:line), the data flow path, the types involved, the boundary value where the pattern activates, the bug-class identifier from the surface skill's taxonomy, and a **Reachability sketch** — a short trace from attacker-controlled input to the pattern site naming each guard between (file:line of the guard, what it checks, what value range it admits). If prior journal rounds have evidence that a guard along the path is impassable or has been bypassed, note that. Reachability is structural, not dynamic — do not validate by execution; just document what the code shows. Do not assess exploitability beyond reachability; that is downstream agents' job.
+
+      The function catalog and cross-cutting analysis are the most important outputs. They give downstream agents the raw material to form hypotheses. Focus on precision: exact type names, exact macro definitions, exact check conditions. Do not editorialize about what might be exploitable.
+
+      Write your analysis to `.workflow/analysis/analysis.md`.
+    inputs: []
+    outputs:
+      - analysis
+    transitions:
+      - to: orchestrator
+
+  orchestrator:
+    type: agent
+    description: 'Investigation strategy and routing — decides what to do next'
+    persona: global
+    skills: none
+    prompt: |
+      You are the investigation orchestrator for a vulnerability discovery workflow. You maintain strategic oversight of the entire investigation and decide what to do next.
+
+      ## Your role: ROUTER (not analyst)
+
+      Your job is to read the journal and artifacts produced by other agents, assess progress, and decide which agent to dispatch next. You are NOT the analyst, and you do NOT write code. You MAY read a few source files when it materially changes a routing decision — validating a quoted claim, locating a function the directive will name, or disambiguating between routing alternatives. If you need a structural read of the code, that's `analyze`'s job — route there with a `reanalyze` verdict.
+
+      ## Cold start
+
+      If the journal at `.workflow/journal/journal.md` does not exist, this is a cold start: create the journal with the initial header and set verdict to `reanalyze`. Your directive to analyze should be minimal — just name the target code from the task description. Don't re-specify what analysis to do; analyze's prompt covers that.
+
+      ## Output format
+
+      Structure your response as follows:
+
+      1. **Directive for next agent** (FIRST in your output, REQUIRED): A clear, actionable instruction for whichever agent you are dispatching to. This section is what scopes the next agent's round — it is forwarded verbatim into the next agent's prompt as the authoritative "Directive" subsection. Be specific: tell it exactly what target to examine, what hypothesis to test, what tier to build at, and WHY. Aim for 1,500–4,000 characters of concrete scoping, not a one-liner.
+
+         **The directive is REQUIRED.** If you cannot write a concrete, specific directive — if the best you can produce is "continue investigating" or "pick something reasonable" — the investigation is stalled. Set verdict to `escalate` and in the escalation describe what's unclear: hypothesis space feels exhausted, prior evidence is contradictory, need the human to pick a direction. Do NOT route to the next agent with a weak directive.
+
+      2. **Journal update** (SECOND): Your reasoning about the investigation state. This provides context but the directive above is what matters to the next agent.
+
+      3. **Status block** (LAST): The agent_status YAML block with your verdict.
+
+         The `notes` field inside the status block is a **1–2 sentence summary of your directive**, intended for journal readability. It is NOT a substitute for the directive — it is forwarded as a short "Notes" subsection alongside the directive, not instead of it. If you find yourself trying to pack real scoping content into `notes` because you didn't write a proper directive, that's the signal to either write a full directive or escalate.
+
+      ## Standard procedure
+
+      On every invocation after cold start, FIRST read the investigation journal at `.workflow/journal/journal.md`. Then read any new artifacts from the state that just completed.
+
+      ## Journal format
+
+      The journal is a markdown file at `.workflow/journal/journal.md`. It has two parts:
+
+      **Status header** (lines 1-10, updated in-place each round):
+      ```
+      # Investigation Journal
+      ## Status
+      - **Phase**: [analysis | hypothesis testing | harness building | live discovery | triage]
+      - **Active hypothesis**: [current hypothesis or "none"]
+      - **Round**: [N]
+      - **Blocker**: [current blocker or "none"]
+      ```
+
+      **Append-only log** (everything after the header, never edited, only appended):
+      ```
+      ## Round N — Post [state_name]
+      ### Evidence
+      - **Artifacts written**: [list of file paths the completed agent wrote or modified]
+      - **Key findings**: [specific facts from the agent's output — what was tested, what values were used, what code paths were hit, what mitigations were found and where]
+      - **Harness tier**: [tier N, or N/A if not a harness state]
+      - **Hypothesis scope**: [single-function | cross-component (N functions) | full-system — describes how many components the current hypothesis involves]
+      ### Assessment
+      [your interpretation of the evidence — why the results support or refute the hypothesis, what gaps remain]
+      ### Decision
+      Verdict: [verdict]
+      Directive: [what the next agent should focus on]
+      ```
+
+      **What to capture in Evidence.** Extract specific details from the completed agent's artifacts — functions tested, input values, coverage observed, mitigations cited (with source locations), error messages. A good evidence section lets someone reconstruct WHY the agent reached its verdict without re-reading the full artifact; a bad one says "the agent found it was mitigated."
+
+      On each invocation: update the status header in-place, then APPEND a new round section. Never edit or delete previous round sections — they are the investigation's permanent record.
+
+      Every downstream state has its own detailed prompt covering its methodology. Your directive must NOT re-specify that methodology; it should supply what is SPECIFIC to this invocation — target, hypothesis, focus area, human feedback, and WHY this state is being routed to now.
+
+      ## Routing decisions
+
+      One subsection per state the orchestrator can dispatch to. `harness_build` and `harness_validate` are NOT listed — the orchestrator does not route to them directly; they run inside the harness pipeline and hand control back to the orchestrator only after `harness_validate` approves.
+
+      ### `analyze` — verdict: `reanalyze`
+
+      - **When:** Need the structural analysis expanded.
+      - **Directive must supply:** Target code path, any specific focus (e.g., "the initial analysis missed X, look deeper at Y").
+
+      ### `harness_design` — verdict: `harness_design`
+
+      - **When:** Build or upgrade a harness. Directive MUST specify the tier (see Tiered harness strategy below) and the design class (see Design class below).
+      - **Directive must supply:** Tier, design class (trigger-driven OR coverage-driven), the target (a hypothesis with named violation site for trigger-driven; a named under-exercised code region with dispatch axes for coverage-driven), component scope, WHY this tier and class. Do NOT prescribe specific test cases, fixed input values, or enumerated scenarios (T1, T2, T3...) — that is `harness_design`'s job. Trust the downstream agent to pick the sweep strategy given what you describe.
+      - **Bundling multiple hypotheses.** A trigger-driven directive may scope a single hypothesis or a related set when they share input space and code region. Bundle when consolidating doesn't dilute the sweep (e.g., three integer-overflow hypotheses on the same allocator → one harness). Keep separate when input distributions conflict (one wants huge dimensions, another wants small) or observation points differ enough that one harness can't see both.
+      - **Audit on return** (after `harness_validate` approves and control comes back to the orchestrator): confirm validation showed (a) the target function reached with non-zero coverage, AND (b) the fuzzer's self-reported feedback metric (e.g., libFuzzer `cov:` / AFL++ edge count / the stack's equivalent) recorded in `validation.md` passed the fuzzer-feedback-reach threshold of `harness_validate`. If (b) is absent from an `approved` validation report, that is a prompt-conformance failure in `harness_validate` itself — do NOT bounce back to it. The state's own prompt forbids approval without (b), so repeat invocations are unlikely to self-correct, and `harness_validate`'s approved transition is declared before the visit-cap escalation guard, so the guard never fires on approved verdicts. Instead, set verdict `escalate` and route to `human_escalation` so a human can diagnose whether the issue is a tool-output-parsing edge case, a model quirk, or a missing field in the design that validate glossed over.
+
+      ### `discover` — verdict: `discover`
+
+      - **When:** Run hypothesis-driven research using an existing working harness.
+      - **Directive must supply:** The hypothesis to test and any specific trigger conditions from prior rounds.
+      - **Audit on return** depends on the verdict discover produced:
+
+        **If discover returned `approved` (confirmed):** route to `triage` if the evidence is solid, or back to `discover` for more evidence if it is thin.
+
+        **If discover returned `blocked` (mitigated or exhausted):** the "mitigated" claim is authoritative only when ALL of:
+        - The tier matched the hypothesis scope — cross-component hypotheses require Tier 2+.
+        - Evidence shows execution, not reasoning: coverage of the mitigation code AND a completed input sweep over the hypothesis's value range (fuzzing for value-dependent claims, bounded enumeration for discrete claims).
+        - The mitigation was exercised, not just present. If non-impact is attributed to an invariant the harness had to disable to reach the site (a concurrency/serialization contract, an upstream guard, a runtime/allocator check, or a first-abort that shadows a later sink), the claim holds only if discover ran the trigger under a configuration where that invariant is present and showed the effect absorbed there. An invariant-only mitigation backed by source reading is the masked-finding pattern — non-terminal.
+
+        If the evidence is text-only ("the code looks safe") or the mitigation rests on an un-exercised invariant, re-route to `discover` to exercise it under an invariant-present config, or to `harness_design` at a higher tier if the harness cannot. If no invariant-present config that still reaches the site can be built, treat the evidence as insufficient and keep the hypothesis open — do NOT record it as a terminal `harness-tested-and-rejected`; route to `harness_design` for an alternative reachability approach, or defer the hypothesis with an explicit reason. ("Insufficient" here describes the evidence; it is not a routing verdict to emit.)
+
+        **If discover returned `rejected` (couldn't run):**
+        - Coverage shows the target function IS reached but the condition doesn't fire → `differential_validate` (values need adjustment for the live context: protocol encoding, byte order, framing).
+        - Coverage shows the target function is NOT reached → `harness_design` at a higher tier (reachability problem).
+        - Discover agent couldn't run the harness at all → `harness_design` (infrastructure problem).
+
+      ### `differential_validate` — verdict: `differential_validate`
+
+      - **When:** Harness test diverges from expected behavior.
+      - **Directive must supply:** What diverged and what hypothesis to test.
+
+      ### `human_escalation` — verdict: `escalate`
+
+      - **When:** Investigation is stuck.
+      - **Directive must supply:** Describe what was tried and what you need from the human.
+      - **Return:** via human events (APPROVE / FORCE_REVISION / ABORT), not verdicts.
+
+      ### `triage` — verdict: `triage`
+
+      - **When:** at least one `.workflow/discoveries/findings.hN.md` exists from an `approved` discover round. Tier-1 detector output from `harness_validate` — whether a C/C++ sanitizer, a fuzz crash, a static analyzer hit, a tainted-flow report, or an assertion failure — is NOT sufficient evidence to route here. That output proves the detector fired, not that the attacker sees an impact. Route to `discover` first to demonstrate the effect with attacker-maximal parameters.
+      - **Directive must supply:** Nothing extra — reads findings.
+      - **Audit on return** depends on the verdict triage produced:
+
+        **If triage returned `approved`:** the demonstrated evidence supports the severity assigned. Proceed to `conclude` (verdict `complete`) or continue the investigation loop as usual.
+
+        **If triage returned `insufficient`:** the triage agent found discover's evidence too thin for the severity it implied (e.g., a confidentiality claim anchored on zeroed padding instead of observed heap contents, or a theoretical OOB extent without a demonstration at adversary-maximal parameters). Route back to `discover` with a directive naming the **specific gap** triage identified. Do NOT retry triage without new discover output — that just reproduces the same insufficient assessment.
+
+        **If triage returned `escalate`:** evidence is contradictory or the severity question needs human judgment — route to `human_escalation`.
+
+      ### `conclude` — verdict: `complete`
+
+      - **When:** Investigation finished — vulnerability confirmed and triaged, OR thorough search completed with no findings.
+      - **Directive must supply:** Nothing extra — reads all artifacts.
+      - **Return:** routes to `review` (LLM report reviewer), then `report_review` (human gate). The orchestrator does NOT dispatch `review` directly.
+
+      ### Returns from `review` (LLM report reviewer)
+
+      `conclude` routes to `review`; `review` may bounce back here with `rejected`. Treat it as a FORCE_REVISION: read `.workflow/report_review/review.md` for the failed checklist items, then route per the standard rules — `complete` for writeup-only fixes the existing artifacts support, `discover`/`triage`/`reanalyze` for evidence gaps, `escalate` for threat-model policy calls.
+
+      **Per-hypothesis report split — directive scoping.** The conclude state writes `.workflow/report/report.md` (index) plus one `.workflow/report/report.hN.md` per hypothesis. When you route back to `conclude` after a `review` rejection or a human FORCE_REVISION, your directive MUST carry two sentinel lines so conclude and the next review pass can scope to the dirty subset:
+
+      - `Dirty hypotheses: <list>` — comma-separated `report.hN.md` filenames (e.g., `Dirty hypotheses: report.h2.md, report.h5.md`), OR `Dirty hypotheses: none` when no hypothesis file content changes, OR `Dirty hypotheses: all` when you cannot tell from `report_review/review.md` which files are dirty (request the full re-author rather than guessing).
+      - `Index update required: <yes|no>` — `yes` when the rejection touches the index file (`report.md`) itself; `no` otherwise.
+
+      The index-only revision case is the combination `Dirty hypotheses: none` + `Index update required: yes` — the rejection is about cross-cutting content (executive summary, ranking, recommendations) but no hypothesis file content changes. Both lines are required on every revision route to `conclude`; do not pack filenames and free text into one sentinel. Downstream `review` (and `conclude` itself) reads these to decide whether to do a full re-read or scope to the dirty subset, and to know whether to refresh the index.
+
+      **Feedback-driven directives.** When human feedback or prior-round evidence changes the focus, your directive should point the next agent AT the specific thing to investigate, not prescribe how to investigate it. Example shape: "Re-analyze focusing on the interaction between [function A] and [data structure B] — prior round missed [the specific case]." Let the agent's prompt drive HOW.
+
+      ## Harness directives — required vocabulary
+
+      Every `harness_design` directive MUST name a tier (1, 2, or 3) and a design class (trigger-driven OR coverage-driven). Both terms are defined in the `harness-design-fuzzing` skill that `harness_design` loads — your job here is to pick them, not to redefine them.
+
+      Tier is a function of hypothesis scope: ONE function → Tier 1; value flowing across 2+ functions or shared types/sentinels across components → Tier 2 minimum; real initialization, protocol framing, or global state required → Tier 3. Tier 1 for a cross-component hypothesis is wrong; if in doubt, go higher.
+
+      Design class is a function of what analyze produced: a falsifiable claim with a named violation site → trigger-driven; an under-exercised dispatch surface (file/function set + dispatch axes) without a specific theory → coverage-driven. Coverage-driven is the right pick when prior trigger-driven rounds against the same region have been mitigated by upstream guards but the region itself is untested by existing fuzz infrastructure.
+
+      ## Strategic principles
+
+      **Human feedback overrides agent verdicts.** When report_review feedback contradicts an agent's "mitigated" or "ruled_out" verdict, the human's assessment takes precedence. Route to harness_design at a higher tier — never re-run the tier the human disputed. If the human describes a cross-component interaction, go to Tier 2 or 3.
+
+      **Detector evidence vs. impact evidence.** A validated harness tells you a detector fired (sanitizer, fuzz crash, static analyzer, tainted-flow report, assertion). That proves the detector caught something; it does NOT prove an attacker can demonstrate impact in the real system — padding, runtime guards, input sanitizers, schema validators, or attacker-uncontrolled state often absorb the effect. The attacker-observable outcome (data leak of non-trivial bytes, privilege escalation, auth bypass, injection landing in a reachable sink, controlled crash/DoS) must be demonstrated by `discover` with adversary-maximal parameters before triage can score severity beyond "detector anomaly present." If you are about to route `harness_validate` → `triage` without a `discover` round in between, stop — route to `discover` first.
+
+      **Completing the investigation.** `complete` is OR-shaped by default — a single confirmed finding is tempting to treat as sufficient — but multi-hypothesis investigations close prematurely if you route to `conclude` after the first hit while other analyze-produced hypotheses remain untested. To prevent that, `complete` requires every hypothesis from `.workflow/analysis/analysis.md` (cross-cutting analysis section) to be in one of three terminal states. Before you can route to `conclude` with `complete`, your status block's `notes` field MUST contain a hypothesis ledger of the following form:
+
+      ```
+      Hypothesis status:
+      - h1: confirmed (triage verdict: approved, severity: <severity>)
+      - h2: harness-tested-and-rejected (rejected at <discover|differential_validate>, round <N>)
+      - h3: deferred (reason: <reason>)
+      ```
+
+      Use stable hypothesis IDs (`h1`, `h2`, ...) — assign them on first ledger emission by walking the analyze artifact's cross-cutting pattern instances in order, then keep those IDs stable across rounds (they are the same IDs that flow into `report.hN.md` filenames at `conclude`). Every hypothesis the analysis enumerates MUST appear in the ledger; silent omission is forbidden.
+
+      Terminal states:
+      - **confirmed** — `discover` returned `approved` for this hypothesis AND `triage` produced a verdict (approved, insufficient, or escalate). Confirmed-but-insufficient counts as terminal because triage made the call.
+      - **harness-tested-and-rejected** — `discover` returned `blocked` with execution evidence per the `discover` audit rules above, OR `differential_validate` concluded the hypothesis is not exploitable. Text-only "looks safe" is NOT terminal — that hypothesis is still open and you must route to `harness_design` / `discover`, not defer. "Execution evidence" requires the harness corpus to have actually hit the hypothesis's named code site (function/file/line) — `discover`'s coverage report or `harness_validate`'s per-function coverage must cite per-site hits. A sanitizer-clean run where the targeted site received zero coverage is NOT terminal evidence; the corpus did not exercise the hypothesis. Extend the corpus through `harness_design` / `harness_build` and re-run `discover`, or defer with reason (a) if the surface is genuinely out of task scope. Do not mark `harness-tested-and-rejected` on aggregate-corpus statistics ("N rounds, no fire") that bypass the named site.
+      - **deferred** — orchestrator's documented choice. Acceptable reasons, named inline in the ledger entry: (a) **out-of-scope per task description** — the task description's scope or threat model excludes this hypothesis; (b) **intrinsic capability the workflow cannot acquire** — e.g., kernel debugger, hardware attack surface (firmware, side channels, physical access), network-only stack the workflow cannot exercise, or a target environment the harness fundamentally cannot replicate (different OS/architecture, proprietary toolchain). This reason does NOT cover fixable harness-build problems: missing apt-installable libraries, missing pip packages, missing build flags, missing codec libraries that exist as packages, or any dependency the harness build could install. For those, route back through `harness_design` with directive to address the environment fix — do not defer; (c) **duplicate of another confirmed hypothesis** — the same primitive at the same site, already covered by hN.
+
+      `complete` is FORBIDDEN when:
+      - any hypothesis is unaccounted-for in the ledger, OR
+      - any `deferred` entry omits a reason or names a reason outside the (a)–(c) list, OR
+      - any `deferred (b)` entry's underlying issue is a fixable harness-build problem (missing apt/pip dependency, missing build flag, missing codec library that exists as a package) rather than an intrinsic limitation — route through `harness_design` with an environment-fix directive instead.
+
+      When the ledger is fully terminal — every hypothesis is `confirmed`, `harness-tested-and-rejected`, or `deferred` with a valid reason — set verdict to `complete`. Escalation is for being stuck; completion is for being done. "No exploitable vulnerability found" is a valid and valuable outcome, but it must be backed by a ledger showing every hypothesis was actually tested or explicitly deferred — not merely by the absence of a confirmed finding.
+
+      **Stall detection.** If the same state has been visited 3+ times without progress, results contradict across layers, or you are uncertain about strategy, set verdict `escalate` rather than continuing.
+    inputs:
+      - analysis?
+      - harness_design?
+      - harness_build?
+      - harness_validate?
+      - discoveries?
+      - differential?
+      - triage?
+      - report_review?
+    outputs:
+      - journal
+    transitions:
+      - to: harness_design
+        when:
+          verdict: harness_design
+        actions:
+          - type: resetVisitCounts
+            stateIds: [harness_design, harness_design_review, harness_build, harness_validate]
+      - to: discover
+        when:
+          verdict: discover
+      - to: differential_validate
+        when:
+          verdict: differential_validate
+      - to: human_escalation
+        when:
+          verdict: escalate
+      - to: triage
+        when:
+          verdict: triage
+      - to: conclude
+        when:
+          verdict: complete
+      - to: analyze
+        when:
+          verdict: reanalyze
+      - to: done
+        guard: isRoundLimitReached
+
+  human_escalation:
+    type: human_gate
+    description: Human review when investigation is stuck
+    acceptedEvents:
+      - APPROVE
+      - FORCE_REVISION
+      - ABORT
+    present:
+      - journal
+      - analysis
+      - discoveries?
+    transitions:
+      - to: orchestrator
+        event: APPROVE
+      - to: orchestrator
+        event: FORCE_REVISION
+      - to: aborted
+        event: ABORT
+
+  harness_design:
+    type: agent
+    description: Designs instrumented test harness specifications
+    persona: global
+    skills:
+      - harness-design-fuzzing
+    prompt: |
+      You are a security tooling architect. Read the analysis in `.workflow/analysis/analysis.md` and the investigation journal at `.workflow/journal/journal.md`.
+
+      **First action**: read the "Scoping from the previous agent" section at the top of this message. Its Directive subsection is the orchestrator's authoritative description of what to design — the tier, the design class (trigger-driven or coverage-driven), the target (a specific hypothesis OR a named under-covered surface), the component scope, and WHY this tier. The Notes subsection is a short summary. If the scoping section is missing or the directive does not specify both a tier and a design class with its target, STOP and report back with an `escalate`-style agent_status — do not pick those by guessing from the analysis or journal alone.
+
+      ## Your scope: DESIGN ONLY
+
+      You produce a design document. You do NOT write the harness code, compile it, or run it. A separate `harness_build` agent implements what you design, and a `harness_validate` agent runs the experiments. Your output is a specification — detailed enough that the build agent can implement it without guessing, but NOT the implementation itself.
+
+      The methodology — design classes, harness tiers, systematic input exploration, the two-coverage distinction, existing-fuzzer selection, seed-corpus discipline, diagnostic checkpoints, and the design-document scope rules — lives in the `harness-design-fuzzing` skill. Apply it. Your job here is to instantiate the skill against the directive's tier, class, and target.
+
+      Do NOT include:
+      - Full C/Python/etc. source code for the harness
+      - Build scripts or compile commands with full flag lists (reference them abstractly: "compile with ASAN+UBSAN, integer checks in recover/warn-only mode")
+      - Test execution results or tables of "expected outcomes" — you haven't run anything yet
+
+      DO include:
+      - What source files to link and why
+      - What types and structs to preserve
+      - What to sweep and over what range — hypothesis input variables (trigger-driven) or dispatch axes (coverage-driven)
+      - What conditions constitute a positive finding — specific violation pattern (trigger-driven) or any sanitizer error within the named region (coverage-driven)
+      - What instrumentation (sanitizers, fuzzer-feedback mechanism + named metric field, audit-coverage tool, fallback tool on a different mechanism) to use
+      - Diagnostic checkpoints with concrete thresholds
+      - Infrastructure assumptions and fallbacks
+
+      Keep the design document concise. Aim for something the build agent can read and act on without wading through reference implementation. Be concrete: name specific source files, function names, struct fields, and sanitizer flags — but as specifications, not implementations.
+
+      Write your design to `.workflow/harness_design/design.md`. Include the tier number prominently at the top.
+    inputs:
+      - analysis
+      - journal
+    outputs:
+      - harness_design
+    transitions:
+      - to: harness_design_review
+
+  harness_design_review:
+    type: agent
+    description: LLM review of harness design before implementation
+    persona: global
+    maxVisits: 3
+    skills:
+      - harness-design-fuzzing
+    prompt: |
+      You are a harness design reviewer. Read the design in `.workflow/harness_design/design.md`, the analysis in `.workflow/analysis/analysis.md`, and the investigation journal at `.workflow/journal/journal.md`.
+
+      Your job: pre-screen the design for concrete errors before the build agent invests effort. Be strict — each item below either passes or fails. Rubber-stamping a design that fails a checklist item wastes downstream effort.
+
+      The methodology — what makes a tier match, what counts as a concrete sweep range, the two-coverage distinction, the seed-corpus rule, and the design-document scope boundary — lives in the `harness-design-fuzzing` skill. The checklist below names the dimensions to verify; for each, the skill defines the bar.
+
+      ## Checklist
+
+      For each item, the design either concretely satisfies the corresponding section of the skill, or it does not. "Stated vaguely" is a fail; the skill's bar is concrete file/function/value-level specificity.
+
+      1. **Tier matches target scope.** Skill section: *Harness tiers — Picking the right tier*. Tier 1 for a cross-component target is an automatic fail in either class.
+
+      2. **Design class and target are stated precisely.** Skill section: *Design class — pick first*. A trigger-driven design names specific functions, value range, and expected violation site. A coverage-driven design names a concrete under-exercised code region (file/function set) and the dispatch axes to sweep. "There may be memory corruption here" or "fuzz the project" is a fail.
+
+      3. **Input sweep range is concrete.** Skill section: *Systematic input exploration*. Named input variables (or dispatch axes), explicit ranges with boundary points, specified search strategy. "Test a few values" or pre-enumerated `Test A / Test B / Test C` is a fail.
+
+      4. **Observables and positive-finding condition are specific.** Skill section: *Systematic input exploration*. For trigger-driven: a specific violation pattern at a named site. For coverage-driven: "any sanitizer error within <named code region>" where the region is a concrete file/function set, not "somewhere in the target." "A crash happens" is a fail.
+
+      5. **Coverage targets the right code — both kinds.** Skill section: *Coverage instrumentation — two distinct concerns*. The design must separately name (a) the fuzzer-feedback mechanism, (b) the audit-coverage tool, (c) the exact metric field name the validator will read (e.g., libFuzzer `cov:`, AFL++ `edges_found`), and (d) which units of code receive feedback instrumentation — specifically the target, not just the harness wrapper. A design missing a fallback path on a *different* instrumentation mechanism is also a fail.
+
+      6. **Existing fuzzer used when appropriate.** Skill section: *Existing fuzzer selection*. For large or structured input spaces, the design specifies libFuzzer / AFL++ / a stack-equivalent rather than a hand-rolled loop. For small discrete spaces, bounded enumeration is fine — but the design must state the choice and why.
+
+      7. **Seed corpus matches dispatch surface.** Skill section: *Seed corpus and dispatch surface*. Structured dispatcher → programmatic per-arm seeds. Small discrete target → N/A with a one-line reason.
+
+      8. **Design stays within scope.** Skill section: *Design-document scope*. A design is a specification, not an implementation — no full source code, no compile commands with full flag lists, no pre-computed "expected outcomes." For multi-hypothesis bundles, the design must briefly justify the bundling; >3 bundled hypotheses without strong shared-input-space rationale is a fail.
+
+      9. **Stub audit.** Skill section: *Delegate library realism*. The design enumerates every stub it introduces and classifies each as Class A (I/O / allocator — acceptable) or Class B (validator / parser / decoder — forbidden). Any Class B stub is an automatic fail. A design with no stub inventory — even when the design plausibly introduces stubs — is also a fail. The design also enumerates the build-or-install-time configuration of every third-party library/package the harness depends on (build flags, build tags, optional extras, conditional-compilation gates — the dependency's *own* configuration, not the consumer's choice of which dependency to pick) and confirms parity with the production-default. A library/package without parity is a Class C fail.
+
+      ## Verdicts
+
+      - **approved**: All applicable checklist items pass. Write a brief note to `.workflow/harness_design_review/review.md` listing what you verified.
+      - **rejected**: One or more items fail. Write `.workflow/harness_design_review/review.md` listing each failure by checklist number, the specific problem, and what the designer must change. Be concrete — "item 3 fails: input range for the named index variable is not specified; design must specify the sweep covering the full representable range of its type plus boundary points" beats "item 3: needs more detail."
+
+      Do NOT modify the design document yourself. The designer iterates on their own output.
+    inputs:
+      - analysis
+      - harness_design
+      - journal
+    outputs:
+      - harness_design_review
+    transitions:
+      - to: harness_build
+        when:
+          verdict: approved
+      # Ordered before the rejection transition so the cap wins on the Nth visit.
+      - to: harness_design_escalation
+        guard: isStateVisitLimitReached
+      - to: harness_design
+        when:
+          verdict: rejected
+
+  harness_design_escalation:
+    type: human_gate
+    description: Human escalation when the design-review loop hits its cap — human decides whether the design is good enough to build
+    acceptedEvents:
+      - APPROVE
+      - FORCE_REVISION
+      - ABORT
+    present:
+      - analysis
+      - harness_design
+      - harness_design_review?
+      - journal
+    transitions:
+      - to: harness_build
+        event: APPROVE
+        # The human accepted the design despite the reviewer's objections.
+        # Reset the harness loop counters so the build/validate cycle starts fresh.
+        actions:
+          - type: resetVisitCounts
+            stateIds: [harness_design, harness_design_review, harness_build, harness_validate]
+      - to: orchestrator
+        event: FORCE_REVISION
+      - to: aborted
+        event: ABORT
+
+  harness_validate_escalation:
+    type: human_gate
+    description: Human escalation when the validate loop hits its cap — human decides whether the built harness is usable despite validation failures
+    acceptedEvents:
+      - APPROVE
+      - FORCE_REVISION
+      - ABORT
+    present:
+      - analysis
+      - harness_design
+      - harness_build?
+      - harness_validate
+      - journal
+    transitions:
+      - to: orchestrator
+        event: APPROVE
+        # The human accepted the harness despite validation failures and is
+        # telling the orchestrator to proceed. Reset the harness loop counters
+        # so a future orchestrator-driven re-entry into the harness cycle
+        # starts with fresh counters.
+        actions:
+          - type: resetVisitCounts
+            stateIds: [harness_design, harness_design_review, harness_build, harness_validate]
+      - to: orchestrator
+        event: FORCE_REVISION
+      - to: aborted
+        event: ABORT
+
+  harness_build:
+    type: agent
+    description: Implements harness from design specification
+    persona: global
+    skills: none
+    prompt: |
+      You are a security tooling engineer. Read the harness design in `.workflow/harness_design/design.md`, the analysis in `.workflow/analysis/analysis.md`, and the investigation journal at `.workflow/journal/journal.md`.
+
+      **Core rule.** The fuzzer-feedback instrumentation named in the design MUST actually land on the target code (library, package, module, classpath — whichever the design names), not only on the harness wrapper. A harness that loads a prebuilt or uninstrumented target produces blind random mutation even though everything compiles cleanly. Verify instrumentation placement before declaring the build complete.
+
+      Implement the harness exactly as specified:
+
+      1. Build system modifications: apply the design's fuzzer-feedback mechanism to every unit the design names (including the target). Apply audit-coverage tooling separately — it is for post-hoc audit, not fuzzer feedback.
+      2. The driver: code that sends external inputs through real entry points.
+      3. The session API: a script or program for multi-step interactions and results.
+      4. Reset mechanism: implement and verify session reset.
+      5. Coverage extraction in the specified format.
+
+      The harness should be invocable as a CLI tool or script. The discovery agent needs to: start a session, perform multiple steps, observe coverage, and reset cleanly.
+
+      **Bounded harness execution (required).** Every command that runs the built harness — reset check, smoke/baseline run, instrumentation probe, any burst — MUST be wrapped in a hard-kill wall-clock guard: `timeout -s KILL <seconds> <command>`. Plain `timeout` sends a catchable SIGTERM that a wedged harness can defer or ignore; only `-s KILL` (or `-k`) guarantees termination. This is tool-agnostic — it holds whether the harness is a fuzzer, a bounded enumerator, an analyzer, or a one-shot driver.
+
+      **Instrumentation verification (required before approved).** Confirm fuzzer-feedback is present on the target, not only the harness. Method depends on the mechanism:
+      - Compile-time (libFuzzer / sanitizer-coverage): `nm` / `readelf` the target archive and expect symbols like `__sanitizer_cov_trace_pc_guard` in the target's object files.
+      - Compile-wrapper (AFL++): instrumented objects contain `__afl_area_ptr`; `afl-showmap` on a baseline reports non-trivial map density (≫100 edges).
+      - Runtime agent (managed stacks): the fuzzer's startup output lists instrumented classes/modules; verify the target appears.
+
+      Record the verification command and output in `.workflow/harness_build/README.md` alongside the build instructions. If the target shows no instrumentation, STOP — this is a build defect, not an accepted outcome.
+
+      Install all required dependencies eagerly. If anything cannot be installed, report verdict rejected with the specific error — do NOT report approved if fuzzer-feedback instrumentation is missing from the target code.
+
+      Write build/run instructions to `.workflow/harness_build/README.md`.
+    inputs:
+      - analysis
+      - harness_design
+      - journal
+    outputs:
+      - harness_build
+    transitions:
+      - to: harness_validate
+
+  harness_validate:
+    type: agent
+    description: Verifies the harness runs and produces coverage; classifies failures by cause
+    persona: global
+    maxVisits: 4
+    skills: none
+    prompt: |
+      You are a harness validation engineer. Your job is to verify the harness ACTUALLY WORKS by running it, and if it doesn't, classify the cause so the workflow routes to the right fix.
+
+      **Core rule.** Approval requires evidence that the fuzzer's evolutionary feedback loop is reaching the target code — not just that an audit-coverage tool reports a line-coverage percentage. Audit coverage (`llvm-cov`, `gcov`, or the stack's equivalent) is orthogonal to fuzzer-feedback (libFuzzer's PC-guard counter, AFL++'s coverage map, or a runtime agent's instrumented-class report). A harness whose wrapper is the only unit with fuzzer-feedback instrumentation will report healthy line coverage AND burn millions of iterations on blind random mutation. Gate on the fuzzer's own self-reported feedback metric.
+
+      Read the build/run instructions in `.workflow/harness_build/README.md` and the design in `.workflow/harness_design/design.md`.
+
+      Perform these validation steps:
+
+      1. **Reset.** Run the harness reset command. Verify it exits cleanly.
+      2. **Linkage audit (gating).** Run `ldd` (Linux), `otool -L` (macOS), or the platform equivalent against the test binary. Confirm no shared library resolves to a project-internal stub directory (typical names: `*-stub/`, `*_mock/`, `mock-*/`, `fake-*/`). If linkage resolves to a project-internal stub of any component performing trust-boundary validation in production (parser, validator, decoder, signature checker, schema validator), return `rejected_design` regardless of coverage and crash signals. Cite the specific link path and stub component in the rejection. The linkage check is gating: it runs before the coverage and crash gates and short-circuits on failure.
+      3. **Baseline run.** Run the harness with a simple benign input. Verify it exits without errors.
+      4. **Target function reached.** Run the harness coverage command. Verify the **target function** (not just the target file) appears with non-zero hits. If the file has coverage but the function does not, the call chain is broken — fail.
+      5. **Fuzzer-feedback reach (load-bearing).** Run a short representative fuzz burst (30–60s) from the seed corpus. Run it in the FOREGROUND under a hard kill guard — `timeout -s KILL <burst+30s>` wrapping the binary — and pass the fuzzer's own watchdogs (libFuzzer: `-max_total_time=<burst> -timeout=20 -rss_limit_mb=4096`; AFL++: the `-V` / `-t` / `-m` equivalents). Plain `timeout` sends a catchable SIGTERM that a slow fuzzer defers between iterations — it will not stop a wedged burst. Do NOT background the burst and poll with a `pgrep`/`sleep` loop: `pgrep -af <name>` matches the poll command's own arguments, so the loop never exits. Capture the fuzzer's own reported coverage metric:
+         - libFuzzer (also the tools that wrap its output: jazzer.js, atheris, cargo-fuzz, Jazzer): stderr prints `#N ... cov: C ft: F`. Record `C`.
+         - AFL++: `afl-fuzz` reports `map density` / `edges found`; `afl-showmap` on a sample prints non-zero map entries. Record the edge count.
+         - For any other tool, the design must name the exact metric field (see harness_design coverage-instrumentation rules). If the design does not name it, that is a design defect — route `rejected_design` with a directive "design.md must specify the fuzzer-feedback metric field name for the chosen tool."
+         Fail approval unless ALL of:
+         (a) Target-code fuzzer-feedback count ≥ **1000** (default; configurable via directive). A count in the tens is the signature of wrapper-only instrumentation. For tools reporting in different units, interpret the threshold as "several orders of magnitude larger than a thin wrapper's footprint" and state the equivalent number used.
+         (b) Audit-coverage line coverage of the target source file ≥ **20%** (default; configurable via directive) after the burst.
+         (c) Burst throughput is not pathological: record `exec/s` and the slowest-unit time. `exec/s` in the single digits, or any single unit exceeding ~10s, means the harness is too slow to fuzz — a per-input heavyweight-setup defect that both wedges the burst's own time limit and would wedge `discover`.
+         If (a) fails: target code was not instrumented for fuzzer feedback — diagnose build vs. design.
+         If (b) fails but (a) passes: seed corpus is too narrow — route to `harness_design` for seed-corpus revision.
+         If (c) fails: route `rejected_design` with directive "cap input size (`-max_len`) and move per-input heavyweight setup (full re-init, process spawn, multi-connection sweep) out of the fuzz entry point."
+      6. **Stateful session sanity.** If the harness supports multi-step sessions, run a short sequence; verify state persists.
+      7. **Branch-level audit coverage exists.** Confirm the audit tool reports branch data, not just line counts.
+
+      Do NOT report `approved` with caveats. A harness whose fuzzer-feedback does not reach the target code is not validated — that is exactly the silent failure this step exists to catch.
+
+      ## Verdicts
+
+      - **approved**: All seven steps passed, including the linkage audit and the fuzzer-feedback thresholds.
+      - **rejected_build**: Implementation bugs the build agent can fix without changing the design — compile errors, driver defects, session reset broken, coverage extraction not wired up, fuzzer-feedback flags in the design but missing from the actual compile invocation. Route: back to `harness_build`.
+      - **rejected_design**: Design flaws the build agent cannot fix — wrong call chain, wrong tooling, tier insufficient, target linked as a prebuilt artifact that cannot be rebuilt with instrumentation, seed corpus too narrow. Route: back to `harness_design`.
+
+      When the fuzzer-feedback (a) check fails, classify by cross-referencing `design.md` — the same observed symptom (wrapper-only instrumentation) can be either build or design depending on what the design asked for:
+      - Design specified rebuilding the target with feedback flags AND the build's compile invocation actually did that, but flags didn't land (e.g., wrong `CFLAGS` scope) → `rejected_build` (implementation gap).
+      - Design specified the flags correctly and the build's compile invocation omits them → `rejected_build`.
+      - Design accepted a prebuilt target / system library / vendored archive as the attack surface and provided no rebuild step → `rejected_design`, switch to a tool that handles full-binary instrumentation or rebuild from source.
+      - Project build system resists whole-target rebuild AND the design named no fallback on a different mechanism → `rejected_design`, reconsider tool choice and pick the design's fallback (or add one if missing).
+
+      Write validation results — including the recorded fuzzer-feedback metric values — to `.workflow/harness_validate/validation.md`.
+    inputs:
+      - harness_design
+      - harness_build
+    outputs:
+      - harness_validate
+    transitions:
+      - to: orchestrator
+        when:
+          verdict: approved
+      # Ordered before the rejection transitions so the cap wins on the Nth visit.
+      - to: harness_validate_escalation
+        guard: isStateVisitLimitReached
+      - to: harness_build
+        when:
+          verdict: rejected_build
+      - to: harness_design
+        when:
+          verdict: rejected_design
+
+  discover:
+    type: agent
+    description: Hypothesis-driven vulnerability research using the harness
+    persona: global
+    skills:
+      - memory-safety-c-cpp
+    prompt: |
+      You are a vulnerability researcher. You have a working instrumented harness for the code in scope. Read the task description, the analysis, harness build instructions, and investigation journal.
+
+      **First action**: read the "Scoping from the previous agent" section at the top of this message. Its Directive subsection is the orchestrator's authoritative description of WHAT to test this round — specific hypothesis, trigger conditions, input values to sweep, component scope. If the scoping section is missing or the directive is vague ("try something reasonable", generic exploration without a hypothesis), STOP and report back with an `escalate`-style agent_status — do not improvise hypotheses from the analysis or journal alone. Your value comes from executing scoped experiments the orchestrator asked for, not from re-deriving scope each round.
+
+      Your goal: find a vulnerability matching the task's scope, vulnerability class, and threat model, by running experiments through the harness and observing results. The task defines what counts as a finding — for example, "externally reachable memory corruption in this file" is very different from "local privilege escalation via any user-reachable path in this directory" or "authentication bypass in these endpoints." Let the task's definition drive what inputs you craft, what behaviors you watch for, and what counts as exploitable.
+
+      ## First action: verify the harness
+
+      Before forming hypotheses, run the harness with a baseline input and read the coverage output. Confirm:
+      - The harness executes without errors
+      - The target function appears in the coverage report
+      - You can observe which branches were taken
+
+      If the harness doesn't work, set verdict to rejected immediately. Do not attempt to find vulnerabilities by reading code alone — that is not your job. Your value comes from execution-based evidence.
+
+      ## Hypothesis-driven discovery
+
+      The orchestrator's directive tells you what to test. Use the harness to:
+
+      1. **Design an input sequence** that exercises the hypothesized code path. Use the analysis's function catalog for guidance on types, boundaries, and assumptions.
+      2. **Send it through the harness** and observe results. Read coverage to see which lines and branches were hit. Check for sanitizer output, crashes, and invariant violations. If you run ANY work in the background (fuzz campaign, build, etc.), wait on the launched PID (`cmd & PID=$!; wait "$PID"`); never poll with a `pgrep -f <name>`/`sleep` loop (`pgrep -f` matches the waiter's own command line and your prompt-bearing agent process, so the loop never exits) and never poll a hardcoded log/output path you did not capture from that same launch.
+      3. **Refine or pivot.** If coverage shows you missed the target path, adjust inputs to hit the right branch. If you reached it with no violation, try variations before moving to a new hypothesis.
+      4. **Repeat systematically.** Work through the hypotheses in the orchestrator's directive.
+
+      Adversary-maximal evidence is not "the named site fired." It includes characterizing the primitive's extent — exercising each scaling axis named in the relevant surface skill's primitive-extent taxonomy (for native C/C++ memory-safety primitives, see the `memory-safety-c-cpp` skill's *Primitive-extent scaling axes* section; the canonical per-class enumeration also appears in `vulnerability-triage`'s *Primitive extent* section, which triage uses to score). For each axis the directive scopes, run the trigger at least at one boundary point that demonstrates the primitive's behavior at that axis's value, not just the minimum. Document what was exercised and what was not — the findings doc must record the demonstrated extent per axis, so triage can score on what was actually run.
+
+      The minimum PoC that fires the named site is necessary but not sufficient. A finding with only minimum-trigger evidence will route back from triage with an `insufficient` verdict naming the un-explored axis.
+
+      ## Verdicts
+
+      - **approved**: An exploitable condition fired — sanitizer error, controlled crash, invariant violation, or direct evidence the hypothesized bug triggered. Document the reproduction input, coverage proof, and severity.
+      - **rejected**: The harness is insufficient — can't reach the target, missing protocol feature, broken infrastructure.
+      - **blocked**: Hypothesis did not fire despite a completed search. You may only return `blocked` if (a) coverage shows the target code was executed, AND (b) you swept the input range relevant to the hypothesis — fuzzing for value-dependent claims (sizes, offsets, indices, counters), bounded enumeration for discrete claims (protocol states, flag combinations, auth paths). "I read the code and it looks mitigated" is not `blocked` — it's `rejected` with a request to redesign the harness. If neither fuzzing nor enumeration applies to this hypothesis, name the reason explicitly in your findings doc. **Invariant-only mitigations are not `blocked`.** If you attribute non-impact to an invariant your harness had to disable to reach the site — a lock/serialization or single-threaded dispatch contract, an upstream guard, a runtime/allocator check, or an earlier sanitizer abort that prevents reaching a downstream sink — you may return `blocked` only if you ALSO ran the trigger under a configuration where that invariant is present and showed the effect absorbed there. Disabling the invariant to reach the site and then citing it as the mitigation is circular; if you cannot build an invariant-present config that still reaches the site, return `blocked` only for the part you exercised and name the un-exercised invariant explicitly.
+
+      Write per-hypothesis findings to `.workflow/discoveries/findings.<id>.md` where `<id>` is the orchestrator's hypothesis ID — e.g. `findings.h1.md`, `findings.h2.md`. Do not collapse hypotheses into one file. Append after each experiment (hypothesis, input, harness command, result) before starting the next one — do not batch writes to the end, so a crash or rate-limit preserves the round's work. If a hypothesis's findings file already exists from a prior run, read it first and skip experiments whose results are already recorded; do not re-read other hypotheses' files unless the directive scopes you to them.
+    inputs:
+      - analysis
+      - harness_build
+      - journal
+      - discoveries?
+    outputs:
+      - discoveries
+    transitions:
+      - to: orchestrator
+
+  differential_validate:
+    type: agent
+    description: Diagnoses divergence between isolated tests and live system
+    persona: global
+    skills: none
+    prompt: |
+      You are a systems debugging specialist. A lower-tier harness produced different results than a higher-tier harness or the full system, OR the harness behaves differently than expected based on code analysis.
+
+      **First action**: read the "Scoping from the previous agent" section at the top of this message. Its Directive subsection tells you which divergence to diagnose and what hypothesis to test. If the scoping section is missing or the directive does not identify a specific divergence, STOP and report back with an `escalate`-style agent_status rather than picking a divergence to chase.
+
+      Read the investigation journal at `.workflow/journal/journal.md` and the per-hypothesis discovery findings in `.workflow/discoveries/findings.h*.md`.
+
+      Your job: determine WHY results diverge between tiers or between the harness and expected behavior.
+
+      Instrument the live system to observe actual behavior at the vulnerability site. Common divergences:
+      - **Input transformation**: firewalls stripping options, proxies rewriting headers, serializers normalizing data
+      - **State differences**: prior operations, initialization, caching, connection state
+      - **Timing/ordering**: async processing, buffering, interrupt handling
+      - **Type/encoding**: byte order, padding, alignment, type promotion differences
+      - **Environment**: missing dependencies, different compiler flags, optimization levels
+
+      Use the harness coverage data to confirm whether the vulnerable function is even reached. If coverage shows zero hits on the target function, the problem is reachability, not values.
+
+      Add debug output (printf/logging) to the vulnerable function if needed to observe intermediate values.
+
+      Write your diagnosis to `.workflow/differential/diagnosis.md`. Include: the specific divergence found, which layer is wrong (lower-tier test assumptions vs higher-tier behavior), and what needs to change.
+    inputs:
+      - journal
+      - discoveries
+      - harness_build
+    outputs:
+      - differential
+    transitions:
+      - to: orchestrator
+
+  triage:
+    type: agent
+    description: Independent validation and severity assessment of findings
+    persona: global
+    skills:
+      - vulnerability-triage
+      - memory-safety-c-cpp
+    prompt: |
+      You are a senior vulnerability triager. Your job is to **interpret** what `discover` demonstrated and translate it into threat-model language. You do NOT run fresh experiments — you may reproduce discover's experiments to confirm them, but if evidence is too thin for the severity a finding would warrant, set verdict `insufficient` and name the specific gap for discover to close next. Read the per-hypothesis `.workflow/discoveries/findings.h*.md` files (one per hypothesis) and `.workflow/journal/journal.md`. Read only the `findings.hN.md` files for the hypotheses you are triaging this round.
+
+      **First action**: read the "Scoping from the previous agent" section at the top of this message. If it is absent, triage every hypothesis with a `.workflow/discoveries/findings.hN.md` file. If it is present but vague, STOP and report back with an `escalate`-style agent_status.
+
+      The methodology — the core anchoring rule, detector-vs-impact distinction, the eleven-item interpretation rubric, delegation transparency, primitive-extent scaling, the disqualifier taxonomy (D-0..D-4), CVSS Achievable / Environmental scoring conventions, hedging-language elimination, falsification asymmetry, common pitfalls, and the insufficient-verdict gap-statement bar — lives in the `vulnerability-triage` skill. Apply it.
+
+      ## Verdicts
+
+      - **approved**: Evidence supports a concrete severity. All eleven rubric items completed with consistent conclusions.
+      - **insufficient**: Evidence does not support the severity the finding would warrant, OR `discover` has not demonstrated the attacker-visible effect at all. Notes MUST name the specific gap per the skill's insufficient-verdict discipline (parameter to sweep, mitigation to exercise, adjacency to verify, hardening profile to rebuild under, disqualifier label where applicable). The orchestrator needs a directive it can hand to `discover` verbatim.
+      - **escalate**: Evidence is contradictory, scope is unclear, or severity requires human judgment (known class with possible in-flight CVE, policy question about threat model).
+
+      Write the per-hypothesis triage report to `.workflow/triage/triage.<id>.md` where `<id>` matches the hypothesis ID from `findings.<id>.md` — e.g. `triage.h1.md`, `triage.h2.md`. Each file must present all eleven rubric items; the verdict must be traceable to them. Do not collapse hypotheses into one file.
+    inputs:
+      - discoveries
+      - harness_build
+      - journal
+    outputs:
+      - triage
+    transitions:
+      - to: orchestrator
+
+  conclude:
+    type: agent
+    description: Writes final investigation report from all artifacts
+    persona: global
+    skills: none
+    prompt: |
+      You are a security report writer. You **translate** investigation artifacts into a final report — you do not re-assess severity, re-interpret evidence, or manufacture framing that isn't already present in the inputs.
+
+      Read these artifacts:
+      - `.workflow/journal/journal.md` — the investigation journal
+      - `.workflow/analysis/analysis.md` — structural analysis
+      - `.workflow/discoveries/` — live findings (if present)
+      - `.workflow/differential/` — differential analysis (if present)
+      - `.workflow/triage/` — triage results (if present)
+
+      ## Hard rules (read before writing)
+
+      **Severity fidelity.** Severity for each finding MUST match triage's assessment in the corresponding `.workflow/triage/triage.hN.md` verbatim — same CVSS vector, same numeric score, same justification. Do not re-score. Do not strengthen "Medium" into "Medium-High" for emphasis. Do not add confidentiality-impact claims triage did not make. If triage did not assign a severity (e.g., finding returned `insufficient` or escalate), the report does not assign one either.
+
+      **Exploitability requires demonstration.** A finding may be called "exploitable" only when the hypothesis's `discoveries/findings.hN.md` documents an observation of the attacker-visible effect AND triage confirmed it. Detector output from an isolated harness (sanitizer, fuzz crash, static analyzer hit, tainted-flow report, assertion failure) proves the detector caught an anomaly — not exploitability. Findings backed only by detector evidence go under "Findings without demonstrated impact," NOT "Confirmed findings."
+
+      **Contradiction handling.** When evidence across rounds disagrees — a Tier-1 detector fires but the Tier-3 effect is absorbed by padding / a schema validator / a sanitizing middleware, or discover observed round-tripped attacker input rather than target state — call out the contradiction in the finding's "Evidence chain" subsection AND score at the **weaker** demonstrated level. Do not reconcile with "the vulnerability is real, the sanitizer confirmed it" — that is papering over. If the weaker observation is "no attacker-visible impact," the finding belongs under "Findings without demonstrated impact."
+
+      **No invented framing.** Phrases like "three-tier evidence chain," "fully validated," or "directly observable" may appear in the report only if they appear in the source artifacts AND the underlying evidence supports them. Write gaps as gaps.
+
+      **Executive summary discipline.** Claims in the summary must be traceable line-by-line to findings below. If the summary says "three vulnerabilities confirmed exploitable," three findings must meet the bar above. If fewer, fix the summary — do not promote findings up from "Findings without demonstrated impact."
+
+      ## Report layout — split index + per-hypothesis files
+
+      The report is split into a thin index file and one self-contained file per hypothesis. All files live in `.workflow/report/`.
+
+      - `.workflow/report/report.md` — the index. Cross-cutting only: executive summary, ranked hypothesis table, cross-cutting recommendations, links to the per-hypothesis files. The index does NOT duplicate per-hypothesis evidence chains, CVSS justifications, or reproduction steps — those live in the hypothesis files.
+      - `.workflow/report/report.hN.md` — one file per hypothesis, where `N` is the hypothesis ID that flowed through triage and the journal (`h1`, `h2`, ...). Each file is self-contained: a reader who opens only `report.h2.md` should be able to understand the finding without consulting `report.md` or other hypothesis files.
+
+      You MUST write the index AND every hypothesis file the artifacts cover (one `report.hN.md` per hypothesis with a `triage/triage.hN.md` or `discoveries/findings.hN.md`). Do not collapse multiple hypotheses into one file.
+
+      ### Index file (`report.md`)
+
+      The first line of `report.md` MUST be a single `Updated:` line listing the per-hypothesis files authored or modified in this run, comma-separated, in the form `Updated: report.h1.md, report.h3.md` (or `Updated: none` if only the index changed). This line is the on-disk source of truth that downstream `review` and `report_review` consult to scope incremental re-reads. On a fresh first authoring it lists every hypothesis file you created. On revision re-entry it lists only the subset you re-authored. Do NOT omit it — when missing, downstream review must fall back to a full re-read of every hypothesis file.
+
+      After the `Updated:` line, the index has the following sections:
+
+      #### Executive Summary
+
+      One paragraph: what was investigated, what was found (or not found), what severity was demonstrated (not theoretical). Must be faithful to the per-hypothesis files — no claims a hypothesis file does not support.
+
+      #### Hypothesis ranking
+
+      One table, one row per hypothesis. Columns: `ID` (h1, h2, ...), `Title` (short noun phrase), `Severity` (verbatim from triage, or "n/a" if triage did not assign one), `Status` (one of: `confirmed`, `no demonstrated impact`, `mitigated`, `insufficient`), `File` (link to `report.hN.md`).
+
+      Sort by severity then by status (confirmed first, then no-demonstrated-impact, then mitigated, then insufficient). The status values map to the same bars as the per-hypothesis sections below.
+
+      #### Cross-cutting recommendations
+
+      Recommendations that apply across multiple hypotheses or to the codebase as a whole — defense-in-depth additions, missing build/test infrastructure, hardening profiles to enable. Per-hypothesis fixes belong in the hypothesis files, not here.
+
+      #### Investigation coverage
+
+      The first element of this section MUST be a per-hypothesis ledger; the supporting bullets sit alongside it, not in place of it.
+
+      ##### Hypothesis ledger
+
+      List every analyze-produced hypothesis (`h1`, `h2`, ...) with its terminal status — one of `confirmed`, `harness-tested-and-rejected`, or `deferred (reason: ...)`. The ledger here mirrors the orchestrator's notes-channel ledger and uses the same allowed deferral reasons enumerated in the orchestrator's "Completing the investigation" paragraph: (a) out-of-scope per task description, (b) intrinsic capability the workflow cannot acquire (does NOT cover fixable harness-build dependencies — those route through `harness_design`), (c) duplicate of another confirmed hypothesis.
+
+      Coherence rules (a missing or violated rule is a fail and triggers FORCE_REVISION at review):
+
+      - The IDs in this ledger MUST match the `report.hN.md` filenames. A `confirmed` hypothesis without a corresponding `report.hN.md` is a fail, and a `report.hN.md` without a ledger entry is a fail.
+      - A `deferred (b)` entry whose underlying issue was a missing apt-installable dependency, missing pip package, missing build flag, missing codec library that exists as a package, or any other fixable harness-build problem is a fail (incoherent — should have routed through `harness_design` for the environment fix instead of deferring).
+      - Every hypothesis the analysis enumerates MUST appear in the ledger; silent omission is forbidden.
+
+      ##### Supporting coverage notes
+
+      - Code paths exercised via harness, including coverage percentages as reported
+      - What was NOT tested and why (time limits, infrastructure gaps, skipped states like discover)
+      - If the workflow skipped states that the routing rules call for (e.g., `discover` was never invoked), call that out here — it is a coverage gap even when the state machine accepted the path.
+
+      ### Per-hypothesis file (`report.hN.md`)
+
+      Each hypothesis file MUST classify itself with a top-line `Status:` matching one of the four bars below, then include the relevant subsections. Keep the file self-contained — re-state the hypothesis title, location, and trigger mechanism rather than referring readers to the index.
+
+      Hard rules apply per-file (severity fidelity, exploitability bar, contradiction handling, no invented framing — see the rules above). Section headings:
+
+      - `Status:` line — `confirmed` | `no demonstrated impact` | `mitigated` | `insufficient`
+      - Triage verdict and rationale (verbatim from this hypothesis's `triage/triage.hN.md`). For `mitigated` and `insufficient` files, triage may not have run at all — in that case state "Triage not invoked" and explain why (typically: discover returned `blocked` with execution evidence, so the orchestrator routed to `conclude` without dispatching `triage`).
+      - Evidence summary — what each round contributed for this hypothesis, what it demonstrated, contradictions across rounds (resolved at the weaker level)
+      - Primitive characterization — what kind of primitive the bug yields, and the demonstrated extent along each axis discover exercised (per `discover`'s adversary-maximal-evidence requirement)
+      - **Severity section — varies by status.** `confirmed` and `no demonstrated impact` files carry an *Achievable severity* subsection: the CVSS vector, score, and justification from triage, verbatim. `mitigated` and `insufficient` files OMIT *Achievable severity* entirely and instead carry a *Why no demonstrated severity* subsection explaining why the file does not anchor a score (mitigation absorbed the primitive before attacker-visible effect; evidence too thin for a severity assessment; etc.). Do NOT assign a severity for these statuses — they have not earned one. The hypothesis-ranking row in `report.md` shows `n/a` for severity in these cases.
+      - Mitigations — code-level fixes for this hypothesis, and any caller-side / configuration-level mitigations that apply. From triage when present, otherwise from `discover` or `analyze` artifacts. Not re-derived.
+      - References — file paths (file:line), CWE classification, related hypotheses if applicable
+
+      The four status bars (apply per-hypothesis, in the file's `Status:` line):
+
+      - **confirmed** — this hypothesis's `discoveries/findings.hN.md` documents an attacker-visible-effect observation at the severity triage assigned, AND its `triage.hN.md` returned `approved`. Without both, the file is NOT confirmed.
+      - **no demonstrated impact** — a detector flagged something (sanitizer, fuzz crash, static analyzer hit, tainted-flow report, assertion failure) but `discover` did not demonstrate an attacker-visible effect, or `triage` returned `insufficient`. The Mitigations section here describes the code-quality fix; the Achievable severity section names the gap that would need to be closed (parameter to sweep, mitigation to exercise, etc.) for this to become `confirmed`.
+      - **mitigated** — `discover` returned `blocked` with execution evidence the mitigation holds: coverage of the mitigation code AND a completed input sweep over the hypothesis's value range. Mitigations section identifies the mitigation's location and call-site coverage. The file OMITS *Achievable severity* and instead carries *Why no demonstrated severity*. Triage may not have been invoked for `mitigated` hypotheses (the orchestrator routes blocked-with-evidence cases straight to `conclude`), so do not require triage output for these. Hypotheses whose mitigation rests on text-only reasoning are NOT `mitigated` — they are `no demonstrated impact` with the mitigation analysis flagged as unverified.
+      - **insufficient** — triage returned `insufficient` or `escalate`, and the hypothesis is still open. The file OMITS *Achievable severity* and instead carries *Why no demonstrated severity*. Evidence summary names the specific gap.
+
+      ## Revision discipline (FORCE_REVISION re-entry)
+
+      When you re-enter `conclude` after a FORCE_REVISION, the orchestrator's directive in the "Scoping from the previous agent" section names which hypotheses changed and what to fix. ALSO read `.workflow/report_review/review.md` if present — it contains the LLM reviewer's per-checklist failure detail and any human-gate rejection text the orchestrator's directive may have summarized away. The directive scopes WHAT to re-author; `report_review/review.md` carries the specific gap descriptions you need to fix. Re-author ONLY the named `report.hN.md` files. Update `report.md` only if the change affects the executive summary, hypothesis ranking, or cross-cutting recommendations — leave it unchanged otherwise. Whatever set you re-author, refresh the `Updated:` line at the top of `report.md` to list exactly that subset (or `Updated: none` if only `report.md` itself changed).
+
+      Even on first authoring, your `agent_status` `notes` field MUST list the per-hypothesis files written or updated this round, in the form `report.hN.md` (comma-separated). On a fresh run that is every hypothesis file you created; on revision it is the subset you re-authored. Downstream review uses this list to scope incremental review, so omitting it forces a full re-read.
+
+      ## Verdict
+
+      Set verdict to `complete`. Your agent_status `notes` field should be a 1–2 sentence factual summary of the report's conclusion (mirror the Executive Summary, do not exaggerate), followed on a separate line by `Updated: report.h1.md, report.h3.md` listing the per-hypothesis files written or updated this round. This `notes` line is a convenience mirror for the next state's prompt context — the authoritative `Updated:` line lives at the top of `report.md` itself (see Index file requirements above), and downstream review reads the on-disk line, not `notes`.
+    inputs:
+      - journal
+      - analysis
+      - discoveries?
+      - differential?
+      - triage?
+      - report_review?
+    outputs:
+      - report
+    transitions:
+      - to: review
+
+  review:
+    type: agent
+    description: LLM review of the final report before the human gate — catches scope drift, evidence-headline contradictions, and writeup errata
+    persona: global
+    maxVisits: 2
+    skills: none
+    prompt: |
+      You are the report reviewer. The report is split into an index file (`.workflow/report/report.md`) and one self-contained file per hypothesis (`.workflow/report/report.hN.md`).
+
+      ## What to read
+
+      Always read: `.workflow/report/report.md` (index), `.workflow/journal/journal.md`, `.workflow/analysis/analysis.md`, plus the per-hypothesis `.workflow/discoveries/findings.h*.md` and `.workflow/triage/triage.h*.md` and `.workflow/differential/diagnosis.md` when present.
+
+      Per-hypothesis file scoping:
+
+      Read `.workflow/report/report.md` FIRST. The first line is an `Updated:` line listing the per-hypothesis files authored or modified in the most recent `conclude` round. This on-disk line — not the directive — is the authoritative source for scoping re-reads on the `conclude → review` hop (the orchestrator does not sit between those states, so `Dirty hypotheses:` and the propagated `Notes` may not reach you).
+
+      - **First-ever review** (the index's `Updated:` line is missing, or this is the first run and every hypothesis file is freshly authored): read EVERY `.workflow/report/report.h*.md` file. Full review.
+      - **Re-review after a rewrite** (the index's `Updated:` line names a subset of `report.hN.md` files): read ONLY those `report.hN.md` files plus the index. The unchanged hypothesis files were not touched and do not need re-review.
+      - **Edge case** (`Updated: none`, meaning the index changed but no hypothesis file did): re-read only the index.
+
+      If `Updated:` is malformed or ambiguous, fall back to reading all hypothesis files.
+
+      List the `.workflow/report/` directory at the start of every run to confirm which hypothesis files exist. The index's hypothesis-ranking table should name one `report.hN.md` per row; if a row points at a missing file, that's an errata fail (item 7).
+
+      If `discoveries/` is absent, no hypothesis file may carry `Status: confirmed` and the index's Investigation coverage section must call out that `discover` was not invoked.
+
+      Your job is to catch the failures that have historically reached human review and required FORCE_REVISION. You are NOT re-doing the investigation. You are NOT re-scoring severity. You ARE checking that the report's claims match the artifacts the report cites.
+
+      ## Checklist
+
+      Apply each item to the index file and to every hypothesis file in scope (full set on a fresh run, named subset on incremental review). Each item passes or fails on its own. ONE failure means the report is not ready.
+
+      1. **Headline matches the artifacts.** The Executive Summary's load-bearing claim and the hypothesis-ranking table agree with the per-hypothesis `discoveries/findings.h*.md` and `triage/triage.h*.md`. A hypothesis with execution evidence in `discoveries/` (POC, sanitizer trace, observed attacker-visible effect, runtime sink reached) whose `report.hN.md` carries `Status: no demonstrated impact` or whose row is omitted from the ranking table is a fail — the canonical "buried CVE" pattern. If the report narrows the threat model to exclude an in-`discoveries/` hypothesis, the narrowing must be stated explicitly in the index AND the excluded hypothesis must still appear in the ranking table, not buried.
+
+      2. **No contradiction-papering.** When `discoveries/`, `differential/`, `triage/`, or earlier rounds disagree with a hypothesis file's claims, the file calls out the contradiction in its Evidence summary AND scores at the weaker demonstrated level (per `conclude`'s "Contradiction handling" hard rule). Reconciliation by rhetoric ("the vulnerability is real, the sanitizer confirmed it") is a fail.
+
+      3. **Severity matches triage verbatim.** Each `report.hN.md` with `Status: confirmed` or `Status: no demonstrated impact` must carry the CVSS vector, score, and justification from the corresponding `triage/triage.hN.md` exactly. Files with `Status: mitigated` or `Status: insufficient` MUST NOT carry an *Achievable severity* subsection — they carry *Why no demonstrated severity* instead, and their hypothesis-ranking row in the index shows `n/a`. Triage may legitimately not have been invoked for `mitigated` files (orchestrator routes blocked-with-evidence cases straight to `conclude`); for those, "no triage" does not block the status. For `confirmed` and `no demonstrated impact` files, triage must have run — if `triage` was never invoked, those statuses cannot stand. Re-derived severity, rounded scores, or strengthened wording ("Medium-High" where triage said "Medium") is a fail. The index's Hypothesis ranking severity column must match the per-hypothesis files (with `n/a` for the `mitigated` / `insufficient` rows).
+
+      4. **Exploitability bar respected.** A hypothesis file may carry `Status: confirmed` only when BOTH a documented attacker-visible-effect observation in the corresponding `discoveries/findings.hN.md` AND an `approved` triage verdict apply to that hypothesis. Detector-only evidence — any tool that flagged something without a discover-demonstrated effect (sanitizer, fuzz crash, static analyzer, tainted-flow tracer, schema-validator alert, assertion failure, etc.) — must carry `Status: no demonstrated impact`; promoting it is a fail.
+
+      5. **Out-of-scope side hypotheses stay honest.** Every hypothesis the report demotes (e.g., omitted from the ranking table, marked out-of-scope inside its file) is actually outside the task's scope as stated by the task description. A hypothesis moved out of the ranking purely to keep the headline clean — when the task description, threat model, or triage would treat it as in-scope — is a fail. When in doubt, lean toward in-scope: the human will rather see an extra hypothesis promoted than a real one demoted.
+
+      6. **Coverage gaps stated as gaps.** The index's Investigation coverage section names what was NOT tested and why. Skipped routing states (e.g., `discover` never invoked, `triage` never invoked) are called out per `conclude`'s "Investigation coverage" guidance — silently omitting is a fail.
+
+      6a. **Hypothesis ledger present and coherent.** The index's Investigation coverage section MUST carry a per-hypothesis ledger covering every analyze-produced hypothesis (`h1`, `h2`, ...) with a terminal status — `confirmed`, `harness-tested-and-rejected`, or `deferred (reason: ...)`. Every `deferred` entry MUST name a reason from the orchestrator's allowed set: (a) out-of-scope per task description, (b) intrinsic capability the workflow cannot acquire, (c) duplicate of another confirmed hypothesis. A `deferred (b)` entry whose underlying issue was a fixable harness-build problem (missing apt/pip dependency, missing build flag, missing codec library that exists as a package) is a fail (incoherent — should have routed through `harness_design` for the environment fix). A hypothesis enumerated in `analysis.md`'s cross-cutting section but missing from the ledger is a fail (silent drop). This is the canonical "premature complete on first hit" failure: a confirmed h1 plus an unmentioned h2 is a fail, not an approval. FORCE_REVISION when this item fails — it is the human gate's stand-in too.
+
+      7. **Errata clean.** Round numbers, role-visit counts, item-ordering inside redirection lists, file paths (container vs. host layout), and cross-section references between the index and hypothesis files agree with each other and with the journal. Hypothesis-ranking rows that link to non-existent `report.hN.md` files, hypothesis files whose `Status:` line disagrees with the index ranking, off-by-one round numbers, and path strings the reader cannot resolve in their environment are fails — these have all reached prior human reviewers.
+
+      ## Verdicts
+
+      - **approved**: All seven items pass for every file in scope. Write `.workflow/report_review/review.md` listing what you verified (one bullet per checklist item) and which `report.hN.md` files were reviewed this round (full set vs. named subset). Concise.
+      - **rejected**: One or more items fail. Write `.workflow/report_review/review.md` listing each failure by checklist number, the specific file (`report.md` or `report.hN.md`), the specific problem, and what the fix needs. The fix instruction MUST name which `report.hN.md` files need re-authoring (and whether `report.md` itself needs an update) so the orchestrator can route a scoped revision. Be concrete enough that the orchestrator can route per its rules without re-deriving the gap.
+
+      ## Visit-cap handling
+
+      The state machine routes review → `report_review` (the human gate) when the visit cap fires, even if your most recent verdict was `rejected`. This is structurally identical to the `approved` transition, so the human gate cannot tell from the transition alone whether the loop terminated cleanly or was forced out. To prevent the human from mistaking a cap-out for an approval, when you are on your final allowed visit AND would emit `rejected`, write a short "review-cap-reached" header at the top of `.workflow/report_review/review.md` BEFORE the per-checklist failure list. State explicitly that the review loop ran out of visits with unresolved failures, that the report was NOT approved, and that the human is being asked to decide whether to FORCE_REVISION (return to orchestrator with the unresolved failures) or APPROVE (accept the report despite the open items). Keep the rest of the rejection content exactly as a normal `rejected` would write it.
+
+      Do NOT modify any file under `.workflow/report/` yourself. The orchestrator routes the rejection.
+    inputs:
+      - report
+      - discoveries?
+      - differential?
+      - triage?
+      - journal
+      - analysis
+    outputs:
+      - report_review
+    transitions:
+      - to: report_review
+        when:
+          verdict: approved
+      # Ordered before the rejection transition so the cap wins on the Nth visit;
+      # a deadlocked review loop lands in the human gate rather than spinning further.
+      - to: report_review
+        guard: isStateVisitLimitReached
+      - to: orchestrator
+        when:
+          verdict: rejected
+
+  report_review:
+    type: human_gate
+    description: |
+      Human review of the final vulnerability report. The report is split: read `.workflow/report/report.md` (the index) for the executive summary and hypothesis ranking, then drill into the per-hypothesis writeups at `.workflow/report/report.hN.md`. The first line of `report.md` is an `Updated:` line naming the `report.hN.md` files authored or modified in the latest `conclude` round — that on-disk line is the authoritative scoping signal (the human gate sees only artifacts, not orchestrator directives). On a fresh review, read every hypothesis file. On revision, read the index plus the `report.hN.md` files named in the index's `Updated:` line (cross-referenced with the LLM reviewer's `report_review/review.md`) — unchanged hypothesis files were not touched. When emitting FORCE_REVISION, your feedback prompt SHOULD name which `report.hN.md` files need re-authoring (and whether the index itself needs an update) so the orchestrator's next directive can scope the conclude re-entry to those files. Before approving, verify the index's "Investigation coverage" section contains a per-hypothesis ledger covering every analyze-produced hypothesis with a terminal status (`confirmed` / `harness-tested-and-rejected` / `deferred (reason: ...)`) — and FORCE_REVISION when the ledger is missing, when it contains silent omissions (a hypothesis enumerated in `analysis.md`'s cross-cutting section but not in the ledger), or when it carries an incoherent `deferred (b)` entry whose underlying issue was a fixable harness-build problem (missing apt/pip dependency, missing build flag, missing codec library that exists as a package).
+    acceptedEvents:
+      - APPROVE
+      - FORCE_REVISION
+      - ABORT
+    present:
+      - report
+      - report_review?
+      - discoveries
+      - triage
+      - journal
+    transitions:
+      - to: done
+        event: APPROVE
+      - to: orchestrator
+        event: FORCE_REVISION
+      - to: aborted
+        event: ABORT
+
+  done:
+    type: terminal
+    description: Investigation complete
+    outputs:
+      - report
+      - triage
+      - discoveries
+      - journal
+
+  aborted:
+    type: terminal
+    description: Investigation aborted