@orkastery/cli 0.5.0 → 0.5.3

package/dist/company-brain-context.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONTEXT_SCHEMA = void 0;
+exports.SERVER_CONTEXT_SCHEMA = exports.CONTEXT_SCHEMA = void 0;
 exports.buildContext = buildContext;
 const portfolio_1 = require("./portfolio");
 const company_brain_client_1 = require("./company-brain-client");
 const company_brain_contract_1 = require("./company-brain-contract");
 const company_brain_source_1 = require("./company-brain-source");
 exports.CONTEXT_SCHEMA = 'ork.brain-context/v1';
+exports.SERVER_CONTEXT_SCHEMA = 'orkmind.company-brain-context/v1';
+const SEM_MODO_CONTEXT = 'brain.selection.context-unsupported';
+const SERVIDOR_INVALIDO = 'brain.context.server-invalid';
 const ID = /^(prod|proj|init)-[a-z0-9][a-z0-9-]{2,47}$/;
 const ORDEM = { prod: 0, proj: 1, init: 2 };
 const LIMITE = 1000;
@@ -27,25 +30,122 @@ function citacaoDe(source) {
         return null;
     return { instance, source_ref, source_hash, source_version, location };
 }
+/** O servidor exige também `authority`: o pacote dele só traz item com a citação inteira; a consulta exige o mesmo. */
+const citadoPeloServidor = (source) => citacaoDe(source) !== null && typeof source.authority === 'string' && source.authority !== '';
 /**
- * Monta o pacote dos ids pedidos mais a cadeia de pais. A fonte canônica é o portfólio local;
- * o Brain é projeção, e a diferença entre os dois sai como frescor e lacuna, nunca é corrigida aqui.
+ * Confere um pacote `orkmind.company-brain-context/v1` contra o lote pedido: schema, tenant, pedido,
+ * digest recalculado, citação inteira, ordem, fecho de pais e destino de cada id pedido.
  */
