@aksp/opencrew 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -3,6 +3,101 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.8.0] — 2026-10-07
+
+Fase U3a, fatia 1 "Pasta de entrega" (`specs/fase-u3a1-pasta-de-entrega.md`). Chega a quem já usa
+com um `npx @aksp/opencrew@latest update`, e funciona nas crews que já existem, sem mexer nelas.
+
+Ainda não nesta versão: PDF e "posts formatados" não são gerados pela entrega (`artigo.md`,
+`corpo.md` e os roteiros saem em markdown, e o LEIA-ME ensina a salvar como PDF pelo "Imprimir");
+copiar a entrega para uma pasta do projeto, registrar "entregar assim mesmo" e marcar "já
+publicado" ficam para a 1.9.0. O LEIA-ME e os nomes dos arquivos são só em português.
+
+### Added
+- **Pasta `entrega/`: o que você usa, separado por canal.** Depois da aprovação final, a crew
+  monta `crews/<crew>/output/<execução>/entrega/` com uma pasta por canal (`instagram/`,
+  `linkedin/`, `blog/`, `email/`, `whatsapp/`, `twitter/`, `youtube/`; só os que a execução tem).
+  Antes, você recebia a pasta da execução com `v1`, `v2`, relatórios e textos cheios de `#`, `**`
+  e rótulos.
+- **Texto pronto para colar.** `legenda.txt`, `post.txt` e `tweet.txt` saem sem `#`, `**`, rótulos
+  nem recados internos, com as hashtags no fim. O primeiro comentário do LinkedIn vem em arquivo
+  à parte; a thread, em `tweet-1.txt`, `tweet-2.txt`…; o blog, em `seo.txt` (título, meta
+  description, palavra-chave, slug) e `artigo.md`; o e-mail, em `assunto.txt`, `previa.txt` e
+  `corpo.md`; o WhatsApp, em `mensagem.txt`. As imagens vão para a pasta do canal com o nome
+  original, sem alteração; o HTML dos slides, para `editaveis/`.
+- **`LEIA-ME.md` em cada entrega.** Diz o que fazer com cada arquivo, canal por canal, em passos
+  numerados; marca cada canal como "Pronto" ou "Não está pronto"; lista em "Antes de usar" o que
+  falta; e diz o que não foi conferido (links e fatos, texto dentro das imagens, aparência final
+  em cada rede).
+- **O que não está pronto fica marcado.** Texto com `[PREENCHER]`, acima de um limite ou arquivo
+  que faltou: o canal aparece como "Não está pronto" e a crew pergunta se você quer corrigir agora
+  ou seguir assim. Se a legenda, o post ou o tweet passar do limite por causa das hashtags no fim,
+  o LEIA-ME traz um alerta.
+- **Arquivo sem canal não se perde.** Proposta, minuta, relatório ou formato que não é de rede
+  nenhuma vai inteiro para `outros/`, com o nome original, e aparece no LEIA-ME.
+- **Entrega de uma execução antiga.** Peça à IA para montar a entrega de uma execução já
+  encerrada: ela lista os arquivos, pede o seu "sim" e monta a pasta.
+- Crew que publica sozinha (Instagram, por exemplo): a entrega é montada antes da publicação, e
+  o LEIA-ME avisa "Esta crew publica este canal sozinha. Antes de postar à mão, confira se já saiu."
+
+### Changed
+- **O fim da execução aponta para `entrega/` e para o LEIA-ME**, não mais para a pasta da execução
+  e para um "arquivo final" que ninguém dizia qual era. A cópia do arquivo final na raiz da
+  execução deixa de ser feita.
+- A pasta `entrega/` é refeita do zero a cada entrega e fica fora do git: o que você editar ali se
+  perde. Para guardar, copie a pasta para outro lugar do projeto (o LEIA-ME avisa).
+- Se o script da entrega não rodar (sem Node, por exemplo), a execução não para: a crew avisa e
+  lista os arquivos aprovados.
+
+### Fixed
+- **O título do arquivo era lido como legenda.** Num arquivo com `# Legenda — …` no topo e a
+  legenda de verdade mais abaixo, o verificador media duas legendas e podia dar alerta falso.
+  Agora o título do arquivo não conta como peça.
+
+### Internal
+- `_opencrew/core/scripts/entregar.mjs` e os módulos de `scripts/entrega/` (sem dependência, até
+  200 linhas cada); `_opencrew/core/prompts/entrega.prompt.md`; seção `### Entrega` no runner, que
+  perde "Save final output", "Run folder" e "Output saved to".
+- Regra 15 do `AGENTS.md`: script do runtime só escreve onde foi combinado.
+- Travas novas: `tests/entregar*.test.js`, `tests/runtime-contracts-u3a.test.js`,
+  `tests/upgrade-u3a.test.js` e o U3a-14c em `tests/package.test.js`.
+- Roteiro renumerado: U3a fatia 2 = 1.9.0, U3b = 1.10.0, U4 = 1.11.0.
+
+## [1.7.1] — 2026-10-06
+
+Fase R3 "Reparos do runner em uso real" (`specs/fase-r3-runner-em-uso-real.md`): dois defeitos
+achados numa execução real de crew, seguindo o runner ao pé da letra. Chega a quem já usa com um
+`npx @aksp/opencrew@latest update`. Execuções antigas continuam legíveis.
+
+### Fixed
+- **A crew parava no segundo passo com "Input … not found".** O passo procurava o arquivo de
+  entrada num caminho em que o passo anterior não tinha gravado (a pesquisa estava em `v1/`, e a
+  entrada era procurada fora dela). Agora a entrada de um passo é sempre a saída mais nova daquele
+  arquivo, em qualquer pasta de versão.
+- **No Windows, cada conferência dependia de a IA traduzir um comando de bash** (`test -s`,
+  `grep`, `ls | sort | tail`, `mkdir -p`). Um erro de tradução virava validação que falhava sem
+  motivo. Esses comandos saíram do runner.
+- O Architect proibia criar pasta por comando e o runner mandava criar: os dois agora dizem a
+  mesma coisa (ninguém cria pasta por comando).
+
+### Changed
+- **Quem calcula os caminhos da execução é um script, não a IA.** O runner roda um comando curto
+  (`_opencrew/core/scripts/caminho.mjs`), igual em qualquer sistema, para criar a pasta da
+  execução, saber onde cada passo grava, achar a entrada e conferir o arquivo gravado. Existência,
+  número de seções e TL;DR saem numa conferência só; antes eram até três.
+- A pasta de versão continua subindo como antes (`v1`, `v2`, `v3`… a cada passo que grava), agora
+  em ordem numérica (`v10` vem depois de `v9`). O script só cria pastas, e só dentro de
+  `crews/<crew>/output/<execução>/`; nunca cria, altera nem apaga arquivo.
+- Se o script não rodar (sem Node, por exemplo), a execução não para: o runner avisa uma vez,
+  segue pela regra escrita e lista esses arquivos como "não verificado" na aprovação final.
+- Saber se a memória da crew está no formato novo e se o `runs.md` existe passa a ser feito lendo
+  o arquivo, sem comando de terminal. Na criação de crew, as crews existentes são listadas pela
+  ferramenta da IDE, não por `ls`.
+
+### Internal
+- Travas novas: `tests/caminho.test.js`, `tests/caminho-casca.test.js`,
+  `tests/runtime-contracts-r3.test.js` e `tests/upgrade-r3.test.js`; os testes R2-04d que contavam
+  comandos de bash no runner passam a proteger as aspas nos comandos novos.
 ## [1.7.0] — 2026-10-06
 
 Fase E1 "Escritório ao vivo — a equipe trabalhando, em 8 bits"

