@aksp/opencrew 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.14.0] — 2026-10-08
+
+Fase U5, fatia 3: "Execução registrada" (`specs/fase-u5c-execucao-registrada.md`). Chega a quem já
+usa com um `npx @aksp/opencrew@latest update`; as crews e as execuções antigas ficam como estão.
+
+Ainda não nesta versão: o pedido avulso à crew (1.15.0).
+
+### Added
+- **`/opencrew retomar <nome>`.** A execução que parou no meio — a conversa caiu, o contexto
+  acabou — continua de onde parou, em qualquer conversa nova. A IA mostra o tema, o que já está
+  pronto e de que passo vai seguir, e espera o seu sim. O que foi gravado e conferido não é
+  refeito; o passo que estava no meio é refeito inteiro.
+- **Registro da execução.** Cada execução deixa na pasta dela um `execucao.json`, gravado por
+  script a cada passo: o tema, os passos conferidos, as suas respostas nas aprovações e os
+  vereditos da revisão. A IA não escreve nesse arquivo. Não há comando a mais por passo: o
+  registro pega carona no que a execução já rodava.
+- **`/opencrew repair` olha o histórico.** Pasta de execução sem linha no `runs.md` vira um ponto
+  do conserto: ele pergunta o tema e grava a linha como `Registrada depois`, com cópia
+  `runs.md.bak`. Linha sem pasta e pasta vazia são só apontadas: nada é apagado.
+
+### Changed
+- **O histórico (`runs.md`) é gravado pelo script, não pela IA** — também quando a execução é
+  abortada ou rejeitada, que antes ficavam de fora. As colunas são as mesmas, e as linhas que já
+  existem não mudam.
+- **O Score tem uma definição só:** aprovações suas sem pedido de correção, sobre as aprovações
+  que você respondeu (`2/3`). Quem conta é o script. Antes o texto dava duas contas diferentes, e
+  numa crew real saiu uma nota.
+- **Regra de Ouro contada de verdade.** As correções ficam no registro de cada execução; no fim, o
+  script mostra as das 10 últimas e a IA procura ali o que se repetiu em 3 ou mais. Antes ela
+  procurava na memória da crew, que não guarda dado de execução. A seção se chama
+  `## Regras de Ouro`, um nome só.
+- O `LEIA-ME.md` da entrega abre com o tema da execução, quando o registro tem um.
+
+### Limites
+- O registro só sabe o que os comandos contam: se a IA pular o aviso de uma aprovação, o score
+  sai errado para menos.
+- Execução feita antes desta versão não tem registro: não dá para retomar, e só entra no
+  histórico pelo conserto.
+- Ao retomar, o que foi combinado só na conversa anterior, sem ter sido gravado, não volta.
+
 ## [1.13.0] — 2026-10-07
 
 Fase U5, fatia 2: "Runner dividido" (`specs/fase-u5b-runner-dividido.md`). Chega a quem já usa

package/README.md

@@ -182,12 +182,12 @@ meu-projeto/
 │   ├── core/
 │   │   ├── system.md             ← 🧠 sistema completo do OpenCrew
 │   │   ├── runner.pipeline.md    ← executor de pipeline (o que toda execução usa)
-│   │   ├── runner/               ← 7 partes do executor, lidas só quando é o caso (painel, fim da execução…)
+│   │   ├── runner/               ← 8 partes do executor, lidas só quando é o caso (painel, fim da execução, retomar…)
 │   │   ├── skills.engine.md      ← gerenciador de skills
 │   │   ├── architect.agent.yaml  ← definição do Arquiteto
 │   │   ├── formato-da-crew.md    ← o formato dos arquivos de uma crew (crew.yaml, pipeline.yaml, passos)
 │   │   ├── best-practices/       ← 24 guias de melhores práticas + _catalog.yaml
-│   │   ├── scripts/              ← verificador, conferência de fontes, caminhos, entrega, documento Word, conserto de crews e os scripts do Escritório
+│   │   ├── scripts/              ← verificador, conferência de fontes, caminhos, registro da execução, entrega, documento Word, conserto de crews e os scripts do Escritório
 │   │   ├── modelos/              ← modelo do perfil de documento oficial (papel timbrado)
 │   │   ├── escritorio/           ← página do Escritório ao vivo (abre com /opencrew dashboard)
 │   │   └── prompts/              ← 15 prompts de fase (discovery, design, build, entrega, documento, etc.)
@@ -206,6 +206,7 @@ meu-projeto/
 ├── crews/                        ← suas crews vivem aqui
 │   ├── blog-semanal/             ← template: blog semanal
 │   │   └── output/<execução>/    ← criada a cada execução
