trailmark: add assurance workflow skills

.claude-plugin/marketplace.json

@@ -225,8 +225,8 @@
     },
     {
       "name": "trailmark",
-      "version": "0.8.3",
-      "description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, and projects SARIF/weAudit/binary findings onto code graphs. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, or augmenting audits with static analysis findings.",
+      "version": "0.9.0",
+      "description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, projects SARIF/weAudit/binary findings onto code graphs, triages single findings with graph evidence, gates branch diffs for structural review regressions, and expands seed findings into variant-neighborhood candidates. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, augmenting audits with static analysis findings, deciding whether one candidate issue is reachable, reviewing graph-level PR risk, or seeding variant analysis.",
       "author": {
         "name": "Scott Arciszewski",
         "url": "https://github.com/tob-scott-a"

plugins/trailmark/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "trailmark",
-  "version": "0.8.3",
-  "description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, and projects SARIF/weAudit/binary findings onto code graphs. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, or augmenting audits with static analysis findings.",
+  "version": "0.9.0",
+  "description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, projects SARIF/weAudit/binary findings onto code graphs, triages single findings with graph evidence, gates branch diffs for structural review regressions, and expands seed findings into variant-neighborhood candidates. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, augmenting audits with static analysis findings, deciding whether one candidate issue is reachable, reviewing graph-level PR risk, or seeding variant analysis.",
   "author": {
     "name": "Scott Arciszewski",
     "url": "https://github.com/tob-scott-a"

plugins/trailmark/README.md

@@ -47,8 +47,11 @@ uv pip install trailmark
 | `genotoxic` | Triage mutation testing results using graph analysis — classify survived mutants as false positives, missing tests, or fuzzing targets |
 | `vector-forge` | Mutation-driven test vector generation — find coverage gaps via mutation testing, then generate Wycheproof-style vectors that close them |
 | `graph-evolution` | Compare code graphs at two snapshots to surface security-relevant structural changes text diffs miss |
+| `trailmark-review-gate` | Apply PASS/WARN/FAIL/UNKNOWN structural gate rules to branch, PR, fix, or release diffs |
 | `mermaid-to-proverif` | Convert Mermaid sequence diagrams into ProVerif formal verification models |
 | `audit-augmentation` | Project SARIF, weAudit, and v0.4 binary-analysis graph findings onto code graphs as annotations and subgraphs |
+| `trailmark-finding-triage` | Triage one finding, SARIF result, weAudit annotation, suspicious function, or report excerpt with reachability, taint, privilege-boundary, and blast-radius evidence |
+| `trailmark-variant-neighborhood` | Expand one seed issue into graph-derived variant candidates for variant-analysis, Semgrep, CodeQL, or manual review |
 | `trailmark-summary` | Quick structural overview (auto-detected languages, entry points, dependencies) for vivisect/galvanize |
 | `trailmark-structural` | Full structural analysis with all pre-analysis passes (blast radius, taint, privilege boundaries, complexity) |
 
@@ -70,9 +73,12 @@ trailmark/
     │   └── references/
     ├── graph-evolution/              # Structural diff
     │   └── scripts/graph_diff.py
+    ├── trailmark-review-gate/         # Structural review gates
     ├── mermaid-to-proverif/          # Sequence diagram → ProVerif
     │   └── examples/
     ├── audit-augmentation/           # SARIF/weAudit integration
+    ├── trailmark-finding-triage/      # Single-finding evidence packets
+    ├── trailmark-variant-neighborhood/ # Variant candidate neighborhoods
     ├── trailmark-summary/            # Quick overview for vivisect/galvanize
     └── trailmark-structural/         # Full structural analysis
 ```
@@ -84,3 +90,4 @@ trailmark/
 | `mutation-testing` | Guidance for running mutation frameworks (mewt, muton) — use before genotoxic for triage |
 | `differential-review` | Text-level security diff review — complements graph-evolution's structural analysis |
 | `audit-context-building` | Deep architectural context before vulnerability hunting |
+| `variant-analysis` | Search for related candidates after trailmark-finding-triage identifies a repeatable root cause |

plugins/trailmark/skills/audit-augmentation/SKILL.md

@@ -27,6 +27,7 @@ also import an external binary-analysis graph JSON export via
 - Cross-referencing static analysis findings with blast radius or taint data
 - Querying which functions have high-severity findings
 - Visualizing audit coverage alongside code structure
+- Preparing one SARIF or weAudit result for `trailmark-finding-triage`
 
 ## When NOT to Use
 
@@ -162,6 +163,10 @@ annotated nodes. Use `engine.subgraph_names()` to see available subgraphs.
 - Findings on high blast radius nodes: overlap with `high_blast_radius`
 - Findings on privilege boundaries: overlap with `privilege_boundary`
 
+For one candidate finding that needs a reachability verdict or PoC handoff,
+continue with `trailmark-finding-triage` and use the augmented node as the
+bound candidate.
+
 ## Annotation Format
 
 Findings are stored as standard Trailmark annotations:

plugins/trailmark/skills/graph-evolution/SKILL.md

@@ -301,6 +301,12 @@ line-level code review. The two are complementary — graph-evolution
 finds attack paths that text diffs miss, while differential-review
 provides git blame context and micro-adversarial analysis.
 
+**trailmark-review-gate skill:**
+Use trailmark-review-gate after graph-evolution when a branch, pull request,
+fix commit, or release diff needs a PASS/WARN/FAIL/UNKNOWN structural review
+packet. The gate applies deterministic review rules to graph-evolution output;
+it does not replace human review.
+
 **genotoxic skill:**
 If graph-evolution reveals new high-CC tainted nodes, feed them to
 genotoxic for mutation testing triage.

plugins/trailmark/skills/trailmark-finding-triage/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: trailmark-finding-triage
+description: "Performs graph-assisted triage of a single security finding, SARIF result, weAudit annotation, suspicious function, or report excerpt using Trailmark reachability, entrypoint paths, taint, privilege-boundary, blast-radius, caller/callee, and neighborhood evidence. Use when deciding whether one candidate issue is reachable, prioritizing a finding before PoC work, preparing evidence for exploit validation, or checking whether a static-analysis result is actionable."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Write
+---
+
+# Trailmark Finding Triage
+
+Build a concise graph evidence packet for one candidate finding. This skill
+answers whether the affected code is reachable, what graph evidence supports
+or weakens the claim, and what manual review is still required before calling
+the issue exploitable.
+
+## When to Use
+
+- Triage one static-analysis result before spending PoC time
+- Check whether a manual finding is entrypoint-reachable
+- Build an evidence packet for PoC work
+- Review a single suspicious function discovered during manual audit
+- Decide whether one issue should be promoted, deprioritized, or treated as
+  part of a broader chain analysis
+
+## When NOT to Use
+
+- Multiple weak findings might compose into a stronger chain. Use a chain or
+  composition workflow instead.
+- The user wants a full audit. Use an audit or design-review workflow instead.
+- The user wants remediation verification for a known finding. Use a
+  remediation-review workflow instead.
+- The target is a PR or branch diff. Use `graph-evolution` plus a differential
+  review workflow.
+- No concrete finding, function, file/line, or suspicious sink exists yet. Use
+  discovery skills first.
+
+## Rationalizations to Reject
+
+| Rationalization | Why It Is Wrong | Required Action |
+|---|---|---|
+| "The scanner says high severity, so reachability is obvious" | Static findings need graph and code context before promotion | Bind the finding to a graph node and check entrypoint paths |
+| "No entrypoint path means impossible" | It may mean parser, proxy, or dynamic dispatch limitations | Report the limitation separately from reachability |
+| "An auth check appears on the path, so the issue is safe" | The check may enforce the wrong predicate or be bypassed by another path | Treat validation/auth as review targets, not proof |
+| "One reachable path is enough for a PoC claim" | The path still needs attacker-controlled inputs and compatible preconditions | Separate graph reachability from exploitability |
+| "This is probably a chain" | Single-finding triage stops at one candidate | Hand off related findings to a composition workflow |
+
+## Workflow
+
+```
+Finding Triage Progress:
+- [ ] Step 1: Normalize the candidate
+- [ ] Step 2: Build or reuse the Trailmark graph
+- [ ] Step 3: Bind the candidate to graph node(s)
+- [ ] Step 4: Analyze reachability, taint, boundaries, and blast radius
+- [ ] Step 5: Decide and emit the evidence packet
+```
+
+### Step 1: Normalize the Candidate
+
+Accept file/line, function name, SARIF result, weAudit annotation, Markdown
+finding excerpt, or a manual claim. Normalize it to:
+
+- title
+- source type
+- file path and line range if present
+- function or node hint
+- suspected source, sink, or asset
+- claimed impact
+
+If there is no concrete code anchor, stop and ask for one.
+
+For input handling details, see
+[references/input-normalization.md](references/input-normalization.md).
+
+### Step 2: Build Or Reuse The Graph
+
+Use the public `trailmark` skill workflow. Prefer an existing fresh exported
+graph or `.trailmark/` artifact when present. Otherwise build a graph with
+`language="auto"` or the target's explicit language list, then run
+`engine.preanalysis()`.
+
+Record the Trailmark version or feature probes used. Feature-gate Trailmark
+0.4-only APIs with `hasattr()` or CLI help checks.
+
+### Step 3: Bind The Candidate
+
+Bind by file and line overlap first, then function name plus file. If several
+nodes match, list every candidate and select the narrowest enclosing node as
+primary. If no node matches, report a binding limitation instead of guessing.
+
+SARIF and weAudit users should reuse the `audit-augmentation` workflow for
+matching and then inspect the annotated node.
+
+### Step 4: Analyze Graph Evidence
+
+Run the query recipe in
+[references/query-recipes.md](references/query-recipes.md):
+
+- entrypoint paths to the bound node
+- trust level of each path when available
+- membership in `tainted`, `privilege_boundary`, and `high_blast_radius`
+  subgraphs
+- direct callers and callees
+- high-impact downstream sinks
+- sibling or nearby nodes worth manual review
+
+Do not treat graph reachability as proof of exploitability.
+
+### Step 5: Decide And Handoff
+
+Produce one verdict:
+
+| Verdict | Meaning |
+|---|---|
+| `Promote` | Graph evidence supports reachability and plausible impact |
+| `Needs manual review` | Evidence is suggestive but not decisive |
+| `Deprioritize` | No reachable path or only trusted/internal paths found |
+| `Blocked` | Binding or Trailmark analysis failed |
+
+Write the evidence packet using
+[references/output-format.md](references/output-format.md).
+
+Hand off promoted PoC-worthy issues to the user's PoC workflow. Hand off
+related findings to a composition workflow. Hand off repeatable root causes to
+`trailmark-variant-neighborhood`, `variant-analysis`, or a custom Semgrep/CodeQL
+rule workflow.
+
+## Example Prompts
+
+- "Use Trailmark finding triage on `src/Vault.sol:148`; I think withdraw can
+  bypass the balance update."
+- "Triage this SARIF result before I spend PoC time: `semgrep:error
+  unchecked-transfer` in `contracts/Bridge.sol` line 91."
+- "This report excerpt claims `parse_packet` is attacker reachable. Build the
+  Trailmark evidence packet and tell me what is still missing."

plugins/trailmark/skills/trailmark-finding-triage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  icon_small: "assets/trail-of-bits-mark.svg"
+  icon_large: "assets/trail-of-bits-mark.svg"
+  brand_color: "#D83A34"

plugins/trailmark/skills/trailmark-finding-triage/references/input-normalization.md

@@ -0,0 +1,51 @@
+# Input Normalization
+
+Normalize every request into one candidate record before graph analysis.
+
+## Accepted Inputs
+
+| Input | Required fields | Notes |
+|---|---|---|
+| File/line | `file`, `line` | Best starting point for direct graph binding |
+| Function name | `function`, optional `file` | Ambiguous across files; ask for file if many nodes match |
+| SARIF result | `artifactLocation.uri`, `region` | Prefer `audit-augmentation` matching when SARIF is available |
+| weAudit annotation | file, line, severity, text | Convert 0-indexed lines to Trailmark's expected source lines when needed |
+| Markdown finding | title, location or symbol | Extract the claimed impact but do not assume it is true |
+| Manual claim | anchor plus suspected issue | Ask for a concrete anchor if none is provided |
+
+## Candidate Record
+
+Use this shape in notes and final output:
+
+```json
+{
+  "title": "Unchecked balance update before transfer",
+  "source_type": "manual|sarif|weaudit|report|function",
+  "file": "src/Vault.sol",
+  "line_range": [148, 168],
+  "function_hint": "withdraw(uint256)",
+  "suspected_source": "external caller",
+  "suspected_sink": "value transfer",
+  "claimed_impact": "withdrawal without balance decrement"
+}
+```
+
+## Stop Conditions
+
+Stop and request a concrete anchor when:
+
+- only a vulnerability class is provided
+- only a package or directory is provided
+- the excerpt has no file, function, line, symbol, or SARIF/weAudit location
+- all matching graph nodes are test, generated, or vendor code and the user did
+  not say those are in scope
+
+## Ambiguity Handling
+
+If multiple graph nodes match:
+
+1. Keep all matches in the evidence packet.
+2. Prefer file/line overlap over name matching.
+3. Prefer the narrowest enclosing node.
+4. Mark confidence `Low` unless the candidate source unambiguously identifies
+   the intended node.