package/README.md

@@ -32,6 +32,9 @@ dentro da sua IDE.**
   mensal, lançamento de produto. Comece em 2 minutos.
 - 📤 **Exportação multi-formato** — PDF, CSV e posts formatados por plataforma,
   sem abrir editor nenhum.
+- 📬 **Entrega por canal** — depois de aprovar, você encontra a pasta `entrega/`: uma pasta por
+  canal (Instagram, LinkedIn, blog, e-mail, WhatsApp, X/Twitter, YouTube), o texto pronto para
+  colar, as imagens e um `LEIA-ME.md` com o passo a passo. O que não está pronto fica marcado.
 - 🎛️ **Seleção inteligente de agentes** — o sistema analisa seu pedido e
   sugere quais agentes são necessários para aquela tarefa. Você confirma ou
   ajusta com um clique. Agentes pulados não gastam tokens naquele run.
@@ -178,9 +181,9 @@ meu-projeto/
 │   │   ├── skills.engine.md      ← gerenciador de skills
 │   │   ├── architect.agent.yaml  ← definição do Arquiteto
 │   │   ├── best-practices/       ← 22 guias de melhores práticas + _catalog.yaml
-│   │   ├── scripts/              ← verificador, conferência de fontes e os scripts do Escritório
+│   │   ├── scripts/              ← verificador, conferência de fontes, caminhos, entrega e os scripts do Escritório
 │   │   ├── escritorio/           ← página do Escritório ao vivo (abre com /opencrew dashboard)
