@kuyper/harness 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# Kuyper Harness
+
+`@kuyper/harness` mantém rules e skills numa fonte canônica, materializa essa
+fonte para Claude e Codex e aplica gates ao fluxo Git de um projeto com uma
+pessoa desenvolvedora.
+
+O Harness ensina o método além de automatizar comandos. Comece por
+[Começar um projeto](docs/guia/01-comecar.md) e siga os guias na ordem:
+
+1. [Começar um projeto](docs/guia/01-comecar.md)
+2. [Conceitos](docs/guia/02-conceitos.md)
+3. [Referência de comandos](docs/guia/03-comandos.md)
+4. [Equivalentes manuais](docs/guia/04-equivalentes-manuais.md)
+5. [O método](docs/guia/05-metodo.md)
+6. [Quando algo falha](docs/guia/06-falhas.md)
+
+Requisitos: Node.js 20 ou posterior, pnpm 9 ou posterior, Git e um repositório
+remoto chamado `origin`. O MVP assume uma pessoa, branches literais `main` e
+`dev`, e GitHub como remoto.
+
+As oito interfaces públicas são `init`, `generate`, `validate`, `integrate`,
+`publish`, `update`, `rule` e `skill`. Invoque sempre o binário instalado no
+projeto:
+
+```bash
+pnpm exec kuyper
+```

package/core/rules/adr.md

@@ -0,0 +1,11 @@
+---
+title: Quando abrir um ADR
+---
+
+Uma decisão técnica vira ADR quando é durável — sobrevive à tarefa que a
+motivou — e quando alguém precisaria entender o porquê depois, não só o
+resultado. Registre o contexto, a decisão e o que foi descartado, não o
+processo de chegar até ela.
+
+Decisão de implementação contida numa tarefa, que ninguém vai precisar
+revisitar fora dela, não precisa de ADR — só de ser feita.

package/core/rules/fluxo-git.md

@@ -0,0 +1,5 @@
+---
+title: Fluxo Git
+---
+
+Trabalhe na `dev`. A `main` recebe merges, não commits diretos.

package/core/rules/limites.md

@@ -0,0 +1,11 @@
+---
+title: Limites
+---
+
+A LLM não usa `--no-verify` nem nenhum outro bypass de gate ou hook. Essa
+porta é do humano, não dela.
+
+O shell é compartilhado, e nada nele distingue quem digitou um comando —
+esta regra reduz o risco de a LLM usar o escape, não o elimina, e não finge
+o contrário. É por isso que os demais mecanismos do produto verificam
+qualidade, nunca procedência: essas barreiras valem para todo mundo, sempre.

package/core/rules/publicacao.md

@@ -0,0 +1,7 @@
+---
+title: Publicação
+---
+
+A sequência: `integrate` a cada tarefa, `publish` quando a feature ou a versão
+estiver pronta. São atos separados — integrar leva a mudança para a `main`;
+publicar manda a `main` para o remoto.

package/core/rules/questionamento.md

@@ -0,0 +1,8 @@
+---
+title: Questionamento
+---
+
+Documento herdado não é verdade absoluta, pode ser questionado. Discordou
+de uma decisão do Discovery, do PRD ou do usuário? Diga, com o motivo e a
+alternativa, antes de executar. Depois execute a decisão dele por inteiro.
+Aceitar em silêncio algo que se acredita ser pior é o que esta regra proíbe.

package/core/rules/state.md

@@ -0,0 +1,16 @@
+---
+title: Uso do STATE
+---
+
+Leia `.kuyper/STATE.md` ao começar ou retomar uma tarefa. Sobrescreva
+somente ao concluir a tarefa ou ao entregá-la a outra sessão, provider ou
+pessoa antes de terminar.
+
+O STATE é o post-it operacional da troca de turno, não o lugar para tudo.
+Um achado que vale para qualquer LLM trabalhando neste projeto, não só para
+quem retomar esta tarefa, tem destino próprio: decisão técnica durável vira
+ADR; mudança de comportamento ainda não aprovada vira proposal; instrução
+permanente sobre como trabalhar aqui vira rule do projeto. O que sobra para
+o STATE é o que é específico desta tarefa — o resto, guardado só ali, some
+na próxima troca de sessão ou de ferramenta, e quem paga o custo é você de
+novo, ou a próxima pessoa.

