@seedgrid/ai-toolkit 0.4.0 → 0.4.2

package/dist/adapters/shared.js

@@ -132,6 +132,7 @@ export function agentsMdBlock(bundle, targets, mode) {
         '',
         `Bloco gerenciado pelo \`seedgrid-ai\` (conteúdo ${bundle.contentVersion}, modo \`${mode}\`). Não edite entre os marcadores; personalize em \`.ai/local/\`.`,
         '',
+        ...(bundle.agentsNotes.length > 0 ? [...bundle.agentsNotes.map((n) => `> ${n}`), ''] : []),
         'Cada pasta de `.ai/` tem um `index.md` com o que há nela: comece por ele e leia só o que a tarefa pedir.',
         '',
         '- Regras: `.ai/rules/`. Antes de tarefas não triviais, leia `coordenacao.md`.',

package/dist/core/content.js

@@ -510,6 +510,10 @@ export async function loadContent(root) {
         checkBrain(ctx, brain.notes, brain.entrypoints, brain.base);
         shared.push(...brain.notes);
     }
+    const rawNotes = manifest.agentsNotes ?? [];
+    if (!Array.isArray(rawNotes) || rawNotes.length > 10 || rawNotes.some((n) => typeof n !== 'string' || n.trim() === '' || n.length > 600 || n.includes('\n'))) {
+        ctx.errors.push('manifest: agentsNotes deve ser uma lista de até 10 linhas de texto (até 600 caracteres, sem quebra de linha)');
+    }
     if (ctx.errors.length > 0) {
         throw new ToolkitError(`Conteúdo inválido em ${absRoot}`, ctx.errors);
     }
@@ -523,6 +527,7 @@ export async function loadContent(root) {
         brain: brain
             ? { notes: brain.notes.length, entrypoints: brain.entrypoints.map((e) => `.ai/brain/${brain.base}/${e}`) }
             : null,
+        agentsNotes: rawNotes,
         sourceFiles: [...ctx.sources].sort(),
     };
 }

package/docs/formato.md

@@ -87,6 +87,7 @@ Arquivos e pastas que começam com ponto são ignorados.
 | --- | --- |
 | `schemaVersion` | `2` (versão do formato do manifesto) |
 | `contentVersion` | semver; deve ser **igual** à versão do pacote (`package.json`); aumente a cada mudança de conteúdo |
+| `agentsNotes` | (opcional) até 10 linhas curtas que o bloco do `AGENTS.md` mostra no topo, como aviso (ex.: o modo de trabalho que uma camada adicional exige) |
 | `toolkitBase` | pasta do vault onde ficam `agents/`, `rules/`, `templates/`, `references/` e `skills/` (aqui, `SeedGrid/Toolkit`) |
 | `components[].id` | único; para skills, `skill:<name>` |
 | `components[].type` | `agents`, `rules`, `templates`, `references`, `skill` ou `brain` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/ai-toolkit",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Instala agentes, skills, regras, templates e referências versionados em projetos locais para Claude Code e Codex.",
   "type": "module",
   "license": "MIT",

package/seedgridKB/SeedGrid/Toolkit/skills/sg-adr/SKILL.md

@@ -17,10 +17,11 @@ Crie uma ADR quando a decisão: muda um comportamento observável; cria, remove
 
 1. **Listar as decisões.** Escreva cada uma em uma frase e **mostre ao usuário** para confirmar: você propõe, quem decide é o usuário. Ao registrar, repita a decisão em uma frase (decisão registrada errada só aparece quando alguém relê).
 2. **Domínio.** Escolha na lista `docs/ai/decisions/dominios.txt` (um domínio por linha). Se o arquivo não existir, proponha 5 a 10 domínios do projeto (por exemplo `seguranca`, `dados`, `api`, `configuracao`, `processo`), confirme e crie. Domínio novo só com confirmação do usuário.
