@orkastery/cli 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Orkastery
+Copyright (c) 2026 Julio Pessoa
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,87 +1,108 @@
-# core/, o núcleo `ork`
+# @orkastery/cli, the `ork` core
 
-Núcleo CLI determinístico do Orkastery (Camada 2, o Looping Threads Maestro).
-**Sem LLM embutido**: o `ork` monta prompt, despacha pelo runtime adapter, verifica no
-mundo real e registra no ledger. Quem escreve código e a orquestra (Camada 3); quem
-decide e o humano.
+**Your agents say "done". `ork` re-runs it.**
 
-## Instalar
+`ork` conducts coding agents (Claude Code, Codex) through six-phase threads, verifies every
+claim by re-running the command that proves it, and only delivers with the push proven on the
+remote. It has no embedded LLM: it assembles the prompt, dispatches through the CLI of the
+runtime you already use, checks the result in the real world and records everything in an
+append-only ledger.
 
-Publicado no npm como **`@orkastery/cli`**. O nome curto `ork` no registry pertence a outro
-projeto, mas o binario instalado continua sendo `ork`:
+- **Truth, not a report.** Every statement becomes a claim with the command that judges it.
+  `ork verify` re-runs it on the thread's real HEAD and, with `ci.required_for_ship`, CI re-runs
+  it again on an independent runner before the merge.
+- **You choose how often you are called.** One mode per #TAG, in the request itself, decides
+  where the cycle pauses. Verification is the same in all of them.
+- **Subscription, never pay-per-token.** Dispatch uses the runtime CLI's own login. `ork` never
+  reads credentials, and the `subscription-only` policy blocks paid providers.
+
+The CLI and the docs are in Brazilian Portuguese today.
+
+## Install
+
+Requires Node.js 20 or newer, git and at least one runtime logged in to your subscription
+(`claude` or `codex`).
 
 ```bash
 npm install -g @orkastery/cli
-ork doctor
+ork demo            # 30 seconds: a false claim rejected, the fixed one accepted; no account, no model
+ork doctor          # what holds on this machine right now (exits != 0 when something blocks)
 ```
 
-O tarball leva junto o catalogo do produto (`skills/`, `references/`, `eval/` e `adapters/`),
-entao `ork eval` e `ork adapter install` funcionam a partir da instalacao global.
+The package ships the product catalog too (skills, references, eval and host adapters), so
+`ork eval` and `ork adapter install` work from the global install.
 
-## Compilar deste repositorio
+## First steps
 
 ```bash
-cd core
-npm install
-npm run build        # gera dist/index.js (bin `ork`)
-npm test             # compila e roda a suite (node --test)
-npm link             # opcional: poe o `ork` desta arvore no PATH
+cd your-repository
+ork init                                          # writes the orkastery.yaml
+ork thread new "fix the date filter" --modo classic --worktree auto
+ork phase run <thread> GOAL --prompt "the filter ignores the user's time zone"
+ork claims add <thread> src/filter.ts --claim "respects the time zone" --verificar "npm test -- filter"
+ork verify <thread>                               # re-runs the claims on the real HEAD
+ork ship <thread> --para main                     # serialized merge and proven push
 ```
 
-O `prepack` roda o build e copia o catalogo da raiz do repositorio para dentro de `core/`; o
-`postpack` remove as copias. E por isso que `npm pack` e `npm publish` levam o produto inteiro
-sem que essas pastas existam na arvore versionada de `core/`.
+`ork board` shows every thread, and `ork pulse` gathers what needs you right now.
+
+## The four modes
 
-## Comandos
+The #TAG goes in the request itself. The mode changes **where** the cycle waits for you:
+
+| #TAG | Pauses | Cycle | What it is for |
+| --- | --- | --- | --- |
+| `#Classic` | 3 | `GOAL* / PLAN* / GO-CHECK* / SHIP-MASTER` | The default: delicate premises |
+| `#Maestro` | 1 | `GOAL-PLAN* / GO-CHECK-SHIP / MASTER` | A clear solution, moving fast |
+| `#Auto` | 0 | `GOAL-PLAN-GO-CHECK-SHIP-MASTER` | Docs, studies, configuration, audits |
+| `#Fast` | 0 | `GO` | A small, clear request that takes minutes |
+
+`*` marks the block that pauses. `#Fast` runs only the GO, with minimal proof (a focused test, a
+cheap claim, or an absence declared in the ledger). It does not authorize a push on its own and
+does not touch public contract files. `ork modos` is the source of truth.
+
+```text
+The mode relaxes the PAUSE. The mode NEVER relaxes VERIFICATION.
+```
+
+## Hosts
+
+`ork` talks to the host through thin adapters. Every rule lives in the core:
 
 ```bash
-node dist/index.js doctor                 # o que vale nesta maquina agora
-node dist/index.js init                   # gera o orkastery.yaml do repo
-node dist/index.js modos                  # tabela dos 5 modos de conducao
-node dist/index.js thread new "<nome>" --modo default
-node dist/index.js thread list
-node dist/index.js thread status <thread-id>
-node dist/index.js phase run <thread-id> GOAL --prompt "<pedido>"
-node dist/index.js phase list <thread-id>
-node dist/index.js sessions [--all]
-node dist/index.js sessions logs|stop|attach <sessao>
+ork adapter list
+ork adapter install claude-code     # also: codex, hermes, openclaw
 ```
 