package/core/skills/architect/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: architect
+description: Decide como será construído. Use depois de um PRD aprovado, para transformar comportamento em decisão técnica e ordem de execução.
+---
+
+# Architect
+
+## Contrato
+
+- **Entrada:** um PRD aprovado.
+- **Saída:** um ADR por decisão técnica contida, ou uma SPEC quando a
+  decisão atravessa mais de um bloco de construção ou muda o comportamento
+  do PRD; e um documento de construção (`kind: build`) com a decomposição em
+  blocos, a ordem de execução e o critério de "pronto" de cada um.
+- **Decide:** a escolha técnica e as alternativas descartadas, por quê.
+- **Não decide:** mudar o comportamento do PRD sem avisar. Se a decisão
+  técnica revela um buraco no PRD, aponta o buraco e questiona — não decide
+  sozinha por cima dele.
+- **Encerra quando:** cada decisão técnica tem ADR ou SPEC, e o documento de
+  construção cobre toda recusa e todo critério de aceitação do PRD, sem
+  nenhum órfão.
+- **Handoff:** skill `dev`, um bloco por vez.
+
+## Procedimento
+
+1. Leia o PRD inteiro. Para cada decisão técnica que ele deixa em aberto,
+   pergunte primeiro "quem já resolve isso" — Git, o gerenciador de
+   pacotes, o sistema operacional — antes de propor mecanismo novo. Nunca
+   reconstruir o que já existe.
+2. Decisão contida num bloco — não obriga dois blocos a se coordenarem antes
+   de existir código, não muda o comportamento do PRD: registre como ADR —
+   contexto, decisão, alternativas descartadas e por quê.
+3. Decisão que atravessa blocos, ou que muda o comportamento do PRD:
+   registre como SPEC, com o escopo só daquela decisão. Ela morre quando os
+   blocos que cobre fecharem — não é o PRD reescrito noutro arquivo.
+4. Se uma decisão técnica revelar um buraco no comportamento que o PRD
+   descreve, não decida por conta própria: aponte o buraco, proponha a
+   mudança, peça aprovação, volte ao PRD — só depois continue (rule
+   `questionamento`).
+5. Decomponha em blocos: um por vez, cada um com um critério de "pronto"
+   executável — algo que se roda e se observa, nunca conferido de olho.
+6. Ordene a execução pelo que os outros blocos dependem. O que não tem
+   equivalente manual, e que os demais chamam ou repetem, vem primeiro.
+7. Termine conferindo a rastreabilidade: toda recusa e todo critério de
+   aceitação do PRD aparece em algum bloco. Um órfão aqui é um furo
+   silencioso que só aparece depois.

package/core/skills/dev/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: dev
+description: Executa um bloco de construção — abre o arquivo indicado e implementa. Use quando há PRD/SPEC/BUILD já decididos e uma tarefa concreta pra fazer.
+---
+
+# Dev
+
+## Contrato
+
+- **Entrada:** um bloco do documento de construção, ou um pedido
+  equivalente — *"abra o arquivo X e execute"*.
+- **Saída:** código, testes, e o `STATE.md` atualizado.
+- **Decide:** como implementar dentro do que já foi decidido no PRD, na SPEC
+  e no ADR do bloco.
+- **Não decide:** mudar arquitetura ou comportamento sem escalar. Se a
+  implementação revelar que o PRD ou a SPEC estão errados, questiona antes
+  de desviar da decisão registrada — não corrige em silêncio.
+- **Encerra quando:** os gates do projeto passam a partir de árvore limpa, e
+  cada item do critério de "pronto" do bloco foi conferido um a um contra o
+  que foi implementado — não só rodado.
+- **Handoff:** de volta para o humano, ao fechar o bloco; ou o próximo
+  bloco, quando ele existir.
+
+## Procedimento
+
+1. Leia o bloco inteiro antes de escrever qualquer código. O critério de
+   "pronto" é a régua da tarefa, não uma lista pra conferir depois de
+   terminar.
+2. Releia o PRD e a SPEC que o bloco toca. Comportamento não se decide lendo
+   o código nem adivinhando — está escrito, ou não existe ainda.
+3. Antes de escrever uma função nova, procure se ela já existe. Reaproveitar
+   é a regra; duplicar é a exceção que precisa de motivo.
+4. Escreva teste para cada item do critério de "pronto", não só para o
+   caminho feliz.
+5. Rode os gates do projeto a partir de árvore limpa.
+6. Audite o critério de "pronto" item a item contra o que foi implementado.
+   Rodar o comando e ele funcionar não é suficiente para saber que o bloco
+   fechou — a lista é.
+7. Atualize o `STATE.md`: onde parou, o que descobriu que não estava óbvio,
+   o próximo passo concreto, e o que quem retomar precisa ter cuidado.
+8. Se o código revelar que o PRD ou a SPEC estão errados, pare e questione
+   antes de desviar — diga o motivo e a alternativa, execute a decisão que
+   vier depois por inteiro (rule `questionamento`).

