@kuyper/harness 0.1.0

package/docs/guia/01-comecar.md

@@ -0,0 +1,156 @@
+# Começar um projeto
+
+Esta é a jornada completa, do repositório vazio à primeira publicação. O
+Harness não instala TypeScript, ESLint ou Vitest: os passos abaixo fazem isso
+explicitamente antes do `init`.
+
+Antes de começar, configure sua identidade do Git e a autenticação SSH do
+GitHub. Estes comandos precisam imprimir seu nome e e-mail; se não imprimirem,
+configure-os com `git config --global user.name "Seu Nome"` e
+`git config --global user.email "voce@example.com"`:
+
+```bash
+git config --global user.name
+git config --global user.email
+```
+
+## 1. Criar e clonar o repositório
+
+No GitHub, crie um repositório **privado e vazio**, sem README, `.gitignore` ou
+licença. Troque os dois valores abaixo e execute:
+
+```bash
+export GITHUB_USER="seu-usuario"
+export PROJECT_NAME="seu-projeto"
+git clone "git@github.com:${GITHUB_USER}/${PROJECT_NAME}.git"
+cd "$PROJECT_NAME"
+git switch -c main
+```
+
+Um clone vazio pode avisar que não tem branch; `git switch -c main` é esperado.
+
+## 2. Criar o projeto TypeScript e os quatro gates
+
+Os comandos abaixo criam uma configuração mínima que realmente compila, passa
+no lint e aceita um projeto ainda sem testes:
+
+```bash
+pnpm init
+pnpm pkg set type=module
+pnpm add -D typescript@^5.9.3 eslint@^10.9.1 @eslint/js@^10.0.1 typescript-eslint@^8.68.0 vitest@^4.1.11
+
+cat > .gitignore <<'EOF'
+node_modules/
+dist/
+.DS_Store
+EOF
+
+cat > tsconfig.json <<'EOF'
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"]
+}
+EOF
+
+cat > eslint.config.js <<'EOF'
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  { ignores: ['dist/'] },
+);
+EOF
+
+mkdir -p src
+cat > src/index.ts <<'EOF'
+export function hello(name: string): string {
+  return `Olá, ${name}.`;
+}
+EOF
+
+pnpm pkg set scripts.typecheck="tsc --noEmit"
+pnpm pkg set scripts.lint="eslint ."
+pnpm pkg set scripts.test="vitest run --passWithNoTests"
+pnpm pkg set scripts.build="tsc"
+
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+O `--passWithNoTests` é deliberado: o gate existe desde o primeiro commit, antes
+de o primeiro teste existir.
+
+## 3. Instalar o Harness e criar o commit raiz
+
+```bash
+pnpm add -D @kuyper/harness
+pnpm exec kuyper --version
+git add -A
+git commit -m "chore: inicia projeto"
+git switch -c dev
+```
+
+O commit raiz precisa acontecer na `main`, antes dos hooks existirem. Todo
+trabalho posterior acontece na `dev`.
+
+## 4. Inicializar o Harness
+
+`init` é o único comando interativo. Ele pergunta nome, descrição e providers;
+pressionar Enter aceita os valores do `package.json` e ambos os providers. A
+quarta pergunta apenas confirma o plano.
+
+```bash
+pnpm exec kuyper init
+```
+
+Revise `.kuyper/`, `CLAUDE.md`, `AGENTS.md`, `.claude/skills/`,
+`.agents/skills/`, `.kuyper/hooks/` e a alteração de `package.json`. Então:
+
+```bash
+pnpm exec kuyper validate
+git add -A
+git commit -m "chore: inicializa Kuyper Harness"
+pnpm exec kuyper integrate
+pnpm exec kuyper publish
+```
+
+Ao final, `main` local e `origin/main` apontam para o merge criado pelo
+`integrate`, e o checkout volta para `dev`.
+
+## 5. Trabalhar depois do primeiro publish
+
+Faça alterações e commits na `dev`. Ao terminar cada tarefa:
+
+```bash
+pnpm exec kuyper integrate
+```
+
+Quando quiser publicar uma ou várias tarefas já integradas:
+
+```bash
+pnpm exec kuyper publish
+```
+
+Quando uma segunda versão do Harness existir na npm:
+
+```bash
+pnpm exec kuyper update
+git add -A
+git commit -m "chore: atualiza Kuyper Harness"
+```
+
+O MVP não certifica `update` no primeiro publish: ainda não existe uma segunda
+versão para `@latest` resolver. Essa prova fecha na primeira atualização real.

package/docs/guia/02-conceitos.md

@@ -0,0 +1,53 @@
+# Conceitos
+
+## Fonte canônica
+
+Tudo que você mantém vive em `.kuyper/` e é versionado. `core/` vem no pacote e
+só `update` o troca; `project/` é seu. Rules são instruções permanentes; skills
+são procedimentos chamados quando necessários. Nunca edite de volta uma saída
+de provider esperando que ela vire fonte.
+
+## Providers e materialização
+
+Claude e Codex são providers: formatos de destino derivados da mesma fonte.
+`generate` produz `CLAUDE.md`, `AGENTS.md`, skills e hooks de forma
+determinística. `generated.lock` registra as saídas conhecidas para distinguir
+uma mudança de fonte de uma edição manual na saída.
+
+Uma rule do projeto pode declarar `replaces: core:<nome>`; a original não é
+materializada. Uma skill substituta usa outro nome e declara `replaces: <nome>`;
+as duas continuam instaladas, mas a lista de roteamento recomenda a substituta.
+
+## Gates
+
+Gates são scripts do próprio projeto. A configuração inicial usa `typecheck` e
+`lint` no `pre-commit`, e os quatro (`typecheck`, `lint`, `test`, `build`) no
+`publish`. O Harness não instala nem interpreta essas ferramentas: executa os
+comandos declarados e exige que o resultado certificado seja o que será
+commitado ou enviado.
+
+## Fluxo Git
+
+`dev` é a branch de trabalho e `main` é a história publicável. `integrate` roda
+as verificações localmente e cria um merge `--no-ff` na `main`; `publish` envia
+a `main` para `origin`. Integrar é frequente e local. Publicar é deliberado e
+remoto.
+
+Os hooks recusam commit direto na `main` e verificam pushes da `main`. Eles não
+provam quem está no teclado: `--no-verify` é uma porta técnica disponível ao
+humano, e uma rule permanente proíbe a LLM de usá-la.
+
+## Autoridade
+
+O humano decide produto, pode atravessar qualquer barreira e tem a palavra
+final. A LLM deve seguir o caminho protegido, declarar discordância com motivo
+e alternativa antes de executar, e então cumprir integralmente a decisão do
+humano. Hooks, gates e rules reduzem risco num shell compartilhado; não são uma
+fronteira de segurança contra uma LLM que ignore instruções.
+
+## Estado compartilhado
+
+Descobertas úteis à próxima sessão pertencem ao projeto, não à memória privada
+de Claude ou Codex. Achado operacional vai para `.kuyper/STATE.md`; decisão
+técnica durável vai para um ADR do próprio projeto; mudança de valor ou
+comportamento volta ao Discovery ou PRD.

package/docs/guia/03-comandos.md

@@ -0,0 +1,65 @@
+# Referência de comandos
+
+Todos os comandos, exceto `init`, são não interativos. Todos recusam fora de um
+projeto inicializado. Use sempre `pnpm exec kuyper`.
+
+## `init`
+
+Confere Git, `package.json`, os quatro scripts e conflito de `core.hooksPath`;
+pergunta nome, descrição e providers; mostra o plano; depois cria `.kuyper/`,
+copia o core, materializa providers e hooks e acrescenta
+`"prepare": "pnpm exec kuyper generate"`. Não commita. Exige TTY.
+
+## `generate [--force]`
+
+Lê a fonte canônica, valida schemas, substituições, colisões, core e saídas;
+calcula todo o plano antes de escrever; materializa providers e hooks; grava o
+lock e aponta `core.hooksPath` para `.kuyper/hooks`. `--force` descarta apenas
+edições em saídas geradas; não autoriza core híbrido nem caminho ocupado.
+
+## `validate`
+
+Compara fonte, saídas, lock, hooks, `core.hooksPath` e script `prepare` sem
+escrever. Código `0`: coerente; `1`: inconclusivo; `2`: divergente.
+
+## `integrate`
+
+Exige árvore limpa, checkout em `dev`, `main` ancestral e commits novos. Roda
+`validate`, executa os gates `publish`, cria `git merge --no-ff dev` na `main`,
+volta à `dev` e faz fast-forward até o merge. Não acessa o remoto.
+
+## `publish`
+
+Exige árvore limpa e commits novos na `main`. Guarda a branch atual, muda para
+`main`, valida, roda gates `publish`, mostra o que será enviado, faz push de
+`main` para `origin` e volta à branch original. Não integra.
+
+## `update`
+
+Comprova árvore limpa e geração sem achados; instala
+`@kuyper/harness@latest`; relança o binário instalado; iguala toda a árvore
+`.kuyper/core/` ao pacote; verifica substituições aposentadas; gera, valida e
+relata a versão. Não faz rollback automático.
+
+## `rule`
+
+```bash
+pnpm exec kuyper rule create <nome> --from <arquivo|-> [--dry-run]
+pnpm exec kuyper rule edit <nome> [--from <arquivo|->] [--dry-run]
+pnpm exec kuyper rule delete <nome> [--dry-run]
+```
+
+Mexe apenas em `.kuyper/project/rules/<nome>.md` e chama `generate`. `edit` sem
+`--from` valida uma edição já feita no arquivo. `--from -` lê stdin.
+
+## `skill`
+
+```bash
+pnpm exec kuyper skill create <nome> --from <SKILL.md|-> [--dry-run]
+pnpm exec kuyper skill edit <nome> [--from <SKILL.md|->] [--dry-run]
+pnpm exec kuyper skill delete <nome> [--dry-run]
+```
+
+Mexe em `.kuyper/project/skills/<nome>/`. `edit --from` troca somente
+`SKILL.md` e preserva `scripts/`; `delete` remove a árvore canônica e deixa o
+`generate` remover saídas órfãs. Comandos de capacidade não alteram `core:`.

package/docs/guia/04-equivalentes-manuais.md

@@ -0,0 +1,135 @@
+# Equivalentes manuais
+
+Estas sequências tornam visível o que cada interface automatiza. Execute-as com
+a árvore limpa e pare diante de qualquer erro. Quando aparece
+`pnpm exec kuyper generate`, ele representa a materialização, a única operação
+sem equivalente em Git ou pnpm.
+
+## `init`
+
+1. Crie `.kuyper/config.yaml` com providers e gates.
+2. Copie `node_modules/@kuyper/harness/core/` inteiro para `.kuyper/core/`.
+3. Crie `.kuyper/project/rules/sobre-o-projeto.md`, substituindo `<nome>` e
+   `<descrição>`:
+
+```markdown
+---
+title: Sobre este projeto
+---
+
+`<nome>` — <descrição>.
+```
+
+Se não houver descrição, use apenas `` `<nome>`. `` no corpo.
+
+4. Crie `.kuyper/STATE.md` com `Atualizado por` e as seções `Onde parei`,
+   `O que descobri que não estava óbvio`, `Próximo passo concreto` e `Cuidado`.
+5. Declare `"prepare": "pnpm exec kuyper generate"` em `package.json`.
+6. Execute:
+
+```bash
+git config core.hooksPath .kuyper/hooks
+pnpm exec kuyper generate
+pnpm exec kuyper validate
+```
+
+## `generate`
+
+A materialização de fonte canônica para dois formatos, com reconciliação do
+lock, **não tem equivalente manual**. Essa é a capacidade própria do produto.
+O apontamento dos hooks tem:
+
+```bash
+git config core.hooksPath .kuyper/hooks
+```
+
+Ele não é versionado e desaparece num clone novo.
+
+## `validate`
+
+Calcule o resultado esperado da fonte e compare byte a byte todas as saídas,
+modos dos hooks e entradas do lock; confirme ainda:
+
+```bash
+test "$(git config --get core.hooksPath)" = ".kuyper/hooks"
+node -e "const p=require('./package.json'); process.exit(p.scripts?.prepare === 'pnpm exec kuyper generate' ? 0 : 1)"
+```
+
+Na prática essa comparação é justamente o trabalho que `validate` torna
+repetível.
+
+## `integrate`
+
+```bash
+git status --porcelain                  # tem de sair vazio
+git switch dev
+pnpm exec kuyper validate
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
+git merge-base --is-ancestor main dev
+test "$(git rev-parse main)" != "$(git rev-parse dev)"
+git switch main
+git merge --no-ff dev
+git switch dev
+git merge --ff-only main
+```
+
+## `publish`
+
+```bash
+git status --porcelain                  # tem de sair vazio
+ORIG=$(git branch --show-current)
+git switch main
+git log --oneline origin/main..main 2>/dev/null || git log --oneline
+pnpm exec kuyper validate
+pnpm typecheck && pnpm lint && pnpm test && pnpm build
+git push -u origin main
+git switch "$ORIG"
+```
+
+## `update`
+
+A ordem protege edições do core. Não mova a instalação antes das comprovações:
+
+```bash
+git status --porcelain                  # tem de sair vazio
+pnpm exec kuyper generate
+git status --porcelain                  # tem de continuar vazio
+pnpm add -D @kuyper/harness@latest
+rm -rf .kuyper/core
+cp -R node_modules/@kuyper/harness/core .kuyper/core
+pnpm exec kuyper generate
+pnpm exec kuyper validate
+git diff .kuyper/core/
+git diff
+```
+
+Se o primeiro `generate` recusar, pare antes do `pnpm add` e do `rm`. Para
+restaurar um core manualmente alterado à versão já instalada, iguale-o ao
+pacote, commite e recomece desde a árvore limpa.
+
+## `rule`
+
+Crie ou edite `.kuyper/project/rules/<nome>.md`, ou remova o arquivo, e rode:
+
+```bash
+pnpm exec kuyper generate
+```
+
+## `skill`
+
+Crie ou edite `.kuyper/project/skills/<nome>/SKILL.md`, preservando scripts
+irmãos quando for uma edição; para apagar, remova a árvore da skill. Depois:
+
+```bash
+pnpm exec kuyper generate
+```
+
+O `generate`, e não `skill delete`, identifica e remove as saídas órfãs.
+
+## Como comparar
+
+Execute comando e equivalente em cópias do mesmo commit. Ignore apenas texto de
+relatório e metadados internos do Git; compare `package.json`, lockfile,
+`.kuyper/`, saídas dos providers, `git config core.hooksPath`, branch atual e
+SHAs/refs que o procedimento deve alterar. A certificação executada fica em
+`docs/certificacao/` no repositório-fonte.

package/docs/guia/05-metodo.md

@@ -0,0 +1,56 @@
+# O método: Discovery, PRD, Architect e Dev
+
+O método separa quatro perguntas que costumam ser misturadas: vale construir,
+o que deve acontecer, como construir e qual bloco executar agora.
+
+## Discovery
+
+Explora uma ideia e define fronteira, princípios, exclusões, itens adiados com
+gatilho, critérios de sucesso e riscos. A skill organiza a análise; **o humano
+decide se vale construir**. Encerra com aprovação ou decisão de não prosseguir.
+Quando aprovado, entrega ao PRD.
+
+Não é necessário quando o humano já tomou uma decisão contida e não existe
+incerteza real de valor, usuário ou fronteira. Registre essa decisão como entrada
+equivalente; não fabrique uma Discovery retrospectiva para cumprir ritual.
+
+## PRD
+
+Transforma a fronteira aprovada em comportamento observável: capacidades,
+recusas com rota de recuperação, mensagens e critérios de aceitação. A skill
+decide a organização do contrato; **o humano decide o que o produto faz**.
+Encerra aprovado e entrega ao Architect.
+
+Não é necessário para uma correção cujo comportamento esperado já está decidido
+e rastreável. É necessário quando a pergunta ainda é “o que deveria acontecer?”.
+
+## Architect
+
+Decide escolhas técnicas, registra ADRs do projeto para decisões contidas,
+SPECs para protocolos que atravessam blocos e um BUILD com ordem e critério de
+pronto. Não
+pode mudar silenciosamente o PRD: um buraco de comportamento volta ao humano e
+ao PRD. Entrega um bloco por vez à skill Dev.
+
+Não é necessário quando a mudança não cria decisão arquitetural nova e cabe
+integralmente num bloco já aprovado. Um detalhe de implementação reversível pode
+ser decidido no código; uma escolha durável ou transversal precisa de registro.
+
+## Dev
+
+Executa um bloco concreto, escreve código e testes, roda gates, audita cada item
+de pronto e atualiza o STATE. Decide apenas dentro dos contratos herdados. Se
+descobrir que PRD, SPEC ou decisão humana estão errados, declara a discordância,
+propõe alternativa e espera a decisão antes de desviar.
+
+## Regra prática
+
+Use só a etapa que resolve a incerteza existente:
+
+- “Vale fazer e qual é a fronteira?” → Discovery.
+- “Qual comportamento e como sabemos que terminou?” → PRD.
+- “Qual desenho técnico e ordem de construção?” → Architect.
+- “O comportamento e o bloco já estão decididos” → Dev.
+
+Pular uma etapa porque não há decisão para ela é enxuto. Pular uma decisão que
+ainda está aberta apenas a empurra para o código, onde fica implícita.

package/docs/guia/06-falhas.md

@@ -0,0 +1,103 @@
+# Quando algo falha
+
+O Harness faz preflight antes de escrever e torna estado parcial visível. Não
+faz rollback automático.
+
+## Recusa antes de escrever
+
+Nada foi alterado. Siga os comandos mostrados pela recusa e execute novamente.
+
+## Interrupção durante uma saída do `generate`
+
+O alvo fica antigo inteiro ou novo inteiro; sucesso não é reportado. Um
+`.kuyper-tmp` pode permanecer, mas leitores o ignoram. Corrija a causa e rode:
+
+```bash
+pnpm exec kuyper generate
+pnpm exec kuyper validate
+```
+
+A próxima materialização bem-sucedida remove todos os temporários do Harness.
+
+## Interrupção do `init` antes da base completa
+
+A base incompleta recusa. Como este é o bootstrap e ainda não há estado válido,
+apague apenas a base parcial e recomece:
+
+```bash
+rm -rf .kuyper
+pnpm exec kuyper init
+```
+
+## Interrupção enquanto `update` iguala o core
+
+A árvore híbrida aparece em `git status`; `generate` recusa sem mudar saídas ou
+lock. Conclua a igualação inteira ao pacote instalado:
+
+```bash
+rm -rf .kuyper/core
+cp -R node_modules/@kuyper/harness/core .kuyper/core
+pnpm exec kuyper generate
+pnpm exec kuyper validate
+```
+
+Se surgir um `replaces:` órfão, edite ou remova a capacidade apontada pela R9 e
+rode os dois últimos comandos novamente.
+
+## Falha depois de um push aceito
+
+O remoto pode já ter recebido a `main`. Não repita o push às cegas: rode
+`pnpm exec kuyper publish`; ele compara `origin/main` e reconhece o que já foi
+publicado.
+
+## Falha do pnpm no `update`
+
+`.kuyper/core/` ainda está íntegro. Escolha uma rota:
+
+```bash
+# Voltar à versão do último commit
+git restore package.json pnpm-lock.yaml
+pnpm install
+
+# Ou insistir na nova
+pnpm add -D @kuyper/harness@latest
+pnpm exec kuyper update
+```
+
+## Falha do `update` depois do pnpm
+
+`package.json` e o lockfile já mudaram. O relatório informa o passo. Se a
+instalação concluiu mas o core ficou antigo ou híbrido, use:
+
+```bash
+rm -rf .kuyper/core
+cp -R node_modules/@kuyper/harness/core .kuyper/core
+pnpm exec kuyper generate
+pnpm exec kuyper validate
+```
+
+## Falha do `integrate` depois do merge
+
+A `main` já avançou corretamente e a `dev` ficou atrás. Conclua:
+
+```bash
+git switch dev
+git merge --ff-only main
+```
+
+## Push recusado porque um gate alterou a árvore
+
+Nada saiu da máquina; `main` local e remota estão intactas. A correção do gate
+está viva e não commitada em `git status`. Leve-a para `dev`, commite onde o
+`pre-commit` pode convergir e integre:
+
+```bash
+git switch dev
+git add -A
+git commit
+pnpm exec kuyper integrate
+pnpm exec kuyper publish
+```
+
+**Não use `git push --no-verify` nessa situação.** Ele enviaria o commit sem a
+correção que o gate acabou de produzir.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kuyper/harness",
+  "version": "0.1.0",
+  "description": "Copiloto de desenvolvimento: fonte canônica de rules e skills para Claude e Codex, gates e fluxo Git.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "kuyper": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "core",
+    "docs/guia"
+  ],
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=9"
+  },
+  "packageManager": "pnpm@10.30.3",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.build.json",
+    "pretest": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.3.0",
+    "eslint": "^10.9.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^4.1.11"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}