-│   │   └── prompts/              ← 13 prompts de fase (discovery, design, build, etc.)
+│   │   └── prompts/              ← 14 prompts de fase (discovery, design, build, entrega, etc.)
 │   ├── agents/                   ← 5 agentes base compartilhados
 │   │   ├── researcher.agent.md
 │   │   ├── copywriter.agent.md
@@ -194,6 +197,9 @@ meu-projeto/
 │
 ├── crews/                        ← suas crews vivem aqui
 │   ├── blog-semanal/             ← template: blog semanal
+│   │   └── output/<execução>/    ← criada a cada execução
+│   │       ├── v1/  v2/  …       ← o que cada passo gravou
+│   │       └── entrega/          ← o que você usa: LEIA-ME.md + uma pasta por canal
 │   ├── instagram-carrossel/      ← template: Instagram carrossel
 │   ├── newsletter-mensal/        ← template: newsletter
 │   └── lancamento-produto/       ← template: lançamento
@@ -209,6 +215,50 @@ meu-projeto/
 
 ---
 
+## Entrega por canal
+
+Depois da aprovação final, a crew monta a pasta `entrega/` dentro da pasta da execução
+(`crews/<crew>/output/<execução>/entrega/`). É ali que está o que você vai usar:
+
+```
+entrega/
+├── LEIA-ME.md      ← comece por aqui: o que fazer com cada arquivo, canal por canal
+├── instagram/      ← legenda.txt (hashtags no fim) e as imagens, com o nome original
+├── linkedin/       ← post.txt e, se houver, post-comentario.txt (o primeiro comentário)
+├── blog/           ← seo.txt (título, meta description, palavra-chave, slug) e artigo.md
+├── email/          ← assunto.txt, previa.txt e corpo.md
+├── whatsapp/       ← mensagem.txt
+├── twitter/        ← tweet.txt (na thread: tweet-1.txt, tweet-2.txt…)
+├── youtube/        ← o roteiro
+├── outros/         ← arquivo sem canal (proposta, minuta, relatório), como está
+└── editaveis/      ← o HTML dos slides, para quem quiser ajustar
+```
+
+Só aparecem as pastas que a execução tem.
+
+- **Texto pronto para colar.** Os `.txt` saem sem `#`, `**`, rótulos nem recados internos, com as
+  hashtags no fim. Com mais de uma peça do mesmo tipo, os arquivos são numerados (`post-1.txt`,
+  `post-2.txt`).
+- **O `LEIA-ME.md` diz o que fazer.** Cada canal tem a situação ("Pronto" ou "Não está pronto"),
+  os arquivos, de onde cada um veio e os passos, numerados. "Antes de usar" junta o que falta;
+  "O que não foi conferido" lembra o que ninguém mediu (links e fatos, texto dentro das imagens,
+  aparência final em cada rede).
+- **O que não está pronto fica marcado.** Sobrou um `[PREENCHER]` ou um texto acima do limite? O
+  canal aparece como "Não está pronto" e a crew pergunta se você quer corrigir agora ou seguir
+  assim.
+- **Arquivo sem canal vai para `outros/`**, inteiro e com o nome original: nada some.
+- **A pasta é refeita a cada entrega e fica fora do git.** O que você editar ali se perde; para
+  guardar, copie a pasta para outro lugar do projeto.
+- **Execução antiga?** Peça à IA: "monte a entrega da execução X da crew Y". Ela lista os
+  arquivos, pede o seu "sim" e monta a pasta. Funciona em crews criadas antes da 1.8.0, depois
+  do `update`.
+
+A entrega não gera PDF nem imagem: `artigo.md`, `corpo.md` e os roteiros saem em markdown, e o
+LEIA-ME ensina a salvar como PDF pelo "Imprimir" do seu editor. O LEIA-ME e os nomes dos arquivos
+são sempre em português.
+
+---
+
 ## Escritório ao vivo
 
 Quer ver a equipe trabalhando? O **Escritório** é uma página em pixel-art, aberta no navegador,

