@orkastery/cli 0.2.0

package/references/security-checklist.md

@@ -0,0 +1,101 @@
+# Security Checklist
+
+A lista normativa que a auditoria de seguranca do CHECK percorre, cuja condicao dura de passagem e
+zero bloqueadores no relatorio consolidado. Ela eleva verificacao que ja existe no nucleo e nao
+inventa nenhuma. Os itens sao numerados uma unica vez no arquivo inteiro. Cite um item como `SEC 5`.
+
+**Fontes:** `core/src/policies.ts` (padroes de segredo e policies bloqueantes),
+`core/src/doctor.ts`, `core/src/ship.ts`, `core/src/gates.ts`,
+`core/src/superficie.ts` (varredura deterministica da superficie de ataque de rede,
+regras SP8..SP12 do pack `security-privacy`),
+[definition-of-done.md](definition-of-done.md).
+
+```mermaid
+flowchart TB
+    E["escopo declarado:<br/>diff, historico, prompts, artefatos"] --> S1["SEC 1 a 4:<br/>segredo e credencial"]
+    S1 --> S2["SEC 5 a 8:<br/>entrada e superficie"]
+    S2 --> S3["SEC 9 e 10:<br/>dependencia e cadeia"]
+    S3 --> S4["SEC 11 a 14:<br/>artefatos do repositorio"]
+    S4 --> S5["SEC 15 a 17:<br/>conduta da auditoria"]
+    S5 --> S6["SEC 18 a 22:<br/>superficie de ataque de rede"]
+    S6 --> C{"algum bloqueador?"}
+    C -->|"sim"| B["veredito BLOQUEADO"]
+    C -->|"nao"| P["zero bloqueadores:<br/>condicao dura cumprida"]
+```
+
+## Segredo e credencial
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 1 | Nenhum segredo na arvore de trabalho: token, chave de API, senha, bloco de chave privada, string de conexao e string de alta entropia com cara de credencial, incluindo arquivos `.env`, fixtures de teste e configs de exemplo. | Leitura do diff da branch mais varredura da arvore. O relatorio nomeia a ferramenta usada ou diz que a passagem foi manual. |
+| 2 | Nenhum segredo no historico atras da branch. Segredo commitado e depois apagado continua vazado. | `git log -p <base>..HEAD` sobre o intervalo inteiro, nao so a arvore. Bloqueador ate a credencial ser rotacionada e o historico limpo, com a rotacao verificada e nao prometida. |
+| 3 | Nenhuma credencial real em prompt despachado. O gate `phase.dispatch` do `ork` avalia a policy `segredo_em_prompt` ANTES de gravar o prompt em disco: prompt reprovado nao chega a existir como arquivo, porque gravar um prompt com credencial cria um segundo vazamento dentro do proprio repositorio. | `ork phase run` sai com motivo tipado `policy.violation`; o ledger registra o nome do padrao e a linha, nunca o trecho casado. |
+| 4 | Nenhuma credencial real em artefato de thread, ledger, saida de comando capturada ou no proprio relatorio de auditoria. Relatorio de vazamento que imprime o segredo e um segundo vazamento. | Leitura dos artefatos que a thread produziu. Placeholder redigido passa e e declarado como tal; credencial e referenciada por localizacao e forma redigida. |
+
+## Entrada e superficie
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 5 | Toda entrada que atravessa fronteira de confianca e validada no lado que confia, e nao no lado que chama. Validacao so no cliente conta como ausente. | Leitura do diff nos pontos de entrada tocados. |
+| 6 | Nenhuma concatenacao de entrada em SQL, shell, caminho de arquivo ou template renderizado. O nucleo `ork` executa comando por lista de argumentos, sem shell interpolado, e o mesmo padrao vale para o codigo revisado. | Leitura do diff; qualquer construcao de comando por concatenacao e bloqueador. |
+| 7 | Autenticacao e autorizacao verificadas por operacao, nao por tela: quem pode ler nem sempre pode escrever, e o teste que prova isso existe ou o achado e aviso com registro. | Testes de autorizacao na suite, reexecutados por `ork verify`. |
+| 8 | Desserializacao de dado nao confiavel nao instancia tipo arbitrario, e todo `JSON.parse` de arquivo de estado tem erro tratado com o caminho no texto do erro. | Leitura do diff sobre os pontos de leitura de estado. |
+
+## Dependencia e cadeia de suprimento
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 9 | Nenhuma dependencia nova sem justificativa no PLAN. Dependencia que entra sem tarefa e scope creep com superficie de ataque. | Diff dos arquivos de manifesto de pacote contra as tarefas do PLAN. |
+| 10 | Vulnerabilidade conhecida nas dependencias declaradas foi consultada, e o resultado esta no relatorio com a data e a ferramenta. Onde nao ha ferramenta, o item sai `unavailable` com o motivo. | `npm audit` onde ha dependencia de producao declarada. |
+
+## Artefatos do repositorio
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 11 | Nenhum comando destrutivo em massa em script, hook ou documentacao que alguem vai copiar: `rm -rf` com caminho variavel nao ancorado, `git add -A`, `git checkout -- .`, `git reset --hard` sem alvo, `push --force`. | Varredura dos diretorios tocados. O guard `PreToolUse` do adaptador Claude Code bloqueia estes mesmos comandos em tempo de execucao. |
+| 12 | Nenhum push direto na branch base. A policy `push_direto_na_base` do manifesto e bloqueante e reprova entrega em que origem e destino sao a mesma branch. | `ork ship` sai com `policy.violation` antes de tocar no remoto. |
+| 13 | Nenhum despacho por provider pago quando a politica e `subscription-only`. Variavel de ambiente que redireciona o `claude` para provider pago e bloqueador, porque o custo aparece na fatura e nao no gate. | `ork doctor` e a policy `provider`, avaliada no gate `phase.dispatch` e no `ship`. |
+| 14 | Permissao de arquivo criado por script nao amplia acesso: nada de `chmod 777`, nada de arquivo de estado com bit de execucao. | Leitura do diff dos scripts e hooks. |
+
+## Conduta da auditoria
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 15 | O escopo auditado esta declarado antes dos achados: quais diretorios, qual intervalo de historico, quais artefatos. Auditoria sem escopo declarado nao e reproduzivel e nao vale como evidencia. | O cabecalho da secao de seguranca do relatorio. |
+| 16 | Cada achado sai categorizado bloqueador, aviso ou sugestao, com o item `SEC n` que ele viola. Achado sem numero de item e opiniao. | A tabela de achados do relatorio. |
+| 17 | Ausencia de achado e afirmada como resultado de verificacao, com o que foi olhado. "Nada encontrado" sem escopo e diferente de "auditado e limpo", e a diferenca fica escrita. | O texto da secao, contra `SEC 15`. |
+
+## Superficie de ataque de rede
+
+O que o produto PUBLICA. Os itens 5 a 8 olham o dado que entra por uma fronteira; estes olham
+a fronteira em si: quais rotas e endpoints existem, quem pode chama-los e a que custo. O pack
+`security-privacy` audita esta secao com varredura DETERMINISTICA (`ork audit surface`, regras
+SP8 a SP12), que roda dentro de `ork audit run security-privacy` e grava cada achado no board
+de divida com evidencia `arquivo:linha` e o comando que a reexecuta.
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 18 | Toda rota de servidor HTTP/API declarada em producao passa por camada de autenticacao/autorizacao, ou e publica por decisao registrada (login, cadastro, health, webhook assinado). Rota publica por esquecimento e bloqueador. | `ork audit surface --regra SP8`. O achado traz a definicao da rota com `arquivo:linha`, o framework reconhecido e o comando que prova a ausencia de guarda no bloco da rota ou no arquivo. |
+| 19 | Endpoint de administracao ou operacao (admin, console, debug, swagger/openapi, health detalhado, metricas, `pprof`, metadados de cluster) nao esta acessivel de fora: ha restricao de rede (allowlist, rede interna) ou oAuth/basic auth. Health que devolve versao, hostname, banco ou dependencia e endpoint de operacao, nao de saude. | `ork audit surface --regra SP9`, mais a configuracao de rede ou o middleware citado com `arquivo:linha`. |
+| 20 | Rota exposta tem limite de taxa por IP e por identidade, com atencao especial ao caminho de autenticacao, recuperacao de senha, OTP, busca, exportacao e qualquer rota publica que altera estado. Sem limite, uma requisicao paga um brute-force. | `ork audit surface --regra SP10`. Middleware de limite, cota ou rpm citado na rota, no roteador que a monta ou no gateway, com o arquivo e a linha. |
+| 21 | CORS nao combina origem global com credenciais, e origem aberta nao aparece em servico que trafega dado pessoal ou sessao. Lista explicita de origens, sempre. | `ork audit surface --regra SP11`. O achado cita a configuracao com `arquivo:linha`, o curinga de origem e a flag de credenciais, cada um com o comando que o reexecuta. |
+| 22 | A definicao da rota declara o esquema do payload na borda (schema, validador, modelo tipado), e a recusa do payload invalido acontece antes do handler. Complementa o item 5, que olha o USO do dado dentro do handler. | `ork audit surface --regra SP12`, com a definicao da rota e a ausencia de esquema no ponto de entrada. |
+
+Achado que a varredura marca com confianca `baixa` (ha middleware que o `ork` nao classifica,
+framework nao reconhecido, marcador presente no arquivo e ausente no bloco da rota) sai como
+**aviso que pede confirmacao humana**, nunca como bloqueador: a maquina diz onde olhar, e quem
+decide se procede e a pessoa.
+
+## Recomendacoes (nao sao gate nesta maquina)
+
+- Varredura por ferramenta dedicada de segredo (gitleaks, trufflehog): nao instalada aqui. Os
+  padroes de `core/src/policies.ts` cobrem chave da Anthropic, da OpenAI, de acesso AWS, token do
+  GitHub, chave privada PEM e atribuicao de segredo em texto, e a auditoria diz que cobriu essas
+  classes e nao outras.
+- Analise de composicao de software e assinatura de artefato: fora do alcance desta maquina; sai
+  `unavailable` com o motivo, nunca como passagem silenciosa.
+- Teste dinamico da superficie (varredura de portas, fuzzing de endpoint, DAST): fora do alcance.
+  A varredura dos itens 18 a 22 e ESTATICA e le a definicao de rota no codigo: ela nao ve rota
+  gerada em tempo de execucao, nem proxy, gateway ou WAF na frente do servico. Onde houver essa
+  camada, o achado continua valendo como pergunta e e resolvido com a evidencia da camada, nunca
+  em silencio.

