groundfast 0.7.7

package/skills/wrap/references/formats.md

@@ -0,0 +1,85 @@
+# Formatos do wrap
+
+Fonte única dos templates. O corpo da skill decide **quando** escrever; este arquivo, **o shape**.
+
+## Tasks
+
+Campos: `id`, `title`, `state` (`open|doing|blocked|done|dropped`), `updated` (`YYYY-MM-DD`), e opcionalmente `evidence`, `notes`, `deps`, `branch`, `worktree`.
+
+Mudança de estado é **linha nova com o mesmo `id`**. O script exige `id`/`title`/`state`/`updated` válidos e recusa o append inteiro se qualquer linha falhar; chaves extras passam.
+
+## Memória do projeto
+
+`memory.md` é a **visão corrente**, não um diário. Três seções fixas, nesta ordem, cada bullet terminando na data `(YYYY-MM-DD)`:
+
+```markdown
+# Memória do projeto — <projeto>
+
+## Decisões negativas — NÃO reverter sem evidência nova
+## Fonte de verdade
+## Processo que funcionou
+```
+
+Tema já coberto se **funde** no bullet existente, com a data atualizada; tema novo entra como bullet novo. **Remova** o que ficou obsoleto, o que virou seção estrutural do `CLAUDE.md`/`AGENTS.md` ou o que virou código. Decisão negativa nunca é removida, só fundida.
+
+Repo com o formato antigo (blocos `## … (data)` apendados): converta inteiro neste wrap, preservando a data de cada bullet.
+
+## Arquivo de instruções
+
+`AGENTS.md` é o canônico da casa: o Pi carrega um arquivo por diretório (`AGENTS.md` antes de `CLAUDE.md`), o Codex lê só `AGENTS.md`, e o Claude Code chega lá por um `CLAUDE.md` de uma linha, `@AGENTS.md`. As seções Learned vivem **num arquivo só** — o que `repo-state.sh` nomeia em `## Arquivo de instruções`, pela regra de `scripts/learn-file.sh`:
+
+| Repo | Alvo |
+| :-- | :-- |
+| `CLAUDE.md` importa `@AGENTS.md`, ou não existe | `AGENTS.md` |
+| `CLAUDE.md` dono (sem import) | `CLAUDE.md`; `AGENTS.md` só se as seções Learned já vivem lá e não nele |
+
+Import inline conta (`Leia @AGENTS.md antes`); import dentro de código não conta, e o Claude Code também não o avalia.
+
+Repo sem nenhum dos dois: crie `AGENTS.md` e um `CLAUDE.md` de uma linha, `@AGENTS.md`; os dois entram no commit B.
+
+Seção Learned no arquivo que **não** é o alvo (o `verify.sh` acusa no check 4c): mova os bullets para o alvo neste wrap, fundindo com os que já estão lá, deixe o outro arquivo sem a seção e leve os dois no commit B. O check 4b soma os dois arquivos, então mover não conta como bullet novo.
+
+## HANDOFF.md
+
+Sobrescreva no worktree principal com exatamente estas seções, nesta ordem:
+
+```markdown
+# HANDOFF — <projeto>
+Atualizado: YYYY-MM-DD HH:MM BRT (<motivo>)
+
+## Done
+## Arquivos tocados
+## Decisões
+## Verificação
+## Tasks abertas
+## Estado do repo
+## Pendências / Riscos
+## Próxima ação física
+```
+
+- **Done** descreve efeito, não atividade.
+- **Verificação** cola resultado de comando que rodou nesta sessão.
+- **Tasks abertas** vem de `tasks.sh open`.
+- **Próxima ação física** é a última seção e tem uma linha só.
+
+Cópia datada em `docs/handoffs/<YYYY-MM-DD>-<slug>.md` e linha no topo de `docs/handoffs/INDEX.md`: `- <data> — <slug> — <próxima ação>`.
+
+Repo com `HANDOFF.md` legado: mova as decisões para `memory.md` **antes** de sobrescrever.
+
+## Espelho `.remember/remember.md`
+
+```markdown
+# Handoff
+
+## State
+<uma a três frases: onde o trabalho parou>
+
+## Next
+1. <próxima ação física>
+2. <as demais tasks abertas>
+
+## Context
+- <o que a próxima sessão precisa saber para não repetir descoberta>
+```
+
+Sem projeto: no Claude `~/.remember/remember.md`; no Pi a extensão sobe do cwd até a raiz git e para — sem git, só o cwd. Não atravessa diretório world-writable.

