project-baseline
Um padrão de prontidão testável: 69 regras, cada uma apoiada por uma verificação que um runner Node sem dependências executa em um repositório em repouso. Bloqueadores falham a CI (exit 1); os julgamentos que um script não pode fazer são resolvidos por meio de um livro de assinaturas datado. O objetivo principal: não confie em uma promessa escrita — faça algo verificar isso.
O kit de ferramentas fica ao lado deste arquivo: check.mjs (runner), rules.json (as 69 regras), config.example.json, templates/, README.md (guia de início rápido), REFERENCE.md (referência completa: tabela de regras, categorias, diagramas de arquitetura, configuração de CI) e GLOSSARY.md (definições em linguagem clara dos termos de DevOps/cadeia de suprimentos).
Resolva o diretório do skill primeiro. $SKILL_DIR abaixo significa o caminho absoluto do diretório que contém este SKILL.md — resolva-o para um caminho concreto antes de executar qualquer comando (não passe a string literal $SKILL_DIR para o shell). Normalmente é ~/.claude/skills/baseline. check.mjs carrega rules.json do seu próprio diretório, então os dois devem permanecer juntos; sempre invoque o runner pelo seu caminho absoluto (node "<abs>/check.mjs" …) em vez de copiá-lo para outro lugar. O runner precisa apenas de Node ≥ 18 e git; se node estiver ausente, informe o usuário em vez de adivinhar.
Quando invocado
Descubra a intenção a partir das palavras do usuário e escolha um modo. Padrão para score se não especificado.
Modo: score (padrão) — "executar baseline", "/baseline", "verificar este repositório"
- Escolha o repositório alvo: um caminho explícito na solicitação, senão o diretório de trabalho atual. Confirme que parece um repositório (tem um manifesto ou
.git). - Execute o runner (legível para humanos):
node "$SKILL_DIR/check.mjs" --repo <alvo>- Adicione
--no-execse NÃO deve executar o comando de bootstrap/teste do repositório (BUILD-05) — por exemplo, repositório não confiável, sem tempo para executar testes, ou o comando não está configurado. Prefira executá-lo quando seguro, pois BUILD-05 é a verificação principal. - Adicione
--profile advancedse o usuário quiser as regras de especialista (SBOM, varredura de código, teste de mutação, integridade de símbolos, varredura de vulnerabilidades de dependências, piso de cobertura). O perfilserviceé ativado automaticamente paraproject_type=service. - Adicione
--jsonquando quiser analisar os resultados programaticamente em vez de mostrar o scorecard.
- Adicione
- Apresente o resultado ao usuário, começando com bloqueadores (estes falham a CI), depois avisos que valem a pena corrigir. Agrupe por categoria. Não despeje todas as 69 linhas — resuma: % de prontidão, contagem de bloqueadores e as FALHAS/AVISOS notáveis específicos com seu detalhe de uma linha. Ofereça-se para corrigir ou estruturar.
Modo: init — "configurar baseline aqui", "adotar o padrão", "estruturar baseline"
- Copie o kit de ferramentas para o repositório (sugira
tools/baseline/), ou referencie-o no local. - Estruture os artefatos, apenas se ausentes (nunca sobrescreva sem perguntar):
cp "$SKILL_DIR/config.example.json" <repo>/baseline.config.json cp "$SKILL_DIR/templates/CLAIMS.json" <repo>/docs/CLAIMS.json # apenas se o repositório faz alegações externas cp "$SKILL_DIR/templates/start-here.md" <repo>/docs/start-here.md # se nenhum documento de status existir mkdir -p <repo>/.project-baseline && cp "$SKILL_DIR/templates/signoff.json" <repo>/.project-baseline/signoff.json - Edite
baseline.config.jsonpara a realidade do repositório: definaproject_type,bootstrap_command(o comando de instalação+teste em checkout limpo para BUILD-05) emakes_external_claims(false pula as regras CLAIM-*). As chaves opt-in*_globs(freshness/generated/grounding) permanecem vazias até que o repositório adote essas convenções. - Mostre a eles a configuração de CI do
README.mde torne o jobbaselineuma verificação obrigatória (essa é a regra BUILD-06). - Execute uma primeira avaliação.
Modo: fix — "corrigir as falhas do baseline", "deixar isso verde"
- Avalie primeiro. Para cada bloqueador/aviso que o usuário queira resolver, aplique o campo
fixda própria regra (leia derules.json) como edições concretas no repositório — adicione a LICENÇA ausente, fixe a ação em um SHA, adicione o.envao.gitignoree rotacione o segredo, adicione o teste negativo, etc. - Para regras
manual(assinatura), não finja uma verificação — ajude o usuário a fazer o julgamento (raio de explosão, passagem de arte anterior, cunha/moat) e registre uma entrada datada em.project-baseline/signoff.json. - Reavalie para confirmar.
Modo: explain — "o que SEC-03 verifica", "por que CTX-05 falhou"
Leia a regra de rules.json (cada uma tem title, rationale, fix, source e o check) e explique-a de forma simples, além do que o runner realmente procurou. Para jargões desconhecidos (SBOM, SLSA, proveniência, livro de assinaturas, …), GLOSSARY.md neste diretório tem definições em linguagem clara.
Como o runner decide (para que você possa interpretar linhas de detalhe)
- PASS / FAIL / WARN / SIGN-OFF / SKIP por regra. Apenas FALHAS
blockerdefinem código de saída 1. - SKIP significa que a regra não se aplicou:
project_typeerrado (n/a para <tipo>), um perfil desligado (perfil 'advanced' desligado), um recurso opt-in não adotado, ou nada a verificar. Um skip nunca conta contra a prontidão. - Perfis:
coresempre executa;serviceexecuta automaticamente quandoproject_type=service;advancedexecuta apenas com--profile advancedouprofiles:["advanced"]na configuração. - Alegações são opt-in: CLAIM-* só executa se um registro de alegações existir ou
makes_external_claims:trueestiver definido explicitamente. Um repositório sem registro de alegações não é penalizado. - A configuração detecta automaticamente de forma sensata;
baseline.config.jsonna raiz do repositório sobrescreve. As chaves estão documentadas emconfig.example.json. - O runner é sem dependências (Node ≥ 18 + git) e resiliente a falhas: uma regra cuja verificação não pode ser avaliada degrada para SKIP, nunca interrompendo a execução.
Notas
- Nunca apresente um aviso como um bloqueador ou vice-versa — a gravidade está em
rules.jsone na saída do runner. - Prefira executar BUILD-05 de verdade (omitindo
--no-exec) quando o repositório for confiável e o comando de bootstrap estiver definido — uma verificação principal verde é o sinal único mais forte. - A justificativa completa, tabela de regras, descrições de categorias, diagramas de arquitetura e trecho de CI estão no
REFERENCE.mddeste diretório — leia-o se o usuário quiser profundidade.