ll-skills 2.0.2 → 3.1.0

package/skills/ll-implement/references/phase-plan.md

@@ -34,6 +34,10 @@ inside one plan only, so a milestone of another phase has no collision check her
   `sonnet/medium` for a mechanical one; PLAN §7 overrides.
 - `verification: external` when presence plus wiring cannot prove the criterion (provider
   callback, email, deploy): the verifier then requires a test exercising the transition.
+- A committed acceptance script under `phases/NN/` derives the repository root with `git rev-parse
+  --show-toplevel`, binds its own port and, when it stops a process, kills only the PID it started.
+  A hardcoded `/home/…` path, a literal `REPO=/abs/...`, `pkill` or `killall` in a committed script
+  is a plan defect, not a style note — a verifier disconfirmation about it is a BLOCK.
 
 ## TDD by milestone type
 
@@ -109,3 +113,22 @@ not in PLAN §1; skipped without a project PLAN.md). Warnings: `block-too-long`
 `files-too-many` (>5), `acceptance-not-command` (no npm/node/pytest/make/… prefix), `model-format`
 (`opus/high`), `truths-missing`, `body-section-missing` (block id without a `### M<n>` body). Then
 `waves --json` reports `file_overlap`, `exclusive_conflict`, `unknown_depends_on`, `cycle` (→ `unscheduled`).
+
+## Helper contract
+
+One row per `ll-tools.js` command this skill calls, with its output fields — read here, the
+helper itself is called, never read.
+
+| Command | Output fields |
+|---|---|
+| `ll-tools.js state` | `phase`, `milestones.{total,passed,list}`, `last_commit`, `waiting`, `epilogue_present`, `active_phase_plan` |
+| `ll-tools.js plan-lint phases/NN/PLAN.md` | `verdict` (pass\|warn\|fail), `defects[]`, `summary.{error,warn}`, `skipped[]` |
+| `ll-tools.js waves phases/NN/PLAN.md --json` | `waves[].{wave,milestones,builds,blocked}`, `defects[]`, `blocked_by`, `unscheduled` |
+| `ll-tools.js board-switch NN --milestones <ids>` | `phase`, seeded `M<n>: {passes:false}` lines; idempotent when the phase already matches |
+| `ll-tools.js dec-reserve <n>` | `ids[]`, `files[]`, `prefix`, `width` |
+| `ll-tools.js spot-check <M> --files <list>` | `verdict` (pass\|fail), `files.{expected,found,missing}`, `commits.{count,shas}` |
+| `ll-tools.js tdd-gate <M> --since <sha>` | `tdd` (pass\|fail), `test`, `feat`, `reason` |
+| `ll-tools.js passes <M> true\|false --phase NN [--commit <sha7> \| --reason <text> --state <…>]` | `passes`, `milestone`, `line`, `created`, `board.{passed,total}` |
+| `ll-tools.js heartbeat "<text>"` | `file`, `line`, `text` |
+| `ll-tools.js backlog-reconcile [--run]` | `items[].{id,state,condition,ran,exit,result}`, `closed[]`, `open` |
+| `ll-tools.js epilogue NN --json` | `phase`, `passed[]`, `left[].{id,why}`, `waiting`, `new_backlog[]`, `dirty`, `head`, `blocked_by`, `next_command` |

package/skills/ll-oncall/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ll-oncall
-description: Runs a session that holds a role instead of a task — writes the `## Federation` contract into the project CLAUDE.md, resolves peers by prefix before every send, answers in the 4-field DONE/EVIDENCE/REFERENCE/PENDING block, and keeps a numbered request log; `watch` turns a vigil into a 5-element brief with a baseline and a degradation rule, `ops` runs a capability pre-flight and a pre-deploy that exercises the exact operation. Use when the request is "Você é o agente responsável por…", when the session was opened as `claude -n <role>`, when it is "a cada 1h verifique…", "vigie…", "monitore…", or when the action is a deploy, apply, cutover, IP change, credential, "avisa a infra", "peça para o agente de infra" — the OPS regime. For planning work, a spec or a roadmap use ll-decide; for a refinement round on a running product use ll-refine.
+description: Runs a session that holds a role instead of a task, writing the Federation contract into the project CLAUDE.md and keeping a numbered request log; watch builds a vigil brief, ops runs a deploy pre-flight.
 argument-hint: "[role <name> | watch [<slug>] | ops]"
+disable-model-invocation: true
 ---
 
 # On call