package/skills/wrap/references/selection.md

@@ -0,0 +1,25 @@
+# Seleção por destino
+
+O wrap **escreve** a tríade; esta régua decide o que entra em cada destino. Nada além do agente escreve a tríade: um overlay de julgamento, se houver, só observa ou pede revisão — não grava, não apaga e não substitui o gate humano de Learned.
+
+## Destinos
+
+| Destino | Entra quando | Não entra quando |
+| :-- | :-- | :-- |
+| Handoff | Informação corrente, com evidência, para retomar: resultado, decisão, verificação, bloqueio, risco, próxima ação. Escopo desta tarefa vale aqui. | Preferência permanente, palpite, comando só sugerido. |
+| `memory.md` | Decisão (sobretudo negativa) com motivo; fonte de verdade; processo que **já** funcionou. Fundir duplicata. | Status transitório, cache de código/config, experimento ainda não feito. |
+| Memória nativa do host | Ponteiro do projeto (onde a tríade mora, qual é a próxima ação) e fato **cross-repo e não-derivável**: preferência do Mestre, cliente, prazo. Data absoluta. | O que o repo já registra; o que só vale neste repo (isso é Learned); host sem memória nativa. |
+| Learned Preferences | Correção explícita do Mestre **nesta sessão** sobre comportamento **deste repo**. | Pedido, aprovação, permissão, escopo de tarefa, preferência global. |
+| Learned Facts | Convenção **deste repo** **e** momento desta sessão em que a ausência causou erro/retrabalho repetível. | Descoberta isolada, dica genérica de ferramenta. |
+| Task | Trabalho acionável, bloqueio, ou `done` com evidência de comando **executado**. | Comando apenas proposto. Baixa utilidade não fecha pendência. |
+| Espelho | Cópia derivada do handoff. | Segunda seleção independente. |
+
+Estrutura de docs (README, Mapa, Verificar) atualiza-se no passo de docs vivas, no lugar onde já vive. Não vira Learned por ser importante.
+
+## Protegidos
+
+Decisão negativa, pendência aberta, bloqueio e próxima ação **não** são omitidos por score baixo. Dúvida vira revisão, não descarte.
+
+## Cobertura da sessão
+
+Fonte explícita, nunca o arquivo mais recente: [`session-coverage.md`](session-coverage.md). Sem fonte, declare cobertura indisponível e escreva só o que a sessão ainda contém.

package/skills/wrap/references/session-coverage.md