+│   │       ├── execucao.json     ← registro da execução, gravado por script (é o que o `/opencrew retomar` lê)
 │   │       ├── v1/  v2/  …       ← o que cada passo gravou
 │   │       └── entrega/          ← o que você usa: LEIA-ME.md + uma pasta por canal (copiada para a pasta do projeto que você escolher)
 │   ├── instagram-carrossel/      ← template: Instagram carrossel
@@ -294,6 +295,25 @@ são sempre em português.
 
 ---
 
+## Histórico e execução interrompida
+
+Cada execução deixa um registro na pasta dela (`crews/<crew>/output/<execução>/execucao.json`):
+o tema, os passos já gravados e conferidos, o que você respondeu em cada aprovação. Quem grava é
+um script, a cada passo — a IA não escreve nesse arquivo.
+
+- **O histórico da crew** (`crews/<crew>/_memory/runs.md`) ganha uma linha por execução, também
+  gravada pelo script: a que terminou, a que você abortou e a que a revisão rejeitou. A coluna
+  Score tem um significado só: aprovações suas sem pedido de correção, sobre as aprovações que você
+  respondeu (`2/3`).
+- **A conversa caiu no meio?** Em qualquer conversa nova, peça `/opencrew retomar <nome>`. A IA
+  mostra o tema, o que já está pronto e de que passo vai continuar, e espera o seu sim. O que já
+  foi gravado e conferido não é refeito; o passo que estava no meio é refeito inteiro. O que foi
+  combinado só na conversa anterior, sem ter sido gravado, não volta.
+- **Execução antiga fora do histórico?** O `/opencrew repair <nome>` mostra as pastas de execução
+  sem linha no histórico, pergunta o tema de cada uma e grava a linha como `Registrada depois`,
+  com cópia `runs.md.bak`. Linha sem pasta e pasta vazia são só apontadas: nada é apagado.
+- Execução feita antes da 1.14.0 não tem registro: não dá para retomar.
+
 ## Documento Word
 
 Ata, ofício, declaração, contrato: quando o resultado é um documento para imprimir, assinar ou
@@ -499,9 +519,10 @@ npx @aksp/opencrew update --check
 | `/opencrew` | Abre o menu principal |
 | `/opencrew create <descrição>` | Cria uma nova crew a partir da sua descrição |
 | `/opencrew run <nome>` | Executa o pipeline de uma crew |
+| `/opencrew retomar <nome>` | Continua a execução que parou no meio (a conversa caiu, o contexto acabou): mostra o que já está pronto e segue do passo seguinte, sem refazer o que foi gravado |
 | `/opencrew list` | Lista todas as suas crews |
 | `/opencrew edit <nome>` | Modifica uma crew existente |
-| `/opencrew repair <nome>` | Mostra o que falta numa crew que você já tem (formato de cada texto, arquivos do projeto que ela deve ler, proibições que o verificador consegue barrar, nomes dos agentes) e conserta um ponto por vez, com o seu sim e uma cópia `.bak` |
+| `/opencrew repair <nome>` | Mostra o que falta numa crew que você já tem (formato de cada texto, arquivos do projeto que ela deve ler, proibições que o verificador consegue barrar, nomes dos agentes, execuções que ficaram fora do histórico) e conserta um ponto por vez, com o seu sim e uma cópia `.bak` |
 | `/opencrew delete <nome>` | Remove uma crew |
 | `/opencrew skills` | Navega, instala ou remove skills |
 | `/opencrew install <skill>` | Instala uma skill do catálogo |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/AGENTS.md

@@ -59,6 +59,7 @@ Route input to the matching action:
 | `/opencrew create <description>` | Load the Architect (`_opencrew/core/architect.agent.yaml`) → Create Crew flow: one prompt per phase, listed there |
 | `/opencrew list` | List all crews in `crews/` (a folder without `crew.yaml` is not a crew) |
 | `/opencrew run <name>` | Load Pipeline Runner → Execute crew |
+| `/opencrew retomar <name>` | Load Pipeline Runner → resume the run of that crew that stopped in the middle (`_opencrew/core/runner/retomar.md`) |
 | `/opencrew edit <name> <changes>` | Load the Architect → Edit Crew flow |
 | `/opencrew repair <name>` | Load `_opencrew/core/prompts/repair.prompt.md` → show what an existing crew is missing and fix one point at a time, each with a `.bak` copy |
 | `/opencrew skills` | Load Skills Engine → Show skills menu |

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.13.0
+1.14.0

package/templates/_opencrew/core/prompts/build.prompt.md

@@ -36,6 +36,8 @@ Generate these files directly — they are compilations of data already gathered
 
    ## Proibições Explícitas
 
