@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/scripts/verificar-recursos/SCRIPT.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
+import { buildCatalog } from '../lib/catalog.mjs';
+import { isGeneratedOutput } from '../lib/gitignore.mjs';
+
+const fail = message => { throw new Error(message); };
+const normalize = value => value.split(sep).join('/');
+const excluded = new Set(['node_modules', '.git', 'opencode-loop', '.agent-tests']);
+const toolState = new Set(['bin', '.cache', 'npm-cache']);
+const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'adapters', 'estado', 'tests', 'docs'];
+
+function checkedStat(root, location) {
+  let item;
+  try { item = lstatSync(location); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null; throw error; }
+  if (item.isSymbolicLink()) fail(`Link simbolico: ${normalize(relative(root, location))}`);
+  return item;
+}
+
+export function registryRoots(root) {
+  checkedStat(root, join(root, '.pbai4devs'));
+  const file = join(root, '.pbai4devs/espelhos.conf');
+  checkedStat(root, file);
+  const rows = readFileSync(file, 'utf8')
+    .split(/\r?\n/).filter(line => /^(?:agente|documento)\|/.test(line))
+    .map(line => line.split('|'));
+  return { agents: rows.filter(row => row[0] === 'agente').map(row => row[1]), paths: rows.map(row => row[1]) };
+}
+
+function walk(root, location, files, { skipTools = true } = {}) {
+  const path = normalize(relative(root, location));
+  if (/^examples\/generated(?:\/|$)/i.test(path)) return;
+  const item = checkedStat(root, location);
+  if (!item) return;
+  if (location === join(root, '.pbai4devs/external-skills/.local')) return;
+  if (skipTools && location === join(root, '.pbai4devs/tools')) return;
+  if (isGeneratedOutput(normalize(relative(root, location)), item.isDirectory())) return;
+  if (item.isDirectory()) {
+    if (excluded.has(basename(location))) return;
+    for (const child of readdirSync(location).sort()) walk(root, join(location, child), files, { skipTools });
+  } else if (item.isFile() && ['.md', '.mdc'].includes(extname(location).toLowerCase())) files.add(location);
+}
+
+export function collectMarkdown(root, registry = registryRoots(root)) {
+  const agents = join(root, '.pbai4devs');
+  checkedStat(root, agents);
+  for (const directory of readdirSync(agents, { withFileTypes: true })) {
+    const location = join(agents, directory.name);
+    const item = checkedStat(root, location);
+    if (isGeneratedOutput(normalize(relative(root, location)), item?.isDirectory())) continue;
+    if (item?.isDirectory() && !checkedStat(root, join(location, 'README.md'))?.isFile()) fail(`README ausente: .pbai4devs/${directory.name}/`);
+  }
+  const files = new Set();
+  const rootMarkdown = readdirSync(root).filter(name => ['.md', '.mdc'].includes(extname(name).toLowerCase()));
+  const sources = ['.pbai4devs', 'docs', 'src', 'bin', 'tests', 'scripts', 'examples',
+    '.github/PULL_REQUEST_TEMPLATE.md', '.github/ISSUE_TEMPLATE', ...rootMarkdown];
+  for (const name of [...sources, ...registry.paths]) walk(root, resolve(root, name), files);
+  const tools = join(agents, 'tools');
+  if (checkedStat(root, tools)) {
+    const guide = join(tools, 'README.md');
+    if (!checkedStat(root, guide)?.isFile()) fail('README ausente: .pbai4devs/tools/');
+    walk(root, guide, files);
+    for (const item of readdirSync(tools, { withFileTypes: true })) {
+      if (toolState.has(item.name) || item.name.startsWith('.')) continue;
+      if (!checkedStat(root, join(tools, item.name))?.isDirectory()) continue;
+      const file = join(tools, item.name, 'README.md');
+      const guide = checkedStat(root, file);
+      if (checkedStat(root, join(tools, item.name, 'TOOL.json')) && !guide?.isFile()) fail(`README ausente: .pbai4devs/tools/${item.name}/`);
+      if (guide) walk(root, file, files);
+    }
+  }
+  return [...files].sort();
+}
+
+export function checkFrontmatter(text, file) {
+  const lines = text.replaceAll('\r', '').split('\n');
+  const closing = lines.indexOf('---', 1);
+  const first = closing > 0 ? lines.slice(closing + 1).find(line => line.trim()) : undefined;
+  if (lines[0] !== '---' || closing < 1 || !first?.startsWith('# ')) fail(`Frontmatter/H1 invalido: ${file}`);
+}
+
+function withoutFences(text) {
+  let fence;
+  return text.split(/\r?\n/).map(line => {
+    const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1];
+      else if (marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = undefined;
+      return '';
+    }
+    return fence ? '' : line;
+  }).join('\n');
+}
+
+export function localLinkTargets(text) {
+  const content = withoutFences(text);
+  const targets = [...content.matchAll(/\]\((<[^>]*>|[^)]*)\)/g)].map(match => match[1]);
+  for (const match of content.matchAll(/^\s{0,3}\[[^\]^][^\]]*\]:\s*(<[^>]+>|\S+)/gm)) targets.push(match[1]);
+  return targets.map(value => {
+    const raw = value.trim();
+    const target = raw.startsWith('<') ? raw.slice(1, raw.indexOf('>')) : raw.split(/\s+["']/)[0];
+    if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target)) return null;
+    const file = target.split(/[?#]/)[0];
+    if (!file) return null;
+    try { return decodeURIComponent(file); }
+    catch { fail(`Link com codificacao invalida: ${target}`); }
+  }).filter(Boolean);
+}
+
+export function checkMarkdown(root, files, { virtualPaths = new Set() } = {}) {
+  for (const file of files) {
+    const label = normalize(relative(root, file));
+    const text = readFileSync(file, 'utf8');
+    checkFrontmatter(text, label);
+    for (const target of localLinkTargets(text)) {
+      const destination = resolve(dirname(file), target);
+      if (!existsSync(destination) && !virtualPaths.has(normalize(relative(root, destination)))) fail(`Link ausente: ${label} -> ${target}`);
+    }
+  }
+}
+
+export function resourcePaths(text) {
+  const result = new Set();
+  for (const match of text.matchAll(/(?<![\w/.-])\.pbai4devs\/(?:scripts|tools|commands|templates)\/[^\s`'"\[\])]+/g)) {
+    let path = match[0].replace(/[.,;:]+$/, '');
+    if (/[<>{}$*]/.test(path) || path.split('/').includes('...')) continue;
+    try { path = decodeURIComponent(path.split(/[?#]/)[0]); } catch { fail(`Referencia com codificacao invalida: ${path}`); }
+    if (path.split('/').some(part => ['.local', '.cache', 'node_modules'].includes(part)) || /^\.pbai4devs\/tools\/(?:bin|npm-cache)(?:\/|$)/.test(path)) continue;
+    result.add(path.replace(/\/$/, ''));
+  }
+  return [...result].sort();
+}
+
+export function checkResourceReferences(root, files) {
+  for (const file of files) for (const path of resourcePaths(readFileSync(file, 'utf8'))) {
+    const location = resolve(root, path); const child = relative(root, location);
+    if (isAbsolute(child) || child === '..' || child.startsWith(`..${sep}`) || path.split('/').some(part => part === '..')) fail(`Referencia fora do projeto: ${path}`);
+    let current = root;
+    for (const part of child.split(sep)) { current = join(current, part); if (!checkedStat(root, current)) fail(`Recurso ausente: ${normalize(relative(root, file))} -> ${path}`); }
+    if (/\.(?:mjs|cjs|js|md|mdc|json)$/.test(path) && !checkedStat(root, location).isFile()) fail(`Recurso deve ser arquivo: ${path}`);
+  }
+}
+
+export function checkCatalog(root, build = buildCatalog) {
+  const result = build(root);
+  for (const [path, expected] of result.outputs) {
+    const file = resolve(root, path); const child = relative(root, file);
+    if (isAbsolute(child) || child === '..' || child.startsWith(`..${sep}`)) fail(`Saida de catalogo fora do projeto: ${path}`);
+    if (!checkedStat(root, file)?.isFile() || readFileSync(file, 'utf8') !== expected) fail(`Catalogo divergente: ${path}; execute sincronizar-agentes.`);
+  }
+  return result.catalog;
+}
+
+export function checkAgentExtras(root, agents) {
+  for (const agent of agents) {
+    for (const name of auxiliary) if (existsSync(join(root, agent, name))) fail(`Auxiliar indevido em ${agent}/${name}`);
+    const files = new Set();
+    walk(root, join(root, agent), files);
+    if ([...files].some(file => ['README.md', 'INSTRUCTIONS.md'].includes(basename(file)))) fail(`Guia indevido em ${agent}`);
+  }
+}
+
+export function checkSynchronization(root, run = spawnSync) {
+  const result = run(process.execPath, [join(root, '.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs'), '--check'], { cwd: root, encoding: 'utf8', timeout: 60000 });
+  if (result.error) throw result.error;
+  if (result.status !== 0) fail(result.stderr?.trim() || result.stdout?.trim() || 'Espelhos divergentes.');
+}
+
+export function checkLint(root, files, run = spawnSync) {
+  const current = join(root, '.pbai4devs/tools/markdownlint-cli2/.local/CURRENT.json');
+  const legacy = join(root, '.pbai4devs/tools/markdownlint-cli2/CURRENT.json');
+  if (!existsSync(current) && !existsSync(legacy)) return ['markdownlint-cli2=missing; verificacao nativa de estrutura e links executada.'];
+  const script = join(root, '.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs');
+  const result = run(process.execPath, [script, 'run', 'markdownlint-cli2', ...files], { cwd: root, encoding: 'utf8', timeout: 60000 });
+  if (result.error) throw result.error;
+  const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+  if (result.status !== 0) fail(output.split('\n').filter(line => !line.startsWith('Finding:')).join('\n') || 'Markdown lint falhou.');
+  return output.split('\n').filter(line => /^(?:Linting:|Summary:)/.test(line));
+}
+
+export function verifyResources({ root = projectRoot, sourceOnly = false, synchronize = checkSynchronization, lint = checkLint, catalogCheck = checkCatalog } = {}) {
+  requireNode();
+  const built = sourceOnly ? buildCatalog(root) : null;
+  if (!sourceOnly) { synchronize(root); catalogCheck(root); }
+  const registry = sourceOnly ? { agents: [], paths: [] } : registryRoots(root);
+  const files = collectMarkdown(root, registry);
+  const virtualPaths = new Set(sourceOnly ? [...built.outputs.keys(), '.pbai4devs/espelhos.conf'] : []);
+  checkMarkdown(root, files, { virtualPaths });
+  checkResourceReferences(root, files);
+  checkAgentExtras(root, registry.agents);
+  return { files, messages: [...lint(root, files), 'recursos=passed'] };
+}
+
+export function main(args = process.argv.slice(2), options = {}) {
+  requireNode();
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) { console.log('Uso: node .pbai4devs/scripts/verificar-recursos/SCRIPT.mjs [--source-only]'); return 0; }
+  if (args.length && !(args.length === 1 && args[0] === '--source-only')) fail('Opcao invalida; use --help.');
+  if (args.includes('--source-only')) options = { ...options, sourceOnly: true };
+  for (const message of verifyResources(options).messages) console.log(message);
+  return 0;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = main(); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/.pbai4devs/scripts/verificar-recursos/tests/TEST.mjs

@@ -0,0 +1,310 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+import { checkFrontmatter, checkLint, checkSynchronization, checkCatalog, checkResourceReferences, collectMarkdown, localLinkTargets, registryRoots, resourcePaths, verifyResources } from '../SCRIPT.mjs';
+import { buildCatalog } from '../../lib/catalog.mjs';
+import { platformKey, toolWrapper } from '../../preparar-ferramentas/SCRIPT.mjs';
+import './ambiente-local.mjs';
+import { mergeGitignore, planLocalIgnore, applyLocalIgnore } from '../../lib/gitignore.mjs';
+
+requireNode();
+const markdown = '# Exemplo\n';
+const document = body => `---\ndescription: Fixture.\n---\n\n${body}`;
+function fixture(t, prefix = 'verificar-recursos-') {
+  const home = join(projectRoot, '.agent-tests');
+  mkdirSync(home, { recursive: true });
+  const root = mkdtempSync(join(home, prefix));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const file = (name, content = document(markdown)) => {
+    const path = join(root, name);
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, content);
+    return path;
+  };
+  return { root, file };
+}
+function resourceFixture(t) {
+  const context = fixture(t);
+  context.file('.pbai4devs/espelhos.conf', 'agente|.codex|plano\n');
+  context.file('.pbai4devs/skills/README.md');
+  context.file('.pbai4devs/skills/exemplo/SKILL.md');
+  context.file('.pbai4devs/tools/README.md');
+  context.file('.pbai4devs/tools/demo/TOOL.json', JSON.stringify({ name: 'demo', description: 'CLI de prova.', group: 'base', source: 'https://github.com/owner/demo', download: { provider: 'npm', package: 'demo', registry: 'https://registry.npmjs.org/', repository: 'owner/demo', channel: 'latest' }, platforms: [platformKey()], scripts: { entry: 'SCRIPT.mjs' }, probe: ['--version'] }));
+  context.file('.pbai4devs/tools/demo/SCRIPT.mjs', toolWrapper('demo'));
+  context.file('.pbai4devs/tools/demo/README.md');
+  context.file('.codex/skills/exemplo/SKILL.md', document('# Exemplo\n\n[Origem](../../../.pbai4devs/skills/exemplo/SKILL.md)\n'));
+  return context;
+}
+const verify = root => verifyResources({ root, synchronize() {}, catalogCheck() {}, lint: () => ['lint=fixture'] });
+
+function writeCatalog(root) {
+  for (const [path, content] of buildCatalog(root).outputs) { mkdirSync(join(root, path, '..'), { recursive: true }); writeFileSync(join(root, path), content); }
+}
+
+test('confere recursos sem percorrer downloads ou modificar a fixture', t => {
+  const { root, file } = resourceFixture(t);
+  file('.pbai4devs/tools/demo/.local/versions/package/README.md', 'invalido');
+  file('.pbai4devs/tools/bin/README.md', 'invalido');
+  file('.pbai4devs/tools/.cache/README.md', 'invalido');
+  file('.pbai4devs/tools/npm-cache/README.md', 'invalido');
+  const before = readdirSync(root, { recursive: true });
+  const result = verify(root);
+  assert.deepEqual(result.messages, ['lint=fixture', 'recursos=passed']);
+  assert.ok(result.files.includes(join(root, '.pbai4devs/tools/demo/README.md')));
+  assert.ok(!result.files.some(path => path.includes('.local')));
+  assert.deepEqual(readdirSync(root, { recursive: true }), before);
+});
+
+test('ignora resultados locais em qualquer caixa e ainda verifica fixtures comuns', t => {
+  const { root, file } = resourceFixture(t);
+  for (const path of ['.pbai4devs/TmP/invalid.md', '.pbai4devs/skills/exemplo/.PLAYWRIGHT-MCP/invalid.md', '.pbai4devs/skills/exemplo/playwright-report/invalid.md', '.pbai4devs/skills/exemplo/TEST-RESULTS/invalid.md', '.codex/skills/exemplo/.agent-tests/invalid.md']) file(path, '# Resultado sem frontmatter\n');
+  const kept = file('.pbai4devs/skills/exemplo/fixtures/cache/input.md');
+  assert.ok(verify(root).files.includes(kept));
+  file('.pbai4devs/skills/exemplo/fixtures/cache/input.md', '# Fixture invalida\n');
+  assert.throws(() => verify(root), /fixtures\/cache\/input.md/);
+});
+
+test('verifica Markdown de todas as pastas padrão e documentos da raiz', t => {
+  const { root, file } = resourceFixture(t);
+  const sources = ['src/README.md', 'bin/README.md', 'tests/README.md', 'scripts/release/README.md',
+    'examples/README.md', 'CHANGELOG.md', 'CONTRIBUTING.md', 'GUIDE.MD',
+    '.github/PULL_REQUEST_TEMPLATE.md', '.github/ISSUE_TEMPLATE/question.md'];
+  for (const source of sources) file(source);
+  const collected = verify(root).files;
+  for (const source of sources) {
+    assert.ok(collected.includes(join(root, source)), source);
+    file(source, '# Sem frontmatter\n');
+    assert.throws(() => verify(root), /Frontmatter\/H1 invalido/);
+    file(source);
+  }
+});
+
+test('coleta source-only ignora exemplos gerados e clientes, sem exigir Git', t => {
+  const { root, file } = resourceFixture(t);
+  const guide = file('examples/README.md');
+  file('examples/generated/README.md', '# Resultado inválido\n');
+  file('examples/generated/demo/.pbai4devs/README.md', '# Cópia inválida\n');
+  file('src/node_modules/dependency/README.md', '# Download inválido\n');
+  file('scripts/TEST-RESULTS/README.md', '# Resultado inválido\n');
+  file('.github/skills/generated/SKILL.md', '# Cliente inválido\n');
+  file('.codex/skills/generated/SKILL.md', '# Cliente inválido\n');
+  const result = verifyResources({ root, sourceOnly: true, lint: () => ['lint=fixture'] });
+  assert.ok(result.files.includes(guide));
+  for (const path of result.files) assert.doesNotMatch(relative(root, path), /examples[\\/]generated|node_modules|TEST-RESULTS|\.github[\\/]skills|\.codex/);
+});
+
+test('catalogo derivado cobre recursos e detecta JSON editado sem reescrever', t => {
+  const { root, file } = resourceFixture(t);
+  file('.pbai4devs/commands/inspecionar/COMMAND.md', document('# Inspecionar\n\n[Script](../../scripts/inspecionar/SCRIPT.mjs).\n'));
+  file('.pbai4devs/scripts/README.md'); file('.pbai4devs/scripts/inspecionar/README.md');
+  file('.pbai4devs/scripts/inspecionar/SCRIPT.mjs', 'export {};\n');
+  file('.pbai4devs/templates/README.md'); file('.pbai4devs/templates/exemplo/TEMPLATE.md');
+  file('.pbai4devs/tools/demo/.local/versions/upstream/README.md', 'nao verificar');
+  writeCatalog(root);
+  const catalog = checkCatalog(root);
+  assert.equal(catalog.commands[0].id, 'inspecionar'); assert.equal(catalog.scripts[0].id, 'inspecionar');
+  assert.equal(catalog.templates[0].id, 'exemplo'); assert.equal(catalog.tools[0].name, 'demo');
+  assert.ok(!JSON.stringify(catalog).includes('upstream'));
+  const path = join(root, '.pbai4devs/catalog.json'); writeFileSync(path, '{"editado":true}\n');
+  assert.throws(() => checkCatalog(root), /Catalogo divergente/);
+  assert.equal(readFileSync(path, 'utf8'), '{"editado":true}\n');
+  writeCatalog(root);
+  const native = join(root, '.pbai4devs/skills.json'); writeFileSync(native, '{"entries":[]}\n');
+  assert.throws(() => checkCatalog(root), /skills.json/);
+});
+
+test('catalogo recusa TOOL incompleto, ponte ausente e referencia de comando quebrada', t => {
+  const { root, file } = resourceFixture(t); writeCatalog(root);
+  rmSync(join(root, '.pbai4devs/tools/demo/SCRIPT.mjs'));
+  assert.throws(() => checkCatalog(root), /Script ausente/);
+  file('.pbai4devs/tools/demo/SCRIPT.mjs', toolWrapper('demo'));
+  file('.pbai4devs/tools/demo/TOOL.json', '{}'); assert.throws(() => checkCatalog(root), /Nome/);
+  rmSync(join(root, '.pbai4devs/tools/demo'), { recursive: true });
+  file('.pbai4devs/commands/quebrado/COMMAND.md', document('# Quebrado\n\n[Script](../../scripts/ausente/SCRIPT.mjs).\n'));
+  assert.throws(() => checkCatalog(root), /Referencia ausente/);
+});
+
+test('caminhos concretos em comandos e exemplos apontam para arquivos reais', t => {
+  const { root, file } = resourceFixture(t);
+  file('.pbai4devs/scripts/tarefa/SCRIPT.mjs', 'export {};\n');
+  const command = file('.pbai4devs/commands/tarefa/COMMAND.md', document('# Tarefa\n\n```console\nnode .pbai4devs/scripts/tarefa/SCRIPT.mjs check\n```\n\nModelo: `.pbai4devs/templates/<nome>/TEMPLATE.md`.\n'));
+  checkResourceReferences(root, [command]);
+  assert.deepEqual(resourcePaths('`.pbai4devs/tools/demo/.local/CURRENT.json` e `.pbai4devs/tools/bin/demo.mjs`'), []);
+  assert.deepEqual(resourcePaths('`node .pbai4devs/scripts/tarefa/SCRIPT.mjs`'), ['.pbai4devs/scripts/tarefa/SCRIPT.mjs']);
+  rmSync(join(root, '.pbai4devs/scripts/tarefa/SCRIPT.mjs'));
+  assert.throws(() => checkResourceReferences(root, [command]), /Recurso ausente/);
+});
+
+test('external-skills mantém seu guia validado e só oculta o payload .local', t => {
+  const { root, file } = resourceFixture(t);
+  const guide = file('.pbai4devs/external-skills/README.md');
+  file('.pbai4devs/external-skills/CATALOG.json', '{"entries":[]}');
+  for (let index = 0; index < 80; index++) file(`.pbai4devs/external-skills/.local/upstream-${index}/SKILL.md`, '# Upstream sem frontmatter\n');
+  const result = verify(root);
+  assert.ok(result.files.includes(guide));
+  assert.ok(!result.files.some(path => /external-skills[\\/]\.local/.test(path)));
+  file('.pbai4devs/external-skills/README.md', '# Guia sem frontmatter\n');
+  assert.throws(() => verify(root), /Frontmatter\/H1 invalido: .pbai4devs\/external-skills\/README.md/);
+  file('.pbai4devs/external-skills/README.md');
+  file('.pbai4devs/external-skills/notes/guia.md', '# Documento externo ao payload\n');
+  assert.throws(() => verify(root), /Frontmatter\/H1 invalido: .pbai4devs\/external-skills\/notes\/guia.md/);
+  rmSync(join(root, '.pbai4devs/external-skills/notes'), { recursive: true });
+  file('.pbai4devs/skills/.local/guia.md', '# Este .local continua sendo verificado\n');
+  assert.throws(() => verify(root), /Frontmatter\/H1 invalido: .pbai4devs\/skills\/.local\/guia.md/);
+});
+
+test('external-skills é auxiliar proibido nas pastas dos agentes', t => {
+  const { root, file } = resourceFixture(t);
+  file('.codex/external-skills/CATALOG.json', '{"entries":[]}');
+  assert.throws(() => verify(root), /Auxiliar indevido em .codex\/external-skills/);
+});
+
+const symlinkCases = [
+  ['README.md', 'file', false],
+  ['.pbai4devs', 'dir', true],
+  ['.pbai4devs/espelhos.conf', 'file', true],
+  ['.pbai4devs/espelhos.conf', 'file', false],
+  ['.pbai4devs/tools', 'dir', true],
+  ['.pbai4devs/tools', 'dir', false],
+  ['.pbai4devs/tools/demo', 'dir', true],
+  ['.pbai4devs/tools/demo', 'dir', false],
+  ['.pbai4devs/tools/demo/README.md', 'file', false],
+  ['.pbai4devs/tools/demo/TOOL.json', 'file', false],
+  ['.pbai4devs/external-skills/.local', 'dir', true],
+  ['.pbai4devs/external-skills/.local', 'dir', false],
+];
+for (const [name, type, targetExists] of symlinkCases) {
+  test(`rejeita link ${targetExists ? 'existente' : 'quebrado'} em ${name} antes de ler o destino`, t => {
+    const { root, file } = resourceFixture(t);
+    if (name.startsWith('.pbai4devs/external-skills/')) file('.pbai4devs/external-skills/README.md');
+    const target = join(root, 'payload', type === 'dir' ? 'directory' : 'file');
+    if (targetExists) {
+      if (type === 'dir') { file('payload/directory/README.md', 'payload invalido'); file('payload/directory/espelhos.conf', 'payload invalido'); }
+      else file('payload/file', 'payload invalido');
+    }
+    const link = join(root, name);
+    rmSync(link, { recursive: true, force: true });
+    try { symlinkSync(target, link, process.platform === 'win32' && type === 'dir' ? 'junction' : type); }
+    catch (error) {
+      if (process.platform === 'win32' && ['EPERM', 'EACCES'].includes(error.code)) { t.skip('Sem permissão para criar este link no Windows.'); return; }
+      throw error;
+    }
+    assert.throws(() => verify(root), error => error.message === `Link simbolico: ${name}`);
+  });
+}
+
+test('frontmatter e primeiro conteúdo H1 são obrigatórios', () => {
+  checkFrontmatter(document('# Correto\n'), 'ok.md');
+  checkFrontmatter(document('# Correto\r\n'), 'ok.mdc');
+  for (const text of ['# Sem YAML\n', '---\ndescription: aberto\n# H1\n', document('Texto\n# Tarde\n'), document('## H2\n')]) {
+    assert.throws(() => checkFrontmatter(text, 'erro.md'), /Frontmatter\/H1 invalido/);
+  }
+});
+
+test('valida links locais inline, referências e nomes codificados', t => {
+  const { root, file } = resourceFixture(t);
+  file('docs/target name.md');
+  const guide = file('README.md', document('# Links\n\n[Local](docs/target%20name.md#titulo)\n[Outro][target]\n[Web](https://example.com)\n[Email](mailto:teste@example.com)\n[Âncora](#titulo)\n\n[target]: <docs/target name.md>\n\n```md\n[Exemplo](nao-existe.md)\n```\n'));
+  verify(root);
+  file('README.md', document('# Falha\n\n[Local](missing.md)\n'));
+  assert.throws(() => verify(root), /Link ausente: README.md -> missing.md/);
+  writeFileSync(guide, document('# Falha\n\n[Local][ref]\n\n[ref]: missing.md\n'));
+  assert.throws(() => verify(root), /Link ausente/);
+  assert.throws(() => localLinkTargets('[Local](invalid%Q0.md)'), /codificacao invalida/);
+});
+
+test('inclui mdc e documentos registrados no catálogo', t => {
+  const { root, file } = resourceFixture(t);
+  file('.pbai4devs/espelhos.conf', 'agente|.codex|plano\ndocumento|EXTRA.md|AGENTS.md\n');
+  file('EXTRA.md');
+  file('.codex/rules/exemplo.mdc', document('## H2 invalido\n'));
+  assert.throws(() => verify(root), /Frontmatter\/H1 invalido: .codex\/rules\/exemplo.mdc/);
+  file('.codex/rules/exemplo.mdc');
+  assert.ok(collectMarkdown(root).includes(join(root, 'EXTRA.md')));
+});
+
+test('exige guias da origem e impede auxiliares nos espelhos', t => {
+  const { root, file } = resourceFixture(t);
+  rmSync(join(root, '.pbai4devs/tools/demo/README.md'));
+  assert.throws(() => verify(root), /README ausente: .pbai4devs\/tools\/demo/);
+  file('.pbai4devs/tools/demo/README.md');
+  file('.codex/README.md');
+  assert.throws(() => verify(root), /Guia indevido em .codex/);
+  rmSync(join(root, '.codex/README.md'));
+  file('.codex/tools/tool.json', '{}');
+  assert.throws(() => verify(root), /Auxiliar indevido em .codex\/tools/);
+});
+
+test('chama sincronizador e linter pelo Node atual, sem wrappers shell', t => {
+  const { root, file } = resourceFixture(t);
+  const calls = [];
+  const run = (...args) => { calls.push(args); return { status: 0, stdout: 'Finding: fixture\nLinting: 2 files\nSummary: 0 error(s)\n', stderr: '' }; };
+  checkSynchronization(root, run);
+  assert.equal(calls[0][0], process.execPath);
+  assert.deepEqual(calls[0][1], [join(root, '.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs'), '--check']);
+  assert.match(checkLint(root, [], run)[0], /markdownlint-cli2=missing/);
+  file('.pbai4devs/tools/markdownlint-cli2/.local/CURRENT.json', '{}');
+  const files = [join(root, 'README.md')];
+  assert.deepEqual(checkLint(root, files, run), ['Linting: 2 files', 'Summary: 0 error(s)']);
+  assert.equal(calls[1][0], process.execPath);
+  assert.deepEqual(calls[1][1], [join(root, '.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs'), 'run', 'markdownlint-cli2', ...files]);
+  assert.throws(() => checkSynchronization(root, () => ({ status: 1, stderr: 'espelhos divergentes' })), /espelhos divergentes/);
+  assert.throws(() => checkLint(root, files, () => ({ status: 1, stdout: 'Finding: fixture\nREADME.md: MD041' })), /README.md: MD041/);
+});
+
+
+function git(root, args, input) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', input });
+  if (result.error) throw result.error;
+  return result;
+}
+function ignoredPaths(root, paths) {
+  const result = git(root, ['check-ignore', '--no-index', '--stdin', '-z'], paths.join('\0') + '\0');
+  assert.ok([0, 1].includes(result.status), result.stderr);
+  return result.stdout.split('\0').filter(Boolean);
+}
+function ignoreFixture(t) {
+  const context = fixture(t, 'local-source-ignore-');
+  assert.equal(git(context.root, ['init', '-q']).status, 0);
+  for (const name of ['local.ignore', 'shared.ignore', 'agents.ignore']) context.file('.pbai4devs/templates/gitignore/' + name, readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore/' + name), 'utf8'));
+  context.file('.pbai4devs/.gitignore', mergeGitignore('', readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore/shared.ignore'), 'utf8')).text);
+  for (const root of ['.github', '.vscode']) context.file(root + '/.gitignore', mergeGitignore('', readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore/agents.ignore'), 'utf8')).text);
+  return context;
+}
+
+test('fontes novas permanecem elegíveis e derivados locais ficam fora do índice', t => {
+  const { root, file } = ignoreFixture(t);
+  const outputs = ['.github/skills/generated/SKILL.md', '.vscode/.gitignore', '.github/.gitignore'];
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
+  const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs', '.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
+  const generated = [...outputs, '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf', '.pbai4devs/estado/agentdevkit.json'];
+  for (const path of [...sources, ...generated]) file(path, 'fixture\n');
+  assert.deepEqual(ignoredPaths(root, sources), []);
+  assert.deepEqual(new Set(ignoredPaths(root, generated)), new Set(generated));
+  assert.equal(git(root, ['add', '--all']).status, 0);
+  const tracked = git(root, ['ls-files', '-z']).stdout.split('\0');
+  for (const path of sources) assert.ok(tracked.includes(path), path);
+  for (const path of generated) assert.equal(tracked.includes(path), false, path);
+});
+
+test('ignores locais cobrem resultados em qualquer caixa sem bloquear fixtures', t => {
+  const { root } = ignoreFixture(t);
+  const ignored = ['.pbai4devs/.PLAYWRIGHT-MCP/session.json', '.pbai4devs/tests/TestResults/report.xml', '.github/skills/demo/.env', '.github/skills/demo/NoDe_MoDuLeS/dep.js', '.vscode/logs/session.log'];
+  assert.deepEqual(new Set(ignoredPaths(root, ignored)), new Set(ignored));
+  assert.deepEqual(ignoredPaths(root, ['.pbai4devs/tests/fixtures/cache/input.json', '.github/skills/demo/.env.development.example', '.vscode/new-config.json']), []);
+});
+
+test('validação source-only não exige catálogo, manifesto ou adaptadores gerados', t => {
+  const { root, file } = resourceFixture(t);
+  rmSync(join(root, '.pbai4devs/espelhos.conf'));
+  file('.pbai4devs/README.md', document('# Origem\n\n[Índice](catalog.json)\n'));
+  const before = readdirSync(root, { recursive: true }).sort();
+  const result = verifyResources({ root, sourceOnly: true, synchronize() { throw new Error('Não sincronizar fontes'); }, lint: () => ['lint=fixture'] });
+  assert.ok(result.files.includes(join(root, '.pbai4devs/README.md')));
+  assert.deepEqual(readdirSync(root, { recursive: true }).sort(), before);
+  file('.pbai4devs/README.md', document('# Origem\n\n[Erro](not-a-generated-file.json)\n'));
+  assert.throws(() => verifyResources({ root, sourceOnly: true, lint: () => [] }), /Link ausente/);
+});

package/.pbai4devs/scripts/verificar-recursos/tests/ambiente-local.mjs

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { projectRoot } from '../../lib/runtime.mjs';
+
+const templates = join(projectRoot, '.pbai4devs/templates/ambiente-local');
+function fixture(t) {
+  const home = join(projectRoot, '.agent-tests');
+  mkdirSync(home, { recursive: true });
+  const root = mkdtempSync(join(home, 'ambiente-local-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  copyFileSync(join(templates, 'Makefile.template'), join(root, 'Makefile'));
+  copyFileSync(join(templates, 'compose.local.yml.template'), join(root, 'compose.local.yml'));
+  return root;
+}
+
+test('modelos exigem comandos reais e configuração local explícita', () => {
+  const makefile = readFileSync(join(templates, 'Makefile.template'), 'utf8');
+  const setup = makefile.slice(makefile.indexOf('\nsetup:'), makefile.indexOf('\nup:'));
+  assert.ok(setup.indexOf('$(SETUP_COMMAND)') < setup.indexOf('$(DOCTOR_COMMANDS)'));
+  for (const command of ['SETUP_COMMAND', 'BUILD_COMMAND', 'TEST_COMMAND', 'LINT_COMMAND']) {
+    assert.ok(makefile.includes(`$(if $(strip $(${command})),,$(error Defina ${command}`));
+  }
+  assert.match(makefile, /docker version\r?\ndocker compose version\r?\n\$\(COMPOSE\) config --quiet/);
+  const compose = readFileSync(join(templates, 'compose.local.yml.template'), 'utf8');
+  for (const name of ['COMPOSE_PROJECT_NAME', 'APP_IMAGE', 'APP_PORT', 'APP_CONTAINER_PORT', 'APP_HEALTHCHECK']) assert.ok(compose.includes(`\${${name}:?`));
+  assert.ok(compose.includes('127.0.0.1:'));
+  assert.ok(compose.includes('healthcheck:'));
+});
+
+test('Makefile prepara o ambiente antes de validar e propaga falhas', t => {
+  if (process.platform === 'win32') { t.skip('Fixture de Make opcional para POSIX; contrato validado em Node em todos os sistemas.'); return; }
+  const available = spawnSync('make', ['--version'], { encoding: 'utf8' });
+  if (available.error || available.status !== 0) { t.skip('make ausente; contrato do modelo validado em Node.'); return; }
+  const root = fixture(t);
+  const log = join(root, 'order.log');
+  const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
+  const node = quote(process.execPath);
+  const stub = join(root, 'docker-stub.mjs');
+  const setup = join(root, 'setup.mjs');
+  const failure = join(root, 'failure.mjs');
+  writeFileSync(stub, `import { appendFileSync, existsSync } from 'node:fs';\nconst command = process.argv.slice(2).join(' ');\nappendFileSync(process.env.AGENT_TEMPLATE_ORDER, command + '\\n');\nif (!['version', 'compose version', 'compose -f compose.local.yml config --quiet'].includes(command)) process.exit(99);\nif (command.endsWith('config --quiet') && !existsSync('.env')) process.exit(1);\n`);
+  writeFileSync(setup, `import { appendFileSync, copyFileSync } from 'node:fs';\nappendFileSync(process.env.AGENT_TEMPLATE_ORDER, 'setup\\n');\ncopyFileSync('.env.example', '.env');\n`);
+  writeFileSync(failure, 'process.exit(7);\n');
+  writeFileSync(join(root, '.env.example'), 'FIXTURE_ENV=ready\n');
+  writeFileSync(join(root, 'fixture.mk'), `include Makefile\ndefine DOCTOR_COMMANDS\n${node} ${quote(stub)} version\n${node} ${quote(stub)} compose version\n${node} ${quote(stub)} compose -f compose.local.yml config --quiet\nendef\n`);
+  const run = args => spawnSync('make', ['-f', 'fixture.mk', ...args], { cwd: root, encoding: 'utf8', env: { ...process.env, AGENT_TEMPLATE_ORDER: log } });
+  const result = run(['setup', `SETUP_COMMAND=${node} ${quote(setup)}`]);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.ok(existsSync(join(root, '.env')));
+  assert.deepEqual(readFileSync(log, 'utf8').trim().split('\n'), ['setup', 'version', 'compose version', 'compose -f compose.local.yml config --quiet']);
+  for (const [target, variable] of [['setup', 'SETUP_COMMAND'], ['build', 'BUILD_COMMAND'], ['test', 'TEST_COMMAND'], ['lint', 'LINT_COMMAND']]) {
+    writeFileSync(log, '');
+    const missing = run([target]);
+    assert.notEqual(missing.status, 0);
+    assert.match(missing.stderr, new RegExp(variable));
+    assert.equal(readFileSync(log, 'utf8'), '');
+    const failed = run([target, `${variable}=${node} ${quote(failure)}`]);
+    assert.notEqual(failed.status, 0);
+    assert.equal(readFileSync(log, 'utf8'), '');
+  }
+});
+
+test('Compose aceita valores explícitos e rejeita configuração incompleta', t => {
+  const available = spawnSync('docker', ['compose', 'version'], { encoding: 'utf8' });
+  if (available.error || available.status !== 0) { t.skip('Docker Compose CLI ausente; nenhum daemon é necessário.'); return; }
+  const root = fixture(t);
+  const empty = join(root, 'empty.env');
+  writeFileSync(empty, '');
+  const env = { ...process.env };
+  for (const name of ['COMPOSE_PROJECT_NAME', 'APP_IMAGE', 'APP_PORT', 'APP_CONTAINER_PORT', 'APP_HEALTHCHECK']) delete env[name];
+  const args = ['compose', '--env-file', empty, '-f', join(root, 'compose.local.yml'), 'config', '--quiet'];
+  const valid = spawnSync('docker', args, { cwd: root, encoding: 'utf8', env: { ...env, COMPOSE_PROJECT_NAME: 'agents-template-check', APP_IMAGE: 'example/app:1.0', APP_PORT: '39001', APP_CONTAINER_PORT: '3000', APP_HEALTHCHECK: 'test -f /tmp/ready' } });
+  assert.equal(valid.status, 0, valid.stderr);
+  const missing = spawnSync('docker', args, { cwd: root, encoding: 'utf8', env });
+  assert.notEqual(missing.status, 0);
+  assert.match(missing.stderr, /COMPOSE_PROJECT_NAME|APP_IMAGE|APP_PORT|APP_CONTAINER_PORT|APP_HEALTHCHECK/);
+});

package/.pbai4devs/skills/README.md

@@ -0,0 +1,24 @@
+---
+description: Finalidade e criação de skills compartilhadas.
+---
+
+# Skills
+
+São procedimentos reutilizáveis, organizados em `git`, `projeto`, `produto` e
+`specs`. Cada skill usa `<grupo>/<nome>/SKILL.md` com nome e descrição no YAML.
+
+- `git`: operações de versionamento.
+- `projeto`: configuração, criação e manutenção dos recursos.
+- `produto`: PRD, experiência e design técnico.
+- `specs`: especificações, roadmap e implementação.
+
+Use `criar-skill` quando uma tarefa recorrente precisar de decisões próprias;
+use `criar-recurso` para encontrar um fluxo existente antes de criar outro.
+Mantenha instruções essenciais no arquivo e detalhes opcionais em referências.
+Use `usar-skills-externas` para referências curadas, `atualizar-documentacao`
+para manter os documentos e `revisar-entrega` para concluir implementações.
+Use [proximos-passos](projeto/proximos-passos/SKILL.md) para orientar a
+continuidade conforme a fase e as pendências reais.
+
+O [guia compartilhado](../INSTRUCTIONS.md) orienta o uso das skills.
+Ao alterar o inventário, sincronize os índices e apontamentos locais.

package/.pbai4devs/skills/git/git-branch/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: git-branch
+description: Cria, inspeciona ou troca branches Git.
+---
+
+# git-branch
+
+Confira branch atual, worktrees e alterações locais. Crie ou troque a branch
+solicitada sem sobrescrever ou descartar trabalho; siga o fluxo de specs em
+[implementar-spec](../../specs/implementar-spec/SKILL.md), incluindo a escolha
+da branch de base conforme o projeto existente.