-Bloco B1 (verdade, gate de tokens, handoff e entrega):
+## Most used commands
+
+| Command | What it does |
+| --- | --- |
+| `ork doctor` | Checks runtime, manifest, cost policy and sessions |
+| `ork thread new <name> --modo <mode>` | Creates the thread, the slug and the ledger |
+| `ork phase run <thread> <PHASE> --prompt "..."` | Dispatches the phase on the block's runtime |
+| `ork claims add` / `ork verify` | Records claims and re-runs them |
+| `ork ci prepare` / `ork ci run` | Takes the claims to the independent CHECK in CI |
+| `ork ship <thread> --para main` | Merge serialized by lease, with the push proven by `ls-remote` |
+| `ork board` / `ork pulse` | View of the threads and of the human attention queue |
+| `ork setup <mode>` | Runtime, model and effort per block of each mode |
+
+The full list comes from `ork help`.
+
+## Build from this repository
 
 ```bash
-node dist/index.js claims add <thread-id> <arquivo> --claim "<alegacao>" --verificar "<comando>"
-node dist/index.js claims list|verificar|retirar <thread-id> [...]
-node dist/index.js verify <thread-id> [--baseline] [--so-claims]
-node dist/index.js gate next <thread-id> [--proximo FASE] [--ocupacao 0..1] [--transcript ARQ]
-node dist/index.js gate approve <thread-id> push --por <quem>
-node dist/index.js handoff export <thread-id> [--proxima-fase FASE]
-node dist/index.js handoff recall <thread-id> "<path#ancora>"
-node dist/index.js ship <thread-id> --para main [--autorizar-push <quem>] [--dry-run]
-node dist/index.js lease list|release <nome>
+cd core
+npm ci
+npm run build        # writes dist/index.js (the `ork` bin)
+npm test             # builds and runs the suite (node --test)
+npm link             # optional: puts this tree's `ork` on the PATH
 ```
 
-## Mapa dos módulos
-
-| Arquivo | Papel |
-|---|---|
-| `src/index.ts` | CLI: parse de argumentos e roteamento dos subcomandos |
-| `src/doctor.ts` | Checks de ambiente, manifesto, abbrev, custo/provider e sessões |
-| `src/init.ts` | Detecção do repo e geração do `orkastery.yaml` |
-| `src/thread.ts` | Estado da thread em disco, slug, base carimbada, listagem |
-| `src/phase.ts` | Montagem do prompt da fase, despacho e leitura do ledger |
-| `src/modos.ts` | Matriz dos 5 modos de condução e parse da #TAG |
-| `src/slug.ts` | Slug de 3 partes, regex canonica e rotação de sessão |
-| `src/ledger.ts` | Ledger JSONL append-only por thread |
-| `src/manifest.ts` | Leitura e validação do manifesto (com fallback `devmaster.yaml`) |
-| `src/yaml.ts` | Leitor do subconjunto de YAML usado pelo manifesto (sem dependência) |
-| `src/adapters/claude-bg.ts` | Runtime adapter: `claude --bg`, `claude agents`, logs e stop |
-| `src/sessoes.ts` | Observabilidade: cruza o runtime real com o registrado nas threads |
-| `src/claims.ts` | Alegações verificaveis por thread (`claims.jsonl`) e a regra da alegação negativa |
-| `src/verify.ts` | Reexecucao no HEAD real, baseline e classificação regressão vs pré-existente |
-| `src/gates.ts` | Catálogo de motivos tipados de gate e registro de aprovação humana |
-| `src/policies.ts` | Policies do manifesto executaveis, por gate e por severidade |
-| `src/leases.ts` | Leases com aquisição atômica e TTL (o `main-tree` serializa o ship) |
-| `src/ship.ts` | Merge --no-ff serializado, verificado, e push provado por `ls-remote` |
-| `src/tokens.ts` | Gate de tokens: medida honesta da janela e veredito de rotação |
-| `src/handoff.ts` | Handoff triado em 3 níveis com proveniência, e o recall dos ponteiros |
+`prepack` builds and copies the catalog from the repository root into `core/`, and `postpack`
+removes the copies. That is why `npm pack` and `npm publish` ship the whole product without
+those folders existing in the versioned tree of `core/`.
+
+## License
+
+MIT. Full documentation, roadmap and changelog in the Orkastery repository.