package/references/testing-patterns.md

@@ -0,0 +1,51 @@
+# Testing Patterns
+
+O que uma suite precisa provar e como uma suite verde e ganha honestamente. Os itens sao numerados
+uma unica vez no arquivo inteiro. Cite um item como `TEST 3`.
+
+**Fontes:** `core/src/verify.ts` (baseline e reexecucao), `core/src/claims.ts`,
+[definition-of-done.md](definition-of-done.md), [code-review-axes.md](code-review-axes.md).
+
+```mermaid
+flowchart LR
+    B["baseline gravada<br/>antes do GO"] --> G["GO: implementacao<br/>slice por slice"]
+    G --> R["reexecucao no HEAD real"]
+    R --> D{"comparacao contra a baseline"}
+    D -->|"passava e falha"| RG["regressao:<br/>TEST 1, gate verify.regression"]
+    D -->|"ja falhava"| DV["divida pre-existente:<br/>declarada, nao imputada a thread"]
+    D -->|"tudo verde"| OK["suite verde ganha"]
+```
+
+## O que a suite prova
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 1 | Existe baseline gravada antes do GO. Sem ela, uma falha nao distingue regressao de divida pre-existente, e a thread leva culpa por defeito que ja estava la, ou pior, esconde o que ela mesma quebrou. | `ork verify <thread> --baseline` antes do GO. |
+| 2 | Todo criterio de sucesso do GOAL tem um comando que o comprova. Criterio que nao vira comando nao e criterio, e adjetivo. | As claims da thread, com `--verificar`. |
+| 3 | Numa demanda de correcao, existe um teste que reproduz o defeito e que falhava antes da correcao. Correcao cujo defeito nunca foi reproduzido nao pode provar que corrigiu nada. | O teste novo, rodado contra o commit anterior a correcao. |
+| 4 | O caminho de falha tem teste, nao so o caminho feliz. Suite que so exercita o sucesso mede otimismo. | Leitura da suite contra os casos de borda do PLAN. |
+| 5 | Teste novo falha quando a implementacao e revertida. Teste que passa com e sem a mudanca nao testa a mudanca. | Reverter localmente e rodar, ou mutar a linha central e conferir a reprovacao. |
+
+## Como a suite verde e ganha
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 6 | A suite roda no HEAD real, no diretorio de trabalho da thread. Passagem relatada por agente nao e passagem. | `ork verify <thread>` reexecuta os comandos do manifesto e as claims, e carimba o commit real. |
+| 7 | Nenhum teste foi desligado, marcado para pular ou afrouxado para fechar a entrega. Pular teste e mudanca de escopo com registro, nunca ajuste de rota silencioso. | Diff sobre os arquivos de teste, procurando teste removido, `skip` e assercao relaxada. |
+| 8 | Nenhuma assercao foi trocada pelo valor que o codigo produz hoje sem que alguem tenha dito por que o valor certo mudou. Ajustar o esperado ao observado e a forma mais comum de transformar defeito em contrato. | Diff das assercoes contra a intencao declarada no PLAN. |
+| 9 | Teste nao depende de rede, de credencial paga nem de relogio de parede. Fixture deterministica e o padrao; o que precisa de mundo externo fica fora do gate e e declarado. | Rodar a suite offline. No `ork`, os canarios de `ork eval` montam repositorio git temporario e nao tocam a rede. |
+| 10 | Teste nao depende de outro teste nem da ordem de execucao. Estado compartilhado entre casos e defeito, mesmo quando a suite esta verde hoje. | Rodar em ordem embaralhada ou isoladamente o caso suspeito. |
+
+## Contagem e cobertura
+
+| # | Verificacao | Como se comprova |
+|---|---|---|
+| 11 | A contagem de testes reportada e a que o comando imprimiu, colada da saida real. Numero de suite digitado de memoria nao e evidencia. | A saida do runner no relatorio da entrega. |
+| 12 | Cobertura e reportada com origem: `runtime_reported` quando a ferramenta mediu, `estimated` quando alguem estimou e disse que estimou, `unavailable` quando nao ha ferramenta. Lacuna e publicada como lacuna, nunca como zero. | A secao de metricas do relatorio. |
+
+## Recomendacoes (nao sao gate nesta maquina)
+
+- Cobertura por ferramenta: este repositorio nao tem uma instalada, entao a cobertura sai
+  `unavailable` por `TEST 12`, e nao estimada por conveniencia.
+- Teste de mutacao para provar `TEST 5` de forma automatica: fora do alcance desta maquina; a prova
+  aqui e manual e declarada como manual.