-function buildContext(c, ids, transport, thread) {
-    const tenant = c.manifesto.memory.tenant;
-    const pedido = [...new Set(ids)].sort(comparar);
-    if (!pedido.length)
-        throw Error('brain.context.ids-required');
-    if (pedido.some(id => !ID.test(id)))
-        throw Error('brain.context.id-invalid');
-    if (pedido.length > LIMITE)
-        throw Error('brain.context.too-many');
-    const fonte = new Map((0, company_brain_source_1.portfolioEntities)((0, portfolio_1.readPortfolio)(c.raiz), { tenant, instance: c.manifesto.project.name, thread, aclRef: 'ork-factory' }).map(e => [e.id, e]));
-    const base = { schema: exports.CONTEXT_SCHEMA, tenant, contrato: company_brain_contract_1.CONTRACT_HASH, thread, pedido };
-    const encerrar = (r) => ({ ...base, state: r.state, ...(r.error ? { error: r.error } : {}), itens: [], lacunas: [], digest: null, consultadoEm: new Date().toISOString() });
+function conferirPacoteDoServidor(r, tenant, lote) {
+    const ctx = r.context;
+    if (!['ok', 'empty'].includes(r.state) || !ctx || typeof ctx !== 'object' || Array.isArray(ctx))
+        return false;
+    if (Object.keys(ctx).sort().join(',') !== 'digest,gaps,items,requested,schema,tenant_id')
+        return false;
+    const { digest: recebido, ...corpo } = ctx;
+    if (ctx.schema !== exports.SERVER_CONTEXT_SCHEMA || ctx.tenant_id !== tenant || (0, company_brain_contract_1.canonical)(ctx.requested) !== (0, company_brain_contract_1.canonical)(lote) ||
+        !Array.isArray(ctx.items) || !Array.isArray(ctx.gaps) || typeof recebido !== 'string' || (0, company_brain_contract_1.digest)(corpo) !== recebido)
+        return false;
+    if (r.state !== (ctx.items.length ? 'ok' : 'empty'))
+        return false;
+    const pedidos = new Set(lote), vistos = new Map(), codigos = new Map();
+    for (const g of ctx.gaps) {
+        if (!g || typeof g.id !== 'string' || typeof g.code !== 'string' || !ID.test(g.id))
+            return false;
+        if (!codigos.has(g.id))
+            codigos.set(g.id, new Set());
+        codigos.get(g.id).add(g.code);
+    }
+    for (const item of ctx.items) {
+        if (!item || typeof item.id !== 'string' || !ID.test(item.id) || vistos.has(item.id))
+            return false;
+        if (item.state === 'withheld') {
+            if (Object.keys(item).length !== 2)
+                return false;
+        }
+        else if (item.state !== 'ok' || !item.entity || typeof item.entity !== 'object' || item.entity.kind !== kindDe(item.id) ||
+            !Number.isInteger(item.entity.version) || !citadoPeloServidor(item.entity.source))
+            return false;
+        vistos.set(item.id, item);
+    }
+    const ordem = ctx.items.map((i) => i.id);
+    const ordenado = [...ordem].sort((a, b) => ORDEM[kindDe(a)] - ORDEM[kindDe(b)] || comparar(a, b));
+    if ((0, company_brain_contract_1.canonical)(ordem) !== (0, company_brain_contract_1.canonical)(ordenado))
+        return false;
+    // Fecho: todo item fora do pedido é pai, um kind acima, de um item citado do pacote.
+    const paisCitados = new Set();
+    for (const item of ctx.items)
+        if (item.state === 'ok') {
+            const parent = item.entity.parent_id;
+            if (typeof parent === 'string' && ID.test(parent) && ORDEM[kindDe(parent)] < ORDEM[kindDe(item.id)])
+                paisCitados.add(parent);
+        }
+    for (const id of vistos.keys())
+        if (!pedidos.has(id) && !paisCitados.has(id))
+            return false;
+    // Destino: todo id pedido sai como item ou como lacuna de desconhecido ou de citação incompleta.
+    for (const id of lote) {
+        const c = codigos.get(id);
+        if (!vistos.has(id) && !(c?.has('entity.unknown') || c?.has('citation.incomplete')))
+            return false;
+        if (vistos.has(id) && (c?.has('entity.unknown') || c?.has('citation.incomplete')))
+            return false;
+    }
+    return true;
+}
+/**
+ * B4.2: resolve o escopo pelo modo `context` do servidor. Devolve null quando o OrkMind não tem o modo
+ * (o chamador usa a consulta), ou a resposta que encerra o pacote.
+ */
+function resolverPeloServidor(transport, tenant, pedido, fonte, pai) {
+    const escopo = new Set(pedido), brain = new Map(), retidos = new Set(), semCitacao = new Set();
+    let primeiro = true;
+    for (let pendentes = pedido; pendentes.length;) {
+        const resolvidosNaVolta = [];
+        for (let inicio = 0; inicio < pendentes.length; inicio += LIMITE) {
+            const lote = pendentes.slice(inicio, inicio + LIMITE);
+            const r = transport({ schema: company_brain_client_1.BRAIN_API, operation: 'query', payload: (0, company_brain_contract_1.validateContract)({ schema: 'orkmind.company-brain-selection/v1',
+                    tenant_id: tenant, facets: { ids: lote, kinds: [], workspace_ids: [], source_instances: [] }, mode: 'context',
+                    limit: lote.length, offset: 0 }) });
+            if (r.state === 'unavailable' && r.error === SEM_MODO_CONTEXT)
+                return primeiro ? null : { state: 'conflict', error: SERVIDOR_INVALIDO };
+            primeiro = false;
+            if (falha(r.state))
+                return r;
+            if (!conferirPacoteDoServidor(r, tenant, lote))
+                return { state: 'conflict', error: SERVIDOR_INVALIDO };
+            const ctx = r.context;
+            for (const g of ctx.gaps)
+                if (g.code === 'citation.incomplete')
+                    semCitacao.add(g.id);
+            for (const item of ctx.items) {
+                // Pai que outro lote ou volta já resolveu vale uma vez só: a primeira resposta fica.
+                if (escopo.has(item.id) && !lote.includes(item.id))
+                    continue;
+                escopo.add(item.id);
+                resolvidosNaVolta.push(item.id);
+                if (item.state === 'withheld')
+                    retidos.add(item.id);
+                else
+                    brain.set(item.id, { ...item.entity, id: item.id });
+            }
+            resolvidosNaVolta.push(...lote);
+        }
+        // O servidor fecha os pais que o Brain conhece; os que só a fonte local conhece vão na próxima volta.
+        const novos = new Set();
+        for (const id of resolvidosNaVolta)
+            if (!retidos.has(id))
+                for (const parent of [pai(id, fonte.get(id)?.parent_id), pai(id, brain.get(id)?.parent_id)])
+                    if (parent && !escopo.has(parent))
+                        novos.add(parent);
+        novos.forEach(id => escopo.add(id));
+        pendentes = [...novos].sort(comparar);
+    }
+    return { brain, retidos, semCitacao, escopo };
+}
+/** B4.1: o caminho anterior ao modo `context`, por `query` e `get`, para um OrkMind sem o modo. */
+function resolverPelaConsulta(transport, tenant, pedido, fonte, pai) {
     const escopo = new Set(pedido), brain = new Map(), retidos = new Set();
-    // O pai só entra por um filho visível e tem kind acima dele: init, proj e prod fecham em três voltas.
-    const pai = (id, parent) => typeof parent === 'string' && ID.test(parent) && ORDEM[kindDe(parent)] < ORDEM[kindDe(id)] ? parent : null;
     let gets = 0;
     for (let pendentes = pedido; pendentes.length;) {
         for (let inicio = 0; inicio < pendentes.length; inicio += LIMITE) {
@@ -54,7 +154,7 @@ function buildContext(c, ids, transport, thread) {
                     tenant_id: tenant, facets: { ids: lote, kinds: [], workspace_ids: [], source_instances: [] }, mode: 'selection',
                     limit: lote.length, offset: 0 }) });
             if (falha(r.state))
-                return encerrar(r);
+                return r;
             const itens = Array.isArray(r.items) ? r.items : [];
             for (const item of itens)
                 if (item?.state === 'ok' && doLote.has(item.entity?.id))
@@ -67,10 +167,10 @@ function buildContext(c, ids, transport, thread) {
             else if (retidosNoLote)
                 for (const id of faltantes) {
                     if (++gets > LIMITE_DE_GET)
-                        return encerrar({ state: 'unavailable', error: 'brain.context.get-limit' });
+                        return { state: 'unavailable', error: 'brain.context.get-limit' };
                     const g = transport({ schema: company_brain_client_1.BRAIN_API, operation: 'get', payload: { tenant_id: tenant, id } });
                     if (falha(g.state))
-                        return encerrar(g);
+                        return g;
                     if (g.state === 'withheld')
                         retidos.add(id);
                     else if (g.state === 'ok' && g.entity?.id === id)
@@ -87,6 +187,35 @@ function buildContext(c, ids, transport, thread) {
                     }
         pendentes = novos.sort(comparar);
     }
+    return { brain, retidos, semCitacao: new Set(), escopo };
+}
+/**
+ * Monta o pacote dos ids pedidos mais a cadeia de pais. A fonte canônica é o portfólio local;
+ * o Brain é projeção, e a diferença entre os dois sai como frescor e lacuna, nunca é corrigida aqui.
+ */
+function buildContext(c, ids, transport, thread) {
+    const tenant = c.manifesto.memory.tenant;
+    const pedido = [...new Set(ids)].sort(comparar);
+    if (!pedido.length)
+        throw Error('brain.context.ids-required');
+    if (pedido.some(id => !ID.test(id)))
+        throw Error('brain.context.id-invalid');
+    if (pedido.length > LIMITE)
+        throw Error('brain.context.too-many');
+    const fonte = new Map((0, company_brain_source_1.portfolioEntities)((0, portfolio_1.readPortfolio)(c.raiz), { tenant, instance: c.manifesto.project.name, thread, aclRef: 'ork-factory' }).map(e => [e.id, e]));
+    const base = { schema: exports.CONTEXT_SCHEMA, tenant, contrato: company_brain_contract_1.CONTRACT_HASH, thread, pedido };
+    // O pai só entra por um filho visível e tem kind acima dele: init, proj e prod fecham em três voltas.
+    const pai = (id, parent) => typeof parent === 'string' && ID.test(parent) && ORDEM[kindDe(parent)] < ORDEM[kindDe(id)] ? parent : null;
+    const doServidor = resolverPeloServidor(transport, tenant, pedido, fonte, pai);
+    const caminho = doServidor === null ? 'consulta' : 'servidor';
+    const encerrar = (r) => ({ ...base, state: r.state, ...(r.error ? { error: r.error } : {}), itens: [], lacunas: [],
+        digest: null, consultadoEm: new Date().toISOString(), caminho });
+    if (doServidor && 'state' in doServidor)
+        return encerrar(doServidor);
+    const resolvido = doServidor ?? resolverPelaConsulta(transport, tenant, pedido, fonte, pai);
+    if ('state' in resolvido)
+        return encerrar(resolvido);
+    const { escopo, brain, retidos, semCitacao } = resolvido;
     const itens = [], lacunas = [];
     const lacuna = (id, codigo) => lacunas.push({ id, codigo });
     for (const id of escopo) {
@@ -95,12 +224,19 @@ function buildContext(c, ids, transport, thread) {
             lacuna(id, 'brain.retido');
             continue;
         }
+        // Sem citação no Brain vale como no caminho da consulta: o Brain tem a entidade, mas ela não é citável.
+        if (semCitacao.has(id)) {
+            lacuna(id, 'citacao.incompleta');
+            continue;
+        }
         const b = brain.get(id), f = fonte.get(id);
         if (!b && !f) {
             lacuna(id, 'entidade.desconhecida');
             continue;
         }
-        const entidade = b ?? f, citacao = citacaoDe(entidade.source);
+        // Suspeitas da revisao de 03/10: a citacao exige `authority` nos dois caminhos, como o servidor (o
+        // schema do Source a exige); sem isso, um Brain fora do contrato dava pacote e digest diferentes por caminho.
+        const entidade = b ?? f, citacao = citadoPeloServidor(entidade.source) ? citacaoDe(entidade.source) : null;
         if (!citacao) {
             lacuna(id, 'citacao.incompleta');
             continue;
@@ -128,5 +264,5 @@ function buildContext(c, ids, transport, thread) {
     lacunas.sort((a, b) => comparar(a.id, b.id) || comparar(a.codigo, b.codigo));
     // O digest cobre o que foi dito e de onde veio; o horário da consulta fica fora para o pacote ser reproduzível.
     const corpo = { ...base, state: (itens.length ? 'ok' : 'empty'), itens, lacunas };
-    return { ...corpo, digest: (0, company_brain_contract_1.digest)(corpo), consultadoEm: new Date().toISOString() };
+    return { ...corpo, digest: (0, company_brain_contract_1.digest)(corpo), consultadoEm: new Date().toISOString(), caminho };
 }

package/dist/docs.js

@@ -43,9 +43,11 @@ exports.comandosDaAjuda = comandosDaAjuda;
 exports.verificarDocs = verificarDocs;
 exports.renderizarRelance = renderizarRelance;
 exports.renderizarEstado = renderizarEstado;
+exports.docsPendentesDoMerge = docsPendentesDoMerge;
 exports.textoDaVerificacao = textoDaVerificacao;
 exports.escreverYaml = escreverYaml;
 exports.mergeDaThread = mergeDaThread;
+exports.mergesDaThreadNoGit = mergesDaThreadNoGit;
 exports.escopoPadraoDoSync = escopoPadraoDoSync;
 exports.sincronizarDocs = sincronizarDocs;
 exports.tabelaDoRoadmap = tabelaDoRoadmap;
@@ -262,9 +264,12 @@ function verificarDocs(raiz, opcoes = {}) {
         verificarFontes(raiz, d, comandos, achados);
         if (d.tipo === 'roadmap') {
             verificarEstadoDoRoadmap(raiz, d, base, achados);
+            if (base)
+                verificarMergeDaThread(raiz, d, base, achados, opcoes.pr === true);
             verificarTabelasDeEstado(d, achados);
         }
     }
+    verificarIndices(raiz, docs, achados, opcoes.pr === true);
     return { docs, achados };
 }
 function verificarChaves(d, achados) {
@@ -564,6 +569,95 @@ function verificarEstadoDoRoadmap(raiz, d, base, achados) {
         }
     }
 }
+/**
+ * RM-037 (fatia 3, defeito 1): o outro sentido da paridade com o git. Depois do merge do PR, o
+ * frontmatter da RM-049 (#26) e da RM-051 (#33) seguiu em "Branch criada", e o verificador dizia OK:
+ * ele so conferia que `Mesclado` tem o commit na base. O merge desta fabrica e pelo GitHub, sem o
+ * `ork ship` no caminho, entao a prova mora aqui, no job que o CI obrigatorio roda. A regra usa o
+ * mesmo `ship(<thread>)` do `sincronizarDocs`: tudo o que ela acusa o `sincronizar` corrige.
+ */
+function verificarMergeDaThread(raiz, d, base, achados, pr = false) {
+    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)],
+    [`${exports.DIR_PRODUTO}/README.md`, (docs) => tabelaDoProduto(docs)],
+];
+/**
+ * RM-037 (fatia 3, defeito 1): o indice e uma vista do frontmatter, como as tabelas do corpo, e mentia
+ * do mesmo jeito: sem a RM-051 e com a RM-031 de antes. Divergente reprova; vazio (o modelo recem-copiado
+ * pelo `ork docs init`) so avisa; sem os marcadores, nao ha indice gerado para conferir.
+ */
+function verificarIndices(raiz, docs, achados, pr = false) {
+    for (const [arquivo, gerar] of INDICES_GERADOS) {
+        const abs = path.join(raiz, arquivo);
+        if (!fs.existsSync(abs))
+            continue;
+        // Checkout com CRLF (Windows com core.autocrlf) nao e divergencia: as paginas tambem normalizam.
+        const atual = blocoEntre(fs.readFileSync(abs, 'utf8').replace(/\r\n/g, '\n'), INICIO, FIM);
+        if (atual === null)
+            continue;
+        if (atual === '') {
+            if (docs.length > 0) {
+                achados.push(aviso(arquivo, undefined, 'docs.paridade.indice', 'o índice ainda não foi gerado', 'rode ork docs sincronizar --escrever'));
+            }
+        }
+        else if (atual !== gerar(docs)) {
+            achados.push((pr ? aviso : erro)(arquivo, undefined, 'docs.paridade.indice', `o índice diverge do frontmatter das páginas${pr ? ' (no PR, aviso: o push da main reprova)' : ''}`, 'o índice é gerado do frontmatter: rode ork docs sincronizar --escrever e commite o índice'));
+        }
+    }
+}
 // --------------------------------------------------------------------------------------------
 // Saida para humano (TDAH) e para agente
 function textoDaVerificacao(docs, achados) {
@@ -666,13 +760,26 @@ function mergeDaThread(raiz, thread, base) {
             return { sha: String(ship.mergeSha).slice(0, 7), fonte: 'ledger ship_done' };
     }
     catch { /* thread sem estado nesta maquina: cai para o git */ }
-    // Sem `-n 1`: o git corta antes de inverter, e `--reverse -n 1` devolveria o mais recente.
-    const log = git(raiz, ['log', base, '--reverse', '--format=%H', '--fixed-strings', `--grep=ship(${thread})`]);
-    const primeiro = log.ok ? log.saida.split('\n')[0] : '';
+    const primeiro = mergesDaThreadNoGit(raiz, thread, base)[0];
     if (primeiro)
         return { sha: primeiro.slice(0, 7), fonte: `git log ${base}` };
     return null;
 }