@@ -0,0 +1,49 @@
+# Cobertura da sessão
+
+“Sessão inteira” é o histórico **original** do arquivo explícito, não o contexto compactado que o modelo vê agora.
+
+## Fonte
+
+| Host | Identidade | Folha |
+| :-- | :-- | :-- |
+| Pi | `PI_SESSION_FILE` (absoluto). Não liste o diretório de sessões. | Último `id` gravado no arquivo, ou o 3º argumento posicional. Caminho = `parentId` até raiz. |
+| Claude Code | `${CLAUDE_CODE_SESSION_ID}` (ou `${CLAUDE_SESSION_ID}`) + arquivo `~/.claude/projects/<slug>/<id>.jsonl`, **somente se o `sessionId` interno coincidir com o nome do arquivo**. O slug sai de `${CLAUDE_PROJECT_DIR}`; sem ela, do toplevel git; sem repo, do cwd. | `last-prompt.leafUuid`. Caminho = `parentUuid`; no `system/compact_boundary`, que o zera, `logicalParentUuid` quando ele aparece antes no arquivo; com elo para frente ou ausente, a cadeia para no boundary. |
+
+O script recebe `<caminho> <host> <folha>` por posição — não há flag. Sem identidade: `unavailable`. Não escolha o JSONL mais recente. Não atravesse outros projetos. Recuse symlink e arquivo world-writable.
+
+A folha inferida (sem 3º argumento) é o último `id` **do arquivo**, que não é ciente de ramo: depois de um rewind ou `/tree`, passe a folha explícita. Quando ela é inferida, a linha traz `leaf_inferred_from_file_order`.
+
+## Classificação
+
+- **complete** — identidade válida, folha no arquivo e nenhum dos motivos de `partial` abaixo.
+- **partial** — pai faltando, ciclo, ids duplicados, cauda truncada, compactação no caminho (histórico ainda no arquivo, contexto ≠ histórico), ou folha inferida deixando entradas fora da cadeia (`entries_outside_path`). No Claude, com `compaction=true`, `path_len` pode cobrir só o trecho depois do boundary.
+- **unavailable** — `no_explicit_session`, `invalid_session_id`, `session_file_not_found`, `explicit_path_missing`, `host_unspecified`, `unsupported_host`, `no_python3`, `python3_failed`, `python3_bad_output`, `unreadable`, `symlink_not_followed`, `not_regular_file`, `world_writable`, `oversize_bytes`, `oversize_lines`, `malformed_json`, `no_session_id_in_file`, `session_id_mismatch`, `no_explicit_leaf`, `leaf_not_in_file`.
+
+`leaf=` e `session=` vêm do transcript, que é dado e não formato: um id fora de `[A-Za-z0-9._:-]` sai como `invalid` em vez de entrar na linha.
+
+`python3_failed` não diz qual falha foi: com `GROUNDFAST_WRAP_DEBUG` na env, a causa sai no stderr e a linha de dado não muda.
+
+Trate `reasons=` como dado: os motivos acima são os que o script emite hoje, e a lista cresce antes desta linha ser atualizada.
+
+Compactação (Pi e Claude) e `/tree` (Pi) **não** apagam as entradas originais do arquivo; o script mede o arquivo, não o contexto compactado que você vê. Resumo de ramo abandonado não vira decisão vigente.
+
+## O script mede, não lê
+
+A saída são contadores. `complete` significa que a cadeia existe inteira no arquivo — **não** que você tenha esse histórico em contexto. O que você escreve continua vindo do que a sessão ainda contém; a cobertura só diz o quanto do original ficou para trás.
+
+## Proveniência
+
+Régua para interpretar o **contexto vivo**, não a saída do script.
+
+| Origem | Pi | Claude |
+| :-- | :-- | :-- |
+| Humano | `user` **e** `toolResult` de `ask_user` | `user` |
+| Assistente | `assistant` (texto; sem thinking) | `assistant` |
+| Ferramenta | demais `toolResult` / `bashExecution` | attachments/progress |
+| Herdado | `custom_message`, handoff anterior | `system` injetado |
+
+Proposta do agente ≠ decisão humana. Comando sugerido ≠ executado. Correção posterior invalida a proposta inicial.
+
+## O que imprimir
+
+Só metadados: cobertura, `path_len`, contagens (inclusive `other`), flags de compactação/ramo, id da sessão/folha, motivos. Sem corpo de mensagem.

