Quality gate deterministici

Schema e quality gate proteggono la forma canonica. Non sostituiscono il giudizio umano su accuratezza, chiarezza o utilità.

Obiettivo e transizione autorevole

Il gate trasforma un candidato non fidato in contenuto eleggibile per la persistenza o blocca l'operazione con diagnostica. Non modifica da solo uno stato editoriale.

Input e fonti accettate

L'input è un oggetto Issue Content JSON. topicId, knowledgeAssetIds, issueNumber, categoria, tag e learning objective vengono normalizzati da fonti runtime autorevoli prima del gate finale.

Attore e autorizzazione

Il codice applicativo esegue il gate durante generazione, salvataggio draft, approvazione e pubblicazione. Nessun client può dichiarare autonomamente passed: true.

Validazione e quality gate

Il contratto corrente richiede:

campi obbligatori dello schema e nessuna proprietà estranea;
almeno una sezione pratica;
almeno una sezione di trade-off;
almeno un esempio enterprise realistico;
una sezione references con body e almeno un URL HTTPS negli items;
learning objective e domanda di riflessione non vuoti;
Topic TOPIC-000 e almeno un Knowledge Asset KA-000;
nessun elemento HTML in una stringa canonica;
dimensione massima di 64 KiB.

flowchart TD
    candidate["Candidate JSON"] --> json{"JSON valido?"}
    json -->|"no"| fail["Diagnostica e stop"]
    json -->|"sì"| schema{"Schema valido?"}
    schema -->|"no"| fail
    schema -->|"sì"| normalize["Normalizza metadati runtime"]
    normalize --> quality{"Quality gate passano?"}
    quality -->|"no"| fail
    quality -->|"sì"| persist["Persistenza draft o transizione esplicita"]

Responsabilità dell'AI

Il prompt descrive i requisiti per aumentare la probabilità di successo, ma l'AI non è il validatore. Anche un output plausibile viene respinto se il controllo deterministico fallisce.

Persistenza e audit in D1

Solo contenuto schema-valid e quality-passing entra come draft generato. Le revisioni manuali di un draft sono validate prima dell'update e registrate con numero di revisione, snapshot precedente/nuovo e change reason opzionale.

Evidenza di successo

risultato quality passed: true ricalcolato dal Worker;
zero diagnostiche;
readback dell'Issue con revisione attesa;
per approvazione o pubblicazione, stato autorevole coerente dopo il gate.

Fallimento e recupero

Usare codice, path e messaggio della diagnostica per correggere il campo canonico. Non salvare HTML, output parziali o una versione fuori schema come recovery. Dopo una modifica rileggere la revisione e rieseguire il gate.

Effetti collaterali esclusi

Un gate riuscito non:

prova la correttezza editoriale;
approva o pubblica;
rende pubblico il draft;
prepara una campagna;
dimostra una delivery.