package/skills/README.md

@@ -0,0 +1,43 @@
+# skills/
+
+Catalogo do Orkastery: as 17 skills que levam a metodologia das 6 fases para qualquer host
+compativel. Buckets: `core/`, `phases/`, `reviewers/`, `governance/`, `observability/`.
+
+**Regra do catalogo, herdada do original e mantida aqui:** cada skill e um **roteador fino que
+chama o `ork`**, nunca a implementacao, e **skill sem eval nao entra**. A metodologia executavel
+mora no nucleo (`core/`), nao nesta prosa. Em qualquer divergencia entre uma skill e o que o `ork`
+faz, o nucleo vence, e a divergencia e defeito da skill.
+
+| Bucket | Skill | Roteia para |
+|---|---|---|
+| core | [orkastery-bootstrap](core/orkastery-bootstrap/SKILL.md) | `ork modos`, `ork thread new`, `ork board` |
+| core | [thread-state](core/thread-state/SKILL.md) | `ork thread status`, `ork phase list` |
+| phases | [goal-definition](phases/goal-definition/SKILL.md) | `ork phase run <t> GOAL`, `ork claims add` |
+| phases | [plan-specification](phases/plan-specification/SKILL.md) | `ork phase run <t> PLAN`, `ork lease acquire` |
+| phases | [go-implementation](phases/go-implementation/SKILL.md) | `ork worktree ensure`, `ork verify --baseline` |
+| phases | [check-quality](phases/check-quality/SKILL.md) | `ork verify`, `ork gate approve` |
+| phases | [ship-release](phases/ship-release/SKILL.md) | `ork ship` |
+| phases | [master-metrics](phases/master-metrics/SKILL.md) | `ork master`, `ork master --batch` |
+| reviewers | [code-reviewer](reviewers/code-reviewer/SKILL.md) | `references/code-review-axes.md` |
+| reviewers | [security-auditor](reviewers/security-auditor/SKILL.md) | `references/security-checklist.md` |
+| reviewers | [test-engineer](reviewers/test-engineer/SKILL.md) | `references/testing-patterns.md` |
+| reviewers | [web-performance-auditor](reviewers/web-performance-auditor/SKILL.md) | `references/performance-checklist.md` |
+| governance | [decision-triage](governance/decision-triage/SKILL.md) | `ork gate approve` |
+| governance | [narrative-guardian](governance/narrative-guardian/SKILL.md) | `ork verify`, `ork phase list` |
+| governance | [roadmap-keeper](governance/roadmap-keeper/SKILL.md) | `ork board`, `ork thread new` |
+| governance | [scope-check-capability-map](governance/scope-check-capability-map/SKILL.md) | `ork doctor`, `ork board plan` |
+| observability | [thread-tracing](observability/thread-tracing/SKILL.md) | `ork phase list`, `ork sessions` |
+
+## Evals
+
+Os 87 casos que protegem estas skills ficam em [`eval/casos/`](../eval/casos/) e rodam por
+`ork eval`. Cada skill tem no minimo tres casos, cobrindo caminho feliz, resistencia a
+racionalizacao e borda de dominio. O runner julga a **metade estatica** (as regras que precisam
+existir no arquivo para o comportamento ser possivel) e diz em voz alta que a **metade
+comportamental e `unavailable`**, nunca `passing`: lacuna e publicada como lacuna.
+
+## Instalacao nos hosts
+
+`ork adapter install claude-code|hermes|openclaw` instala estas mesmas skills no host, sem copiar o
+catalogo: **uma copia so**, declarada caminho a caminho no manifesto do plugin. Duas copias do
+catalogo divergem, e a divergencia so aparece quando ja custou uma entrega.

