ll-skills 2.0.2 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/). A skill `ll-update` lê este arquivo para mostrar o que mudou entre a versão instalada e a publicada.
 
+## [3.1.0] - 2026-09-11
+
+### Adicionado
+
+- Passo `board-switch` no helper: troca o marcador de fase antes da primeira onda gravar, e `passes` recusa gravar quando o marcador é de outra fase — a onda 1 não escreve mais no lugar da fase anterior (F-1).
+- Coluna `note` e condição executável (`` `cmd` exit N ``) nas linhas de backlog nascidas em `ll-implement`; o epílogo lista quem ainda não é parseável e a fase roda `backlog-reconcile` a seco antes de fechar, reescrevendo a linha na hora (F-2).
+- Linha de progresso por onda no terminal durante uma fase (`onda i/M — M2, M3 rodando`), no despacho e no retorno de cada marco (F-4).
+- Lint rule 9 (`lint-prompts.sh`): nenhuma pergunta ao dono ou linha de contagem carrega `band-1`, `[DEC-`, `[D-` ou `ASM-`; os casos de eval que esperavam a sessão "nomear o comando" (`router-research`, `router-execute`, `router-large-opener`) foram apagados e `router-no-skill` prova o contrário — um pedido comum é feito na hora mesmo num repositório com estado; os asserts de `decide-final-round` e `implement-stops-at-next` seguem a nova redação.
+- Teto de tamanho do helper em 760 linhas / 36 000 bytes (`DEC-0016-helper-ceiling-760-36000.md`).
+- `phase-stats --since <data>` passa a incluir o próprio dia informado (F-12).
+- `ll-resume` grava a resposta a uma decisão `WAITING` no próprio arquivo da decisão.
+- Linhas de memória fora do repositório (`ll-brainstorm`, `ll-close`) declaradas na tabela de entregáveis (F-10).
+- Segunda rodada completa do laboratório: `lab/scenarios/notes-api.md` ganha os turnos 8–24 (fechamento por milestone, pesquisa, decisão sem perguntas com roadmap de quatro fases e uma decisão `WAITING`, meta autônoma, verificação externa, sabotagem seguida de reverificação, oncall, feedback em docx, refino, `ll-auto --pause-at/--resume`), `lab/README.md` ganha o protocolo de sessão isolada (`CLAUDE_CONFIG_DIR` próprio, diálogo de confiança pré-aceito, sondagem a cada 5 minutos) e `lab/rubric.md` ganha as métricas de progresso visível, integridade do board e caminhos percorridos.
+
+### Corrigido
+
+- `ll-implement --no-talk` nunca pergunta: o item que só você decide vira decisão `WAITING` e congela só os marcos que dependem dele; o resto da fase roda (era o que `ll-auto` já assumia).
+- Skill só por comando explícito: o preâmbulo global não redireciona mais nenhum pedido para uma skill, em nenhum repositório, tenha ele estado do ll-skills ou não — a sessão responde ou faz o que foi pedido, e só nomeia um comando quando o dono pergunta qual usar (feedback do dono, 2026-09-11).
+- O gate de premissas do `ll-decide` manda no máximo quatro perguntas num bloco só, com cabeçalhos limpos (sem `[PG-n]`, sem `banda 1` na tela); a restrição inventada por cautela deixou de ser pergunta — vira assunção `ASM-n [revisable]` com gatilho de revisão, contada como assunção.
+- Pergunta cujas opções só diferem em rigor de checagem não é mais feita — vira decisão por ausência (F-8).
+- A sala de decisão (`OPTIONS.html`) é entregue por caminho de arquivo antes da primeira pergunta, sem publicar artefato e sem chamar outra skill (F-5, `DEC-0017-decision-room-file-not-published.md`).
+- As telas e as perguntas ao dono não usam mais `banda 1`, `DEC-`, `ASM-`; a linha de contagem virou `perguntas N · decisões só suas em aberto K` (F-3, `DEC-0018-plain-question-headers.md`).
+- As skills chamam o helper pelo comando, nunca leem o código dele na tela do dono (F-7).
+- Script de aceitação comitado com caminho absoluto ou que mata processo alheio (`pkill`, `killall`) vira bloqueio do verificador em vez de uma ressalva (F-6).
+- O primeiro turno de um pedido grande para no comando e num plano de até 5 linhas, sem escolher formato de id nem biblioteca de IO antes da hora (F-9).
+- O laboratório aceita o diálogo de confiança da pasta antes do primeiro turno, num `CLAUDE_CONFIG_DIR` isolado — a primeira tentativa da rodada de 2026-09-11 tinha morrido nesse diálogo (F-11, `DEC-0019-lab-round-2-scope.md`).
+
+### Alterado
+
+- `lab/rubric.md`: a lista de jargão troca `gate` por `regime` (a classe de roteamento já tem nome próprio no `CLAUDE.md`; nada em `lab/` deveria repeti-la na tela do dono).
+
+## [3.0.0] - 2026-09-10
+
+### Adicionado
+
+- **`ll-auto`**: skill que roda o ciclo inteiro a partir do estado em disco — research, brainstorm, decide, fases, verificações, close — seguindo o `SKILL.md` de cada etapa em vigor, com as flags `"<objetivo>"`, `--research`, `--brainstorm`, `--interactive`, `--auto-decision`, `--pause-at <stage|N>`, `--from N`, `--to N`, `--only N`, `--verify all`, `--redo <stage>`, `--dry-run` e `--resume`; escreve `docs/AUTO.md` (objetivo, flags, roteiro, status por etapa) e lista no final toda decisão tomada sozinha, marcada `[decided by absence — revisable]`.
+- Helper `skills/ll-auto/scripts/ll-auto.js` (Node puro, sem dependências, próprio da skill): `detect`, `roteiro`, `next-cmd`, `report`, `auto-md`.
+- `--no-talk` em `ll-decide` e `ll-close`: nenhum bloco de pergunta é enviado; itens de faixa 2/3 tomam a recomendação como `ASM-n [decided by absence — revisable]`, itens de faixa 1 viram decisão `WAITING`.
+- **`ll-goal --autonomous`**: modo que aponta o texto do `/goal` para `ll-auto --auto-decision` até a entrega inteira fechar, em vez de uma fase; sem a parte BUDGET, frontmatter com `mode: autonomous` em vez de `ceiling_usd`.
+- Casos de eval `auto-dry-run` e `auto-empty-repo` (`scripts/evals/cases/`), a seção offline `evals-auto` do `scripts/smoke-test.sh` e uma repetição real de ambos via `scripts/evals/run.sh`.
+
+### Quebras
+
+- As skills não são mais invocadas pelo modelo — todas com `disable-model-invocation: true`.
+- Preâmbulo sem roteador de pedidos.
+- Descrições das skills reescritas em uma linha.
+
+### Alterado
+
+- Lint rule 1 e 3 do `lint-prompts.sh`.
+- Casos de eval `router-*` e `preamble-no-ritual` passam a exigir o comando nomeado e nenhuma chamada da ferramenta Skill; helper `no_tool_use` em `scripts/evals/lib/assert.sh`.
+
 ## [2.0.2] - 2026-09-08
 
 ### Alterado