package/adapters/README.md

@@ -1,22 +1,37 @@
 # adapters/
 
-Adaptadores de host (Camada 1: Hermes, OpenClaw, plugin do Claude Code, CI e cron).
+Adaptadores de host (Camada 1): Claude Code, Codex, Hermes e OpenClaw.
 
-Eles traduzem intencao em chamada de `ork`, apresentam gates ao humano e registram decisoes.
-**Zero regra de negocio.** O parse da #TAG de modo de conducao acontece aqui e vira `--mode` no
-`ork thread new`, mas nem o parse e reimplementado: o host chama `ork modos --do-pedido`, que usa a
-`extrairTagDoPedido` do nucleo. A validacao contra `conduction.allowed_modes` e do nucleo.
+Eles traduzem intenção em chamada de `ork`, apresentam gates ao humano e registram decisões.
+**Zero regra de negócio.** Nem o parse da #TAG de modo é reimplementado aqui: o host chama
+`ork modos --do-pedido`, que usa a `extrairTagDoPedido` do núcleo, e a validação contra
+`conduction.allowed_modes` também é do núcleo.
 
-| Host | O que entra | Instalacao |
-|---|---|---|
-| [claude-code](claude-code/README.md) | Plugin com as 17 skills, 6 subagentes de fase, `/goal` ... `/master` e guard `PreToolUse` | `ork adapter install claude-code` |
-| [hermes](hermes/README.md) | Skill roteadora fina, plugin e script de abertura de thread | `ork adapter install hermes` |
-| [openclaw](openclaw/README.md) | `openclaw.plugin.json` com 16 tools `ork_*` | `ork adapter install openclaw` |
+| Host | O que entra | Instalação |
+| --- | --- | --- |
+| [claude-code](claude-code/README.md) | Plugin com as skills do catálogo, subagentes de fase, `/goal` ... `/master` e o guard `PreToolUse` | `ork adapter install claude-code` |
+| codex | Entrada `$ork` e o catálogo de condução em skills locais do projeto | `ork adapter install codex` |
+| [hermes](hermes/README.md) | Skill roteadora fina, plugin de ingresso HITL e scripts de abertura de thread | `ork adapter install hermes` |
+| [openclaw](openclaw/README.md) | Extensão (`package.json`, `dist/index.js` e manifesto) com as tools `ork_*`, instalada em `extensions/orkastery` | `ork adapter install openclaw` |
 
-Cada README traz os **3 pitfalls de instalacao** do seu host: os tres jeitos conhecidos de a
-instalacao "dar certo" e nao funcionar. O instalador cita os mesmos tres ao terminar, e o
+Cada README traz os **3 pitfalls de instalação** do seu host: os três jeitos conhecidos de a
+instalação "dar certo" e não funcionar. O instalador cita os mesmos três ao terminar, e o
 `--dry-run` mostra o que ele faria sem escrever nada.
 
-Os adaptadores de RUNTIME (Camada 3) sao outra coisa e ficam em `core/src/adapters/`, porque quem
-os chama e o nucleo: hoje `claude-bg`. O Claude Code aparece nas duas camadas, com papeis
-diferentes; confundir as duas e como o Orkastery original acabou prometendo um motor que nunca teve.
+Os adaptadores de RUNTIME (Camada 3) são outra coisa e ficam em `core/src/adapters/`, porque quem
+os chama é o núcleo: `claude-bg` e `codex`. O Claude Code aparece nas duas camadas, com papéis
+diferentes, e confundir as duas é o jeito mais rápido de prometer um motor que não existe.
+
+## Paridade Maestro
+
+A frase `orkastery maestro` consulta o mesmo contrato do núcleo nas quatro
+instalações: MCP no Codex e no Claude, wrapper argv no Hermes e tool argv no OpenClaw.
+O instalador inclui entrada, callback e recibo de arquivos; instalação não prova
+ativação em sessão nova. `maestro-parity.test.ts` compara o contrato canônico e
+instalações temporárias. Os testes específicos de cada adaptador exercitam o
+transporte fixture; os recibos live são uma etapa posterior e separada.
+
+Usabilidade HITL é prioridade máxima: recomendação, opções claras e canal disponível
+associado ao pedido. MCP local conserva elicitation; Telegram segue disponível
+quando configurado. Ingresso nativo Hermes/Discord e OpenClaw depende de callback
+autenticado e binding privado; terminal Hermes/ACP não está homologado.

