@aksp/opencrew 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [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/package.json

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

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.7.0
+1.7.1

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/runner.pipeline.md

@@ -53,12 +53,9 @@ Before starting execution:
 > unless the user base expands beyond PT-BR — at that point, discuss a migration strategy
 > (e.g. i18n key mapping) rather than mixing languages in a single file.
 
-1b. **Memory format migration** — After loading `memories.md`, check whether it uses the new format by scanning for the `## Estilo de Escrita` section header:
-   ```bash
-   [ -f "crews/{name}/_memory/memories.md" ] && grep -q "## Estilo de Escrita" "crews/{name}/_memory/memories.md" && echo "NEW_FORMAT" || echo "OLD_FORMAT"
-   ```
-   - If `NEW_FORMAT` → proceed normally.
-   - If `OLD_FORMAT` (or file is empty / does not exist) → migrate before proceeding:
+1b. **Memory format migration** — After loading `memories.md`, check whether it uses the new format: it does when it has the `## Estilo de Escrita` section header (read the file with the read tool — no command).
+   - If it has the header → proceed normally.
+   - If it does not (or the file is empty / does not exist) → migrate before proceeding:
      a0. If the file exists and is not empty, FIRST copy it to `crews/{name}/_memory/memories.md.bak`
         (never lose what the crew learned), then tell the user in one line:
         "Atualizei o formato da memória da crew; a versão anterior está em `memories.md.bak`."
@@ -78,11 +75,8 @@ Before starting execution:
         ## 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.)
-     b. Check if `crews/{name}/_memory/runs.md` exists:
-        ```bash
-        test -f "crews/{name}/_memory/runs.md" && echo "EXISTS" || echo "MISSING"
-        ```
-        If `MISSING`, create it with:
+     b. Check if `crews/{name}/_memory/runs.md` exists (read tool — no command).
+        If it does not exist, create it with:
         ```markdown
         # Run History: {crew-name}
 
@@ -229,9 +223,9 @@ Before starting execution:
    identical to today: all agents listed, no Skipped line.
 5b. **Initialize run folder**: Generate a unique run ID for this execution:
    - Format: `YYYY-MM-DD-HHmmss` using the current timestamp (e.g. `2026-03-03-143022`)
-   - Check if `crews/{name}/output/{run_id}/` already exists
+   - Check (folder-listing tool, no command) if `crews/{name}/output/{run_id}/` already exists
      - If it does (sub-second collision), append `-2`, `-3`, etc. until the folder does not exist
-   - Create the folder using Bash: `mkdir -p "crews/{name}/output/{run_id}"`
+   - Create the folder: run the `pasta` command (see "Output Path Transformation" below) — never create a folder by command yourself
    - Store `run_id` in working memory for this run — it will be used for ALL output paths
 6. **Escritório** — if it is on, run `iniciar`, then one `pular` per deselected agent, one after the other (see "Escritório" below).
 
@@ -379,11 +373,9 @@ Before executing any step that references an agent:
 To prevent linear token growth across multi-agent pipelines, apply context compression
 when passing prior agents' outputs as context:
 
-1. **TL;DR extraction**: After each agent completes, check if its output contains a `## TL;DR` section.
+1. **TL;DR extraction**: After each agent completes, check if its output contains a `## TL;DR` section
+   (a line starting with `## TL;DR` — you have the output, no command is needed).
    If present, extract and store it separately as the agent's summary.
-   ```bash
-   grep -q "^## TL;DR" "{outputFile}" && echo "HAS_TLDR" || echo "NO_TLDR"
-   ```
 
 2. **Compressed context assembly**: When preparing context for Agent N:
    - Include **TL;DR summaries** from Agents 1 through N-2 (all agents except the direct predecessor)
@@ -441,7 +433,7 @@ When an agent's `.agent.md` frontmatter contains a `tasks:` field:
    e. Check task veto conditions (same enforcement as step veto conditions below)
 
 3. **Final output**: The output of the LAST task in the chain becomes the step's output
-   - Apply the Output Path Transformation (Steps 1 and 2: run_id injection + version folder) to the `outputFile` path before saving — this applies regardless of whether the step runs as `execution: inline` or `execution: subagent`
+   - Resolve the `outputFile` path with the `saida` command (Output Path Transformation) before saving — this applies regardless of whether the step runs as `execution: inline` or `execution: subagent`
    - Save to the **transformed** outputFile path
    - This is what the next step (or checkpoint) receives
 
@@ -455,40 +447,44 @@ When an agent's `.agent.md` frontmatter contains a `tasks:` field:
 
 ### Output Path Transformation
 
-Before saving any output file in a step, apply these rules to determine the final path:
-
-#### Step 1 — Insert run_id
-
-- If the path starts with `crews/{name}/output/`, insert `{run_id}/` immediately after `output/`
-  - Example: `crews/carousel/output/slides/draft.md` → `crews/carousel/output/2026-03-03-143022/slides/draft.md`
-  - Example: `crews/carousel/output/angles-brief.yaml` → `crews/carousel/output/2026-03-03-143022/angles-brief.yaml`
-- If the path does NOT start with `crews/{name}/output/`, leave it unchanged
-
-#### Step 2 — Insert version folder
-
-Apply to every path that was transformed in Step 1:
-
-1. Determine the **output group** = the parent directory of the file (after Step 1 transformation)
-   - Example: `crews/carousel/output/2026-03-03-143022/slides/draft.md` → group is `crews/carousel/output/2026-03-03-143022/slides/`
-   - Example: `crews/carousel/output/2026-03-03-143022/angles-brief.yaml` → group is `crews/carousel/output/2026-03-03-143022/`
-
-2. Detect existing versions for this group using Bash:
-   ```bash
-   ls -1 "crews/{name}/output/{run_id}/{relative-group}/" 2>/dev/null | grep -E '^v[0-9]+$' | sort -V | tail -1
-   ```
-   - If the command returns a version (e.g. `v2`) → use `v3`
-   (Always increment the highest version found, even if lower versions have gaps — e.g. if `v1` and `v3` exist, use `v4`)
-   - If the command returns nothing (no versions yet) → use `v1`
-   (`{relative-group}` is the portion of the group path after `crews/{name}/output/{run_id}/`, e.g. `slides/` or empty string for root-level files)
-
-3. Insert the version folder immediately before the filename:
-   - `crews/carousel/output/2026-03-03-143022/slides/draft.md` → `crews/carousel/output/2026-03-03-143022/slides/v1/draft.md`
-   - `crews/carousel/output/2026-03-03-143022/angles-brief.yaml` → `crews/carousel/output/2026-03-03-143022/v1/angles-brief.yaml`
-
-4. **Cache per group**: within a single step execution, once a version is determined for a group, reuse it for all subsequent files in that same group. Do not re-run the `ls` per file.
-   If the same file path is written twice within a step, both writes go to the same versioned path (the second write overwrites the first within that version).
+The path of every file of the run comes from one script (`caminho.mjs`), the same on every system —
+never from a path you put together, never from a shell command of your own. Run from the project
+root the one-line command of each moment and read the last line (`CAMINHO:OK {path}`,
+`CAMINHO:FALTA {path}` or `CAMINHO:REPROVADO {motivo}`):
 
-Apply this transformation consistently for every write in this step.
+| Moment | Command |
+|---|---|
+| Start of the run (Initialization, step 5b) | `node _opencrew/core/scripts/caminho.mjs "{name}" pasta --run "{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}"` |
+
+- **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
+  (nome seguro) applies: the crew and every path between double quotes.
+- **`saida`** answers with the **transformed** path and creates its folder: write the file there,
+  never to the raw path. Run it once per group in a step — the other `outputFile`s of the same
+  group reuse the version folder it returned, and a file written twice in a step goes to the same path.
+- **`entrada`** answers with the newest output of that file: use the path it returns, whatever
+  its version folder.
+- **The rule the script applies** (apply it yourself only when the script does not run):
+  1. A declared path that starts with `crews/{name}/output/` gets `{run_id}/` right after
+     `output/`; any other path stays as declared, with no version folder.
+  2. The **group** is the folder of the file, run_id included (`…/output/{run_id}/`, or
+     `…/output/{run_id}/slides/`). A step writes to the group's next version folder: the highest
+     `vN` there plus 1, or `v1` when there is none — numeric order (`v10` comes after `v9`), gaps
+     not filled (`v1` and `v3` → `v4`).
+  3. A step reads the newest version that has the file: from the highest `vN` down, the first
+     where the file exists and is not empty; then the group itself, with no version folder (where
+     checkpoint answers live).
+
+  Example, one group: the researcher writes `…/v1/pesquisa.md`, the writer writes `…/v2/post.md`
+  and reads `…/v1/pesquisa.md`. Never assume `v1`.
+- **Script that does not run** (no Node, an error, or no `CAMINHO:` line): tell the user once per
+  run `Não consegui rodar a conferência de caminhos; sigo pela regra escrita e marco os arquivos como não verificados.`,
+  build the path by the rule above (the Write tool creates the folder) and continue. A file handled
+  this way skips its gate and is listed at the final approval:
+  `{arquivo} — não verificado: a conferência de caminhos não rodou`.
 
 ### For each pipeline step:
 
@@ -505,13 +501,9 @@ Apply this transformation consistently for every write in this step.
 
 0b. **Escritório** — if it is on, run `passo`, or `checkpoint` when the step is a checkpoint (see "Escritório" above).
 
-1. **Pre-Step Input Validation** — MANDATORY. If the step's frontmatter declares an `inputFile`, validate that the input exists before executing the step. Run via Bash tool:
-   ```bash
-   test -s "{transformed inputFile path}" && echo "VALIDATION:PASS" || echo "VALIDATION:FAIL"
-   ```
-   - Apply the Output Path Transformation (Step 1: run_id injection) to the `inputFile` path before running the check.
-   - If the Bash output contains `VALIDATION:PASS` → proceed to execute the step.
-   - If the Bash output contains `VALIDATION:FAIL` → do NOT execute the step. Present to user:
+1. **Pre-Step Input Validation** — MANDATORY. If the step's frontmatter declares an `inputFile`, the input comes from the `entrada` action, never from a path you build: validate that the input exists before executing the step. Run the `entrada` command (Output Path Transformation) with the `inputFile` as declared:
+   - `CAMINHO:OK {path}` → that path is the step's input (the newest version that has the file): read the input from it and execute the step.
+   - `CAMINHO:FALTA {path}` → do NOT execute the step. Present to user:
      ```
      ⚠️ Input for {Agent Name} not found: {path}
      The previous step may have failed to produce output.
@@ -530,7 +522,7 @@ Apply this transformation consistently for every write in this step.
 - Inform user: `🔍 {Agent Name} is working in the background...`
 - Read the step's `model_tier` frontmatter field (if present).
   Valid values: `fast` or `powerful`. If absent or any other value: default to `powerful`.
-- **Before building the subagent prompt**: Apply the Output Path Transformation (Step 1: run_id injection + Step 2: version folder) to all output paths referenced in the step file. Store the transformed path(s) in working memory — they will be used both in the prompt and in post-completion verification. Never pass raw paths from the step file to the subagent.
+- **Before building the subagent prompt**: Resolve all output paths referenced in the step file with the `saida` command (Output Path Transformation, once per group). Store the transformed path(s) in working memory — they will be used both in the prompt and in post-completion verification. Never pass raw paths from the step file to the subagent.
 - Use the Task tool to dispatch the step as a subagent:
   - If `model_tier: fast`: use the fastest/lightest model available in your current IDE.
   - If `model_tier: powerful` or absent/invalid: use the default model (no model override needed)
@@ -542,7 +534,7 @@ Apply this transformation consistently for every write in this step.
   - The veto conditions from the step file (agent should self-check before completing)
   - The company context
   - The crew memory
-  - The **transformed** path to save output (e.g., `crews/{name}/output/2026-03-20-140736/slides/v1/draft.md`)
+  - The **transformed** path to save output (the one `saida` returned, e.g. `crews/{name}/output/2026-03-20-140736/slides/v2/draft.md`)
 - Wait for the subagent to complete
 - Inform user: `✓ {Agent Name} completed`
 - Proceed to Post-Step Output Validation (below) before advancing.
@@ -552,13 +544,13 @@ Apply this transformation consistently for every write in this step.
 - Announce: `{icon} {Agent Name} is working...`
 - Follow the step instructions
 - Present output directly in the conversation
-- Save output to the specified output file — apply the Output Path Transformation (Steps 1 and 2) to the path before writing. Do not write to the raw path from the step file.
+- Save output to the specified output file — resolve the path with the `saida` command (Output Path Transformation) before writing. Do not write to the raw path from the step file.
 - Proceed to Post-Step Output Validation (below) before advancing.
 
 #### If `type: checkpoint`
 - Present the checkpoint message to the user
 - If the checkpoint requires a choice (numbered list), present options as a numbered list
-- **Always include the file path** of any generated content the user needs to review. Example: "Review the content at `crews/{name}/output/{run_id}/v1/content.md` and let me know if it looks good."
+- **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
 - **Correction → memory, right away**: if the answer corrects something (tone, audience, a term,
@@ -571,7 +563,7 @@ Apply this transformation consistently for every write in this step.
   (e.g. the organization's name, the main audience), ask: "Isso vale para todas as crews?
   Atualizo o perfil da empresa?" — change `company.md` only after a yes.
 - **If the step frontmatter contains `outputFile`**: after collecting the user's full response,
-  apply the Output Path Transformation **Step 1 only** (run_id injection — skip Step 2, version folder) to the `outputFile` path, then write the response to the transformed path using the Write tool before moving to the next step. Checkpoint files are user input captures, not versioned output — Step 2 does not apply here, regardless of the general "every write" rule in the Output Path Transformation section above.
+  insert only the run_id in the `outputFile` path (item 1 of the rule in Output Path Transformation — no version folder, no `saida` command), then write the response to that path using the Write tool (it creates the folder) before moving to the next step. Checkpoint files are user input captures, not versioned output: they live in the group itself, where `entrada` finds them.
   Use this format:
   ```
   # Research Focus
@@ -584,28 +576,22 @@ Apply this transformation consistently for every write in this step.
 
 ### Post-Step Output Validation
 
-After a step produces output (subagent or inline) and BEFORE Veto Condition Enforcement, the runner MUST validate that the declared output files exist and are non-empty. This is a binary, non-negotiable gate — the runner does NOT proceed on memory or assumption, only on bash output.
+After a step produces output (subagent or inline) and BEFORE Veto Condition Enforcement, the runner MUST validate that the declared output files exist and are non-empty. This is a binary, non-negotiable gate — the runner does NOT proceed on memory or assumption, only on the script's `CAMINHO:` line.
 
-**If the step declares an `outputFile`** (single or multiple), run via Bash tool for EACH output file:
+**If the step declares an `outputFile`** (single or multiple), run the `conferir` command (Output Path Transformation) for EACH output file, with the **stored transformed path** (the one `saida` returned), not the raw path from the step file. A step with an `output_contract:` adds its options to this same call (see Output Contract Validation): one command per file.
 
-```bash
-test -s "{transformed outputFile path}" && echo "VALIDATION:PASS" || echo "VALIDATION:FAIL"
-```
-
-Use the **stored transformed path** (after Output Path Transformation Steps 1 and 2), not the raw path from the step file.
-
-**Rules:**
-- If ALL output files return `VALIDATION:PASS` → proceed to Veto Condition Enforcement.
+**Rules** (`FAIL` below = the last line is `CAMINHO:REPROVADO arquivo ausente ou vazio`):
+- If ALL output files return `CAMINHO:OK` → proceed to Veto Condition Enforcement.
 - **Irreversible step** (`side_effects: irreversible` — publish, post, send) with ANY
-  `VALIDATION:FAIL` → NEVER re-execute it. Tell the user: "⚠️ {Agent Name} did not save its
+  `FAIL` → NEVER re-execute it. Tell the user: "⚠️ {Agent Name} did not save its
   output, but the action may already have happened (post published / email sent). Check
   before retrying." Then offer: 1. Retry step (only after the user checked) · 2. Mark as done
   and continue · 3. Abort pipeline.
-- If ANY output file returns `VALIDATION:FAIL` (any other step):
+- If ANY output file returns `FAIL` (any other step):
   1. **Retry once**: re-execute the entire step with the same input and context.
   2. After re-execution, run the validation again for all output files.
-  3. If second attempt returns `VALIDATION:PASS` for all files → proceed normally.
-  4. If second attempt still has ANY `VALIDATION:FAIL` → present to user:
+  3. If second attempt returns `CAMINHO:OK` for all files → proceed normally.
+  4. If second attempt still has ANY `FAIL` → present to user:
      ```
      ⚠️ {Agent Name}'s output was not generated: {path}
 
@@ -617,26 +603,23 @@ Use the **stored transformed path** (after Output Path Transformation Steps 1 an
 - If the step does not declare an `outputFile` (e.g., steps that only produce inline console output) → skip output validation.
 - Checkpoint steps (`type: checkpoint`) are exempt — their output is the user's response, not a file.
 
-**IMPORTANT**: Do NOT rely on reading the file with the Read tool to "verify" output. The Read tool returns content that can be misinterpreted. Use ONLY the bash `test -s` command — its output is binary and cannot be hallucinated.
+**IMPORTANT**: Do NOT rely on reading the file with the Read tool to "verify" output. The Read tool returns content that can be misinterpreted. Use ONLY the `conferir` command — its last line is binary and cannot be hallucinated.
 
 ### Output Contract Validation
 
 If the step's frontmatter declares an `output_contract:` field, apply structured validation
-AFTER the basic file existence check passes:
+in the same call as the basic file existence check (Post-Step Output Validation):
 
-1. **Required sections check**: If `output_contract.required_sections` is defined,
-   verify each required section exists in the output file:
-   ```bash
-   grep -c "^## " "{transformed outputFile path}" | xargs -I {} test {} -ge {min_sections} && echo "SECTIONS:PASS" || echo "SECTIONS:FAIL"
-   ```
+1. **Required sections check**: If `output_contract.required_sections` is defined, add
+   `--secoes {min_sections}` to the same `conferir` command: the file needs at least that many
+   lines starting with `## `.
 
-2. **TL;DR check**: If the output contract requires a TL;DR section:
-   ```bash
-   grep -q "^## TL;DR" "{transformed outputFile path}" && echo "TLDR:PASS" || echo "TLDR:FAIL"
-   ```
+2. **TL;DR check**: If the output contract requires a TL;DR section, add `--tldr` to the same
+   `conferir` command.
 
-3. **If any check fails**:
-   - Present to user: "⚠️ Output from {Agent Name} is incomplete: {which checks failed}"
+3. **If a check fails** (the last line is `CAMINHO:REPROVADO {motivo}`, with a motivo other than
+   `arquivo ausente ou vazio`; the script reports the first one):
+   - Present to user: "⚠️ Output from {Agent Name} is incomplete: {motivo}"
    - Options as numbered list:
      1. Accept anyway and continue
      2. Retry step (re-execute the agent)
@@ -720,7 +703,8 @@ When a step has `on_reject: {step-id}` (a review step):
    lines under each file, not the "não é texto" line of **Notas**), one per line as
    `{arquivo} — {motivo}`, then the lines under `**Notas:**` in that report, as they are written,
    and repeat every "não rodou" warning of this run (checker and source check) and the line of
