qualifier 0.5.1

Deterministic quality annotations 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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

+++
name = "concepts"
summary = "Annotation model, kinds, supersession, IDs, .qual layout"
since = "0.5.0"
+++

# qualifier — key concepts

## The annotation envelope

Every qualifier record is a single-line JSON object using the **Metabox envelope**.
The envelope fields appear in a fixed order and are identical for every record type:

(formatted for readability; each record is a single line in the .qual file)

```json
{
  "metabox":    "1",
  "type":       "annotation",
  "subject":    "src/auth.rs",
  "issuer":     "mailto:agent@example.com",
  "issuer_type": "ai",
  "created_at": "2026-03-01T10:00:00Z",
  "id":         "<blake3-hex>",
  "body":       { ... }
}
```

Field notes:

- `metabox` — always `"1"`. Validation rejects any other value.
- `type` — `"annotation"` (default, may be omitted in files), `"epoch"`, `"dependency"`, or any non-empty string for custom types (URI recommended).
- `subject` — the artifact being annotated. A path (`src/auth.rs`), module, build target, or package name. Opaque to qualifier.
- `issuer` — who or what wrote the record. Must be a URI (see §Issuer URIs below).
- `issuer_type` — optional; one of `human`, `ai`, `tool`, `unknown`.
- `created_at` — RFC 3339 timestamp.
- `id` — BLAKE3 hash of the canonical form (see §Content addressing). Never hand-edit.
- `body` — type-specific payload; body fields are serialized in alphabetical order.

You do not construct this JSON by hand. Use `qualifier record`, `qualifier reply`,
`qualifier resolve`, or `qualifier emit` — they compute the correct `id` for you.

## Kinds

The `kind` field in an annotation body identifies the nature of the signal.
Choose the most specific kind that fits; downstream filtering and polarity depend on it.

| Kind         | When to use |
|--------------|-------------|
| `concern`    | A non-blocking issue worth tracking (e.g., a code smell, a risk, a TODO that matters). |
| `blocker`    | A blocking issue that must be resolved before release. |
| `fail`       | The artifact does not meet a stated quality bar. |
| `pass`       | The artifact meets a stated quality bar. |
| `comment`    | An observation or discussion point with no polarity impact. |
| `praise`     | Positive recognition — marks intentional design for future readers. |
| `suggestion` | A proposed improvement, typically paired with `--suggested-fix`. |
| `waiver`     | An acknowledged issue explicitly accepted with rationale. |
| `resolve`    | Closes a prior record via supersession. Prefer `qualifier resolve` instead of recording this directly. |

Any other string is valid as a custom kind. The CLI warns if it looks like a
typo of a built-in kind (edit distance ≤ 2).

Polarity summary: `pass`, `praise`, `waiver` are positive; `comment` and `resolve`
are neutral; `concern`, `suggestion`, `fail`, `blocker` are negative.

## Supersession

Records are **immutable once written**. To update or retract a signal, write a
new annotation with `supersedes` pointing to the old record's `id`.

Rules the system enforces:

- The superseding and superseded records **must share the same `subject`**.
  Cross-subject supersession is rejected.
- Supersession chains must be **acyclic**. A → B → A is detected and rejected.
- Only the **tip** of a supersession chain is active. Superseded records are
  hidden by `qualifier show` and `qualifier ls`.
- Dangling `supersedes` references (pointing to IDs not present in the
  current file set) are allowed — the referencing record stays active.

The canonical way to close an issue is `qualifier resolve <id>`, which writes
a `resolve`-kind annotation that supersedes the target. The original record
is no longer surfaced; the resolve record stands as a visible tombstone.

## `.qual` file layout and discovery

A `.qual` file is UTF-8 JSONL (one record per line). Three layouts coexist:

| Layout | Example file | Trade-off |
|--------|-------------|-----------|
| Per-directory (recommended) | `src/.qual` | Clean tree, good merge behavior |
| Per-file | `src/parser.rs.qual` | Maximum merge isolation, noisy tree |
| Per-project | `.qual` at repo root | Simplest, but high merge contention |

When you run `qualifier record concern src/auth.rs ...`, the CLI writes to
`src/.qual` by default (or `src/auth.rs.qual` if that file already exists).
Override with `--file <path>`.

**Discovery** walks from the project root (found by searching upward for
`.git`, `.hg`, `.jj`, `.pijul`, `_FOSSIL_`, or `.svn`). It collects every
file named `.qual` or ending in `.qual`.

**Ignore rules** are applied by default:
- `.gitignore` at any level (including global gitignore and `.git/info/exclude`).
- `.qualignore` — same syntax as `.gitignore`, qualifier-specific. Place
  anywhere in the tree to exclude vendored code, generated files, or examples.

Pass `--no-ignore` to bypass all ignore rules on any discovery command
(`show`, `ls`, `compact`, `review`, `praise`).

Hidden directories (e.g., `.git`, `.vscode`) are always skipped. Hidden
*files* like `.qual` are not skipped.

## Issuer URIs and `issuer_type`

The `issuer` field identifies who or what created a record. It must be a URI
— specifically, it must contain `:`. Validation rejects bare strings without a colon.

Common forms:

```
mailto:agent@example.com      # typical for an AI agent or human
https://ci.example.com        # CI job or tool with a URL
urn:qualifier:compact         # reserved for the compact command
```

When `--issuer` is omitted, the CLI detects the VCS user identity:
- Git: `git config user.email` → wrapped as `mailto:<email>`
- Mercurial: `hg config ui.username` → wrapped as `mailto:<username>`
- Fallback: `mailto:$USER@localhost`

As an agent, always pass `--issuer "mailto:your-agent-id@example.com"` and
`--issuer-type ai` so records are traceable back to you.

The `issuer_type` field is optional but strongly recommended:

| Value     | Use when |
|-----------|----------|
| `human`   | A person wrote this record |
| `ai`      | An AI agent wrote this record |
| `tool`    | An automated scanner or CI job wrote this record |
| `unknown` | Origin is unclear |

## Content addressing (BLAKE3)

A record's `id` is the BLAKE3 hash of its **Metabox Canonical Form (MCF)**:
the record serialized with envelope fields in fixed order, body fields in
alphabetical order, all optional absent fields omitted, and `id` set to `""`
during hashing.

Implications:

- Identical inputs always produce the same `id`, on every machine and implementation.
- Changing any canonical field (summary, kind, span, issuer, timestamp, ...) changes the `id`.
- **Do not hand-edit `.qual` files.** Editing a field invalidates the `id`,
  and `qualifier` will reject the record. Use `qualifier record`, `qualifier emit`,
  or the compactor to write records.
- Span normalization is part of MCF: a span with no `end` has `end` set equal
  to `start` before hashing, so `{"start":{"line":42}}` and
  `{"start":{"line":42},"end":{"line":42}}` produce the same `id`.

The `id` is a stable handle you can use to target a record with
`qualifier reply <id-prefix>` or `qualifier resolve <id-prefix>`.
Four characters of prefix are the minimum; use more if the file has many records.