package/adapters/claude-code/.claude-plugin/plugin.json

@@ -3,7 +3,9 @@
   "displayName": "Orkastery",
   "description": "Conducao de looping threads em 6 fases com gates humanos, estado em disco e MASTER log com score de 0 a 5. As skills sao roteadores finos: quem executa e o nucleo `ork`.",
   "version": "{{versao}}",
-  "author": { "name": "Julio Pessoa e contribuidores do Orkastery" },
+  "author": {
+    "name": "Julio Pessoa e contribuidores do Orkastery"
+  },
   "license": "MIT",
   "skills": [
     "./skills/core/orkastery-bootstrap",
@@ -22,10 +24,14 @@
     "./skills/reviewers/code-reviewer",
     "./skills/reviewers/security-auditor",
     "./skills/reviewers/test-engineer",
-    "./skills/reviewers/web-performance-auditor"
+    "./skills/reviewers/web-performance-auditor",
+    "./skills/core/onboarding"
   ],
   "commands": "./commands",
-  "agents": "./agents",
-  "hooks": "./hooks/hooks.json",
-  "keywords": ["orquestracao", "metodologia", "governanca", "telemetria"]
+  "keywords": [
+    "orquestracao",
+    "metodologia",
+    "governanca",
+    "telemetria"
+  ]
 }

package/adapters/claude-code/README.md

@@ -1,14 +1,17 @@
 # Adaptador Claude Code
 
-O Orkastery chega ao Claude Code como **plugin**: as 17 skills finas do catalogo, seis subagentes
+O Orkastery chega ao Claude Code como **plugin**: as 18 skills finas do catalogo, seis subagentes
 de fase, os slash commands `/goal` ... `/master` e um guard `PreToolUse`.
 
 ## Instalacao
 
 ```bash
-ork adapter install claude-code                 # instala em <projeto>/.claude
-ork adapter install claude-code --dir ~/.claude # instala para todos os projetos da maquina
-ork adapter install claude-code --dry-run       # lista o que seria escrito, sem escrever
+ork adapter install claude-code --dry-run
+ork adapter install claude-code # prepara <projeto>/.claude/plugins/orkastery
+claude plugin validate .claude/plugins/orkastery
+claude plugin marketplace add "$PWD/.claude/plugins/orkastery" --scope project
+claude plugin install orkastery@orkastery --scope project
+claude plugin details orkastery
 ```
 
 O instalador copia o catalogo unico de `skills/` e `references/`, renderiza o manifesto do plugin
@@ -16,6 +19,37 @@ com os caminhos declarados um a um, e grava `INSTALADO.json` com a origem e o sh
 arquivo. E esse arquivo que permite detectar depois que alguem editou a copia instalada em vez do
 catalogo.
 
+Copiar o adaptador não habilita o plugin no Claude. Os comandos nativos acima registram
+o marketplace e habilitam o plugin no projeto atual. Confirme primeiro que o nome
+`orkastery` não pertence a outro marketplace e preserve as configurações existentes.
+O manifesto usa a descoberta padrão de `agents/` e `hooks/hooks.json`: declarar o
+diretório como `agents` é inválido no Claude 2.1.263; declarar novamente o arquivo
+padrão em `hooks` provoca erro de carregamento por duplicação.
+
+O escopo precisa ser provado em cada worktree. Nos ensaios do Claude 2.1.263,
+`--scope project` habilitou os diretórios configurados explicitamente, enquanto
+`--scope local` na main também alcançou uma worktree não configurada. Não use esse
+último mecanismo para excluir threads. O [plano de ativação](ACTIVATION.md) descreve
+preservação, exclusões, prova de despacho e rollback antes de uso operacional.
+
+Validação, instalação e startup nativos sem modelo:
+
+```bash
+npm --prefix core run build
+npm --prefix core run build:test
+node adapters/claude-code/test/native-plugin.cjs
+```
+
+O teste cria projeto e worktrees pela API do `ork`, isola cache/configuração com
+`CLAUDE_CONFIG_DIR` e verifica o startup do CLI, além do inventário. Uma worktree
+não habilitada e outro projeto devem carregar zero hooks. O teste explícito
+`node adapters/claude-code/test/native-plugin.cjs --smoke` também abre duas sessões
+reais e exige `PermissionRequest` no ledger canônico, sem aprovar Bash. Esse smoke
+exige Linux, Python 3/pexpect e OAuth de assinatura em `ANTHROPIC_TOKEN` no arquivo
+`~/.hermes/.env`; não usa chave API nem fallback. A configuração global
+permanece fora da fixture. As sessões e os ledgers temporários são descartados;
+guarde a saída JSON como recibo antes de declarar a prova concluída.
+
 ## O que voce ganha
 
 | Voce digita | Voce recebe |