package/skills/core/orkastery-bootstrap/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: orkastery-bootstrap
+description: "Skill raiz do Orkastery: explica o ciclo de looping threads, roteia /goal /plan /go /check /ship /master para as skills de fase e para o `ork`, e le a #TAG de conducao do pedido. Ativa sempre que o repositorio tem orkastery.yaml."
+bucket: core
+roteia: "ork modos | ork thread new | ork board"
+license: MIT
+---
+
+# Orkastery Bootstrap
+
+## O que esta skill e
+
+Um roteador fino. Ela nao executa fase nenhuma, nao escreve codigo e nao guarda regra de negocio:
+ela diz qual comando `ork` responde pela intencao do builder e chama esse comando. **A metodologia
+executavel mora no nucleo `ork`, nunca nesta prosa.** Em qualquer divergencia entre o que esta
+escrito aqui e o que o `ork` faz, o nucleo vence, e a divergencia e defeito desta skill.
+
+Essa e a licao que matou o Orkastery original: metodologia que existe so como texto e metodologia
+que ninguem verifica.
+
+## Quando usar
+
+- Automaticamente, sempre que o repositorio de trabalho tem `orkastery.yaml`.
+- Quando o builder pede para comecar, retomar, listar ou avaliar trabalho.
+- Quando outra skill do catalogo precisa das regras de base repetidas.
+
+## Como rotear
+
+```bash
+ork doctor                                    # o que vale nesta maquina agora
+ork modos                                     # a tabela dos 5 modos de conducao
+ork thread new "<nome>" --mode <modo>         # abre a thread com a #TAG do pedido
+ork phase run <thread> GOAL --prompt "<...>"  # despacha a fase pelo runtime
+ork board                                     # o estado de todas as threads
+ork board plan                                # quem avanca agora, quem espera e por que
+```
+
+## A #TAG de conducao
+
+A autonomia se escolhe no pedido, nao em arquivo de configuracao. O adaptador do host extrai a
+primeira #TAG do texto do builder e repassa `--mode` ao `ork`; sem #TAG vale o
+`conduction.default_mode` do manifesto. **A validacao contra `allowed_modes` e do nucleo:** o host
+nao decide se um modo e permitido, ele so transporta a tag.
+
+| #TAG | Pausas humanas | Uso |
+|---|---|---|
+| `#Look` | 6 | Risco alto, passo irreversivel, dominio novo |
+| `#Ork` | 5 | Veredito separado da execucao e da evidencia |
+| `#Classic` | 3 | O padrao: premissas delicadas, entrega solta, score em batch |
+| `#Maestro` | 1 | Solucao clara e agil, score em batch |
+| `#Auto` | 0 | Docs, estudos, configuracoes, auditorias |
+
+## As regras inviolaveis
+
+1. **Nenhuma fase se pula.** Demanda pequena ganha fase compacta, nunca fase a menos. Uma correcao
+   de uma linha tambem atravessa GOAL, PLAN, GO, CHECK, SHIP e MASTER.
+2. **O modo afrouxa a pausa, NUNCA a verificacao.** Claims, verify, policies e gates tipados rodam
+   identicos em `#Look` e em `#Auto`; o que muda e se o veredito espera o humano.
+3. **A camada que apresenta nunca escreve codigo de produto.** Quem escreve codigo e a orquestra
+   (Camada 3), despachada pelo `ork`. Adaptador que implementa a demanda quebrou a arquitetura.
+4. **O estado mora em disco**, em `.orkastery/threads/<id>/`. Qualquer sessao retoma qualquer
+   thread a partir do disco; conversa nao e estado.
+5. **Gate e decisao humana registrada**, ou decisao autonoma registrada com quem decidiu, com que
+   evidencia e por que. Gate sem registro nao aconteceu.
+6. **Entrega sem MASTER log nao aconteceu.** O score humano de 0 a 5 fecha toda thread, na hora ou
+   na fila de batch dos modos sem pausa de MASTER.
+
+## Racionalizacoes comuns
+
+| Desculpa | Realidade |
+|---|---|
+| "E uma correcao minima, GOAL e exagero" | Compacto, nunca ausente: um GOAL de tres paragrafos custa minutos e evita o retrabalho classico de direcao errada. |
+| "Depois eu dou o score da thread anterior" | Entrega sem MASTER log nao aconteceu. Nos modos sem pausa, o score vai para a fila de `ork master --batch`, que continua sendo humana. |
+| "Como e `#Auto`, da para pular o verify" | O modo afrouxa a pausa, nunca a verificacao. Policy `block` e escalacao tipada param `#Auto` igual param `#Look`. |
+| "Eu mesmo escrevo esse trecho, e mais rapido" | A camada que apresenta nao escreve codigo de produto. Velocidade que quebra a trilha de auditoria e divida, nao velocidade. |
+| "A conversa lembra em que fase a thread esta" | Conversa termina. O estado mora em disco e e isso que faz qualquer sessao retomar qualquer thread. |
+
+## Bandeiras vermelhas
+
+- Um diretorio de thread sem `thread.json` ou sem `ledger.jsonl`.
+- Uma skill do catalogo implementando o que o `ork` ja faz, em vez de chamar o comando.
+- Regra de negocio dentro do adaptador de host: validacao de modo, calculo de slug, decisao de gate.
+- Uma entrega mergeada sem relatorio de CHECK, ou uma thread fechada sem MASTER log.
+
+## Verificacao antes de sair da skill
+
+Manifesto lido, modo da thread conhecido, estado da thread presente em disco, comando `ork` certo
+identificado, e o builder informado em uma linha de em que fase a thread esta e o que acontece
+agora. Ver `DoD 17` e `DoD 20`.