-   every file left unchecked by the safe-name rule. If the approved
+   every file left unchecked by the safe-name rule. List the same way every file the path script
+   did not check (see Output Path Transformation). If the approved
    text still contains `[PREENCHER: …]`, ask the user for each missing piece of real information
    and write it into the text before approving.
 
@@ -731,14 +715,14 @@ For reference, the complete execution order for each pipeline step is:
 ```
 0. Agent deselection check (skip step if its agent was deselected)
 0b. Escritório command (passo or checkpoint) — only if it is on
-1. Pre-Step Input Validation (bash gate)
+1. Pre-Step Input Validation (script gate: `entrada`)
 2. Read step file
 3. Check execution mode and execute (subagent / inline / checkpoint)
-4. Post-Step Output Validation (bash gate)
+4. Post-Step Output Validation (script gate: `conferir`)
 5. Veto Condition Enforcement
 ```
 
-Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT advance — the user is consulted.
+Steps 1 and 4 are binary script gates. If either fails, the pipeline does NOT advance — the user is consulted.
 
 ### After Pipeline Completion
 

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

@@ -0,0 +1,49 @@
+// Linha de comando do `caminho.mjs`: a crew, a ação, as opções e a linha de uso.
+// Spec: fase-r3-runner-em-uso-real.md, §3 e §6 (repositório do OpenCrew).
+import { MSG } from '../comum.mjs';
+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 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
+ * 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`.
+ */
+export function lerArgs(argv) {
+  const soltos = [];
+  const opcoes = {};
+  for (let i = 0; i < argv.length; i++) {
+    const [, nome, colado] = argv[i].match(OPCAO) ?? [];
+    if (!nome) soltos.push(argv[i]);
+    else if (nome === 'tldr') opcoes.tldr = true;
+    else if (colado !== undefined) opcoes[nome] = colado;
+    else opcoes[nome] = i + 1 < argv.length && !OPCAO.test(argv[i + 1]) ? argv[++i] : '';
+  }
+  const [crew, acao] = soltos.filter((s) => !s.startsWith('--'));
+  return { crew, acao, tldr: false, ...opcoes };
+}
+
+/**
+ * O que falta ou está errado na linha de comando, antes de olhar o disco. `conferir` recebe um
+ * 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 }) {
+  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}.`;
+  if (acao !== 'conferir' && !run) return MSG.faltaOpcao('--run');
+  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.';
+  return null;
+}

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