@@ -50,6 +84,64 @@ verifica. Comando que comeca com `ork` passa direto, porque quem prova o push e
 o nucleo. E se o proprio guard quebrar, ele **libera**: um hook que derruba a sessao por bug proprio
 e pior que nenhum hook.
 
+## Sensores de sessão
+
+`PermissionRequest`, `Notification`, `Stop`, `SubagentStop` e `PostToolUse` chamam
+`ork sessions event` com a sessão e o diretório fornecidos pelo Claude. A sessão deve
+estar registrada em uma thread do projeto. `ORK_SENSOR_CLI` pode apontar para o executável
+do ork instalado; o padrão é `ork` no PATH. Cada chamada tem timeout de três segundos.
+
+O sensor deixa stdout vazio e sai com código zero, inclusive em falha. Ele observa o
+bloqueio, sem decidir a permissão. `PermissionRequest` captura a solicitação imediata;
+`Notification` com `permission_prompt` só ocorre após cerca de seis segundos, conforme a
+[referência de hooks](https://code.claude.com/docs/en/hooks#permissionrequest).
+
+O ledger recebe carimbos e identificadores, sem prompts, comandos ou transcrições.
+`PostToolUse` registra progresso; para Bash, um recibo de commit só é emitido quando o
+resultado contém o SHA do HEAD confirmado no Git. O comando recebido nunca é executado.
+`Stop` e `SubagentStop` são observações distintas e não aprovam uma fase.
+
+Teste de integração isolado: `npm --prefix core run build && npm --prefix core run build:test && node --test core/dist-test/test/claude-sensors.test.js`.
+
+O canário `node core/dist/index.js eval --so-canarios --canario fx-sensores-runtime`
+integra hook, CLI, supervisor e watcher em um repositório temporário. Seus eventos Codex
+são sintéticos; a saída identifica esse limite e mede ingestão, morte e duplicatas.
+
+Para homologação com as assinaturas autenticadas, execute explicitamente:
+
+```bash
+node core/scripts/smoke-sensores.cjs --runtime claude
+node core/scripts/smoke-sensores.cjs --runtime codex
+```
+
+O harness exige usuário comum; Claude exige Python 3 com `pexpect`. Ele cria um projeto
+temporário e aceita a confiança somente nesse projeto que acabou de criar. Claude roda
+em PTY com permissão de Bash obrigatória: o teste observa o diálogo real, o instante do
+hook e a ingestão no ledger, e encerra a sessão sem aprovar a ferramenta. A saída inclui
+o código/sinal desse encerramento controlado, sem alegar resposta ou aprovação humana.
+Codex executa um comando curto e o harness confere o arquivo produzido, tokens, rollout
+e recibo supervisionado. A descoberta do rollout é refeita no término porque sua criação
+pode ocorrer após `thread.started`. O sandbox vem de `runtime.sandbox` do manifesto
+do diretório de execução, sem override do harness. A prova de escrita em `read-only`
+falha, preservando o modo configurado.
+
+Cada comando emite JSON e retorna código 1 quando falta a prova. Variáveis de credenciais
+e redirecionamento de API paga são removidas; não há fallback. HOME, CODEX_HOME,
+CLAUDE_CONFIG_DIR, XDG e temporários ficam dentro da tentativa, junto dos ledgers.
+O recibo lista os arquivos nativos e confirma a limpeza apenas desses recursos.
+Claude usa OAuth de assinatura somente no ambiente. Codex lê seu cache nativo por
+`memfd` Linux selado, sem cópia persistente de credenciais ou escrita na origem.
+Refresh que precise escrever no cache torna a prova indisponível. Veja os limites
+e o tratamento do rollout legado de T9 no [plano de ativação](ACTIVATION.md).
+Guarde o JSON no diretório de evidências da thread
+condutora. O teste de contrato do harness não dispara runtimes nem substitui esses smokes.
+O prompt de permissão de rede do sandbox tem um fluxo distinto, descrito na
+[referência de PermissionRequest](https://code.claude.com/docs/en/hooks#permissionrequest).
+
+Sem `tool_use_id`, cada invocação do hook recebe uma identidade de ocorrência. O tamanho
+do transcript não identifica uma ocorrência; eventos de um novo episódio de permissão
+podem chegar sem alteração do arquivo. Replays com `tool_use_id` continuam idempotentes.
+
 ## A #TAG de conducao
 
 O comando `/goal` extrai o modo do proprio pedido, sem reimplementar nada:
@@ -71,9 +163,11 @@ tres e o `--dry-run` mostra o que ele vai fazer sobre cada um.
 1. **Manifesto sem os caminhos das skills instala limpo e nao expoe nada.** Um plugin do Claude
    Code auto-descobre `skills/<nome>/SKILL.md` e para ai: ele nao desce nos diretorios de bucket
    (`core/`, `phases/`, `reviewers/`, ...) que este catalogo usa. Por isso `plugin.json` declara os
-   17 caminhos um a um. Depois de instalar, confira a contagem em vez de confiar no manifesto:
-   `claude plugin details orkastery` precisa reportar 17, o mesmo numero de `SKILL.md` em disco.
-   Quando divergir, quem esta errado e o manifesto.
+   caminhos um a um. O teste compara esses caminhos com o catálogo fonte e exige
+   `onboarding`, acrescentada por I15. Neste catálogo, `claude plugin details orkastery`
+   deve reportar 26 entradas: 18 skills mais oito comandos. O startup registra
+   separadamente skills e comandos. A prova anterior de T10, com 17 skills, é histórica.
+   Confira também os seis agentes e seis eventos de hooks, sem erros de carregamento.
 
 2. **Duas copias do catalogo divergem, e a divergencia so aparece quando ja custou uma entrega.**
    A fonte unica e `skills/` na raiz do produto. O instalador copia de la e grava a origem e o
@@ -84,7 +178,7 @@ tres e o `--dry-run` mostra o que ele vai fazer sobre cada um.
 3. **Hook com caminho relativo silenciosamente nao roda, e o guard vira decoracao.** O
    `hooks.json` chama `node "${CLAUDE_PLUGIN_ROOT}/hooks/ork-guard.js"`, nunca um caminho relativo
    ao diretorio de trabalho, que muda a cada worktree de thread. Depois de instalar, prove que o
-   guard esta vivo em vez de supor:
+   script do guard funciona isoladamente:
 
    ```bash
    echo '{"tool_name":"Bash","tool_input":{"command":"git add -A"}}' \
@@ -100,3 +194,11 @@ host onde o builder conversa e de onde as chamadas de `ork` saem. Ele tambem e *
 orquestra, quando o `ork` despacha `claude --bg` para escrever codigo, e esse adaptador de runtime
 mora em `core/src/adapters/claude-bg.ts`, chamado pelo nucleo. Sao papeis diferentes no mesmo
 programa, e misturar os dois e como o Orkastery original acabou prometendo um motor que nunca teve.
+# Entrada Maestro
+
+Em sessão nova com o plugin ativado, diga `orkastery maestro`. A entrada consulta
+`mcp__orkastery__ork_maestro` e apresenta fontes, lacunas e ações disponíveis.
+A instalação em fixture prova os arquivos/roteamento; ativação e conversa real
+dependem do recibo pós-SHIP. HITL prioriza recomendação, opções claras e pergunta
+nativa na condutora. Telegram é opcional. Falha de autenticação não autoriza trocar
+provider, runtime ou permissões.

package/adapters/claude-code/commands/onboarding.md

@@ -0,0 +1,21 @@
+---
+description: Conduz ou retoma a entrevista do projeto pela pauta do núcleo ork.
+argument-hint: "<pedido de onboarding>"
+allowed-tools: Bash(ork:*)
+---
+
+# /onboarding
+
+Execute `ork onboarding` para obter a pauta e `ork onboarding show --json` para consultar
+as respostas atuais. Conduza as pendências pela pauta devolvida pelo núcleo. Não duplique
+etapas ou validação neste host e não invente respostas em nome do builder.
+
+Grave a resposta pública solicitada com `ork onboarding set <etapa> --conteudo <JSON> --por <quem>`.
+Transporte o JSON como argumento, com escaping de shell adequado; nunca execute o texto recebido.
+Peça somente nomes de variáveis para credenciais. Valores secretos ficam em `~/.hermes/.env`;
+não leia esse arquivo nem transporte valores para a conversa, onboarding ou ledger.
+
+Reset solicitado usa `ork onboarding reset [etapa]`. Publicação opcional usa
+`ork onboarding sync --json`; apresente o motivo tipado de degradação sem bloquear a entrevista.
+A escolha da memória orienta o manifesto, sem editá-lo automaticamente.
+Conclua com o estado de `ork onboarding show --json`. Não crie thread para apenas entrevistar.

package/adapters/claude-code/commands/ork.md

@@ -1,37 +1,109 @@
 ---
-description: Painel do Orkastery: estado das threads, escalonador, modos e o que a maquina permite agora.
-argument-hint: "[board|plan|doctor|modos]"
-allowed-tools: Bash(ork:*), Read
+description: Reconhece orkastery maestro e conduz pedidos, retomadas e status na conversa com o Maestro/Builder.
+argument-hint: "[pedido em linguagem natural|thread|status|board|plan|doctor|modos]"
+allowed-tools: Bash(ork:*), Read, mcp__orkastery__ork_thread_status, mcp__orkastery__ork_phase_list, mcp__orkastery__ork_hitl_pending, mcp__orkastery__ork_observe, mcp__orkastery__ork_artifact_read, mcp__orkastery__ork_claims_list, mcp__orkastery__ork_git_status, mcp__orkastery__ork_thread_new, mcp__orkastery__ork_phase_run, mcp__orkastery__ork_preflight
 ---
 
-# /ork
+# /orkastery:ork
 
-Entrada geral do adaptador. Nao conduz fase nenhuma: mostra o estado e diz qual comando responde
-pela intencao do builder.
+Entrada nativa do plugin ativado no projeto: `/orkastery:ork`. A copia dos arquivos pelo
+instalador ainda exige ativacao nativa; `/ork` sozinho nao e um alias garantido.
 
-## O que este comando faz
+Esta entrada ja esta carregada pela invocacao do dono. Nao invoque `Skill(orkastery:ork)`
+nem outro comando para recarregar estas instrucoes. Conduza o pedido com as ferramentas
+ja permitidas.
+As oito consultas MCP e criar/despachar thread desta entrada valem no turno da invocacao;
+nao persistem por si nas proximas mensagens. Criar/despachar exige demanda e escopo autorizados
+pelo dono, modo resolvido e preflight do nucleo. Nao recarregue a skill para obter permissoes.
+Esses grants nao ativam MCP, nao autorizam outras mutacoes nem aprovam gates ou respostas humanas.
+
+Leia o contrato comum com `Read`, sem chamar `Skill` para carregar o bootstrap:
+@${CLAUDE_PLUGIN_ROOT}/skills/core/orkastery-bootstrap/SKILL.md
+
+Se o contrato ja estiver no contexto, use-o sem reler. Se o arquivo estiver ausente,
+informe instalacao incompleta; nao invente outro fluxo.
+
+Entrada conversacional do Orkastery. Use o contrato comum para conduzir a intencao do dono pelo nucleo. Nao limite um pedido de execucao a indicar outro
+slash command. Se recebeu um pedido e possui as ferramentas necessarias, execute o roteamento.
+Os comandos de fase continuam disponiveis como atalhos; o dono nao precisa conhece-los.
+
+## Reconhecer a intencao
+
+A frase literal `orkastery maestro`, em sessão limpa, pede leitura do panorama.
+Descubra a ferramenta com `ToolSearch` em `select:mcp__orkastery__ork_maestro`,
+então consulte o projeto fixado. Não abre thread nem despacho por consulta.
+Projeto ausente/ambíguo exige resolver o contexto permitido pelo núcleo.
+Se já recebeu fase/thread/worktree, execute o bloco recebido, sem recursão.
+MCP ausente ou autenticação negada permanece impedimento; não troque runtime,
+provider ou sandbox. A consulta CLI `ork maestro --json` não concede mutações.
+
+Usabilidade HITL é prioridade máxima: tópicos, recomendação e opções rotuladas,
+UUID interno e cancelamento preservado. A condutora usa
+`mcp__orkastery__ork_request_decision`; o filho nunca responde em nome do dono.
+
+| Pedido do dono | Acao do agente |
+|---|---|
+| Demanda nova | Resolva o modo pelo nucleo, confira o preflight e abra/despache a thread correspondente. |
+| "Continue" ou thread/roadmap existente | Leia o estado e o ultimo resultado; retome o proximo passo autorizado, sem duplicar despacho. |
+| "Como esta?" ou status | Consulte a thread conhecida; apresente progresso comprovado, impedimento e proximo passo. |
+| Decisao ou resposta | Correlacione com o pedido/gate apresentado, transporte pelo caminho suportado e confira o resultado. |
+| Onboarding | Use a pauta de `ork onboarding` e retome as etapas existentes. |
+| board, plan, doctor ou modos | Execute a consulta correspondente e interprete o resultado para a intencao do dono. |
+
+## Fontes do nucleo
+
+Priorize as ferramentas MCP do Orkastery quando descobertas nesta sessao, com o projeto
+fixado pelo servidor. No Claude, o servidor instalado `orkastery` expoe nomes completos como
+`mcp__orkastery__ork_thread_status`. Se houver ferramentas adiadas, use `ToolSearch` com
+`select:mcp__orkastery__ork_thread_status,mcp__orkastery__ork_artifact_read` para essas leituras;
+para outra operacao, selecione seu nome completo realmente exposto. Nao tente `select:ork_thread_status`
+nem adivinhe outro namespace. Ativacao inicial do MCP e consentimento do dono continuam nativos. `ork_thread_status`, `ork_phase_list` e `ork_hitl_pending` leem
+estado; `ork_thread_new` e `ork_phase_run` abrem/despacham; `ork_observe` consulta a sessao
+nativa despachada. Quando pausa/escalacao real permitir e faltar pedido, use
+`ork_gate_request(threadId, motivo?)`; nunca crie pedido para uma consulta de status.
+`ork_request_decision(threadId, pedidoId)` apresenta o dialogo ao dono:
+a resposta vem pelo host, nunca por argumento de resposta ou identidade inventada pelo modelo.
+
+As consultas CLI abaixo continuam uteis quando a ferramenta correspondente nao esta disponivel:
 
 ```bash
-ork doctor       # o que vale nesta maquina agora (sai != 0 se bloqueado)
-ork board        # todas as threads em uma visao
-ork board plan   # quem avanca agora, quem espera e por que
-ork modos        # a tabela dos 5 modos de conducao por #TAG
-ork master --batch  # o que fechou e ainda espera score humano
+ork thread status <thread>
+ork phase list <thread>
+ork pulse --json
+ork board plan
+ork doctor
+ork modos
+ork master --batch
 ```
 
-## Roteamento
+Use apenas as consultas necessarias. Nao rode todas a cada mensagem. O preflight pertence ao
+inicio de despacho ou a uma mudanca relevante de ambiente; uma pergunta de status nao reinicia
+onboarding nem trabalho. Se a thread estiver ambigua, esclareca antes de alterar seu estado.
+Pausas listadas nos blocos do modo sao previstas. Para dizer que o dono precisa responder
+agora, identifique uma pendencia atual no estado/ultimo resultado da thread, com gate,
+pedido ou evento correspondente. Uma thread nova sem fase executada nao aguarda premissas
+so porque o bloco f12 do modo preve essa pausa.
 
-| O builder quer | Comando |
-|---|---|
-| abrir demanda nova | `/goal <pedido com #TAG>` |
-| especificar | `/plan <thread>` |
-| implementar | `/go <thread>` |
-| verificar | `/check <thread>` |
-| entregar | `/ship <thread>` |
-| fechar e dar o score | `/master <thread>` |
-
-## Regras do adaptador
-
-- **Zero regra de negocio aqui.** Este comando le e apresenta; quem decide e o humano e quem
-  verifica e o `ork`.
-- Um `fail` do `ork doctor` para o ciclo antes de ele abrir, e isso e economia, nao obstaculo.
+## Continuidade
+
+Preserve modo, decisoes e autorizacoes da thread/sessao. Prossiga com trabalho autorizado em
+vez de encerrar com "posso continuar?". Pergunte quando o modo ou uma ambiguidade real exigir
+intervencao do dono e explique o que a resposta destrava. Nao aprove gates em nome dele.
+
+Com despacho existente, consulte `ork_observe` e trate a espera nativa atual. Nao substitua
+observacao por loops longos de `phase list`, sleeps ou regex de conclusao sobre historico.
+Se faltar MCP e o sandbox impedir `.git`, informe instalacao pendente do transporte nativo;
+nao repita a mutacao negada nem altere o sandbox. Diferencie permissao nativa de gate do Ork.
+
+Antes do despacho, use `ork_preflight({modo})`; alternativa CLI: `ork doctor --modo <modo>`. A sonda segue setup por bloco, sem inventário global, e não comprova autenticação, gates ou entrega.
+Para HEADs e estado Git, consulte `ork_git_status`; nao invente SHAs nem substitua o transporte por Bash Git.
+O perfil filho `worktree` e opt-in da instalacao do projeto; nao o habilite por argumento de ferramenta
+ou edicao de configuracao para contornar bloqueio. Preserve o perfil configurado e as permissoes nativas.
+
+A sessao condutora despacha e acompanha; uma sessao que ja recebeu uma fase executa essa fase,
+sem redespachar a si mesma. O nucleo continua validando fases, evidencias e gates.
+
+Mostre o resultado, o ultimo progresso confirmado e o que acontece agora. Registre checkpoint
+antes de uma retomada futura; nao prometa notificacao fora das capacidades da sessao.
+Conclua com entrega e validacao efetivas, distinguindo o que ainda depende de CHECK, SHIP ou
+score humano. A lista de comandos executados e diagnostico auxiliar, nao a experiencia do dono.

package/adapters/claude-code/hooks/hooks.json

@@ -12,6 +12,11 @@
           }
         ]
       }
-    ]
+    ],
+    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "Notification": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "Stop": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "SubagentStop": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }],
+    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/ork-sensor.js\"", "timeout": 5 }] }]
   }
 }