add

Record a code finding observation (deduplicated by fingerprint).

If the fingerprint matches a live finding, that finding's occurrence count is bumped and IT is returned (was_new: false, dedup_action: "bumped"); a match on a fixed finding reopens it as a regression ("reopened"); a match on a wont_fix/not_a_bug finding creates a new row linked via meta.recurrence_of. Without a fingerprint a conservative server-side one is derived from category, file and the normalized description.

dedup_action has exactly four values — "created", "bumped", "reopened" and "recurrence_of_closed" — and the fourth is the one to read carefully: a recurrence of a DISMISSED twin files a NEW row and therefore reports was_new: true, so a client that tells create from match by gating on was_new == false misses the event entirely. The twin's id is always in meta.recurrence_of, and meta.similar_to usually carries its status alongside; on the paths where it does not — a caller-supplied fingerprint whose text does not resemble the twin, or a normalized description under the similarity minimum — the twin's status is NOT in this response at all, and costs one get.

attention is a top-level list, ALWAYS present and often empty: an empty list means "evaluated, nothing serious fired", which is a different fact from an absent channel. Two record forms exist, and a list may carry both (severity first, category second; each form at most once).

{signal: severity_escalated, from, to} says THIS observation raised the finding's stored severity. It appears only where a stored severity was raised — the bumped and reopened branches — and severity is monotonic under observation, so there is no de-escalation record to expect.

{signal: category_divergence, observed, stored} says this observation does not NAME the matched finding's category. It appears on every branch that HAS a matched row: bumped, reopened, and the recurrence branch, where the comparison is against the DISMISSED TWIN rather than the new row. Both sides are normalized, so a difference of spelling (Process Improvement vs process-improvement) is deliberately not a signal while a difference of name is; a stored category that is not text is skipped rather than raising. A newly created finding matched nothing, so it emits neither record.

stripped_meta_keys is a top-level list, ALWAYS present and often empty, following the same discipline as attention: [] means "checked, nothing to strip", never "no such channel". A meta key that is identity machinery OUTPUT (e.g. occurrences, recurrence_of, category_minted) is stripped from what gets stored rather than refused, so a caller that copies a fetched card's meta forward (get -> modify -> add) can tell, from this response alone, which of its own keys silently did not land. resolver_errors is the one exception: it reports a FAILURE state, not machinery input, so it is REFUSED outright rather than stripped, on this path exactly as on update's meta_update. This is the ADD-side contract only — CSV import strips the same dynamic reserved union but silently, with no equivalent response key (a decided, separate contract, CB-51), and update's meta_update still refuses every reserved key rather than stripping any of them.

stripped_description_tail is a top-level boolean, ALWAYS present and usually False, following that same discipline: False means "checked, nothing to cut", never "no such channel". Some filing agents leak a slice of their own tool call into the end of description; when the text after a </description> marker is nothing but envelope lines, that tail is CUT rather than refused — the finding is real and only its tail is junk — and cut BEFORE the fingerprint is derived, so a tailed and a clean report of one defect collapse onto one card instead of two. Prose that merely quotes the marker is not cut. True means the text stored is not byte-for-byte the text you passed.

Args:

• severity: critical, high, medium, or low (case-insensitive, no aliases)

• category: Finding category (e.g. tz_naive_datetime, n_plus_one, missing_validation). Call categories first to reuse existing category names. Spelling is normalized (casefold, hyphen/whitespace -> "_"); a category this tracker does not already hold is REFUSED with a hint unless new_category=true — but only when the observation would CREATE a row: a fingerprint match on a known live or fixed finding is recorded regardless, with the observed category kept in the occurrence ring.

• file: File path relative to project root

• description: What's wrong

• lines: WHERE IN THE CODE this finding is, and the only input that gives the card a durable ANCHOR. An anchor stores the surrounding source text and the commit it was read at, so the card still points at the right code after the file is edited and the line numbers move; a path written in description does not, and is never read as a location. WITHOUT THIS THE CARD HAS NO ANCHOR — nothing else in this call supplies one. Four spellings, all accepted: a bare line number ("1850") or range ("1850-1870"), which are read against the file argument above; a full "path/file.py:1850" token, whose path must name the same file as file or the anchor is refused rather than pointed at another file's line numbers; and a list ("[1850, 1870]"), which is N SEPARATE lines and never a range. Pass it whenever the finding is about a place in the code. Omit it — do not invent one — when the finding is about a process, a decision or a whole file: a made-up anchor is worse than none. Same field as meta.lines; supplying both with different values is refused.

• source: First reporter of this defect (default: claude). Frozen at first report by design (BT-4): a re-observation keeps the original; newest sources live in the occurrence ring (meta.occurrences[*].source) — and an imported observation's ring source can be a peer tracker's.

• tags: Optional tags for grouping

• meta: Optional JSON metadata for anything this call has no argument for (module, rule_code, and so on). The code location is NOT one of those: it has its own lines argument above, and that is the spelling to use. meta.lines remains the same field and still works, so the two must not disagree — passing both with different values is refused rather than one silently winning. Top-level meta is the row's AUTHORED state, observation-frozen (BT-4): a re-observation's meta lands only as per-occurrence evidence in meta.occurrences[*].meta. Promoting specific keys into the row is a future allowlist by measured demand, not a general merge.

• reported_at_commit: Git SHA when finding was created (auto-detected from HEAD if omitted)

• reported_at_ref: Version/tag label (e.g. "v2.1.0"), always caller-supplied. Observation-frozen: a bump never updates it (per-occurrence refs stay in the ring as evidence) — but manually mutable BY DESIGN via update(reported_at_ref=), since a release is tagged after filing.

• fingerprint: Stable identity token for this defect, computed from the INVARIANT part of the observation (normalized error signature + failing test + anchor file — no timestamps, SHAs, run ids). Same defect → same fingerprint. The auto: prefix is reserved for server-derived values.

• new_category: Explicit permission to MINT a category the tracker does not hold yet (CB-60). Minting is stamped as meta.category_minted for later counting. Existing categories never need this.