brito-cli 0.7.5 → 0.9.0

package/dist/provider/index.js

@@ -1,10 +1,12 @@
 import { AnthropicProvider } from "./anthropic.js";
+import { LocalSlmProvider } from "./local.js";
 import { OpenAICompatProvider } from "./openai-compat.js";
 import { resolveModel } from "./resolve.js";
 let factory = null;
 /** Só para testes: troca a criação de provedores. `null` volta ao normal. */
 export function setProviderFactory(f) { factory = f; }
 let anthropic;
+let local;
 const openai = new Map();
 /**
  * Provedor de um modelo pelo nome que o usuário usa. O cliente da Anthropic só nasce quando um modelo Claude é usado:
@@ -16,6 +18,8 @@ export function providerFor(name) {
         return factory(r);
     if (r.kind === "anthropic")
         return (anthropic ??= new AnthropicProvider());
+    if (r.local)
+        return (local ??= new LocalSlmProvider());
     // O config pode mudar na sessão: refaz o provedor quando o perfil muda.
     const key = JSON.stringify(r.profile);
     const hit = openai.get(r.name);

package/dist/provider/local.js

@@ -0,0 +1,88 @@
+import { slmChat, slmChatCtx } from "../local/slm.js";
+const textOf = (c) => typeof c === "string" ? c : c.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("\n");
+const resultText = (c) => typeof c === "string" ? c : (c ?? []).flatMap((b) => (b.type === "text" ? [b.text] : [])).join("\n");
+/**
+ * Histórico interno (formato da Anthropic) → histórico do LlamaChat. Cada `tool_use` vira uma `functionCall` com o
+ * `result` do `tool_result` correspondente; chamada sem resultado fica com resultado vazio. Imagens são descartadas.
+ */
+export function toChatHistory(system, messages) {
+    const out = [{ type: "system", text: system }];
+    const pending = new Map();
+    for (const m of messages) {
+        if (m.role === "assistant") {
+            const response = [];
+            if (typeof m.content === "string")
+                response.push(m.content);
+            else
+                for (const b of m.content) {
+                    if (b.type === "text" && b.text)
+                        response.push(b.text);
+                    else if (b.type === "tool_use") {
+                        const call = { type: "functionCall", name: b.name, params: b.input ?? {}, result: "" };
+                        pending.set(b.id, call);
+                        response.push(call);
+                    }
+                }
+            if (response.length)
+                out.push({ type: "model", response });
+            continue;
+        }
+        if (typeof m.content === "string") {
+            out.push({ type: "user", text: m.content });
+            continue;
+        }
+        const text = [];
+        for (const b of m.content) {
+            if (b.type === "tool_result") {
+                const call = pending.get(b.tool_use_id);
+                if (call)
+                    call.result = (b.is_error ? "ERRO: " : "") + resultText(b.content);
+            }
+            else if (b.type === "text")
+                text.push(b.text);
+        }
+        if (text.length)
+            out.push({ type: "user", text: text.join("\n") });
+    }
+    return out;
+}
+/** Só as palavras-chave de JSON Schema que a gramática do llama.cpp entende; o resto é descartado. */
+export function toGbnfSchema(s) {
+    if (!s || typeof s !== "object")
+        return { type: "string" };
+    if (Array.isArray(s.enum))
+        return { enum: s.enum };
+    const t = Array.isArray(s.type) ? s.type.find((x) => x !== "null") : s.type;
+    if (t === "object" || s.properties) {
+        const props = Object.fromEntries(Object.entries(s.properties ?? {}).map(([k, v]) => [k, toGbnfSchema(v)]));
+        return { type: "object", properties: props, ...(Array.isArray(s.required) && s.required.length ? { required: s.required.filter((k) => k in props) } : {}) };
+    }
+    if (t === "array")
+        return { type: "array", items: toGbnfSchema(s.items) };
+    if (t === "string" || t === "number" || t === "integer" || t === "boolean")
+        return { type: t };
+    return { type: "string" };
+}
+export const toChatFunctions = (tools = []) => Object.fromEntries(tools.map((t) => [t.name, { description: t.description, params: toGbnfSchema(t.input_schema) }]));
+const approxTokens = (s) => Math.ceil(s.length / 4);
+/** SLM embutido como modelo do loop do Brito (fallback do Claude): mesma interface dos outros provedores. */
+export class LocalSlmProvider {
+    kind = "openai";
+    async send(req, hooks = {}) {
+        const history = toChatHistory(req.system, req.messages);
+        const r = await slmChat({
+            history, functions: toChatFunctions(req.tools),
+            maxTokens: Math.min(req.maxTokens, Math.floor(slmChatCtx() / 2)), signal: hooks.signal, onText: hooks.onText,
+        });
+        const content = [];
+        if (r.text.trim())
+            content.push({ type: "text", text: r.text });
+        r.calls.forEach((c, i) => content.push({ type: "tool_use", id: `slm_${Date.now().toString(36)}_${i}`, name: c.name, input: c.input }));
+        const input = approxTokens(JSON.stringify(history));
+        return {
+            content,
+            stopReason: r.calls.length ? "tool_use" : r.truncated ? "max_tokens" : "end_turn",
+            usage: { input, output: approxTokens(r.text + JSON.stringify(r.calls)), cacheRead: 0 },
+        };
+    }
+}