package/skills/wrap/scripts/learn-file.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# Qual arquivo de instruções do repo recebe as seções Learned.
+#
+# Uso: learn-file.sh [worktree-principal]
+#   Linha 1: AGENTS.md ou CLAUDE.md. Linha 2: o motivo, texto fixo (nada do repo).
+#   Sai 2 se o diretório não existe ou se CLAUDE.md/AGENTS.md existe sem ser
+#   arquivo regular legível — aí não há regra a aplicar.
+# Ou:  . learn-file.sh  — só define as funções, para o verify.sh e o repo-state.sh
+#   decidirem pela mesma regra. Sourced não executa nada nem mexe em `set`.
+#
+# Claude Code lê só CLAUDE.md; Pi lê um arquivo por diretório, AGENTS.md antes
+# de CLAUDE.md; Codex lê só AGENTS.md. Convenção da casa: AGENTS.md canônico e
+# CLAUDE.md = `@AGENTS.md`. Regra, nesta ordem:
+#   CLAUDE.md ausente ou importando @AGENTS.md  → AGENTS.md
+#   CLAUDE.md dono com seção Learned            → CLAUDE.md
+#   CLAUDE.md dono, Learned só no AGENTS.md     → AGENTS.md
+#   CLAUDE.md dono, nenhum com Learned          → CLAUDE.md
+# Import inline conta (`Leia @AGENTS.md`); dentro de código não conta — o Claude
+# Code tokeniza o arquivo com marked e pula os tokens code e codespan antes de
+# procurar `@path` (visto no binário 2.1.261). O path vai até o espaço:
+# `@AGENTS.md.` ou `(@AGENTS.md)` não é este arquivo.
+#
+# Os greps leem até o fim (sem -q): quem chama tem pipefail, e um grep que sai
+# no primeiro match mata o pipeline a montante com SIGPIPE quando o arquivo é
+# longo o bastante para estourar o buffer de stdout — a função devolvia falso.
+
+# Fence (CommonMark): até 3 espaços de indentação; fecha só com o mesmo
+# caractere, comprimento >= o de abertura e nada além de espaço depois. `~~~`
+# dentro de um bloco ``` é conteúdo, ```text não fecha nada, e ``` com 4
+# espaços é código dentro do bloco.
+unfenced() { # [arquivo] — sem argumento, lê a stdin
+  awk '
+    match($0, /^ {0,3}(```+|~~~+)/) {
+      m = substr($0, RSTART, RLENGTH); sub(/^ +/, "", m)
+      rest = substr($0, RSTART + RLENGTH)
+      if (!f) { f = 1; fc = substr(m, 1, 1); fl = length(m); next }
+      if (substr(m, 1, 1) == fc && length(m) >= fl && rest ~ /^[[:space:]]*$/) { f = 0; next }
+    }
+    !f' "$@"
+}
+# Heading canônico: os dois nomes do passo 8, exatos — `## Learned Workspace
+# Facts Archive` não é seção Learned. verify.sh usa o mesmo padrão.
+LEARNED_HEADING='^## Learned (User Preferences|Workspace Facts)[[:space:]]*$'
+learned() { # <arquivo>
+  [ -f "$1" ] && unfenced "$1" | grep -E "$LEARNED_HEADING" >/dev/null
+}
+# Code span (CommonMark, e o marked): um run de N backticks fecha no próximo
+# run de exatamente N — na mesma linha ou nas seguintes do mesmo parágrafo.
+# Sem par até linha em branco, heading ou fim, o run é literal e o conteúdo
+# volta. Um sed com backreference perde ``@x `y``: `[^`]*` não atravessa o
+# backtick interno, cai no par de um e deixa o conteúdo à mostra.
+unspanned() { # stdin → stdout sem os code spans
+  awk '
+    function fecha(   pos) { # corta s logo após o fechamento de tamanho n
+      for (pos = 1; match(substr(s, pos), /`+/); pos += RSTART + RLENGTH - 1)
+        if (RLENGTH == n) { s = substr(s, pos + RSTART + RLENGTH - 1); return 1 }
+      return 0
+    }
+    {
+      s = $0; out = ""; h = (s ~ /^ {0,3}#{1,6}([[:space:]]|$)/)
+      if (n && (h || s ~ /^[[:space:]]*$/)) { print pend; n = 0 }
+      if (n) { if (fecha()) n = 0; else { pend = pend "\n" s; next } }
+      while (match(s, /`+/)) {
+        out = out substr(s, 1, RSTART - 1)
+        n = RLENGTH; run = substr(s, RSTART, n); s = substr(s, RSTART + n)
+        if (fecha()) { n = 0; continue }
+        pend = run s; s = ""; break
+      }
+      if (n && h) { out = out pend; n = 0 } # heading é bloco de uma linha
+      print out s
+    }
+    END { if (n) print pend }'
+}
+imports() {
+  [ -f "$1" ] && unfenced "$1" | unspanned \
+    | grep -E '(^|[[:space:]])@(\./)?AGENTS\.md([[:space:]]|$)' >/dev/null
+}
+learn_unreadable() { # <root> → nome do arquivo que existe sem ser regular e legível; exit 1 se nenhum
+  local f
+  for f in CLAUDE.md AGENTS.md; do
+    if [ -e "$1/$f" ] && ! { [ -f "$1/$f" ] && [ -r "$1/$f" ]; }; then echo "$f"; return 0; fi
+  done
+  return 1
+}
+
+# O alvo e o motivo saem do mesmo julgamento: quem decide é esta função, e as
+# duas abaixo só traduzem o estado. Assim as duas não podem discordar.
+learn_case() { # <root> → um nome de estado da regra
+  local c="$1/CLAUDE.md" a="$1/AGENTS.md"
+  if [ ! -f "$c" ]; then
+    [ -f "$a" ] && echo only-agents || echo none
+  elif imports "$c"; then
+    learned "$c" && echo import-owner || echo import
+  elif learned "$c"; then
+    learned "$a" && echo drift-owner || echo owner-learned
+  elif learned "$a"; then
+    echo agents-learned
+  else
+    echo owner
+  fi
+}
+
+learn_target() { # <root> → AGENTS.md | CLAUDE.md
+  case "$(learn_case "$1")" in
+    owner|owner-learned|drift-owner) echo CLAUDE.md ;;
+    *)                               echo AGENTS.md ;;
+  esac
+}
+
+learn_reason() { # <root> → uma linha, texto fixo
+  case "$(learn_case "$1")" in
+    none)           echo "nenhum dos dois existe — crie AGENTS.md e um CLAUDE.md de uma linha, @AGENTS.md" ;;
+    only-agents)    echo "CLAUDE.md não existe — crie-o com uma linha, @AGENTS.md, para o Claude Code ler o mesmo" ;;
+    import)         echo "CLAUDE.md importa @AGENTS.md" ;;
+    import-owner)   echo "CLAUDE.md importa @AGENTS.md — as seções Learned que ainda estão no CLAUDE.md vêm para cá" ;;
+    owner-learned)  echo "CLAUDE.md é o dono e já tem as seções Learned" ;;
+    drift-owner)    echo "CLAUDE.md é o dono e já tem as seções Learned — as do AGENTS.md vêm para cá" ;;
+    agents-learned) echo "CLAUDE.md é o dono, mas as seções Learned já vivem no AGENTS.md" ;;
+    owner)          echo "CLAUDE.md é o dono (sem @AGENTS.md)" ;;
+  esac
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  set -uo pipefail
+  root=${1:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}
+  [ -d "$root" ] || { echo "learn-file.sh: '$root' não é um diretório" >&2; exit 2; }
+  if bad=$(learn_unreadable "$root"); then
+    echo "learn-file.sh: $bad existe em $root mas não é arquivo regular legível" >&2
+    exit 2
+  fi
+  learn_target "$root"
+  learn_reason "$root"
+  exit 0
+fi