package/README.md

@@ -1,6 +1,6 @@
 # LL Skills
 
-Um ciclo de trabalho para [Claude Code](https://claude.com/claude-code): 11 skills, 4 agentes, 3 hooks e um helper que compartilham o mesmo estado em arquivos versionados do repositório. Um preâmbulo roteador instalado no seu `~/.claude/CLAUDE.md` classifica cada pedido antes de agir — pedido pequeno continua pequeno, pedido grande cai na skill certa sem você digitar o nome dela. O produto real é a fase: `ll-implement` roda conversa, plano, revisão adversarial, ondas de execução com TDD, verificação de contexto limpo e epílogo em **uma** invocação, e escreve tudo em disco à medida que acontece, para que uma compactação não perca nada.
+Um ciclo de trabalho para [Claude Code](https://claude.com/claude-code): 12 skills, 4 agentes, 3 hooks e dois helpers que compartilham o mesmo estado em arquivos versionados do repositório. Um preâmbulo instalado no seu `~/.claude/CLAUDE.md` carrega o bloco de regras da casa — delegação, decisões, prova — que vale para qualquer skill que você chamar. O produto real é a fase: `ll-implement` roda conversa, plano, revisão adversarial, ondas de execução com TDD, verificação de contexto limpo e epílogo em **uma** invocação, e escreve tudo em disco à medida que acontece, para que uma compactação não perca nada.
 
 ## Instalação
 
@@ -10,7 +10,7 @@ Requer [Node.js](https://nodejs.org) 18+ (o mesmo que o Claude Code já usa).
 npx ll-skills@latest
 ```
 
-Reinicie o Claude Code ao final. As skills são standalone — sem o prefixo `ll-skills:` — e podem ser chamadas pelo nome (`/ll-implement 3`) ou escolhidas pelo roteador do preâmbulo.
+Reinicie o Claude Code ao final. As skills são standalone — sem o prefixo `ll-skills:` — e são chamadas pelo nome (`/ll-implement 3`).
 
 ```bash
 npx ll-skills@latest --local          # instala em ./.claude, só para o projeto atual
@@ -25,8 +25,9 @@ O que a instalação **escreve** (em `$CLAUDE_CONFIG_DIR` ou `~/.claude`):
 
 | Caminho | Conteúdo |
 |---|---|
-| `skills/ll-*/` | as 11 skills, com `SKILL.md` e `references/` |
+| `skills/ll-*/` | as 12 skills, com `SKILL.md` e `references/` |
 | `skills/ll-{implement,verify,close}/scripts/ll-tools.js` | cópia do helper, uma por skill que o usa |
+| `skills/ll-auto/scripts/ll-auto.js` | o helper da própria skill, executável |
 | `agents/ll-{executor,scout,verifier,reviewer}.md` | os 4 agentes |
 | `hooks/ll-{skills-check-update,state,precompact}.js` | os 3 hooks, executáveis |
 | `settings.json` | duas entradas em `SessionStart` (`startup\|resume\|compact`) e uma em `PreCompact`; backup em `settings.json.ll-skills.bak` |
@@ -35,22 +36,9 @@ O que a instalação **escreve** (em `$CLAUDE_CONFIG_DIR` ou `~/.claude`):
 
 O que a instalação apenas **imprime**, e nunca escreve: a política sugerida de `settings.json` (`assets/settings.suggested.json` — deny list, `autoCompactWindow`, cache, modelos por papel) e o diagnóstico de sobras de instalações antigas. Reinstalar é idempotente; a primeira instalação 2.x poda as skills 1.x pelo manifesto.
 
-## Como funciona
+## Como as skills são chamadas
 
-O preâmbulo classifica todo pedido por três critérios — lacuna de intenção, irreversibilidade e pegada — e anuncia o regime em uma linha antes de agir.
-
-| Regime | Gatilho | O que acontece | Skill |
-|---|---|---|---|
-| SMALL | verbo + alvo endereçável, ≤25 palavras, ~3 chamadas | lê o alvo, faz, verifica com um número | nenhuma |
-| FIX | "não era isso", "quebrou", "não sobe" | após 2 tentativas iguais, para, junta evidência, diagnostica | nenhuma |
-| RESEARCH | "pesquise", "compare", "docs oficiais", restrição não validada | frentes paralelas + contra-evidência + checagem de citação | `ll-research` |
-| OPS | deploy, apply, cutover, credencial, IP, "avise a infra" | pré-flight de capacidades e verdade por outro caminho | `ll-oncall` |
-| LARGE | ideia nova, "plano", horas de máquina, cria um lugar | plano de ataque em 5 linhas, depois o contrato | `ll-decide` |
-| EXECUTE | "implementa", "continua", marco com `passes: false` | a fase inteira em uma invocação | `ll-implement` |
-| RESUME | 1º turno num repo com PROGRESS.md, "onde paramos" | briefing de ≤20 linhas, nada escrito | `ll-resume` |
-| REFINE | produto rodando + "melhorar", "fiel ao protótipo" | uma rodada fechada de refino | `ll-refine` |
-
-Uma palavra sua vence o classificador (`direto`, `pesquise`, `plano`, `implementa`, `fecha`, `status`). E a regra que amarra o conjunto: **uma skill nunca chama outra**. Cada uma termina num arquivo dentro do repositório e imprime `▶ Next — /clear, depois <comando>`; quem cola é você.
+Uma skill roda só quando você digita `/ll-<nome>`. A sessão nunca inicia uma skill sozinha: quando o pedido parece o trabalho de uma delas, ela responde com o comando exato para você colar e para aí. Uma skill por turno — nenhuma chama outra. Cada uma termina num arquivo dentro do repositório e imprime `▶ Next — /clear, depois <comando>`; quem cola é você. `ll-auto` é a única exceção: o único lugar que segue as instruções de outra skill, e só quando você digita `/ll-auto`.
 
 ## Ciclo de um projeto
 
@@ -58,7 +46,7 @@ Uma vez por milestone, com a contagem de prompts seus por etapa:
 
 | Etapa | Prompts | Sai disso |
 |---|---|---|
-| ideia → roteador | 1 | plano de ataque em 5 linhas (LARGE) |
+| ideia → `/ll-brainstorm` ou `/ll-research` | 1 | plano de ataque em 5 linhas (LARGE) |
 | `ll-brainstorm` | 0–1 | mapa A/B/C + bateria de ≤4 → `DECISIONS.md` / `OPENING.md` |
 | `ll-research` | 0–1 | `docs/research-<tema>/` com SUMMARY, evidências e fontes |
 | `ll-decide` | 1 + cliques | `PLAN.md`, `ROADMAP.md`, `decisions/`, `PROGRESS.md` vazio |
@@ -89,7 +77,7 @@ Entre fases, `/clear`: sessão nova custa menos e erra menos que compactação.
 | `ll-brainstorm` | "tenho uma ideia", "vamos discutir", antes de abrir uma fase | `phases/NN/DECISIONS.md` ou `docs/decide/OPENING.md` |
 | `ll-research` | "pesquise", "compare A e B", restrição não validada; `--market` para mercado e preço | `docs/research-<tema>/` (SUMMARY + evidências + fontes datadas) |
 | `ll-decide` | "escreve o plano", segunda tentativa, ou feedback externo em docx/pdf/xlsx | `PLAN.md` §0–§11, `ROADMAP.md`, `decisions/`, ou `docs/review-<data>.md` |
-| `ll-goal` | antes de uma noite sem ninguém olhando | `docs/GOAL.md` + o texto de 9 partes para `/goal` |
+| `ll-goal` | antes de uma noite sem ninguém olhando; `ll-goal --autonomous ["<objetivo>"]` cobre a entrega inteira | `docs/GOAL.md` + o texto de 9 partes para `/goal`; no modo autônomo, o texto mantém `ll-auto --auto-decision` rodando até a entrega fechar |
 | `ll-implement` | "implementa a fase N", "continua" | a fase entregue, `phases/NN/PLAN.md`, PROGRESS carimbado |
 | `ll-verify` | "confere se terminou de verdade", contrato público, dinheiro, dado de cliente | `VERIFICATION.md` com ledger FRESH/STALE e dois selos |
 | `ll-close` | "fecha", "pode arquivar"; `--milestone` arquiva as fases | `docs/DELIVERY.md`, retrospectiva, ROADMAP colapsado |
@@ -97,6 +85,30 @@ Entre fases, `/clear`: sessão nova custa menos e erra menos que compactação.
 | `ll-refine` | produto rodando: "melhorar as telas", "fiel ao protótipo" | uma rodada registrada no PROGRESS; modo `visual` até o veredito FIEL |
 | `ll-oncall` | `claude -n <papel>`, "vigie a cada 1h", deploy/apply/cutover | bloco `## Federation`, `docs/REQUESTS.md`, pré-flight do deploy |
 | `ll-update` | "atualiza o ll-skills", ou o aviso da sessão | o pacote atualizado, com o changelog mostrado antes |
+| `ll-auto` | `/ll-auto "<objetivo>" [flags]` | `docs/AUTO.md` e o ciclo inteiro |
+
+### Fluxo autônomo
+
+`ll-auto` lê o estado em disco (`detect`), corta a lista de etapas com as flags (`roteiro`) e segue cada etapa lendo o `SKILL.md` dela — a única skill que faz isso, e só porque você digitou o comando.
+
+| Flag | Efeito |
+|---|---|
+| `--research` | entra `research` no roteiro, se não estiver `done` |
+| `--brainstorm` | entra `brainstorm` no roteiro, se não estiver `done` |
+| `--interactive` | tira o `--no-talk` de `ll-brainstorm`/`ll-implement`: essas etapas falam com você |
+| `--auto-decision` | resolve toda decisão de dono para a opção recomendada e segue |
+| `--pause-at <stage\|N>` | para depois daquela etapa ou fase, com `▶ Next — /clear, then ll-auto --resume` |
+| `--from N` / `--to N` / `--only N` | corta as fases por número (`--only N` corta o `close`) |
+| `--verify all` | roda `ll-verify NN` depois de cada fase, mesmo sem o epílogo pedir |
+| `--redo <stage>` | força uma etapa `done` de volta para `todo` |
+| `--dry-run` | imprime a tabela do roteiro e para, antes de escrever `docs/AUTO.md` |
+| `--resume` | retoma as flags gravadas em `docs/AUTO.md`, a partir da primeira linha que não é `done` |
+
+Num repositório vazio (sem pesquisa, sem `OPENING.md`, sem `PLAN.md`) e sem objetivo, `ll-auto` não pergunta nada: imprime o comando que completa (`/ll-auto "<objetivo>" [--research] [--brainstorm]`) e para. Toda decisão de dono tomada sozinha ao longo do run (com `--auto-decision`) entra listada no fim, cada uma marcada `[decided by absence — revisable]`.
+
+#### Para rodar sem parar
+
+`ll-goal --autonomous` escreve o texto, você cola em `/goal <texto>`, e o loop do `/goal` reinicia `ll-auto --auto-decision` sempre que a sessão parar antes da entrega; decisões tomadas sozinhas ficam listadas no fim (`[decided by absence — revisable]`); só dinheiro, produção ou dados de cliente param a corrida.
 
 ## Agentes
 
@@ -132,6 +144,16 @@ Nenhum agente despacha subagente (profundidade 1) e nenhum pergunta ao dono: uma
 | `epilogue` | monta os dados do fim de fase e diz o próximo comando |
 | `phase-stats` | dias com trabalho, dias ociosos, commits por tipo, razão teste/feature |
 
+`skills/ll-auto/scripts/ll-auto.js` é o helper próprio da skill `ll-auto` — Node puro, sem dependências, nunca uma cópia de `ll-tools.js`.
+
+| Comando | O que faz |
+|---|---|
+| `detect` | lê o estado em disco e devolve a tabela de etapas (`research` … `close`) com status `todo`/`half`/`done` |
+| `roteiro` | corta a tabela do `detect` pelas flags e devolve a lista ordenada de etapas a rodar |
+| `next-cmd` | lê o comando da última linha `▶ Next` de um arquivo |
+| `report` | lista os `decisions/*.md` marcados `[decided by absence — revisable]` |
+| `auto-md` | monta o corpo de `docs/AUTO.md` (objetivo, flags, roteiro, decisões, log) |
+
 ## Arquivos de estado no repositório
 
 ```

package/agents/ll-executor.md

@@ -22,6 +22,7 @@ You execute one milestone of a phase plan. You do not plan, do not decide and do
 2. The project's `CLAUDE.md`.
 3. The `### M<n>` blocks of previous waves in `PROGRESS.md`: what was built before you and what they left in `not_verified:`.
 4. Every file in your milestone's `read_first:`, and the section of `phases/NN/CODE-CONTEXT.md` the brief names.
+5. The brief itself, field by field: MILESTONE, PLAN, CONTEXT, FILES, WAVE (your wave and the milestones running in parallel — their files are not yours), TDD, ACCEPTANCE, MODEL, DEC RESERVED (the only ids you may cite in `questions:`), INPUTS (paths that already exist), DO NOT, RETURN.
 
 Nothing else. One Read per file; do not re-read a range already in context. Grep before Read on files over 2,000 lines.
 
@@ -89,7 +90,7 @@ commits: <sha7> test(M<n>): <msg> · <sha7> feat(M<n>): <msg>
 commands: <acceptance command> → "<last output line>" · <other command> → "<last line>"
 deviations: none | <rule applied> — <what> (<file:line>)
 questions: none | <decision requested> — <the option you would take and why>
-backlog: none | <deviation|stub|test-not-run|debt|domain-question> · <what> · `<closing command>` exit 0
+backlog: none | <type> · <what> · `<cmd>` exit 0 · note: <prose>
 not_verified: <what this milestone does not prove; one item per line, or none>
 ```
 

package/agents/ll-verifier.md

@@ -50,6 +50,7 @@ Levels for a phase criterion: exists (the file) → substantive (not a stub: no
 - `git diff <range> -- <test files>`: an assertion loosened, a test skipped, deleted or made unconditional without a `DEC-` id in the commit or in `decisions/` → `BLOCKS: process`.
 - each milestone with `tdd: yes`: `git log` shows `test(M<n>)` before `feat(M<n>)`; missing or inverted → `BLOCKS: process`.
 - files a milestone's block names that do not exist in HEAD, or commits it lists that git does not have → `BLOCKS: report`.
+- a committed script under `phases/` or `scripts/` with an absolute home path, `pkill -f` or `killall` → `BLOCKS: process` (a disconfirmation about a committed artifact is a BLOCK, not a reservation).
 
 ## The 8 plan questions (mode plan)
 

package/assets/preamble.md

@@ -1,36 +1,21 @@
 <!-- ll-skills:preamble v1 -->
 # ll-skills — how this session works
 
-## Route every request before acting
-Classify every request by three criteria — intent gap (does it say what it wants, or only what
-hurts?), irreversibility (leaves the repo, costs money, touches prod?) and footprint (one file, one
-service, one system?) — and state the regime and the reason in one line before doing anything.
-- SMALL: verb + addressable target, ≤25 words, fits in ~3 tool calls → read the target, do what is
-  authorized, verify with a number, label provenance; no skill, no file, no subagent.
-- FIX: "não era isso", "quebrou", "não sobe" → after 2 failed attempts of the same kind, stop, write
-  what was ruled out, gather evidence, present diagnosis + one question with options; fix AND root cause.
-- RESEARCH: "pesquise", "compare", "docs oficiais", unvalidated restriction → `ll-research`.
-- OPS: deploy, apply, cutover, credential, IP, "avise a infra" → `ll-oncall` (ops mode).
-- LARGE: new idea, "plano", hours of machine time, the request creates a place (folder, repo) →
-  5-line plan of attack, then `ll-decide project`, or `ll-research <topic>` first when intent is missing.
-- EXECUTE: `phases/NN/PLAN.md` has a milestone with `passes: false`, or "implementa" / "continua" /
-  "roda a fase N" → `ll-implement N`.
-- RESUME: first turn in a repo with PROGRESS.md; "status", "onde estamos", "o que tenho pra decidir" → `ll-resume`.
-- REFINE: product running + "melhorar"; external feedback (docx, pdf, sheet); "fiel ao protótipo" →
-  `ll-refine`, or `ll-decide feedback`.
-One word from the owner beats the classifier: direto → SMALL; pesquise → RESEARCH; plano → LARGE;
-goal → `ll-goal N`; implementa / continua → EXECUTE; fecha → `ll-close`; status → RESUME; a skill
-named as a suffix of the request also counts. Never change regime silently: when small turns large (bigger
-root cause, operational pain, chained deliveries, a new place), say so in one line and offer once.
-Never in SMALL: spec, plan, PROGRESS, VERIFICATION, premortem, interview, a subagent for what fits in
-3 calls, questions about implementation, two questions in a row, automatic commits.
-
 ## Skills
-A skill never invokes another skill and never decides the owner's next request; `ll-implement` covers one
-phase per invocation. Every skill ends in a repository file and prints "▶ Next — `/clear` then `<command>`" for
-the owner to paste; that line ends the turn, no tool call follows it. State lives at the repo root (`PLAN.md`,
-`PROGRESS.md`, `phases/`, `decisions/`), never in a subfolder, written as it happens. Reply to the owner in
-Portuguese, in their words (marco, onda, gate, contexto limpo, fiel); every file is English. Short answer, long proof.
+A skill runs only when the owner types `/ll-<name>`. The session never starts one on its own, never runs one on the
+owner's behalf, never calls the Skill tool on an ll skill and never redirects a request to a skill: whatever the owner
+asks is answered or done as asked, in any repository, whether or not `PLAN.md`, `PROGRESS.md`, `phases/` or
+`decisions/` exist. A command is named only when the owner asks which command to use. `ll-auto` is the single place
+that follows another skill's instructions, and only while the owner invoked `/ll-auto`.
+A request that is a verb plus an addressable target and fits in about three tool calls gets the work itself, not a
+ritual: read the target, do what is authorized, verify with a number, label provenance; no spec, no plan, no PROGRESS
+entry, no VERIFICATION, no premortem, no interview, no subagent, no automatic commit, no two questions in a row. When
+a small request turns out to be large (a bigger root cause, a chained delivery, a new folder or repo), say so in one
+line. A skill never invokes another skill and never decides the owner's next request; `ll-implement` covers one phase
+per invocation. Every skill ends in a repository file and prints "▶ Next — /clear, then <command>" for the owner to
+paste; that line ends the turn, no tool call follows it. State lives at the repo root (`PLAN.md`, `PROGRESS.md`,
+`phases/`, `decisions/`), never in a subfolder, written as it happens. Reply to the owner in Portuguese, in their
+words (marco, onda, gate, contexto limpo, fiel); every file is English. Short answer, long proof.
 
 ## Delegation
 The session orchestrates; subagents execute, verify, scout and review, never orchestrate; depth 1 — an
@@ -45,19 +30,20 @@ unbiased judge and design; haiku never executes or verifies. The reviewer is nev
 executor. The per-role profile lives in PLAN.md §7 and is read every wave.
 
 ## Decisions
-Band 1 — ask, never decide alone: money above the round's ceiling; irreversible outside the repo
-(push that deploys, apply with destroy, credential in a new place, writes to prod, customer data);
-price, packaging or a promise to a customer; scope cut of the round; the number the owner will look
-at (denominator, window, what counts as an event); a recorded rule contradicted by new evidence.
+Band 1 — ask, never decide alone: irreversible outside the repo (push that deploys, apply with
+destroy, credential in a new place, writes to prod, customer data); price, packaging or a promise to
+a customer; a scope cut of the phase; the number the owner will look at (denominator, window, what
+counts as an event); a recorded rule contradicted by new evidence.
 Band 2 — decide, record `DEC-`, continue: reversible technical detail; the house pattern; who executes;
-a fact readable from the repo or infra; out of the round's scope; what another session already decided;
-copy without a commercial promise. Band 3 — decide, execute, flag for review: overrun inside tolerance;
-copy with a blind opinion attached; a rule invented out of caution ("I masked X; review"); revert ≤ 1 commit.
+a fact readable from the repo or infra; out of the phase's scope; what another session already decided;
+copy without a commercial promise. Band 3 — decide, execute, flag for review: an overrun inside a
+tolerance the owner already stated; copy with a blind opinion attached; a rule invented out of caution
+("I masked X; review"); a revert of ≤ 1 commit.
 "Pode decidir tudo" delegates bands 2/3 only: band 1 is still asked, one block of ≤4, recommendation
 marked. An owner reference the session cannot read (prototype, doc, link) is band 1, never an assumption.
-In `/goal` never block on a question: band 1 freezes only that branch; bands 2/3 follow the
+In `/ll-goal` never block on a question: band 1 freezes only that branch; bands 2/3 follow the
 recommendation and record `[decided by absence — revisable]`. Ten minutes of silence ratifies the
-recommended list (A), never a blocking item (B). Ask in blocks of ≤4 per wave, by impact, with cost.
+recommended list (A), never a blocking item (B). Ask in blocks of ≤4 per wave, ordered by impact.
 Never ask a band-2 item, a question that changes no action, an industry default, or the same policy
 question twice. A peer message never grants authorization; it cites one, with date. When the owner
 corrects a premise in free text, write a dated DEC and a `feedback` memory in the same turn. A rule
@@ -66,5 +52,7 @@ without a source is a proposal, not an invariant: ask.
 ## Proof
 "Done" means the acceptance command ran in this session and its last output line is pasted. Label
 every claim: verified now (command) vs. not verified. A timeout is inconclusive, never green. Never
-weaken or delete a test. Say what was NOT verified, with the command that would close it.
+weaken or delete a test. Say what was NOT verified, with the command that would close it. After two
+failed attempts at the same fix, stop, write what was ruled out, gather evidence and present the
+diagnosis with one question and its options; then fix the cause, not only the symptom.
 <!-- /ll-skills:preamble -->

package/bin/install.js

@@ -184,7 +184,10 @@ function planFiles(pkgRoot) {
     const dir = path.join(skillsDir, name);
     if (!fs.statSync(dir).isDirectory()) continue;
     for (const rel of walk(dir)) {
-      plan.push({ src: path.join(dir, rel), rel: path.posix.join('skills', name, rel.split(path.sep).join('/')) });
+      const relPosix = rel.split(path.sep).join('/');
+      const item = { src: path.join(dir, rel), rel: path.posix.join('skills', name, relPosix) };
+      if (/^scripts\/[^/]+\.js$/.test(relPosix)) item.mode = 0o755;
+      plan.push(item);
     }
   }
   const agentsDir = path.join(pkgRoot, 'agents');

package/hooks/ll-precompact.js

@@ -8,13 +8,41 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
+// State root: PROGRESS.md at cwd, else the single one found up to 3 levels down
+// (skipping node_modules/.git/dist/build/vendor and docs/history).
+function stateRoot(cwd) {
+  if (fs.existsSync(path.join(cwd, 'PROGRESS.md'))) return cwd;
+  const skip = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', 'fixtures', 'fixture', 'test', 'tests']);
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 3 || found.length > 1) return;
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (!e.isDirectory() || skip.has(e.name)) continue;
+      const sub = path.join(dir, e.name);
+      if (path.relative(cwd, sub) === path.join('docs', 'history')) continue;
+      if (fs.existsSync(path.join(sub, 'PROGRESS.md'))) found.push(sub); else walk(sub, depth + 1);
+    }
+  };
+  walk(cwd, 1);
+  if (found.length > 1) {
+    // several candidates: keep those with an ll-state block, then the most recently written
+    const stamp = (d) => { try { return fs.statSync(path.join(d, 'PROGRESS.md')).mtimeMs; } catch { return 0; } };
+    const withState = found.filter((d) => { try { return /<!--\s*ll-state\s*-->/.test(fs.readFileSync(path.join(d, 'PROGRESS.md'), 'utf8')); } catch { return false; } });
+    const pool = withState.length ? withState : found;
+    return pool.sort((a, b) => stamp(b) - stamp(a))[0];
+  }
+  return found.length === 1 ? found[0] : cwd;
+}
+
 function main() {
   let input = {};
   try { input = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { input = {}; }
   const cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd();
   const trigger = typeof input.trigger === 'string' && input.trigger ? input.trigger : 'auto';
 
-  const file = path.join(cwd, 'PROGRESS.md');
+  const file = path.join(stateRoot(cwd), 'PROGRESS.md');
   let body;
   try { body = fs.readFileSync(file, 'utf8'); } catch { return; }
 

package/hooks/ll-skills-check-update.js

@@ -4,8 +4,8 @@
 // Hook SessionStart do ll-skills. Instalado em <configDir>/hooks/ pelo bin/install.js.
 //
 // Modo leitor (sem argumentos, foreground, sem rede):
-//   lê o cache da execução anterior e, se houver versão mais nova registrada para a
-//   versão instalada agora, emite um systemMessage curto. Depois dispara o modo worker
+//   reads the cache of the previous run and, when a newer version is recorded for the
+//   version installed now, emits a short systemMessage. Then it starts the worker mode
 //   em background e sai.
 //
 // Modo worker (--worker, background, com rede):
@@ -13,8 +13,8 @@
 //   está no registro e a instalação veio de `npx github:`, cai para `git ls-remote` e
 //   compara o SHA. Regrava o cache.
 //
-// Regra de ouro: nunca atrasar o início da sessão, nada em stderr, nada fora do
-// próprio cache. Qualquer falha termina em silêncio com exit 0.
+// Golden rule: never delay the session start, nothing on stderr, nothing outside
+// its own cache. Any failure ends silently with exit 0.
 
 const fs = require('fs');
 const path = require('path');
@@ -111,7 +111,7 @@ function worker(installed) {
     return;
   }
 
-  // Pacote ainda não publicado: só há referência remota confiável se a instalação veio do GitHub.
+  // Package not published yet: a remote reference is reliable only when installed from GitHub.
   const info = readJson(path.join(STATE_DIR, 'install.json'));
   if (info && info.source === 'github' && info.sha) {
     const remote = gitRemoteSha();
@@ -152,6 +152,6 @@ function main() {
 try {
   main();
 } catch {
-  /* silêncio */
+  /* silence */
 }
 process.exit(0);

package/hooks/ll-state.js

@@ -64,7 +64,7 @@ function parseStateBlockLite(bl) {
     if (!line.trim() || /^\s*#/.test(line)) continue;
     let m = /^phase:\s*(.*)$/.exec(line);
     if (m) { st.phase = String(llScalar(m[1])); inM = false; continue; }
-    if (/^milestones:\s*$/.test(line)) { inM = true; continue; }
+    if (/^milestones:\s*(\{\s*\})?$/.test(line)) { inM = true; continue; }
     m = /^(\s*)(M\d+|G-\d+):\s*\{(.*)\}\s*$/.exec(line);
     if (m && inM) {
       st.milestones[m[2]] = llScalar('{' + m[3] + '}');
@@ -144,10 +144,38 @@ function build(cwd, source) {
   return out.slice(0, MAX_LINES - 2).concat(['', board.text]);
 }
 
+// State root: PROGRESS.md at cwd, else the single one found up to 3 levels down
+// (skipping node_modules/.git/dist/build/vendor and docs/history).
+function stateRoot(cwd) {
+  if (fs.existsSync(path.join(cwd, 'PROGRESS.md'))) return cwd;
+  const skip = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', 'fixtures', 'fixture', 'test', 'tests']);
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 3 || found.length > 1) return;
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (!e.isDirectory() || skip.has(e.name)) continue;
+      const sub = path.join(dir, e.name);
+      if (path.relative(cwd, sub) === path.join('docs', 'history')) continue;
+      if (fs.existsSync(path.join(sub, 'PROGRESS.md'))) found.push(sub); else walk(sub, depth + 1);
+    }
+  };
+  walk(cwd, 1);
+  if (found.length > 1) {
+    // several candidates: keep those with an ll-state block, then the most recently written
+    const stamp = (d) => { try { return fs.statSync(path.join(d, 'PROGRESS.md')).mtimeMs; } catch { return 0; } };
+    const withState = found.filter((d) => { try { return /<!--\s*ll-state\s*-->/.test(fs.readFileSync(path.join(d, 'PROGRESS.md'), 'utf8')); } catch { return false; } });
+    const pool = withState.length ? withState : found;
+    return pool.sort((a, b) => stamp(b) - stamp(a))[0];
+  }
+  return found.length === 1 ? found[0] : cwd;
+}
+
 function main() {
   const input = readStdin();
   const cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd();
-  const lines = build(cwd, input.source);
+  const lines = build(stateRoot(cwd), input.source);
   if (!lines || !lines.length) return;
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: lines.join('\n').trim() },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ll-skills",
-  "version": "2.0.2",
-  "description": "Evidence-driven development pipeline for Claude Code: router preamble, 11 skills (brainstorm, research, decide, goal, implement, verify, close, resume, refine, oncall, update), 4 agents, 3 hooks and a state helper",
+  "version": "3.1.0",
+  "description": "Evidence-driven development pipeline for Claude Code: router preamble, 12 skills (auto, brainstorm, research, decide, goal, implement, verify, close, resume, refine, oncall, update), 4 agents, 3 hooks and a state helper",
   "bin": {
     "ll-skills": "bin/install.js"
   },
@@ -16,6 +16,7 @@
     "README.md"
   ],
   "scripts": {
+    "lint": "bash scripts/lint-prompts.sh && node scripts/lint-contract.cjs",
     "test": "bash scripts/smoke-test.sh"
   },
   "engines": {

package/scripts/evals/README.md

@@ -0,0 +1,81 @@
+# Behavioural evals
+
+`smoke-test.sh` checks what the files say. These cases check what a session *does* with them: each
+installs the package into a throwaway `CLAUDE_CONFIG_DIR`, runs `claude -p` against a throwaway
+copy of a fixture repository, and scores the answer and the work tree with a shell assert.
+
+    bash scripts/evals/run.sh --dry-run --all              # print the commands, call nothing
+    bash scripts/evals/run.sh --case router-small --reps 1 # one case, one rep
+    bash scripts/evals/run.sh --all                        # twelve cases, three reps
+
+`--all` | `--case <id>` (repeatable) | `--reps N` (default 3) | `--model <id>` | `--dry-run`.
+Exit 0 when every selected case passed in at least `min_pass` reps (`case.json`, capped at the
+reps actually run, so `--reps 1` means 1 of 1).
+
+## Cost
+
+Router cases are 1–8 turns and cost cents. The six agent and skill cases run 30–40 turns: dollars
+per rep, tens of dollars for `--all --reps 3` — a skill that fans out subagents costs about a dollar
+per turn-block, so keep routing caps low. Dry run first, then one cheap case.
+
+## Autonomous cases
+
+`auto-dry-run`, `auto-empty-repo` and `goal-autonomous` run the unattended path end to end: ≤ 12
+turns and cost cents, like the router cases. The prompt is the slash command exactly as the owner
+types it (`/ll-auto --dry-run`, `/ll-auto`, `/ll-goal --autonomous "Deliver phases 07 and 08"`),
+which `claude -p` expands; there is no agent, no fan-out. `goal-autonomous` scores the pasted `/goal`
+text (`ll-auto --auto-decision`, ≤ 4000 chars) and the committed `docs/GOAL.md` (`mode: autonomous`,
+`phase: all`). Their assert scripts are proven offline, without calling `claude -p`, by `npm test`
+(section `evals-auto` in `scripts/smoke-test.sh`) against the fixed answers under
+`scripts/fixtures/evals-auto/<case>/pass.txt`.
+
+`max_turns` is a budget, not a measurement: the `num_turns` the result reports counts the skill's `!`
+preprocessor Bash calls together with the model's own tool calls, and a run has ended `success` with
+`num_turns 7` under `--max-turns 4`. Pin each cap above the highest count real reps show (`case.json`
+`note`), so the cap only ever cuts a run that really went long.
+
+## Router cases
+
+A skill runs only when the owner types it, so these cases score what the session does with a plain
+request — never which command it names back.
+
+| case | prompt | what it scores |
+|---|---|---|
+| `router-small` | `conta as linhas de README.md` | the answer itself: nothing written, no ritual, no Skill call |
+| `router-no-skill` | a research request in a repo that carries `PLAN.md` and `decisions/` | the research itself: no command handed back, no `▶ Next`, no Skill call, nothing created |
+| `preamble-no-ritual` | a one-line typo fix | no spec, no plan, no `PROGRESS.md`, no subagent |
+
+A case that exercises a skill types the slash command in its `prompt.txt` (`/ll-implement 7`,
+`/ll-decide project …`): a skill is never started from prose, so a prose prompt would score the
+plain answer, not the skill.
+
+## Cases proven offline
+
+The `router-no-skill` (research delivered, no command handed back), `decide-final-round`
+(decision-room path before the first question, count line in plain words) and
+`implement-stops-at-next` (wave line before the epilogue, helper never read) asserts are proven
+without calling `claude -p` by `npm test` (section `evals-auto`), against the captures and answers
+under `fixtures/router-no-skill/` — `out.json`, a compliant `pass.txt` and a `fail.txt` that only
+hands a command back — and the inline captures the smoke test builds.
+
+## Results — outside the repo
+
+Each run writes `$LL_EVAL_RESULTS/<YYYY-MM-DD-HHMM>/` (default `~/.claude/ll-skills-evals`, outside the repo): `RESULTS.md`,
+`summary.json`, the installer log and, per rep, `out.json`, `out.txt`, `assert.log`. Work trees
+live under `mktemp -d` outside the repo — so the session under test never discovers this project's
+own `.claude/` or `CLAUDE.md` — and are kept; `RESULTS.md` prints their path.
+
+## Add a case
+
+`cases/<id>/`: `case.json` (`max_turns`, `history`, `min_pass`, `agent`, `permission_mode`,
+optional `reuse`), `prompt.txt` (`{{WORK}}` becomes the work tree's absolute path), optional
+`fixture/` (else `scripts/fixtures/project`), optional `setup.sh <workdir>`, and
+`assert.sh <workdir> <out.json> <out.txt>` sourcing `lib/assert.sh`.
+
+## Environment
+
+`env -u CLAUDECODE`, `--strict-mcp-config`, `--permission-mode bypassPermissions` by default.
+`--max-turns` works but is absent from `claude --help`. `--verbose` is required: without it
+`--output-format json` prints only the `result` object, and the regime line — stated in the *first*
+assistant message, before any tool call — cannot be read. A fresh `CLAUDE_CONFIG_DIR` has no auth:
+`run.sh` symlinks `~/.claude/.credentials.json` into it (a copy goes stale on token refresh).

package/scripts/evals/cases/auto-dry-run/assert.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# --dry-run: the stage table and the roteiro are printed, nothing is written, no skill starts.
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../../lib" && pwd)/assert.sh"
+
+WORK="$1"; OUT_JSON="$2"; OUT_TXT="$3"
+
+# The roteiro of the shared fixture, tolerant to a table or a numbered list:
+# each stage and its command on one line.
+contains "$OUT_TXT" 'phase-07.*ll-implement 0?7' 'the roteiro carries the phase-07 row with ll-implement 07'
+contains "$OUT_TXT" 'phase-08.*ll-implement 0?8' 'the roteiro carries the phase-08 row with ll-implement 08'
+contains "$OUT_TXT" 'close.*ll-close'            'the roteiro carries the close row with ll-close'
+
+# CA-04: the stage table from detect is printed too, decide already done.
+contains "$OUT_TXT" 'decide.*done' 'the stage table is printed with decide: done'
+
+no_path "$WORK/docs/AUTO.md" 'docs/AUTO.md was not written: the dry run stopped before opening the run'
+
+# The capture files are the harness's, not the run's: a real rep keeps them under
+# the results dir, the offline check hands them inside the scratch work tree.
+dirty="$(git -C "$WORK" status --porcelain | while IFS= read -r line; do
+  path="${line#???}"
+  [ "$WORK/$path" = "$OUT_JSON" ] || [ "$path" = "$OUT_JSON" ] && continue
+  [ "$WORK/$path" = "$OUT_TXT" ]  || [ "$path" = "$OUT_TXT" ]  && continue
+  printf '%s\n' "$line"
+done)"
+if [ -z "$dirty" ]; then
+  ok 'git status --porcelain is empty: nothing was written'
+else
+  fail "the working tree was changed: $(printf '%s' "$dirty" | tr '\n' ' ')"
+fi
+
+no_tool_use "$OUT_JSON" Skill           'no Skill tool call anywhere in the capture'
+no_tool_use "$OUT_JSON" AskUserQuestion 'no AskUserQuestion tool call anywhere in the capture'
+
+finish

package/scripts/evals/cases/auto-dry-run/case.json

@@ -0,0 +1,8 @@
+{
+  "max_turns": 6,
+  "history": false,
+  "min_pass": 1,
+  "agent": null,
+  "permission_mode": "bypassPermissions",
+  "note": "Proves the --dry-run stop of ll-auto: the stage table and the roteiro are printed, docs/AUTO.md is not written and no skill is started. bypassPermissions so the helper's Bash runs unattended. Shared fixture: scripts/fixtures/project (phase-07 half, phase-08 planned)."
+}

package/scripts/evals/cases/auto-dry-run/prompt.txt

@@ -0,0 +1 @@
+/ll-auto --dry-run