sinapse-ai 1.7.0 → 1.9.0

package/.sinapse-ai/development/agents/developer.md

@@ -272,6 +272,8 @@ dependencies:
     - create-worktree.md
     - list-worktrees.md
     - remove-worktree.md
+    # Execution Mode (task→agent binding gap closed)
+    - yolo-toggle.md
   scripts:
     # Recovery System (Epic 5)
     - recovery-tracker.js # Track implementation attempts

package/.sinapse-ai/development/agents/devops.md

@@ -280,6 +280,15 @@ dependencies:
     - merge-worktree.md
     # Environment & Deployment (Infra Research 2026-04)
     - environment-promotion-pipeline.md
+    # Release & Contributor Flow (task→agent binding gap closed)
+    - publish-npm.md
+    - review-contributor-pr.md
+    # IDS Governance & Registry (task→agent binding gap closed — devops owns CI/G6)
+    - ids-governor.md
+    - ids-health.md
+    - ids-query.md
+    - sync-registry-intel.md
+    - delegate-to-external-executor.md
   knowledge_bases:
     - environment-deployment-patterns.md
   workflows:

package/.sinapse-ai/development/agents/snps-orqx.md

@@ -1,6 +1,6 @@
 # Agent: Imperator — Sinapse Master
 
-> ACTIVATION-NOTICE: You are now Imperator — the supreme orchestrator of the SINAPSE ecosystem. You have authority over all 18 specialized squads (189 agents total). You do not execute domain work yourself — you diagnose, route, coordinate, and synthesize across the entire ecosystem. Every request passes through you first. You are the CEO of this AI workforce.
+> ACTIVATION-NOTICE: You are now Imperator — the supreme orchestrator of the SINAPSE ecosystem. You have authority over all 17 specialized squads (172 agents total). You do not execute domain work yourself — you diagnose, route, coordinate, and synthesize across the entire ecosystem. Every request passes through you first. You are the CEO of this AI workforce.
 
 ## ACTIVATION INSTRUCTIONS — MANDATORY ON LOAD
 
