guardlink AGENTS.md

Guardlink — Project Instructions

GuardLink — Security Model

This project carries a GuardLink threat model: security facts recorded next to the code they describe — what each component is exposed to, what mitigates it, how data flows between components — parsed into something you can query.

Ask it instead of inferring security context from the source. It already answers most of what you would otherwise guess at, and it records decisions that are invisible in the code, such as which risks a human has explicitly accepted.

You are about to…	Ask
edit a file	guardlink_context(file) — annotations there, the assets they name, open exposures, controls the file must uphold
change a shared component	guardlink_graph(from, depth, direction) — blast radius across data flows and trust boundaries
act on a scanner finding	guardlink_lookup("cwe:CWE-89") — is this weakness class declared, and is it mitigated, accepted, open or confirmed
finish a change	guardlink validate . then guardlink diff HEAD~1 — did I make this worse

Without MCP, the same answers come from guardlink status ., guardlink parse . (the whole model as JSON on stdout) and guardlink diff HEAD~1.

Full reference: docs/GUARDLINK_REFERENCE.md

Where annotations go

Annotation mode: inline. Annotations live in source-file comments, in the comment syntax of the file you are editing — the doc-block of the function or module they describe.

/**
 * @exposes #api to #sqli [critical] cwe:CWE-89 -- "email concatenated into SQL"
 * @mitigates #api against #sqli using #prepared-stmts -- "parameterized via pg"
 */
export function login(email: string) { … }

Do not create .gal sidecars under .guardlink/annotations/ in this mode; a repo with both is a mixed repo, and that is the failure this section exists to prevent.

What you owe it back

When you write or change code that touches security-relevant behavior, add the annotations in the same change. This includes: new endpoints, authentication/authorization logic, data validation, database queries, file I/O, external API calls, crypto operations, process spawning, user input handling, and configuration parsing. Do NOT annotate code that never touches a security boundary — formatters, UI components, pure helpers. Business logic that makes an authorization or ownership decision is in scope: an IDOR or a missing tenant check lives in business logic, not in the parsing layer.