package/skills/core/thread-state/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: thread-state
+description: "O estado da thread em disco: thread.json, ledger.jsonl, claims.jsonl, prompts com hash e leases. Roteia para ork thread status, ork phase list e ork board; nenhuma leitura de estado por memoria de conversa."
+bucket: core
+roteia: "ork thread status | ork phase list | ork board"
+license: MIT
+---
+
+# Thread State
+
+## O que esta skill e
+
+Um roteador fino sobre o estado que o `ork` mantem em disco. Ela nao inventa formato, nao edita
+arquivo de estado na mao e nao guarda regra: ela diz qual comando le a verdade e chama esse
+comando. **Editar `thread.json` com editor de texto e corromper estado, nao adiantar trabalho.**
+
+## Quando usar
+
+- Ao retomar uma thread que outra sessao abriu.
+- Antes de qualquer fase, para saber em que ponto do ciclo a thread esta.
+- Quando duas threads parecem estar disputando o mesmo arquivo ou a mesma arvore.
+
+## Onde o estado mora
+
+```text
+.orkastery/
+|- threads/<thread-id>/
+|  |- thread.json          estado da thread: modo, blocos, base carimbada, sessoes
+|  |- ledger.jsonl         append-only: todo evento, com quem decidiu e a evidencia
+|  |- claims.jsonl         alegacoes verificaveis e o comando que comprova cada uma
+|  |- prompts/             o prompt exato de cada sessao, nomeado pelo sha256
+|  |- POSTMORTEM.json      fechamento tipado da thread
+|  `- master-log.json      o contrato congelado ork.master-log/v1, com o score humano
+`- leases/                 leases por familia e a fila de espera
+```
+
+## Como rotear
+
+```bash
+ork thread list                    # todas as threads do projeto
+ork thread status <thread>         # estado da thread, cruzado com o runtime real
+ork phase list <thread>            # o ledger inteiro, evento a evento
+ork claims list <thread>           # as alegacoes e o estado de cada uma
+ork lease list                     # leases, familias e as filas
+ork board                          # todas as threads em uma visao
+ork memory status                  # regime de memoria efetivo (files ou orkmind)
+ork recall <thread> --fase <FASE>  # resolve os ponteiros do handoff DESTE momento
+```
+
+## O que o nucleo garante
+
+- **Append-only.** O `ledger.jsonl` so cresce. Correcao entra como evento novo, nunca como linha
+  reescrita: historico editado deixa de ser historico.
+- **O prompt e artefato, nao lembranca.** Cada sessao grava o prompt exato com `sha256` no nome, e
+  o mesmo hash vai ao ledger. Isso e o que permite provar o que foi pedido.
+- **A base e carimbada na criacao.** `thread.json` guarda a branch e o commit de onde a thread
+  partiu; e contra esse carimbo que `ork worktree audit` detecta que a base andou.
+- **O estado real vence o estado gravado.** `ork thread status` cruza as sessoes gravadas com o
+  runtime; sessao que o `thread.json` diz viva e o runtime nao conhece aparece como divergencia.
+- **A memoria e opcional e declarada.** O handoff carrega o regime (`files` ou `orkmind`) e os
+  ponteiros dizem QUANDO devem ser resolvidos. Com OrkMind fora do ar, o mesmo ponteiro resolve
+  por `path#ancora`, e nenhum ciclo para por causa disso.
+
+## Racionalizacoes comuns
+
+| Desculpa | Realidade |
+|---|---|
+| "A conversa ainda tem todo o contexto, nao preciso ler o disco" | Conversa termina e janela rotaciona. Trabalho nao registrado e trabalho nao retomavel e nao auditavel. |
+| "E mais rapido editar o thread.json na mao" | Editar estado na mao corrompe estado. Todo campo tem um comando que o escreve, e o comando tambem registra no ledger. |
+| "Vou consertar o ledger que ficou errado" | O ledger e append-only. Correcao e evento novo. Historico editado nao e mais historico, e narrativa. |
+| "Vou carregar o handoff inteiro na sessao nova" | O handoff separa inline de ponteiro de proposito. `ork recall <thread> --fase <FASE>` traz so o que e daquele momento; o resto continua endereçado, nao perdido. |
+| "Duas threads no mesmo arquivo, mas elas nao se cruzam" | Quem decide isso e o lease, nao a intuicao. `ork lease list` mostra colisao de regiao e a fila. |
+
+## Bandeiras vermelhas
+
+- Diretorio de thread sem `thread.json` ou sem `ledger.jsonl`.
+- Prompt despachado sem arquivo correspondente em `prompts/` com o sha no nome.
+- Sessao gravada como viva que o runtime nao reconhece.
+- Lease vencido com a thread ainda escrevendo na regiao.
+- Manifesto pedindo `memory.mode: orkmind` com `ork memory status` reportando regime efetivo
+  `files`: a memoria semantica nao esta valendo, e o motivo tipado diz por que.
+
+## Verificacao antes de sair da skill
+
+Thread identificada pelo id, estado lido por comando e nao por memoria, fase atual conhecida, e
+qualquer divergencia entre disco e runtime dita em voz alta. Ver `DoD 4`.

