qualifier 0.8.0

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

+++
name = "conventions"
summary = "Tag vocabulary, the alternative kind, close authority, and self-sufficient records"
sees_also = ["threads", "batch", "workflows"]
since = "0.8.0"
+++

# qualifier — conventions

These conventions carry state that the record format does not model as
fields. Tools and agents rely on the exact spellings.

## Tags

| tag | meaning |
|---|---|
| `status:needs-decision` | Waiting on a human judgment call. Address it with `status:needs-decision:<issuer>`. |
| `status:decided` | A human made the call; the record carrying this tag states it. |
| `status:deferred` | Acknowledged; intentionally not now. |
| `reason:fixed` `reason:wontfix` `reason:duplicate` `reason:invalid` `reason:obsolete` | Why a `resolve` closed its target. `qualifier resolve --reason <r>` adds it. |
| `session:<harness>:<id>` | The session whose reasoning produced the record. Added automatically (see `qualifier agents concepts`, issuer defaults). |
| `revisit:<condition>` | On an `alternative`: when to reconsider it. |
| `depends-on:<id>` | On a reply in thread B: B cannot land before the thread whose `origin` has this full ID (the origin is stable when the root is edited or re-anchored). List with `qualifier threads --tag 'depends-on:*'`; fetch the other thread with `qualifier threads <id>`. |

A thread's status is its *latest* `status:*` tag. Find open decisions with
`qualifier threads --status needs-decision`.

## Kinds for design work

- A critique → `concern`. A defect that must be fixed → `blocker`. An idea →
  `suggestion`. An accepted risk → `waiver`.
- A path considered and not taken → `alternative` (a custom kind). Put what
  it was in the summary, why not now in `--detail`, and an observable
  trigger in a `revisit:` tag:

```bash
qualifier record alternative docs/design.md:40:52 "Per-session worker pool" \
  --detail "One pool is simpler until sessions exceed ~1k" \
  --tag "revisit:concurrent sessions exceed 1000"
```

## Close authority

Resolve a record in one of two cases:

- **(a) Your session issued it** (subagents share the session): resolve
  with a message citing why — the refuting reply's ID, or the evidence
  itself. No commit ref needed.
- **(b) Your own commit fixed it**: resolve only with evidence in the
  message (a test that now passes, or a command and its output) and
  `--ref git:<sha>`. Commit the `.qual` change separately: a resolve
  cannot live in the commit it references.

Without evidence for (b), reply with what you found and let a human close
it. `wontfix` and decisions belong to humans.

## Self-sufficient records

A record must make sense to someone who never saw the session that wrote
it. Cite repository paths, line ranges, and record IDs. Never cite a
prompt, a brief, "principle 3", "as discussed", or files outside the
repository.