@@ -0,0 +1,36 @@
+// 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.
+// Spec: fase-r3-runner-em-uso-real.md, regra 6 (repositório do OpenCrew).
+import { mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
+
+/** Os nomes das pastas que ficam direto em `pasta`; pasta que não existe não tem nenhuma. */
+export function pastasDe(pasta) {
+  try {
+    return readdirSync(pasta, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+export function ehPasta(caminho) {
+  try {
+    return statSync(caminho).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** É um arquivo, existe e não está vazio? */
+export function temConteudo(arquivo) {
+  try {
+    const info = statSync(arquivo);
+    return info.isFile() && info.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+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 }); };

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

@@ -0,0 +1,61 @@
+// Núcleo do `caminho.mjs`: as regras de caminho de uma execução, em funções puras. Não toca em
+// disco nem em processo (quem lê pastas e arquivos é `disco.mjs`).
+// Spec: fase-r3-runner-em-uso-real.md, regras 2 a 5 (repositório do OpenCrew).
+
+export const ACOES = ['pasta', 'saida', 'entrada', 'conferir'];
+
+/** Os motivos de `CAMINHO:REPROVADO`, na ordem em que são conferidos (§6 da spec). */
+export const MOTIVO = {
+  ausente: 'arquivo ausente ou vazio',
+  secoes: (achadas, minimo) => `${achadas} seções, mínimo ${minimo}`,
+  tldr: 'falta a seção TL;DR',
+};
+
+/** Caminho como o script o compara e devolve: com `/`, sem `./` na frente e sem barra dobrada. */
+export const normalizar = (caminho) => String(caminho).replace(/\\/g, '/').replace(/^(?:\.\/+)+/, '').replace(/\/{2,}/g, '/');
+
+/**
+ * Regra 2 — o caminho da execução. Caminho declarado que começa por `crews/<crew>/output/` ganha
+ * `<run>/` logo depois de `output/`.
+ * @returns {{ grupo: string, nome: string } | null} o grupo (a pasta do arquivo, já com o run) e
+ *   o nome do arquivo; `null` quando o caminho não é de `output/` (volta como veio)
+ */
+export function naExecucao(declarado, crew, run) {
+  const saida = `crews/${crew}/output/`;
+  const caminho = normalizar(declarado);
+  if (!caminho.startsWith(saida)) return null;
+  const partes = caminho.slice(saida.length).split('/');
+  const nome = partes.pop();
+  return { grupo: [`${saida}${run}`, ...partes].join('/'), nome };
+}
+
+/** O número de uma pasta de versão (`v` + número), ou `null` para qualquer outro nome. */
+function numero(nome) {
+  const [, digitos] = /^v(\d{1,9})$/.exec(nome) ?? [];
+  return digitos === undefined ? null : Number(digitos);
+}
+
+/** As pastas de versão, da mais nova para a mais antiga, em ordem numérica (`v10` antes de `v9`). */
+export function daMaisNova(nomes) {
+  return nomes.filter((nome) => numero(nome) !== null).sort((a, b) => numero(b) - numero(a));
+}
+
+/** Regra 3 — a versão em que o passo grava: a maior `vN` do grupo mais 1; sem nenhuma, `v1`. */
+export function proximaVersao(nomes) {
+  const [maior] = daMaisNova(nomes);
+  return `v${maior ? numero(maior) + 1 : 1}`;
+}
+
+/**
+ * Regra 5 — o que falta no texto de um arquivo gravado, pelo primeiro motivo da §6.
+ * @param {string} texto o conteúdo do arquivo (que já existe e não está vazio)
+ * @param {{ secoes?: number|null, tldr?: boolean }} pedido
+ * @returns {string|null} o motivo, ou `null` quando o arquivo passa
+ */
+export function motivoDeReprovacao(texto, { secoes = null, tldr = false } = {}) {
+  const linhas = (texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto).split(/\r?\n/);
+  const achadas = linhas.filter((linha) => linha.startsWith('## ')).length;
+  if (secoes !== null && achadas < secoes) return MOTIVO.secoes(achadas, secoes);
+  if (tldr && !linhas.some((linha) => linha.startsWith('## TL;DR'))) return MOTIVO.tldr;
+  return null;
+}

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

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Caminho da execução de uma crew: diz onde cada passo grava, de onde lê e se o arquivo gravado
+// está lá. Quem calcula é este script, igual em qualquer sistema — a IA não monta o caminho.
+// Uso (na pasta do projeto): node _opencrew/core/scripts/caminho.mjs <crew> <ação> --run <id> [opções]
+//   pasta    --run <id>                       cria crews/<crew>/output/<id>/
+//   saida    --run <id> --arquivo <declarado> onde o passo grava (abre a pasta de versão seguinte)
+//   entrada  --run <id> --arquivo <declarado> a saída mais nova desse arquivo
+//   conferir --arquivo <caminho já resolvido> [--secoes N] [--tldr]
+// <crew> é o nome da pasta em `crews/`. <declarado> é o `inputFile` ou `outputFile` do passo.
+// Só cria pastas, e só dentro de crews/<crew>/output/<id>/; nunca cria, altera nem apaga arquivo.
+// Última linha da saída (o runner lê esta linha): CAMINHO:OK <caminho>, CAMINHO:FALTA <caminho>
+// ou CAMINHO:REPROVADO <motivo>; o caminho sai relativo à pasta do projeto, com `/`.
+// Código de saída: 0 sempre que a linha CAMINHO: sai · 1 = erro de uso (ação ou opção faltando,
+// pasta sem `_opencrew/`, crew inexistente ou fora do projeto); com código 1 não há linha
+// CAMINHO: e nada é criado.
+// Spec: fase-r3-runner-em-uso-real.md (repositório do OpenCrew).
+import path from 'node:path';
+import { MSG, dentroDoProjeto, ehPrincipal, realDentroDe } from './comum.mjs';
+import { USO, erroDeArgumentos, lerArgs, limpar } from './caminho/argumentos.mjs';
+import { MOTIVO, daMaisNova, motivoDeReprovacao, naExecucao, normalizar, proximaVersao } from './caminho/nucleo.mjs';
+import { criarPasta, ehPasta, lerTexto, pastasDe, temConteudo } from './caminho/disco.mjs';
+
+const ok = (caminho) => `CAMINHO:OK ${caminho}`;
+const falta = (caminho) => `CAMINHO:FALTA ${caminho}`;
+const reprovado = (motivo) => `CAMINHO:REPROVADO ${motivo}`;
+
+/**
+ * O arquivo declarado cabe na execução? Dentro de `output/`, depois de ganhar o run, ele tem de
+ * continuar dentro da pasta da execução — pelo texto e pelo lugar real.
+ * @returns {string|null} o erro de uso, ou `null`
+ */
+function erroDoArquivo(raiz, crew, { acao, run, arquivo }) {
+  if (!dentroDoProjeto(raiz, arquivo)) return MSG.foraDoProjeto(limpar(arquivo));
+  const local = acao === 'conferir' ? null : naExecucao(arquivo, crew, run);
+  if (!local) return null;
+  if (!local.nome) return `Falta o nome do arquivo em --arquivo: ${limpar(arquivo)}`;
+  const execucao = path.resolve(raiz, 'crews', crew, 'output', run);
+  const partes = normalizar(arquivo).split('/');
+  const sai = partes.includes('..') || partes.includes('.') || !realDentroDe(execucao, path.resolve(raiz, local.grupo));
+  return sai ? `Caminho fora da pasta da execução: ${limpar(arquivo)}` : null;
+}
+
+/**
+ * Onde fica a crew, ou o erro de uso. A crew é uma pasta direta de `crews/` (`crews/<nome>`
+ * também vale).
+ * @returns {{ erro: string } | { crew: string }}
+ */
+function localizar(raiz, args) {
+  const erro = erroDeArgumentos(args);
+  if (erro) return { erro };
+  if (!ehPasta(path.join(raiz, '_opencrew'))) return { erro: MSG.semRaiz };
+  const base = path.resolve(raiz, 'crews');
+  const nome = args.crew.replace(/^crews[\\/]+/, '');
+  if (!dentroDoProjeto(base, nome)) return { erro: MSG.foraDoProjeto(limpar(args.crew)) };
+  const pasta = path.resolve(base, nome);
+  if (path.dirname(pasta) !== base || !ehPasta(pasta)) return { erro: MSG.crewNaoEncontrada(limpar(args.crew)) };
+  const crew = path.basename(pasta);
+  const doArquivo = args.arquivo ? erroDoArquivo(raiz, crew, args) : null;
+  return doArquivo ? { erro: doArquivo } : { crew };
+}
+
+/** Regras 2 e 3: o caminho em que o passo grava; a pasta dele é criada. */
+function saida(raiz, crew, { run, arquivo }) {
+  const local = naExecucao(arquivo, crew, run);
+  if (!local) return ok(normalizar(arquivo));
+  const pasta = `${local.grupo}/${proximaVersao(pastasDe(path.resolve(raiz, local.grupo)))}`;
+  criarPasta(path.resolve(raiz, pasta));
+  return ok(`${pasta}/${local.nome}`);
+}
+
+/** Regra 4: a versão mais nova que tem o arquivo; depois, o próprio grupo, sem pasta de versão. */
+function entrada(raiz, crew, { run, arquivo }) {
+  const local = naExecucao(arquivo, crew, run);
+  const { grupo, nome } = local ?? { grupo: path.posix.dirname(normalizar(arquivo)), nome: path.posix.basename(normalizar(arquivo)) };
+  const versoes = local ? daMaisNova(pastasDe(path.resolve(raiz, grupo))) : [];
+  const candidatos = [...versoes.map((versao) => `${grupo}/${versao}/${nome}`), local ? `${grupo}/${nome}` : normalizar(arquivo)];
+  const achado = candidatos.find((caminho) => temConteudo(path.resolve(raiz, caminho)));
+  return achado ? ok(achado) : falta(candidatos.at(-1));
+}
+
+/** Regra 5: o arquivo gravado existe, não está vazio e tem o que o contrato do passo pede. */
+function conferir(raiz, { arquivo, secoes, tldr }) {
+  const caminho = normalizar(arquivo);
+  const alvo = path.resolve(raiz, caminho);
+  if (!temConteudo(alvo)) return reprovado(MOTIVO.ausente);
+  const pedido = { secoes: secoes === undefined ? null : Number(secoes), tldr };
+  const motivo = pedido.secoes !== null || tldr ? motivoDeReprovacao(lerTexto(alvo), pedido) : null;
+  return motivo ? reprovado(motivo) : ok(caminho);
+}
+
+function responder(raiz, crew, args) {
+  if (args.acao === 'saida') return saida(raiz, crew, args);
+  if (args.acao === 'entrada') return entrada(raiz, crew, args);
+  if (args.acao === 'conferir') return conferir(raiz, args);
+  const pasta = `crews/${crew}/output/${args.run}`;
+  criarPasta(path.resolve(raiz, pasta));
+  return ok(pasta);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps] `cwd` (a pasta do projeto) e `escrever`
+ * @returns {number} 0 = a linha `CAMINHO:` saiu · 1 = erro de uso, ou falha ao ler ou criar pasta
+ *   (a linha de uso e o motivo, ou só o erro; sem linha `CAMINHO:`)
+ */
+export function main(argv, deps = {}) {
+  const { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = deps;
+  const args = lerArgs(argv);
+  const local = localizar(cwd, args);
+  if (local.erro) {
+    escrever(USO);
+    escrever(local.erro);
+    return 1;
+  }
+  try {
+    escrever(responder(cwd, local.crew, args));
+    return 0;
+  } catch (erro) {
+    escrever(`Não consegui resolver o caminho: ${limpar(erro?.message ?? erro)}`);
+    return 1;
+  }
+}
+
+if (ehPrincipal(import.meta.url)) process.exitCode = main(process.argv.slice(2));