@andespindola/crow-skills 0.3.0 → 0.5.0

package/skills/crow-behaviour/references/quality-patterns.md

@@ -17,12 +17,24 @@ Quando a solução ainda for desconhecida, separe perguntas falsificáveis e res
 
 Não imponha consenso: dois agentes podem compartilhar a mesma suposição errada. Sem independência real, rotule como perspectivas da mesma execução.
 
+## Painel com juízes
+
+Para decisões de design com várias saídas plausíveis: N propostas independentes (mesmo problema, sem ver umas às outras); avaliadores paralelos pontuam cada uma pelos critérios do usuário, com justificativa ligada a evidência; sintetize a vencedora incorporando o melhor das demais. Os juízes recebem as propostas e os critérios, não a preferência do coordenador. Empate ou divergência forte entre juízes é sinal para buscar a evidência que decide, não para votar de novo.
+
 ## Pesquisa com triangulação
 
-Separe eixos complementares, não só variações de palavras-chave. Exija fontes rastreáveis, data/versão, observações e inferências separadas. Na síntese, identifique fontes derivadas entre si e conflitos de versão; não conte cópias da mesma origem como confirmações independentes.
+Separe eixos complementares, não só variações de palavras-chave, e execute-os em paralelo. Exija fontes rastreáveis, data/versão, observações e inferências separadas. Na síntese, identifique fontes derivadas entre si e conflitos de versão; não conte cópias da mesma origem como confirmações independentes.
 
 Verifique afirmações centrais contra a fonte primária quando disponível. Falta de acesso é desconhecido, não refutação. Não preencha o relatório com fontes irrelevantes para aparentar cobertura.
 
+## Varredura por vários eixos
+
+Em revisão e auditoria, como em pesquisa, divida a busca por dimensões (por exemplo, corretude, segurança, desempenho, compatibilidade, dados, operação) e execute cada eixo em paralelo, com seu próprio executor. Cada achado segue para a verificação adversária; achados duplicados entre eixos são deduplicados numa barreira antes da verificação.
+
+## Busca até secar
+
+Em descoberta, auditoria ou revisão, repita rodadas com ângulos novos até K rodadas consecutivas sem item novo (K = 2 por padrão; maior quando o custo de um item perdido é alto). Registre no ledger K, o número de rodadas e o motivo de parada (secou, limite explícito ou capacidade ausente). Isto é diferente de "Corrigir até passar": lá o loop termina quando um check passa; aqui termina quando a descoberta para de render itens.
+
 ## Fan-out por item: auditoria ou migração
 
 Faça inventário do conjunto-alvo e estabeleça uma unidade verificável por item/lote. Preserve identidade de cada item e resultado inclusive em falha, cancelamento ou retorno vazio. Não filtre falhas silenciosamente para produzir uma taxa de sucesso melhor.
@@ -39,8 +51,14 @@ Depois de uma falha, formule causa e correção, aplique o menor ajuste autoriza
 
 O executor entrega o artefato e sua evidência; o revisor recebe requisitos e artefato e tenta refutar o aceite. Revise fronteiras: entradas inválidas, permissões, concorrência, compatibilidade, recuperação ou fidelidade de conteúdo, conforme o domínio real.
 
+Por padrão, salvo trabalho trivial ou já verificado nesta revisão, submeta cada achado ou alegação a vários verificadores independentes instruídos a refutar, cada um com uma lente distinta (corretude, segurança, desempenho, reprodução). O achado cai se a maioria refutar, salvo evidência reproduzível (teste, comando, trecho de fonte primária) que resista às refutações; nesse caso ele fica, e a divergência é registrada com o motivo. Verificadores que leram a mesma fonte derivada contam como uma só confirmação.
+
 O principal valida achados contestados e reconcilia revisão com testes. Não peça ao revisor apenas que confirme que o executor está certo. Quando não houver segundo agente, faça revisão sequencial sem afirmar independência, e prefira testes/medidas reproduzíveis para reduzir viés.
 
+## Crítico de completude
+
+Antes de encerrar, uma unidade separada (outro executor, ou uma passada sem o contexto da produção quando não houver outro) recebe o pedido original, os critérios e a entrega, e lista apenas o que falta ou não está demonstrado. Itens novos voltam para o plano; uma resposta vazia conta para a parada. Não peça ao crítico que aprove a entrega.
+
 ## Critério de conclusão
 
 Antes de encerrar, confronte pedido e entrega:
