0.5.1 — safety and diagnostics, from first real-project use

[emmepi86]

Tutto quanto segue viene dall'uso reale su un codebase clinico, non da review: cinque casi in cui tracelink ha fatto qualcosa di difendibile e inutile per chi lo stava usando.

1. Un vault appartiene a un registro

Splittare un secondo registro nello stesso vault riscriveva INDEX.md per descrivere solo il nuovo arrivato e lasciava orfane le note già presenti — un vault formalmente valido e semanticamente falso.

Il manifest guadagna schema_version: 2 e l'identità del registro:

{
  "schema_version": 2,
  "register": { "prefix": "RES", "source": "FINDINGS.md" }
}

e lo split rifiuta fail-closed:

ERROR: vault already belongs to prefix RES
cannot split prefix CQR into the same vault
use a separate --out directory

--adopt-vault è la via esplicita. Il merge multi-registro resta un'operazione deliberata, non un effetto collaterale di due split. I manifest v1 continuano a essere compresi.

2. Gli identificatori sono accettati come sono scritti

Un registro con ### F1 non produceva niente, perché il pattern pretendeva il trattino. Ora è opzionale e l'id è preservato: F1 resta F1. Riscrivere un identificatore umano per comodità del tool è un costo pagato da ogni lettore del registro, per sempre, per risparmiare una regex.

Funzionano anche i prefissi con trattini, quindi P1-CQR-4 splitta e ordina correttamente.

3. Il fallimento dice cosa ha trovato

Prima nominava il pattern che voleva e basta; rispondere a «e allora cosa c'è in questo file?» richiedeva leggere il sorgente.

No findings matched in audit.md.

Expected:
  heading level: 2-6
  identifier:    F-<number> or F<number>

First headings found:
  ### F1 — Negazioni e correzioni diventano diagnosi attive
  ### F2 — Collasso dei fenotipi rari

più --inspect per l'elenco completo degli stili presenti.

4. Le note che non collegano nulla vengono nominate, con la causa

notes_with_matches: 10 comprimeva tre problemi diversi in un numero solo. Una finding scritta in prosa, candidati filtrati perché troppo comuni e simboli solo ambigui richiedono tre correzioni diverse.

UNLINKED NOTES

CQR-3
  reason: no symbol identifiers found

CQR-8
  reason: only ambiguous symbols found

--report-unlinked li elenca, --require-linked fa fallire la CI, e l'output JSON porta unlinked_notes.

5. I riferimenti ambigui restano visibili

Trattenere il link è giusto — indovinare fra due definizioni è peggio che astenersi — ma toglierlo del tutto da CODE-INDEX.md lasciava silenzio esattamente dove la risposta era due risposte. Ora hanno una sezione propria con le note che li citano e tutti i candidati.

README

Documentato il contratto editoriale: il linking è lessicale, quindi identificatori espliciti e qualified name producono link forti e la prosa no. watchdog.cancel resta forte anche dove cancel è ovunque.

Verifica

77 test, tutti verdi (14 preesistenti + 63 nuovi). Provato end-to-end sui registri reali che avevano fallito: quello con ### F1 ora produce le 5 note, e il vault multi-registro viene rifiutato invece di corrompersi.

Fuori scope, per 0.6.0 come da piano: .tracelink.toml, init, doctor, context, policy configurabile per i common symbols, JSON stabile ovunque.