ll-skills 2.0.2 → 3.0.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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.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.
 

package/assets/preamble.md

@@ -1,33 +1,24 @@
 <!-- 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 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 proposes to run one for them and never calls the Skill tool
+on an ll skill; when a request looks like a skill's job it answers with the exact command to paste
+and stops there. `ll-auto` is the single place that follows another skill's instructions, and only
+while the owner invoked `/ll-auto`.
+Commands to name, never to run: research, a comparison or an unvalidated restriction →
+`/ll-research <topic>`; a new idea → `/ll-brainstorm`; a phase whose PLAN still has an open
+milestone, "implementa", "continua" → `/ll-implement N`; "status", "onde estamos", "o que tenho pra
+decidir" → `/ll-resume`; a decision to record → `/ll-decide`; deploy, credential, incident →
+`/ll-oncall`; external feedback on a running product → `/ll-refine`; closing a phase → `/ll-close`.
+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 and name the command once.
 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
+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.
@@ -45,19 +36,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 +58,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.0.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,57 @@
+# 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                        # thirteen 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–6 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.
+
+## 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

package/scripts/evals/cases/auto-empty-repo/assert.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# "/ll-auto" on an empty repository -> the two-line stop, no question, nothing written.
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../../lib" && pwd)/assert.sh"
+
+WORK="$1"; OUT_JSON="$2"; OUT_TXT="$3"
+
+contains "$OUT_TXT" 'Nada encontrado neste reposit' 'the answer carries the empty-repository line'
+contains "$OUT_TXT" '/ll-auto "<objetivo>"' 'the answer carries the command to complete'
+
+no_path "$WORK/docs" 'no docs/ was created'
+no_path "$WORK/PLAN.md" 'no PLAN.md was created'
+
+# OUT_JSON may sit inside WORK for an offline check; exclude it by name so the
+# capture file itself is not read as a change to the work tree.
+dirty="$(git -C "$WORK" status --porcelain 2>/dev/null | grep -v -- " $(basename "$OUT_JSON")\$")"
+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" AskUserQuestion 'no AskUserQuestion tool call anywhere in the capture'
+no_tool_use "$OUT_JSON" Skill 'no Skill tool call anywhere in the capture'
+
+finish

package/scripts/evals/cases/auto-empty-repo/case.json

@@ -0,0 +1,8 @@
+{
+  "max_turns": 10,
+  "history": false,
+  "min_pass": 1,
+  "agent": null,
+  "permission_mode": "bypassPermissions",
+  "note": "Own fixture holding only .gitkeep (an empty repository). Proves the empty-repo stop: two exact lines, no question, nothing written. max_turns 10 (B-018): the `num_turns` the result reports counts the skill's `!` preprocessor Bash calls and the model's own tool calls together — real reps of this case reported 3 and 7 while the cap was 4 and the run still ended `success`, so the two numbers are not the same unit. The cap is pinned above the highest count seen, so a rep that really runs long is cut instead of scoring."
+}

package/scripts/evals/cases/auto-empty-repo/prompt.txt

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

package/scripts/evals/cases/decide-final-round/assert.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# The final round is always sent, with the counter, before anything is frozen.
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../../lib" && pwd)/assert.sh"
+
+WORK="$1"; OUT_JSON="$2"; OUT_TXT="$3"
+
+# a one-shot run has no owner to answer: either the final round (counter) or a blocking gate block (≤ 4 questions) is the correct stop
+if grep -qE 'questions asked' "$OUT_TXT"; then
+  contains "$OUT_TXT" 'band-1 open' 'the final round carries "band-1 open"'
+else
+  contains "$OUT_TXT" '\[PG-1\]|Pergunta 1/|Question 1/' 'the gate asks its first question instead of assuming'
+  n="$(grep -cE '^\*\*\[PG-[0-9]+\]|^\*\*Pergunta [0-9]+/|^\*\*Question [0-9]+/' "$OUT_TXT")"
+  if [ "$n" -le 4 ]; then ok "the block carries $n questions (≤ 4)"; else fail "the block carries $n questions (> 4)"; fi
+  no_path "$WORK/PLAN.md" 'nothing frozen while the gate is open'
+fi
+
+# The contract is only scored when it was written: with a band-1 item open, nothing freezes.
+if [ -f "$WORK/PLAN.md" ]; then
+  contains "$WORK/PLAN.md" '^## ' 'PLAN.md carries ## sections'
+  if [ -d "$WORK/decisions" ]; then
+    ok 'decisions/ exists beside the frozen PLAN.md'
+  else
+    fail 'PLAN.md was written but decisions/ does not exist'
+  fi
+else
+  ok 'no PLAN.md written — nothing was frozen, so the contract is not scored'
+fi
+
+# The phase plan is never written by this skill.
+no_path "$WORK/phases/01/PLAN.md" 'no phases/NN/PLAN.md was written here'
+
+finish

package/scripts/evals/cases/decide-final-round/case.json

@@ -0,0 +1,8 @@
+{
+  "max_turns": 40,
+  "history": false,
+  "min_pass": 2,
+  "agent": null,
+  "permission_mode": "bypassPermissions",
+  "note": "Empty fixture so the LARGE route has nowhere to resume from. The final round is always sent, even when every item was band 2/3, so the counter must appear whether or not PLAN.md was frozen."
+}

package/scripts/evals/cases/decide-final-round/fixture/README.md

@@ -0,0 +1,3 @@
+# reminders
+
+An empty repository. Nothing is planned yet: no PLAN.md, no ROADMAP.md, no PROGRESS.md.

package/scripts/evals/cases/decide-final-round/prompt.txt

@@ -0,0 +1 @@
+escreva o plano para um serviço que envia lembretes por e-mail