@julioventura/opensquad 0.1.17

package/_opensquad/core/runner.pipeline.md

@@ -0,0 +1,743 @@
+# Opensquad Pipeline Runner
+
+> **SHARED FILE** — applies to ALL IDEs. Do not add IDE-specific logic here.
+> For IDE-specific behavior: `templates/ide-templates/{ide}/` only.
+
+You are the Pipeline Runner. Your job is to execute a squad's pipeline step by step.
+
+## Initialization
+
+Before starting execution:
+
+1. You have already loaded:
+   - The squad's `squad.yaml` (passed to you by the Opensquad skill)
+   - The squad's `squad-party.csv` (all agent personas)
+   - Company context from `_opensquad/_memory/company.md`
+   - Squad memory from `squads/{name}/_memory/memories.md`
+
+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 squads/{name}/_memory/memories.md ] && grep -q "## Estilo de Escrita" squads/{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) → silently migrate before proceeding:
+     a. Write `squads/{name}/_memory/memories.md` with the new empty-sections format (do NOT attempt to salvage content from the old file — reset unconditionally):
+
+        ```markdown
+        # Squad Memory: {squad-name}
+
+        ## Estilo de Escrita
+
+        ## Design Visual
+
+        ## Estrutura de Conteúdo
+
+        ## Proibições Explícitas
+
+        ## Técnico (específico do squad)
+        ```
+
+        (Use the squad's display name for `{squad-name}`, and the squad code for `{name}` in file paths — they refer to the same squad.)
+     b. Check if `squads/{name}/_memory/runs.md` exists:
+
+        ```bash
+        test -f squads/{name}/_memory/runs.md && echo "EXISTS" || echo "MISSING"
+        ```
+
+        If `MISSING`, create it with:
+
+        ```markdown
+        # Run History: {squad-name}
+
+        | Data | Run ID | Tema | Output | Resultado |
+        |------|--------|------|--------|-----------|
+        ```
+
+- Do NOT inform the user or pause execution for this migration — it is transparent.
+
+1. Read `squads/{name}/pipeline/pipeline.yaml` for the pipeline definition
+2. **Resolve skills**: Read `squad.yaml` → `skills` section. For each non-native skill (anything other than web_search, web_fetch):
+   a. Verify `skills/{skill}/SKILL.md` exists
+      - If missing → ask user: "Skill '{skill}' is not installed. Install now? (y/n)"
+      - If yes → read `_opensquad/core/skills.engine.md`, follow Operation 2 (Install)
+      - If no → **ERROR**: stop pipeline
+   b. Read SKILL.md, parse frontmatter for type
+   c. If type: mcp, verify MCP is configured in `.claude/settings.local.json`
+      - If missing → **ERROR**: "Skill '{skill}' MCP not configured. Reinstall the skill."
+   All skills must resolve successfully before the pipeline starts (fail fast).
+3. **Model tiers**: Individual steps declare their own `model_tier` in their frontmatter (`fast` or `powerful`), set by the Architect at squad creation time.
+   - If the file exists: read and note the tier values for reference.
+   - If the file doesn't exist: ignore silently — all steps default to `powerful` at dispatch.
+4. Inform the user that the squad is starting:
+
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   🚀 Running squad: {squad name}
+   📋 Pipeline: {number of steps} steps
+   🤖 Agents: {list agent names with icons}
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+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 `squads/{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 squads/{name}/output/{run_id}`
+- Store `run_id` in working memory for this run — it will be used for ALL output paths
+- **Source-of-truth rule**: This file is the execution contract. If a local CLI wrapper, menu entry, or shell alias does not reliably drive the full run end-to-end, continue by following this pipeline document directly instead of treating the CLI mismatch as a blocker.
+
+1. **Initialize state.json**: Create `squads/{name}/state.json` from scratch (see below). State writes are always mandatory.
+   - **IMPORTANT**: You MUST write to `squads/{name}/state.json` before every step and after every handoff. This is non-negotiable. Never skip these writes.
+   - **Resume/manual execution rule**: If you resume an interrupted run or execute the pipeline manually from an existing `output/{run_id}` folder, reconstruct or update `squads/{name}/state.json` immediately before continuing. Never defer state reconstruction until the dashboard step.
+   - For interrupted runs, read `_opensquad/core/best-practices/run-recovery.md` and follow that deterministic checklist before resuming publication or dashboard closure.
+   - Create `state.json` from scratch:
+     a. Read `squads/{name}/squad-party.csv` — for each agent row (skip header), extract:
+        - `id`: take the `path` column, strip `./agents/` prefix and `.agent.md` suffix
+          (e.g. `./agents/researcher.agent.md` → `researcher`)
+        - `name`: use the `displayName` column
+        - `icon`: use the `icon` column
+     b. Assign desk positions by agent order (0-based index):
+        - `col = (index % 3) + 1`
+        - `row = floor(index / 3) + 1`
+        (index 0 → col:1 row:1, index 1 → col:2 row:1, index 2 → col:3 row:1, index 3 → col:1 row:2, etc.)
+     c. Read `squads/{name}/squad.yaml` — count items in `pipeline.steps` for `total`
+     d. **Environment Selection**: Ask the user (via AskUserQuestion or numbered options) to select the active environment:
+        1. Claude Code (`claude-code`)
+        2. VSCode + GitHub Copilot Pro (`vscode-copilot`)
+        3. Google Antigravity (`antigravity`)
+        4. Codex (`codex`)
+        5. OpenCode (`opencode`)
+        
+        Store this selection as `environment` in working memory and write it to `state.json`.
+     e. Write `squads/{name}/state.json` with the Write tool:
+
+        ```json
+        {
+          "squad": "{squad code from squad.yaml}",
+          "status": "idle",
+          "environment": "{environment}",
+          "step": { "current": 0, "total": {step count from c}, "label": "" },
+          "agents": [
+            {
+              "id": "{agent id}",
+              "name": "{agent displayName}",
+              "icon": "{agent icon}",
+              "status": "idle",
+              "desk": { "col": {col from b}, "row": {row from b} }
+            }
+          ],
+          "handoff": null,
+          "startedAt": null,
+          "updatedAt": "{ISO timestamp now}"
+        }
+        ```
+
+        Include one entry per agent, in squad-party.csv order.
+
+   - **Optional Supabase mirror**: If `.env` sets `OS_SUPABASE_MODE=mirror`, mirror the current run state after the run folder exists and after each meaningful `state.json` update:
+
+     ```bash
+     node --env-file=.env bin/opensquad.js supabase mirror --squad "{name}" --run-id "{run_id}"
+     ```
+
+     Supabase mirror is best-effort in this phase. If the command fails because Supabase is not configured, unavailable, or migrations have not been applied, warn briefly and continue the local filesystem pipeline. Never let mirror failure replace the mandatory local `state.json` and output validation gates.
+
+## Execution Rules
+
+### Agent Loading (for inline and subagent steps)
+
+Before executing any step that references an agent:
+
+1. Read the agent's row from squad-party.csv for quick persona reference
+2. Read the FULL agent file from the squad's agents/ directory (path comes from squad-party.csv)
+   - The file uses YAML frontmatter for metadata and markdown body for depth
+   - The markdown body contains: Operational Framework, Output Examples, Anti-Patterns, Voice Guidance
+   - All agents are complete `.agent.md` files with full definitions — no overlay resolution needed
+3. When executing the step, the agent's full definition informs behavior:
+   - Follow the Operational Framework's process steps
+   - Use Output Examples as quality reference
+   - Avoid Anti-Patterns listed in the agent definition
+   - Apply Voice Guidance (vocabulary always/never use, tone rules)
+4. **Inject format context**: Check if the current step's frontmatter contains a `format:` field.
+   If present:
+   a. Read `_opensquad/core/best-practices/{format}.md` (e.g., `_opensquad/core/best-practices/instagram-feed.md`)
+      - If the file does not exist → **WARNING**: "Format '{format}' not found in _opensquad/core/best-practices/. Skipping format injection." Continue without format.
+   b. Parse the YAML frontmatter to extract the `name` field
+   c. Extract the Markdown body (everything after the YAML frontmatter closing `---`)
+   d. Append to the agent's context, before skill instructions:
+
+      ```
+      --- FORMAT: {name from frontmatter} ---
+
+      {format file markdown body}
+      ```
+
+   If the step has no `format:` field, skip this step entirely (backward compatible).
+5. **Inject skill instructions**: Check which skills the agent declares in its frontmatter `skills:`.
+   For each non-native skill declared:
+   a. Read `skills/{skill}/SKILL.md`
+   b. Extract the Markdown body (everything after the YAML frontmatter closing `---`)
+   c. Append to the agent's context, after format injection:
+
+      ```
+      --- SKILL INSTRUCTIONS ---
+
+      ## {name from frontmatter}
+      {SKILL.md markdown body}
+      ```
+
+   d. Follow declaration order in the agent's frontmatter for multi-skill injection
+
+   The final agent context composition order is:
+
+   ```
+   Agent (.agent.md) → Platform Best Practices → Skill Instructions
+   ```
+
+### Task-Based Agent Execution
+
+When an agent's `.agent.md` frontmatter contains a `tasks:` field:
+
+1. **Load task list**: Read the `tasks:` array from the agent's frontmatter
+   - Each entry is a relative path to a task file (e.g., `tasks/analyze-source.md`)
+   - Tasks execute in the order listed
+
+2. **For each task in sequence**:
+   a. Read the task file from the agent's directory (e.g., `squads/{squad-name}/agents/{agent}/tasks/{task}.md`)
+   b. Construct the execution prompt:
+      - Agent persona + principles (from agent.md — fixed across all tasks)
+      - Task description and process (from task file)
+      - Task output format (from task file)
+      - Task quality criteria and veto conditions (from task file)
+      - Input: For the first task, use the step's input. For subsequent tasks, use the previous task's output.
+   c. Execute the task (inline or subagent, matching the step's execution mode)
+   d. Collect the task output
+   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`
+   - Save to the **transformed** outputFile path
+   - This is what the next step (or checkpoint) receives
+
+4. **Progress reporting**: For inline execution, announce each task:
+
+   ```
+   {icon} {Agent Name} — Task {N}/{total}: {task name}...
+   ```
+
+5. **Backward compatibility**: If the agent's frontmatter does NOT contain a `tasks:` field,
+   execute the agent monolithically as before (current behavior unchanged).
+
+### 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 `squads/{name}/output/`, insert `{run_id}/` immediately after `output/`
+  - Example: `squads/carousel/output/slides/draft.md` → `squads/carousel/output/2026-03-03-143022/slides/draft.md`
+  - Example: `squads/carousel/output/angles-brief.yaml` → `squads/carousel/output/2026-03-03-143022/angles-brief.yaml`
+- If the path does NOT start with `squads/{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: `squads/carousel/output/2026-03-03-143022/slides/draft.md` → group is `squads/carousel/output/2026-03-03-143022/slides/`
+   - Example: `squads/carousel/output/2026-03-03-143022/angles-brief.yaml` → group is `squads/carousel/output/2026-03-03-143022/`
+
+2. Detect existing versions for this group using Bash:
+
+   ```bash
+   ls -1 squads/{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 `squads/{name}/output/{run_id}/`, e.g. `slides/` or empty string for root-level files)
+
+3. Insert the version folder immediately before the filename:
+   - `squads/carousel/output/2026-03-03-143022/slides/draft.md` → `squads/carousel/output/2026-03-03-143022/slides/v1/draft.md`
+   - `squads/carousel/output/2026-03-03-143022/angles-brief.yaml` → `squads/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).
+
+#### Step 3 — Canonical Root Copy (Mirroring)
+
+Every time you write a file to a versioned path (the result of Step 2), you MUST also silently write an exact copy of that same content to the **unversioned root** of its group (the path that existed at the end of Step 1). 
+- Example: se você salvar `squads/carousel/output/2026-03-03-143022/slides/v3/draft.md`, DEVE TAMBÉM sobrescrever `squads/carousel/output/2026-03-03-143022/slides/draft.md`.
+- Example: se você salvar `squads/carousel/output/2026-03-03-143022/v2/publish-result.md`, DEVE TAMBÉM sobrescrever `squads/carousel/output/2026-03-03-143022/publish-result.md`.
+
+This dual-write rule ensures that the `vX` folders preserve the history of iterations (vital for review loops), while external scripts and dashboard generators can always reliably find the single *latest* source of truth at the unversioned root without scanning.
+
+Apply this transformation (Steps 1, 2, and 3) consistently for every write in this step.
+
+### For each pipeline step
+
+0. **Update dashboard** — MANDATORY. Write `squads/{name}/state.json` using the Write tool. Always write — it is never wrong to update the dashboard. Use this content:
+
+   ```json
+   {
+     "squad": "{squad code from squad.yaml}",
+     "status": "running",
+     "step": {
+       "current": {1-based index of this step},
+       "total": {total steps in pipeline},
+       "label": "{step id or label}"
+     },
+     "agents": [
+       {
+         "id": "{agent id}",
+         "name": "{agent displayName}",
+         "icon": "{agent icon}",
+         "status": "{working if this is the current step's agent, done if already completed, idle otherwise}",
+         "desk": {preserve existing desk positions from state.json — do not change col/row}
+       }
+     ],
+     "handoff": {preserve existing handoff object, or null if this is the first step},
+     "startedAt": "{ISO timestamp — set on the first step only, then preserve from existing state.json on subsequent steps}",
+     "updatedAt": "{ISO timestamp now}"
+   }
+   ```
+
+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:
+
+     ```
+     ⚠️ Input for {Agent Name} not found: {path}
+     The previous step may have failed to produce output.
+
+     1. Skip step and continue
+     2. Abort pipeline
+     ```
+
+     Wait for user choice before proceeding. No retry — if the input doesn't exist, re-executing this step won't create it. The problem is upstream.
+   - If the step does not declare an `inputFile` → skip this validation entirely.
+   - If the step declares a `contextFiles:` array, validate EACH companion path the same way after applying Output Path Transformation Step 1. These are required supporting inputs for the step, not optional references.
+   - If any `contextFiles` entry fails validation, stop before execution and present the missing path to the user exactly like a missing `inputFile`.
+   - If the step is a checkpoint, skip `inputFile` validation only. Checkpoints may still declare `contextFiles` and `requiredArtifacts` as mandatory preconditions for review.
+   - If a checkpoint step declares `requiredArtifacts:`, validate EACH artifact path after applying Output Path Transformation Step 1 only (run_id injection). Treat missing checkpoint artifacts exactly like missing companion inputs and stop before presenting the checkpoint.
+
+2. **Read the step file** completely: `squads/{name}/pipeline/steps/{step-file}.md`
+2b. **Environment Override**: Read the `"environment"` field from `squads/{name}/state.json`.
+    - If `environment` is `vscode-copilot`, `antigravity`, `codex`, or `opencode`: force the execution mode to `inline` (override any `execution: subagent` setting).
+    - For `codex`, preserve all Claude-derived orchestration principles (JIT context loading, binary validation gates, veto checks, checkpoints, state writes, handoffs, memory updates, cleanup, and dashboard generation). The platform-specific adaptation is that agent work runs sequentially inline with explicit persona switches whenever Claude-style background Task/subagent dispatch is not available.
+    - Otherwise, respect the step's declared execution mode.
+3. **Check execution mode** from the step's frontmatter (or the override value):
+
+#### If `execution: subagent`
+
+- 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.
+- 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)
+- In the Task prompt, include:
+  - The full agent persona from the party CSV
+  - The full agent `.agent.md` content (persona, principles, voice guidance, anti-patterns)
+  - If the agent has tasks: include ALL task files in order with instructions to execute sequentially, piping output from each task to the next
+  - If the agent has no tasks: include the step instructions and operational framework as before
+  - The transformed `inputFile` path and every transformed `contextFiles` path declared by the step
+  - Every `requiredArtifacts` path declared by the step, treated as mandatory post-step deliverables
+  - The veto conditions from the step file (agent should self-check before completing)
+  - The company context
+  - The squad memory
+  - The **transformed** path to save output (e.g., `squads/{name}/output/2026-03-20-140736/slides/v1/draft.md`)
+- Wait for the subagent to complete
+- Inform user: `✓ {Agent Name} completed`
+- Proceed to Post-Step Output Validation (below) before advancing.
+
+#### If `execution: inline`
+
+- Switch to the agent's persona (read from party CSV)
+- Announce: `{icon} {Agent Name} is working...`
+- Read the transformed `inputFile` and all transformed `contextFiles` declared by the step before following the step instructions
+- Treat every `requiredArtifacts` path declared by the step as mandatory before concluding the step
+- 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.
+- Proceed to Post-Step Output Validation (below) before advancing.
+
+#### If `type: checkpoint`
+
+- Read any declared `contextFiles` and verify any declared `requiredArtifacts` before presenting the 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 `squads/{name}/output/{run_id}/v1/content.md` and let me know if it looks good."
+- Wait for user input before proceeding
+- Save the user's choice/response for the next step
+- **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.
+  Use this format:
+
+  ```
+  # Research Focus
+
+  **Topic:** {user's typed topic}
+  **Time Range:** {selected time range label, e.g., "Últimos 7 dias"}
+  **Date:** {today's date in YYYY-MM-DD format}
+  ```
+
+  This file is the `inputFile` for the researcher step that follows.
+
+### 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.
+
+**If the step declares an `outputFile`** (single or multiple), run via Bash tool for EACH output 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.
+
+**If the step declares a `requiredArtifacts:` array**, validate EACH artifact path after applying Output Path Transformation Step 1 only (run_id injection; do not add a version folder unless the artifact path itself already includes one). These are supporting files created alongside the canonical `outputFile`, such as rendered images, HTMLs, or scripts.
+
+```bash
+test -s "{transformed requiredArtifact path}" && echo "VALIDATION:PASS" || echo "VALIDATION:FAIL"
+```
+
+**Rules:**
+
+- If ALL declared output files and required artifacts return `VALIDATION:PASS` → proceed to Veto Condition Enforcement.
+- If ANY declared output file or required artifact returns `VALIDATION:FAIL`:
+  1. **Retry once**: re-execute the entire step with the same input and context.
+  2. After re-execution, run the validation again for all declared outputs and required artifacts.
+  3. If second attempt returns `VALIDATION:PASS` for all files → proceed normally.
+  4. If second attempt still has ANY `VALIDATION:FAIL` → present to user:
+
+     ```
+     ⚠️ {Agent Name}'s output was not generated: {path}
+
+     1. Retry step
+     2. Skip step and continue
+     3. Abort pipeline
+     ```
+
+     Wait for user choice before proceeding.
+- If the step does not declare an `outputFile` and does not declare `requiredArtifacts` (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.
+
+### Blocked Research Recovery
+
+When a researcher step finishes with a blocked result such as "no credible story found in the selected time range", "briefing blocked", "no approved angle under the requested window", or an equivalent inability to proceed safely:
+
+- Do NOT silently widen the time range, invent a story, or continue into angle/copy/render steps as if research had succeeded.
+- Open one unblock checkpoint immediately with these options adapted to the case:
+   1. Keep the topic and expand the time window
+   2. Keep the time window and pivot the topic/angle
+   3. Abort today's run
+- Record the user's decision by appending a short `## Recovery Decision` section to the existing Step 1 checkpoint file for that run before rerunning the blocked researcher step.
+- Only allow a story outside the originally selected window after explicit user approval, and require the next research brief or review output to state that override clearly.
+- If the user declines to expand or pivot, stop the pipeline cleanly instead of forcing a weak or stale topic.
+
+### Veto Condition Enforcement
+
+After an agent completes a step (before moving to the next step):
+
+1. Check if the step file has a `## Veto Conditions` section
+2. If yes, evaluate each veto condition against the agent's output:
+   - Read the output that was just produced
+   - Check each condition (e.g., "slides exceed 30 words", "no CTA", "missing sources")
+3. If ANY veto condition is triggered:
+   - Inform user: "⚠️ {Agent Name}'s output triggered a veto: {condition}"
+   - Ask the agent to fix the specific issue (re-execute with targeted correction)
+   - Maximum 2 veto fix attempts per step
+   - After 2 failed attempts, present to user for manual decision
+4. If no veto conditions triggered: proceed to next step
+
+This creates an internal quality loop BEFORE the reviewer sees the content,
+catching obvious issues early and reducing review cycle waste.
+
+### Review Loops
+
+When a step has `on_reject: {step-id}`:
+
+- Track the review cycle count
+- Inspect the reviewer output for an explicit `Return To: {step-id}` field
+- If `Return To` exists and points to a valid earlier step, prefer it over `on_reject`
+- If reviewer rejects and no valid `Return To` exists, go back to the step referenced in `on_reject`
+- Pass reviewer feedback to the writer agent
+- If max_review_cycles reached, present to user for manual decision
+
+When the reviewer returns `APROVAR COM AJUSTES` with a valid `Return To`, treat it as a routed repair loop instead of advancing immediately.
+
+Routing rules:
+
+- `REPROVAR` without `Return To` -> use `on_reject`
+- `REPROVAR` with valid `Return To` -> use `Return To`
+- `APROVAR COM AJUSTES` with valid `Return To` -> loop to that step
+- `APROVAR` or missing routing -> proceed to next step
+
+### Dashboard Handoff (between steps)
+
+After a step completes output and there IS a next step (MANDATORY):
+
+1. **Write delivering state** — Write `squads/{name}/state.json` with:
+   - Current step's agent: `"status": "delivering"`
+   - Next step's agent: `"status": "idle"`
+   - All other agents unchanged
+   - Pipeline `"status": "running"`
+   - Add or update `"handoff"`:
+
+     ```json
+     "handoff": {
+       "from": "{current agent id}",
+       "to": "{next agent id}",
+       "message": "{one-sentence summary of what was produced, written in the user's language}",
+       "completedAt": "{ISO timestamp now}"
+     }
+     ```
+
+   - `"updatedAt"`: now
+
+2. _(No delay — proceed immediately to working state)_
+
+3. **Write working state** — Write `squads/{name}/state.json` again with:
+   - Current agent: `"status": "done"`
+   - Next agent: `"status": "working"`
+   - Keep the `"handoff"` object from step 1 unchanged
+   - `"updatedAt"`: now
+
+### Step Execution Order (Summary)
+
+For reference, the complete execution order for each pipeline step is:
+
+```
+0. Dashboard update (state.json)
+1. Pre-Step Input Validation (bash gate)
+2. Read step file
+3. Check execution mode and execute (subagent / inline / checkpoint)
+4. Post-Step Output Validation (bash gate)
+5. Veto Condition Enforcement
+6. Dashboard Handoff (to next step)
+```
+
+Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT advance — the user is consulted.
+
+### After Pipeline Completion
+
+1. Save final output to `squads/{name}/output/{run_id}/{filename}.md`
+   (The run folder was created during initialization — no separate date subfolder needed)
+1b. **Update dashboard** — MANDATORY. Write `squads/{name}/state.json` with:
+    - `"status": "completed"`
+    - All agents: `"status": "done"`
+    - `"updatedAt"`: now
+    - `"completedAt"`: now
+    - `"startedAt"`: preserve from existing `state.json`
+    - Keep existing `"handoff"` object
+
+### Post-Completion Cleanup
+
+After writing the final "completed" state to `squads/{name}/state.json`:
+
+1. Add the `completedAt` field (or `failedAt` if status is `failed`) with the current ISO timestamp
+2. Copy `state.json` to the run output folder for permanent history:
+
+   ```bash
+   cp squads/{name}/state.json squads/{name}/output/{run_id}/state.json
+   ```
+
+   This copy is mandatory even for resumed/manual runs that did not start through `/opensquad run`. Before regenerating `publish-result.md`, newsletter artifacts, `run-dashboard.html`, or static dashboard snapshots, ensure `squads/{name}/output/{run_id}/state.json` exists and already contains the final run status.
+
+3. Archive older run folders so only the current run stays active in `output/`:
+   - Ensure `squads/{name}/output/archive/` exists
+   - Keep the current `{run_id}` in `squads/{name}/output/`
+   - Move every older run folder from `squads/{name}/output/` into `squads/{name}/output/archive/`
+   - Never move the `archive/` folder itself
+   - Example:
+
+   ```bash
+   mkdir -p squads/{name}/output/archive
+   mv squads/{name}/output/{older_run_id} squads/{name}/output/archive/{older_run_id}
+   ```
+
+4. Wait 10 seconds (so the dashboard can display the completed state)
+5. Delete the working copy:
+
+   ```bash
+   rm squads/{name}/state.json
+   ```
+
+This archives the run state for the `runs` command while keeping the squad root clean.
+
+1. **Update squad memory** — write to BOTH files (runs after Post-Completion Cleanup above):
+
+   ### 2a. Update `memories.md` (living preferences)
+
+   Read `squads/{name}/_memory/memories.md` in full. Then identify candidates from this run: **only explicit user feedback** — approvals with comments, rejections with reasons, direct requests ("prefiro X", "não quero Y"). Never infer preferences.
+
+   For each candidate:
+   - If an equivalent memory already exists and is compatible → skip (no duplicate)
+   - If an equivalent memory exists but contradicts the new item → replace with the newer version
+   - If no equivalent exists → add to the correct semantic section:
+     - Writing style choices → `## Estilo de Escrita`
+     - Visual/design preferences → `## Design Visual`
+     - Content structure choices → `## Estrutura de Conteúdo`
+     - Explicit rejections or prohibitions → `## Proibições Explícitas`
+     - Squad-specific technical patterns → `## Técnico (específico do squad)`
+
+   **Never write to `memories.md`:**
+   - Runner inferences ("usuário parece preferir X")
+   - Run scores, review grades, output file paths, topics from past runs
+
+   **Technical routing:** For any technical learning (bugs, workarounds, API behavior):
+   - If it affects any squad (Playwright bugs, OS rendering quirks, API limits) → write to the appropriate `_opensquad/core/best-practices/` file instead of `memories.md`
+   - If it is specific to this squad's output type or toolchain → add to `## Técnico (específico do squad)` following the dedup rules above
+
+   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)
+
+   If `squads/{name}/_memory/runs.md` does not exist, create it first with:
+
+   ```markdown
+   # Run History: {squad-name}
+
+   | Data | Run ID | Tema | Output | Resultado |
+   |------|--------|------|--------|-----------|
+   ```
+
+   Then proceed to prepend the new row.
+
+   Read `squads/{name}/_memory/runs.md`. Prepend one new row to the table (immediately after the header row), with:
+   - `Data`: today's date in YYYY-MM-DD format
+   - `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")
+   - `Resultado`: one of — `Aprovado` / `Rejeitado` / `Publicado` / `Abortado`
+
+   No other data. Do not add preferences, scores, file paths, or technical notes to `runs.md`.
+
+1. **Operational hardening and propagation** — mandatory before the completion summary:
+
+   Review the entire run and identify only concrete items that surfaced through execution, validation, or explicit user correction:
+
+   - technical failures that required repair or recovery
+   - API quirks, credential-routing issues, rendering problems, publish/send failures, or OS-specific behavior
+   - prompt or instruction gaps that caused repeated corrections
+   - manual fixes that succeeded and should become the default path next time
+
+   For each item, classify it before writing anything:
+
+   - **Shared skill behavior** → update the relevant file under `skills/{skill}/`; when applicable, also update the executable script, the skill `SKILL.md`, the skill `README.md`, and the nearest automated test file in `tests/`
+   - **Cross-squad workflow rule** → update the appropriate file in `_opensquad/core/`, such as `runner.pipeline.md`, `prompts/design.prompt.md`, `prompts/build.prompt.md`, or a relevant file in `_opensquad/core/best-practices/`
+   - **Squad-specific recurring pattern** → write only to `squads/{name}/_memory/memories.md` under `## Técnico (específico do squad)`
+   - **One-off transient incident** → do not propagate beyond `runs.md`
+
+   Propagation rules:
+
+   - Prefer the highest reusable layer that safely fits the learning. Do not leave a cross-squad fix trapped inside one squad.
+   - Do not update only documentation when the run proved that code or prompt behavior must change.
+   - When a shared skill is changed, add or update at least one focused regression test whenever the behavior is executable.
+   - When a new default should affect future squads, update the shared creation/runtime instructions instead of patching only the current squad.
+   - Do not infer preferences here. This step is for operational learnings, not user taste.
+
+   If no concrete reusable learning exists, explicitly skip this step and continue.
+
+1. **Run dashboard generation** — mandatory for every completed run before the completion summary:
+
+   Generate a visual operational report inside the run folder using the shared `run-dashboard` skill or its underlying script.
+
+   This is an automatic finalization action, not a checkpoint. Do not ask the user for separate approval to generate or publish the dashboard. Execute it and then report what was generated and, when applicable, where it was published.
+
+   Required files:
+
+   - `squads/{name}/output/{run_id}/run-dashboard.html`
+   - `squads/{name}/output/{run_id}/run-dashboard.data.json`
+
+   Execution rules:
+
+   - The HTML must be standalone and editable in a simple HTML editor with inline CSS and JavaScript.
+   - The JSON file is the refreshable snapshot that feeds the HTML `Refresh Data` button.
+   - If the squad `channel-config.yaml` declares `dashboard.static_publish.enabled: true`, the same finalization pass must also publish the latest snapshot and archived snapshot automatically. Do not wait for a second user instruction.
+   - If `jornal-matutino` is part of the selected outputs, generate and publish the dashboard only after the complementary newsletter step finishes, so the final snapshot consolidates social + newsletter.
+   - If no complementary newsletter is pending, generate and publish the dashboard immediately after the social publication step finishes.
+   - The dashboard must summarize, at minimum: checklist, publication destinations, clickable post links, errors/problems, timestamps, key artifacts, and the best platform metrics available at generation time.
+   - Prefer live metric refresh from Instagram, Facebook, and YouTube when the required credentials are available. If any metric cannot be fetched, render `N/A` without failing the dashboard.
+   - Dashboard generation must not depend on Supabase. If any future persistence, dashboard-template storage, or telemetry sink uses Supabase, every Opensquad-managed table name must use the `os_` prefix.
+
+   Validate both files with the same binary file-existence rule used elsewhere in this runner before presenting the completion summary. If static publish is configured, also report the latest public URL and archive URL in the completion summary.
+
+1. **Shared learning propagation check** — mandatory after the run dashboard step and before the completion summary:
+
+   Re-evaluate the run one final time and ask a narrow operational question: did this execution reveal an important reusable experience that should help future squads?
+
+   Only propagate items that are concrete, reusable, and proven by this run, such as:
+
+   - a failure mode plus the repair that worked
+   - a validation gap that allowed a broken output to pass too far
+   - a publish/distribution/dashboard recovery path that should become standard
+   - a parser, prompt, routing, or environment behavior that can recur across squads
+
+   Routing rule:
+
+   - If it changes a shared tool or integration behavior → register it in the relevant shared skill under `skills/{skill}/` and update executable code/tests when needed
+   - If it changes pipeline orchestration or finalization behavior across squads → register it in `_opensquad/core/` or the relevant `_opensquad/core/best-practices/` file
+   - If it is only recurring inside one squad → keep it in `squads/{name}/_memory/memories.md`
+   - If it is only a one-off local incident with no reusable value → do not propagate it
+
+   Do not stop at documenting the current run locally when the learning is cross-squad. Before closing the pipeline, either register the reusable learning in the appropriate shared layer or explicitly conclude that there is no reusable learning to propagate.
+
+1. Present completion summary:
+
+   - **Crucial Rule for the Completion Summary**: ALWAYS explicitly list the generated final URLs/permalinks (e.g., published social posts, videos, or scheduled dashboard URLs) inside the completion summary so the user can click them directly. Do not just refer the user to the `publish-result.md` or the `run-dashboard`. Show the actual links.
+
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ✅ Pipeline complete!
+   📁 Run folder: squads/{name}/output/{run_id}/
+   📄 Output saved to: {output path}
+   
+   🔗 Published Links:
+   - Dashboard: {dashboard_url}
+   - Facebook/Instagram: {social_url}
+   - YouTube: {youtube_url}
+   - (List any other published platforms here)
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   What would you like to do?
+   ● Run again (new topic)
+   ○ Edit this content
+   ○ Back to menu
+   ```
+
+## Error Handling
+
+- If a subagent fails, retry once. If it fails again, inform the user and offer to skip the step or abort.
+- If a step file is missing, inform the user and suggest running `/opensquad edit {squad}` to fix.
+- If company.md is empty, stop and redirect to onboarding.
+- Never continue past a checkpoint without user input.
+
+## Pipeline State
+
+Track pipeline state in memory during execution:
+
+- Run ID (run_id) — the output subfolder name for this execution
+- Current step index
+- Outputs from each completed step (file paths)
+- User choices at checkpoints
+- Review cycle count
+- Start time
+
+This state does NOT persist to disk — it exists only during the current run.