+   ## Regras de Ouro
+
    ## Técnico (específico do crew)
    ```
    - `crews/{code}/_memory/runs.md` — empty run history log:

package/templates/_opencrew/core/prompts/repair.prompt.md

@@ -2,7 +2,7 @@
 
 You are the opencrew Repair agent. A crew built by an older version misses what later versions
 added: the format of each text, the project sources, bans the checker can enforce, the persona
-names. Your job is to show the user what is missing in **one crew that already exists** and fix
+names, the runs that never reached the history. Your job is to show the user what is missing in **one crew that already exists** and fix
 one point at a time, each with the user's yes.
 
 **You never write inside `crews/` yourself.** Every change is one command of the script below,
@@ -33,6 +33,8 @@ It only reads. Its last line is the status:
 
 - `CONSERTO:OK` — say "A crew {nome} está em dia: não há o que consertar." and stop.
 - `CONSERTO:PENDENTE` — one block per finding, each starting with `[código]`. Go to Step 3.
+- A line starting with `Nota:` (with any status) is information, not a finding: show it to the
+  user once, in plain words; there is nothing to fix and nothing is deleted.
 - `CONSERTO:ERRO`, or the script did not run (no Node, an error) — show the user the message as
   it came and stop. Do not repair by hand.
 
@@ -60,6 +62,7 @@ codes between brackets, the `--aplicar` lines or the `CONSERTO:` status line.
 | `sem-aprovacao-final` | "Depois da revisão não há um ponto de aprovação seu. Isso se resolve editando a crew: /opencrew edit {nome}." | none |
 | `publica-antes` | "O passo {n} publica ou envia antes da revisão e da sua aprovação final. Enquanto estiver assim, o que sai não passou pela revisão. Isso se resolve editando a crew: /opencrew edit {nome}." | none |
 | `passo-faltando` | Show the lines the script printed and say that it is solved by editing the crew: `/opencrew edit {nome}` | none |
+| `historico` | For each listed run folder: "A pasta {run} tem arquivos de uma execução que não está no histórico: {arquivos}. Qual foi o tema dela? (Se não lembrar, responda 'não sei'.)" With 'não sei', the theme is `não informado`. A folder the script marks as `interrompida` can still be resumed: say so (`/opencrew retomar {nome}`) and register it only if the user prefers. An empty folder (`execução abandonada`) and a row with no folder are only shown: nothing is deleted | `--aplicar "historico:{run}={tema}"` — the theme on one line, with only letters, digits, spaces and `. , : ; - ( ) / ?` |
 
 The command is always the same line, with the item between double quotes:
 

package/templates/_opencrew/core/runner/fim-da-execucao.md

@@ -31,46 +31,35 @@ After applying all candidates, write the updated `memories.md`.
 
 If no candidates are found (the run had no explicit user feedback), skip writing `memories.md` entirely — do not write an unmodified copy. Always proceed to step 2b regardless.
 
-### 2b. Prepend to `runs.md` (reverse-chronological log — newest run first)
+### 2b. Prepend to `runs.md` — the script writes the row
 
-If `crews/{name}/_memory/runs.md` does not exist, create it first with:
-```markdown
-# Run History: {crew-name}
+Never write `crews/{name}/_memory/runs.md` yourself. Close the run with the `fechar` command of the runner ("Run record"): `--resultado` is `aprovado` (the final approval was given), `publicado` (an irreversible step published or sent) or `rejeitado` (the review rejected at the last cycle and the user aborted); `--saida` is a brief description of what was generated (e.g. "Carrossel 9 slides", "Thread 7 posts"); add `--tema "{tema}"` (1 sentence max) if no command of this run carried the topic yet.
 