@@ -51,6 +69,8 @@ Antes de encerrar, confronte pedido e entrega:
 | O que foi realmente executado? | Saída observada, alvo/revisão e condição do teste. |
 | As partes funcionam juntas? | Verificação de interfaces, não só aprovação isolada. |
 | Há alegação sem base ou conflito escondido? | Fonte, teste ou rótulo de desconhecido; motivo da resolução. |
-| O trabalho pode continuar sem repetir tudo? | Estado remanescente, artefatos válidos e próxima ação. |
+| A descoberta secou? | Rodadas sem item novo (K), crítico de completude sem lacuna nova, ou limite explícito registrado. |
+| O que ficou de fora? | Itens cortados ou não verificados, com motivo; nenhum corte silencioso. |
+| O trabalho pode continuar sem repetir tudo? | Ledger com estado remanescente, artefatos válidos e próxima ação. |
 
 A resposta final prioriza o resultado e limitações que mudam a decisão do usuário. A coordenação fica em segundo plano; só detalhe a metodologia quando solicitado ou necessário para interpretar a confiança.

package/skills/crow-behaviour/scripts/crow_ledger.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Run ledger for crow-behaviour: record units and print the chat summary.
+
+Standard library only; runs on any host that can execute python3. The
+coordinator is the single writer of a ledger; workers report back and the
+coordinator records the transition.
+
+  crow_ledger.py start --title "..." --host claude [--phase id=Título ...] [--session ID] [--global]
+  crow_ledger.py phase ID --run RUN [--title T] [--status running|done|...]
+  crow_ledger.py unit ID --run RUN [--title T] [--phase P] [--owner O] [--status S] [--progress 0..1] [--summary TXT]
+  crow_ledger.py finish --run RUN [--status done|failed|cancelled]
+  crow_ledger.py show [--run RUN]         # tree + ASCII bars for the chat
+  crow_ledger.py path [--run RUN]         # where the ledger lives
+
+start prints "<run-id> <path>"; pass that run id as --run (or $CROW_RUN) on
+every later call. Without it the helper only proceeds when exactly one
+running ledger matches the working directory, so parallel sessions in the
+same clone never write to each other's run.
+
+Location: $CROW_LEDGER (a file) when set; with --global, or when the working
+directory is not writable, ~/.crow/runs/<run-id>.json; else
+<cwd>/.crow/runs/<run-id>.json, with .crow/.gitignore = "*" so the directory
+never shows up in Git. Lookups walk from the working directory up to the
+filesystem root, so a run started at the repository root is still found from
+a subdirectory.
+"""
+import argparse
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+
+SCHEMA = "crow-run/1"
+UNIT_STATUSES = ("pending", "running", "done", "failed", "skipped")
+RUN_STATUSES = ("running", "done", "failed", "cancelled")
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def slug(text):
+    value = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return value[:40] or "run"
+
+
+def run_dirs():
+    """<dir>/.crow/runs from the working directory up to the root, then ~/.crow/runs."""
+    cwd = Path.cwd()
+    dirs = [d / ".crow" / "runs" for d in (cwd, *cwd.parents)]
+    dirs.append(Path.home() / ".crow" / "runs")
+    result = []
+    for d in dirs:
+        if d not in result:
+            result.append(d)
+    return result
+
+
+def under(cwd, base):
+    """True when cwd is base or one of its subdirectories."""
+    base = str(base).rstrip("/") or "/"
+    return cwd == base or cwd.startswith(base.rstrip("/") + "/")
+
+
+def writable_dir(global_only=False):
+    home_runs = Path.home() / ".crow" / "runs"
+    choices = [home_runs] if global_only else [Path.cwd() / ".crow" / "runs", home_runs]
+    for index, directory in enumerate(choices):
+        try:
+            directory.mkdir(parents=True, exist_ok=True)
+            if index == 0 and directory != home_runs:
+                ignore = directory.parent / ".gitignore"
+                if not ignore.exists():
+                    ignore.write_text("*\n", encoding="utf-8")
+            probe = tempfile.NamedTemporaryFile(dir=directory, delete=True)
+            probe.close()
+            return directory
+        except OSError:
+            continue
+    raise SystemExit("crow_ledger: nenhum diretório gravável para o ledger.")
+
+
+def save(path, data):
+    data["updatedAt"] = now()
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp = tempfile.mkstemp(dir=path.parent, prefix="." + path.name + ".")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temp, path)
+    finally:
+        if os.path.exists(temp):
+            os.unlink(temp)
+
+
+def candidates():
+    if os.environ.get("CROW_LEDGER"):
+        return [Path(os.environ["CROW_LEDGER"]).expanduser()]
+    files = []
+    for directory in run_dirs():
+        if directory.is_dir():
+            files += directory.glob("*.json")
+    return files
+
+
+def locate(run_id=None, write=False):
+    """Find the ledger to read or update.
+
+    With a run id (--run or $CROW_RUN) the match is exact. Without one, only
+    ledgers whose cwd is the working directory or one of its ancestors are
+    considered, and a write is refused when more than one of them is running:
+    guessing would put this session's units into another session's run.
+    """
+    run_id = run_id or os.environ.get("CROW_RUN") or None
+    pinned = bool(os.environ.get("CROW_LEDGER"))
+    cwd = str(Path.cwd())
+    found = []
+    for path in candidates():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            mtime = path.stat().st_mtime
+        except (OSError, ValueError):
+            continue
+        if not isinstance(data, dict) or data.get("schema") != SCHEMA:
+            continue
+        if run_id and data.get("id") != run_id:
+            continue
+        if not run_id and not pinned and isinstance(data.get("cwd"), str) and not under(cwd, data["cwd"]):
+            continue
+        found.append(((data.get("status") == "running", mtime), path, data))
+    if not found:
+        raise SystemExit("crow_ledger: nenhuma execução encontrada" + (" com id " + run_id if run_id else "") +
+                         "; use start primeiro.")
+    running = [item for item in found if item[2].get("status") == "running"]
+    if not run_id and not pinned and len(running) > 1 and write:
+        ids = ", ".join(sorted(str(item[2].get("id")) for item in running))
+        raise SystemExit("crow_ledger: mais de uma execução em andamento neste diretório (" + ids +
+                         "); passe --run <id> (o id impresso por start).")
+    best = max(found, key=lambda item: item[0])
+    return best[1], best[2]
+
+
+def bar(fraction, width=20):
+    filled = int(round(max(0.0, min(1.0, fraction)) * width))
+    return "[" + "#" * filled + "-" * (width - filled) + "]"
+
+
+def clean(text, limit=120):
+    text = " ".join("".join(c if c.isprintable() else " " for c in str(text or "")).split())
+    return text if len(text) <= limit else text[: limit - 3] + "..."
+
+
+def render(data):
+    units = data.get("units", [])
+    counted = [u for u in units if u.get("status") != "skipped"]
+    done = sum(u.get("status") == "done" for u in counted)
+    overall = sum(1.0 if u.get("status") in ("done", "skipped") else float(u.get("progress") or 0) for u in units) / len(units) if units else 0.0
+    icons = {"done": "x", "running": ">", "failed": "!", "pending": " ", "skipped": "-"}
+    lines = ["crow > " + clean(data.get("title")) + " [" + data.get("status", "running") + "]",
+             bar(overall) + " " + str(int(overall * 100)) + "%  " + str(done) + "/" + str(len(counted)) + " unidades"]
+    phases = data.get("phases", []) or []
+    known = [p.get("id") for p in phases]
+    groups = [(p.get("title") or p.get("id"), [u for u in units if u.get("phase") == p.get("id")]) for p in phases]
+    loose = [u for u in units if u.get("phase") not in known]
+    if loose:
+        groups.append(("(sem fase)", loose))
+    for title, members in groups:
+        finished = sum(u.get("status") in ("done", "skipped") for u in members)
+        lines.append("- " + clean(title) + " " + str(finished) + "/" + str(len(members)))
+        for unit in members:
+            progress = 1.0 if unit.get("status") in ("done", "skipped") else float(unit.get("progress") or 0)
+            owner = " @" + clean(unit.get("owner"), 30) if unit.get("owner") else ""
+            lines.append("  [" + icons.get(unit.get("status"), "?") + "] " + clean(unit.get("title") or unit.get("id"), 70) +
+                         " " + bar(progress, 10) + " " + str(int(progress * 100)) + "%" + owner)
+            if unit.get("summary") and unit.get("status") in ("done", "failed"):
+                lines.append("      " + clean(unit["summary"]))
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(dest="command", required=True)
+    start = sub.add_parser("start")
+    start.add_argument("--title", required=True)
+    start.add_argument("--host", default="other",
+                       help="claude, codex, gemini (Gemini CLI), agy (Antigravity; nunca gemini), devin ou other")
+    start.add_argument("--phase", action="append", default=[], help="id=Título; repetir na ordem")
+    start.add_argument("--session", help="ID da sessão do host, se conhecido (tokens exatos e status line da sessão certa)")
+    start.add_argument("--global", dest="global_only", action="store_true",
+                       help="grava em ~/.crow/runs (tarefa somente leitura no diretório ou clone compartilhado)")
+    phase = sub.add_parser("phase")
+    phase.add_argument("id")
+    phase.add_argument("--title")
+    phase.add_argument("--status", choices=UNIT_STATUSES)
+    unit = sub.add_parser("unit")
+    unit.add_argument("id")
+    unit.add_argument("--title")
+    unit.add_argument("--phase")
+    unit.add_argument("--owner")
+    unit.add_argument("--status", choices=UNIT_STATUSES)
+    unit.add_argument("--progress", type=float)
+    unit.add_argument("--summary")
+    finish = sub.add_parser("finish")
+    finish.add_argument("--status", choices=RUN_STATUSES[1:], default="done")
+    for name in ("show", "path"):
+        child = sub.add_parser(name)
+        child.add_argument("--run")
+    for child in (phase, unit, finish):
+        child.add_argument("--run")
+    args = p.parse_args(argv)
+
+    if args.command == "start":
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+        run_id = stamp + "-" + slug(args.title)
+        path = Path(os.environ["CROW_LEDGER"]).expanduser() if os.environ.get("CROW_LEDGER") else writable_dir(args.global_only) / (run_id + ".json")
+        phases = []
+        for item in args.phase:
+            pid, _, title = item.partition("=")
+            phases.append({"id": pid.strip(), "title": (title or pid).strip(), "status": "pending"})
+        data = {"schema": SCHEMA, "id": run_id, "title": args.title, "host": args.host.lower(), "cwd": str(Path.cwd()),
+                "status": "running", "startedAt": now(), "endedAt": None, "phases": phases, "units": []}
+        if args.session:
+            data["session"] = {"host": args.host.lower(), "id": args.session}
+        save(path, data)
+        print(run_id + " " + str(path))
+        return 0
+    path, data = locate(getattr(args, "run", None), write=args.command in ("phase", "unit", "finish"))
+    if args.command == "path":
+        print(path)
+        return 0
+    if args.command == "show":
+        print(render(data))
+        return 0
+    if args.command == "phase":
+        phases = data.setdefault("phases", [])
+        entry = next((x for x in phases if x.get("id") == args.id), None)
+        if entry is None:
+            entry = {"id": args.id, "title": args.title or args.id, "status": "pending"}
+            phases.append(entry)
+        if args.title:
+            entry["title"] = args.title
+        if args.status:
+            entry["status"] = args.status
+    elif args.command == "unit":
+        units = data.setdefault("units", [])
+        entry = next((x for x in units if x.get("id") == args.id), None)
+        if entry is None:
+            entry = {"id": args.id, "title": args.title or args.id, "owner": "", "status": "pending", "progress": 0.0,
+                     "startedAt": None, "endedAt": None, "summary": ""}
+            units.append(entry)
+        for field in ("title", "phase", "owner", "summary"):
+            if getattr(args, field) is not None:
+                entry[field] = getattr(args, field)
+        if args.progress is not None:
+            entry["progress"] = max(0.0, min(1.0, args.progress))
+        if args.status:
+            entry["status"] = args.status
+            if args.status == "running" and not entry.get("startedAt"):
+                entry["startedAt"] = now()
+            if args.status in ("done", "failed", "skipped"):
+                entry["endedAt"] = now()
+                if not entry.get("startedAt"):
+                    entry["startedAt"] = entry["endedAt"]
+                if args.status in ("done", "skipped"):
+                    entry["progress"] = 1.0
+    elif args.command == "finish":
+        data["status"] = args.status
+        data["endedAt"] = now()
+    save(path, data)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())