package/core/skills/discovery/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: discovery
+description: Explora uma ideia e decide se vale construir. Use quando uma proposta ainda precisa ser descoberta.
+---
+
+# Discovery
+
+## Contrato
+
+- **Entrada:** uma ideia ou um problema, em qualquer estágio de maturidade —
+  de uma frase a uma conversa longa.
+- **Saída:** um documento em `.kuyper/docs/discovery/<data>-<slug>.md`, com o
+  frontmatter completo (`schemaVersion`, `kind: discovery`, `status`,
+  `revision`, `createdAt`/`approvedAt`, `depends: []` — Discovery não depende
+  de nada).
+- **Decide:** como organizar a fronteira do que vale a pena, que princípios
+  resolvem as tensões reais da proposta, o que fica de fora e por quê.
+- **Não decide:** se vale a pena construir. Isso é sempre do humano — a
+  skill redige, ele aprova ou recusa.
+- **Encerra quando:** o humano aprova (`status: approved`) ou decide não
+  seguir. As duas são saídas válidas — uma recomendação de "não proceder" não
+  é falha da skill, é o trabalho dela funcionando.
+- **Handoff:** skill `prd`, quando aprovado.
+
+## Procedimento
+
+1. Entenda o problema antes de propor solução. Pergunte até a pessoa não
+   conseguir mais responder "por quê" sem repetir o que já disse.
+2. Escreva o que é e o problema primeiro. Se não sair em poucas frases, o
+   problema ainda não está claro o bastante pra continuar — não force a
+   fronteira antes disso.
+3. Proponha princípios: frase curta, cada um resolvendo uma tensão real da
+   proposta. Uma lista de boas intenções não é princípio.
+4. Desenhe a fronteira em três partes — **incluído** (o que entra),
+   **excluído** (o que fica de fora desta versão, sem gatilho de volta) e
+   **adiado com gatilho** (o que fica de fora por agora, com o evento
+   observável que o traz de volta; nunca "quando tivermos mais tempo").
+5. Liste as decisões que restringem a fronteira, uma por linha, numeradas.
+   Não registre decisão que não restringe nada.
+6. Escreva critérios de sucesso executáveis — algo que se roda e observa, não
+   "o usuário vai gostar".
+7. Liste riscos, cada um com mitigação. Um risco sem mitigação é um risco não
+   avaliado.
+8. Termine com uma recomendação clara: proceder, ou não — e por quê.
+9. Pergunte ao humano se aprova. Se sim, `status: approved`, siga para o
+   handoff. Se não, ele diz o motivo, você ajusta, repete — sem aceitar em
+   silêncio uma direção que você acha pior (rule `questionamento`).