-| Data | Run ID | Tema | Output | Score | Resultado |
-|------|--------|------|--------|-------|-----------|
-```
-Then proceed to prepend the new row.
-
-Read `crews/{name}/_memory/runs.md`. Prepend one new row to the table (immediately after the header row), with:
-- `Data`: the date of this run (the first 10 characters of the `run_id`)
-- `Run ID`: the `run_id` for this execution
-- `Tema`: the topic or user request from this run (1 sentence max)
-- `Output`: brief description of what was generated (e.g., "Carrossel 9 slides", "Thread 7 posts")
-- `Score`: `{approved}/{total}` agent outputs approved without corrections (e.g., `4/5`)
-- `Resultado`: one of — `Aprovado` / `Rejeitado` / `Publicado` / `Abortado`
+The script writes the row of this run right below the header — `Data | Run ID | Tema | Output | Score | Resultado`, newest run first; a row this run already had is replaced — and prints it. No other data.
 
-No other data.
+`Score` has one definition, and the script counts it from the recorded checkpoints: the checkpoints the user approved without corrections ÷ the checkpoints the user answered (approved + corrected; a skipped one does not count), e.g. `2/3`; `—` when none was answered. Never compute it yourself.
 
-The `Score` column tracks how many agent outputs were approved by the user without corrections in this run. Count only explicit checkpoint approvals (not "skip" or "continue"). Format: `{approved}/{total checkpoints}` (e.g., `4/5` means 4 of 5 agent outputs were approved as-is).
+- Last line `EXECUCAO:FECHADA {resultado} {score}` → go on to 2c. A line `Não consegui gravar o histórico desta execução: {motivo}` before it → show it to the user as it came.
+- The script did not run (no Node, an error, no `EXECUCAO:` line) → tell the user `⚠️ Não consegui gravar o histórico desta execução: {motivo}` and go on. Do not write the row by hand.
 
 ### 2c. Post-Run Reflection (pattern detection)
 
-After updating `memories.md` and `runs.md`, run a reflection pass. This is a lightweight analysis — not a full agent execution, just pattern matching on the run's feedback and past memory.
+After updating `memories.md` and closing the run, run a reflection pass. This is a lightweight analysis — not a full agent execution, just pattern matching on the corrections of this run and of the last runs.
 
 1. **Collect this run's corrections**: From checkpoint responses, gather every user rejection or correction. A correction is:
    - A rejected output with a reason ("tom muito informal", "cor não combina", "fonte sem data")
    - A modification request during checkpoint ("muda o título para X", "usa azul em vez de verde")
 
-2. **Look for recurrence**: Compare each correction against past runs recorded in `memories.md`:
-   - Search `memories.md` for similar patterns (same category, same agent, same type of correction)
-   - Count: how many past runs have a correction matching this pattern?
-   - A "match" means the same agent + same type of error (e.g., "redator + tom informal", "designer + cores saturadas")
+2. **Look for recurrence**: use the list the `fechar` command printed under `Correções das últimas execuções:` — one line per correction recorded in the last 10 closed runs of this crew, this one included (`- {run_id} · passo {N} · {nota}`).
+   - Do not search `memories.md` for past runs: by rule it keeps no run data.
+   - Count: in how many different runs of that list does the same pattern appear?
+   - A "match" means the same step (so the same agent) + the same type of error (e.g. "redator + tom informal", "designer + cores saturadas")
+   - No list was printed → there is nothing to compare: skip items 3 and 4.
 
 3. **Promote to Regra de Ouro**: If the SAME pattern appears in **3 or more runs** (including this one):
-   a. Add a new entry under `## Regras de Ouro` in `memories.md`:
+   a. Add a new entry under `## Regras de Ouro` in `memories.md` (the header is exactly this, fixed PT-BR; create the section if the file does not have it):
       ```markdown
-      ## Regras de Ouro (promovidas após 3+ ocorrências)
+      ## Regras de Ouro
 
       - **{Agent role}**: SEMPRE {correct behavior}. {Why — grounded in user feedback}.
         (Runs: #{run1}, #{run2}, #{run3})
@@ -94,7 +83,7 @@ After updating `memories.md` and `runs.md`, run a reflection pass. This is a lig
 
 5. **Bail out early**: If this run had zero corrections (all checkpoints approved), skip the entire reflection — nothing to learn.
 
-6. **Reflection budget**: Maximum 30 seconds of analysis. If the crew has a long history (>20 past runs), sample the most recent 10 runs for pattern matching. This is a quick scan, not an exhaustive audit.
+6. **Reflection budget**: Maximum 30 seconds of analysis: the list of the script is all the history you read. This is a quick scan, not an exhaustive audit.
 
 3. Present completion summary:
 ```

package/templates/_opencrew/core/runner/memoria.md

@@ -13,6 +13,7 @@ preferred language.
 | `## Design Visual` | `memories.md` | Visual design preferences per crew |
 | `## Estrutura de Conteúdo` | `memories.md` | Content structure rules per crew |
 | `## Proibições Explícitas` | `memories.md` | User bans and hard blocks per crew |
+| `## Regras de Ouro` | `memories.md` | Corrections repeated in 3 or more runs, promoted at the end of a run |
 | `## Técnico (específico do crew)` | `memories.md` | Technical crew-specific settings |
 | `Data \| Run ID \| Tema \| Output \| Score \| Resultado` | `runs.md` | Run history table columns |
 
@@ -41,6 +42,8 @@ unless the user base expands beyond PT-BR — at that point, discuss a migration
 
         ## Proibições Explícitas
 