package/dist/provider/resolve.js

@@ -1,4 +1,10 @@
 import { MODEL_ALIASES, loadProfiles } from "../model.js";
+/** Nome do SLM local como modelo (fallback do Claude e `/model slm`). Um perfil `slm` no config tem precedência. */
+export const SLM_MODEL = "slm";
+const SLM_PROFILE = {
+    name: SLM_MODEL, type: "openai", label: "SLM local", baseURL: "local:", model: SLM_MODEL, apiKeyEnv: "",
+    contextWindow: 16_384, vision: false, thinkingToggle: false,
+};
 /** Janela dos modelos Claude quando nada informa outra. */
 const CLAUDE_WINDOW = 200_000;
 const COMPACT_DEFAULT = 120_000;
@@ -6,6 +12,8 @@ const COMPACT_DEFAULT = 120_000;
 export function resolveModel(name) {
     const key = name.trim().toLowerCase();
     const profile = loadProfiles().profiles[key];
+    if (!profile && key === SLM_MODEL)
+        return { kind: "openai", name: SLM_MODEL, wireModel: SLM_MODEL, label: SLM_PROFILE.label, contextWindow: SLM_PROFILE.contextWindow, profile: SLM_PROFILE, local: true };
     if (profile)
         return { kind: "openai", name: key, wireModel: profile.model, label: profile.label, contextWindow: profile.contextWindow, profile };
     const wire = MODEL_ALIASES[key] ?? name.trim();

package/dist/repl.js

@@ -7,6 +7,7 @@ import { Dock } from "./ui/dock.js";
 import os from "node:os";
 import { ui, c, fmtTokens } from "./ui/ui.js";
 import { cols } from "./ui/theme.js";
+import { engineChip } from "./provider/fallback.js";
 /** Nome do usuário da máquina (fallback para variáveis de ambiente). */
 const userName = () => {
     try {
@@ -16,9 +17,10 @@ const userName = () => {
         return process.env.USER ?? process.env.USERNAME ?? "você";
     }
 };
-import { listPending, listSkills, deleteSkill, promoteSkill, globalHome } from "./skills/store.js";
+import { listPending, listSkills, listBuiltins, getSkill, suggestSkills, deleteSkill, promoteSkill, globalHome } from "./skills/store.js";
 import { listAgents } from "./agent/agents.js";
 import { perms, cycleMode, MODE_LABEL } from "./permissions.js";
+import { orch } from "./orchestrator.js";
 /**
  * Backend com o motor substituível no meio da sessão (claude CLI → qwen): o REPL monta o menu uma vez, então os
  * comandos ficam estáveis e o que o motor atual não tem responde "indisponível". `usage`/`cost` somam todos os
@@ -56,6 +58,7 @@ export function switchableBackend(initial) {
             const all = [...seen].map((b) => b.cost?.()).filter((x) => x !== undefined);
             return all.length ? all.reduce((s, x) => s + x, 0) : undefined;
         },
+        fallback: () => cur.fallback?.() ?? [...seen].map((b) => b.fallback?.()).find((s) => s?.active),
         turn: (text, signal) => cur.turn(text, signal),
         abort: () => cur.abort?.(),
         // Todos os motores: o claude CLI fora de uso guarda a sessão (--resume) e os turnos que o fallback herdaria.
@@ -73,24 +76,32 @@ const COMMON = {
     "/help": "esta ajuda",
     "/agents": "subagentes disponíveis",
     "/indicadores": "explica os números da barra de status",
-    "/skills": "lista; pending | approve <nome> | reject <nome> | consolidate | rm <nome> | promote <nome>",
+    "/skills": "lista; suggest <tarefa> | pending | approve <nome> | reject <nome> | consolidate | rm <nome> | promote <nome>",
     "/modo": "mostra ou troca o modo (manual, auto, plano) — ou Shift+Tab",
-    "/clear": "limpa a conversa",
+    "/clear": "começa outra conversa (a anterior fica salva)",
     "/sair": "encerra (ou Ctrl+C duas vezes)",
 };
 export async function runRepl(b, o) {
     const interactive = !!process.stdin.isTTY && !!process.stdout.isTTY;
     let skillCount = listSkills(o.root).length;
     const refreshSkills = () => { skillCount = listSkills(o.root).length; };
+    // Skills de invocação manual (embutidas ou do usuário) viram /nome, com Tab.
+    const skillCmds = [...listBuiltins(o.root), ...listSkills(o.root).filter((s) => s.invoke === "manual")]
+        .map((s) => ({ name: `/${s.name}`, desc: `skill: ${s.description}` }));
     const menu = [
+        ...skillCmds,
         ...Object.entries(b.commands).map(([name, v]) => ({ name, desc: v.desc })),
         ...Object.entries(COMMON).map(([name, desc]) => ({ name, desc })),
     ].sort((x, y) => x.name.localeCompare(y.name));
     const modeColor = { manual: c.muted, auto: c.ok, plan: c.warn, bypass: c.err };
-    const modeChip = () => { const m = MODE_LABEL[perms.mode]; return modeColor[perms.mode](`${m.icon} ${m.name}`); };
+    const modeChip = () => {
+        const m = MODE_LABEL[perms.mode];
+        return modeColor[perms.mode](`${m.icon} ${m.name}`) + (orch.on ? c.ok(` ⚙ →${orch.model}`) : "");
+    };
     const status = () => ui.statusLine({
         project: path.basename(o.root),
         mode: modeChip(),
+        engine: engineChip(b.model(), b.fallback?.()),
         model: b.model(), ctxTokens: b.contextTokens(), ctxWindow: b.ctxWindow,
         input: b.usage().input, output: b.usage().output, cacheRead: b.usage().cacheRead, startedAt: o.startedAt, cost: b.cost?.(),
         extra: `${skillCount} ${skillCount === 1 ? "skill" : "skills"}`,
@@ -175,9 +186,21 @@ export async function runRepl(b, o) {
         // Este tratador vale antes de `b.commands` (ver `run` mais abaixo): ele cuida de `promote` e `rm` e DELEGA o resto
         // (listar, pending, approve, reject, consolidate) ao /skills do backend. Sem a delegação, esse /skills completo
         // ficava escondido e a revisão de propostas pendentes era inalcançável no REPL.
-        "/skills": async ([sub, name]) => {
+        "/skills": async ([sub, name, ...rest]) => {
+            const args = [name, ...rest].filter((x) => !!x);
             const full = b.commands["/skills"];
-            if (sub === "promote" && name) {
+            if (sub === "suggest") {
+                const q = args.join(" ");
+                const found = q ? suggestSkills(o.root, q) : [];
+                if (!q)
+                    ui.warn("uso: /skills suggest <descrição da tarefa>");
+                else if (!found.length)
+                    ui.print(c.dim("  (nenhuma skill parecida)"));
+                else
+                    for (const { skill: s, score } of found)
+                        ui.print(`  ${c.soft(s.invoke === "manual" ? "/" + s.name : s.name)} ${c.muted(`(${score.toFixed(1)}) ${s.description}`)}`);
+            }
+            else if (sub === "promote" && name) {
                 try {
                     promoteSkill(o.root, name);
                     ui.print(c.ok(`promovida para global: ${name}`));
@@ -243,6 +266,26 @@ export async function runRepl(b, o) {
             await run(args);
             return;
         }
+        // /nome de uma skill: o usuário a invoca de propósito (inclusive as manuais). Argumentos viram o contexto.
+        const sk = line.startsWith("/") && !cmd.slice(1).includes("/") ? getSkill(o.root, key.slice(1)) : null;
+        if (sk) {
+            const one = args.includes("--um") || args.includes("--one");
+            const ctxText = args.filter((x) => x !== "--um" && x !== "--one").join(" ");
+            const msg = `Invoquei a skill ${sk.name}. Chame skill_load("${sk.name}") agora e siga-a.${one ? " Faça UMA pergunta por mensagem." : ""}${ctxText ? `\n\nContexto: ${ctxText}` : "\n\n(Sem contexto extra: comece perguntando sobre o que quero trabalhar.)"}`;
+            const ac = (running = new AbortController());
+            dock?.setBusy(true);
+            try {
+                await b.turn(msg, ac.signal);
+                await b.afterTurn?.();
+            }
+            finally {
+                running = null;
+                dock?.setBusy(false);
+                refreshSkills();
+                dock?.repaint();
+            }
+            return;
+        }
         // "/Users/x/arquivo.pdf" é caminho, não comando: segue como mensagem ao agente
         if (line.startsWith("/") && !cmd.slice(1).includes("/")) {
             ui.warn(`comando desconhecido: ${cmd}. Digite /help.`);

package/dist/rules.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const home = () => process.env.BRITO_HOME ?? path.join(os.homedir(), ".brito");
+export const projectSettingsPath = (root) => path.join(root, ".brito", "settings.json");
+const settingsFiles = (root) => [path.join(home(), "settings.json"), projectSettingsPath(root), path.join(root, ".brito", "settings.local.json")];
+function readPerms(file) {
+    try {
+        const p = JSON.parse(fs.readFileSync(file, "utf8"))?.permissions ?? {};
+        const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.trim() !== "") : []);
+        return { allow: list(p.allow), deny: list(p.deny) };
+    }
+    catch {
+        return {};
+    } // arquivo ausente ou ilegível: sem regras dele
+}
+export function loadRules(root) {
+    const parts = settingsFiles(root).map(readPerms);
+    return { allow: parts.flatMap((p) => p.allow ?? []), deny: parts.flatMap((p) => p.deny ?? []) };
+}
+/** Acrescenta uma regra ao `.brito/settings.json` do projeto, preservando o resto do arquivo. */
+export function addRule(root, kind, rule) {
+    if (!parseRule(rule))
+        throw new Error(`regra inválida: ${rule} (use tool ou tool(padrão))`);
+    const file = projectSettingsPath(root);
+    let cfg = {};
+    try {
+        cfg = JSON.parse(fs.readFileSync(file, "utf8")) ?? {};
+    }
+    catch { /* arquivo novo */ }
+    cfg.permissions ??= {};
+    const list = (cfg.permissions[kind] ??= []);
+    if (!list.includes(rule))
+        list.push(rule);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+}
+export function parseRule(rule) {
+    const m = /^\s*([A-Za-z_][\w-]*)\s*(?:\((.*)\))?\s*$/s.exec(rule);
+    return m ? { tool: m[1], pattern: m[2] } : null;
+}
+const esc = (s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+/** Padrão de comando: `*` = qualquer coisa; `:*` no fim = o prefixo sozinho ou seguido de argumentos. */
+function commandRegex(p) {
+    const prefix = p.endsWith(":*");
+    const body = (prefix ? p.slice(0, -2) : p).trim().split("*").map(esc).join(".*");
+    return new RegExp(`^${body}${prefix ? "(\\s.*)?" : ""}$`, "s");
+}
+/** Padrão de caminho: `**` cruza diretórios, `*` não. */
+function pathRegex(p) {
+    const body = p.replace(/\\/g, "/").split("**").map((part) => part.split("*").map(esc).join("[^/]*")).join(".*");
+    return new RegExp(`^${body}$`);
+}
+/**
+ * Divide um comando nos pedaços que o shell executaria (`&&`, `||`, `;`, `|`, quebra de linha). Uma regra `allow`
+ * precisa cobrir cada pedaço: `npm test*` não pode liberar `npm test && rm -rf ~`. Aspas não são interpretadas, o
+ * que só pode gerar pedaços a mais (mais perguntas), nunca a menos.
+ */
+export function commandSegments(cmd) {
+    return cmd.split(/&&|\|\||[;|\n]/).map((s) => s.trim()).filter(Boolean);
+}
+/** Construções que rodam ou escrevem algo fora do que o texto do pedaço mostra: nunca liberadas por regra. */
+const OPAQUE = /\$\(|`|<\(|>\(/;
+const SAFE_REDIRECTS = /\s*(?:\d?>\s*\/dev\/null|2>&1|>&2)/g;
+/** O alvo da regra para cada tool que pede aprovação; `undefined` = a tool não tem alvo (regra só pelo nome). */
+function targetOf(tool, input, root) {
+    if (tool === "bash")
+        return typeof input?.command === "string" ? input.command : undefined;
+    if (typeof input?.path === "string")
+        return path.relative(root, path.resolve(root, input.path)).split(path.sep).join("/");
+    return undefined;
+}
+function matches(rule, tool, target, segment) {
+    const r = parseRule(rule);
+    if (!r || r.tool !== tool)
+        return false;
+    if (r.pattern === undefined || r.pattern.trim() === "*")
+        return true;
+    if (target === undefined)
+        return false;
+    if (tool === "bash")
+        return commandRegex(r.pattern).test(segment ?? target);
+    return pathRegex(r.pattern).test(target);
+}
+/** Decide uma chamada de tool pelas regras. `ask` = nenhuma regra decide; o modo de permissão segue valendo. */
+export function decide(rules, tool, input, root) {
+    const target = targetOf(tool, input, root);
+    if (tool === "bash" && target !== undefined) {
+        const segs = commandSegments(target);
+        if (rules.deny.some((d) => matches(d, tool, target, target) || segs.some((s) => matches(d, tool, target, s))))
+            return "deny";
+        if (OPAQUE.test(target) || /[<>]/.test(target.replace(SAFE_REDIRECTS, "")))
+            return "ask";
+        const clean = (s) => s.replace(SAFE_REDIRECTS, "").trim();
+        return segs.length && segs.every((s) => rules.allow.some((a) => matches(a, tool, target, clean(s)))) ? "allow" : "ask";
+    }
+    if (rules.deny.some((d) => matches(d, tool, target)))
+        return "deny";
+    if (rules.allow.some((a) => matches(a, tool, target)))
+        return "allow";
+    return "ask";
+}

package/dist/skills/builtin.js

@@ -0,0 +1,89 @@
+export const BUILTIN_SKILLS = [
+    {
+        name: "grill-me",
+        description: "Entrevista o usuário sobre uma ideia/plano vago até ele conseguir se comprometer; sem escrever arquivos.",
+        model: "modelo mais capaz",
+        body: `## Quando usar
+O usuário digitou /grill-me com uma ideia, funcionalidade ou decisão ainda vaga. Comece numa conversa nova, sem plano pronto.
+
+## Passos
+1. Antes de perguntar, use graph_search/graph_context/recall para responder sozinho o que o código ou a memória já dizem. Nunca pergunte o que dá para descobrir.
+2. Trabalhe em RODADAS. Cada rodada é a "frontier": todas as perguntas cujos pré-requisitos já foram respondidos. Nunca pergunte algo que depende de resposta ainda não dada.
+3. Numere as perguntas (Q1, Q2…), agrupe por tema e dê, em cada uma, a sua recomendação e o porquê. O usuário decide: não aceite "ok, ok, ok" sem teste; peça a razão quando a resposta for vaga.
+4. Se o usuário pediu --um (ou "uma por vez"), faça só UMA pergunta por mensagem, a mais importante da frontier.
+5. Perguntas que conversa não resolve (ex.: "formato longo ou curto?") não se discutem: proponha um protótipo descartável (em worktree ou arquivo temporário), peça para avaliar e volte com uma resposta curta.
+6. Mostre premissas implícitas que você notou ("você está assumindo que X"). Procure o que quebra: falhas, casos de borda, dependências, custo.
+7. Não escreva nem edite arquivos. Não use o modo plano: o objetivo é continuar perguntando, não correr para um plano.
+
+## Armadilhas
+- Passar de ~50 perguntas ou 4–5 rodadas: o escopo está grande demais. Proponha dividir em partes menores (ver wayfinder) em vez de seguir.
+- Sessão longa piora a qualidade das perguntas; resuma o que já foi decidido a cada rodada.
+
+## Verificação
+Termine quando a frontier esvaziar: todos os ramos visitados e nenhuma premissa implícita. Feche com um resumo curto das decisões tomadas e sugira o próximo passo (grill-with-docs para registrar, ou começar a implementar).`,
+    },
+    {
+        name: "grill-with-docs",
+        description: "Como o grill-me, mas lê o código e registra cada decisão fechada na memória do grafo (remember).",
+        model: "modelo mais capaz",
+        body: `## Quando usar
+O usuário digitou /grill-with-docs: a mesma entrevista do grill-me, mas o resultado precisa ficar registrado para as próximas sessões.
+
+## Passos
+1. Rode recall com os termos do tema e leia as notas e decisões existentes antes de perguntar. Não reabra o que já foi decidido, a menos que o usuário peça.
+2. Siga o método do grill-me (rodadas pela frontier, recomendação em cada pergunta, nada de perguntar o que o grafo responde). Use graph_context/graph_callers para embasar as perguntas em código real.
+3. A cada decisão fechada, chame remember(kind="decision") com o texto da decisão, o motivo e refs para os arquivos/símbolos afetados. Termos de domínio novos viram remember(kind="convention") com a definição.
+4. Quando o usuário discordar de uma nota antiga, registre a nova e diga qual substitui qual.
+5. Ao terminar, liste as notas gravadas e, se fizer sentido, sugira atualizar README/docs (só sugerir; editar exige pedido).
+
+## Armadilhas
+- Não grave hipóteses ou perguntas em aberto como decisão.
+- Não grave segredos nem caminhos absolutos.
+
+## Verificação
+Cada decisão do resumo final tem uma nota correspondente (confira com recall) e a frontier está vazia.`,
+    },
+    {
+        name: "wayfinder",
+        description: "Para trabalho grande demais para uma sessão: mapeia o esforço em partes, ordena e delega cada parte.",
+        model: "modelo mais capaz",
+        body: `## Quando usar
+O usuário digitou /wayfinder com um objetivo amplo (migração, refatoração grande, funcionalidade com várias partes) que não cabe em um contexto só.
+
+## Passos
+1. Mapeie o terreno com o grafo: graph_search para achar os pontos de entrada, graph_impact nos arquivos centrais para medir o raio de mudança. Dispense ler arquivos inteiros.
+2. Quebre o objetivo em partes pequenas e independentes, cada uma com: objetivo, arquivos/símbolos, dependências de outras partes e como verificar (typecheck/teste).
+3. Ordene por dependência; marque quais podem rodar em paralelo.
+4. Mostre o mapa ao usuário e confirme antes de executar. Se houver dúvidas de escopo, rode o método do grill-me só nelas.
+5. Execute parte por parte. Use delegate para as que são grandes ou só de leitura (explore/plan em paralelo); mantenha uma lista com todo_write, uma parte in_progress por vez.
+6. Ao fim de cada parte, verifique, grave com remember o que foi decidido e siga para a próxima.
+
+## Armadilhas
+- Partes que tocam os mesmos arquivos não devem rodar em paralelo.
+- Não deixe uma parte depender de contexto que só existe na conversa: escreva a tarefa completa para o subagente.
+
+## Verificação
+Todas as partes do mapa estão concluídas e verificadas, e o typecheck e os testes do projeto passam.`,
+    },
+    {
+        name: "grill-diff",
+        description: "Revisão por perguntas: usa o grafo no diff atual e questiona o usuário sobre impacto e intenção das mudanças.",
+        model: "modelo mais capaz",
+        body: `## Quando usar
+O usuário digitou /grill-diff antes de commitar/abrir PR, ou quer testar se as mudanças foram intencionais.
+
+## Passos
+1. Rode git diff (e git status) via bash para listar o que mudou. Não edite nada.
+2. Para cada símbolo ou arquivo alterado, use graph_callers/graph_impact e liste quem depende dele.
+3. Faça perguntas pontuais, numeradas, só onde há risco: "você mudou X, que Y e Z chamam. O comportamento para o caso W continua igual?", "esta função perdeu o tratamento de erro: foi intencional?", "falta teste para este caminho".
+4. Dê a sua recomendação em cada pergunta. Não repita o que o diff já deixa óbvio.
+5. Se uma resposta revelar um problema, aponte a correção, mas só aplique se o usuário pedir.
+
+## Armadilhas
+- Mudança só de formatação ou de comentário não precisa de pergunta.
+- Não confunda impacto no grafo (quem chama) com quebra real: confirme lendo o trecho.
+
+## Verificação
+Cada símbolo alterado com chamadores teve a pergunta feita e respondida (ou descartada como segura), e o resumo final lista riscos restantes e testes a rodar.`,
+    },
+];

package/dist/skills/describe.js

@@ -1,4 +1,4 @@
-import { getSkill, lintSkill, targetScope } from "./store.js";
+import { adviseSkill, getSkill, lintSkill, targetScope } from "./store.js";
 import { lineDiff } from "../util/diff.js";
 /** Texto de aprovação de um skill_save: body inteiro na criação, diff na atualização, com o resultado do lint no topo. */
 export function describeSave(root, i) {
@@ -6,7 +6,8 @@ export function describeSave(root, i) {
     const prev = getSkill(root, i.name);
     const tag = scope === "global" ? "GLOBAL (vale em todos os projetos)" : "do projeto";
     const updating = prev && prev.scope === scope;
-    const { errors, warnings } = lintSkill(i);
+    const { errors, warnings: lintWarnings } = lintSkill(i);
+    const warnings = [...lintWarnings, ...adviseSkill(i)];
     const shown = updating ? lineDiff(prev.body, i.body.trim()) : i.body.split("\n");
     return `${updating ? `ATUALIZAR skill ${tag} ${i.name} (v${prev.version} → v${prev.version + 1})` : `CRIAR skill ${tag} ${i.name}`}\n  quando: ${i.description}\n  motivo: ${i.reason}\n` +
         [...errors.map((e) => `  ✗ ${e}`), ...warnings.map((w) => `  ⚠ ${w}`)].join("\n") + (errors.length || warnings.length ? "\n" : "") +

package/dist/skills/learn.js

@@ -96,7 +96,7 @@ export function recordOutcomes(turn, ctx) {
     const verdict = judgeTurn(turn);
     if (!verdict)
         return [];
-    return [...(ctx.loadedSkills ?? [])].flatMap((n) => recordOutcome(ctx.root, n, verdict === "win") ?? []);
+    return [...(ctx.loadedSkills ?? [])].flatMap((n) => recordOutcome(ctx.root, n, verdict === "win", extractSignals(turn)[0]?.detail) ?? []);
 }
 export const defaultComplete = async ({ model, system, user, tools, maxTokens }) => {
     // Raciocínio desligado: o julgamento cabe no orçamento e a resposta útil é a chamada de skill_save.
@@ -183,7 +183,7 @@ export function buildReflectInput(turn, ctx, previous) {
     const seen = similarEntries(ctx.root, turn);
     return (`# Skills existentes\n${existing.length ? existing.map((s) => `- ${s.name}${s.scope === "global" ? " (global)" : ""}${staleRefs(ctx.root, s).length ? " [refs obsoletas]" : ""}: ${s.description}`).join("\n") : "(nenhuma)"}\n\n` +
         (pending.length ? `# Propostas pendentes (aguardam revisão do usuário; contam como existentes: para ajustar uma, use o MESMO name)\n${pending.map((p) => `- ${p.name}${p.scope === "global" ? " (global)" : ""}: ${p.description}`).join("\n")}\n\n` : "") +
-        (loaded.length ? `# Skills carregadas neste turno (candidatas a melhoria)\n${loaded.map((s) => `## ${s.name} (${s.scope}) v${s.version}${staleRefs(ctx.root, s).length ? `\n(refs que não existem mais: ${staleRefs(ctx.root, s).join(", ")} — atualize se o turno mostrou os caminhos novos)` : ""}\n${s.body}`).join("\n\n")}\n\n` : "") +
+        (loaded.length ? `# Skills carregadas neste turno (candidatas a melhoria)\n${loaded.map((s) => `## ${s.name} (${s.scope}) v${s.version}${s.lastLoss ? `\n(último tropeço registrado: ${s.lastLoss})` : ""}${staleRefs(ctx.root, s).length ? `\n(refs que não existem mais: ${staleRefs(ctx.root, s).join(", ")} — atualize se o turno mostrou os caminhos novos)` : ""}\n${s.body}`).join("\n\n")}\n\n` : "") +
         (signals.length ? `# Sinais\n${signals.map((x) => `- ${x.kind}: ${x.detail}`).join("\n")}\n\n` : "") +
         (seen.length ? `# Tarefas parecidas já vistas (sessões anteriores)\n${seen.map(describeEntry).join("\n")}\n\n` : "") +
         (previous ? `# Turno anterior (só contexto, não é o que está sendo avaliado)\n${renderPrevious(previous)}\n\n` : "") +

package/dist/skills/store.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parseFrontmatter, stringifyFrontmatter } from "../util/frontmatter.js";
+import { BUILTIN_SKILLS } from "./builtin.js";
 export const NAME_RE = /^[a-z0-9][a-z0-9-]{1,48}$/;
 const today = () => new Date().toISOString().slice(0, 10);
 /** Skills globais valem para todos os projetos. `BRITO_HOME` troca o local (útil em testes). */
@@ -28,12 +29,15 @@ function parse(text, scope) {
         losses: Number(meta.losses) || 0,
         body: body.trim(),
         scope,
+        invoke: meta.invoke === "manual" ? "manual" : "auto",
+        model: meta.model ?? "",
+        lastLoss: meta.lastLoss ?? "",
     };
 }
 export function writeSkill(root, s) {
     const file = fileOf(root, s.scope, s.name);
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, stringifyFrontmatter({ name: s.name, description: s.description, version: s.version, uses: s.uses, created: s.created, updated: s.updated, lastUsed: s.lastUsed, refs: s.refs.join(", "), status: s.status, origin: s.origin, wins: s.wins, losses: s.losses }, s.body));
+    fs.writeFileSync(file, stringifyFrontmatter({ name: s.name, description: s.description, version: s.version, uses: s.uses, created: s.created, updated: s.updated, lastUsed: s.lastUsed, refs: s.refs.join(", "), status: s.status, origin: s.origin, wins: s.wins, losses: s.losses, ...(s.invoke === "manual" ? { invoke: "manual" } : {}), ...(s.model ? { model: s.model } : {}), ...(s.lastLoss ? { lastLoss: s.lastLoss } : {}) }, s.body));
 }
 /** Lê uma skill de um escopo específico. */
 export function getSkillIn(root, name, scope) {
@@ -48,7 +52,19 @@ export function getSkillIn(root, name, scope) {
 }
 /** Resolve por nome: a skill do projeto sobrepõe a global de mesmo nome. */
 export function getSkill(root, name) {
-    return getSkillIn(root, name, "project") ?? getSkillIn(root, name, "global");
+    return getSkillIn(root, name, "project") ?? getSkillIn(root, name, "global") ?? getBuiltin(name);
+}
+/** Skills embutidas: disponíveis em qualquer projeto sem gravar nada em disco. */
+export function getBuiltin(name) {
+    const b = BUILTIN_SKILLS.find((x) => x.name === name);
+    if (!b)
+        return null;
+    const d = "2026-11-07";
+    return { name: b.name, description: b.description, version: 1, uses: 0, created: d, updated: d, lastUsed: d, refs: [], status: "active", origin: "manual", wins: 0, losses: 0, body: b.body, scope: "global", invoke: "manual", model: b.model ?? "", lastLoss: "", builtin: true };
+}
+/** Embutidas ainda não sobrepostas por uma skill do usuário. */
+export function listBuiltins(root) {
+    return BUILTIN_SKILLS.flatMap((b) => (getSkillIn(root, b.name, "project") ?? getSkillIn(root, b.name, "global") ? [] : [getBuiltin(b.name)]));
 }
 function listScope(root, scope) {
     const dir = dirOf(root, scope);
@@ -118,6 +134,17 @@ export function lintSkill(input) {
     const destructive = DESTRUCTIVE_RULES.filter((r) => r.re.test(text)).map((r) => `comando destrutivo (${r.msg}): só mantenha se houver guarda (backup, cópia/ambiente de teste ou confirmação)`);
     return { errors, warnings: [...urls, ...destructive] };
 }
+/** Limite suave: skills longas pioram a qualidade do agente ("dumb zone"); acima disso, sugerimos dividir. */
+export const SOFT_BODY_LIMIT = 3000;
+/** Dicas de qualidade (não bloqueiam nem entram em `lintSkill`): tamanho e critério de término/verificação. */
+export function adviseSkill(input) {
+    const tips = [];
+    if (input.body.length > SOFT_BODY_LIMIT)
+        tips.push(`body com ${input.body.length} chars (> ${SOFT_BODY_LIMIT}): considere dividir em skills menores`);
+    if (!/verifica|crit[ée]rio de (t[ée]rmino|sa[ií]da|pronto)|done when|pronto quando/i.test(input.body))
+        tips.push("sem seção '## Verificação' ou critério de término: diga como saber que acabou");
+    return tips;
+}
 export function validate(input) {
     if (!NAME_RE.test(input.name))
         throw new Error("name deve ser kebab-case (a-z, 0-9, hífen), 2–49 chars.");
@@ -164,6 +191,9 @@ export function saveSkill(root, input, scope, opts = {}) {
         losses: opts.auto && prev?.status === "trial" ? 0 : prev?.losses ?? 0,
         body: input.body.trim(),
         scope: target,
+        invoke: input.invoke ?? prev?.invoke ?? "auto",
+        model: input.model ?? prev?.model ?? "",
+        lastLoss: prev?.lastLoss ?? "",
     };
     writeSkill(root, skill);
     return { created: !prev, version: skill.version, scope: target };
@@ -215,13 +245,13 @@ export function rejectPending(root, name) {
 }
 export function bumpUses(root, name) {
     const s = getSkill(root, name);
-    if (s)
+    if (s && !s.builtin)
         writeSkill(root, { ...s, uses: s.uses + 1, lastUsed: today() });
 }
 /** Move para `.trash` do próprio escopo em vez de apagar. */
 export function deleteSkill(root, name, scope) {
     const s = scope ? getSkillIn(root, name, scope) : getSkill(root, name);
-    if (!s)
+    if (!s || s.builtin)
         return false;
     const base = dirOf(root, s.scope);
     fs.mkdirSync(path.join(base, ".trash"), { recursive: true });
@@ -239,8 +269,34 @@ export function promoteSkill(root, name) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.renameSync(path.join(dirOf(root, "project"), name), dest);
 }
-/** Índice compacto para o system prompt (divulgação progressiva: o corpo só entra via skill_load). */
-export function skillsIndex(root, max = 40, now = Date.now()) {
-    const all = listSkills(root, now).slice(0, max);
-    return all.length ? all.map((s) => `- ${s.name}${s.scope === "global" ? " (global)" : ""}${s.status === "trial" ? " (em teste)" : ""}${staleRefs(root, s).length ? " [refs obsoletas]" : ""}: ${s.description}`).join("\n") : "";
+/** Quantas skills vão para o índice do system prompt; o resto é achado por `skill_load` (sugestões) ou `/skills suggest`. */
+export const INDEX_MAX = 25;
+/** Índice compacto para o system prompt (divulgação progressiva: o corpo só entra via skill_load). Skills `manual` ficam de fora. */
+export function skillsIndex(root, max = INDEX_MAX, now = Date.now()) {
+    const eligible = listSkills(root, now).filter((s) => s.invoke !== "manual");
+    const all = eligible.slice(0, max);
+    if (!all.length)
+        return "";
+    const rest = eligible.length - all.length;
+    return all.map((s) => `- ${s.name}${s.scope === "global" ? " (global)" : ""}${s.status === "trial" ? " (em teste)" : ""}${staleRefs(root, s).length ? " [refs obsoletas]" : ""}: ${s.description}`).join("\n")
+        + (rest > 0 ? `\n(+${rest} skills não listadas: chame skill_load com uma palavra da tarefa para receber sugestões)` : "");
+}
+const STOP = new Set(["para", "como", "com", "uma", "que", "the", "and", "uso", "usar", "skill", "fazer", "esta", "isso", "nos", "nas", "dos", "das", "por"]);
+export const words = (t) => (t.toLowerCase().normalize("NFD").replace(/\p{M}/gu, "").match(/[a-z0-9]{3,}/g) ?? []).filter((w) => !STOP.has(w));
+/** Skills (incluindo manuais e embutidas) ordenadas por afinidade lexical com o texto. Nome pesa mais que descrição. */
+export function suggestSkills(root, text, limit = 5) {
+    const q = new Set(words(text));
+    if (!q.size)
+        return [];
+    return [...listSkills(root), ...listBuiltins(root)]
+        .map((skill) => {
+        const nm = new Set(words(skill.name)), ds = new Set(words(skill.description)), bd = new Set(words(skill.body));
+        let score = 0;
+        for (const w of q)
+            score += (nm.has(w) ? 3 : 0) + (ds.has(w) ? 2 : 0) + (bd.has(w) ? 0.5 : 0);
+        return { skill, score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+        .slice(0, limit);
 }

package/dist/skills/trial.js

@@ -9,11 +9,11 @@ export const TRIAL_DAYS = 21;
 /** Teto de skills novas criadas sozinhas por dia (contido: cada uma vira instrução para o agente). */
 export const DAILY_LIMIT = 3;
 /** Registra o resultado de um turno que usou a skill. Devolve um aviso se ela foi promovida ou arquivada. */
-export function recordOutcome(root, name, win) {
+export function recordOutcome(root, name, win, loss) {
     const s = getSkill(root, name);
-    if (!s)
+    if (!s || s.builtin)
         return null;
-    const next = { ...s, wins: s.wins + (win ? 1 : 0), losses: s.losses + (win ? 0 : 1) };
+    const next = { ...s, wins: s.wins + (win ? 1 : 0), losses: s.losses + (win ? 0 : 1), lastLoss: win ? s.lastLoss : (loss ?? s.lastLoss).replace(/\s+/g, " ").slice(0, 200) };
     if (s.origin === "auto") {
         if (s.status === "trial") {
             if (next.wins >= PROMOTE_WINS && next.wins >= 3 * next.losses) {