-3. **Criar o arquivo** `docs/ai/decisions/AAAA-MM-DD-slug.md` a partir do modelo `.ai/templates/decisao-arquitetura.md`: cabeçalho completo (`titulo`, `data`, `status`, `decidido-por`, `consultados`, `dominio`, `modulos`, `origem`) e as seções Contexto, Decisão, Alternativas e Consequências. Comece com `status: proposta` e mude para `aceita` quando o usuário confirmar.
-4. **Substituição.** Se a decisão troca outra, não edite a antiga: crie a nova com `substitui: [arquivo-antigo.md]` e apenas marque a antiga como `status: substituida` e `substituida-por`.
-5. **Índice.** Rode `node .ai/skills/sg-adr/scripts/adr-index.mjs`. Ele valida o cabeçalho e gera `docs/ai/decisions/INDEX.md` em ordem decrescente de data. Nunca edite o `INDEX.md` à mão; use `--check` para conferir se está em dia.
-6. **Entregar** listando as ADRs criadas e o que ficou como `proposta`.
+3. **Número.** `node .ai/skills/sg-adr/scripts/adr-index.mjs --proximo` dá o próximo número livre; ele é sequencial, vai em `numero:` e **nunca muda** (dá para conversar sobre "a ADR #7"). Para ADRs antigas sem número, `--numerar` numera só as que não têm.
+4. **Criar o arquivo** `docs/ai/decisions/AAAA-MM-DD-slug.md` a partir do modelo `.ai/templates/decisao-arquitetura.md`: cabeçalho completo (`titulo`, `numero`, `data`, `status`, `decidido-por`, `consultados`, `dominio`, `modulos`, `origem`) e as seções Contexto, Decisão, Alternativas e Consequências. Comece com `status: proposta` e mude para `aceita` quando o usuário confirmar.
+5. **Substituição.** Se a decisão troca outra, não edite a antiga: crie a nova com `substitui: [arquivo-antigo.md]` e apenas marque a antiga como `status: substituida` e `substituida-por`.
+6. **Índice.** Rode `node .ai/skills/sg-adr/scripts/adr-index.mjs`. Ele valida o cabeçalho e gera `docs/ai/decisions/INDEX.md` em ordem decrescente de data. Nunca edite o `INDEX.md` à mão; use `--check` para conferir se está em dia.
+7. **Entregar** listando as ADRs criadas e o que ficou como `proposta` (o que o dono confirmou e já está no código é `implementada`).
 
 ## Consultar
 

package/seedgridKB/SeedGrid/Toolkit/skills/sg-adr/scripts/adr-index.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // Gera docs/ai/decisions/INDEX.md a partir do cabeçalho das ADRs, da mais nova para a mais antiga.
 // Uso: node .ai/skills/sg-adr/scripts/adr-index.mjs [--dir docs/ai/decisions] [--check]
-//   --check  só valida e falha se o INDEX.md estiver desatualizado (sem escrever)
+//   --check    só valida e falha se o INDEX.md estiver desatualizado (sem escrever)
+//   --proximo  imprime o próximo número livre para uma ADR nova
+//   --numerar  dá número, em ordem de data e nome, SÓ às ADRs sem "numero"; nunca renumera
 // Domínios: se existir <dir>/dominios.txt (um por linha), só esses são aceitos; senão, qualquer slug em minúsculas com hífen.
 import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
@@ -10,7 +12,7 @@ const args = process.argv.slice(2);
 const di = args.indexOf('--dir');
 const dir = path.resolve(di >= 0 && args[di + 1] ? args[di + 1] : 'docs/ai/decisions');
 const check = args.includes('--check');
-const STATUS = ['proposta', 'aceita', 'substituida', 'rejeitada'];
+const STATUS = ['proposta', 'aceita', 'implementada', 'substituida', 'rejeitada'];
 
 if (!existsSync(dir)) {
   console.error(`Pasta não encontrada: ${dir}`);
@@ -35,9 +37,34 @@ function parse(text, file) {
   return out;
 }
 
+const files = readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'INDEX.md').sort();
+const numeroDe = (f) => {
+  try {
+    const n = parse(readFileSync(path.join(dir, f), 'utf8'), f).numero;
+    return /^\d+$/.test(String(n ?? '')) ? Number(n) : null;
+  } catch { return null; }
+};
+const maior = () => Math.max(0, ...files.map(numeroDe).filter((n) => n !== null));
+if (args.includes('--numerar')) {
+  let max = maior();
+  for (const f of files.filter((x) => numeroDe(x) === null)) {
+    const file = path.join(dir, f);
+    const raw = readFileSync(file, 'utf8');
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    const out = raw.replace(/^(titulo:[^\r\n]*)/m, `$1${eol}numero: ${++max}`);
+    if (out === raw) { console.error(`${f}: sem linha "titulo:" para numerar`); process.exit(1); }
+    writeFileSync(file, out, 'utf8');
+    console.log(`${f} -> #${max}`);
+  }
+}
+if (args.includes('--proximo')) {
+  console.log(maior() + 1);
+  process.exit(0);
+}
+
 const errors = [];
 const adrs = [];