+        ## Regras de Ouro
+
         ## Técnico (específico do crew)
         ```
         (Use the crew's display name for `{crew-name}`, and the crew code for `{name}` in file paths — they refer to the same crew.)

package/templates/_opencrew/core/runner/retomar.md

@@ -0,0 +1,51 @@
+# Resuming a run (retomar)
+
+> Part of the Pipeline Runner (`_opencrew/core/runner.pipeline.md`). Read it only on `/opencrew retomar {name}`.
+
+A run that stopped in the middle — the conversation ended, the context ran out — left its record on
+disk. Resuming is going on from the step after the last one that was done, with the same `run_id`:
+what was written and checked is not redone; the step that was in the middle is done again, whole.
+
+1. From the project root, with the crew code between double quotes (safe-name rule of the runner):
+   ```
+   node _opencrew/core/scripts/execucao.mjs "{name}" retomar
+   ```
+2. Read the last line:
+   - `EXECUCAO:NADA` → say `Não há execução interrompida da crew {nome}.` and stop (to start a new
+     run: `/opencrew run {name}`).
+   - `EXECUCAO:RETOMAR {run_id} {N}` → the lines before it are the theme, the steps already checked
+     (each with its file), the checkpoints already answered and the verdicts of the review. Go to 3.
+   - The output starts with `Execuções abertas` → more than one run is open: show the list and ask
+     which one. For one that is not the newest, run the command again with `--run "{run_id}"`.
+   - A line `Não consegui ler na crew para qual passo a revisão … volta` → show it and confirm the
+     step with the user before going on.
+   - No `EXECUCAO:` line (no Node, an error) → show the message as it came and stop. Never rebuild
+     the state of a run by looking at its folder, and never read `execucao.json` yourself.
+3. Ask, and wait for the answer:
+   `A execução {run} ({tema}) parou depois do passo {k}. Já estão prontos: {lista}. Continuo do passo {N}?`
+   (`{run}`: the `run_id`; `{k}`: the step of the line `Parou depois do passo`; `{lista}`: the files
+   under `Passos conferidos` — not the ones under `Já gravados, mas serão feitos de novo`; a run
+   with no theme goes without the parentheses.)
+   - No → change nothing. Ask `Quer que eu encerre essa execução como abortada?`; after a yes, run
+     the `fechar` command of the runner ("Run record") with `--resultado abortado`, so it is no
+     longer offered. Then stop.
+4. Only now, after the yes (nothing of the runner's Initialization runs before the question): do the Initialization of the runner in full (memory format, source check, project
+   sources, pipeline, skills, tiers, agent selection, the header) **except step 5b**: do not run
+   `pasta` — the `run_id` is the one of the `EXECUCAO:RETOMAR` line.
+   Step 6 (the Escritório) happens as in a new run.
+5. Go on at step `{N}` of "For each pipeline step", with that `run_id`:
+   - Every input comes from the `entrada` command, as always: it finds what the earlier steps wrote.
+   - The paths under `Passos conferidos` are the stored paths of those steps: use them to show a
+     file at a checkpoint and to build the list of the delivery.
+   - Do not ask again a checkpoint the script listed as answered: its answer is in the file the
+     checkpoint saved (the `inputFile` of the step after it), or in the note the script printed.
+   - Step `{N}` is done whole, even when a file of it is already there (`saida` opens a new version).
+   - A review cycle the script listed counts: the cycles left are `max_review_cycles` minus the
+     verdicts under `Revisões:` for that review step (no such section: none), and the next
+     `verificacao-ciclo-{N}.md` is that number plus 1.
+   - The `Tema:` line says whether the record has a topic: `(sem tema)` → send `--tema` with the
+     next `marcar` or with `fechar`.
+   - `{N}` is after the last step of the pipeline (the script says `Todos os passos já foram feitos`)
+     → go straight to "After Pipeline Completion".
+6. Say once, before the first step: `Retomei pelo que está gravado. O que foi combinado só na conversa anterior não veio junto.`
+   A resumed run is recorded and closed like any other (`conferir --passo`, `marcar`, `fechar`).

package/templates/_opencrew/core/runner.pipeline.md

@@ -24,6 +24,7 @@ included), digits, space and `. _ - / \ : ( )`. With any other character (`$`, b
 
 ## Initialization
 
+**Resuming** — only on `/opencrew retomar {name}`: before any step below, read `_opencrew/core/runner/retomar.md` completely and follow it — it asks the user first, then says when to do this Initialization, with no step 5b (no new folder: the run goes on with its `run_id`).
 Before starting execution:
 
 1. You have already loaded:
@@ -90,7 +91,7 @@ Before starting execution:
    When the selection step was skipped (no `agent_dependencies:` in crew.yaml), this is
    identical to today: all agents listed, no Skipped line.
 5b. **Initialize run folder**: the script names the run — never build the date or the time yourself:
-   - Run the `pasta` command (see "Output Path Transformation" below). It creates the folder of this run and answers `CAMINHO:OK crews/{name}/output/{run_id}`
+   - Run the `pasta` command (see "Output Path Transformation" below). It creates the folder of this run and its record, and answers `CAMINHO:OK crews/{name}/output/{run_id}`
    - The `run_id` is the last segment of that path: `YYYY-MM-DD-HHmmss` from the computer's clock (e.g. `2026-03-03-143022`; `-2`, `-3` when that folder already exists)
    - The date of this run, wherever one is asked below, is the first 10 characters of the `run_id`
    - Never create a folder by command yourself
@@ -265,10 +266,10 @@ root the one-line command of each moment and read the last line (`CAMINHO:OK {pa
 
 | Moment | Command |
 |---|---|
-| Start of the run (Initialization, step 5b) | `node _opencrew/core/scripts/caminho.mjs "{name}" pasta` (no `--run`: the script creates the `run_id`) |
+| Start of the run (Initialization, step 5b) | `node _opencrew/core/scripts/caminho.mjs "{name}" pasta --tema "{tema}" --passos {N}` (no `--run`: the script creates the `run_id`) |
 | Before a step, for its `inputFile` | `node _opencrew/core/scripts/caminho.mjs "{name}" entrada --run "{run_id}" --arquivo "{inputFile}"` |
 | Before a step writes, for the first `outputFile` of each group | `node _opencrew/core/scripts/caminho.mjs "{name}" saida --run "{run_id}" --arquivo "{outputFile}"` |
-| After a step wrote, for each output file | `node _opencrew/core/scripts/caminho.mjs "{name}" conferir --arquivo "{path}"` |
+| After a step wrote, for each output file | `node _opencrew/core/scripts/caminho.mjs "{name}" conferir --arquivo "{path}" --passo {step}` |
 
 - **Values** — `{name}`: the crew code. `{inputFile}` / `{outputFile}`: the path as the step
   declares it (raw, without the run_id). `{path}`: the path `saida` returned. The safe-name rule
@@ -297,6 +298,20 @@ root the one-line command of each moment and read the last line (`CAMINHO:OK {pa
   this way skips its gate and is listed at the final approval:
   `{arquivo} — não verificado: a conferência de caminhos não rodou`.
 
+### Run record (registro da execução)
+
+The scripts keep the record of the run on disk (`crews/{name}/output/{run_id}/execucao.json`): `/opencrew retomar` and the history (`runs.md`) are read from it. `pasta` and `conferir` feed it; you add one command at three moments:
+
+| Moment | Command |
+|---|---|
+| A checkpoint was answered and its answer saved | `node _opencrew/core/scripts/execucao.mjs "{name}" marcar --run "{run_id}" --passo {step} --evento checkpoint --resultado {resultado} --nota "{nota}"` |
+| The reviewer gave the verdict (each cycle) | `node _opencrew/core/scripts/execucao.mjs "{name}" marcar --run "{run_id}" --passo {step} --evento revisao --resultado {resultado} --nota "{nota}"` |
+| End of the run, and whenever it is aborted | `node _opencrew/core/scripts/execucao.mjs "{name}" fechar --run "{run_id}" --resultado {resultado} --saida "{saída}"` |
+
+- **Values** — `{step}`: the step's number in `pipeline.yaml` (`step:`; without it, its position, from 1) — the same in `conferir --passo`. `{resultado}`: checkpoint → `aprovado` (the user judged something the crew produced and accepted it as it is), `corrigido` (the answer asked for any change) or `pulado` (no judgement: the checkpoint only collected an answer — a topic, a choice — or was skipped); revisao → `aprovado` or `rejeitado`; fechar → `aprovado`, `publicado` (an irreversible step published or sent), `rejeitado` (the review rejected at the last cycle and the user aborted) or `abortado`. `{nota}`: the correction asked or the reason of the rejection — no `--nota` on an approval. `{tema}`: the topic of this run, in a few words; when only a checkpoint reveals it, start with no `--tema` and add `--tema "{tema}"` to that checkpoint's `marcar`. `{N}`: how many steps will run, checkpoints included. `{saída}`: what was produced ("Carrossel 9 slides").
+- **Text on the command line** (`{tema}`, `{nota}`, `{saída}`) — one line between double quotes, only letters (accents included), digits, spaces and `. , : ; - ( ) / ?`; drop every other sign, and omit the option when no text is left.
+- The scripts are the only writers: never read, write or describe `execucao.json` yourself, and never write `runs.md`. A warning `Não consegui gravar o registro desta execução`, or one of these commands not running, never stops the run: tell the user once and go on.
+
 ### For each pipeline step:
 
 0. **Agent deselection check** — Read the step's `agent:` frontmatter field.
@@ -365,6 +380,7 @@ root the one-line command of each moment and read the last line (`CAMINHO:OK {pa
 - **Always include the file path** of any generated content the user needs to review. Example: "Review the content at `crews/{name}/output/{run_id}/v2/content.md` and let me know if it looks good." (the path the script returned)
 - Wait for user input before proceeding
 - Save the user's choice/response for the next step
+- Record the answer with the `marcar` command (`--evento checkpoint`, see "Run record") — last thing of the checkpoint, after the memory and the `outputFile` below are written
 - **Correction → memory, right away**: if the answer corrects something (tone, audience, a term,
   a fact, a format), write it to `crews/{name}/_memory/memories.md` in the matching section
   **before the next step** (antes do próximo passo) — not only at the end of the run, which may
@@ -470,7 +486,7 @@ When a step has `on_reject: {step-id}` (a review step):
    final approval below collects the missing data from the user.
 3. Track the review cycle count: a **cycle** is one pass of the reviewer. The maximum is
    `max_review_cycles`, an integer from 1: the one declared where the step declares `on_reject` (the
-   step frontmatter or its `pipeline.yaml` entry); without it, the one in `crew.yaml`; absent or invalid in both: 3. On every rejection, with or
+   step frontmatter or its `pipeline.yaml` entry); without it, the one in `crew.yaml`; absent or invalid in both: 3. After each verdict — once the review file passed `conferir` — run `marcar` (`--evento revisao`, see "Run record"). On every rejection, with or
    without a block, send the reviewer's feedback to the writer and go back to the referenced step.
 4. If the last allowed pass also rejects, stop; the status of the last report picks the message, as
    in item 2 — `VERIFICACAO:BLOQUEADA`: the blocks; any other status: the reviewer's feedback, also
@@ -512,7 +528,7 @@ One script turns the approved files into `crews/{name}/output/{run_id}/entrega/`
 1b. **Escritório** — if it is on, run `concluir` (see "Escritório" above).
 
 2. **Close the run** — read `_opencrew/core/runner/fim-da-execucao.md` completely and follow it, in its
-   order: update `memories.md`, add the line to `runs.md`, the post-run reflection and the completion
+   order: update `memories.md`, close the run with the `fechar` command (the script writes the line of `runs.md`), the post-run reflection and the completion
    summary with the final menu. Never skip it, and never write the memory or the history from what you
    remember of it.
 
@@ -525,7 +541,7 @@ One script turns the approved files into `crews/{name}/output/{run_id}/entrega/`
 - If a step file is missing, inform the user and suggest running `/opencrew edit {crew}` to fix.
 - If company.md is empty, stop and redirect to onboarding.
 - Never continue past a checkpoint without user input.
-- When the run is aborted: if the Escritório is on, run `falhar` (see "Escritório" above).
+- When the run is aborted (by the user, by an error, or rejected at the last review cycle): run `fechar` with `abortado` or `rejeitado` (see "Run record") and, if the Escritório is on, run `falhar` (see "Escritório" above). A run that just stopped (the conversation ended) stays open: `/opencrew retomar` finds it.
 
 ## Pipeline State
 
@@ -540,4 +556,4 @@ Track pipeline state in memory during execution:
 - filtered_steps — the ordered steps that will actually run this execution
 - missing_dependency — true if the user knowingly ran with a broken dependency
 
-This state does NOT persist to disk — it exists only during the current run.
+This state lives in memory; what `/opencrew retomar` needs is on disk, in the run record (see "Run record").

package/templates/_opencrew/core/scripts/caminho/argumentos.mjs

@@ -6,15 +6,16 @@ import { ACOES } from './nucleo.mjs';
 export const USO = 'Uso: node _opencrew/core/scripts/caminho.mjs <crew> <ação> --run <id> [opções]';
 
 const LISTA = ACOES.join(', ');
-const OPCAO = /^--(run|arquivo|secoes|tldr)(?:=(.*))?$/s;
-const RUN = /^(?!\.+$)[A-Za-z0-9._-]+$/;
+const OPCAO = /^--(run|arquivo|secoes|tldr|tema|passos|passo)(?:=(.*))?$/s;
+/** O nome de uma execução: letras, dígitos, ponto, sublinhado e hífen (nunca só pontos). */
+export const RUN = /^(?!\.+$)[A-Za-z0-9._-]+$/;
 const INTEIRO = /^[1-9]\d{0,8}$/;
 
 /** Texto que veio da linha de comando e volta numa mensagem: uma linha só, até 200 caracteres. */
 export const limpar = (valor) => String(valor).replace(/\s+/g, ' ').trim().slice(0, 200);
 
 /**
- * `argv` → `{ crew, acao, run, arquivo, secoes, tldr }`. Os dois primeiros argumentos soltos são
+ * `argv` → `{ crew, acao, run, arquivo, secoes, tldr, tema, passos, passo }`. Os dois primeiros argumentos soltos são
  * a crew e a ação. Opção vale como `--nome valor` e `--nome=valor`; `--tldr` não leva valor.
  * Opção ausente fica `undefined`.
  */
@@ -37,7 +38,7 @@ export function lerArgs(argv) {
  * caminho já resolvido: é a única ação que não precisa de `--run`.
  * @returns {string|null} o motivo em PT-BR, ou `null`
  */
-export function erroDeArgumentos({ crew, acao, run, arquivo, secoes }) {
+export function erroDeArgumentos({ crew, acao, run, arquivo, secoes, passos, passo }) {
   if (!crew) return 'Falta o nome da crew.';
   if (!acao) return `Falta a ação. Ações: ${LISTA}.`;
   if (!ACOES.includes(acao)) return `Ação desconhecida: ${limpar(acao)}. Ações: ${LISTA}.`;
@@ -47,5 +48,7 @@ export function erroDeArgumentos({ crew, acao, run, arquivo, secoes }) {
   if (run !== undefined && !RUN.test(run)) return 'O --run só aceita letras, dígitos, ponto, sublinhado e hífen.';
   if (acao !== 'pasta' && !arquivo) return MSG.faltaOpcao('--arquivo');
   if (secoes !== undefined && !INTEIRO.test(secoes)) return 'O --secoes é um número inteiro a partir de 1.';
+  if (passos !== undefined && !INTEIRO.test(passos)) return 'O --passos é um número inteiro a partir de 1.';
+  if (passo !== undefined && !INTEIRO.test(passo)) return 'O --passo é um número inteiro a partir de 1.';
   return null;
 }

package/templates/_opencrew/core/scripts/caminho/crew.mjs

@@ -0,0 +1,20 @@
+// Onde fica a crew de um comando (`caminho.mjs`, `execucao.mjs`): uma pasta direta de `crews/`.
+// Spec: fase-r3-runner-em-uso-real.md, §3 (repositório do OpenCrew).
+import path from 'node:path';
+import { MSG, dentroDoProjeto } from '../comum.mjs';
+import { limpar } from './argumentos.mjs';
+import { ehPasta } from './disco.mjs';
+
+/**
+ * @param {string} raiz a pasta do projeto · @param {string} escrito o nome da crew (`crews/<nome>` também vale)
+ * @returns {{ erro: string } | { crew: string }} o erro de uso, ou o nome da pasta da crew
+ */
+export function acharCrew(raiz, escrito) {
+  if (!ehPasta(path.join(raiz, '_opencrew'))) return { erro: MSG.semRaiz };
+  const base = path.resolve(raiz, 'crews');
+  const nome = escrito.replace(/^crews[\\/]+/, '');
+  if (!dentroDoProjeto(base, nome)) return { erro: MSG.foraDoProjeto(limpar(escrito)) };
+  const pasta = path.resolve(base, nome);
+  if (path.dirname(pasta) !== base || !ehPasta(pasta)) return { erro: MSG.crewNaoEncontrada(limpar(escrito)) };
+  return { crew: path.basename(pasta) };
+}

package/templates/_opencrew/core/scripts/caminho/disco.mjs

@@ -1,5 +1,6 @@
 // O que o `caminho.mjs` faz no disco: lê nomes de pastas, confere se um arquivo tem conteúdo, lê
-// um arquivo e cria pastas. Nunca cria, altera nem apaga arquivo.
+// um arquivo e cria pastas. Nunca cria, altera nem apaga arquivo (o registro da execução é gravado
+// por `execucao/registro.mjs`).
 // Spec: fase-r3-runner-em-uso-real.md, regra 6 (repositório do OpenCrew).
 import { mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
 
@@ -32,5 +33,5 @@ export function temConteudo(arquivo) {
 
 export const lerTexto = (arquivo) => readFileSync(arquivo, 'utf8');
 
-/** Cria a pasta com as pastas-mãe; pasta que já existe não é erro. */
-export const criarPasta = (pasta) => { mkdirSync(pasta, { recursive: true }); };
+/** Cria a pasta com as pastas-mãe; pasta que já existe não é erro. @returns {boolean} criou alguma pasta? */
+export const criarPasta = (pasta) => mkdirSync(pasta, { recursive: true }) !== undefined;