+/**
+ * Os commits `ship(<thread>)` da base, do mais velho ao mais novo, so pelo git (o CI nao tem ledger).
+ * RM-037 (fatia 3): um lugar so para o `sincronizarDocs` e o `verificarDocs` acharem o mesmo merge.
+ */
+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.
+    const log = git(raiz, ['log', base, '--first-parent', '--reverse', '--format=%H%x09%s', '--fixed-strings', `--grep=ship(${thread})`]);
+    if (!log.ok)
+        return [];
+    return log.saida.split('\n').map((l) => l.split('\t'))
+        .filter(([sha, assunto]) => !!sha && typeof assunto === 'string' && assunto.startsWith(`ship(${thread})`))
+        .map(([sha]) => sha);
+}
 function temBranch(raiz, thread) {
     const r = git(raiz, ['for-each-ref', '--format=%(refname:short)', `refs/heads/ork/${thread}-*`, `refs/remotes/origin/ork/${thread}-*`]);
     return r.ok && r.saida.length > 0;

package/dist/doctor-pulse-cron.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * RM-039 (B6): o `ork doctor` acusa o pulse que bate devagar demais.
+ *
+ * A cadencia por tag (#OrkPulseOn-15m e as outras) so vale inteira com a varredura do cron de 15
+ * em 15 minutos. A instalacao antiga fica em `0 * * * *`, e nada avisava. Com o transporte do
+ * pulse configurado (`.orkastery/monitor/pulse-host.json`), o doctor le o `crontab -l` e avisa,
+ * sem bloquear, quando a linha da varredura falta ou bate mais devagar que o template
+ * `monitor/pulse.cron`. O doctor nunca edita o crontab: a correcao traz a linha pronta.
+ */
+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.COMANDO_DO_TEMPLATE = exports.SCRIPT_DA_VARREDURA = exports.BATIDA_DO_TEMPLATE = void 0;
+exports.lerCrontabDoSistema = lerCrontabDoSistema;
+exports.intervaloEmMinutos = intervaloEmMinutos;
+exports.linhasDaVarredura = linhasDaVarredura;
+exports.scriptDaVarreduraDoOrk = scriptDaVarreduraDoOrk;
+exports.comandoDaVarredura = comandoDaVarredura;
+exports.checarCronDoPulse = checarCronDoPulse;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const util_1 = require("./util");
+/** A batida do template `monitor/pulse.cron` (I-50): a menor cadencia das tags. */
+exports.BATIDA_DO_TEMPLATE = '*/15 * * * *';
+/** O script que o template agenda; a linha do crontab e achada por ele. */
+exports.SCRIPT_DA_VARREDURA = 'varredura-pulse.sh';
+/** Comando do template antes da troca do caminho pelo checkout de quem instala. */
+exports.COMANDO_DO_TEMPLATE = '/CAMINHO/orkastery/monitor/varredura-pulse.sh';
+/** Le o crontab do usuario do processo, sem shell e com prazo. */
+function lerCrontabDoSistema() {
+    const r = (0, util_1.exec)('crontab', ['-l'], undefined, 5000);
+    if (r.ok)
+        return { ok: true, texto: r.stdout };
+    if (r.error === 'ENOENT')
+        return { ok: false, motivo: 'comando crontab ausente nesta maquina' };
+    const msg = (r.stderr || r.stdout).trim().split('\n')[0] ?? '';
+    return { ok: false, motivo: msg ? `crontab -l falhou: ${msg}` : `crontab -l saiu ${r.code}` };
+}
+const MACROS = { '@hourly': 60, '@daily': 1440, '@midnight': 1440, '@weekly': 10080,
+    '@monthly': 43200, '@yearly': 525600, '@annually': 525600 };
+/**
+ * Maior intervalo, em minutos, entre duas batidas da linha (so os campos de minuto e hora; dia,
+ * mes e dia da semana restritos contam como mais devagar que uma hora). `null` quando a expressao
+ * nao e reconhecida: o doctor entao avisa pela linha, sem adivinhar.
+ */
+function intervaloEmMinutos(expressao) {
+    const campos = expressao.trim().split(/\s+/);
+    if (campos.length === 1 && campos[0].startsWith('@'))
+        return MACROS[campos[0]] ?? null;
+    if (campos.length !== 5)
+        return null;
+    const [minuto, hora, dia, mes, semana] = campos;
+    const minutos = valoresDoCampo(minuto, 0, 59);
+    if (!minutos)
+        return null;
+    if (hora !== '*' || dia !== '*' || mes !== '*' || semana !== '*')
+        return Math.max(60, maiorLacuna(minutos, 60));
+    return maiorLacuna(minutos, 60);
+}
+function valoresDoCampo(campo, min, max) {
+    const valores = new Set();
+    for (const parte of campo.split(',')) {
+        const m = /^(\*|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/.exec(parte);
+        if (!m)
+            return null;
+        const inicio = m[1] === '*' ? min : Number(m[2]);
+        const fim = m[1] === '*' ? max : m[3] !== undefined ? Number(m[3]) : m[4] !== undefined ? max : inicio;
+        const passo = m[4] !== undefined ? Number(m[4]) : 1;
+        if (passo < 1 || inicio < min || fim > max || inicio > fim)
+            return null;
+        for (let v = inicio; v <= fim; v += passo)
+            valores.add(v);
+    }
+    return [...valores].sort((a, b) => a - b);
+}
+/** Maior distancia entre dois valores consecutivos, contando a volta do ciclo. */
+function maiorLacuna(valores, ciclo) {
+    let maior = 0;
+    for (let i = 0; i < valores.length; i++) {
+        const proximo = i + 1 < valores.length ? valores[i + 1] : valores[0] + ciclo;
+        maior = Math.max(maior, proximo - valores[i]);
+    }
+    return maior;
+}
+/** Separa a expressao de horario do comando numa linha do crontab. */
+function dividirLinha(linha) {
+    const t = linha.trim();
+    if (t.startsWith('@')) {
+        const m = /^(@\S+)\s+(.+)$/.exec(t);
+        return m ? { quando: m[1], comando: m[2] } : null;
+    }
+    const m = /^(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(.+)$/.exec(t);
+    return m ? { quando: m[1], comando: m[2] } : null;
+}
+/** Linhas ativas (nao comentario, nao variavel) que agendam a varredura do pulse. */
+function linhasDaVarredura(crontab) {
+    return crontab.split('\n').map(l => l.trim())
+        .filter(l => l && !l.startsWith('#') && !/^[A-Za-z_][A-Za-z0-9_]*\s*=/.test(l) && l.includes(exports.SCRIPT_DA_VARREDURA));
+}
+/** Aspas de shell so quando o caminho precisa (a linha vai colada no crontab, que roda por `sh`). */
+function citar(caminho) {
+    return /^[A-Za-z0-9_./:@+-]+$/.test(caminho) ? caminho : `'${caminho.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * O script da varredura que este `ork` traz: no pacote do npm, `monitor/` fica ao lado de `dist/`; no
+ * checkout, na raiz do repositorio, dois niveis acima de `core/dist/`. `null` quando nenhum existe.
+ */
+function scriptDaVarreduraDoOrk(dirDoDist = __dirname) {
+    for (const dir of [path.join(dirDoDist, '..', 'monitor'), path.join(dirDoDist, '..', '..', 'monitor')]) {
+        const script = path.join(dir, exports.SCRIPT_DA_VARREDURA);
+        if (fs.existsSync(script))
+            return path.resolve(script);
+    }
+    return null;
+}
+/**
+ * O comando que a linha nova do crontab roda. Ensaio de 03/10/2026 (RM-049): a correcao apontava
+ * `<projeto>/monitor/varredura-pulse.sh`, que so existe no checkout do proprio Orkastery; quem instalou
+ * pelo npm recebia um caminho que nao existe. Quando o projeto nao traz o script, a linha usa o do `ork`
+ * instalado e diz o projeto por `ORK_PULSE_PROJECT` (o cron nao roda no diretorio do projeto).
+ */
+function comandoDaVarredura(raizDoProjeto, scriptDoOrk = scriptDaVarreduraDoOrk()) {
+    const doProjeto = path.join(raizDoProjeto, 'monitor', exports.SCRIPT_DA_VARREDURA);
+    if (fs.existsSync(doProjeto) || !scriptDoOrk)
+        return citar(doProjeto);
+    return `ORK_PULSE_PROJECT=${citar(raizDoProjeto)} ${citar(scriptDoOrk)}`;
+}
+/**
+ * Check "cadencia do pulse no cron". `null` quando o projeto nao tem transporte do pulse: sem
+ * `pulse-host.json` nao ha resumo para entregar, e o doctor nao fala de cron.
+ */
+function checarCronDoPulse(dirMonitor, raizDoCheckout, ler = lerCrontabDoSistema, scriptDoOrk = scriptDaVarreduraDoOrk()) {
+    if (!fs.existsSync(path.join(dirMonitor, 'pulse-host.json')))
+        return null;
+    const nome = 'cadencia do pulse no cron';
+    const comandoSugerido = comandoDaVarredura(raizDoCheckout, scriptDoOrk);
+    const linhaNova = (comando) => `${exports.BATIDA_DO_TEMPLATE} ${comando}`;
+    const ausente = (detalhe) => ({ nome, nivel: 'warn', detalhe,
+        correcao: `adicione ao crontab (crontab -e), como no template monitor/pulse.cron: ${linhaNova(comandoSugerido)}` });
+    const leitura = ler();
+    if (!leitura.ok)
+        return ausente(`pulse-host.json presente, mas sem crontab para ler (${leitura.motivo}): a varredura nao bate`);
+    const linhas = linhasDaVarredura(leitura.texto);
+    if (linhas.length === 0)
+        return ausente(`pulse-host.json presente, e nenhuma linha do crontab roda ${exports.SCRIPT_DA_VARREDURA}: o resumo nao sai`);
+    const lentas = [];
+    for (const linha of linhas) {
+        const partes = dividirLinha(linha);
+        const intervalo = partes ? intervaloEmMinutos(partes.quando) : null;
+        if (intervalo === null || intervalo > 15)
+            lentas.push({ linha, comando: partes?.comando ?? comandoSugerido, intervalo });
+    }
+    if (lentas.length < linhas.length) {
+        return { nome, nivel: 'ok', detalhe: `varredura no cron a cada 15 minutos ou menos (${linhas.length} linha(s))` };
+    }
+    const l = lentas[0];
+    const ritmo = l.intervalo === null ? 'com horario que o doctor nao le' : l.intervalo === 60 ? 'de hora em hora'
+        : `a cada ${l.intervalo} minutos`;
+    return { nome, nivel: 'warn',
+        detalhe: `a varredura do pulse bate ${ritmo} (\`${l.linha}\`): a cadencia por tag (RM-039) pede 15 minutos`,
+        correcao: `troque a linha no crontab (crontab -e) por: ${linhaNova(l.comando)}` };
+}