kenaz 0.0.0-stage → 0.3.2

package/core/dev/archive/ansuz/specs/active-inference-formation.yaml

@@ -0,0 +1,453 @@
+# Factorised Active Inference for Formation Selection
+# Design Specification — CP-1aba (TASK_972)
+#
+# Reference: arXiv:2411.07362 (Factorised Active Inference, AAMAS 2025)
+# Key insight: each agent maintains a factorized generative model with beliefs
+# about OTHER agents' hidden states. Applied here to Formation dispatch:
+# the system maintains Dirichlet beliefs about each formation's competence
+# per task type, and selects formations by minimizing Expected Free Energy.
+#
+# Compatible with existing EFE engine (efe.rs) additive structure:
+#   EFE(s) = G_risk + G_ambiguity + G_novelty  (symbol-level)
+#   EFE(f) = G_pragmatic + G_epistemic          (formation-level, this spec)
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Section 1: Overview
+# ═══════════════════════════════════════════════════════════════════════════
+
+overview:
+  title: "Factorised Active Inference for Formation Selection"
+  version: "0.1.0"
+  status: "draft"
+  author: "TASK_972"
+  reference: "arXiv:2411.07362"
+
+  summary: |
+    Currently, Formation dispatch uses a static heuristic to select formation
+    type (unit > solo > squad > legion) based on task complexity and explicit
+    user overrides. This spec introduces a Bayesian learning layer that
+    maintains per-formation, per-task-type beliefs about completion success,
+    and uses Expected Free Energy (EFE) to select the optimal formation.
+
+    The system is factorized: each formation type (unit, solo, squad, legion)
+    is modeled as an independent factor with its own Dirichlet-distributed
+    belief over success/failure for each task type. This mirrors the AAMAS 2025
+    paper's approach where each agent maintains beliefs about other agents'
+    hidden states, but applied at the formation level.
+
+  goals:
+    - Learn which formations work best for which task types from dispatch history
+    - Balance exploitation (use known-good formations) with exploration (try uncertain ones)
+    - Gracefully degrade to static heuristic when insufficient data exists
+    - Integrate additively with existing EFE engine without breaking current behavior
+
+  formations:
+    - unit    # Single agent, simplest dispatch
+    - solo    # Single agent with enhanced context
+    - squad   # Multi-agent parallel with synthesis
+    - legion  # Lead agent coordinating sub-agents
+
+  task_types:
+    - synapse  # Code intelligence, graph operations
+    - ui       # Frontend/UI work
+    - backend  # Backend/API development
+    - spec     # Specification and documentation
+    - fix      # Bug fixes, incident response
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Section 2: Phase 1 — Beliefs Schema
+# ═══════════════════════════════════════════════════════════════════════════
+
+phase_1_beliefs_schema:
+  description: |
+    Dirichlet-distributed beliefs encode the system's uncertainty about each
+    formation's success probability for each task type. The Dirichlet is the
+    conjugate prior of the Categorical distribution, making Bayesian updates
+    trivial: simply increment the alpha corresponding to the observed outcome.
+
+  storage:
+    file: ".formation/specialist_beliefs.json"
+    format: "JSON"
+    backup: ".formation/specialist_beliefs.backup.json"
+    # Backup written before each update for crash recovery
+
+  schema:
+    description: |
+      Top-level keys are formation types. Each formation maps task types to
+      a Dirichlet parameter vector [alpha_success, alpha_failure].
+
+      The expected success probability is:
+        P(success | formation, task_type) = alpha_success / (alpha_success + alpha_failure)
+
+      Uncertainty decreases as alpha_sum = alpha_success + alpha_failure grows.
+
+    example:
+      unit:
+        synapse: { alpha_success: 1.0, alpha_failure: 1.0 }
+        ui:      { alpha_success: 1.0, alpha_failure: 1.0 }
+        backend: { alpha_success: 1.0, alpha_failure: 1.0 }
+        spec:    { alpha_success: 1.0, alpha_failure: 1.0 }
+        fix:     { alpha_success: 1.0, alpha_failure: 1.0 }
+      solo:
+        synapse: { alpha_success: 1.0, alpha_failure: 1.0 }
+        ui:      { alpha_success: 1.0, alpha_failure: 1.0 }
+        backend: { alpha_success: 1.0, alpha_failure: 1.0 }
+        spec:    { alpha_success: 1.0, alpha_failure: 1.0 }
+        fix:     { alpha_success: 1.0, alpha_failure: 1.0 }
+      squad:
+        synapse: { alpha_success: 1.0, alpha_failure: 1.0 }
+        ui:      { alpha_success: 1.0, alpha_failure: 1.0 }
+        backend: { alpha_success: 1.0, alpha_failure: 1.0 }
+        spec:    { alpha_success: 1.0, alpha_failure: 1.0 }
+        fix:     { alpha_success: 1.0, alpha_failure: 1.0 }
+      legion:
+        synapse: { alpha_success: 1.0, alpha_failure: 1.0 }
+        ui:      { alpha_success: 1.0, alpha_failure: 1.0 }
+        backend: { alpha_success: 1.0, alpha_failure: 1.0 }
+        spec:    { alpha_success: 1.0, alpha_failure: 1.0 }
+        fix:     { alpha_success: 1.0, alpha_failure: 1.0 }
+
+  initial_priors:
+    description: |
+      All alpha parameters start at 1.0 (uniform Dirichlet). This represents
+      maximum ignorance: P(success) = 0.5 for all formation-task combinations.
+      The system has no initial bias toward any formation.
+    alpha_success: 1.0
+    alpha_failure: 1.0
+    rationale: |
+      alpha=1 gives a uniform Beta(1,1) prior for each formation-task pair.
+      This is the least informative proper prior — equivalent to having seen
+      zero successes and zero failures, with no bias.
+
+  metadata:
+    description: "Additional tracking fields in the beliefs file"
+    fields:
+      version: "Schema version string (semver)"
+      updated_at: "ISO-8601 timestamp of last update"
+      total_dispatches: "Total observed dispatches across all formations"
+      dispatch_counts:
+        description: "Per-formation dispatch count for cold-start threshold checks"
+        example:
+          unit: 0
+          solo: 0
+          squad: 0
+          legion: 0
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Section 3: Phase 2 — EFE Computation for Formation Selection
+# ═══════════════════════════════════════════════════════════════════════════
+
+phase_2_efe_computation:
+  description: |
+    Expected Free Energy (EFE) for formation selection. Lower EFE = better.
+    The formation with minimum EFE is selected.
+
+    EFE(formation, task_type) = -G_pragmatic(f, t) - G_epistemic(f, t)
+
+    This is additive and structurally compatible with the existing symbol-level
+    EFE in efe.rs (G_risk + G_ambiguity + G_novelty), but operates at a
+    different level of abstraction (formation selection vs symbol prioritization).
+
+  components:
+    pragmatic_value:
+      symbol: "G_pragmatic(f, t)"
+      description: |
+        Expected completion probability — exploitation term.
+        Higher means the formation is more likely to succeed at this task type.
+      formula: |
+        G_pragmatic(f, t) = E[P(success | f, t)]
+                          = alpha_success / (alpha_success + alpha_failure)
+      range: "[0, 1]"
+      interpretation: |
+        When alpha_success >> alpha_failure, pragmatic value is high (near 1).
+        This drives exploitation: prefer formations with proven track records.
+
+    epistemic_value:
+      symbol: "G_epistemic(f, t)"
+      description: |
+        Information gain from choosing this formation — exploration term.
+        Higher when we are uncertain about the formation's competence.
+      formula: |
+        G_epistemic(f, t) = H[Dir(alpha)] - E[H[Cat(theta)]]
+
+        Simplified (for Dirichlet with 2 categories, i.e., Beta distribution):
+        G_epistemic(f, t) = 1 / (alpha_success + alpha_failure + 1)
+      rationale: |
+        The exact mutual information between parameters and outcomes for a
+        Beta-Bernoulli model. As total observations grow (alpha_sum increases),
+        epistemic value decreases — we learn less from additional trials.
+        When alpha_sum is small (few observations), epistemic value is high,
+        driving exploration of uncertain formations.
+      range: "(0, 1)"
+      interpretation: |
+        New formations (alpha_sum ≈ 2) have epistemic ≈ 0.33.
+        Well-observed formations (alpha_sum ≈ 50) have epistemic ≈ 0.02.
+        This naturally implements an explore-exploit tradeoff.
+
+  selection_formula:
+    description: |
+      Combine pragmatic and epistemic values with a temperature-controlled
+      softmax to produce a formation selection policy.
+
+    efe_score: |
+      EFE(f, t) = w_pragmatic * G_pragmatic(f, t) + w_epistemic * G_epistemic(f, t)
+
+    policy: |
+      pi(f | t) = softmax(EFE(f, t) / temperature)
+               = exp(EFE(f, t) / T) / sum_f'(exp(EFE(f', t) / T))
+
+    selection: |
+      selected_formation = argmax_f pi(f | t)
+
+      Alternatively, sample from pi(f | t) to allow stochastic exploration.
+      Recommendation: use argmax in production, sample during cold-start phase.
+
+  weights:
+    w_pragmatic:
+      default: 1.0
+      description: "Weight for exploitation (pragmatic value)"
+    w_epistemic:
+      default: 0.5
+      description: |
+        Weight for exploration (epistemic value). Set < 1.0 to favor
+        exploitation over exploration. Tunable based on operational needs.
+    temperature:
+      default: 1.0
+      description: |
+        Softmax temperature. Higher = more uniform (exploratory).
+        Lower = more peaked (exploitative). Adaptive temperature from
+        efe.rs could be reused here if health signals are available.
+
+  compatibility_with_efe_rs:
+    description: |
+      The existing efe.rs operates at symbol-level (which symbols to prioritize).
+      This formation-level EFE operates at dispatch-level (which formation to use).
+      They are complementary and do not conflict:
+
+      1. Formation EFE selects the formation type for a dispatch
+      2. Symbol EFE (efe.rs) prioritizes symbols within that dispatch
+
+      Both use additive free energy decomposition. The formation EFE weights
+      (w_pragmatic, w_epistemic) could eventually be learned by the same
+      weight-learning mechanism in efe.rs (TASK_960), but this is out of scope.
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Section 4: Phase 3 — Posterior Update
+# ═══════════════════════════════════════════════════════════════════════════
+
+phase_3_posterior_update:
+  description: |
+    After each dispatch completes, update the Dirichlet beliefs based on the
+    observed outcome. This is the Bayesian learning loop.
+
+  trigger: "post-complete hook (post-complete.js) after dispatch finishes"
+
+  outcome_classification:
+    description: |
+      Map dispatch results to binary success/failure for belief updates.
+    rules:
+      - condition: "task moved to done/ by task-api.js complete"
+        outcome: "success"
+      - condition: "task moved to blocked/ or agent exits with error"
+        outcome: "failure"
+      - condition: "task moved to blocked/ but later unblocked and completed"
+        outcome: "success (delayed — update on final completion only)"
+      - condition: "dispatch timeout or agent crash"
+        outcome: "failure"
+
+  update_rule:
+    description: |
+      Conjugate Bayesian update for Dirichlet-Bernoulli model.
+      This is exact — no approximation needed.
+    on_success: |
+      alpha_success[formation][task_type] += 1.0
+    on_failure: |
+      alpha_failure[formation][task_type] += 1.0
+    atomicity: |
+      Read beliefs file → update in memory → write backup → write beliefs file.
+      Use file locking or atomic rename to prevent corruption from concurrent
+      dispatches (squad/legion run multiple agents in parallel).
+
+  decay:
+    description: |
+      Optional: exponential decay to make beliefs more responsive to recent
+      outcomes. Without decay, early observations dominate forever.
+    enabled: false
+    mechanism: |
+      Before each update, decay all alphas toward the prior:
+        alpha = prior + decay_rate * (alpha - prior)
+      where prior = 1.0 and decay_rate ∈ (0, 1).
+    decay_rate: 0.99
+    rationale: |
+      Decay is disabled by default to maximize sample efficiency during
+      early learning. Enable after sufficient data (e.g., 100+ dispatches)
+      if the system needs to adapt to changing team composition or codebase.
+
+  validation:
+    description: "Sanity checks after each update"
+    rules:
+      - "alpha_success >= 1.0 (never below prior)"
+      - "alpha_failure >= 1.0 (never below prior)"
+      - "beliefs file is valid JSON after write"
+      - "backup file matches pre-update state"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Section 5: Cold Start Handling
+# ═══════════════════════════════════════════════════════════════════════════
+
+cold_start_handling:
+  description: |
+    The system needs sufficient observations before beliefs can meaningfully
+    influence formation selection. Below the threshold, the existing static
+    heuristic is used unchanged.
+
+  threshold:
+    minimum_dispatches: 10
+    scope: "global (total dispatches across all formations)"
+    rationale: |
+      With fewer than 10 dispatches, the Dirichlet posteriors are dominated
+      by the uniform prior (alpha=1). The expected probabilities hover near
+      0.5 regardless of outcomes. 10 dispatches provides enough signal for
+      at least some formation-task pairs to differentiate.
+
+  behavior_below_threshold:
+    description: |
+      Use the existing static heuristic without modification.
+      Beliefs are still updated (observations are still recorded), but
+      the EFE selection is not used for formation choice.
+    static_heuristic:
+      description: |
+        Current formation selection logic in dispatch.js:
+        - Default: unit (simplest, lowest overhead)
+        - Explicit --formation flag overrides everything
+        - Skill definitions may specify preferred formation
+        - Complexity-based: unit > solo > squad > legion
+      priority_order:
+        - unit     # Default for most tasks
+        - solo     # For tasks needing enhanced context
+        - squad    # For parallelizable multi-file tasks
+        - legion   # For large coordinated efforts
+
+  transition:
+    description: |
+      When total dispatches crosses the threshold, begin blending EFE
+      selection with the static heuristic using a linear ramp.
+    blend_formula: |
+      effective_weight = min(1.0, (total_dispatches - threshold) / ramp_length)
+
+      If effective_weight < 1.0:
+        score(f) = (1 - effective_weight) * static_score(f) + effective_weight * EFE(f, t)
+      Else:
+        score(f) = EFE(f, t)
+    ramp_length: 20
+    rationale: |
+      Linear ramp over 20 dispatches (from dispatch 10 to 30) provides a
+      smooth transition from static heuristic to learned beliefs. This
+      avoids sudden behavior changes when crossing the threshold.
+    static_score:
+      description: |
+        Numerical encoding of the static priority order for blending:
+      values:
+        unit: 1.0
+        solo: 0.75
+        squad: 0.5
+        legion: 0.25
+
+  override:
+    description: |
+      The --formation flag in dispatch.js ALWAYS takes precedence over
+      EFE selection, regardless of cold-start state or beliefs. This is
+      the user's escape hatch for manual control.
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Section 6: Integration Points
+# ═══════════════════════════════════════════════════════════════════════════
+
+integration_points:
+  description: |
+    Where this system connects to existing Formation infrastructure.
+
+  dispatch_js:
+    file: ".formation/tools/dispatch.js"
+    change: |
+      In the dispatch() function (around line 229), after loading the skill
+      definition and before executing the formation, insert a formation
+      selection step:
+
+      1. If --formation flag is set → use it (no change)
+      2. Else → call selectFormation(taskType, beliefs) which:
+         a. Loads beliefs from .formation/specialist_beliefs.json
+         b. Checks cold-start threshold
+         c. If below threshold: return static heuristic result
+         d. If above threshold: compute EFE for each formation, return argmax
+    new_function: "selectFormation(taskType, beliefsPath)"
+    location: "New file: .formation/tools/formation-efe.js"
+
+  post_complete_js:
+    file: ".formation/tools/post-complete.js"
+    change: |
+      After task status is finalized (moved to done/ or blocked/), call
+      updateBeliefs(formation, taskType, outcome) to perform the Bayesian
+      posterior update.
+    new_function: "updateBeliefs(formation, taskType, outcome)"
+    location: "Same file: .formation/tools/formation-efe.js"
+
+  beliefs_file:
+    path: ".formation/specialist_beliefs.json"
+    lifecycle:
+      creation: "Auto-created with uniform priors on first dispatch after implementation"
+      updates: "After every dispatch completion via post-complete.js"
+      backup: "Before each update to .formation/specialist_beliefs.backup.json"
+      gitignore: "Add to .gitignore — beliefs are local/machine-specific"
+
+  task_type_detection:
+    description: |
+      Determine the task_type for a given dispatch. Used by both selectFormation
+      and updateBeliefs.
+    strategy: |
+      1. If task YAML has explicit `type` or `category` field → use it
+      2. If task has `role` field (e.g., "backend", "frontend") → map to task_type
+      3. If skill name contains keywords → infer (e.g., skill=synapse → "synapse")
+      4. Fallback → "backend" (most common task type)
+    mapping:
+      role_to_type:
+        backend: "backend"
+        frontend: "ui"
+        design: "ui"
+        synapse: "synapse"
+        spec: "spec"
+        fix: "fix"
+        sre: "backend"
+
+  monitoring:
+    description: |
+      Observability for the belief system to diagnose selection quality.
+    log_events:
+      - event: "formation_selected"
+        data: "{ taskType, selectedFormation, efeScores, belowThreshold }"
+      - event: "beliefs_updated"
+        data: "{ formation, taskType, outcome, newAlphas }"
+    log_location: ".formation/logs/ (existing log infrastructure)"
+
+  future_extensions:
+    description: |
+      Out of scope for this spec, but natural next steps:
+    items:
+      - title: "Per-specialist beliefs"
+        description: |
+          Extend from formation-level to specialist-level beliefs.
+          E.g., Ansuz might be better at spec tasks than backend tasks.
+          Requires specialist identity tracking in dispatch.
+      - title: "Multi-dimensional outcomes"
+        description: |
+          Replace binary success/failure with graded outcomes
+          (quality score, time-to-completion, retry count).
+          Requires Dirichlet over K>2 categories.
+      - title: "Cross-project transfer"
+        description: |
+          Share beliefs across projects with similar characteristics.
+          Requires a project similarity metric.
+      - title: "EFE weight learning"
+        description: |
+          Use the weight learning mechanism from efe.rs (TASK_960) to
+          automatically tune w_pragmatic and w_epistemic.

