qualifier 0.1.1

Deterministic quality attestations for software artifacts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

# Qualifier

Deterministic quality attestations for software artifacts.

Qualifier records structured quality signals against code artifacts and
computes aggregate scores that propagate through dependency graphs. Everything
is stored in VCS-friendly JSONL files that sit alongside your source code.

## Quick Start

```sh
# Install
cargo install qualifier

# Initialize in your repo
qualifier init

# Record a quality concern
qualifier attest src/parser.rs \
  --kind concern \
  --score -30 \
  --summary "Panics on malformed input"

# View scores
qualifier score

# Show details for one artifact
qualifier show src/parser.rs

# CI gate (exits non-zero if any artifact is below threshold)
qualifier check --min-score 0
```

## Core Concepts

**Attestations** are immutable quality signals: pass, fail, blocker, concern,
praise, suggestion, waiver. Each carries a score delta (-100 to +100) and is
content-addressed via BLAKE3. Attestations are append-only — updates use
supersession chains rather than mutation.

**Raw score** is the clamped sum of active (non-superseded) attestation scores
for an artifact, bounded to [-100, 100].

**Effective score** is the minimum of an artifact's raw score and the effective
scores of all its dependencies. A low-quality dependency pulls down everything
that depends on it.

**Compaction** prunes superseded attestations or collapses history into epoch
attestations, preserving scores while reducing file size.

**.qual files** are JSONL files containing attestations. The recommended layout
is one `.qual` file per directory. See [SPEC.md](SPEC.md) for layout options
and trade-offs.

## CLI Commands

| Command | Description |
|---------|-------------|
| `qualifier attest <artifact>` | Record an attestation |
| `qualifier show <artifact>` | Show attestations and scores for an artifact |
| `qualifier score` | Display scores for all qualified artifacts |
| `qualifier ls` | List artifacts, filterable by score or kind |
| `qualifier check` | CI gate: exit non-zero if scores below threshold |
| `qualifier compact <artifact>` | Prune or snapshot a .qual file |
| `qualifier graph` | Visualize the dependency graph |
| `qualifier blame <artifact>` | VCS attribution for a .qual file |
| `qualifier init` | Initialize qualifier in a repository |

All read commands support `--format json` for machine-readable output.

## Example Workflow

```sh
# Code review finds an issue
qualifier attest src/auth.rs --kind blocker \
  --summary "SQL injection in login query"

# Developer fixes it and supersedes the blocker
qualifier attest src/auth.rs --kind pass --score 20 \
  --summary "Parameterized login query" \
  --supersedes abc12345

# CI verifies the repo is healthy
qualifier check --min-score 0

# Periodically compact history
qualifier compact --all
```

## Agent Integration

Qualifier is built for both humans and coding agents:

- `--format json` on `score`, `show`, and `ls` for structured output
- `--stdin` batch mode reads JSONL attestations for bulk qualification
- `suggested_fix` field carries actionable remediation advice
- `--graph` flag accepts dependency graphs from build tools (Bazel, etc.)

## Configuration

Layered configuration (highest priority first):

1. CLI flags
2. Environment variables (`QUALIFIER_GRAPH`, `QUALIFIER_AUTHOR`)
3. Project config (`.qualifier.toml`)
4. User config (`~/.config/qualifier/config.toml`)
5. Built-in defaults

## Specification

See [SPEC.md](SPEC.md) for the full format specification, scoring algorithm,
and design rationale.

## License

MIT OR Apache-2.0