kenaz 0.0.0-stage → 0.3.2

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

@@ -0,0 +1,250 @@
+brief_version: "1.0"
+task_id: TASK_1229
+title: "Implement Bifrost PreToolUse and PostToolUse hook dispatch"
+role: backend
+produced_by: TASK_1234
+
+# ─────────────────────────────────────────────────────────────────
+# CGDD RECONCILIATION (read this first)
+# ─────────────────────────────────────────────────────────────────
+cgdd_note: >
+  CGDD_hook_lifecycle.js labels PreToolUse/PostToolUse contracts as 'TASK_1231',
+  but the actual backlog assigns them to TASK_1229. FOLLOW THIS BRIEF.
+  The phantom contract names are authoritative; the task number labels inside
+  the CGDD are wrong. Relevant CGDD contracts for this task:
+    relay_dispatchBifrostHook, relay_capturedThreadId, relay_normalizeToolEvent
+
+cgdd_source: ".formation/bifrost/CGDD_hook_lifecycle.js"
+lifecycle_contract_source: ".specialist/tools/task-bridge.js (BIFROST_HOOK_LIFECYCLE.PreToolUse + PostToolUse)"
+
+# ─────────────────────────────────────────────────────────────────
+# OBJECTIVE
+# ─────────────────────────────────────────────────────────────────
+objective: >
+  Add PreToolUse and PostToolUse hook dispatch to relay.js (openai adapter).
+  This is entirely self-contained in relay.js — no changes to session.js or
+  task-bridge.js. Four tool types get two call sites each (8 total call sites):
+  command_execution, file_edit, file_read, mcp_tool_call.
+
+# ─────────────────────────────────────────────────────────────────
+# OWNED FILES — only touch this
+# ─────────────────────────────────────────────────────────────────
+owned_files:
+  primary: ".formation/bifrost/openai/relay.js"
+  read_for_contract: ".specialist/tools/task-bridge.js"
+  read_for_cgdd: ".formation/bifrost/CGDD_hook_lifecycle.js"
+
+# ─────────────────────────────────────────────────────────────────
+# NON-GOALS
+# ─────────────────────────────────────────────────────────────────
+non_goals:
+  - Do NOT modify session.js (TASK_1228 owns dispatchBifrostHook there; TASK_1230 owns session lifecycle)
+  - Do NOT modify task-bridge.js (PostToolUse routing already exists in handleHookEvent)
+  - Do NOT implement SessionStart, UserPromptSubmit, or Stop (session.js events)
+  - Do NOT change relay's stdin/stdout/stderr setup (TASK_1230 changes session.js stdio only)
+  - Do NOT reconstruct tool events from transcript/logs — hooks must fire at real execution boundaries in translateEvent()
+  - specialist field must be null — relay.js does not receive --specialist arg, do not invent it
+
+# ─────────────────────────────────────────────────────────────────
+# WHAT TO CREATE IN relay.js
+# ─────────────────────────────────────────────────────────────────
+module_additions:
+  - name: capturedThreadId
+    type: module_variable
+    placement: "add after RESUME_ID constant declaration (around line 38)"
+    declaration: "let capturedThreadId = null;"
+    set_in: "translateEvent() thread.started case — add: capturedThreadId = event.thread_id || null;"
+    used_in: "normalizeToolEvent() session_id field"
+
+  - name: dispatchBifrostHook
+    type: function
+    signature: "function dispatchBifrostHook(eventName, payload)"
+    placement: "add after the emit/emitToolResult utility functions (around line 63)"
+    require_path: "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) {
+          process.stderr.write(`[relay] hook dispatch failed (${eventName}): ${err.message}\n`);
+        }
+      }
+    error_policy: "catch + process.stderr.write — must never interrupt emit() sequence"
+    note: "This is a DIFFERENT function from session.js::dispatchBifrostHook — same pattern, different require path and different file"
+
+  - name: normalizeToolEvent
+    type: function
+    signature: "function normalizeToolEvent(eventName, toolName, toolId, toolInput, toolResponse)"
+    placement: "add after dispatchBifrostHook()"
+    returns_pretooluse: |
+      {
+        hook_event_name: 'PreToolUse',
+        tool_name:       toolName,
+        tool_id:         toolId,
+        tool_input:      toolInput,
+        session_id:      capturedThreadId,
+        specialist:      null,          // relay does not receive --specialist
+        cwd:             CWD,
+        project_path:    path.resolve(CWD),
+        timestamp:       new Date().toISOString(),
+      }
+    returns_posttooluse: |
+      {
+        hook_event_name: 'PostToolUse',
+        tool_name:       toolName,
+        tool_id:         toolId,
+        tool_input:      toolInput,
+        tool_response:   toolResponse,
+        is_error:        Boolean(toolResponse && (toolResponse.is_error || toolResponse.exit_code !== undefined && toolResponse.exit_code !== 0)),
+        session_id:      capturedThreadId,
+        specialist:      null,
+        cwd:             CWD,
+        project_path:    path.resolve(CWD),
+        timestamp:       new Date().toISOString(),
+      }
+
+# ─────────────────────────────────────────────────────────────────
+# CALL SITES (8 total — 4 tool types × 2 events each)
+# ─────────────────────────────────────────────────────────────────
+call_sites:
+  tool_name_mapping:
+    command_execution: "Bash"
+    file_edit: "Edit"
+    file_read: "Read"
+    mcp_tool_call: "mcp__<server>__<tool> (or use event.item.tool directly)"
+
+  command_execution:
+    pretooluse:
+      location: "translateEvent() item.completed → command_execution branch, AFTER cmdId assignment, BEFORE emit(tool_use)"
+      current_line_approx: 114
+      payload_args: "'PreToolUse', 'Bash', cmdId, { command: event.item.command || '' }, null"
+      call: "dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', 'Bash', cmdId, { command: event.item.command || '' }, null));"
+    posttooluse:
+      location: "AFTER emitToolResult(cmdId, ...) call"
+      tool_response: "{ output: cmdOutput, exit_code: event.item.exit_code }"
+      call: "dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', 'Bash', cmdId, { command: event.item.command || '' }, { output: cmdOutput, exit_code: event.item.exit_code }));"
+
+  file_edit:
+    pretooluse:
+      location: "AFTER editId assignment, BEFORE emit(tool_use)"
+      current_line_approx: 135
+      call: "dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', 'Edit', editId, { file_path: event.item.file_path || '', description: event.item.description || '' }, null));"
+    posttooluse:
+      location: "AFTER emitToolResult(editId, ...) call"
+      tool_response: "{ result: editResult, error: event.item.error || null }"
+      call: "dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', 'Edit', editId, { file_path: event.item.file_path || '' }, { result: editResult, error: event.item.error || null }));"
+
+  file_read:
+    pretooluse:
+      location: "AFTER readId assignment, BEFORE emit(tool_use)"
+      current_line_approx: 158
+      call: "dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', 'Read', readId, { file_path: event.item.file_path || '' }, null));"
+    posttooluse:
+      location: "AFTER emitToolResult(readId, ...) call"
+      tool_response: "{ content: readContent, error: event.item.error || null }"
+      call: "dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', 'Read', readId, { file_path: event.item.file_path || '' }, { content: readContent, error: event.item.error || null }));"
+
+  mcp_tool_call:
+    pretooluse:
+      location: "AFTER mcpId/mcpName assignment, BEFORE emit(tool_use)"
+      current_line_approx: 178
+      call: "dispatchBifrostHook('PreToolUse', normalizeToolEvent('PreToolUse', mcpName, mcpId, event.item.arguments || {}, null));"
+    posttooluse:
+      location: "AFTER emitToolResult(mcpId, ...) call"
+      tool_response: "{ result: mcpResult, error: event.item.error || null }"
+      call: "dispatchBifrostHook('PostToolUse', normalizeToolEvent('PostToolUse', mcpName, mcpId, event.item.arguments || {}, { result: mcpResult, error: event.item.error || null }));"
+
+  thread_started:
+    capture: "add inside the thread.started case, after the existing emit() call: capturedThreadId = event.thread_id || null;"
+
+# ─────────────────────────────────────────────────────────────────
+# INVARIANTS
+# ─────────────────────────────────────────────────────────────────
+invariants:
+  - "PreToolUse fires BEFORE emit(tool_use) — ordering is critical for hook consumers"
+  - "PostToolUse fires AFTER emitToolResult() — both must be for the same tool_id"
+  - "dispatchBifrostHook() must never throw or interrupt the emit() sequence"
+  - "specialist must always be null in relay.js payloads — relay does not receive --specialist"
+  - "capturedThreadId must be set before first tool call fires (thread.started always precedes item.completed)"
+  - "Both PreToolUse and PostToolUse must include hook_event_name as discriminator"
+  - "tool_id must be the SAME value for paired Pre/PostToolUse events (use the same cmdId/editId/readId/mcpId)"
+
+# ─────────────────────────────────────────────────────────────────
+# FORBIDDEN SHORTCUTS
+# ─────────────────────────────────────────────────────────────────
+forbidden:
+  - "Do NOT fire hooks from item.started events — only item.completed (item.started is skipped per existing logic)"
+  - "Do NOT reconstruct tool payloads from transcript or logs — hooks must use in-scope variables only"
+  - "Do NOT spawn a child process to call task-bridge — use require() + handleHookEvent() directly"
+  - "Do NOT add specialist field with a guessed value — null is correct and accepted by task-bridge"
+  - "Do NOT change relay's codex spawn args or stdout piping — those belong to TASK_1230's session.js changes"
+
+# ─────────────────────────────────────────────────────────────────
+# VERIFICATION COMMANDS (Phase 9 style)
+# ─────────────────────────────────────────────────────────────────
+verification:
+  grep_checks:
+    - desc: "capturedThreadId module variable declared"
+      cmd: "grep -n 'capturedThreadId' .formation/bifrost/openai/relay.js"
+      expected: "declaration (let capturedThreadId = null) + set in thread.started + used in normalizeToolEvent"
+
+    - desc: "dispatchBifrostHook function exists in relay.js"
+      cmd: "grep -n 'function dispatchBifrostHook' .formation/bifrost/openai/relay.js"
+      expected: "one match"
+
+    - desc: "normalizeToolEvent function exists"
+      cmd: "grep -n 'function normalizeToolEvent' .formation/bifrost/openai/relay.js"
+      expected: "one match"
+
+    - desc: "PreToolUse fires 4 times (once per tool type)"
+      cmd: "grep -c 'PreToolUse' .formation/bifrost/openai/relay.js"
+      expected: "at least 5 (1 in normalizeToolEvent return + 4 call sites)"
+
+    - desc: "PostToolUse fires 4 times (once per tool type)"
+      cmd: "grep -c 'PostToolUse' .formation/bifrost/openai/relay.js"
+      expected: "at least 5"
+
+    - desc: "require path for task-bridge is correct from relay.js depth"
+      cmd: "grep -n 'task-bridge' .formation/bifrost/openai/relay.js"
+      expected: "path.resolve(__dirname, '../../..', '.specialist/tools/task-bridge.js')"
+
+    - desc: "specialist is null in relay payloads"
+      cmd: "grep -n 'specialist.*null' .formation/bifrost/openai/relay.js"
+      expected: "at least one match in normalizeToolEvent"
+
+  ordering_check:
+    - desc: "PreToolUse before emit in command_execution block"
+      cmd: "grep -n 'PreToolUse\\|emit.*tool_use\\|cmdId' .formation/bifrost/openai/relay.js"
+      expected: "dispatchBifrostHook PreToolUse line appears BEFORE emit(tool_use) line in command_execution block"
+
+  integration_check:
+    desc: "Dry-run PostToolUse through task-bridge"
+    cmd: |
+      node -e "
+        const path = require('path');
+        const tb = require('./.specialist/tools/task-bridge');
+        const payload = {
+          hook_event_name: 'PostToolUse',
+          tool_name: 'Bash',
+          tool_id: 'test_cmd_1',
+          tool_input: { command: 'echo test' },
+          tool_response: { output: 'test', exit_code: 0 },
+          is_error: false,
+          session_id: 'thread_test',
+          specialist: null,
+          cwd: process.cwd(),
+          project_path: process.cwd(),
+          timestamp: new Date().toISOString()
+        };
+        tb.handleHookEvent(payload).then(r => console.log('OK (no TaskCreate/Update in payload):', r)).catch(e => console.error('FAIL:', e.message));
+      "
+    expected: "OK: null (task-bridge no-ops for Bash, only acts on TaskCreate/TaskUpdate tool_name)"
+
+# ─────────────────────────────────────────────────────────────────
+# ORDERING
+# ─────────────────────────────────────────────────────────────────
+ordering:
+  no_prerequisite: "This task is independent — dispatchBifrostHook lives in relay.js, not session.js, so TASK_1228 completion is not required before starting"
+  can_run_in_parallel_with: "TASK_1228 (session.js only), TASK_1230 (session.js only)"
+  must_complete_before: "TASK_1231 (verification gate)"

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