package/core/dev/archive/ansuz/specs/brief_TASK_1228_userpromptsubmit.yaml

@@ -0,0 +1,191 @@
+brief_version: "1.0"
+task_id: TASK_1228
+title: "Implement Bifrost UserPromptSubmit hook parity for per-turn context injection"
+role: backend
+produced_by: TASK_1234
+
+# ─────────────────────────────────────────────────────────────────
+# CGDD RECONCILIATION (read this first)
+# ─────────────────────────────────────────────────────────────────
+cgdd_note: >
+  CGDD_hook_lifecycle.js (produced by TASK_1232) labels phantom contracts by
+  task number, but those numbers were written before backlog was finalized.
+  CGDD TASK_1228 = SessionStart, CGDD TASK_1229 = UserPromptSubmit — these are
+  reversed from what the actual backlog says.
+  FOLLOW THIS BRIEF, NOT THE CGDD TASK NUMBER LABELS.
+  The phantom contract names (session_dispatchBifrostHook,
+  session_normalizeUserPromptSubmit) are correct — only the task number labels
+  inside CGDD are wrong.
+
+cgdd_source: ".formation/bifrost/CGDD_hook_lifecycle.js"
+lifecycle_contract_source: ".specialist/tools/task-bridge.js (BIFROST_HOOK_LIFECYCLE.UserPromptSubmit)"
+
+# ─────────────────────────────────────────────────────────────────
+# OBJECTIVE
+# ─────────────────────────────────────────────────────────────────
+objective: >
+  Add UserPromptSubmit hook emission to session.js so Codex specialists receive
+  per-turn context injection. This requires: (1) creating the dispatchBifrostHook()
+  utility in session.js (shared by TASK_1230), (2) creating normalizeUserPromptSubmit(),
+  (3) wiring the call site before relay.stdin.write(prompt).
+
+# ─────────────────────────────────────────────────────────────────
+# OWNED FILES — only touch these
+# ─────────────────────────────────────────────────────────────────
+owned_files:
+  primary: ".formation/bifrost/session.js"
+  read_for_contract: ".specialist/tools/task-bridge.js"
+  read_for_cgdd: ".formation/bifrost/CGDD_hook_lifecycle.js"
+
+# ─────────────────────────────────────────────────────────────────
+# NON-GOALS
+# ─────────────────────────────────────────────────────────────────
+non_goals:
+  - Do NOT implement SessionStart or Stop dispatch (TASK_1230 owns those)
+  - Do NOT modify relay.js (TASK_1229 owns PreToolUse/PostToolUse there)
+  - Do NOT modify task-bridge.js (handleHookEvent already handles UserPromptSubmit)
+  - Do NOT redefine the payload schema (it is frozen in BIFROST_HOOK_LIFECYCLE.UserPromptSubmit)
+  - Do NOT change the relay spawn command or its stdio settings (TASK_1230 owns that)
+
+# ─────────────────────────────────────────────────────────────────
+# WHAT TO CREATE IN session.js
+# ─────────────────────────────────────────────────────────────────
+functions_to_create:
+  - name: dispatchBifrostHook
+    signature: "function dispatchBifrostHook(eventName, payload)"
+    placement: "add near top of file, after SIGNAL_PATH constant (around line 41)"
+    require_statement: "const taskBridge = require(path.resolve(__dirname, '../..', '.specialist/tools/task-bridge.js'));"
+    body_skeleton: |
+      function dispatchBifrostHook(eventName, payload) {
+        try {
+          const taskBridge = require(path.resolve(__dirname, '../..', '.specialist/tools/task-bridge.js'));
+          taskBridge.handleHookEvent(payload);
+        } catch (err) {
+          console.error(`[bifrost] hook dispatch failed (${eventName}): ${err.message}`);
+        }
+      }
+    error_policy: "catch + console.error — must never throw to caller"
+    shared_with: "TASK_1230 (SessionStart/Stop will reuse this same function)"
+
+  - name: normalizeUserPromptSubmit
+    signature: "function normalizeUserPromptSubmit(prompt)"
+    placement: "add after dispatchBifrostHook()"
+    returns: |
+      {
+        hook_event_name: 'UserPromptSubmit',
+        user_prompt:     prompt,
+        prompt:          prompt,      // required alias — maybeEmitReminder() reads payload.prompt
+        text:            prompt,      // secondary alias
+        specialist:      SPECIALIST,
+        session_id:      RESUME_ID,   // null for new sessions
+        cwd:             CWD,
+        project_path:    path.resolve(CWD),
+        submitted_at:    new Date().toISOString(),
+      }
+    compat_critical: "prompt + user_prompt + text aliases are ALL required — maybeEmitReminder() in task-bridge.js reads payload.prompt"
+
+# ─────────────────────────────────────────────────────────────────
+# WIRING CALL SITE
+# ─────────────────────────────────────────────────────────────────
+call_site:
+  location: "session.js main execution block (bottom of file, lines ~246-260)"
+  current_code: |
+    if (RESUME_ID) {
+      writeSignal();
+      const userMsg = args._rest || 'Continue the session.';
+      launchRelay(userMsg);
+    } else {
+      const kernelPrompt = assemblePrompt();
+      const prompt = renderCodexAntiDrift() + kernelPrompt;
+      writeSignal();
+      launchRelay(prompt);
+    }
+  target_code: |
+    if (RESUME_ID) {
+      writeSignal();
+      const userMsg = args._rest || 'Continue the session.';
+      dispatchBifrostHook('UserPromptSubmit', normalizeUserPromptSubmit(userMsg));
+      launchRelay(userMsg);
+    } else {
+      const kernelPrompt = assemblePrompt();
+      const prompt = renderCodexAntiDrift() + kernelPrompt;
+      writeSignal();
+      dispatchBifrostHook('UserPromptSubmit', normalizeUserPromptSubmit(prompt));
+      launchRelay(prompt);
+    }
+  ordering_invariant: "UserPromptSubmit MUST fire after writeSignal() and BEFORE relay.stdin.write(prompt) (which launchRelay does internally)"
+
+# ─────────────────────────────────────────────────────────────────
+# INVARIANTS
+# ─────────────────────────────────────────────────────────────────
+invariants:
+  - "dispatchBifrostHook() must never throw — always wrap body in try/catch"
+  - "Exactly ONE UserPromptSubmit fires per session.js invocation"
+  - "payload.prompt must always be set (maybeEmitReminder depends on it)"
+  - "hook_event_name literal must be 'UserPromptSubmit' (handleHookEvent routes on this)"
+  - "project_path must always be set — use path.resolve(CWD) as minimum fallback"
+
+# ─────────────────────────────────────────────────────────────────
+# FORBIDDEN SHORTCUTS
+# ─────────────────────────────────────────────────────────────────
+forbidden:
+  - "Do NOT call dispatchBifrostHook via stdin pipe or child_process.exec — it must be a direct require() call"
+  - "Do NOT omit the prompt alias from the payload — the existing maybeEmitReminder() consumer reads payload.prompt, not payload.user_prompt"
+  - "Do NOT call dispatchBifrostHook inside launchRelay() — keep it at the call site boundary"
+  - "Do NOT change the session.js module structure or move existing constants"
+
+# ─────────────────────────────────────────────────────────────────
+# VERIFICATION COMMANDS (Phase 9 style)
+# ─────────────────────────────────────────────────────────────────
+verification:
+  grep_checks:
+    - desc: "dispatchBifrostHook function exists in session.js"
+      cmd: "grep -n 'function dispatchBifrostHook' .formation/bifrost/session.js"
+      expected: "one match at definition line"
+
+    - desc: "normalizeUserPromptSubmit function exists"
+      cmd: "grep -n 'function normalizeUserPromptSubmit' .formation/bifrost/session.js"
+      expected: "one match"
+
+    - desc: "UserPromptSubmit wired before launchRelay"
+      cmd: "grep -n 'UserPromptSubmit\\|launchRelay' .formation/bifrost/session.js"
+      expected: "dispatchBifrostHook('UserPromptSubmit'...) appears BEFORE launchRelay() on both code paths"
+
+    - desc: "payload.prompt alias present in normalizeUserPromptSubmit"
+      cmd: "grep -n 'prompt:.*prompt' .formation/bifrost/session.js"
+      expected: "at least one match inside normalizeUserPromptSubmit body"
+
+    - desc: "task-bridge require path is correct"
+      cmd: "grep -n 'task-bridge' .formation/bifrost/session.js"
+      expected: "path.resolve(__dirname, '../..', '.specialist/tools/task-bridge.js')"
+
+  integration_check:
+    desc: "Dry-run hook dispatch without Codex"
+    cmd: |
+      node -e "
+        process.env.NODE_ENV='test';
+        const path = require('path');
+        const tb = require('./.specialist/tools/task-bridge');
+        const payload = {
+          hook_event_name: 'UserPromptSubmit',
+          user_prompt: 'test prompt',
+          prompt: 'test prompt',
+          text: 'test prompt',
+          specialist: 'TestSpec',
+          session_id: null,
+          cwd: process.cwd(),
+          project_path: process.cwd(),
+          submitted_at: new Date().toISOString()
+        };
+        tb.handleHookEvent(payload).then(r => console.log('OK:', r)).catch(e => console.error('FAIL:', e.message));
+      "
+    expected: "OK: null (maybeEmitReminder fires but returns null in test context)"
+
+# ─────────────────────────────────────────────────────────────────
+# PREDECESSOR / SUCCESSOR
+# ─────────────────────────────────────────────────────────────────
+ordering:
+  this_task_creates: "dispatchBifrostHook() in session.js — TASK_1230 MUST NOT recreate it"
+  prerequisite_for: "TASK_1230 (Stop/SessionStart dispatch reuses dispatchBifrostHook)"
+  can_run_in_parallel_with: "TASK_1229 (relay.js only — no file overlap)"
+  must_complete_before: "TASK_1231 (verification gate)"