package/skills/governance/decision-triage/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: decision-triage
+description: "A disciplina de delegacao: classifica cada decisao em classe 1 (humano decide), 2 (contrato publico, exige ratificacao) ou 3 (delegada, registrada), e sobe tradeoff real com opcoes e uma recomendacao. Roteia para ork gate approve."
+bucket: governance
+roteia: "ork gate approve <thread> <sobre> --por <quem>"
+license: MIT
+---
+
+# Decision Triage
+
+## O que esta skill e
+
+Um roteador fino da disciplina de delegacao. Ela nao decide pelo humano e nao esconde decisao
+atras de "detalhe tecnico": ela classifica, registra o que e delegado e sobe o que e do humano.
+**Decisao delegada sem registro e decisao perdida.**
+
+## As tres classes
+
+| Classe | Quem decide | O que exige |
+|---|---|---|
+| 1 | O humano, sempre | Tradeoff de produto, risco de negocio, prioridade, escopo, dinheiro |
+| 2 | O humano, com ratificacao registrada | Mudanca de contrato publico versionado: schema, tipos de evento, layout de estado, interface |
+| 3 | Delegada ao agente | Escolha interna sem efeito observavel fora do modulo, registrada no ledger quando relevante |
+
+## Como rotear
+
+```bash
+ork gate approve <thread> <sobre> --por <quem>   # decisao humana registrada
+ork phase list <thread>                          # a auditoria de delegacao le daqui
+```
+
+## Conduta
+
+1. **Classificar antes de agir**, nao depois de ter agido.
+2. **Subir tradeoff com opcoes e exatamente uma recomendacao.** Subir sem recomendacao empurra o
+   trabalho de volta ao humano; subir sem opcoes pede assinatura, nao decisao.
+3. **Registrar a classe 3 relevante.** O qualificador carrega peso: formatacao e nome interno
+   tambem sao classe 3, e exigir evento para cada um deles e escalacao indevida.
+4. **Auditar os dois lados com peso igual.** Subclassificar (tratar decisao de produto como
+   detalhe tecnico) e escalar indevidamente (pedir aval para trivialidade) sao defeitos do mesmo
+   tamanho, e a auditoria de CHECK caca os dois.
+5. **Decisao fechada trava.** Reabrir e decisao nova, com registro proprio, nunca edicao silenciosa.
+
+## Racionalizacoes comuns
+
+| Desculpa | Realidade |
+|---|---|
+| "Isso e detalhe tecnico, decido sozinho" | Se muda o que o usuario ve, o que o produto promete ou o que custa dinheiro, e classe 1. Subclassificar e a forma educada de decidir pelo humano. |
+| "Pergunto tudo, assim ninguem reclama" | Escalacao indevida e defeito de igual peso. Quem pergunta tudo transfere o trabalho e some com a delegacao. |
+| "Subo a duvida e o humano escolhe" | Sem opcoes e sem uma recomendacao, isso e transferir o problema. Traga o mapa e diga por onde ir. |
+| "Mudo o schema, e compativel na pratica" | Contrato publico versionado e classe 2: exige ratificacao registrada antes do merge, mesmo quando parece compativel. |
+| "A decisao mudou, atualizo o texto antigo" | Decisao fechada trava. Reabertura e decisao nova com registro; editar a antiga apaga a razao da primeira. |
+
+## Bandeiras vermelhas
+
+- Mudanca de contrato publico no diff sem gate de ratificacao no ledger.
+- Uma serie de decisoes de produto aparecendo so no resumo final da fase.
+- Pergunta ao humano sobre nome de variavel enquanto o escopo mudou sem aviso.
+- Decisao registrada em dois lugares com redacoes diferentes.
+
+## Verificacao antes de sair da triagem
+
+Cada decisao com classe atribuida, as de classe 1 e 2 subidas com opcoes e uma recomendacao, as de
+classe 3 relevantes registradas no ledger, e nenhuma decisao fechada reaberta em silencio. Ver
+`DoD 5`, `DoD 12` e `DoD 20`.

