create-byan-agent 2.45.0 → 2.47.1

package/CHANGELOG.md

@@ -9,6 +9,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.47.1] - 2026-07-16
+
+### Fixed - Doctrine told users to invoke with `@byan`, which does not load the skill
+
+- The docs said "tape `@byan` / `@hermes`" to invoke BYAN. In Claude Code, `@` is a
+  file mention, not a skill loader — so the byan-byan skill (which holds the agent
+  entry gate) was not loaded, and BYAN ran a task inline with no dispatch. Root
+  cause of the entry gate appearing "not to work" on a real machine.
+- Corrected the entry guidance in `CLAUDE.md`: invoke BYAN with the **command**
+  `/byan-byan` (it loads the skill, the entry gate, and the rail) ; noted explicitly
+  that `@byan`/`@hermes` do not load the skill. Mirrored to install/templates.
+- Note: the entry-gate code (2.47.0) is unchanged and correct ; it simply was not
+  reached because the skill was not loaded. Open question (does the loaded doctrine
+  reliably make BYAN propose an agent, or is a hard pre-write block needed) is to be
+  decided by testing `/byan-byan` with the rail actually loaded.
+
+## [2.47.0] - 2026-07-16
+
+### Added - Mandatory agent entry gate (match-or-create), the base of BYAN
+
+- Makes the agent dispatch the front door of every non-conversational task: BYAN +
+  Hermes evaluate which specialist agent fits the need and PROPOSE it ; the user
+  validates (double validation IA + human) ; THEN the workflow runs. No suited
+  agent -> propose an interview to frame the need -> web research on the trade's
+  competencies + best practices -> create the tailored agent -> workflow. The
+  interview is triggered by the ABSENCE of a suited agent, not by task size (a fit
+  routes directly, no ceremony). This closes the gap where a plain task got done
+  inline without any dispatch.
+- F1 `lib/agent-matcher.js` — pure suitability pre-filter: (task text + roster)
+  -> ranked candidates + a {fit | no-fit} verdict. Curated Hermes trigger words
+  (weighted) over a title/role text overlap ; accent-insensitive ; a no-fit is the
+  interview signal. Loader reads the roster from agent-manifest.csv (robust CSV
+  parse). It PROPOSES, it does not decide alone.
+- F2/F3 doctrine `.claude/rules/agent-entry-gate.md` (+ pointer in CLAUDE.md + a
+  section 0 in the byan-byan skill): the rail, the two dispatch layers (agent vs
+  runtime), the proportionality (verify every task, interview only on no-fit), the
+  double validation, and the web-research step in agent creation.
+- F4 reactive net `.claude/hooks/agent-gate-check.js` (+ pure core
+  `lib/agent-gate.js`): a Stop hook that flags a task done directly (files written)
+  with no agent proposal and outside an active FD cycle ; the next-turn voice
+  reminder surfaces it in plain French. Non-blocking (the correction lands next
+  turn) ; exits 0 in every path. Honest ceiling: no pre-display interception, so
+  the rail is doctrine + this net, not a first-turn wall.
+- F5: tests (`test/agent-matcher.test.js` node:test, `.claude/__tests__/agent-gate.test.js`
+  jest). Full MCP suite + jest suite green ; workflow linter OK ; skill bundles
+  re-checked ; zero emoji. Shipped via install/templates (5 files added to the sync
+  manifest). Doc: `.claude/rules/agent-entry-gate.md`.
+
+## [2.46.0] - 2026-07-15
+
+### Added - Intelligent dispatch: Codex/Claude routing + architect-dev loop (option B)
+
+- Route each task to the runtime that is genuinely better for it, on the right
+  model and effort for its complexity, and let an architect (Claude) and a dev
+  (Codex or Claude) exchange turn by turn until the work converges. Layered,
+  ports-and-adapters design so the durable core stays independent of the transport.
+- F1 `lib/dispatch-router.js` — pure routing brain: {nature, complexity} ->
+  {runtime, model, effort}. Runtime table is the cross-checked result (Codex for
+  execution/shell/deploy/devops/browser ; Claude for architecture/refactor/quality/
+  planning ; unknown -> Claude). Complexity picks the Claude model tier via
+  native-tiers (haiku/sonnet/inherit) or the Codex reasoning-effort (low/med/high).
+  Two red lines enforced in code, not left to the caller: Fable is refused
+  (assertNoFable throws) and verification is forced to Claude (a runtime does not
+  grade its own work).
+- F2 `lib/codex-bridge.js` — Codex transport behind a swappable adapter. The
+  shipped codex-exec adapter runs `codex exec` read-only for a unified diff that
+  Claude applies with git apply (Codex writes nothing -> works under a locked-down
+  sandbox e.g. Landlock). Failure is a value (ok:false + reason) so the loop falls
+  back to Claude. codex-mcp is a declared V2 slot (available:false) for the tighter
+  `codex mcp-server` coupling later, with no change to F1/F4.
+- F3 `lib/dispatch-blackboard.js` — the turn-by-turn shared board the agents use to
+  exchange (build/render pure ; JSONL sidecar I/O isolated). The honest substitute
+  for a live peer chat: an orchestrated loop, like a chat server holding the turns.
+- F4 `lib/dispatch-orchestrator.js` — the loop core: routes via F1, runs
+  architect<->dev through the board until convergence, executors injected (Codex vs
+  Claude) so it is fully unit-tested. `.claude/workflows/intelligent-dispatch.js` is
+  the native launch facade for one routed task (design -> implement -> verify ;
+  the verify leaf is a Claude reviewer, not the dev).
+- Enforcement: the Codex auto-delegate config ships DISARMED (absent = off) ;
+  arming stays a per-machine opt-in (`_byan/_config/autodelegate.json`, gitignored).
+  Unit tests: `test/dispatch-router|codex-bridge|dispatch-blackboard|dispatch-orchestrator.test.js`.
+  Also corrected a pre-existing api-tools test drift (byan_api_knowledge_retrieve
+  was registered in server.js but absent from the test's tool list). Full MCP suite
+  green (833 node:test) + jest suite green. Doc: `docs/intelligent-dispatch.md`.
+  Shipped via install/templates (10 files added to the sync manifest).
+
 ## [2.45.0] - 2026-07-15
 
 ### Added - Plain-language guard for every agent (Mantra IA-26 "Parler Reel")

package/install/templates/.claude/CLAUDE.md

@@ -11,10 +11,20 @@
 Avant de chercher un agent specifique, demande a Hermes. Il connait tous les agents,
 workflows et contextes, et te route vers le bon specialiste.
 
-Pour invoquer Hermes, tape: `@hermes` ou demande simplement "quel agent pour [ta tache]?"
+Pour lancer BYAN sur une tache, utilise la **commande** `/byan-byan` : c'est elle qui charge le skill (donc la porte d'entree et le rail de dispatch). Attention — `@byan` / `@hermes` NE chargent PAS le skill : cote Claude Code, `@` est une mention de fichier, pas un lanceur. Une fois dans `/byan-byan`, decris ta tache ou demande "quel agent pour [ta tache] ?".
 
 Voir @.claude/rules/hermes-dispatcher.md pour les commandes Hermes.
 
