Trailmark Review Gate
Apply deterministic security gate rules to Trailmark structural diff evidence.
This skill does not replace line-level review. It produces a compact structural
packet reviewers can cite while they inspect the code.
When to Use
- Reviewing a branch, pull request, release diff, or fix commit
- Checking whether a change expands attack surface
- Looking for removed validation or authorization on reachable paths
- Comparing before/after taint, privilege-boundary, blast-radius, or
complexity signals
- Producing graph evidence for a differential review
When NOT to Use
- Single-snapshot analysis. Use
trailmark or trailmark-structural.
- Text-diff review only. Use
differential-review.
- Full vulnerability discovery. Use an audit or bug-finding workflow.
- One static finding. Use
trailmark-finding-triage.
- Tooling is unavailable and the user wants manual review only.
Rationalizations to Reject
| Rationalization |
Why It Is Wrong |
Required Action |
| "The line diff is small, so no graph gate is needed" |
Small changes can create new call paths |
Compare before/after graphs |
| "Graph gate passed, so the PR is secure" |
The gate only checks structural regressions |
Still perform line-level review |
| "Trailmark failed, so pass the gate" |
Tool failure is unknown risk, not success |
Emit UNKNOWN |
| "Tests pass, so removed validation is fine" |
Tests may miss affected entrypoint paths |
Review the removed path manually |
| "Only new code matters" |
Removed auth, validation, and callers can be higher risk than additions |
Review removals and path changes |
Workflow
Review Gate Progress:
- [ ] Step 1: Resolve before/after inputs
- [ ] Step 2: Build graph-evolution evidence
- [ ] Step 3: Normalize structural changes
- [ ] Step 4: Apply gate rules
- [ ] Step 5: Emit review packet and actions
Step 1: Resolve Inputs
Accept two refs, a branch name, a commit range, or before/after directories.
Do not check out branches unnecessarily. Prefer git diff, git show, and
git worktrees, following the graph-evolution snapshot workflow.
Step 2: Build Graph Evidence
Run graph-evolution or equivalent Trailmark before/after graph analysis.
Both snapshots must run engine.preanalysis() so taint, privilege-boundary,
blast-radius, complexity, and entrypoint signals are available.
Record Trailmark version and any feature probes. If graph construction fails,
emit UNKNOWN.
Step 3: Normalize Changes
Normalize evidence into:
- added, removed, and modified nodes
- added and removed edges
- entrypoint set changes
- taint membership changes
- privilege-boundary membership changes
- blast-radius changes
- complexity changes
- newly reachable sensitive sinks
- unresolved, proxy, or dynamic edge changes
Step 4: Apply Gate Rules
Apply the rules in references/gate-rules.md.
Gate verdicts are:
| Verdict |
Meaning |
FAIL |
A high-risk structural regression needs review before acceptance |
WARN |
A meaningful graph change needs reviewer attention |
PASS |
No configured structural gate fired |
UNKNOWN |
Trailmark failed or evidence is too incomplete |
Step 5: Emit Packet
Write the packet using
references/output-format.md, then hand it to
the branch reviewer. Use
references/review-integration.md when
combining this packet with differential-review or another PR review process.
Requirements
- Never mutate the user's working branch while comparing refs.
- Never report
PASS when Trailmark failed.
- Separate graph evidence from manual security judgment.
- Include exact changed nodes or paths for every
FAIL and WARN.
- Include limitations when parser, proxy, unresolved-call, or dynamic-dispatch
uncertainty affects the verdict.
1---2name: trailmark-review-gate3description: Runs a Trailmark structural review gate over a branch, pull request, fix commit, release diff, or git ref range to detect new entrypoints, new tainted paths, removed validation or authorization calls, privilege-boundary drift, blast-radius growth, complexity growth, and newly reachable sensitive sinks. Use when reviewing a PR, branch, remediation commit, or release diff where graph-level security regressions should be checked before merge.4---5
6# Trailmark Review Gate
7
8Apply deterministic security gate rules to Trailmark structural diff evidence.
9This skill does not replace line-level review. It produces a compact structural
10packet reviewers can cite while they inspect the code.
11
12## When to Use
13
14- Reviewing a branch, pull request, release diff, or fix commit
15- Checking whether a change expands attack surface
16- Looking for removed validation or authorization on reachable paths
17- Comparing before/after taint, privilege-boundary, blast-radius, or
18 complexity signals
19- Producing graph evidence for a differential review
20
21## When NOT to Use
22
23- Single-snapshot analysis. Use `trailmark` or `trailmark-structural`.
24- Text-diff review only. Use `differential-review`.
25- Full vulnerability discovery. Use an audit or bug-finding workflow.
26- One static finding. Use `trailmark-finding-triage`.
27- Tooling is unavailable and the user wants manual review only.
28
29## Rationalizations to Reject
30
31| Rationalization | Why It Is Wrong | Required Action |
32|---|---|---|
33| "The line diff is small, so no graph gate is needed" | Small changes can create new call paths | Compare before/after graphs |
34| "Graph gate passed, so the PR is secure" | The gate only checks structural regressions | Still perform line-level review |
35| "Trailmark failed, so pass the gate" | Tool failure is unknown risk, not success | Emit `UNKNOWN` |
36| "Tests pass, so removed validation is fine" | Tests may miss affected entrypoint paths | Review the removed path manually |
37| "Only new code matters" | Removed auth, validation, and callers can be higher risk than additions | Review removals and path changes |
38
39## Workflow
40
41```
42Review Gate Progress:
43- [ ] Step 1: Resolve before/after inputs
44- [ ] Step 2: Build graph-evolution evidence
45- [ ] Step 3: Normalize structural changes
46- [ ] Step 4: Apply gate rules
47- [ ] Step 5: Emit review packet and actions
48```
49
50### Step 1: Resolve Inputs
51
52Accept two refs, a branch name, a commit range, or before/after directories.
53Do not check out branches unnecessarily. Prefer `git diff`, `git show`, and
54git worktrees, following the `graph-evolution` snapshot workflow.
55
56### Step 2: Build Graph Evidence
57
58Run `graph-evolution` or equivalent Trailmark before/after graph analysis.
59Both snapshots must run `engine.preanalysis()` so taint, privilege-boundary,
60blast-radius, complexity, and entrypoint signals are available.
61
62Record Trailmark version and any feature probes. If graph construction fails,
63emit `UNKNOWN`.
64
65### Step 3: Normalize Changes
66
67Normalize evidence into:
68
69- added, removed, and modified nodes
70- added and removed edges
71- entrypoint set changes
72- taint membership changes
73- privilege-boundary membership changes
74- blast-radius changes
75- complexity changes
76- newly reachable sensitive sinks
77- unresolved, proxy, or dynamic edge changes
78
79### Step 4: Apply Gate Rules
80
81Apply the rules in [references/gate-rules.md](references/gate-rules.md).
82Gate verdicts are:
83
84| Verdict | Meaning |
85|---|---|
86| `FAIL` | A high-risk structural regression needs review before acceptance |
87| `WARN` | A meaningful graph change needs reviewer attention |
88| `PASS` | No configured structural gate fired |
89| `UNKNOWN` | Trailmark failed or evidence is too incomplete |
90
91### Step 5: Emit Packet
92
93Write the packet using
94[references/output-format.md](references/output-format.md), then hand it to
95the branch reviewer. Use
96[references/review-integration.md](references/review-integration.md) when
97combining this packet with `differential-review` or another PR review process.
98
99## Requirements
100
101- Never mutate the user's working branch while comparing refs.
102- Never report `PASS` when Trailmark failed.
103- Separate graph evidence from manual security judgment.
104- Include exact changed nodes or paths for every `FAIL` and `WARN`.
105- Include limitations when parser, proxy, unresolved-call, or dynamic-dispatch
106 uncertainty affects the verdict.
gabrielmoreira