@orkastery/cli 0.5.1 → 0.5.6

package/dist/conhecimento.js

@@ -0,0 +1,490 @@
+"use strict";
+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.LIMITES_DO_CONHECIMENTO = exports.REFERENCIA_DE_DECISAO = exports.NOME_DE_COLECAO = exports.ID_DE_DOCUMENTO = exports.CONTRATO_CONHECIMENTO = void 0;
+exports.lerConhecimento = lerConhecimento;
+/**
+ * RM-026 K7 (fatia 1): conhecimento escrito, no contrato `ork.conhecimento/v1`.
+ *
+ * Cada documento é um Markdown versionado na pasta que o `orkastery.yaml` declara (`conhecimento.dir`), com
+ * frontmatter fechado: `id` (`doc-...`), `titulo`, `colecoes` e, opcional, `referencias` a ids do Brain e a
+ * decisões `thread#linha` do ledger. A coleção é o nome no frontmatter, sem arquivo próprio.
+ *
+ * Só leitura. Documento inválido ou referência que não confere vira lacuna tipada, nunca resposta (D4). A pasta
+ * vem com o repositório e segue a fronteira da RM-047 (D6): relativa, dentro da raiz pelo caminho real, sem
+ * seguir link e sem executar nada. Nesta fatia a decisão confere no ledger canônico e o id do Brain só pela forma
+ * (D5); a CLI, as tools MCP e a conferência pelo Brain chegam nas fatias 2 e 3. Contrato:
+ * docs/referencia/contratos/conhecimento-rm026.md.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const company_brain_journal_1 = require("./company-brain-journal");
+const docs_1 = require("./docs");
+const portfolio_1 = require("./portfolio");
+const saida_segura_1 = require("./saida-segura");
+const thread_1 = require("./thread");
+const yaml_1 = require("./yaml");
+exports.CONTRATO_CONHECIMENTO = 'ork.conhecimento/v1';
+/** D3: a forma do id do documento (a regra dos ids do portfólio), da coleção e da citação de decisão. */
+exports.ID_DE_DOCUMENTO = /^doc-[a-z0-9][a-z0-9-]{2,47}$/;
+exports.NOME_DE_COLECAO = /^[a-z0-9][a-z0-9-]{0,47}$/;
+exports.REFERENCIA_DE_DECISAO = /^([a-zA-Z0-9][a-zA-Z0-9._-]{0,79})#([1-9][0-9]{0,8})$/;
+const LIMITE_DO_TITULO = 160;
+const COLECOES_POR_DOCUMENTO = 16;
+const REFERENCIAS_POR_LISTA = 64;
+/** D2: as chaves do frontmatter; qualquer outra invalida o documento. */
+const CHAVES_DO_DOCUMENTO = ['id', 'titulo', 'colecoes', 'referencias'];
+const CHAVES_DAS_REFERENCIAS = ['brain', 'decisoes'];
+/** D5: as linhas do ledger que são decisão, as do dossiê; `human_decision` é relato sem recibo e não conta. */
+const TIPOS_DE_DECISAO = ['autonomous_decision', 'hitl_requested', 'human_gate'];
+/** D6: pastas do repositório que nunca guardam conhecimento, sem distinguir caixa (o disco do macOS não distingue). */
+const PASTAS_RESERVADAS = ['.git', '.orkastery'];
+const reservada = (segmento) => PASTAS_RESERVADAS.includes(segmento.toLowerCase());
+/** D10: o invisível é o do `saida-segura.ts`, a regra única do núcleo para texto alheio (ZWJ e seletores de emoji valem). */
+const INVISIVEIS = new RegExp(saida_segura_1.INVISIVEL.source, 'gu');
+exports.LIMITES_DO_CONHECIMENTO = Object.freeze({
+    entradas: 5000, profundidade: 8, bytesPorDocumento: 1024 * 1024, bytesDoFrontmatter: 16 * 1024,
+    bytesNoTotal: 32 * 1024 * 1024, bytesDoLedger: 16 * 1024 * 1024,
+});
+const comparar = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const ehMapa = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Texto que veio do repositório, pronto para a resposta: numa linha, sem invisível e, com teto, cortado sem partir caractere. */
+const limpo = (v, teto = Infinity) => Array.from((0, saida_segura_1.emUmaLinha)(v)).slice(0, teto).join('');
+const relativo = (raizReal, abs) => path.relative(raizReal, abs).split(path.sep).join('/');
+const LINK = 'link simbólico não é seguido; o documento é o arquivo versionado';
+/** `stat` que nunca lança: a pasta que some ou não abre vale como ausente. */
+const statOuNulo = (p) => { try {
+    return fs.statSync(p, { throwIfNoEntry: false }) ?? null;
+}
+catch {
+    return null;
+} };
+function lacuna(codigo, detalhe, onde = {}) {
+    return { codigo, arquivo: onde.arquivo ?? null, documento: onde.documento ?? null,
+        referencia: typeof onde.referencia === 'string' ? limpo(onde.referencia, 200) : null, detalhe };
+}
+/**
+ * D6: a pasta declarada, pelo caminho real. A forma recusa antes de tocar o disco (vazia, absoluta, `..`, `\`,
+ * invisível, a própria raiz, `.git` e `.orkastery`); o caminho real, com os links resolvidos, precisa ficar dentro
+ * da raiz.
+ */
+function pastaDoConhecimento(raiz, dir) {
+    const segmentos = dir.split('/').filter((s) => s !== '' && s !== '.');
+    if (path.isAbsolute(dir) || dir.includes('\\') || saida_segura_1.INVISIVEL.test(dir) || !segmentos.length || segmentos.includes('..') ||
+        reservada(segmentos[0])) {
+        return lacuna('conhecimento.dir-invalido', 'conhecimento.dir precisa ser uma pasta relativa à raiz, sem "..", ' +
+            'fora de .git e .orkastery, como docs/conhecimento; nada foi lido');
+    }
+    let raizReal, real;
+    try {
+        raizReal = fs.realpathSync(raiz);
+        real = fs.realpathSync(path.join(raizReal, ...segmentos));
+    }
+    catch {
+        return lacuna('conhecimento.dir-ausente', 'a pasta de conhecimento.dir não existe ou não abre');
+    }
+    const rel = path.relative(raizReal, real);
+    if (rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) {
+        return lacuna('conhecimento.dir-fora-da-raiz', 'pelo caminho real (links resolvidos), conhecimento.dir sai da raiz ' +
+            'do projeto; o manifesto vem com o repositório e não escolhe caminho fora dela; nada foi lido');
+    }
+    if (rel === '' || reservada(rel.split(path.sep)[0]) || saida_segura_1.INVISIVEL.test(rel)) {
+        return lacuna('conhecimento.dir-invalido', 'pelo caminho real, conhecimento.dir é a própria raiz, cai em .git ou ' +
+            '.orkastery, ou tem caractere invisível; nada foi lido');
+    }
+    if (!statOuNulo(real)?.isDirectory())
+        return lacuna('conhecimento.dir-ausente', 'conhecimento.dir não é uma pasta');
+    return { real, raizReal };
+}
+/**
+ * Varre a pasta sem seguir link (D6) e sem ler entrada oculta (D8). Devolve os candidatos a documento, ou o
+ * detalhe do teto estourado (D7), que falha fechado. Entrada que não abre vira lacuna, nunca exceção.
+ */
+function varrer(real, raizReal, limites, lacunas) {
+    const candidatos = [];
+    const pilha = [{ abs: real, profundidade: 0 }];
+    let entradas = 0;
+    while (pilha.length) {
+        const atual = pilha.pop();
+        // Uma pasta trocada por link depois de entrar na pilha não leva a varredura para fora: o caminho real é
+        // conferido logo antes da listagem. Num clone parado não há troca; a conferência fecha a janela larga.
+        let realDaPasta;
+        try {
+            realDaPasta = fs.realpathSync(atual.abs);
+        }
+        catch {
+            realDaPasta = null;
+        }
+        if (realDaPasta !== atual.abs) {
+            lacunas.push(lacuna('documento.link', LINK, { arquivo: relativo(raizReal, atual.abs) }));
+            continue;
+        }
+        let nomes;
+        try {
+            nomes = fs.readdirSync(atual.abs, { encoding: 'buffer' }).sort(Buffer.compare);
+        }
+        catch {
+            lacunas.push(lacuna('documento.nao-regular', 'a pasta não abriu para leitura; o que está nela não foi lido', { arquivo: relativo(raizReal, atual.abs) }));
+            continue;
+        }
+        for (const bruto of nomes) {
+            if (bruto[0] === 0x2e)
+                continue;
+            if (++entradas > limites.entradas)
+                return { teto: `a pasta passa de ${limites.entradas} entradas` };
+            const nome = bruto.toString('utf8');
+            if (!Buffer.from(nome, 'utf8').equals(bruto) || saida_segura_1.INVISIVEL.test(nome)) {
+                lacunas.push(lacuna('documento.nome-invalido', 'nome fora de UTF-8 ou com caractere invisível; não foi lido', { arquivo: relativo(raizReal, path.join(atual.abs, nome.replace(INVISIVEIS, '?'))) }));
+                continue;
+            }
+            const abs = path.join(atual.abs, nome), arquivo = relativo(raizReal, abs);
+            let st;
+            try {
+                st = fs.lstatSync(abs, { throwIfNoEntry: false });
+            }
+            catch {
+                lacunas.push(lacuna('documento.nao-regular', 'a entrada não abriu para leitura; não foi lida', { arquivo }));
+                continue;
+            }
+            if (!st)
+                continue;
+            if (st.isSymbolicLink()) {
+                lacunas.push(lacuna('documento.link', LINK, { arquivo }));
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (atual.profundidade + 1 > limites.profundidade)
+                    return { teto: `a pasta passa de ${limites.profundidade} níveis` };
+                pilha.push({ abs, profundidade: atual.profundidade + 1 });
+                continue;
+            }
+            if (!(0, docs_1.ehPaginaDeDocs)(nome))
+                continue;
+            if (!st.isFile()) {
+                lacunas.push(lacuna('documento.nao-regular', 'não é arquivo comum; não foi lido', { arquivo }));
+                continue;
+            }
+            candidatos.push({ abs, arquivo, st });
+        }
+    }
+    return candidatos;
+}
+/**
+ * Lê um arquivo comum sem seguir link (`O_NOFOLLOW`) e sem travar em FIFO (`O_NONBLOCK`), conferindo que é o
+ * mesmo do `lstat` e que cabe no teto. Devolve os bytes ou o motivo. Com `crescer` (o ledger, que só recebe linha
+ * no fim), vale o que existia no `fstat`, mesmo que o arquivo cresça durante a leitura; o documento que muda
+ * durante a leitura não vale.
+ */
+function lerArquivo(abs, st, teto, crescer = false) {
+    let fd;
+    try {
+        fd = fs.openSync(abs, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    }
+    catch (e) {
+        return e.code === 'ELOOP' ? 'link' : 'nao-regular';
+    }
+    try {
+        const f = fs.fstatSync(fd);
+        if (!f.isFile() || f.dev !== st.dev || f.ino !== st.ino)
+            return 'nao-regular';
+        if (f.size > teto)
+            return 'grande';
+        const bytes = Buffer.alloc(crescer ? f.size : f.size + 1);
+        let lidos = 0, n;
+        while (lidos < bytes.length && (n = fs.readSync(fd, bytes, lidos, bytes.length - lidos, null)) > 0)
+            lidos += n;
+        if (crescer)
+            return bytes.subarray(0, lidos);
+        return lidos === f.size ? bytes.subarray(0, lidos) : 'nao-regular';
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Valor de lista do frontmatter: lista de textos ou um texto só. Inteiro vira texto, sem perda; nulo, booleano
+ * e decimal (o `yes` que o YAML lê como `true`, a vírgula sobrando que vira nulo) recusam em vez de virar texto.
+ */
+function lista(v) {
+    if (v === undefined || v === null)
+        return [];
+    const itens = [];
+    for (const b of Array.isArray(v) ? v : [v]) {
+        if (typeof b === 'string')
+            itens.push(b);
+        else if (typeof b === 'number' && Number.isSafeInteger(b))
+            itens.push(String(b));
+        else
+            return null;
+    }
+    return itens;
+}
+/** D2 e D3: o frontmatter vale inteiro ou devolve a lacuna do primeiro problema, com o id quando ele já vale. */
+function validarFrontmatter(dados, arquivo) {
+    if (!ehMapa(dados))
+        return lacuna('documento.frontmatter-invalido', 'o frontmatter precisa ser um mapa de chaves', { arquivo });
+    const id = typeof dados.id === 'string' && exports.ID_DE_DOCUMENTO.test(dados.id) ? dados.id : null;
+    if (!id) {
+        return lacuna('documento.id-invalido', 'id precisa ser doc- seguido de 3 a 48 letras minúsculas, números ou hífens, ' +
+            'começando por letra ou número', { arquivo });
+    }
+    const onde = { arquivo, documento: id };
+    const estranhas = Object.keys(dados).filter((k) => !CHAVES_DO_DOCUMENTO.includes(k));
+    if (estranhas.length) {
+        return lacuna('documento.chave-desconhecida', `chave fora do contrato: ${estranhas.map((k) => JSON.stringify(limpo(k, 40))).join(', ')} ` +
+            `(o frontmatter tem só ${CHAVES_DO_DOCUMENTO.join(', ')})`, onde);
+    }
+    const titulo = typeof dados.titulo === 'string' ? dados.titulo.trim() : '';
+    if (!titulo || titulo.length > LIMITE_DO_TITULO || saida_segura_1.INVISIVEL.test(titulo)) {
+        return lacuna('documento.titulo-invalido', `titulo precisa ser texto de 1 a ${LIMITE_DO_TITULO} caracteres, ` +
+            'sem caractere de controle', onde);
+    }
+    const colecoes = lista(dados.colecoes);
+    if (!colecoes || !colecoes.length || colecoes.length > COLECOES_POR_DOCUMENTO ||
+        colecoes.some((c) => !exports.NOME_DE_COLECAO.test(c)) || new Set(colecoes).size !== colecoes.length) {
+        return lacuna('documento.colecoes-invalidas', `colecoes precisa listar de 1 a ${COLECOES_POR_DOCUMENTO} nomes ` +
+            'de 1 a 48 letras minúsculas, números ou hífens, sem repetir', onde);
+    }
+    const refs = dados.referencias ?? null;
+    const brain = ehMapa(refs) ? lista(refs.brain) : [], decisoes = ehMapa(refs) ? lista(refs.decisoes) : [];
+    if ((refs !== null && !ehMapa(refs)) || (ehMapa(refs) && Object.keys(refs).some((k) => !CHAVES_DAS_REFERENCIAS.includes(k))) ||
+        !brain || brain.length > REFERENCIAS_POR_LISTA || !decisoes || decisoes.length > REFERENCIAS_POR_LISTA) {
+        return lacuna('documento.referencias-invalidas', 'referencias é um mapa só com brain e decisoes, cada uma uma lista ' +
+            `de até ${REFERENCIAS_POR_LISTA} textos`, onde);
+    }
+    return { id, titulo, colecoes: [...colecoes].sort(comparar), brain: [...new Set(brain)], decisoes: [...new Set(decisoes)] };
+}
+/**
+ * As linhas citadas do ledger canônico de uma thread (D5). O ledger é lido como a captura do Brain o lê
+ * (`readCycle`): só linhas completas, em UTF-8 exato, para o sha256 da linha ser o `source_hash` dela no Brain.
+ * Cada ledger é lido uma vez, e só as linhas citadas ficam na memória.
+ */
+function linhasCitadas(raiz, thread, citadas, teto) {
+    let arquivo;
+    try {
+        arquivo = path.join((0, thread_1.dirThread)(raiz, thread), 'ledger.jsonl');
+    }
+    catch {
+        return { motivo: 'a pasta da thread no estado do projeto é link ou fica fora da regra de id' };
+    }
+    let st;
+    try {
+        st = fs.lstatSync(arquivo, { throwIfNoEntry: false });
+    }
+    catch (e) {
+        // A pasta da thread que é arquivo comum dá ENOTDIR: a thread não tem ledger, e nada lança.
+        if (e.code !== 'ENOTDIR')
+            return { motivo: `o ledger da thread ${thread} não abriu para leitura` };
+    }
+    if (!st)
+        return { motivo: `a thread ${thread} não tem ledger neste projeto` };
+    const bytes = lerArquivo(arquivo, st, teto, true);
+    if (!Buffer.isBuffer(bytes))
+        return { motivo: `o ledger da thread ${thread} não é arquivo comum de até ${teto / 1024 / 1024} MiB` };
+    const fim = bytes.lastIndexOf(10) + 1;
+    const completo = bytes.subarray(0, fim).toString('utf8');
+    if (!Buffer.from(completo, 'utf8').equals(bytes.subarray(0, fim)))
+        return { motivo: `o ledger da thread ${thread} não é UTF-8` };
+    const todas = completo.split('\n').slice(0, -1);
+    const linhas = new Map();
+    for (const n of citadas)
+        if (n <= todas.length)
+            linhas.set(n, todas[n - 1]);
+    return { linhas, completas: todas.length };
+}
+/** D5: a referência `thread#linha` confere quando a linha completa existe, é da thread e é uma decisão. */
+function conferirDecisao(ref, ledgers) {
+    const m = exports.REFERENCIA_DE_DECISAO.exec(ref);
+    if (!m)
+        return { codigo: 'referencia.invalida', detalhe: 'decisão é <thread>#<linha>, com o id da thread e a linha do ledger a partir de 1' };
+    const thread = m[1], linha = Number(m[2]);
+    const ledger = ledgers.get(thread);
+    if ('motivo' in ledger)
+        return { codigo: 'referencia.decisao-ausente', detalhe: ledger.motivo };
+    const bruta = ledger.linhas.get(linha);
+    if (bruta === undefined) {
+        return { codigo: 'referencia.decisao-ausente', detalhe: `o ledger da thread ${thread} tem ${ledger.completas} linha(s) completa(s)` };
+    }
+    let evento = null;
+    try {
+        const lido = JSON.parse(bruta);
+        if (lido && typeof lido === 'object' && !Array.isArray(lido))
+            evento = lido;
+    }
+    catch { /* linha que não é JSON não é decisão */ }
+    const onde = `a linha ${linha} do ledger da thread ${thread}`;
+    if (!evento)
+        return { codigo: 'referencia.nao-e-decisao', detalhe: `${onde} não é um evento JSON` };
+    if (evento.thread !== thread)
+        return { codigo: 'referencia.nao-e-decisao', detalhe: `${onde} é de outra thread` };
+    const tipo = TIPOS_DE_DECISAO.find((t) => t === evento?.tipo);
+    if (!tipo) {
+        const visto = typeof evento.tipo === 'string' && /^[a-z_]{1,40}$/.test(evento.tipo) ? evento.tipo : 'sem tipo conhecido';
+        return { codigo: 'referencia.nao-e-decisao', detalhe: `${onde} é ${visto}, não decisão (${TIPOS_DE_DECISAO.join(', ')})` };
+    }
+    return { ref, thread, linha, tipo, fonte: `threads/${thread}/ledger.jsonl#L${linha}`, sha256: (0, company_brain_journal_1.bytesHash)(bruta) };
+}
+/**
+ * Lê o conhecimento declarado no manifesto: documentos válidos, coleções e lacunas, tudo em ordem estável.
+ * Nunca lança por causa do conteúdo do repositório; o que não vale vira lacuna tipada.
+ */
+function lerConhecimento(c, limites = exports.LIMITES_DO_CONHECIMENTO) {
+    const declarado = c.manifesto.conhecimento?.dir ?? null;
+    const dir = declarado === null ? null : limpo(declarado);
+    const so = (l) => ({ contrato: exports.CONTRATO_CONHECIMENTO, dir, documentos: [], colecoes: [], lacunas: [l] });
+    if (declarado === null)
+        return so(lacuna('conhecimento.nao-declarado', 'o orkastery.yaml não declara conhecimento.dir'));
+    const pasta = pastaDoConhecimento(c.raiz, declarado);
+    if ('codigo' in pasta)
+        return so(pasta);
+    const teto = (detalhe) => so(lacuna('conhecimento.limite', `${detalhe}; nenhum documento foi devolvido`));
+    const lacunas = [];
+    const candidatos = varrer(pasta.real, pasta.raizReal, limites, lacunas);
+    if (!Array.isArray(candidatos))
+        return teto(candidatos.teto);
+    const decodificador = new TextDecoder('utf-8', { fatal: true });
+    const validos = [];
+    const declarados = new Map();
+    let total = 0;
+    for (const { abs, arquivo, st } of candidatos) {
+        const bytes = lerArquivo(abs, st, limites.bytesPorDocumento);
+        if (bytes === 'link') {
+            lacunas.push(lacuna('documento.link', LINK, { arquivo }));
+            continue;
+        }
+        if (bytes === 'nao-regular') {
+            lacunas.push(lacuna('documento.nao-regular', 'não abriu como arquivo comum, ou mudou durante a leitura', { arquivo }));
+            continue;
+        }
+        if (bytes === 'grande') {
+            lacunas.push(lacuna('documento.grande-demais', `o documento passa de ${limites.bytesPorDocumento / 1024} KiB`, { arquivo }));
+            continue;
+        }
+        total += bytes.length;
+        if (total > limites.bytesNoTotal)
+            return teto(`os documentos passam de ${limites.bytesNoTotal / 1024 / 1024} MiB no total`);
+        let texto;
+        try {
+            texto = decodificador.decode(bytes);
+        }
+        catch {
+            lacunas.push(lacuna('documento.codificacao', 'o arquivo não é UTF-8', { arquivo }));
+            continue;
+        }
+        const { bruto } = (0, docs_1.separarFrontmatter)(texto);
+        if (bruto === null) {
+            lacunas.push(lacuna('documento.sem-frontmatter', 'o arquivo não começa com o frontmatter entre duas linhas ---', { arquivo }));
+            continue;
+        }
+        if (Buffer.byteLength(bruto, 'utf8') > limites.bytesDoFrontmatter) {
+            lacunas.push(lacuna('documento.frontmatter-invalido', `o frontmatter passa de ${limites.bytesDoFrontmatter / 1024} KiB`, { arquivo }));
+            continue;
+        }
+        let dados;
+        // A linha do `---` de abertura entra na leitura (e é pulada nela) para o erro dizer a linha do arquivo.
+        try {
+            dados = (0, yaml_1.lerYaml)('---\n' + bruto, { estrito: true });
+        }
+        catch (e) {
+            lacunas.push(lacuna('documento.frontmatter-invalido', limpo(e.message, 200), { arquivo }));
+            continue;
+        }
+        // D4: o id na forma certa conta para a regra do repetido mesmo quando o resto do documento não vale.
+        const idDeclarado = ehMapa(dados) && typeof dados.id === 'string' && exports.ID_DE_DOCUMENTO.test(dados.id) ? dados.id : null;
+        if (idDeclarado)
+            declarados.set(idDeclarado, (declarados.get(idDeclarado) ?? 0) + 1);
+        const v = validarFrontmatter(dados, arquivo);
+        if ('codigo' in v) {
+            lacunas.push(v);
+            continue;
+        }
+        validos.push({ ...v, arquivo, bytes: bytes.length, sha256: (0, company_brain_journal_1.bytesHash)(bytes) });
+    }
+    // D4: id repetido não escolhe arquivo; todos os documentos com ele saem da resposta, também quando a outra
+    // cópia não vale por outro motivo (ela já tem a lacuna dela).
+    const unicos = validos.filter((v) => {
+        const vezes = declarados.get(v.id);
+        if (vezes > 1) {
+            lacunas.push(lacuna('documento.id-repetido', `o id aparece em ${vezes} arquivos; nenhum deles vale até sobrar um`, { arquivo: v.arquivo, documento: v.id }));
+        }
+        return vezes === 1;
+    });
+    // D5: cada ledger citado é lido uma vez, com as linhas que os documentos válidos pedem.
+    const citadas = new Map();
+    for (const v of unicos)
+        for (const ref of v.decisoes) {
+            const m = exports.REFERENCIA_DE_DECISAO.exec(ref);
+            if (m)
+                citadas.set(m[1], (citadas.get(m[1]) ?? new Set()).add(Number(m[2])));
+        }
+    const ledgers = new Map();
+    for (const [thread, linhas] of citadas)
+        ledgers.set(thread, linhasCitadas(c.raiz, thread, linhas, limites.bytesDoLedger));
+    const documentos = [];
+    for (const v of unicos) {
+        const onde = { arquivo: v.arquivo, documento: v.id };
+        const brain = [], decisoes = [];
+        for (const referencia of v.brain) {
+            if (portfolio_1.ID_DE_ENTIDADE.test(referencia))
+                brain.push(referencia);
+            else
+                lacunas.push(lacuna('referencia.invalida', 'id do Brain é prod-, proj- ou init-, na regra dos ids do portfólio', { ...onde, referencia }));
+        }
+        for (const referencia of v.decisoes) {
+            const r = conferirDecisao(referencia, ledgers);
+            if ('codigo' in r)
+                lacunas.push(lacuna(r.codigo, r.detalhe, { ...onde, referencia }));
+            else
+                decisoes.push(r);
+        }
+        documentos.push({ id: v.id, titulo: v.titulo, colecoes: v.colecoes,
+            referencias: { brain: brain.sort(comparar), decisoes: decisoes.sort((a, b) => comparar(a.thread, b.thread) || a.linha - b.linha) },
+            arquivo: v.arquivo, bytes: v.bytes, sha256: v.sha256 });
+    }
+    const colecoes = new Map();
+    for (const d of documentos)
+        for (const nome of d.colecoes) {
+            const ids = colecoes.get(nome) ?? [];
+            ids.push(d.id);
+            colecoes.set(nome, ids);
+        }
+    return {
+        contrato: exports.CONTRATO_CONHECIMENTO, dir,
+        documentos: documentos.sort((a, b) => comparar(a.id, b.id)),
+        colecoes: [...colecoes].map(([nome, ids]) => ({ nome, documentos: ids.sort(comparar) })).sort((a, b) => comparar(a.nome, b.nome)),
+        lacunas: lacunas.sort((a, b) => comparar(a.arquivo ?? '', b.arquivo ?? '') || comparar(a.codigo, b.codigo) ||
+            comparar(a.referencia ?? '', b.referencia ?? '')),
+    };
+}

package/dist/docs.js

@@ -43,6 +43,7 @@ exports.comandosDaAjuda = comandosDaAjuda;
 exports.verificarDocs = verificarDocs;
 exports.renderizarRelance = renderizarRelance;
 exports.renderizarEstado = renderizarEstado;
+exports.docsPendentesDoMerge = docsPendentesDoMerge;
 exports.textoDaVerificacao = textoDaVerificacao;
 exports.escreverYaml = escreverYaml;
 exports.mergeDaThread = mergeDaThread;
@@ -78,6 +79,8 @@ const node_child_process_1 = require("node:child_process");
 const yaml_1 = require("./yaml");
 const thread_1 = require("./thread");
 const ledger_1 = require("./ledger");
+const branch_de_estado_1 = require("./branch-de-estado");
+const locale_1 = require("./locale");
 exports.DIR_PRODUTO = 'docs/produto';
 exports.DIR_ROADMAP = 'docs/roadmap';
 exports.DIR_PADROES = 'docs/padroes';
@@ -198,6 +201,9 @@ function git(raiz, args) {
 }
 /** Resolve a branch base: local, depois `origin/`, porque o CI faz checkout destacado. */
 function resolverBase(raiz, preferida = 'main') {
+    // RM-047 (fronteira de confiança): `preferida` vem do `worktree.base_branch` do clone.
+    if (!(0, branch_de_estado_1.branchValida)(preferida))
+        return null;
     for (const ref of [preferida, `origin/${preferida}`]) {
         if (git(raiz, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]).ok)
             return ref;
@@ -560,7 +566,8 @@ function verificarEstadoDoRoadmap(raiz, d, base, achados) {
         achados.push(erro(d.arquivo, d.id, 'docs.paridade.git', 'código Mesclado sem o commit do merge', 'preencha evidencias.codigo.commit (ork docs sincronizar faz isso a partir do ledger e do git)'));
     }
     if (commit && base) {
-        if (!git(raiz, ['cat-file', '-e', `${commit}^{commit}`]).ok) {
+        // RM-047: o commit vem do frontmatter do clone; só sha hexadecimal vai ao git.
+        if (!(0, branch_de_estado_1.shaValido)(commit) || !git(raiz, ['cat-file', '-e', `${commit}^{commit}`]).ok) {
             achados.push(erro(d.arquivo, d.id, 'docs.paridade.git', `o commit ${commit} não existe neste repositório`));
         }
         else if (codigo === 'Mesclado' && !git(raiz, ['merge-base', '--is-ancestor', commit, base]).ok) {
@@ -576,20 +583,58 @@ function verificarEstadoDoRoadmap(raiz, d, base, achados) {
  * mesmo `ship(<thread>)` do `sincronizarDocs`: tudo o que ela acusa o `sincronizar` corrige.
  */
 function verificarMergeDaThread(raiz, d, base, achados, pr = false) {
-    const sdlc = ehMapa(d.dados.sdlc) ? d.dados.sdlc : null;
-    const thread = sdlc && typeof sdlc.thread === 'string' ? sdlc.thread.trim() : '';
-    if (!thread)
-        return;
-    const merges = mergesDaThreadNoGit(raiz, thread, base);
-    if (merges.length === 0)
-        return;
-    const codigo = String((ehMapa(d.dados.estado) ? d.dados.estado.codigo : null) ?? '');
-    if (codigo === 'Mesclado')
+    const pendente = pendenciaDeMerge(raiz, d, base);
+    if (!pendente)
         return;
+    const { thread, merges, codigo } = pendente;
     achados.push((pr ? aviso : erro)(d.arquivo, d.id, 'docs.paridade.merge', `a thread ${thread} entrou na ${base} pelo merge ${merges[0].slice(0, 7)} (ship(${thread})), e o estado.codigo diz "${codigo || 'vazio'}"` +
         (pr ? ' (no PR, aviso: o push da main reprova)' : ''), `abra um PR de docs sobre a ${base} atualizada com ork docs sincronizar --escrever --so ${d.id} (o item e os índices); ` +
         `se o item tem outra fatia em curso, aponte sdlc.thread para a thread dela`));
 }
+/**
+ * A regra do `docs.paridade.merge`, isolada para o `ork ship registrar-pr` (RM-044, A3): a pagina cujo
+ * `sdlc.thread` ja tem merge `ship(<thread>)` na base e cujo `estado.codigo` ainda nao diz `Mesclado`.
+ * `thread`, quando dada, restringe a pagina a essa thread.
+ */
+function pendenciaDeMerge(raiz, d, base, thread) {
+    const sdlc = ehMapa(d.dados.sdlc) ? d.dados.sdlc : null;
+    const daPagina = sdlc && typeof sdlc.thread === 'string' ? sdlc.thread.trim() : '';
+    if (!daPagina || (thread !== undefined && daPagina !== thread))
+        return null;
+    const codigo = String((ehMapa(d.dados.estado) ? d.dados.estado.codigo : null) ?? '');
+    if (codigo === 'Mesclado')
+        return null;
+    const merges = mergesDaThreadNoGit(raiz, daPagina, base);
+    if (merges.length === 0)
+        return null;
+    return { thread: daPagina, merges, codigo };
+}
+/**
+ * RM-044 (A3): as paginas do roadmap, lidas da `ref` (a base remota depois do fetch, nao a copia local,
+ * que pode estar atras), que a regra `docs.paridade.merge` vai acusar por causa da `thread`. Nao grava
+ * nada: so lista. Ref ilegivel ou sem `docs/roadmap` devolve lista vazia.
+ */
+function docsPendentesDoMerge(raiz, thread, ref) {
+    const ls = git(raiz, ['ls-tree', '--name-only', `${ref}:${exports.DIR_ROADMAP}`]);
+    if (!ls.ok || !ls.saida)
+        return [];
+    const pendentes = [];
+    for (const nome of ls.saida.split('\n').filter(ehPaginaDeDocs).sort()) {
+        const arquivo = `${exports.DIR_ROADMAP}/${nome}`;
+        const blob = git(raiz, ['show', `${ref}:${arquivo}`]);
+        if (!blob.ok)
+            continue;
+        const lido = documentoDeTexto(arquivo, `${blob.saida}\n`);
+        if (!('doc' in lido) || lido.doc.tipo !== 'roadmap')
+            continue;
+        const p = pendenciaDeMerge(raiz, lido.doc, ref, thread);
+        if (!p)
+            continue;
+        pendentes.push({ id: lido.doc.id, arquivo, codigo: p.codigo, merge: p.merges[0],
+            comando: `ork docs sincronizar --escrever --so ${lido.doc.id}` });
+    }
+    return pendentes;
+}
 /** Os indices gerados (`docs/roadmap/README.md`, `docs/produto/README.md`) e o que o frontmatter diz. */
 const INDICES_GERADOS = [
     [`${exports.DIR_ROADMAP}/README.md`, (docs) => tabelaDoRoadmap(docs)],
@@ -716,7 +761,7 @@ function mergeDaThread(raiz, thread, base) {
     try {
         const eventos = (0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, thread));
         const ship = eventos.filter((e) => e.tipo === 'ship_done' && typeof e.mergeSha === 'string')
-            .find((e) => git(raiz, ['merge-base', '--is-ancestor', String(e.mergeSha), base]).ok);
+            .find((e) => (0, branch_de_estado_1.shaValido)(e.mergeSha) && (0, branch_de_estado_1.branchValida)(base) && git(raiz, ['merge-base', '--is-ancestor', e.mergeSha, base]).ok);
         if (ship)
             return { sha: String(ship.mergeSha).slice(0, 7), fonte: 'ledger ship_done' };
     }
@@ -734,6 +779,9 @@ function mergesDaThreadNoGit(raiz, thread, base) {
     // Sem `-n 1`: o git corta antes de inverter, e `--reverse -n 1` devolveria o mais recente.
     // GO-FIX 2 (achado 4 do CHECK): so a linha de primeiro pai da base e o assunto que COMECA com
     // `ship(<thread>)`, como no `mergeDaEntrega`. Commit que cita o merge no corpo, ou o Revert dele, nao e merge.
+    // RM-047 (fronteira de confiança): a base pode ser o `worktree.base_branch` cru do clone.
+    if (!(0, branch_de_estado_1.branchValida)(base))
+        return [];
     const log = git(raiz, ['log', base, '--first-parent', '--reverse', '--format=%H%x09%s', '--fixed-strings', `--grep=ship(${thread})`]);
     if (!log.ok)
         return [];
@@ -915,16 +963,21 @@ const ARQUIVOS_DO_PADRAO = [
     ['roadmap/README.md', `${exports.DIR_ROADMAP}/README.md`],
     ['markdownlint-cli2.jsonc', '.markdownlint-cli2.jsonc'],
 ];
-function dirDosModelos() {
-    for (const c of [path.join(__dirname, '..', 'assets', 'docs'), path.join(__dirname, '..', '..', 'assets', 'docs')]) {
+/**
+ * A pasta dos modelos do nucleo na lingua pedida. RM-061 (F3a, D3 e D6): o ingles mora em `assets/docs-en/`, com os
+ * mesmos nomes; o contrato que o `ork docs verificar` le (frontmatter, secoes, `Em uma frase`) e o mesmo nas duas.
+ */
+function dirDosModelos(locale = locale_1.LOCALE_PADRAO) {
+    const pasta = locale === 'en' ? 'docs-en' : 'docs';
+    for (const c of [path.join(__dirname, '..', 'assets', pasta), path.join(__dirname, '..', '..', 'assets', pasta)]) {
         if (fs.existsSync(c))
             return c;
     }
-    throw new Error('docs.modelos: assets/docs do nucleo nao encontrado');
+    throw new Error(`docs.modelos: assets/${pasta} do nucleo nao encontrado`);
 }
-/** Cria o que falta; nunca sobrescreve pagina existente. Devolve o que criou. */
-function iniciarDocs(raiz) {
-    const origem = dirDosModelos();
+/** Cria o que falta, no `locale` pedido (pt-BR por omissao); nunca sobrescreve pagina existente. Devolve o que criou. */
+function iniciarDocs(raiz, locale = locale_1.LOCALE_PADRAO) {
+    const origem = dirDosModelos(locale);
     const criados = [];
     for (const [de, para] of ARQUIVOS_DO_PADRAO) {
         const destino = path.join(raiz, para);