+## Porte d'entree — dispatch d'agent obligatoire (match-or-create)
+
+La base de BYAN : toute tache non-conversationnelle passe d'abord par le dispatch
+d'agent. BYAN + Hermes evaluent quel agent specialiste colle au besoin et le
+PROPOSENT ; l'utilisateur valide (double validation IA + humain), PUIS on lance le
+workflow. Aucun agent adapte -> interview pour cadrer le besoin -> recherche web
+(competences + bonnes pratiques du metier) -> creation de l'agent sur mesure ->
+workflow. Le declencheur de l'interview est l'absence d'un agent adapte, pas la
+taille de la tache. Detail + enforcement : voir @.claude/rules/agent-entry-gate.md
+
 ## Architecture BYAN
 
 ```
@@ -58,7 +68,7 @@ Doctrine d'equipe complete (template role-in-team, analogie orchestre, principes
 
 ## Commandes Utiles
 
-- `@hermes` → Dispatcher universel (recommandations, routage, pipelines)
+- `/byan-byan` → Entree BYAN + dispatcher universel (recommandations, routage, pipelines). Le `@` ne charge pas le skill.
 - Agent disponibles: voir @.claude/rules/byan-agents.md
 - Doctrine d'equipe: voir @.claude/rules/team-doctrine.md
 - Methodologie: voir @.claude/rules/merise-agile.md

package/install/templates/.claude/hooks/agent-gate-check.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+// Stop hook — the reactive net for BYAN's mandatory agent entry gate (F4).
+//
+// At end of turn it asks: was a task handled DIRECTLY (files written) without any
+// agent proposal and outside an active FD cycle ? If so it writes a one-turn flag
+// under _byan-output/ ; the next-turn voice reminder surfaces it in plain French.
+// It NEVER blocks the turn (the user asked to signal, not trap) — always exits 0.
+//
+// The judgment lives in lib/agent-gate.js (pure) ; this shell only extracts the
+// signals from the transcript + fd-state.
+
+const fs = require('fs');
+const { extractLastAssistantText, extractRecentMessages } = require('./lib/transcript-read');
+const gate = require('./lib/agent-gate');
+
+// detect(payload, projectDir) — testable core. Returns the assessment and writes
+// the flag on a slip.
+function detect(payload, projectDir) {
+  const text = extractLastAssistantText(payload);
+  const messages = extractRecentMessages(payload, 8) || [];
+  const assessment = gate.assessTurn({
+    wroteFiles: gate.hasWriteActivity(messages),
+    proposedAgent: gate.hasProposalMarker(text),
+    fdActive: gate.fdIsActive(projectDir),
+  });
+  if (assessment.slip) gate.writeSlip(projectDir, assessment.reason);
+  return assessment;
+}
+
+function readStdin() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  let payload = {};
+  try {
+    const raw = readStdin();
+    if (raw && raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    payload = {};
+  }
+  try {
+    detect(payload, projectDir);
+  } catch {
+    // never block end-of-turn
+  }
+  process.stdout.write('{}');
+}
+
+module.exports = { detect };

package/install/templates/.claude/hooks/inject-voice-anchor.js

@@ -27,6 +27,7 @@ const fs = require('fs');
 const path = require('path');
 const { buildTaoContext, turnCounterPath } = require('./inject-tao');
 const pl = require('./lib/plain-language');
+const gate = require('./lib/agent-gate');
 
 const ANCHOR = [
   'Voix BYAN (rappel par tour ; tao complet chargé au démarrage de session) :',
@@ -88,6 +89,13 @@ function withSlipReminder(baseContext, hits) {
   return reminder ? `${baseContext}\n${reminder}` : baseContext;
 }
 
+// Append the agent-gate reminder (F4) when the previous turn did a task directly
+// without proposing an agent. Pure; the fs read + clear stays in require.main.
+function withGateReminder(baseContext, slip) {
+  const reminder = gate.formatReminder(slip);
+  return reminder ? `${baseContext}\n${reminder}` : baseContext;
+}
+
 if (require.main === module) {
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const every = refreshEvery();
@@ -99,11 +107,16 @@ if (require.main === module) {
   // the flag (one-shot). Read/clear here, formatting stays pure in withSlipReminder.
   const slipHits = pl.readSlip(projectDir);
   if (slipHits && slipHits.length) pl.clearSlip(projectDir);
+  // Forward net #2 (F4): agent entry-gate slip. Read + clear one-shot.
+  const gateSlip = gate.readSlip(projectDir);
+  if (gateSlip) gate.clearSlip(projectDir);
+  let ctx = withSlipReminder(additionalContext, slipHits);
+  ctx = withGateReminder(ctx, gateSlip);
   process.stdout.write(
     JSON.stringify({
       hookSpecificOutput: {
         hookEventName: 'UserPromptSubmit',
-        additionalContext: withSlipReminder(additionalContext, slipHits),
+        additionalContext: ctx,
       },
     })
   );
@@ -117,5 +130,6 @@ module.exports = {
   writeTurn,
   decideAnchor,
   withSlipReminder,
+  withGateReminder,
   DEFAULT_REFRESH_EVERY,
 };

package/install/templates/.claude/hooks/lib/agent-gate.js

@@ -0,0 +1,127 @@
+'use strict';
+
+// F4 core — the reactive net for the mandatory agent entry gate.
+//
+// BYAN's philosophy: every non-conversational task passes through Hermes+BYAN
+// PROPOSING a suited agent (or an interview to create one), validated by the
+// user, BEFORE any work. No pre-display hook exists, so this net is post-hoc: at
+// end of turn it detects a task done DIRECTLY (files written) without any agent
+// proposal and without an active FD cycle, writes a one-turn flag, and the
+// next-turn reminder surfaces it. Non-blocking by design (the user asked to
+// "signal", not to trap the turn) — the correction lands on the next turn.
+//
+// Pure: assessTurn + the marker/write detectors take plain inputs. The flag I/O
+// is isolated. The hook shell feeds it transcript + fd-state signals.
+
+const fs = require('fs');
+const path = require('path');
+
+// Text signals that the entry gate WAS engaged this turn (an agent was proposed,
+// an FD phase is being narrated, a specialist was addressed, or the interview /
+// no-fit path was surfaced). Any of these means "not a silent direct-do".
+const PROPOSAL_MARKERS = [
+  '[fd:', '@hermes', 'agent adapte', 'aucun agent', 'je propose', 'proposition d\'agent',
+  'interview', 'byan-hermes-dispatch', 'dispatch d\'agent', 'quel agent',
+];
+
+// Tool names that count as "did real work on the repo" this turn.
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+
+function hasProposalMarker(text) {
+  const t = String(text == null ? '' : text).toLowerCase();
+  return PROPOSAL_MARKERS.some((m) => t.includes(m));
+}
+
+// hasWriteActivity(messages) — true if any recent assistant message carried a
+// tool_use block that writes to the repo. `messages` is an array of
+// { role, content } where content is a string or a block array.
+function hasWriteActivity(messages) {
+  if (!Array.isArray(messages)) return false;
+  for (const m of messages) {
+    if (!m || m.role !== 'assistant' || !Array.isArray(m.content)) continue;
+    for (const block of m.content) {
+      if (block && block.type === 'tool_use' && WRITE_TOOLS.has(block.name)) return true;
+    }
+  }
+  return false;
+}
+
+// assessTurn — the decision. A slip is a task done directly (files written) with
+// no agent proposal AND no active FD cycle. When an FD is engaged, the gate is
+// already in play (DISPATCH is part of it), so it is never a slip.
+function assessTurn({ wroteFiles = false, proposedAgent = false, fdActive = false } = {}) {
+  const slip = Boolean(wroteFiles && !proposedAgent && !fdActive);
+  return {
+    slip,
+    reason: slip
+      ? 'files written directly without an agent proposal and no active FD cycle'
+      : 'ok',
+  };
+}
+
+// --- slip flag (isolated I/O, mirrors the plain-language forward net) ------
+
+function slipPath(projectDir) {
+  return path.join(projectDir, '_byan-output', '.agent-gate-slip.json');
+}
+
+function writeSlip(projectDir, detail) {
+  try {
+    const p = slipPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ detail: String(detail || '') }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readSlip(projectDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(slipPath(projectDir), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function clearSlip(projectDir) {
+  try { fs.rmSync(slipPath(projectDir), { force: true }); } catch { /* never block */ }
+}
+
+// formatReminder — the plain-French note injected next turn. Empty when no slip.
+function formatReminder(slip) {
+  if (!slip) return '';
+  return [
+    'Rappel dispatch (porte d\'entree BYAN) : au dernier tour une tache a ete',
+    'traitee en direct sans proposer d\'agent adapte. La base de BYAN, c\'est de',
+    'passer par Hermes : proposer l\'agent qui colle (ou une interview pour en',
+    'creer un), l\'utilisateur valide, PUIS on lance le travail. Applique-le ce tour-ci.',
+  ].join(' ');
+}
+
+// fdIsActive(projectDir) — reads _byan-output/fd-state.json ; active means a live
+// phase (not COMPLETED / ABORTED / absent). Read-only, best-effort.
+function fdIsActive(projectDir) {
+  try {
+    const state = JSON.parse(fs.readFileSync(path.join(projectDir, '_byan-output', 'fd-state.json'), 'utf8'));
+    const phase = state && state.phase;
+    return Boolean(phase) && phase !== 'COMPLETED' && phase !== 'ABORTED';
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  PROPOSAL_MARKERS,
+  WRITE_TOOLS,
+  hasProposalMarker,
+  hasWriteActivity,
+  assessTurn,
+  slipPath,
+  writeSlip,
+  readSlip,
+  clearSlip,
+  formatReminder,
+  fdIsActive,
+};

package/install/templates/.claude/rules/agent-entry-gate.md

@@ -0,0 +1,83 @@
+# Porte d'entree BYAN — dispatch d'agent obligatoire (match-or-create)
+
+> La base de BYAN : mettre la personne sur des rails pour toute tache ou projet.
+> Avant de faire le travail, on regarde quel agent specialiste colle au besoin.
+> Un agent adapte existe -> on le propose et on lance son workflow. Aucun ne
+> colle -> on interviewe pour cadrer le besoin, on cherche les competences du
+> metier, et on cree l'agent sur mesure. Le dispatch d'agent n'est pas une
+> option : c'est l'entree de tout.
+
+## Le principe
+
+Il y a DEUX dispatch, ne pas les confondre :
+- **Dispatch d'agent (Hermes)** — QUI fait le travail : quel agent BYAN, ou on en
+  cree un. C'est le rail decrit ici.
+- **Dispatch de runtime** — une fois l'agent choisi, sur quel moteur (Codex ou
+  Claude) + modele + effort. C'est la couche du dessous (voir
+  `docs/intelligent-dispatch.md`).
+
+Cette regle porte sur le premier : la porte d'entree.
+
+## Le flux (sur toute tache non-conversationnelle)
+
+```
+demande utilisateur
+  -> BYAN + Hermes evaluent quel agent specialiste colle (matcher F1)
+       AGENT ADAPTE TROUVE
+         -> BYAN le PROPOSE ("je pars sur @dev, tu valides ?")
+         -> l'utilisateur valide (double validation IA + humain)
+         -> on lance le workflow de cet agent (+ dispatch runtime)
+       AUCUN AGENT ADAPTE
+         -> BYAN le dit et propose une interview
+         -> interview : cadrer precisement le besoin de l'agent
+         -> recherche web : competences + bonnes pratiques du metier vise
+         -> creation de l'agent sur mesure
+         -> on lance le workflow
+```
+
+Le declencheur de l'interview, c'est **l'absence d'un agent adapte**, pas la
+taille de la tache. "code un script" -> l'agent dev existe -> workflow direct,
+zero ceremonie. "il me faut un agent art moderne" -> aucun agent -> interview +
+recherche + creation.
+
+## La proportion (pour que le rail ne devienne pas un mur)
+
+Le rail impose de **verifier** la pertinence d'un agent a chaque tache — pas de
+declencher une interview a chaque fois. Agent existant qui colle = on route
+direct. Besoin flou ou aucun agent adapte = la ou l'interview + creation se
+declenchent. La ceremonie est proportionnee au manque, pas systematique.
+
+## La double validation
+
+Le matcher (F1, `_byan/mcp/byan-mcp-server/lib/agent-matcher.js`) est un
+pre-tri deterministe : il classe les candidats du roster et rend un verdict
+{fit | no-fit}. Il PROPOSE, il ne tranche pas seul. BYAN presente la proposition
+en clair ; l'utilisateur valide. IA propose, humain confirme.
+
+## La creation d'agent enrichie (chemin no-fit)
+
+Quand aucun agent ne colle, la creation passe par :
+1. **Interview** — cadrer le besoin (ce que l'agent doit faire, ses lignes
+   rouges, son perimetre). Flux INT / agent-builder existant.
+2. **Recherche web** — avant de generer l'agent, chercher les competences reelles
+   et les bonnes pratiques du metier vise (ex : pour un agent "art moderne",
+   courants, techniques, references). C'est ce qui evite l'agent-zombie generique.
+3. **Generation** — generer l'agent sur mesure a partir de l'interview + la
+   recherche.
+4. **Workflow** — lancer le travail avec le nouvel agent.
+
+## L'enforcement (honnete sur son plafond)
+
+Aucun controle ne s'execute AVANT que la reponse s'affiche (pas de hook de
+pre-affichage cote Claude Code). Le rail tient donc par deux forces, pas par un
+mur beton au premier tour :
+1. **Doctrine** — cette regle + le skill byan-byan + `CLAUDE.md` font que BYAN
+   lance la proposition d'agent d'office.
+2. **Filet reactif** — `.claude/hooks/agent-gate-check.js` (Stop) repere une tache
+   traitee en direct (fichiers ecrits) sans proposition d'agent et hors cycle FD,
+   pose un drapeau, et le rappel du tour suivant le signale en clair. Non
+   bloquant : la correction est portee au tour d'apres (meme methode que les
+   autres filets BYAN). Coeur teste : `.claude/hooks/lib/agent-gate.js`.
+
+Quand un cycle FD est deja engage, la porte est deja en jeu (la phase DISPATCH en
+fait partie) : le filet ne se declenche pas.

package/install/templates/.claude/settings.json

@@ -86,6 +86,10 @@
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/plain-language-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
           },
+          {
+            "type": "command",
+            "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/agent-gate-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
+          },
           {
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/drain-advisory.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""

package/install/templates/.claude/skills/byan-byan/SKILL.md

@@ -7,6 +7,20 @@ description: BYAN — Builder of YAN. Core meta-agent that owns the Feature Deve
 
 You are BYAN when this skill is active. You own the eight-phase Feature Development workflow and you enforce it mechanically. Every new feature the user asks for goes through all phases in order. No skipping. No implicit transitions. The cycle includes a REFACTOR loop back to BUILD when VALIDATE fails.
 
+## 0. Entry gate — agent dispatch first (match-or-create)
+
+Before doing any non-conversational task, run the mandatory agent entry gate:
+BYAN + Hermes evaluate which specialist agent fits the need (the matcher in
+`_byan/mcp/byan-mcp-server/lib/agent-matcher.js` pre-ranks the roster), and you
+PROPOSE it to the user, who validates (double validation IA + human). A suited
+agent -> launch its workflow (+ runtime dispatch). No suited agent -> propose an
+interview to frame the need, do web research on the trade's competencies + best
+practices, create the tailored agent, then launch the workflow. The interview is
+triggered by the ABSENCE of a suited agent, not by task size — a fit routes
+directly, no ceremony. Do NOT do a task inline without this proposal. Full
+doctrine + the reactive net (`agent-gate-check.js`): see
+@.claude/rules/agent-entry-gate.md
+
 ## 1. Activation triggers
 
 Invoke this protocol when the user :

package/install/templates/.claude/workflows/intelligent-dispatch.js

@@ -0,0 +1,68 @@
+export const meta = {
+  name: 'intelligent-dispatch',
+  description: 'Route a task to Codex or Claude (pre-decided by the F1 router), then run architect -> dev -> verify with the dev turn on the routed runtime.',
+  whenToUse: 'When you have a single task already routed by the dispatch brain (runtime/model/effort in args) and want the native architect<->dev<->verify pipeline. The Codex-inclusive multi-round loop lives in the dispatch-orchestrator lib on the main thread; this script is the native launch facade for one routed task.',
+  phases: [
+    { title: 'Design', detail: 'architect frames the change (Claude)' },
+    { title: 'Implement', detail: 'dev turn on the routed runtime (Codex via codex exec, or Claude)' },
+    { title: 'Verify', detail: 'a Claude reviewer checks the result (never Codex)' },
+  ],
+};
+
+// A native workflow script has NO imports and NO filesystem of its own, so it
+// cannot require the dispatch-router (F1) or the blackboard (F3). The doctrine's
+// hybrid pattern applies: routing is decided OUTSIDE (the main-thread skill calls
+// the F1 router / byan_dispatch) and handed in via `args`. This script only runs
+// the exchange for ONE already-routed task. The dev agent() leaf holds the tools
+// (Bash), so IT is what actually invokes `codex exec` and applies the diff — the
+// script never shells out itself.
+//
+// args shape: { brief, runtime: 'codex'|'claude', effort: 'low'|'medium'|'high',
+//               model?: string, codexModel?: string, paths?: string[] }
+
+const task = (args && typeof args === 'object') ? args : {};
+const brief = task.brief || 'No brief provided.';
+const runtime = task.runtime === 'codex' ? 'codex' : 'claude';
+const effort = ['low', 'medium', 'high'].includes(task.effort) ? task.effort : 'medium';
+const codexModel = task.codexModel || 'gpt-5.4';
+
+phase('Design');
+// The architect framing is the load-bearing reasoning step of the whole loop, so
+// it opts to the session model (the 'deep-' prefix = frontier analysis, no
+// downgrade) rather than the sonnet analysis default. On an Opus session the
+// design is framed by Opus; a lighter session inherits its own model.
+const design = await agent(
+  `You are the architect (Claude). Frame this task for a delegated dev.\n` +
+  `Give: the intended change, the interface/contract to honour, and the acceptance check.\n` +
+  `Keep it tight and unambiguous.\n\nTask:\n${brief}`,
+  { label: 'deep-design-architecture', phase: 'Design' }
+);
+
+phase('Implement');
+// Implementation leaf -> deep (inherit session model). The prompt BRANCHES on the
+// routed runtime: for Codex, the leaf runs `codex exec` read-only to get a diff
+// and applies it (Codex never writes; Claude applies). For Claude, it implements
+// directly. Routing was decided upstream by F1 — this leaf just executes it.
+const devPrompt = runtime === 'codex'
+  ? `You are the dev, delegating to Codex. Run Codex non-interactively to get a unified diff, then apply it.\n` +
+    `Command (adjust the task text): \`codex exec -c model="${codexModel}" -c model_reasoning_effort="${effort}" -c sandbox_permissions=["disk-full-read-access"] "<<diff-only instruction + the task>>"\`\n` +
+    `Extract the diff, apply it with \`git apply\`, and report what changed. Codex must NOT write files itself (read-only sandbox); YOU apply the diff.\n` +
+    `If Codex is unavailable or errors, say so plainly and implement the change yourself on Claude (the fallback).\n\n` +
+    `Design from the architect:\n${design}\n\nTask:\n${brief}`
+  : `You are the dev (Claude). Implement the change per the architect's design.\n` +
+    `Follow the interface exactly. Write the code and the tests.\n\n` +
+    `Design from the architect:\n${design}\n\nTask:\n${brief}`;
+const work = await agent(devPrompt, { label: 'implement-task', phase: 'Implement' });
+
+phase('Verify');
+// Verification leaf -> deep, and ALWAYS Claude (the red line: a runtime never
+// grades its own work). Never routed to Codex regardless of the dev runtime.
+const verdict = await agent(
+  `You are the reviewer (Claude, NOT the dev). Verify the implemented change against the architect's acceptance check.\n` +
+  `Report PASS or FAIL with the exact reasons. Do not fix — only judge.\n\n` +
+  `Design + acceptance:\n${design}\n\nDev report:\n${work}`,
+  { label: 'verify-result', phase: 'Verify' }
+);
+
+log(`intelligent-dispatch done: runtime=${runtime} effort=${effort}`);
+return { runtime, effort, design, work, verdict };