package/package.json

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

package/templates/AGENTS.md

@@ -61,6 +61,7 @@ Route input to the matching action:
 | `/opencrew dashboard` | Turn on and open the Escritório (live view) — see "Dashboard (Optional)" |
 | `/opencrew dashboard off` | Turn the Escritório off — see "Dashboard (Optional)" |
 | `/opencrew reset` | Confirm and reset all configuration |
+| Request to deliver a run that already ended ("monte a entrega da execução …") | Load `_opencrew/core/prompts/entrega.prompt.md` → build the `entrega/` folder of that run |
 | Natural language about crews | Infer intent and route accordingly |
 
 ## Loading Agents
@@ -120,6 +121,8 @@ and touch nothing else: stop no process, delete no file.
 - Exception: crew memory scaffolding (`memories.md` headers, `runs.md` columns)
   keeps fixed PT-BR structural labels regardless of the user's language —
   see `_opencrew/core/runner.pipeline.md`
+- Exception: the delivery folder (`entrega/`) — its folder names, file names and the `LEIA-ME.md`
+  are written by a script in fixed PT-BR, whatever the user's language
 
 ## Critical Rules
 

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.7.0
+1.8.0

package/templates/_opencrew/core/architect.agent.yaml

@@ -32,7 +32,7 @@ agent:
       - Each agent must have exactly one clear responsibility
       - Pipelines must have checkpoints at every user decision point
       - Default to the simplest pipeline that achieves the goal
-      - "Path safety: Never use Bash mkdir to create directories. Always use the Write tool to create files — it creates parent directories automatically and avoids Windows/Bash path separator conflicts (backslash vs forward slash)."
+      - "Path safety: Never create directories by command (no Bash mkdir, on any system). Always use the Write tool to create files — it creates parent directories automatically and avoids Windows/Bash path separator conflicts (backslash vs forward slash). At run time, the folders of a run are created by the runner (`_opencrew/core/scripts/caminho.mjs`), never by a command of yours."
 
   discussion: true
 

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

@@ -305,7 +305,7 @@ target_formats:  # content crews only; empty list for others
 
 The `crew_code` must be a short, URL-safe slug derived from the crew's purpose (e.g., `content-calendar`, `competitor-tracker`, `lead-notify`).
 
-**CRITICAL — Name uniqueness:** The `crew_code` MUST NEVER match any existing folder name in `crews/`. Before finalizing, run `ls crews/ 2>/dev/null` (Bash) to list existing crew directories. If the slug you derive matches an existing folder, append a numeric suffix (`-2`, `-3`, etc.) until it is unique. Never reuse an existing crew folder name — doing so would overwrite another crew's files.
+**CRITICAL — Name uniqueness:** The `crew_code` MUST NEVER match any existing folder name in `crews/`. Before finalizing, list the existing folders of `crews/` with the IDE's folder-listing tool (no shell command); if `crews/` does not exist yet, there are none. If the slug you derive matches an existing folder, append a numeric suffix (`-2`, `-3`, etc.) until it is unique. Never reuse an existing crew folder name — doing so would overwrite another crew's files.
 
 ---
 

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