@@ -25,9 +25,9 @@ Then display:
 
 ```
  AI Agent Squads for Claude Code
- 18 squads · 189 agents · 1,213 tasks
+ 17 squads · 172 agents · 1,200 tasks
 
- 👑 Imperator — Sinapse Master activated
+ 👑 [Imperator] — Sinapse Master activated
 
  Describe your goal and I'll diagnose the domain
  and route to the right agent.
@@ -112,7 +112,7 @@ agent:
   whenToUse: "ALWAYS as the default agent. Imperator is the first point of contact for EVERY request. Routes directly to @specialist when clear, or to @{domain}-orqx when complex."
 
 persona:
-  role: "Supreme Orchestrator of all 18 SINAPSE Squads (189 agents)"
+  role: "Supreme Orchestrator of all 17 SINAPSE Squads (172 agents)"
   identity: >
     The strategic mind at the top of the SINAPSE hierarchy. Imperator
     sees across all domains — branding, commerce, content, copy, animations,
@@ -161,7 +161,7 @@ intelligent_routing:
       - '"Assessment de seguranca" -> @cyber-orqx'
 
 # ══════════════════════════════════════════════════════════════════════════════
-# COMPLETE ROUTING TABLE — ALL 18 SQUADS
+# COMPLETE ROUTING TABLE — ALL 17 SQUADS
 # ══════════════════════════════════════════════════════════════════════════════
 
 routing_table:
@@ -211,23 +211,14 @@ routing_table:
       tasks: 73
       keywords: ["animacao", "animation", "Three.js", "shader", "WebGL", "GSAP", "motion", "Framer Motion", "parallax", "3D", "canvas", "particle"]
 
-    - squad: squad-artdir
-      prefix: artdir
-      orchestrator: artdir-orqx (Canvas)
-      invocation: "/artdir:agents:artdir-orqx"
-      domain: "Art direction para landing pages, websites, plataformas SaaS premium. 7 pilares de retencao + conversao. Visual strategy, design system premium, packaging visual."
-      agents: 14
-      tasks: 13
-      keywords: ["art direction", "direcao de arte", "landing page", "LP", "site", "website", "premium", "platform", "SaaS visual", "packaging visual", "visual strategy", "pilar", "retencao", "conversao"]
-
     - squad: squad-design
       prefix: design
       orchestrator: design-orqx (Nexus)
       invocation: "/design:agents:design-orqx"
-      domain: "UX/UI, experiencia digital, wireframes, prototipos, design system, acessibilidade"
-      agents: 8
+      domain: "UX/UI, experiencia digital, wireframes, prototipos, design system, acessibilidade. Art direction para landing pages, websites, plataformas SaaS premium — visual strategy, design system premium, packaging visual, 7 pilares de retencao + conversao."
+      agents: 14
       tasks: 101
-      keywords: ["UX", "UI", "experiencia", "wireframe", "prototipo", "design system", "acessibilidade", "usabilidade", "user research", "interaction design", "figma"]
+      keywords: ["UX", "UI", "experiencia", "wireframe", "prototipo", "design system", "acessibilidade", "usabilidade", "user research", "interaction design", "figma", "art direction", "direcao de arte", "landing page", "LP", "site", "website", "premium", "platform", "SaaS visual", "packaging visual", "visual strategy", "pilar", "retencao", "conversao"]
 
     - squad: squad-finance
       prefix: finance
@@ -522,7 +513,7 @@ commands:
     description: "Design a multi-squad execution plan for a complex initiative"
     args: "{initiative_description}"
   - name: "*status"
-    description: "Report on all 18 squads — capabilities, agents, tasks"
+    description: "Report on all 17 squads — capabilities, agents, tasks"
     args: "[--squad {name}] [--verbose]"
   - name: "*brief"
     description: "Generate a strategic brief leveraging relevant squads"
@@ -591,7 +582,7 @@ framework_compatibility:
     description: >
       Without any external framework, Imperator is the top-level orchestrator.
       Users invoke /sinapse:agents:sinapse-orqx directly, and Imperator routes
-      to all 18 squads autonomously.
+      to all 17 squads autonomously.
     orchestrator: "sinapse-orqx (Imperator)"
 
   with_sinapse:
@@ -672,11 +663,10 @@ Imperator can provide ecosystem-wide insights by combining capabilities across s
 | 15 | cybersecurity | cyber | Fortress | Cybersecurity, compliance, pentest |
 | 16 | cloning | cloning | Helix | Cognitive cloning, mental DNA extraction |
 | 17 | courses | courses | Syllabus | Course creation, workshops, ebooks |
-| 18 | claude-code-mastery | claude | Nucleus | Claude Code mastery, prompt engineering |
 
-**Total ecosystem:** 18 squads, 189 agents, 1,213 tasks
+**Total ecosystem:** 17 squads, 172 agents, 1,200 tasks
 
 ## Cross-Squad Handoffs
 - **Receives from:** Every squad (escalations, cross-squad requests)
 - **Sends to:** Every squad (routed work, coordination directives)
-- **Coordinates with:** All 18 squad orchestrators
+- **Coordinates with:** All 17 squad orchestrators

package/.sinapse-ai/development/external-executors/README.md

@@ -0,0 +1,18 @@
+# External Executors
+
+External executors let one SINAPSE runtime keep orchestration authority while another CLI runtime performs the implementation work in an isolated run directory.
+
+This pattern is opt-in. The default development mode remains `native`, where the active SINAPSE agent plans, implements, validates, and updates story state in the same runtime.
+
+## Contract
+
+- The orchestrator owns story selection, acceptance criteria, scope, review, and story state updates.
+- The external executor owns only the delegated implementation attempt.
+- Run artifacts live under `.sinapse/external-runs/<timestamp>-<slug>/`.
+- The orchestrator must read the executor output and inspect the diff before updating checkboxes, File List, or story status.
+
+## Providers
+
+- `codex.md`: reference provider for Codex CLI headless execution.
+
+Future provider files can document `aider`, `cline`, `cursor-cli`, `gemini-cli`, or any other runtime that supports non-interactive execution.

package/.sinapse-ai/development/external-executors/codex.md

@@ -0,0 +1,56 @@
+# Codex External Executor Adapter
+
+## Provider ID
+
+`codex`
+
+## Invocation
+
+The `sinapse-delegate` wrapper launches Codex in non-interactive exec mode and sends the prompt through stdin:
+
+```bash
+codex -a never -s workspace-write exec -C <workdir> -o <run_dir>/output.md -
+```
+
+For `--sandbox danger-full-access`, the wrapper uses the explicit Codex bypass flag:
+
+```bash
+codex --dangerously-bypass-approvals-and-sandbox exec -C <workdir> -o <run_dir>/output.md -
+```
+
+## Sandbox Mapping
+
+| SINAPSE sandbox | Codex behavior |
+| --- | --- |
+| `read-only` | `-a never -s read-only` |
+| `workspace-write` | `-a never -s workspace-write` |
+| `full-auto` | `-a never -s workspace-write` |
+| `danger-full-access` | `--dangerously-bypass-approvals-and-sandbox` |
+
+`full-auto` is retained as a SINAPSE abstraction for background executor runs. On current Codex CLI versions, it maps to `workspace-write` plus `approval=never` rather than bypassing the sandbox.
+
+## Supported Options
+
+- `--model <model>` maps to `codex -m <model>`.
+- `--profile <name>` maps to `codex -p <name>`.
+- `--image <path>` maps to `codex exec -i <path>`.
+- `--workdir <path>` maps to `codex exec -C <path>`.
+- `--prompt` and `--prompt-file` are sent via stdin.
+- `--output-last-message` is managed by the wrapper through `-o <run_dir>/output.md`.
+
+## Exit Code Semantics
+
+- In background mode, `sinapse-delegate` returns after a process is spawned and prints the PID.
+- In foreground mode, `sinapse-delegate` waits for Codex and returns Codex's exit code.
+- Missing Codex binary is a pre-condition failure.
+- Dirty git worktrees are blocked unless `--allow-dirty` is explicit.
+
+## Run Artifacts
+
+Each run directory contains:
+
+- `prompt.md`: prompt sent to Codex
+- `output.md`: last Codex message, written by Codex
+- `codex.log`: stdout/stderr stream
+- `command.txt`: exact command line
+- `metadata.json`: provider, workdir, sandbox, PID, and artifact paths

package/.sinapse-ai/development/scripts/populate-entity-registry.js

@@ -12,6 +12,12 @@ const REPO_ROOT = path.resolve(__dirname, '../../..');
 const REGISTRY_PATH = path.resolve(__dirname, '../../data/entity-registry.yaml');
 
 const SCAN_CONFIG = [
+  // `bin` scanned FIRST on purpose: buildNameIndex is last-wins for the entity
+  // id key, so scanning bin before the other categories lets later categories
+  // win on the few generic id collisions (cli, constants) — preserving existing
+  // dependency resolution — while still indexing bin entry-points so their
+  // requires (e.g. bin/commands/ideate.js → ideation-engine) populate usedBy.
+  { category: 'bin', basePath: 'bin', glob: '**/*.js', type: 'script' },
   { category: 'tasks', basePath: '.sinapse-ai/development/tasks', glob: '**/*.md', type: 'task' },
   { category: 'templates', basePath: '.sinapse-ai/product/templates', glob: '**/*.{yaml,yml,md}', type: 'template' },
   { category: 'scripts', basePath: '.sinapse-ai/development/scripts', glob: '**/*.{js,mjs}', type: 'script' },
@@ -32,6 +38,11 @@ const SCAN_CONFIG = [
   { category: 'product-data', basePath: '.sinapse-ai/product/data', glob: '**/*.{yaml,yml,md}', type: 'data' }
 ];
 
+// Generated/self-referential artifacts excluded from scanning. The registry
+// must not track ITSELF as an entity — its checksum would change every regen
+// (each run rewrites the file), so it could never reach a stable fixed point.
+const SCAN_IGNORE = ['**/entity-registry.yaml'];
+
 const ADAPTABILITY_DEFAULTS = {
   agent: 0.3,
   module: 0.4,
@@ -322,7 +333,17 @@ function scanCategory(config, verbose = false) {
   }
 
   const globPattern = path.posix.join(absBase.replace(/\\/g, '/'), config.glob);
-  const files = fg.sync(globPattern, { onlyFiles: true, absolute: true });
+  // Sort the glob result: fast-glob returns files in filesystem (readdir) order,
+  // which varies across machines/runs and reorders the entire registry on every
+  // regen (non-deterministic churn). A stable sort makes entity insertion order —
+  // and everything derived from it (usedBy push order, YAML key order) —
+  // deterministic.
+  // `ignore` drops self-referential / generated artifacts (the registry file
+  // itself) — tracking the registry as an entity makes its checksum oscillate
+  // every run (each regen rewrites the file), which can never stabilize.
+  const files = fg
+    .sync(globPattern, { onlyFiles: true, absolute: true, ignore: SCAN_IGNORE })
+    .sort();
 
   const entities = {};
   const seenIds = new Set();
@@ -474,6 +495,14 @@ function resolveUsedBy(allEntities) {
       }
     }
   }
+
+  // Sort usedBy lists so the serialized order is deterministic regardless of the
+  // order entities were scanned in.
+  for (const entities of Object.values(allEntities)) {
+    for (const entity of Object.values(entities)) {
+      entity.usedBy.sort();
+    }
+  }
 }
 
 function classifyDependencies(allEntities, nameIndex) {
@@ -551,14 +580,23 @@ function populate(options = {}) {
       for (const [category, entities] of Object.entries(existingRegistry.entities)) {
         if (!allEntities[category]) continue;
         for (const [entityId, entity] of Object.entries(entities)) {
-          if (entity.invocationExamples && Array.isArray(entity.invocationExamples) && allEntities[category][entityId]) {
+          const fresh = allEntities[category][entityId];
+          if (!fresh) continue;
+          if (entity.invocationExamples && Array.isArray(entity.invocationExamples)) {
             // Enforce limits: max 3 examples, each max 200 chars
             const examples = entity.invocationExamples.slice(0, 3).map((e) => String(e).slice(0, 200));
-            allEntities[category][entityId].invocationExamples = examples;
+            fresh.invocationExamples = examples;
+          }
+          // Preserve lastVerified when the file content (checksum) is unchanged.
+          // Re-stamping every entity on each regen — even untouched ones — was a
+          // primary source of registry churn; the timestamp only carries meaning
+          // when the entity was actually re-verified (i.e. its checksum changed).
+          if (entity.lastVerified && entity.checksum === fresh.checksum) {
+            fresh.lastVerified = entity.lastVerified;
           }
         }
       }
-      console.log('[IDS] Preserved invocationExamples from existing registry');
+      console.log('[IDS] Preserved invocationExamples + lastVerified from existing registry');
     }
   } catch {
     // No existing registry or parse error — skip preservation
@@ -599,11 +637,28 @@ function populate(options = {}) {
     categories
   };
 
-  const yamlContent = yaml.dump(registry, {
-    lineWidth: 120,
-    noRefs: true,
-    sortKeys: false
-  });
+  const dumpOpts = { lineWidth: 120, noRefs: true, sortKeys: false };
+
+  // Idempotent timestamp: only bump `lastUpdated` when the substantive content
+  // (everything except the timestamp itself) actually changed. Without this,
+  // every regen rewrites the file solely because of a new timestamp, producing
+  // churn on each commit even when nothing meaningful changed.
+  try {
+    const existing = yaml.load(fs.readFileSync(REGISTRY_PATH, 'utf8'));
+    if (existing && existing.metadata && existing.metadata.lastUpdated) {
+      const stripStamp = (r) => yaml.dump(
+        { ...r, metadata: { ...r.metadata, lastUpdated: null } },
+        dumpOpts,
+      );
+      if (stripStamp(existing) === stripStamp(registry)) {
+        registry.metadata.lastUpdated = existing.metadata.lastUpdated;
+      }
+    }
+  } catch {
+    // No existing registry or parse error — keep the fresh timestamp.
+  }
+
+  const yamlContent = yaml.dump(registry, dumpOpts);
 
   try {
     fs.writeFileSync(REGISTRY_PATH, yamlContent, 'utf8');
@@ -618,6 +673,7 @@ function populate(options = {}) {
 
 function getCategoryDescription(category) {
   const descriptions = {
+    bin: 'CLI entry points and command implementations',
     tasks: 'Executable task workflows for agent operations',
     templates: 'Document and code generation templates',
     scripts: 'Utility and automation scripts',

package/.sinapse-ai/development/scripts/squad/squad-downloader.js

@@ -52,6 +52,20 @@ const ALLOWED_REDIRECT_HOSTS = new Set([
  */
 const MAX_REDIRECTS = 5;
 
+/**
+ * Per-request timeout (ms). Aborts a hung/slow remote so a compromised or
+ * unresponsive host can't stall the installer indefinitely (P3-001).
+ * @constant {number}
+ */
+const REQUEST_TIMEOUT_MS = 30000;
+
+/**
+ * Maximum response size (bytes). Caps a single download so a malicious/
+ * misconfigured host can't exhaust memory (10 MB is ample for a squad).
+ * @constant {number}
+ */
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+
 /**
  * Error codes for SquadDownloaderError
  * @enum {string}
@@ -483,8 +497,7 @@ class SquadDownloader {
         }
       }
 
-      https
-        .get(url, options, (res) => {
+      const req = https.get(url, options, (res) => {
           // Check for rate limiting
           if (res.statusCode === 403) {
             const rateLimitRemaining = res.headers['x-ratelimit-remaining'];
@@ -565,25 +578,55 @@ class SquadDownloader {
             return;
           }
 
-          // Collect chunks as Buffer objects to support binary files
+          // Collect chunks as Buffer objects to support binary files, capping
+          // total size to prevent a malicious host from exhausting memory.
           const chunks = [];
+          let total = 0;
           res.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > MAX_RESPONSE_BYTES) {
+              const err = new SquadDownloaderError(
+                DownloaderErrorCodes.NETWORK_ERROR,
+                `Response exceeded ${MAX_RESPONSE_BYTES} bytes — aborting`,
+                'The remote file is unexpectedly large; verify the source',
+              );
+              if (typeof req.destroy === 'function') req.destroy(err);
+              else reject(err);
+              return;
+            }
             chunks.push(chunk);
           });
           res.on('end', () => {
             // Concatenate all chunks into a single Buffer
             resolve(Buffer.concat(chunks));
           });
-        })
-        .on('error', (error) => {
-          reject(
-            new SquadDownloaderError(
-              DownloaderErrorCodes.NETWORK_ERROR,
-              `Network error: ${error.message}`,
-              'Check internet connection',
-            ),
+        });
+
+      // Abort hung requests (P3-001) — destroy() surfaces via the 'error' handler.
+      // Guarded: test doubles for https.get may not implement setTimeout/destroy.
+      if (typeof req.setTimeout === 'function') {
+        req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+          const err = new SquadDownloaderError(
+            DownloaderErrorCodes.NETWORK_ERROR,
+            `Request timed out after ${REQUEST_TIMEOUT_MS}ms fetching ${url}`,
+            'Check internet connection or try again later',
           );
+          if (typeof req.destroy === 'function') req.destroy(err);
+          else reject(err);
         });
+      }
+
+      req.on('error', (error) => {
+        reject(
+          error instanceof SquadDownloaderError
+            ? error
+            : new SquadDownloaderError(
+                DownloaderErrorCodes.NETWORK_ERROR,
+                `Network error: ${error.message}`,
+                'Check internet connection',
+              ),
+        );
+      });
     });
   }
 

package/.sinapse-ai/development/tasks/build-autonomous.md

@@ -1,3 +1,11 @@
+---
+task: build-autonomous
+responsavel: '@developer'
+entrada: '`story-id` + opções (`--worktree`, `--timeout`, `--max-retries`)'
+saida: 'Subtasks executadas com retry/self-critique + estado de build + relatório'
+atomic_layer: Task
+---
+
 # Task: Build Autonomous
 
 > **Command:** `*build-autonomous {story-id}`
@@ -192,8 +200,10 @@ The AutonomousBuildLoop emits these events for monitoring:
 _Task file for Story 8.1 - Coder Agent Loop_
 
 ## Handoff
+
 next_agent: @quality-gate
 next_command: *review {story-id}
 condition: Autonomous build completed successfully
 alternatives:
-  - agent: @developer, command: *build-resume {story-id}, condition: Build failed, needs resume
+
+- agent: @developer, command: *build-resume {story-id}, condition: Build failed, needs resume

package/.sinapse-ai/development/tasks/build-resume.md

@@ -1,3 +1,11 @@
+---
+task: build-resume
+responsavel: '@developer'
+entrada: '`story-id` — build a retomar'
+saida: 'Build autônomo retomado a partir do último checkpoint'
+atomic_layer: Task
+---
+
 # Task: Build Resume
 
 > **Command:** `*build-resume {story-id}`

package/.sinapse-ai/development/tasks/build-status.md

@@ -1,3 +1,11 @@
+---
+task: build-status
+responsavel: '@developer'
+entrada: '`story-id` ou `--all`'
+saida: 'Status, progresso, métricas e indicadores de saúde dos builds'
+atomic_layer: Task
+---
+
 # Task: Build Status
 
 > **Command:** `*build-status {story-id}` or `*build-status --all`

package/.sinapse-ai/development/tasks/build.md

@@ -1,3 +1,11 @@
+---
+task: build
+responsavel: '@developer'
+entrada: '`story-id` + flags (`--dry-run`, `--no-merge`, `--no-qa`, `--verbose`, `--timeout`)'
+saida: 'Build autônomo completo + relatório em `plan/build-report-{story-id}.md`'
+atomic_layer: Task
+---
+
 # Task: Build (Autonomous)
 
 > **Command:** `*build {story-id}`

package/.sinapse-ai/development/tasks/cleanup-worktrees.md

@@ -1,3 +1,11 @@
+---
+task: cleanup-worktrees
+responsavel: '@developer'
+entrada: '`--days` — limite de idade em dias (default: 30)'
+saida: 'Worktrees obsoletas removidas com segurança + resumo da limpeza'
+atomic_layer: Task
+---
+
 # cleanup-worktrees
 
 Remove all stale git worktrees older than specified threshold.
@@ -37,4 +45,3 @@ Clean up abandoned worktrees to maintain repository hygiene.
 - `*list-worktrees` - List all worktrees
 - `*remove-worktree` - Remove single worktree
 - `*create-worktree` - Create new worktree
-

package/.sinapse-ai/development/tasks/delegate-to-external-executor.md

@@ -0,0 +1,152 @@
+# delegate-to-external-executor.md
+
+**Task**: Delegate Implementation to External Executor
+
+**Purpose**: Standardize the orchestrator/executor split for SINAPSE workflows. The active SINAPSE runtime keeps authority over story interpretation, acceptance criteria validation, constitutional gates, review, and story updates while a separate CLI runtime performs only the implementation attempt.
+
+**When to use**: Use only for `@developer` implementation work where the story scope is clear enough to hand to another runtime. Do not use for @product-lead, @quality-gate, @sprint-lead, @devops, architecture approval, or release authority.
+
+## Task Definition
+
+```yaml
+task: delegateToExternalExecutor()
+responsavel: Orchestrating agent
+responsavel_type: Agente
+atomic_layer: Organism
+
+inputs:
+  - campo: prompt
+    tipo: string
+    obrigatorio: true
+    validacao: Must cite acceptance criteria, story path, file scope, and explicit non-goals
+  - campo: slug
+    tipo: string
+    obrigatorio: true
+    validacao: Stable filesystem-safe run slug
+  - campo: story_id
+    tipo: string
+    obrigatorio: false
+  - campo: story_path
+    tipo: string
+    obrigatorio: false
+  - campo: workdir
+    tipo: string
+    obrigatorio: false
+    default: Current project root
+  - campo: provider
+    tipo: string
+    obrigatorio: false
+    default: codex
+
+outputs:
+  - campo: run_dir
+    tipo: string
+    destino: Orchestrator
+  - campo: output
+    tipo: file
+    destino: <run_dir>/output.md
+  - campo: log
+    tipo: file
+    destino: <run_dir>/<provider>.log
+  - campo: diff
+    tipo: git-diff
+    destino: Orchestrator review
+```
+
+## Configuration
+
+Delegation is disabled by default.
+
+```yaml
+dev:
+  execution_mode: native       # native | delegate
+  delegate_to: codex
+  auto_review: true
+
+external_executors:
+  enabled: false
+  default_sandbox: workspace-write   # read-only | workspace-write | full-auto | danger-full-access
+  run_dir: .sinapse/external-runs
+```
+
+## Pre-Conditions
+
+```yaml
+pre_conditions:
+  - [ ] External executor provider is installed and available on PATH.
+  - [ ] Working tree is clean, or existing intentional changes are already committed.
+  - [ ] Prompt cites the story path and acceptance criteria.
+  - [ ] Prompt lists allowed file scope and explicit non-goals.
+  - [ ] Delegated work is implementation work owned by @developer.
+  - [ ] Orchestrator has enough context to review the resulting diff.
+```
+
+## Execution
+
+### 1. Build the Prompt
+
+The orchestrator writes a prompt that contains:
+
+- Story ID and story path
+- Acceptance criteria copied or summarized from the story
+- Allowed file paths or modules
+- Testing expectations
+- Constraints from Constitution and project rules
+- Explicit instruction that the executor must not update story status, checkboxes, File List, PRs, or releases
+
+### 2. Start the Delegate Run
+
+Use the wrapper:
+
+```bash
+sinapse-delegate codex -t <slug> -f <prompt_file> -d <workdir>
+```
+
+The wrapper prints:
+
+```text
+STATUS=started
+RUN_DIR=.sinapse/external-runs/<timestamp>-<slug>
+PID=<pid>
+LOG=<run_dir>/codex.log
+OUTPUT=<run_dir>/output.md
+PROMPT=<run_dir>/prompt.md
+COMMAND=<provider command>
+```
+
+### 3. Monitor Completion
+
+The orchestrator may tail the log or wait for the PID. Do not mark story progress while the external executor is still running.
+
+### 4. Review Output and Diff
+
+The orchestrator must read:
+
+- `<run_dir>/output.md`
+- `<run_dir>/<provider>.log`
+- `git diff`
+
+Then validate:
+
+```yaml
+review_checklist:
+  - [ ] Every acceptance criterion is satisfied.
+  - [ ] Diff scope matches the story and prompt.
+  - [ ] Article IV No Invention: every change traces to a requirement.
+  - [ ] Tests were added or updated when behavior changed.
+  - [ ] Lint, typecheck, and relevant tests pass.
+  - [ ] No story state was mutated before review approval.
+```
+
+### 5. Accept or Iterate
+
+- **Approved**: orchestrator updates story checkboxes, File List, status, and final validation evidence.
+- **Rejected**: orchestrator writes specific feedback and may start a new run with a new slug or iteration suffix.
+
+## Anti-Patterns
+
+- Marking a story done by trusting the executor summary without reading the diff.
+- Delegating @product-lead, @quality-gate, @sprint-lead, or @devops authority to an external runtime.
+- Letting the executor create PRs, push, release, or mutate story state.
+- Delegating vague work without acceptance criteria and file scope.
+- Running with `danger-full-access` unless the surrounding environment is externally sandboxed.