package/skills/wrap/scripts/repo-state.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Inventário do estado do repositório para o fechamento de sessão.
+#
+# Garantias: nunca imprime conteúdo de arquivo — só caminho, nome de branch,
+# assunto de commit, contagem e texto fixo deste script. Nome de branch e
+# assunto de commit são texto livre escrito por humano e podem carregar segredo,
+# então passam por redação best-effort. Toda linha é truncada: a saída daqui
+# entra direto no prompt.
+set -uo pipefail
+
+here=$(cd "$(dirname "$0")" && pwd -P)
+# Redação é garantia, não conveniência: sem o redact.sh (ou com um que não
+# carrega) o script para, em vez de imprimir branch e commit crus no prompt.
+redact_file="$here/../../../scripts/redact.sh"
+# shellcheck source=../../../scripts/redact.sh
+{ [ -f "$redact_file" ] && [ -r "$redact_file" ] && . "$redact_file"; } \
+  || { echo "(redact.sh ausente ou inválido em $here/../../../scripts — sem redação; abortando)"; exit 2; }
+
+# Corpo de seção: a garantia do cabeçalho — nada cru no prompt — mora aqui, e
+# não em sete cópias que uma edição distraída deixa sem `| redact`.
+body() { # <texto quando não há nada> — conteúdo já truncado na stdin
+  local b
+  b=$(cat)
+  [ -n "$b" ] && printf '%s\n' "$b" | redact || echo "$1"
+}
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "(fora de um repositório git — sem tríade; grave só memória nativa)"
+  exit 0
+fi
+
+main=$(git worktree list --porcelain 2>/dev/null | head -1)
+main=${main#worktree }
+top=$(git rev-parse --show-toplevel 2>/dev/null)
+
+echo "## Worktree principal"
+printf '%s\n' "${main:-(desconhecido)}" | redact
+[ -n "$main" ] && [ "$main" != "$top" ] && echo "ATENÇÃO: cwd está em worktree secundário — a tríade vai no principal"
+
+echo
+echo "## Branch"
+branch=$(git branch --show-current 2>/dev/null)
+if [ -n "$branch" ]; then
+  printf '%s\n' "$branch" | redact
+else
+  echo "(detached HEAD @ $(git rev-parse --short HEAD 2>/dev/null || echo 'sem commits'))"
+fi
+
+echo
+echo "## Operação em curso"
+inflight=
+for p in rebase-merge rebase-apply MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_LOG; do
+  [ -e "$(git rev-parse --git-path "$p" 2>/dev/null)" ] && inflight="$inflight $p"
+done
+[ -n "$inflight" ] && echo "EM CURSO:$inflight — não commite" || echo "(nenhuma)"
+
+echo
+echo "## Working tree"
+git status --porcelain 2>/dev/null | head -40 | body "(limpo)"
+
+echo
+echo "## Diff vs HEAD (linhas por arquivo)"
+git diff --stat HEAD 2>/dev/null | tail -30 | body "(sem diff)"
+
+echo
+echo "## Commits das últimas 24h"
+git log --since="24 hours ago" --format='%h %s' --no-decorate 2>/dev/null | head -20 | body "(nenhum)"
+
+echo
+echo "## Branches locais (upstream e ahead/behind)"
+git for-each-ref --format='%(refname:short) -> %(upstream:short) %(upstream:track)' refs/heads 2>/dev/null | head -30 | body "(nenhuma)"
+
+echo
+echo "## Worktrees"
+git worktree list 2>/dev/null | head -20 | body "(só o principal)"
+
+echo
+echo "## Stash"
+git stash list --format='%gd %ci %gs' 2>/dev/null | head -20 | body "(vazio)"
+
+echo
+echo "## Tríade"
+for f in HANDOFF.md tasks.jsonl memory.md; do
+  if [ -f "$main/$f" ]; then
+    echo "$f: existe ($(wc -l <"$main/$f" | tr -d ' ') linhas)"
+  else
+    echo "$f: ausente"
+  fi
+done
+
+echo
+echo "## Arquivo de instruções"
+# Mesma função que o verify.sh usa no 4c; o motivo é texto fixo do script, e
+# passa pela redação só para manter a garantia do cabeçalho em toda linha.
+learn_root=${main:-$top}
+# shellcheck source=./learn-file.sh
+if [ -f "$here/learn-file.sh" ] && [ -r "$here/learn-file.sh" ] && . "$here/learn-file.sh"; then
+  if bad=$(learn_unreadable "$learn_root"); then
+    echo "($bad existe mas não é arquivo regular legível — sem alvo; o verify.sh vai acusar)"
+  else
+    printf '%s — %s\n' "$(learn_target "$learn_root")" "$(learn_reason "$learn_root")" | redact
+  fi
+else
+  echo "(learn-file.sh ausente em $here — sem regra; o verify.sh vai acusar)"
+fi
+
+echo
+echo "## Plan files da sessão (7 dias)"
+find "$HOME/.claude/plans" -maxdepth 1 -name '*.md' -mtime -7 2>/dev/null | head -10 | body "(nenhum)"
+exit 0