@@ -113,7 +114,7 @@ delivery answered in 4 fields to the peer and to the owner; `docs/REQUESTS.md` c
 entries with their responses; a `watch` with brief, baseline and probe committed; an `ops` with its
 pre-flight output pasted.
 
-`▶ Next — /clear then ll-resume` in a new session of the same role, or the command the round names.
+`▶ Next — /clear, then ll-resume (in a new session of the same role, or the command the round names)`
 
 ## References
 

package/skills/ll-refine/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ll-refine
-description: Runs one refinement round on a product that already runs — a production review by ll-reviewer, an impact-ordered decision battery, sliced work with a per-coder file allowlist, a deterministic gate that only blocks new errors, and the round recorded in PROGRESS.md; in `visual` mode it drives the reference → calibrated gate → clean-context validator → area-owner loop until the verdict is FIEL. Use when the product is already running and the request is "melhorar as telas", "refino", "rodada", "fiel ao protótipo", "valide visualmente", "outra rodada", "improve the screens", "make it match the prototype" — the REFINE regime. External written feedback (docx, pdf, spreadsheet) is ingested by ll-decide in feedback mode, not here; to audit a finished delivery use ll-verify.
+description: Runs one refinement round on a product already in production, from a review and an impact-ordered decision battery to sliced work with a per-coder file allowlist and a gate that blocks only new errors.
 argument-hint: "[product | visual] [--round N]"
+disable-model-invocation: true
 ---
 
 # Refine
@@ -107,7 +108,7 @@ last output line pasted into the round record; every finding is fixed, deferred
 `BACKLOG` with an executable closing condition; `visual` mode has `validation/E<n>/REPORT.md` with every
 element `FIEL`; `PROGRESS.md` has `### Round N — <date>`; `git status --porcelain` is empty.
 
-`▶ Next — /clear then ll-verify` when the round is the last one, or `/clear then ll-refine --round N+1`.
+`▶ Next — /clear, then ll-verify (or ll-refine --round N+1, when the round is not the last one)`
 
 ## References
 

package/skills/ll-research/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ll-research
-description: Researches a topic with clean-context fronts and web search, delivering `docs/research-<topic>/` in two layers — a SUMMARY.md that separates what to apply from what only the owner can decide and what gates it, plus the per-front evidence trail and a dated, liveness-checked source list. Use when the request is "pesquise", "faça uma pesquisa profunda", "compare A e B", "veja se alguém já resolveu", "docs oficiais de…", "research X", "compare A vs B", "check if anyone already solved this", or when a declared constraint has not been validated by whoever decides. For a market, competitor, pricing or sizing question add `--market`; to turn the findings into a plan, the next command is `ll-decide project`.
+description: Researches a topic with clean-context fronts and web search, delivering a SUMMARY.md that separates what to apply from what only the owner can decide, plus the evidence trail and a dated source list.
 argument-hint: <topic> [--market] [--constraints "…"]
+disable-model-invocation: true
 ---
 
 # Research
@@ -78,7 +79,7 @@ Report in Portuguese: where the files are, the short answer with numbers, the op
 
 Done when `SUMMARY.md` carries `## Apply`, `## Discuss`, `## Gates` and `## What the evidence does NOT cover`; every claim under `## Apply` names a source labelled `[VERIFIED]` in `sources.md`; every front has its note under `evidence/`; and every declared constraint appears either as validated or as a dated premise. Anything left out is said out loud, with the reason.
 
-▶ Next — `/clear` then `ll-decide project` reading `docs/research-<topic>/SUMMARY.md`.
+▶ Next — /clear, then ll-decide project (reading docs/research-<topic>/SUMMARY.md)
 
 ## References
 

package/skills/ll-resume/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ll-resume
-description: Reconstructs where a project stands in a fixed reading order and answers with a briefing of at most 20 lines — where we are, what changed since the owner last took part, what it cost, what is blocked, what waits on him, and the next command. Use when it is the first turn in a repo that has PROGRESS.md, or when the owner asks "Como está o status e qual o próximo passo?", "Qual o estado atual?", "O que tenho pra decidir?", "onde paramos?", "what is the status", "where did we stop", "what do I have to decide" — the RESUME regime. It does not write anything; for closing a phase and recording the delivery use ll-close.
+description: Reconstructs where a project stands in a fixed reading order and answers with a briefing of at most 20 lines - state, cost, blockers, what waits on the owner and the next command. It writes no file.
 argument-hint: "[--decisions]"