package/core/skills/prd/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: prd
+description: Define o que será construído e quando está pronto. Use depois de um Discovery aprovado, ou quando não há incerteza de valor a resolver.
+---
+
+# PRD
+
+## Contrato
+
+- **Entrada:** um Discovery aprovado, ou uma decisão equivalente do humano
+  quando não havia incerteza de valor a fechar.
+- **Saída:** um documento em `.kuyper/docs/prd/<data>-<slug>.md`, com
+  `depends` apontando para o Discovery (quando existir) e frontmatter
+  completo.
+- **Decide:** como organizar o comportamento em contratos observáveis, quais
+  recusas nomear, o formato das mensagens do produto.
+- **Não decide:** o que o produto faz. O humano decide o quê; a skill
+  redige o comportamento resultante.
+- **Encerra quando:** o humano aprova (`status: approved`).
+- **Handoff:** skill `architect`.
+
+## Procedimento
+
+1. Releia o Discovery aprovado — não resuma. Extraia só as conclusões que
+   restringem a construção; o porquê fica lá, não aqui. Se uma frase só faz
+   sentido citando a motivação original, ela está no documento errado.
+2. Para cada capacidade que o Discovery decidiu incluir, escreva um contrato
+   observável: o que faz, quando recusa, quando está pronto. Nunca "deveria
+   funcionar bem".
+3. Nomeie toda recusa prevista com um código, e a rota que resolve —
+   comandos copiáveis, nunca "corrija o problema".
+4. Se o produto fala com o usuário, decida a forma da mensagem: um fato na
+   primeira linha, os caminhos envolvidos, a consequência quando não for
+   óbvia, a rota em comandos que concluem sozinhos.
+5. Tamanho vem do formato de seções que você decidiu (comandos, contratos,
+   recusas, critérios de aceitação), nunca de um teto de linhas.
+6. Pergunte ao humano se o comportamento descrito é o certo — ele decide o
+   quê, você decide como registrar. Discordou de algo que ele decidiu? Diga,
+   com o motivo e a alternativa, antes de escrever como se tivesse
+   concordado (rule `questionamento`).
+7. Termine com critérios de aceitação executáveis, cada um rastreável a uma
+   futura decomposição em blocos de construção — mesmo que os blocos ainda
+   não existam.

package/dist/atomicWrite.js

@@ -0,0 +1,89 @@
+import { mkdir, readdir, rename, rm, writeFile, chmod } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * Sufixo reservado do Harness (PRD §3.2, ADR escrita-atomica).
+ * Dentro dele a regra "não destrói o que não criou" não vale.
+ */
+export const TMP_SUFFIX = '.kuyper-tmp';
+/**
+ * Escreve `content` em `<targetPath>.kuyper-tmp`, no mesmo diretório do alvo,
+ * e renomeia por cima. Quem lê vê o arquivo velho inteiro ou o novo inteiro,
+ * nunca truncado — a atomicidade é a do próprio `rename()` do sistema de
+ * arquivos, não uma máquina de estados do Harness (ADR escrita-atomica,
+ * decisão 1).
+ *
+ * O Harness **não** promete atomicidade da operação inteira: se `generate`
+ * parar entre dois arquivos, algumas saídas ficam antigas e outras novas — a
+ * comparação de três pontas reconhece o que já foi materializado e a
+ * reexecução converge. Não há seam de injeção de falha aqui: estados
+ * parciais são fixtures de disco nos blocos que os interpretam (B2, B9).
+ */
+export async function writeFileAtomic(targetPath, content, options = {}) {
+    const tmpPath = `${targetPath}${TMP_SUFFIX}`;
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(tmpPath, content);
+    if (options.mode !== undefined) {
+        await chmod(tmpPath, options.mode);
+    }
+    await rename(tmpPath, targetPath);
+}
+/** Verdadeiro se o caminho pertence ao namespace reservado do Harness. */
+export function isTempPath(path) {
+    return path.endsWith(TMP_SUFFIX);
+}
+/**
+ * Remove `path` se, e só se, ele existir e terminar em `.kuyper-tmp`.
+ * Usado para os candidatos explícitos que não vivem sob um diretório
+ * controlado (ex.: CLAUDE.md.kuyper-tmp na raiz do projeto).
+ */
+export async function removeIfTemp(path) {
+    if (!isTempPath(path))
+        return false;
+    try {
+        await rm(path, { force: false });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+/**
+ * Varre recursivamente cada diretório em `dirs` removendo todo arquivo
+ * `*.kuyper-tmp` encontrado, sem distinguir qual comando o deixou (ADR
+ * escrita-atomica, decisão 2 — o namespace é do Harness inteiro, não de uma
+ * operação). Diretório ausente é ignorado, não é erro.
+ *
+ * Este é o primitivo; a política de "quais raízes varrer, e quando" — a
+ * limpeza global e silenciosa ao final de uma materialização bem-sucedida,
+ * antes de reportar sucesso — pertence a quem chama (o `generate` do B2).
+ */
+export async function sweepTempFiles(dirs) {
+    const removed = [];
+    for (const dir of dirs) {
+        await walk(dir);
+    }
+    return removed;
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile() && isTempPath(entry.name)) {
+                await rm(full, { force: true });
+                removed.push(full);
+            }
+        }
+    }
+}