@@ -0,0 +1,131 @@
+# Entrega — The Delivery Folder of a Run
+
+One script turns the approved files of a run into `crews/{name}/output/{run_id}/entrega/`: one
+folder per channel, text ready to paste and a `LEIA-ME.md` that tells the user what to do with each
+file. Your part is to build the list of files, run the script and act on its last line.
+
+You do NOT copy, split, rename or rewrite a file yourself, and you never write inside `entrega/`:
+the script rebuilds that folder from scratch on every call. **When** the delivery runs is in the
+section "Entrega" of `_opencrew/core/runner.pipeline.md`; a request to deliver a run that is
+already over starts at "A run that already ended", below.
+
+## Step 1: Build the list
+
+`{lista}` is one item per file, separated by commas, each written `{caminho}={formato}`.
+
+- **What goes in:** for each **creation or rendering step** of the approved run, every path the
+  `saida` action of `caminho.mjs` returned the **last time** the step ran (a step sent back by the
+  reviewer ran more than once: only its last version counts) — all the output files of the step,
+  images and HTML included. Use the paths you stored during the run. Never look for a `vN` folder
+  by yourself and never assume `v1`.
+- **`{formato}`** is the `format:` of the step that wrote the file. A rendering step with no
+  `format:` uses the `format:` of the content step it renders (the slides of an `instagram-feed`
+  carousel go as `=instagram-feed`). With no format either way, with an export format (`pdf`,
+  `csv`, `formatted-post`) or with one outside `[a-z0-9-]+`, the item goes without `={formato}`:
+  the script puts that file in `outros/`.
+  This list is **not** the list of the checker (`verificar.mjs`), where a step with no `format:`
+  goes without one: here the rendering step (images, HTML) takes the format of the content step it
+  renders — the step that wrote its `inputFile`. Without it the images land in `outros/`.
+- **Stay out:** research, briefing, the reviewer's verdict, checkpoint answers and every skipped
+  step (a deselected agent, or a step the user skipped).
+- **Safe names** — the safe-name rule (nome seguro) of the runner applies. A file that rule left
+  out of commands stays out of the list too; tell the user:
+  `{arquivo} — ficou fora da entrega: nome com caractere que não vai em comando`.
+
+## Step 2: Channels the crew publishes by itself
+
+Add `--vai-publicar {canal}` once for each channel of the list that has an irreversible step in the
+pipeline (`side_effects: irreversible`, in the step or in the agent's skill), whether that step
+already ran or not. The `LEIA-ME.md` then opens that channel with: "Esta crew publica este canal
+sozinha. Antes de postar à mão, confira se já saiu."
+
+- The channel of a step is the `platform:` of its `format:` — read it in
+  `_opencrew/best-practices.local/{format}.md` when that file declares `platform:`, otherwise in
+  `_opencrew/core/best-practices/{format}.md`. For a step with no `format:`, the one of the skill
+  (`instagram-publisher` → `instagram`). With neither, do not pass the option.
+- `{canal}` is the folder name: `instagram`, `linkedin`, `blog`, `email`, `whatsapp`, `twitter` or
+  `youtube`. Only a channel that has an item in the list (an item whose format has that
+  `platform:`) — for any other the script stops with `Canal não encontrado nesta entrega: {canal}.`
+
+## Step 3: Run the script
+
+From the project root, one line, everything between double quotes:
+
+`node _opencrew/core/scripts/entregar.mjs --crew "crews/{name}" --run "{run_id}" --arquivo "{lista}"`
+
+With channels from Step 2, the same command ends with one option per channel:
+
+`node _opencrew/core/scripts/entregar.mjs --crew "crews/{name}" --run "{run_id}" --arquivo "{lista}" --vai-publicar {canal}`
+
+## Step 4: Show the result and read the last line
+
+The output of the script is the final summary of the run (the folder, each channel as "Pronto" or
+"Não está pronto", what is missing, the path of the `LEIA-ME.md`): show it to the user as it came,
+without the `ENTREGA:` line. Do not rewrite it and do not add files it does not list. Besides the
+`entrega/` folder, the script also writes `crews/{name}/output/{run_id}/verificacao-entrega.md`,
+the report of the check made at delivery time (it is not part of the delivery).
+
+- `ENTREGA:OK` → go on with the run.
+- `ENTREGA:INCOMPLETA` → a channel is not ready, or a file could not be written. The files were
+  generated anyway and the `LEIA-ME.md` marks the channel. Show what is missing and ask:
+  ```
+  ⚠️ A entrega ficou incompleta: {o que falta}
+  1. Corrigir agora (eu ajusto e monto a entrega de novo)
+  2. Seguir assim (no LEIA-ME, o canal fica marcado como "Não está pronto")
+  ```
+  Wait for the answer.
+  - **1** — for each item that is missing, fix it in the source file the summary names: ask the
+    user for the real information of every `[PREENCHER: …]`, shorten what is over a limit, write
+    again a file that is not there (when the summary says a file could not be written, there is
+    nothing to fix in the text). Then run the delivery again, with the same list.
+  - **2** — go on, with the delivery as it is. Every irreversible step still asks for its own
+    confirmation, as it does today.
+
+After "Edit this content" (the final menu of the runner) changes an approved file, or any step
+runs again after the delivery, run the delivery again with the new paths: the folder is rebuilt
+from scratch, so whatever was edited inside `entrega/` is lost — the `LEIA-ME.md` says so.
+
+## When the script does not run
+
+The script did not run when there is no Node, an error, or no `ENTREGA:` line at the end (it prints
+one line in PT-BR and stops, with nothing written). Then never build the folder by hand. If the line points to something in the
+command you wrote (an option, a channel, the run), fix the command and run it once more. Otherwise
+tell the user, list the approved files (the paths of your list) and go on with the run:
+
+```
+⚠️ A entrega automática não rodou: {motivo}
+Os arquivos aprovados estão em:
+- {caminho}
+```
+
+`{motivo}` is the line the script printed, or what kept it from running. The completion summary
+of the runner then shows this list in place of the `entrega/` folder.
+
+## A run that already ended
+
+When the user asks to deliver a run that is over (it was run before this folder existed, or the
+delivery did not run):
+
+1. Find the crew and the run. If the user did not say which, list the folders of
+   `crews/{name}/output/` with the IDE's folder-listing tool (no shell command) and ask.
+2. Read the steps of `crews/{name}/pipeline/`. For the `outputFile` of each creation or rendering
+   step (same rules of Step 1 for what stays out and for `{formato}`), run:
+   `node _opencrew/core/scripts/caminho.mjs "{name}" entrada --run "{run_id}" --arquivo "{outputFile}"`
+   `CAMINHO:OK {path}` → that path is the item. `CAMINHO:FALTA` → the file is not in that run:
+   leave it out.
+3. Nobody recorded what was approved in that run, so show the list and wait for the "sim":
+   ```
+   Entrega da execução {run_id} da crew {name}. Arquivos:
+   - {caminho} ({formato})
+   Posso montar a entrega com esta lista? (sim / não)
+   ```
+4. On "sim", follow Steps 2 to 4. No step of the pipeline runs again, and nothing is published.
+
+## Rules
+
+- **DO** show the output of the script as it came; the folder and file names and the `LEIA-ME.md`
+  are fixed PT-BR, whatever the user's language.
+- **DO** run the delivery again whenever an approved file changes.
+- **DO NOT** create, edit or delete anything inside `entrega/` yourself.
+- **DO NOT** put in the list a file the user did not approve, nor a path you guessed.
+- **DO NOT** treat `ENTREGA:INCOMPLETA` as an error of the script: it is its answer.