+disable-model-invocation: true
 ---
 
 # Resume
@@ -47,13 +48,15 @@ Custo — <days with work · span · commits · agent runs, only where measurabl
 Bloqueado — <M<n>> por <cause, with evidence>   |   nada
 Espera por você — <n> decisões WAITING: <ID> <one line each>   |   nada
 Não verificado — <stale memory of N days, orphan worktree, phantom goal, absent verification>
-▶ Next — <the command the epilogue names>
+▶ Next — /clear, then <the command the epilogue names>
 ```
 
 Every claim carries its evidence — sha, `file:line`, or date; a green milestone with no commit
 behind it is an orphan, not a delivery. If there are WAITING decisions, offer them after the
 briefing in one `AskUserQuestion` with at most 4, ordered by what they block, each stating the cost
-of waiting — never before it, never twice in a turn. Answers stay in the conversation.
+of waiting — never before it, never twice in a turn. When the owner picks an option, append
+`status: DECIDED — "<option>" (owner, <date>, ll-resume)` to that `decisions/DEC-*.md` — one write,
+that file only.
 
 ## Legacy names
 
@@ -72,4 +75,6 @@ Projects not yet migrated keep the Portuguese names — read them, rename nothin
 
 ## Completion criterion
 
-Briefing in ≤20 lines, ≤5 tool calls, 0–1 questions, zero files touched, last line `▶ Next — <cmd>`.
+Briefing in ≤20 lines, ≤5 tool calls, 0–1 questions, zero files touched (one write to a
+`decisions/DEC-*.md` only when the owner answers a WAITING decision), last line
+`▶ Next — /clear, then <cmd>`.

package/skills/ll-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ll-update
-description: Updates the installed ll-skills package to the latest published version — reads the installed and published versions, shows the CHANGELOG entries between them before touching anything, asks once, runs the installer and reports which skills changed. Use when the owner says "atualiza o ll-skills", "atualizar as skills", "tem versão nova do ll-skills?", or when the session warning says "ll-skills desatualizado (instalado X, disponível Y) — rode /ll-update". It installs nothing else — every mutation goes through the package installer, and no project file is touched.
+description: Updates the installed ll-skills package to the latest published version, showing the CHANGELOG entries between the two, asking once, running the installer and reporting which skills changed.
 argument-hint: "[--no-preamble]"
 disable-model-invocation: true
 ---
@@ -66,6 +66,11 @@ carries the old skills — new or renamed skills appear after restarting Claude
 content of an existing skill is read on its next invocation. If `VERSION` did not change, say
 that instead of declaring success.
 
+## Completion criterion
+
+The installed `VERSION` equals the published one (or the owner declined the update) and the report above was printed.
+▶ Next — /clear, then ll-resume (the running session keeps the old skill texts until it restarts)
+
 ## Migration from 1.x
 
 The first 2.x install removes the eight Portuguese skills — `ll-orquestrar`, `ll-pesquisar`,

package/skills/ll-verify/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ll-verify
-description: Audits a finished phase or delivery in clean context — three layers (mechanical, contract, integrity) that never saw the implementation reasoning, a per-criterion ledger with file:line and FRESH/STALE hashes, and a VERIFICATION.md carrying a verdict, two seals and the blocks. Use when the request is "verifica a entrega", "audita isso", "confere se terminou de verdade", "revisa a implementação", when the /goal text cites this skill, at the end of a phase that touches a public contract, money or customer data, and before and after a push that deploys. Findings are findings — the session decides what to fix; to close the delivery, write DELIVERY.md and archive, use ll-close.
+description: Audits a finished phase or delivery in clean context, in three layers that never saw the implementation reasoning, and writes VERIFICATION.md with a per-criterion ledger, a verdict and two seals.
 argument-hint: "[phase-number] [--external] [--criterion SC-nn]"
+disable-model-invocation: true
 allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/ll-tools.js *)
 ---
 

package/skills/ll-verify/references/verifier-briefs.md

@@ -43,6 +43,9 @@ long runs decay: nothing here is accepted by declaration.
    `ll-tools.js ledger` to mark each ledger line FRESH or STALE.
 5. Only after every state is written, open the `<!-- ll-state -->` board in PROGRESS.md and compare:
    `passes: true` whose command fails in this run is the gravest finding there is: name it.
+6. 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).
 
 Install no dependency, start no service beyond the sanity step; what is missing becomes
 NOT_VERIFIABLE with the requirement named.