OS Self-Test
Rode o script
node scripts/os-self-test.js
É a verificação inteira. Exit 0 = coerente, exit 1 = pelo menos um erro.
Isto era um checklist manual dentro deste arquivo, e esse era o problema. Verificação que depende de alguém lembrar não é verificação — três session-logs (2026-04-30, 2026-05-09, 2026-08-08) registram esta skill não sendo executada exatamente quando teria ajudado. Desde a v0.5.2 é script, e o CI roda em todo push e PR.
O que o script verifica
| Grupo |
Verifica |
| Estrutura canônica |
CLAUDE.md, START-HERE.md, WIZARD.md, README.md, CHANGELOG.md, LICENSE, .claude/{agents,rules,skills,commands}, e duplicata na raiz |
| Frontmatter |
toda skill tem name + description e o name bate com o diretório; todo agente e comando tem description |
| Links |
todo link relativo .md do repo resolve |
| Registry |
todo pack está no INDEX.md, e todo link do INDEX.md aponta pack existente |
| Session-log |
toda entrada datada está indexada |
| Hooks |
os hooks declarados em settings.json existem em disco, e todo hook em disco está declarado |
| Gitignore |
cobre .env, node_modules/, CLAUDE.local.md |
| Artefatos |
modo repo-do-OS versus projeto derivado, detectado pelo marcador .aios-self |
Dois modos
O script se adapta ao contexto:
- Repo do AI Dev OS (tem
.aios-self) — os artefatos de projeto (BUSINESS-PLAN.md, PRODUCT-BRIEF.md…) não devem existir; se existirem, avisa.
- Projeto derivado — os mesmos artefatos são esperados, e a ausência vira aviso e não erro, porque o wizard pode simplesmente não ter chegado naquela fase.
Seu trabalho quando falha
O script diz o que está quebrado. Interpretar e consertar continua sendo trabalho seu:
- Rode e leia os erros.
- Para cada um, decida se o certo é corrigir a referência ou remover o alvo — link quebrado às vezes significa que falta o arquivo, às vezes que sobra o link.
- Avisos (🟡) não bloqueiam, mas acumulam. Skill sem frase-gatilho na descrição é o caso típico: funciona, mas ninguém a invoca.
- Se consertar algo estrutural, registre no
session-log/.
Quando rodar além do CI
- Depois de renomear ou mover arquivo canônico.
- Depois de mergear uma pilha de PRs.
- Antes de abrir sprint ou cortar release — o
release-check já delega para cá.
- Quando o usuário desconfiar que alguma coisa quebrou.
Related
- Script:
scripts/os-self-test.js
- Testes dos scripts e hooks:
node --test scripts/test/*.test.js (sem aspas — o shell expande; aspas exigem Node 21+)
- Gate de release que o invoca:
release-check
1---2name: os-self-test3description: Verify the AI Dev Operating System is in a coherent state inside a project. Detects missing canonical files, broken cross-references, skills/agents/commands without frontmatter, registry drift, unindexed session logs, unwired hooks and gitignore gaps. Run after major edits to the OS, after renaming or moving canonical files, before opening a new sprint, before a release, and when the user says "tá tudo certo aqui?", "quebrou alguma coisa na estrutura?", "faz um check geral", "os links estão funcionando?".4---56# OS Self-Test78## Rode o script910```bash11node scripts/os-self-test.js12```1314É a verificação inteira. Exit `0` = coerente, exit `1` = pelo menos um erro.1516**Isto era um checklist manual dentro deste arquivo, e esse era o problema.** Verificação que depende de alguém lembrar não é verificação — três session-logs (`2026-04-30`, `2026-05-09`, `2026-08-08`) registram esta skill não sendo executada exatamente quando teria ajudado. Desde a v0.5.2 é script, e o CI roda em todo push e PR.1718## O que o script verifica1920| Grupo | Verifica |21|---|---|22| Estrutura canônica | `CLAUDE.md`, `START-HERE.md`, `WIZARD.md`, `README.md`, `CHANGELOG.md`, `LICENSE`, `.claude/{agents,rules,skills,commands}`, e duplicata na raiz |23| Frontmatter | toda skill tem `name` + `description` e o `name` bate com o diretório; todo agente e comando tem `description` |24| Links | todo link relativo `.md` do repo resolve |25| Registry | todo pack está no `INDEX.md`, e todo link do `INDEX.md` aponta pack existente |26| Session-log | toda entrada datada está indexada |27| Hooks | os hooks declarados em `settings.json` existem em disco, e todo hook em disco está declarado |28| Gitignore | cobre `.env`, `node_modules/`, `CLAUDE.local.md` |29| Artefatos | modo repo-do-OS *versus* projeto derivado, detectado pelo marcador `.aios-self` |3031## Dois modos3233O script se adapta ao contexto:3435- **Repo do AI Dev OS** (tem `.aios-self`) — os artefatos de projeto (`BUSINESS-PLAN.md`, `PRODUCT-BRIEF.md`…) **não** devem existir; se existirem, avisa.36- **Projeto derivado** — os mesmos artefatos são esperados, e a ausência vira aviso e não erro, porque o wizard pode simplesmente não ter chegado naquela fase.3738## Seu trabalho quando falha3940O script diz **o que** está quebrado. Interpretar e consertar continua sendo trabalho seu:41421. Rode e leia os erros.432. Para cada um, decida se o certo é corrigir a referência ou remover o alvo — link quebrado às vezes significa que falta o arquivo, às vezes que sobra o link.443. Avisos (🟡) não bloqueiam, mas acumulam. Skill sem frase-gatilho na descrição é o caso típico: funciona, mas ninguém a invoca.454. Se consertar algo estrutural, registre no `session-log/`.4647## Quando rodar além do CI4849- Depois de renomear ou mover arquivo canônico.50- Depois de mergear uma pilha de PRs.51- Antes de abrir sprint ou cortar release — o `release-check` já delega para cá.52- Quando o usuário desconfiar que alguma coisa quebrou.5354## Related5556- Script: `scripts/os-self-test.js`57- Testes dos scripts e hooks: `node --test scripts/test/*.test.js` (sem aspas — o shell expande; aspas exigem Node 21+)58- Gate de release que o invoca: [`release-check`](../release-check/SKILL.md)
lglucas