package/skills/governance/narrative-guardian/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: narrative-guardian
+description: "Auditoria de canon: confere que todo artefato publico do produto diz a mesma coisa que o codigo faz, sem numero sem origem, sem promessa de capacidade inexistente e sem metrica inventada. Roda antes de qualquer publicacao."
+bucket: governance
+roteia: "ork verify <thread> | ork phase list <thread>"
+license: MIT
+---
+
+# Narrative Guardian
+
+## O que esta skill e
+
+Um roteador fino da auditoria de canon. Ela compara o que os artefatos publicos afirmam com o que
+o codigo e o ledger provam. **Numero sem origem nao entra em documento publico**, e capacidade que
+nao existe nao vira promessa em README.
+
+## Quando usar
+
+- Antes de publicar README, doc de produto, changelog, post ou pagina de marketing.
+- Ao fim de toda thread que muda documentacao voltada para fora.
+- Sempre que um artefato cita metrica, tempo, contagem ou comparacao.
+
+## Como rotear
+
+```bash
+ork verify <thread>        # o que a maquina realmente prova hoje
+ork phase list <thread>    # a origem de cada evidencia citada
+ork master --batch         # o que ja foi fechado e pode ser citado como entregue
+```
+
+## As regras do canon
+
+1. **Todo numero publicado tem origem colada.** Comando, saida, data. Numero de memoria nao entra.
+2. **Capacidade descrita e capacidade que existe hoje.** Roadmap se escreve como roadmap, no futuro
+   declarado, nunca no presente do indicativo.
+3. **Metrica de tempo e cronometrada, nao estimada com otimismo.** A promessa de quinze minutos do
+   quickstart vale porque o run foi executado e o registro publicado junto.
+4. **Lacuna e publicada como lacuna.** `unavailable` com o motivo, nunca zero, nunca omissao.
+5. **Divergencia entre doc e codigo e defeito do doc**, e vira tarefa, nao nota de rodape.
+
+## Racionalizacoes comuns
+
+| Desculpa | Realidade |
+|---|---|
+| "Uns 15 minutos, e mais ou menos isso" | Metrica de tempo e cronometrada. Numero sem origem vira promessa que o primeiro usuario desmente. |
+| "Vai existir na proxima versao, ja escrevo no presente" | Capacidade descrita e capacidade que existe hoje. Roadmap escrito como presente e a mentira que matou o produto original. |
+| "Deixo o campo vazio, ninguem repara" | Lacuna publicada como lacuna. Campo vazio vira zero na proxima leitura, e zero e um dado. |
+| "O doc esta desatualizado, mas o codigo esta certo" | Divergencia entre doc e codigo e defeito do doc, com tarefa propria. Doc errado e o produto errado para quem le. |
+| "Comparei com o concorrente de cabeca" | Comparacao publicada precisa de metodo e data. Sem isso, e propaganda com cara de dado. |
+| "O time todo sabe que esse numero e aproximado" | Quem le de fora nao sabe. Aproximacao publicada declara que e aproximacao. |
+| "Tiro o `unavailable`, fica feio no README" | Feio e o numero falso descoberto depois. A honestidade de medicao e parte do produto, nao um detalhe de formatacao. |
+| "Isso e detalhe de marketing, nao de engenharia" | O artefato publico e superficie do produto. O canon vale igual nos dois lados. |
+
+## Bandeiras vermelhas
+
+- Numero em documento publico sem comando ou data ao lado.
+- Verbo no presente para funcionalidade de roadmap.
+- Benchmark citado sem maquina, regime e repeticao.
+- Campo de metrica em branco em vez de `unavailable`.
+- Changelog citando entrega sem MASTER log correspondente.
+
+## Verificacao antes de publicar
+
+Todo numero com origem, toda capacidade conferida contra o codigo, todo tempo cronometrado, toda
+lacuna declarada, e nenhuma divergencia entre o artefato e o que o ledger prova. Ver `TEST 12`,
+`PERF 9` e `PERF 10`.

