Skip to content

feat(trailmark): skills that reason about code as graphs#133

Open
tob-scott-a wants to merge 14 commits intomainfrom
trailmark
Open

feat(trailmark): skills that reason about code as graphs#133
tob-scott-a wants to merge 14 commits intomainfrom
trailmark

Conversation

@tob-scott-a
Copy link
Contributor

@tob-scott-a tob-scott-a commented Mar 23, 2026

These are the public Claude skills associated with Trailmark (GitHub repository).

Skill Description Author
trailmark Build and query multi-language code graphs with pre-analysis passes (blast radius, taint, privilege boundaries, entrypoints) @tob-scott-a
diagramming-code Generate Mermaid diagrams from code graphs (call graphs, class hierarchies, complexity heatmaps, data flow) @tob-scott-a
crypto-protocol-diagram Extract protocol message flow from source code or specs (RFC, ProVerif, Tamarin) into sequence diagrams @pbottine
genotoxic Triage mutation testing results using graph analysis — classify survived mutants as false positives, missing tests, or fuzzing targets @tob-scott-a
vector-forge Mutation-driven test vector generation — find coverage gaps via mutation testing, then generate Wycheproof-style vectors that close them @tob-scott-a
graph-evolution Compare code graphs at two snapshots to surface security-relevant structural changes text diffs miss @tob-scott-a
mermaid-to-proverif Convert Mermaid sequence diagrams into ProVerif formal verification models @pbottine
audit-augmentation Project SARIF and weAudit findings onto code graphs as annotations and subgraphs @tob-scott-a

The vector-forge skill was used to create C2SP/wycheproof#224 (an initial offering of BLS-12-381 test vectors for the Wycheproof project) after discussing the idea with one of the Wycheproof maintainers at Real World Cryptography.