@@ -0,0 +1,301 @@
+brief_version: "1.0"
+task_id: TASK_1230
+title: "Implement Bifrost SessionStart and Stop parity for specialist session lifecycle"
+role: backend
+produced_by: TASK_1234
+
+# ─────────────────────────────────────────────────────────────────
+# CGDD RECONCILIATION (read this first)
+# ─────────────────────────────────────────────────────────────────
+cgdd_note: >
+  CGDD_hook_lifecycle.js splits SessionStart (CGDD TASK_1228) and Stop (CGDD TASK_1230)
+  into separate tasks. The actual backlog combines them into TASK_1230.
+  FOLLOW THIS BRIEF. Relevant CGDD phantom contracts for this task:
+    session_normalizeSessionStart, session_resultCapture, session_normalizeStop.
+  The dispatchBifrostHook() function is NOT created here — TASK_1228 creates it.
+  This task adds it to the two new call sites only.
+
+cgdd_source: ".formation/bifrost/CGDD_hook_lifecycle.js"
+lifecycle_contract_source: ".specialist/tools/task-bridge.js (BIFROST_HOOK_LIFECYCLE.SessionStart + Stop)"
+
+# ─────────────────────────────────────────────────────────────────
+# OBJECTIVE
+# ─────────────────────────────────────────────────────────────────
+objective: >
+  Add SessionStart and Stop hook dispatch to session.js. SessionStart fires after
+  writeSignal() and before launchRelay(). Stop fires in relay.on('close') before
+  the existing reflex feedback block. Stop requires intercepting relay stdout to
+  capture cost/token metrics from the result event — this is the only non-trivial
+  wiring change in this task.
+
+prerequisite: "TASK_1228 must complete first — it creates dispatchBifrostHook() in session.js"
+
+# ─────────────────────────────────────────────────────────────────
+# 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 create dispatchBifrostHook() — TASK_1228 already created it
+  - Do NOT modify relay.js (TASK_1229 owns that file)
+  - Do NOT modify task-bridge.js (handleHookEvent fall-through for SessionStart/Stop is already safe)
+  - Do NOT redefine payload schema (frozen in BIFROST_HOOK_LIFECYCLE)
+  - Do NOT change the logic inside the reflex feedback try/catch block (lines ~124-173) — Stop fires BEFORE it, not inside it
+
+# ─────────────────────────────────────────────────────────────────
+# WHAT TO ADD IN session.js
+# ─────────────────────────────────────────────────────────────────
+module_additions:
+  - name: sessionStartedAt
+    type: module_variable
+    placement: "add near top after SIGNAL_PATH constant"
+    declaration: "let sessionStartedAt = null;"
+    set_in: "normalizeSessionStart() — set sessionStartedAt = new Date().toISOString() before returning payload"
+    used_in: "normalizeStop() started_at field"
+
+  - name: resultCapture
+    type: module_variable
+    placement: "add after sessionStartedAt"
+    declaration: "const resultCapture = { total_cost_usd: 0, num_turns: 0, input_tokens: 0, output_tokens: 0 };"
+    set_in: "relay stdout 'data' event handler added by this task"
+    used_in: "normalizeStop() cost + token fields"
+    critical: "resultCapture starts as zero — Stop payload will have zeroes if stdout capture fails (acceptable degradation)"
+
+functions_to_create:
+  - name: normalizeSessionStart
+    signature: "function normalizeSessionStart()"
+    placement: "add after dispatchBifrostHook() (created by TASK_1228)"
+    body: |
+      function normalizeSessionStart() {
+        sessionStartedAt = new Date().toISOString();
+        return {
+          hook_event_name: 'SessionStart',
+          specialist:      SPECIALIST,
+          adapter:         ADAPTER,
+          model:           MODEL,
+          cwd:             CWD,
+          pid:             process.pid,
+          session_id:      RESUME_ID,
+          started_at:      sessionStartedAt,
+          project_path:    path.resolve(CWD),
+        };
+      }
+    side_effect: "sets module-level sessionStartedAt — this is intentional"
+
+  - name: normalizeStop
+    signature: "function normalizeStop(code, startedAt)"
+    placement: "add after normalizeSessionStart()"
+    body: |
+      function normalizeStop(code, startedAt) {
+        return {
+          hook_event_name: 'Stop',
+          specialist:      SPECIALIST,
+          adapter:         ADAPTER,
+          exit_code:       code || 0,
+          is_error:        (code || 0) !== 0,
+          session_id:      RESUME_ID,
+          total_cost_usd:  resultCapture.total_cost_usd,
+          num_turns:       resultCapture.num_turns,
+          input_tokens:    resultCapture.input_tokens,
+          output_tokens:   resultCapture.output_tokens,
+          started_at:      startedAt,
+          ended_at:        new Date().toISOString(),
+          cwd:             CWD,
+          project_path:    path.resolve(CWD),
+        };
+      }
+
+# ─────────────────────────────────────────────────────────────────
+# CALL SITES
+# ─────────────────────────────────────────────────────────────────
+call_sites:
+  sessionstart:
+    location: "main execution block (bottom of file)"
+    current_code: |
+      if (RESUME_ID) {
+        writeSignal();
+        ...
+        launchRelay(userMsg);
+      } else {
+        ...
+        writeSignal();
+        launchRelay(prompt);
+      }
+    target_code: |
+      if (RESUME_ID) {
+        writeSignal();
+        dispatchBifrostHook('SessionStart', normalizeSessionStart());
+        ...
+        launchRelay(userMsg);
+      } else {
+        ...
+        writeSignal();
+        dispatchBifrostHook('SessionStart', normalizeSessionStart());
+        launchRelay(prompt);
+      }
+    ordering_invariant: "SessionStart AFTER writeSignal(), BEFORE launchRelay()"
+    ordering_with_userpromptsubmit: "If TASK_1228 already added UserPromptSubmit dispatch, SessionStart must come BEFORE it: writeSignal() → SessionStart → UserPromptSubmit → launchRelay()"
+
+  stop:
+    location: "relay.on('close') handler in launchRelay() function (current lines ~119-176)"
+    current_code: |
+      relay.on('close', (code) => {
+        cleanupSignal();
+        try {
+          // ... reflex feedback block (lines ~124-173)
+        } catch (err) {
+          console.error(`[bifrost] Reflex feedback skipped: ${err.message}`);
+        }
+        process.exit(code || 0);
+      });
+    target_code: |
+      relay.on('close', (code) => {
+        cleanupSignal();
+        dispatchBifrostHook('Stop', normalizeStop(code, sessionStartedAt));  // ← ADD THIS LINE
+        try {
+          // ... reflex feedback block (unchanged)
+        } catch (err) {
+          console.error(`[bifrost] Reflex feedback skipped: ${err.message}`);
+        }
+        process.exit(code || 0);
+      });
+    ordering_invariant: "Stop fires BEFORE reflex feedback block and BEFORE process.exit"
+
+  stdout_capture:
+    description: "Change relay stdio and intercept result events to populate resultCapture"
+    current_spawn: |
+      const relay = spawn('node', [relayScript, ...relayArgs], {
+        cwd: CWD,
+        stdio: ['pipe', 'inherit', 'inherit'],
+        windowsHide: true
+      });
+    target_spawn: |
+      const relay = spawn('node', [relayScript, ...relayArgs], {
+        cwd: CWD,
+        stdio: ['pipe', 'pipe', 'inherit'],   // ← change 'inherit' to 'pipe' for stdout
+        windowsHide: true
+      });
+    add_after_spawn: |
+      // Tee relay stdout: forward to process.stdout AND intercept result lines
+      let stdoutBuffer = '';
+      relay.stdout.on('data', (chunk) => {
+        process.stdout.write(chunk);  // forward as-is (preserve downstream consumers)
+        stdoutBuffer += chunk.toString();
+        const lines = stdoutBuffer.split('\n');
+        stdoutBuffer = lines.pop();
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const parsed = JSON.parse(line);
+            if (parsed.type === 'result') {
+              resultCapture.total_cost_usd = parsed.total_cost_usd || 0;
+              resultCapture.num_turns      = parsed.num_turns || 0;
+              resultCapture.input_tokens   = (parsed.usage && parsed.usage.input_tokens) || parsed.input_tokens || 0;
+              resultCapture.output_tokens  = (parsed.usage && parsed.usage.output_tokens) || parsed.output_tokens || 0;
+            }
+          } catch { /* non-JSON line — already forwarded */ }
+        }
+      });
+    critical: >
+      relay stdout is currently 'inherit' — changing it to 'pipe' is necessary
+      to intercept the result event for cost/token capture. The manual tee
+      (process.stdout.write(chunk)) preserves all existing downstream behavior.
+      This is the only non-trivial change in this entire task.
+
+# ─────────────────────────────────────────────────────────────────
+# INVARIANTS
+# ─────────────────────────────────────────────────────────────────
+invariants:
+  - "SessionStart fires exactly once per session.js invocation, on both RESUME_ID and fresh-session paths"
+  - "Stop fires exactly once, in relay.on('close'), BEFORE the reflex feedback block"
+  - "sessionStartedAt is captured inside normalizeSessionStart() — not at a different time"
+  - "resultCapture gracefully degrades to all-zeros if no result event is intercepted"
+  - "relay stdout must be forwarded to process.stdout unchanged — no content filtering"
+  - "dispatchBifrostHook() must not throw — existing try/catch from TASK_1228 covers this"
+
+# ─────────────────────────────────────────────────────────────────
+# FORBIDDEN SHORTCUTS
+# ─────────────────────────────────────────────────────────────────
+forbidden:
+  - "Do NOT place Stop inside the reflex feedback try/catch — Stop must fire even if reflex logic fails"
+  - "Do NOT use process.on('exit') or process.on('SIGTERM') as the Stop call site — must be relay.on('close')"
+  - "Do NOT set relay stdout to 'ignore' — downstream consumers depend on relay output"
+  - "Do NOT recreate dispatchBifrostHook() — reuse what TASK_1228 created"
+  - "Do NOT capture resultCapture inside the reflex block — it must be set before Stop fires"
+
+# ─────────────────────────────────────────────────────────────────
+# VERIFICATION COMMANDS (Phase 9 style)
+# ─────────────────────────────────────────────────────────────────
+verification:
+  grep_checks:
+    - desc: "normalizeSessionStart function exists"
+      cmd: "grep -n 'function normalizeSessionStart' .formation/bifrost/session.js"
+      expected: "one match"
+
+    - desc: "normalizeStop function exists"
+      cmd: "grep -n 'function normalizeStop' .formation/bifrost/session.js"
+      expected: "one match"
+
+    - desc: "sessionStartedAt module variable declared"
+      cmd: "grep -n 'sessionStartedAt' .formation/bifrost/session.js"
+      expected: "at least 3 matches: declaration, set in normalizeSessionStart, used in normalizeStop call"
+
+    - desc: "resultCapture module variable declared"
+      cmd: "grep -n 'resultCapture' .formation/bifrost/session.js"
+      expected: "at least 4 matches: declaration, 4 field assignments, used in normalizeStop"
+
+    - desc: "relay stdio changed to pipe for stdout"
+      cmd: "grep -n \"stdio.*pipe.*pipe\\|'pipe', 'pipe'\" .formation/bifrost/session.js"
+      expected: "match showing stdout changed from 'inherit' to 'pipe'"
+
+    - desc: "relay.stdout.on data handler exists (tee)"
+      cmd: "grep -n 'relay.stdout.on' .formation/bifrost/session.js"
+      expected: "one match"
+
+    - desc: "Stop dispatch wired before reflex block"
+      cmd: "grep -n \"dispatchBifrostHook.*Stop\\|reflex feedback\\|cleanupSignal\" .formation/bifrost/session.js"
+      expected: "cleanupSignal() first, then Stop dispatch, then reflex feedback comment — in that order"
+
+    - desc: "SessionStart wired on both code paths"
+      cmd: "grep -n 'SessionStart' .formation/bifrost/session.js"
+      expected: "at least 2 dispatch call sites (RESUME_ID path + fresh-session path) plus normalizeSessionStart body"
+
+  ordering_proof:
+    - desc: "Verify SessionStart fires before UserPromptSubmit (if TASK_1228 already done)"
+      cmd: "node -e \"const src = require('fs').readFileSync('.formation/bifrost/session.js','utf8'); const ssIdx = src.lastIndexOf('SessionStart'); const upsIdx = src.lastIndexOf('UserPromptSubmit'); console.log('SessionStart at:', ssIdx, 'UserPromptSubmit at:', upsIdx, 'Correct order:', ssIdx < upsIdx);\""
+      expected: "Correct order: true"
+
+  integration_check:
+    desc: "Dry-run SessionStart through task-bridge (no-op expected)"
+    cmd: |
+      node -e "
+        const tb = require('./.specialist/tools/task-bridge');
+        const payload = {
+          hook_event_name: 'SessionStart',
+          specialist: 'Ansuz',
+          adapter: 'openai',
+          model: null,
+          cwd: process.cwd(),
+          pid: process.pid,
+          session_id: null,
+          started_at: new Date().toISOString(),
+          project_path: process.cwd(),
+        };
+        tb.handleHookEvent(payload).then(r => console.log('OK (no-op):', r)).catch(e => console.error('FAIL:', e.message));
+      "
+    expected: "OK (no-op): null"
+
+# ─────────────────────────────────────────────────────────────────
+# ORDERING
+# ─────────────────────────────────────────────────────────────────
+ordering:
+  prerequisite: "TASK_1228 must complete first (creates dispatchBifrostHook in session.js)"
+  can_run_in_parallel_with: "TASK_1229 (relay.js only — no file overlap)"
+  must_complete_before: "TASK_1231 (verification gate)"
+  final_hook_ordering_in_session_js: "writeSignal() → SessionStart → UserPromptSubmit → launchRelay() → [relay runs] → Stop → reflex block → process.exit()"