package/skills/governance/roadmap-keeper/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: roadmap-keeper
+description: "Guardiao do roadmap: toda demanda entra registrada antes de virar thread, toda proposta de auditor vira item com origem, e nada some do escopo sem decisao registrada. Roteia para ork board e ork thread new."
+bucket: governance
+roteia: "ork board | ork board plan | ork thread new"
+license: MIT
+---
+
+# Roadmap Keeper
+
+## O que esta skill e
+
+Um roteador fino entre a demanda e a thread. Ela nao prioriza no lugar do humano: ela garante que
+toda demanda esteja escrita antes de virar trabalho, com origem, e que nada saia do escopo em
+silencio. **Demanda que vira thread sem estar registrada e trabalho sem dono e sem historia.**
+
+## Como rotear
+
+```bash
+ork board                       # o estado de todas as threads
+ork board plan                  # quem avanca agora, quem espera e por que
+ork thread new "<nome>" --mode <modo>
+ork master --batch              # o que fechou e ainda espera score
+```
+
+## Conduta
+
+1. **Registrar antes de abrir.** A demanda entra com titulo, origem e o problema que resolve, e so
+   entao vira `ork thread new`.
+2. **Origem sempre.** Pedido do builder, achado de auditor, licao de MASTER log: quem pediu fica
+   escrito. Item sem origem nao sabe por que existe e nao sabe quando morrer.
+3. **Proposta de auditor entra como proposta**, nunca como correcao ja aplicada. O auditor le, o
+   roadmap decide.
+4. **Item que sai do escopo sai com decisao registrada**, com quem decidiu e por que. Escopo que
+   encolhe em silencio e escopo que reaparece como surpresa.
+5. **A capacidade da maquina limita o quadro.** `concurrency.max_parallel_threads` no manifesto e o
+   teto real; roadmap que ignora o teto vira fila disfarcada de plano.
+
+## Racionalizacoes comuns
+
+| Desculpa | Realidade |
+|---|---|
+| "Abro a thread agora e registro depois" | Registrar depois e registrar do jeito que a memoria contar. A demanda entra escrita, com origem, antes de virar trabalho. |
+| "Esse item obviamente saiu do escopo" | Obvio para quem estava na conversa. Saida de escopo e decisao registrada, ou vira surpresa na entrega seguinte. |
+| "O auditor achou, ja corrijo direto" | Auditor propoe, roadmap decide. Correcao aplicada direto por auditor e mudanca sem dono e sem gate. |
+| "Cabe mais uma thread em paralelo, e pequena" | O teto e o do manifesto, medido, nao o do otimismo. Acima dele as threads competem por arvore e por atencao humana. |
+| "Isso e obviamente prioridade, nem precisa perguntar" | Prioridade e decisao de classe 1, do humano. O roadmap organiza a escolha; ele nao faz a escolha. |
+
+## Bandeiras vermelhas
+
+- Thread aberta sem item de roadmap correspondente.
+- Item sem origem escrita.
+- Achado de auditor aplicado como correcao direta.
+- Escopo reduzido sem registro de quem decidiu.
+- Numero de threads ativas acima do teto do manifesto.
+
+## Verificacao antes de sair da skill
+
+Demanda registrada com origem, teto de paralelismo respeitado, propostas de auditor tratadas como
+propostas, e toda mudanca de escopo com decisao registrada. Ver `DoD 20` e `REVIEW 11`.

package/skills/governance/scope-check-capability-map/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: scope-check-capability-map
+description: "Fase 0: antes de abrir a thread, confere se a demanda cabe no que o produto e no que a maquina conseguem fazer, e devolve o que falta em vez de comecar trabalho fadado a parar no meio."
+bucket: governance
+roteia: "ork doctor | ork board plan | ork thread new --dry-run"
+license: MIT
+---
+
+# Scope Check e Capability Map
+
+## O que esta skill e
+
+Um roteador fino da fase 0. Ela roda antes do GOAL e responde uma pergunta so: **esta demanda cabe
+no que existe hoje?** Se nao cabe, ela devolve o que falta, com nome, antes de qualquer thread
+consumir janela de contexto.
+
+## Como rotear
+
+```bash
+ork doctor                                # o que vale nesta maquina agora
+ork board plan                            # capacidade ocupada e capacidade livre
+ork thread new "<nome>" --mode <modo> --dry-run   # ensaio: slug, modo, blocos, sem gravar
+```
+
+## O mapa de capacidade
+
+1. **Capacidade de maquina.** Runtime disponivel, assinatura valida, provider correto. Um `fail` do
+   `ork doctor` para o ciclo antes de ele abrir, e isso e economia, nao obstaculo.
+2. **Capacidade de paralelismo.** Threads ativas contra `concurrency.max_parallel_threads`, mais os
+   leases que ja estao tomados na regiao que a demanda vai tocar.
+3. **Capacidade de produto.** O que a demanda pede existe no produto, ou e capacidade nova. Se e
+   nova, isso e dito no scope check e nao descoberto no GO.
+4. **Capacidade de decisao.** A demanda depende de decisao que so o humano toma? Entao ela nasce
+   com o gate previsto, nao com uma surpresa no meio.
+
+## O contrato de devolucao
+
+Quando a demanda nao cabe, a devolucao **nomeia o que falta e o que destravaria**, em uma linha
+cada. Devolver "nao da" sem o que falta e recusa, nao scope check.
+
+## Racionalizacoes comuns
+
+| Desculpa | Realidade |
+|---|---|
+| "Comeco e vejo no caminho o que falta" | Descobrir a falta no GO custa a thread inteira. O scope check custa um comando. |
+| "O doctor esta com um fail, mas nao e desse ponto" | Um `fail` do doctor e a maquina dizendo que o despacho nao vale. Abrir mesmo assim gasta janela para parar no mesmo lugar. |
+| "Cabe mais uma thread, dou conta" | Quem da conta e a maquina e o humano que aprova gate, e os dois tem teto medido no manifesto. |
+| "A demanda e vaga, o GOAL esclarece" | GOAL esclarece objetivo, nao existencia de capacidade. Demanda que pede o que nao existe volta antes, com o que falta escrito. |
+
+## Bandeiras vermelhas
+
+- Thread aberta com `ork doctor` em `fail`.
+- Demanda que pede capacidade inexistente sem isso estar escrito.
+- Regiao de arquivos ja sob lease de outra thread, sem fila prevista.
+- Devolucao sem dizer o que destravaria a demanda.
+
+## Verificacao antes de abrir a thread
+
+Doctor lido, capacidade de paralelismo conferida, capacidade de produto confirmada ou declarada
+ausente, gates humanos previstos, e ensaio com `--dry-run` mostrando slug, modo e blocos. Ver
+`DoD 17`.