@orkastery/cli 0.2.0

package/dist/master.js

@@ -0,0 +1,453 @@
+"use strict";
+/**
+ * Modulo MASTER/score: o coracao do bloco B2.
+ *
+ * "N looping threads, 1 score." A fase MASTER fecha toda thread, em todo modo, com
+ * duas pecas que o `ork` grava e valida:
+ *
+ *   - `POSTMORTEM.json`: o corpo estruturado, com CLASSES DE FALHA FIXAS. Classe livre
+ *     vira texto solto, e texto solto nao agrega no `ork learn` do B4.
+ *   - `master-log.json`: o MASTER log no CONTRATO CONGELADO. Os nomes dos campos sao o
+ *     contrato e nao mudam. "Uma entrega sem MASTER log nao aconteceu."
+ *
+ * O score e humano, de 0 a 5, com JUSTIFICATIVA OBRIGATORIA: o `ork` recusa score sem
+ * justificativa, em qualquer modo. Nos modos que nao pausam no MASTER (`#Ork`,
+ * `#Maestro`, `#Auto`) o score nao desaparece: a thread cai na fila de batch scoring,
+ * que `ork master --batch` lista para o humano pontuar em bloco.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORDEM_DAS_CLASSES = exports.CLASSES_DE_FALHA = exports.VERSAO_MASTER_LOG = exports.CONTRATO_MASTER_LOG = void 0;
+exports.parseClasse = parseClasse;
+exports.caminhoPostmortem = caminhoPostmortem;
+exports.caminhoMasterLog = caminhoMasterLog;
+exports.fasesPercorridas = fasesPercorridas;
+exports.regimeDoScore = regimeDoScore;
+exports.entregou = entregou;
+exports.exigirScoreValido = exigirScoreValido;
+exports.registrarMaster = registrarMaster;
+exports.validarMasterLog = validarMasterLog;
+exports.lerMasterLog = lerMasterLog;
+exports.pendentesDeScore = pendentesDeScore;
+exports.tabelaDeBatch = tabelaDeBatch;
+exports.textoDoMaster = textoDoMaster;
+exports.tabelaDeClasses = tabelaDeClasses;
+const path = __importStar(require("node:path"));
+const ledger_1 = require("./ledger");
+const modos_1 = require("./modos");
+const thread_1 = require("./thread");
+const types_1 = require("./types");
+const util_1 = require("./util");
+const fs = __importStar(require("node:fs"));
+/** Identificador do contrato congelado do MASTER log. */
+exports.CONTRATO_MASTER_LOG = 'ork.master-log/v1';
+/** Versao do contrato. Uma mudanca de contrato exige uma versao nova, nao um campo novo. */
+exports.VERSAO_MASTER_LOG = 1;
+/** As classes de falha FIXAS do POSTMORTEM, com o que cada uma significa. */
+exports.CLASSES_DE_FALHA = {
+    'sem-falha': 'a thread atravessou o ciclo sem incidente',
+    'erro-de-spec': 'o objetivo ou o plano estavam errados; a execucao seguiu a spec errada',
+    'base-avancou': 'a base mudou embaixo da thread e o trabalho precisou ser ressincronizado',
+    conflito: 'colisao de regiao entre threads, resolvida na mao',
+    'rate-limit': 'o runtime bateu limite de uso e a fase parou por isso',
+    modelo: 'o modelo errou (alucinou, ignorou instrucao, entregou self-report)',
+    processo: 'o metodo falhou: gate faltando, verificacao pulada, evidencia nao coletada',
+    'scope-creep': 'a entrega cresceu alem do que o GOAL prometia',
+    outra: 'nao cabe em nenhuma classe acima (descreva na justificativa)',
+};
+/** Ordem canonica das classes na saida do CLI. */
+exports.ORDEM_DAS_CLASSES = [
+    'sem-falha',
+    'erro-de-spec',
+    'base-avancou',
+    'conflito',
+    'rate-limit',
+    'modelo',
+    'processo',
+    'scope-creep',
+    'outra',
+];
+/** Remove acentos: a classe escrita com acento vira a classe fixa equivalente. */
+function semAcento(texto) {
+    return texto.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+}
+/** Parseia uma classe de falha. Retorna null quando ela nao esta no catalogo fixo. */
+function parseClasse(bruto) {
+    if (!bruto)
+        return null;
+    const limpo = semAcento(bruto.trim().toLowerCase()).replace(/[\s_]+/g, '-');
+    return exports.ORDEM_DAS_CLASSES.includes(limpo)
+        ? limpo
+        : null;
+}
+/** Caminho do POSTMORTEM da thread. */
+function caminhoPostmortem(raiz, id) {
+    return path.join((0, thread_1.dirThread)(raiz, id), 'POSTMORTEM.json');
+}
+/** Caminho do MASTER log da thread. */
+function caminhoMasterLog(raiz, id) {
+    return path.join((0, thread_1.dirThread)(raiz, id), 'master-log.json');
+}
+/**
+ * As fases que a thread realmente percorreu, reconstruidas do LEDGER.
+ *
+ * Nao e o que o modo prometia nem o que a sessao disse ter feito: e o que ficou
+ * registrado, com quantos eventos e em que janela de tempo.
+ */
+function fasesPercorridas(raiz, id) {
+    const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+    const porFase = new Map();
+    for (const e of eventos) {
+        const bruta = typeof e.fase === 'string' ? e.fase.toUpperCase() : null;
+        if (!bruta || !types_1.FASES.includes(bruta))
+            continue;
+        const atual = porFase.get(bruta) ?? {
+            fase: bruta,
+            eventos: 0,
+            primeiroEm: e.ts,
+            ultimoEm: e.ts,
+            sessoes: [],
+        };
+        atual.eventos += 1;
+        atual.ultimoEm = e.ts;
+        const slug = typeof e.slug === 'string' ? e.slug : null;
+        if (slug && !atual.sessoes.includes(slug))
+            atual.sessoes.push(slug);
+        porFase.set(bruta, atual);
+    }
+    return types_1.FASES.filter((f) => porFase.has(f)).map((f) => porFase.get(f));
+}
+/** Regime do score: `pausa` nos modos que param no MASTER, `batch` nos demais. */
+function regimeDoScore(thread) {
+    return (0, thread_1.pausaNaThread)(thread, 'MASTER') ? 'pausa' : 'batch';
+}
+/** A thread ja entregou (o ledger tem `ship_done`)? */
+function entregou(raiz, id) {
+    return (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id)).some((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.shipConcluido);
+}
+/**
+ * Valida o score humano ANTES de gravar qualquer coisa.
+ *
+ * Score sem justificativa nao e score, e carimbo. Por isso o `ork` recusa, e recusa
+ * igual em todos os modos: o modo afrouxa a pausa, nunca a verificacao.
+ */
+function exigirScoreValido(score, justificativa) {
+    if (!Number.isInteger(score) || score < 0 || score > 5) {
+        throw new Error(`score invalido: "${score}". O score do MASTER e um inteiro de 0 a 5 (--score 0..5)`);
+    }
+    if (justificativa.trim().length < 3) {
+        throw new Error('score sem justificativa: o MASTER exige --justificativa "<texto>". ' +
+            'Score sem justificativa nao vira aprendizado e o `ork` nao o registra.');
+    }
+}
+/**
+ * Registra o MASTER da thread: POSTMORTEM tipado, MASTER log no contrato e o score.
+ * Ao fim, a thread fecha (`status: fechada`) e o ledger ganha `master_done`.
+ */
+function registrarMaster(raiz, id, opcoes) {
+    const thread = (0, thread_1.lerThread)(raiz, id);
+    exigirScoreValido(opcoes.score, opcoes.justificativa);
+    if (thread.score && !opcoes.refazer) {
+        throw new Error(`a thread ${id} ja tem score ${thread.score.valor}/5 dado por ${thread.score.avaliadoPor} ` +
+            `em ${thread.score.avaliadoEm}; use --refazer para regravar o MASTER`);
+    }
+    const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id));
+    const gatesBloqueados = eventos
+        .filter((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.gateBloqueado)
+        .map((e) => ({
+        ts: e.ts,
+        motivo: String(e.motivo ?? '(sem motivo)'),
+        detalhe: String(e.detalhe ?? ''),
+    }));
+    const entregas = eventos
+        .filter((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.shipConcluido)
+        .map((e) => ({
+        ts: e.ts,
+        de: String(e.de ?? ''),
+        para: String(e.para ?? ''),
+        mergeSha: String(e.mergeSha ?? ''),
+        pushVerificado: e.pushVerificado === true,
+    }));
+    const avisos = [];
+    let classesInferidas = false;
+    let classes = opcoes.classes ?? [];
+    if (classes.length === 0) {
+        classesInferidas = true;
+        classes = gatesBloqueados.length > 0 ? ['outra'] : ['sem-falha'];
+        avisos.push(gatesBloqueados.length > 0
+            ? `a thread levou ${gatesBloqueados.length} reprovacao(oes) tipada(s) e nenhuma --classe foi ` +
+                'informada: o `ork` gravou "outra". Corrija com --classe <classe> --refazer.'
+            : 'nenhuma --classe informada e nenhum gate reprovou: o `ork` gravou "sem-falha".');
+    }
+    const score = {
+        valor: opcoes.score,
+        justificativa: opcoes.justificativa.trim(),
+        avaliadoPor: (opcoes.por ?? 'humano').trim() || 'humano',
+        avaliadoEm: (0, util_1.agora)(),
+        regime: regimeDoScore(thread),
+    };
+    const percorridas = fasesPercorridas(raiz, id);
+    const resumo = opcoes.resumo?.trim() ||
+        `thread ${thread.id} (${(0, modos_1.tagDoModo)(thread.modo)}) fechada com score ${score.valor}/5 ` +
+            `apos ${percorridas.length} fase(s) registradas no ledger e ${entregas.length} entrega(s)`;
+    const postmortem = {
+        versao: exports.VERSAO_MASTER_LOG,
+        thread: thread.id,
+        slug: thread.slug,
+        modo: thread.modo,
+        tag: (0, modos_1.tagDoModo)(thread.modo),
+        variante: thread.variante ?? null,
+        fasesPercorridas: percorridas,
+        classesDeFalha: classes,
+        score,
+        gatesBloqueados,
+        decisoesAutonomas: eventos.filter((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.decisaoAutonoma).length,
+        pausasHumanas: eventos.filter((e) => e.tipo === ledger_1.TIPOS_DE_EVENTO.pausaHumana).length,
+        entregas,
+        resumo,
+        geradoEm: (0, util_1.agora)(),
+    };
+    const masterLog = {
+        contrato: exports.CONTRATO_MASTER_LOG,
+        versao: exports.VERSAO_MASTER_LOG,
+        thread: thread.id,
+        slug: thread.slug,
+        projeto: thread.projeto,
+        modo: thread.modo,
+        tag: (0, modos_1.tagDoModo)(thread.modo),
+        variante: thread.variante ?? null,
+        // Fases PERCORRIDAS, nao as prometidas pelo modo. Ledger vazio vira ['MASTER'], que e
+        // a unica fase que de fato aconteceu: dizer o contrario seria self-report.
+        fases: percorridas.length > 0 ? percorridas.map((f) => f.fase) : ['MASTER'],
+        score: score.valor,
+        justificativa: score.justificativa,
+        avaliadoPor: score.avaliadoPor,
+        avaliadoEm: score.avaliadoEm,
+        classesDeFalha: classes,
+        resumo,
+        base: thread.base,
+        worktree: thread.worktree,
+        evidencia: {
+            ledger: path.join('.orkastery', 'threads', thread.id, 'ledger.jsonl'),
+            postmortem: path.join('.orkastery', 'threads', thread.id, 'POSTMORTEM.json'),
+            eventos: eventos.length,
+            sessoes: thread.sessoes.length,
+            claims: thread.claims.length,
+        },
+    };
+    const invalido = validarMasterLog(masterLog);
+    if (invalido.length > 0) {
+        throw new Error(`MASTER log fora do contrato congelado:\n  - ${invalido.join('\n  - ')}`);
+    }
+    const caminhoP = caminhoPostmortem(raiz, id);
+    const caminhoM = caminhoMasterLog(raiz, id);
+    (0, util_1.gravarJson)(caminhoP, postmortem);
+    (0, util_1.gravarJson)(caminhoM, masterLog);
+    thread.score = score;
+    thread.faseAtual = 'MASTER';
+    thread.status = 'fechada';
+    (0, thread_1.gravarThread)(raiz, thread);
+    (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, id), id, ledger_1.TIPOS_DE_EVENTO.postmortemGravado, {
+        fase: 'MASTER',
+        classesDeFalha: classes,
+        classesInferidas,
+        gatesBloqueados: gatesBloqueados.length,
+        arquivo: path.relative(raiz, caminhoP),
+    });
+    (0, ledger_1.registrar)((0, thread_1.dirThread)(raiz, id), id, ledger_1.TIPOS_DE_EVENTO.masterConcluido, {
+        fase: 'MASTER',
+        modo: thread.modo,
+        tag: (0, modos_1.tagDoModo)(thread.modo),
+        score: score.valor,
+        justificativa: score.justificativa,
+        autorizadoPor: score.avaliadoPor,
+        regime: score.regime,
+        contrato: exports.CONTRATO_MASTER_LOG,
+        arquivo: path.relative(raiz, caminhoM),
+        estado: 'thread fechada',
+    });
+    return {
+        thread,
+        postmortem,
+        masterLog,
+        caminhoPostmortem: caminhoP,
+        caminhoMasterLog: caminhoM,
+        classesInferidas,
+        avisos,
+    };
+}
+/**
+ * Valida um MASTER log contra o contrato congelado. Devolve a lista de erros (vazia = valido).
+ * E o mesmo validador que a suite roda: o contrato e executavel, nao prosa.
+ */
+function validarMasterLog(bruto) {
+    const erros = [];
+    if (!bruto || typeof bruto !== 'object')
+        return ['o MASTER log nao e um objeto'];
+    const log = bruto;
+    if (log.contrato !== exports.CONTRATO_MASTER_LOG) {
+        erros.push(`campo "contrato" deve ser "${exports.CONTRATO_MASTER_LOG}"`);
+    }
+    if (log.versao !== exports.VERSAO_MASTER_LOG)
+        erros.push(`campo "versao" deve ser ${exports.VERSAO_MASTER_LOG}`);
+    for (const campo of ['thread', 'slug', 'modo', 'tag', 'justificativa', 'resumo', 'avaliadoPor']) {
+        const v = log[campo];
+        if (typeof v !== 'string' || v.trim() === '')
+            erros.push(`campo "${campo}" ausente ou vazio`);
+    }
+    if (typeof log.score !== 'number' || !Number.isInteger(log.score) || log.score < 0 || log.score > 5) {
+        erros.push('campo "score" deve ser um inteiro de 0 a 5');
+    }
+    if (typeof log.avaliadoEm !== 'string' || Number.isNaN(Date.parse(log.avaliadoEm))) {
+        erros.push('campo "avaliadoEm" deve ser um carimbo ISO valido');
+    }
+    if (!Array.isArray(log.fases) || log.fases.length === 0) {
+        erros.push('campo "fases" deve listar as fases percorridas');
+    }
+    else {
+        const fora = log.fases.filter((f) => !types_1.FASES.includes(f));
+        if (fora.length > 0)
+            erros.push(`campo "fases" tem fase fora do ciclo canonico: ${fora.join(', ')}`);
+    }
+    if (!Array.isArray(log.classesDeFalha) || log.classesDeFalha.length === 0) {
+        erros.push('campo "classesDeFalha" deve ter ao menos uma classe fixa');
+    }
+    else {
+        const fora = log.classesDeFalha.filter((c) => !exports.ORDEM_DAS_CLASSES.includes(c));
+        if (fora.length > 0) {
+            erros.push(`campo "classesDeFalha" tem classe fora do catalogo fixo: ${fora.join(', ')}`);
+        }
+    }
+    if (!log.projeto || typeof log.projeto.name !== 'string' || typeof log.projeto.abbrev !== 'string') {
+        erros.push('campo "projeto" precisa de name e abbrev');
+    }
+    if (!log.base || typeof log.base.branch !== 'string' || typeof log.base.commit !== 'string') {
+        erros.push('campo "base" precisa de branch e commit');
+    }
+    if (!log.evidencia || typeof log.evidencia.ledger !== 'string' || typeof log.evidencia.postmortem !== 'string') {
+        erros.push('campo "evidencia" precisa apontar o ledger e o POSTMORTEM');
+    }
+    return erros;
+}
+/** Le o MASTER log de uma thread, quando existe. */
+function lerMasterLog(raiz, id) {
+    const caminho = caminhoMasterLog(raiz, id);
+    if (!fs.existsSync(caminho))
+        return null;
+    return (0, util_1.lerJson)(caminho);
+}
+/**
+ * A fila de batch scoring: threads que entregaram (ou chegaram ao MASTER) e ainda nao
+ * tem score. E a fila que `#Ork`, `#Maestro` e `#Auto` alimentam ao entregar sem pausa.
+ */
+function pendentesDeScore(raiz, todas = false) {
+    const saida = [];
+    for (const id of (0, thread_1.listarIds)(raiz)) {
+        const thread = (0, thread_1.lerThread)(raiz, id);
+        if (thread.score)
+            continue;
+        const jaEntregou = entregou(raiz, id);
+        const noMaster = thread.faseAtual === 'MASTER';
+        if (!todas && !jaEntregou && !noMaster)
+            continue;
+        saida.push({
+            thread,
+            regime: regimeDoScore(thread),
+            entregou: jaEntregou,
+            noMaster,
+            fasesPercorridas: fasesPercorridas(raiz, id).length,
+        });
+    }
+    return saida;
+}
+/** Tabela de `ork master --batch`: o review em bloco. */
+function tabelaDeBatch(raiz, todas = false) {
+    const pendentes = pendentesDeScore(raiz, todas);
+    if (pendentes.length === 0) {
+        return todas
+            ? 'Nenhuma thread aberta sem score. A fila de batch scoring esta vazia.'
+            : 'Nenhuma thread entregue esperando score. A fila de batch scoring esta vazia.\n' +
+                'Para ver tambem as threads que ainda nao entregaram: ork master --batch --todas';
+    }
+    const linhas = pendentes.map((p) => [
+        p.thread.id,
+        p.thread.slug,
+        (0, modos_1.tagDoModo)(p.thread.modo),
+        p.thread.faseAtual,
+        p.thread.status,
+        p.regime,
+        p.entregou ? 'sim' : 'nao',
+        String(p.fasesPercorridas),
+    ]);
+    const cabecalho = (0, util_1.tabela)(['ID', 'SLUG', 'MODO', 'FASE', 'STATUS', 'REGIME', 'ENTREGOU', 'FASES'], linhas);
+    return [
+        `Fila de score (${pendentes.length} thread(s) esperando o humano)`,
+        '',
+        cabecalho,
+        '',
+        'Pontue em bloco, uma linha por thread:',
+        ...pendentes.map((p) => `  ork master ${p.thread.id} --score <0-5> --justificativa "<por que>" --classe <classe>`),
+        '',
+        `Classes fixas: ${exports.ORDEM_DAS_CLASSES.join(', ')}`,
+    ].join('\n');
+}
+/** Texto de `ork master <thread-id> --score`. */
+function textoDoMaster(r) {
+    const linhas = [];
+    linhas.push(`MASTER registrado: thread ${r.thread.id} fechada.`);
+    linhas.push(`  score          ${r.masterLog.score}/5 (${r.postmortem.score.regime})`);
+    linhas.push(`  justificativa  ${r.masterLog.justificativa}`);
+    linhas.push(`  avaliado por   ${r.masterLog.avaliadoPor} em ${r.masterLog.avaliadoEm}`);
+    linhas.push(`  classes        ${r.masterLog.classesDeFalha.join(', ')}`);
+    linhas.push(`  fases          ${r.masterLog.fases.join(' -> ')}`);
+    linhas.push(`  entregas       ${r.postmortem.entregas.length} ship(s) concluido(s) no ledger`);
+    linhas.push(`  gates          ${r.postmortem.gatesBloqueados.length} reprovacao(oes) tipada(s)`);
+    linhas.push('');
+    linhas.push(`  POSTMORTEM     ${r.caminhoPostmortem}`);
+    linhas.push(`  MASTER log     ${r.caminhoMasterLog} (contrato ${r.masterLog.contrato})`);
+    if (r.avisos.length > 0) {
+        linhas.push('');
+        for (const a of r.avisos)
+            linhas.push(`  AVISO: ${a}`);
+    }
+    return linhas.join('\n');
+}
+/** Tabela das classes de falha fixas, para o humano escolher sem inventar. */
+function tabelaDeClasses() {
+    const linhas = ['Classes de falha do POSTMORTEM (fixas, nao extensiveis pelo executor)', ''];
+    for (const c of exports.ORDEM_DAS_CLASSES)
+        linhas.push(`  ${c.padEnd(14)} ${exports.CLASSES_DE_FALHA[c]}`);
+    return linhas.join('\n');
+}