Review di esempio: production readiness su mklang

Questo è un campione, non un cliente. È la review applicata al mio codice open source, mklang, per mostrare la forma del documento che si riceve con la review da 3.500 €. Nessun cliente, nessun dato riservato. Ogni numero rimanda a un file, a un run o a una pagina pubblica. Dove manca la ricevuta è scritto «nessuna ricevuta ancora».

Perché mklang e non orka. mklang ha ricevute pubbliche datate su tutti e quattro i pilastri: pagine di esperimento con risultati, inclusi quelli negativi, 37 ADR, CHANGELOG e un gate di copertura al 90%. Il repo pubblico di orka ha CI e una cartella evals/, ma nessun risultato datato con numeri. orka resta un candidato per un secondo campione.

Oggetto: gianlucamazza/mklang @ 67f286da (tip di main, 2026-10-05, «Eval harness: first-true fidelity vs prompt-spaghetti (#126)»), pacchetto PyPI mklang 1.3.7. CI: verde su main @ 67f286da, run 37348390065 (2026-10-05): test su Linux (Python 3.11/3.12/3.13), macOS e Windows, più quality e live-smoke. Metodo: sola lettura del repository e delle ricevute già pubblicate. Per questo campione non ho eseguito run live. Come nella review reale, non ho modificato il codice.

1. Valutazione per pilastro

Stato — dove si perde lo stato? · Giudizio: buono, con un rischio sui dati

  • Cosa c'è.
    • I checkpoint a inizio loop riprendono una run sospesa: blackboard, stato, step, totali di token, budget di repair e trace. È l'ADR 0007, «Accepted». L'ADR 0008 fa sospendere anche l'escalate verso un umano.
    • Test: tests/engine/test_checkpoint.py (19 test, tra cui test_root_suspend_on_cost).
    • Una ripresa incoerente si ferma con resume-mismatch (src/mklang/engine.py, righe 1162 e 1370) invece di proseguire su uno stato sbagliato.
    • Lo store dei checkpoint è intercambiabile: ADR 0032, «Accepted» e implementato su main con la PR #87 (014c5186, 4 ago 2026). Ci sono il protocollo CheckpointStore, il FileCheckpointStore e i test dedicati in test_checkpoint.py.
    • Una run sospesa in modo pulito riprende da file in una sessione nuova, cioè con uno store vuoto come in un altro processo (tests/mcp/test_mcp.py::test_durable_resume_across_stores, ::test_durable_resume_of_cli_checkpoint).
  • Cosa manca.
    • La sospensione è opt-in (suspendable=True / --checkpoint PATH, default off) e scatta su esaurimento del budget o su escalate (ADR 0007).
    • Non esiste un test di ripresa dopo un crash del processo a metà chiamata: nessuna ricevuta ancora.
  • Rischio.
    • Un checkpoint serializza l'intera blackboard in JSON in chiaro: testo dei clienti, dati personali, policy interne (src/mklang/checkpoint.py, righe 31–34). Il file è scritto con permessi owner-only (0600), verificati da test_checkpoint_written_owner_only.
    • Il punto di aggancio per cifrare esiste (ADR 0032), ma mklang non fornisce uno store cifrato (l'ADR 0032 lo mette «Not in scope») né una scadenza dei file.
    • I file più sensibili, cioè le escalation, sono anche quelli che restano più a lungo.

Recovery — come si recupera dai fallimenti? · Giudizio: debole, misurato onestamente

  • Cosa c'è.
    • repair(N) rientra nello stato con la condizione fallita come feedback. Le uscite esaurite vanno su escalate/fail, non su un ok di comodo (repair-convergence).
    • Per gli stop puliti vale la ripresa da file descritta sopra. Per i crash a metà chiamata non c'è ricevuta.
  • Misura (secondo il riepilogo pubblicato dell'esperimento nel repo).
    • Run del 2026-08-20, DeepSeek, 30 run, di cui 13 arrivate a un secondo tentativo. Pass rate al tentativo 1 0,57, al tentativo 2 0,15, lift −0,41. Verdetto del repo: «no convergence».
    • Il run del 2026-08-09 (9 run) non ha misurato nulla, perché nessuna run è arrivata al secondo tentativo.
    • Fonte: la stessa pagina, tabella «Results» (aggiunta con la PR #99). I dati grezzi di questi run non sono nel repo: c'è solo il riepilogo.
  • Lettura.
    • Non è una confutazione: il repo stesso nota l'effetto di selezione, perché al tentativo 2 restano solo i casi più difficili.
    • Però oggi non c'è evidenza che il feedback batta un semplice nuovo campione.
    • Lo script supporta già un confronto a tre bracci (first_attempt / plain_resample / feedback_repair), ma un run a tre bracci non è mai stato fatto: nessuna ricevuta ancora.

Eval — come si misura la qualità degli output? · Giudizio: metodo forte, dati sottili

  • Cosa c'è.
    • Una suite di conformità con 42 casi in conformance/cases/, contro un LLM scriptato.
    • Il gate di copertura fail_under = 90 (pyproject.toml).
    • Un corpus di confine (threshold_edge, priority_shadow, none_holds), con metriche separate: accordo tra provider, accordo con sé stesso, accuratezza contro il gold e gate_blind_spot (gate-divergence).
    • Il repo ammette che l'accordo «1.0» fino al 2026-07-27 «non aveva potere discriminante» (stessa pagina).
  • Misure (secondo i riepiloghi pubblicati nel repo, senza dati grezzi).
    • Corpus di confine: una sola riga live (2026-08-09, DeepSeek+OpenAI, tutto 1.0, comprese 108/108 coppie di parafrasi). Il repo stesso la chiama «un primo dato, non una questione chiusa» (gate-divergence, «Limitations»).
    • 2026-07-24: accordo aggregato 0,917, severity_escalate 0,667 (validation report, riga C3).
    • Authoring: blind_spot 0,0167 (2026-07-23, deepseek-reasoner, modello ritirato il 2026-07-24; authoring-blind-spot).
  • Dati grezzi.
    • L'unico set leggibile da macchina su GitHub è l'artifact live-provider-report del run di release 36544053885 (v1.3.7, 2026-09-29): gate_divergence + severity_escalate su DeepSeek/OpenAI/OpenRouter. Non è il corpus di confine e scade il 2026-12-28.
  • Cosa manca.
    • First-true fidelity: nessun risultato live, solo il dry-run mock (first-true-fidelity, «Results»).
    • La release di evidenze evidence/2026-09-evidence-release/ contiene solo un README segnaposto, senza JSONL grezzi né manifest.
    • Anthropic non è coperto (chiave assente, validation report C3).

Costi — quanto costa ogni richiesta? · Giudizio: contabilità corretta, nessun costo per run

  • Cosa c'è.
    • Un budget di costo che sospende la run (cost_budget, cost-exhausted; ADR 0007; test_root_suspend_on_cost).
    • Ogni run riporta l'uso dei token in RunResult.usage.
    • Dalla 1.3.7 (2026-09-29) una risposta rifiutata resta addebitata: un output troncato o un parse: fallito non azzera più i token di una chiamata già fatturata (CHANGELOG 1.3.7, PR #111). Il fix è coperto da test di regressione (tests/engine/test_truncation.py).
    • Articolo pubblico: «A Refused Answer Still Has to Charge Its Tokens» (4 ott 2026).
  • Cosa manca.
    • Non esiste ancora una ricevuta di costo per run, né in € né in $. I token vengono contati, ma nessuno script li converte in costo per richiesta o per macchina.
    • Le cifre di TypeSafe/Jev (~$0,001 solo input, a listino) non sono un costo di mklang e restano fuori da questo campione.

2. Interventi in ordine di priorità

| # | Intervento | Pilastro | Sforzo | Perché prima | |---|---|---|---|---| | 1 | Misurare il costo per run: token in/out convertiti in € per ogni macchina dello stdlib, incluse le risposte rifiutate, con un report datato nel repo | Costi | S–M | Il pilastro costi non ha nessun numero per run; i token ci sono già in RunResult.usage | | 2 | Usare il punto di aggancio già esistente (ADR 0032) per uno store cifrato e una scadenza dei checkpoint, a partire dalle escalation | Stato | M | Dati personali in chiaro proprio sui casi più sensibili | | 3 | Test di kill-and-resume: uccidere il processo a metà chiamata LLM e riprendere dal checkpoint | Stato / Recovery | M | Oggi è testata solo la ripresa dopo uno stop pulito; il crash, il guasto più comune in produzione, non ha ricevuta | | 4 | Pubblicare i dati grezzi degli esperimenti in evidence/ (JSONL, environments.json, summary.json, REPORT.md, manifest). Per primo copiare l'artifact del run 36544053885 prima che scada il 2026-12-28 | Eval / Recovery | S–M | Oggi 0,57/0,15 e l'accordo tra modelli esistono solo come riepilogo, e un terzo non può verificarli | | 5 | Run a tre bracci first_attempt / plain_resample / feedback_repair su DeepSeek, n ≥ 30, con i dati grezzi salvati | Recovery | S (script pronto) | Decide se repair vale i suoi token o se basta un retry | | 6 | Primo run live di first-true fidelity (2 ripetizioni) e una seconda data sul corpus di confine | Eval | S | Oggi una sola riga live sul corpus di confine e nessuna su first-true | | 7 | Coprire Anthropic nel gate di divergenza | Eval | S (con chiave) | La portabilità oggi vale su due o tre provider |

3. Nota di architettura (com'è oggi)

Un documento .mkl è il programma. loader.py lo carica e lo valida (schema/). engine.py esegue il loop: gli stati producono con un LLM, i gate decidono il passo successivo (avanza, repair, escalate, fail, chiama un tool).

  • I gate in prosa vengono giudicati con una sola chiamata LLM.judge, in ordine di documento e con l'opzione «nessuna» (SPEC §5, first-true).
  • Le regole esatte (importi, date, allowlist) vanno sui gate hook: in codice (ADR 0006).
  • Il contesto non fidato è delimitato (ADR 0025) e la contaminazione del flusso di controllo è tracciata (ADR 0030).
  • In cima al loop ci sono i controlli di budget e il punto di checkpoint: checkpoint.py, con lo store intercambiabile CheckpointStore (ADR 0007/0032).
  • I provider sono in src/mklang/llm/ (OpenAI-compatibile, Anthropic, mock e un adapter Jev opt-in, ADR 0037 «Proposed»).
  • L'uso dei token e il trace finiscono in RunResult.
  • Superfici: CLI, console e server MCP (src/mklang/mcp/).

Limite dichiarato dal progetto: la topologia è esplicita e tracciabile; l'accuratezza dei gate in prosa è empirica, non garantita (what mklang is / is not).

EN abstract

SAMPLE, not a client. This is a production readiness review run on my own open-source project mklang (main @ 67f286da, CI green in run 37348390065) to show the shape of the €3,500 deliverable: a written assessment per pillar, a prioritised list with effort, and an architecture note. It is read-only and no live run was made for this sample.

  • State: good, with a data risk. Resumable checkpoints are covered by 19 tests, the pluggable store (ADR 0032) is implemented, and a cleanly paused run resumes from file in a fresh session. But checkpoints hold the full blackboard as plaintext JSON, with no encrypting store and no expiry, and there is no kill-mid-run test.
  • Recovery: weak and honestly measured. Per the repo's published experiment summary (no raw data), the pass rate went from 0.57 at attempt 1 to 0.15 at attempt 2 on 30 DeepSeek runs, so repair is not shown to beat resampling.
  • Eval: strong method, thin data. The boundary corpus has one live row, first-true fidelity has no live result, and the evidence release holds only a placeholder README.
  • Cost: correct accounting, no per-run cost. Since 1.3.7 refused output is still billed, and the fix is covered by regression tests. There is no per-run cost receipt yet, and measuring it is the top intervention.