-for (const f of readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'INDEX.md').sort()) {
+for (const f of files) {
   let h;
   try {
     h = parse(readFileSync(path.join(dir, f), 'utf8'), f);
@@ -46,7 +73,8 @@ for (const f of readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'INDEX
     continue;
   }
   if (!/^\d{4}-\d{2}-\d{2}-/.test(f)) errors.push(`${f}: o nome deve começar com AAAA-MM-DD-`);
-  for (const k of ['titulo', 'data', 'status', 'decidido-por', 'dominio']) if (!h[k] || h[k].length === 0) errors.push(`${f}: falta "${k}"`);
+  for (const k of ['titulo', 'numero', 'data', 'status', 'decidido-por', 'dominio']) if (!h[k] || h[k].length === 0) errors.push(`${f}: falta "${k}"`);
+  if (h.numero && !/^[1-9]\d*$/.test(h.numero)) errors.push(`${f}: numero inválido (${h.numero}); use inteiro a partir de 1`);
   if (h.data && !/^\d{4}-\d{2}-\d{2}$/.test(h.data)) errors.push(`${f}: data inválida (${h.data})`);
   if (h.status && !STATUS.includes(h.status)) errors.push(`${f}: status inválido (${h.status}); use ${STATUS.join(' | ')}`);
   const doms = Array.isArray(h.dominio) ? h.dominio : [h.dominio].filter(Boolean);
@@ -57,22 +85,27 @@ for (const f of readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'INDEX
   }
   adrs.push({ file: f, ...h, doms });
 }
+const nums = adrs.map((a) => Number(a.numero)).filter(Number.isInteger).sort((a, b) => a - b);
+for (let i = 0; i < nums.length; i++) {
+  if (i > 0 && nums[i] === nums[i - 1]) errors.push(`numero #${nums[i]} repetido`);
+  else if (nums[i] !== i + 1) { errors.push(`numeração com lacuna: esperado #${i + 1}, achei #${nums[i]}`); break; }
+}
 if (errors.length) {
   console.error(errors.join('\n'));
   process.exit(1);
 }
-adrs.sort((a, b) => b.data.localeCompare(a.data) || b.file.localeCompare(a.file));
+adrs.sort((a, b) => b.data.localeCompare(a.data) || Number(b.numero) - Number(a.numero));
 
 const list = (v) => (Array.isArray(v) ? v.join(', ') : v || '');
-const rows = adrs.map((a) => `| ${a.data} | [${a.titulo}](${a.file}) | ${a.doms.join(', ')} | ${a.status} | ${list(a['decidido-por'])} | ${list(a.consultados)} |`);
+const rows = adrs.map((a) => `| ${a.numero} | ${a.data} | [${a.titulo}](${a.file}) | ${a.doms.join(', ')} | ${a.status} | ${list(a['decidido-por'])} | ${list(a.consultados)} |`);
 const body = `# Decisões (ADR)
 
-> Gerado por \`node .ai/skills/sg-adr/scripts/adr-index.mjs\` a partir do cabeçalho de cada ADR. Não edite à mão. Ordem: da mais nova para a mais antiga.
+> Gerado por \`node .ai/skills/sg-adr/scripts/adr-index.mjs\` a partir do cabeçalho de cada ADR. Não edite à mão. Ordem: da mais nova para a mais antiga. O número \`#\` é sequencial, dado na criação e **nunca muda**: use-o para falar de uma ADR ("ADR #7").
 
 Para saber **por que** algo foi feito, procure pelo domínio (coluna 3) ou pelo módulo no cabeçalho de cada ADR.${DOMINIOS ? ` Domínios: ${DOMINIOS.join(', ')}.` : ''}
 
-| Data | Decisão | Domínio | Status | Decidido por | Consultados |
-|---|---|---|---|---|---|
+| # | Data | Decisão | Domínio | Status | Decidido por | Consultados |
+|---|---|---|---|---|---|---|
 ${rows.join('\n')}
 `;
 const target = path.join(dir, 'INDEX.md');

package/seedgridKB/SeedGrid/Toolkit/templates/decisao-arquitetura.md

@@ -11,8 +11,9 @@ Cabeçalho (obrigatório, no topo do arquivo, entre `---`):
 ---
 description: Uma linha com a decisão.
 titulo: Título curto da decisão
+numero: 1                 # sequencial, dado na criação (--proximo); nunca muda
 data: AAAA-MM-DD
-status: proposta          # proposta | aceita | substituida | rejeitada
+status: proposta          # proposta | aceita | implementada | substituida | rejeitada
 decidido-por: nome ou papel
 consultados: [nomes, quando houver]
 dominio: [seguranca]      # lista do projeto (docs/ai/decisions/dominios.txt)
@@ -23,6 +24,8 @@ origem: plano, commit ou tarefa que gerou a decisão
 ---
 ```
 
+Status: `proposta` (a IA propôs; o dono não confirmou); `aceita` (confirmada, ainda não está no código); `implementada` (confirmada e já no código; o que já foi implementado não fica `proposta`).
+
 ## Contexto
 Problema, forças em jogo e restrições.
 

package/seedgridKB/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "contentVersion": "0.4.0",
+  "contentVersion": "0.4.2",
   "toolkitBase": "SeedGrid/Toolkit",
   "components": [
     {