(There's more cool stuff I can talk about here, but I want to save it for the upcoming blog post that introduces Trailmark to the world. Stay tuned!)

@tob-scott-a tob-scott-a requested a review from dguido as a code owner March 23, 2026 19:07
claude[bot]
claude bot reviewed Mar 23, 2026
View reviewed changes
Copy link

@claude claude bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review.

Tip: disable this comment in your organization's Code Review settings.

@tob-scott-a @claude
Add Codex skill symlinks for trailmark plugin
ebbd30f 
The trailmark plugin's 10 skills were missing .codex/skills/ mappings,
which caused the validate_codex_skills CI check to fail.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@tob-scott-a
Copy link
Contributor Author

tob-scott-a commented Mar 23, 2026

@claude review

claude[bot]
claude bot reviewed Mar 23, 2026
View reviewed changes
@tob-scott-a @claude
Address PR #133 review feedback
7286147 
- Add Rationalizations (Do Not Skip) sections to 5 security skills:
  trailmark, audit-augmentation, crypto-protocol-diagram,
  mermaid-to-proverif, graph-evolution
- Fix requires-python: diagram.py >= 3.12 (was 3.13), protocol.py
  >= 3.12 (was 3.11) to match trailmark's actual requirement
- Rename diagram/ to diagramming-code/ to match SKILL.md frontmatter
  name and all cross-skill references; update Codex symlink

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 23, 2026
View reviewed changes
@tob-scott-a @claude
Fix diagram skill to use uv run instead of plain python
6c20c18 
The diagram.py script carries PEP 723 inline metadata declaring
trailmark as a dependency. Plain python ignores this metadata,
causing ImportError for users who haven't pre-installed trailmark.
uv run processes the metadata and handles dependency resolution.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 23, 2026
View reviewed changes
tob-scott-a and others added 2 commits March 23, 2026 16:27
@tob-scott-a @claude
Address second round of PR #133 review feedback
827f742 
- Fix README directory tree: diagram/ -> diagramming-code/
- Fix diagram-types.md: python -> uv run for all script invocations
- Fix graph-evolution Phase 3: replace undefined shell variables
  ($BEFORE_JSON etc) with template substitutions ({before_json} etc)
- Fix vector-forge mutation-frameworks.md: replace cross-skill file
  link with prose reference to genotoxic skill (avoids reference chain)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@tob-scott-a @claude
Local skill-improver review pass across all 10 trailmark skills
4ce07e6 
diagramming-code:
- Fix arrow syntax inconsistency: uncertain edges use ..-> not -.->
- Fix extra closing paren in diagram-types.md
- Fix diagram.py docstring to match uv run invocation

crypto-protocol-diagram:
- Remove reference chain: spec-parsing-patterns.md no longer links to
  mermaid-sequence-syntax.md, inlines the arrow syntax instead
- Fix ProVerif example note: "Tamarin/ProVerif" -> "ProVerif"

trailmark:
- Replace "path/to/project" with {targetDir} in query-patterns.md
- Add uv run prefix to CLI examples in query-patterns.md
- Add circom to supported language list
- Add pre-analysis annotation kinds to annotation docs

genotoxic:
- Remove reference chains: triage-methodology.md and
  mutation-frameworks.md no longer link to graph-analysis.md

vector-forge:
- Add trailmark to Prerequisites section
- Fix bare trailmark commands to use uv run with {targetDir}

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 23, 2026
View reviewed changes
@tob-scott-a @claude
Address third round of PR #133 review feedback
704c42f 
mermaid-to-proverif:
- Fix ProVerif type error: verify(...) = true is a type mismatch
  since verify returns bitstring. Use let _ = verify(...) in instead,
  which aborts on destructor failure (correct ProVerif pattern)

trailmark-summary, trailmark-structural:
- Add 8 missing language extensions to find command (.rb, .php, .cs,
  .java, .hs, .erl, .cairo, .circom)
- Remove unsupported .lean extension
- Split .c -> --language c and .cpp -> --language cpp (separate parsers)

All 7 security skills:
- Rename "Rationalizations (Do Not Skip)" to "Rationalizations to
  Reject" per CLAUDE.md convention

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 23, 2026
View reviewed changes
@tob-scott-a @claude
Address fourth round of PR #133 review feedback
cc0838b 
mermaid-to-proverif:
- Fix ProVerif type errors in process template: pkey values cannot
  appear in bitstring positions. Add pkey2bs() and concat() to the
  function declarations and rewrite the template to use them,
  matching the sample-output.pv example

trailmark-summary:
- Split .js/.ts mapping: .js -> --language javascript,
  .ts -> --language typescript (separate parsers)

graph-evolution:
- Replace bare python with python3 in graph_diff.py invocations
  (python does not exist on modern Ubuntu/Debian/macOS)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 23, 2026
View reviewed changes
@tob-scott-a @claude
Address fifth round of PR #133 review feedback
6d9c211 
graph-evolution:
- Change python3 to uv run for graph_diff.py invocations to match
  ecosystem convention

trailmark-structural, trailmark-summary:
- Add Rationalizations to Reject sections (both are security skills
  running blast radius, taint, and privilege boundary analysis)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 24, 2026
View reviewed changes
tob-scott-a and others added 2 commits March 23, 2026 21:28
@tob-scott-a @claude
Fix ProVerif type consistency and graph-evolution template vars
8a821fc 
mermaid-to-proverif:
- Rename senc/sdec to aead_enc/aead_dec in Step 3 preamble to match
  the process template and sample-output.pv
- Fix hkdf signature: hkdf(key, bitstring): key (first arg is DH
  shared secret which has type key, not bitstring)

crypto-to-proverif-mapping.md:
- Fix hkdf declaration and summary table to match corrected signature
- Fix example to use concat/pkey2bs for type-correct HKDF input

graph-evolution:
- Replace $BEFORE_DIR/$AFTER_DIR shell vars in Phase 5 with
  {before_dir}/{after_dir} template substitutions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@tob-scott-a @claude
Comprehensive vivisect-style review of all trailmark skills
3df67e8 
ProVerif correctness (mermaid-to-proverif):
- Fix broken ForwardSecrecyTest pattern in security-properties.md:
  process waited on c_fs but nothing sent on it, past_session_key
  was never bound to any session. Replaced with working pattern
  that leaks long-term keys and checks session key secrecy.
- Fix hkdf(bitstring,bitstring) -> hkdf(key,bitstring) in
  proverif-syntax.md to match SKILL.md and sample-output.pv
- Fix type-incorrect example in proverif-syntax.md: tuple of
  (key,pkey,pkey) passed where bitstring expected. Now uses
  concat2/pkey2bs for type-correct serialization.
- Align senc/sdec -> aead_enc/aead_dec in proverif-syntax.md and
  crypto-to-proverif-mapping.md to match SKILL.md and example
- Fix auth query parameter count in security-properties.md:
  beginI fires before session key is known, so has fewer params

Cross-skill consistency:
- Fix 3 stale "diagram skill" references -> "diagramming-code"
  in trailmark/SKILL.md and preanalysis-passes.md
- Add PEP 723 header to graph_diff.py for convention consistency

README and helper skills:
- Add trailmark-summary and trailmark-structural to README skills
  table and directory tree
- Add secondary file extensions (.jsx, .tsx, .h, .hpp, .cc, .cxx)
  to language detection in summary and structural skills
- Inline language mapping in trailmark-structural (was deferred
  to trailmark-summary, violating one-level-deep rule)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 24, 2026
View reviewed changes
@tob-scott-a @claude
Fix ProVerif type consistency and graph-evolution template vars
dec734b 
- Fix endInitiator -> endI in mermaid-to-proverif Step 6 template
  (endInitiator was never declared as an event)
- Add missing msg2_label constant to Step 3 constants block
- Add .hh/.hxx C++ header extensions to language detection in
  trailmark-summary and trailmark-structural

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 24, 2026
View reviewed changes
@tob-scott-a @claude
Fix mermaid-to-proverif template: missing beginI event and secrecy wi…
b3addf8 
…tness

Step 6 Initiator template:
- Add missing event beginI(pk(sk_I), pk_R) before first out —
  without it, authentication queries always report false attacks
- Replace local new secret_I with free private_I [private] to
  match sample-output.pv's secrecy witness pattern

security-properties.md:
- Fix beginI/beginR from 3 args to 2 args in mutual auth section
  and query checklist (begin events fire before session key is
  known, so they only take the two public keys)
- Update "Placing Events" table to match 2-param form

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
claude[bot]
claude bot reviewed Mar 24, 2026
View reviewed changes
@tob-scott-a @claude
Address sixth round of PR #133 review feedback
e6bd48a 
proverif-syntax.md Two-Party Process example:
- Fix type errors: pkey values passed directly to bitstring params
  in sign() and verify(). Now uses concat2(pkey2bs(...)) pattern.
- Add missing pkey2bs declaration to function list
- Add missing info_session constant declaration
- Fix msg2_label -> msg2 in verification check example to match
  the file's own constant declarations

trailmark-structural:
- Fix contradiction: Rationalizations table said "Install trailmark
  first" but Execution section forbids install commands. Changed
  to "Report not installed and return" to match execution policy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@claude claude[bot] claude[bot] left review comments

@dguido dguido Awaiting requested review from dguido dguido is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tob-scott-a