Qualifier

Continuous Annotation, stored as files. Record concerns, suggestions, and feedback against code the moment you see them — humans and bots writing the same format. No server, no database, just .qual files next to your source.

cargo install qualifier
qualifier record concern src/auth.rs:42 "SQL injection risk in login handler"

The annotation is pinned to that file and line, stored as a content-addressed JSONL record in src/.qual, and git blame/git log/git diff all work on it. Append-only, so concurrent edits don't conflict structurally.

What it's for

Quality work is batched behind PRs and gates. You notice a problem on Tuesday but the PR isn't until Friday. Inline comments disappear into merged PRs. Three sprints later nobody remembers what was flagged, what was fixed, and what was quietly ignored.

Qualifier is ambient review: annotate any file, any time, whether it changed today or three years ago. Annotations thread into conversations, survive merges and rebases, and surface drift automatically when the code underneath them changes.

Quick tour

# Record a concern at a specific line
qualifier record concern src/parser.rs:42 "Panics on malformed input"

# See it
qualifier show src/parser.rs

# Reply (id-prefix or location)
qualifier reply a1b2 "Good catch — fixed in 8f3c2a1"

# Close it
qualifier resolve a1b2

# Find drift in span-bound annotations after the source changed
qualifier review src/parser.rs

CLI

Record observations

<kind> is one of concern, comment, suggestion, pass, fail, blocker, praise, waiver, resolve, or any custom string. <location> is a path with an optional span (src/foo.rs:42, src/foo.rs:42:58). <target> is an id-prefix (≥4 chars) or a <location>.

Inspect annotations

Maintain

All read commands accept --format json for machine-readable output.

Records

Annotations are the primary record type, but .qual is a substrate. The Metabox envelope wraps any type-specific body — annotations, epochs (compaction snapshots), dependencies, licenses, security advisories, performance measurements, or any custom URI-typed record. Tools that don't understand a body type still round-trip the record unchanged.

A two-record .qual file:

{"metabox":"1","type":"annotation","subject":"src/auth.rs","issuer":"mailto:alice@example.com","issuer_type":"human","created_at":"2026-02-24T10:00:00Z","id":"a1b2…","body":{"kind":"concern","summary":"SQL injection risk in login handler"}}
{"metabox":"1","type":"annotation","subject":"src/auth.rs","issuer":"urn:anthropic:claude","issuer_type":"ai","created_at":"2026-02-24T11:00:00Z","id":"e5f6…","body":{"kind":"comment","references":"a1b2…","summary":"Switched to parameterized queries in 8f3c2a1"}}

Records are immutable and content-addressed (BLAKE3). Updates use supersession chains rather than mutation. Compaction prunes superseded records or collapses history into epoch records.

File layout

.qual files can sit per-directory (src/.qual — recommended), per-file (src/parser.rs.qual), or per-project (.qual at the root). All layouts coexist. Discovery respects .gitignore and .qualignore; pass --no-ignore to bypass.

For collaborative repos, configure your VCS to use union merges on .qual files (e.g. *.qual merge=union in .gitattributes for git) so concurrent appends don't collide.

Agent integration

• --format json on show and ls for structured output
• qualifier record --stdin and qualifier emit --stdin accept JSONL on stdin
• body.suggested_fix carries actionable remediation
• body.span targets specific line ranges
• --issuer-type ai distinguishes agent-authored records in display

Documentation

• SPEC.md — full format specification
• METABOX.md — the envelope format
• CHANGELOG.md — release notes

License

MIT OR Apache-2.0