@pennyfarthing/core 7.6.0 → 7.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pennyfarthing/core",
-  "version": "7.6.0",
+  "version": "7.6.1",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
   "bin": {

package/pennyfarthing-dist/guides/agent-behavior.md

@@ -158,14 +158,15 @@ HTML comments that agents emit to signal Cyclist UI. Format: `<!-- CYCLIST:TYPE:
 |------|-------|----------------|
 | `HANDOFF` | `/agent` | Shows "Continue with /agent" button |
 | `CONTEXT_CLEAR` | `/agent` | Clears session, reloads with agent |
-| `QUESTION` | `yesno` | Shows yes/no dialog |
-| `CHOICES` | `1,2,3` | Shows choice buttons |
+| `QUESTION` | `yesno` or `open` | Shows input dialog |
+| `CHOICES` | `opt1,opt2,opt3` | Shows choice buttons |
 
 **Examples:**
 ```
 <!-- CYCLIST:HANDOFF:/tea -->
 <!-- CYCLIST:CONTEXT_CLEAR:/dev -->
 <!-- CYCLIST:QUESTION:yesno -->
+<!-- CYCLIST:QUESTION:open -->
 <!-- CYCLIST:CHOICES:option1,option2,option3 -->
 ```
 
@@ -175,6 +176,27 @@ HTML comments that agents emit to signal Cyclist UI. Format: `<!-- CYCLIST:TYPE:
 - `QUESTION`/`CHOICES` - User input needed mid-work
 </info>
 
+<critical>
+**Question Reflector Enforcement:** A Stop hook validates that ANY question to the user has a reflector marker. Emit the marker BEFORE your question.
+
+**Question types requiring markers:**
+- Direct questions ending with `?`
+- Implicit questions: "let me know if...", "would you like...", "should I..."
+- Choice offerings: "Option A or Option B"
+- Requests for input: "what do you think", "your preference"
+- Clarification requests: "could you clarify"
+
+**Marker selection:**
+- `<!-- CYCLIST:QUESTION:yesno -->` - Yes/no questions
+- `<!-- CYCLIST:QUESTION:open -->` - Open-ended questions
+- `<!-- CYCLIST:CHOICES:a,b,c -->` - Multiple choice (list options)
+
+**Exempt (no marker needed):**
+- Rhetorical questions you answer yourself
+- Questions inside code blocks or examples
+- Historical context ("the question was...")
+</critical>
+
 ---
 
 <agent-exit-protocol>

package/pennyfarthing-dist/scripts/core/check-context.sh

@@ -53,6 +53,7 @@ critical_threshold = $DEFAULT_CRITICAL_THRESHOLD
 max_tokens = $DEFAULT_MAX_TOKENS
 tirepump_threshold = $DEFAULT_TIREPUMP_THRESHOLD
 permission_mode = 'manual'  # Default to manual
+relay_mode = False  # MSSCI-12395: Independent auto-handoff toggle
 
 # First try .pennyfarthing/config.local.yaml (preferred location)
 try:
@@ -67,9 +68,13 @@ try:
                 critical_threshold = cb.get('critical_threshold', critical_threshold)
                 max_tokens = cb.get('max_tokens', max_tokens)
                 tirepump_threshold = cb.get('tirepump_threshold', tirepump_threshold)
-            # Read permission_mode from workflow section
-            if 'workflow' in config and 'permission_mode' in config['workflow']:
-                permission_mode = config['workflow']['permission_mode']
+            # Read permission_mode and relay_mode from workflow section
+            if 'workflow' in config:
+                if 'permission_mode' in config['workflow']:
+                    permission_mode = config['workflow']['permission_mode']
+                # MSSCI-12395: relay_mode for auto-handoff (independent of permission_mode)
+                if 'relay_mode' in config['workflow']:
+                    relay_mode = config['workflow']['relay_mode'] == True
 except:
     # Fallback to settings.local.json (legacy location)
     try:
@@ -82,8 +87,12 @@ except:
                 critical_threshold = cb.get('critical_threshold', critical_threshold)
                 max_tokens = cb.get('max_tokens', max_tokens)
                 tirepump_threshold = cb.get('tirepump_threshold', tirepump_threshold)
-            if 'workflow' in settings and 'permission_mode' in settings['workflow']:
-                permission_mode = settings['workflow']['permission_mode']
+            if 'workflow' in settings:
+                if 'permission_mode' in settings['workflow']:
+                    permission_mode = settings['workflow']['permission_mode']
+                # MSSCI-12395: relay_mode for auto-handoff (independent of permission_mode)
+                if 'relay_mode' in settings['workflow']:
+                    relay_mode = settings['workflow']['relay_mode'] == True
     except:
         pass
 
@@ -93,6 +102,7 @@ print(f'CRITICAL_THRESHOLD={critical_threshold}')
 print(f'MAX_TOKENS={max_tokens}')
 print(f'TIREPUMP_THRESHOLD={tirepump_threshold}')
 print(f'PERMISSION_MODE={permission_mode}')
+print(f'RELAY_MODE={str(relay_mode).lower()}')
 " 2>/dev/null)
 
 # Apply config or use defaults
@@ -140,6 +150,7 @@ import json
 warning_threshold = $WARNING_THRESHOLD
 max_tokens = $MAX_TOKENS
 permission_mode = '$PERMISSION_MODE'
+relay_mode = '$RELAY_MODE' == 'true'  # MSSCI-12395: Independent auto-handoff toggle
 tirepump_threshold = $TIREPUMP_THRESHOLD  # Threshold for TirePump auto-handoff (configurable)
 
 with open('$TRANSCRIPT', 'r') as f:
@@ -199,10 +210,11 @@ if last_total is not None:
         print('HANDOFF_MODE=ask')
 
     # TirePump: Use CONTEXT_CLEAR (clear + load next agent) when:
-    # 1. permission_mode is 'turbo' (auto-handoff enabled)
+    # 1. relay_mode is true (auto-handoff enabled) - MSSCI-12395
     # 2. context > 60% (tirepump_threshold)
     # This enables continuous autonomous runs without manual intervention
-    use_tirepump = permission_mode == 'turbo' and usable_pct > tirepump_threshold
+    # Legacy: also support permission_mode == 'turbo' for backwards compatibility
+    use_tirepump = (relay_mode or permission_mode == 'turbo') and usable_pct > tirepump_threshold
     print(f'USE_TIREPUMP={str(use_tirepump).lower()}')
 
     # Cyclist detection: Multiple methods for robustness

package/pennyfarthing-dist/scripts/hooks/question-reflector-check.mjs

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+/**
+ * question-reflector-check.mjs - Question reflector enforcement hook
+ *
+ * Story: MSSCI-12393
+ *
+ * Validates that any question asked by the agent has an appropriate
+ * CYCLIST reflector marker. Used by both Stop hook and PreToolUse hook.
+ *
+ * Question types detected:
+ *   - Direct questions (ends with ?)
+ *   - Implicit questions (would you like, should I, let me know if)
+ *   - Choice offerings (option A or B, we could do X or Y)
+ *
+ * Required markers:
+ *   <!-- CYCLIST:QUESTION:yesno -->
+ *   <!-- CYCLIST:QUESTION:open -->
+ *   <!-- CYCLIST:CHOICES:opt1,opt2,opt3 -->
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+// Marker patterns
+const QUESTION_MARKER_PATTERN = /<!--\s*CYCLIST:QUESTION:(yesno|open)\s*-->/i;
+const CHOICES_MARKER_PATTERN = /<!--\s*CYCLIST:CHOICES:[^>]+\s*-->/i;
+
+// Question patterns - direct (with ?)
+// Match: end of line, followed by space+capital (new sentence), or followed by newline
+const DIRECT_QUESTION_PATTERN = /\?(\s*$|\s+[A-Z]|\s*\n)/;
+
+// Rhetorical patterns to exclude
+const RHETORICAL_PATTERNS = /\b(the question (was|is)|asked whether|wondering if)\b/i;
+
+// Implicit question patterns
+const IMPLICIT_PATTERNS = [
+  /\bwould you like\b/i,
+  /\bshould I\b/i,
+  /\bdo you want\b/i,
+  /\blet me know if\b/i,
+  /\bwhat do you (think|prefer)\b/i,
+  /\byour (preference|thoughts)\b/i,
+  /\bcould you (clarify|confirm|specify)\b/i,
+  /\bwhich (option|approach)\b/i,
+  /\bready to proceed\b/i,
+];
+
+// Choice offering patterns
+const CHOICE_PATTERNS = [
+  /\boption [A-D]\b/i,
+  /\bchoice [0-9]\b/i,
+  /\bwe could (either|do)\b/i,
+  /\balternatively\b/i,
+  /\bor would you prefer\b/i,
+  /\bpick one\b/i,
+  /\bchoose between\b/i,
+];
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Strip fenced code blocks from text to avoid false positives
+ * @param {string} text - The text to process
+ * @returns {string} Text with code blocks removed
+ */
+function stripCodeBlocks(text) {
+  // Remove fenced code blocks (```...```)
+  let result = text.replace(/```[\s\S]*?```/g, '');
+  // Remove inline code (`...`)
+  result = result.replace(/`[^`]+`/g, '');
+  return result;
+}
+
+// =============================================================================
+// Exported Functions
+// =============================================================================
+
+/**
+ * Check if enforcement should be skipped based on config
+ * @param {object} config - The config object with workflow settings
+ * @returns {boolean} True if enforcement should be skipped
+ */
+export function shouldSkipEnforcement(config) {
+  const workflow = config?.workflow || {};
+
+  // Legacy: turbo mode skips enforcement
+  if (workflow.permission_mode === 'turbo') {
+    return true;
+  }
+
+  // New: relay_mode skips enforcement (for auto-handoff flows)
+  if (workflow.relay_mode === true) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Detect if a message contains a question
+ * @param {string} message - The message to check
+ * @returns {{ detected: boolean, type: string }} Detection result
+ */
+export function detectQuestion(message) {
+  // Strip code blocks first
+  const cleanMessage = stripCodeBlocks(message);
+
+  // Check for rhetorical patterns - if found, not a real question
+  if (RHETORICAL_PATTERNS.test(cleanMessage)) {
+    return { detected: false, type: '' };
+  }
+
+  // Check for direct questions (with ?)
+  if (DIRECT_QUESTION_PATTERN.test(cleanMessage)) {
+    return { detected: true, type: 'direct' };
+  }
+
+  // Check for implicit questions
+  for (const pattern of IMPLICIT_PATTERNS) {
+    if (pattern.test(cleanMessage)) {
+      return { detected: true, type: 'implicit' };
+    }
+  }
+
+  // Check for choice offerings
+  for (const pattern of CHOICE_PATTERNS) {
+    if (pattern.test(cleanMessage)) {
+      return { detected: true, type: 'choices' };
+    }
+  }
+
+  return { detected: false, type: '' };
+}
+
+/**
+ * Check if a message has a CYCLIST reflector marker
+ * @param {string} message - The message to check
+ * @returns {boolean} True if a marker is present
+ */
+export function hasReflectorMarker(message) {
+  return QUESTION_MARKER_PATTERN.test(message) || CHOICES_MARKER_PATTERN.test(message);
+}
+
+/**
+ * Extract the last assistant message from a transcript
+ * @param {Array} transcript - Array of message objects
+ * @returns {string} The last assistant message content
+ */
+export function extractLastAssistantMessage(transcript) {
+  // Find the last assistant message (reverse order)
+  for (let i = transcript.length - 1; i >= 0; i--) {
+    const msg = transcript[i];
+    if (msg.role === 'assistant') {
+      // Handle content as string or array
+      if (typeof msg.content === 'string') {
+        return msg.content;
+      }
+      if (Array.isArray(msg.content)) {
+        // Extract text from text blocks, skip tool_use blocks
+        return msg.content
+          .filter(block => block.type === 'text')
+          .map(block => block.text)
+          .join('');
+      }
+      return '';
+    }
+  }
+  return '';
+}
+
+/**
+ * Build the block reason message
+ * @param {string} questionType - The type of question detected
+ * @returns {string} The reason message
+ */
+function buildBlockReason(questionType) {
+  let reason = 'You asked a question but did not emit a CYCLIST reflector marker. ';
+
+  switch (questionType) {
+    case 'direct':
+      reason += 'Add <!-- CYCLIST:QUESTION:yesno --> for yes/no questions or <!-- CYCLIST:QUESTION:open --> for open-ended questions before your question.';
+      break;
+    case 'implicit':
+      reason += 'Add <!-- CYCLIST:QUESTION:yesno --> before phrases like "would you like" or "should I".';
+      break;
+    case 'choices':
+      reason += 'Add <!-- CYCLIST:CHOICES:option1,option2,option3 --> listing the choices before presenting options.';
+      break;
+    default:
+      reason += 'Add the appropriate marker before your question.';
+  }
+
+  reason += ' Re-state your question with the appropriate marker.';
+  return reason;
+}
+
+/**
+ * Main check for Stop hook - validates question reflector markers
+ * @param {object} input - Hook input with transcript_path, stop_hook_active
+ * @param {object} config - Config with workflow settings
+ * @param {string} lastMessage - The last assistant message (pre-extracted for testing)
+ * @returns {{ ok: true } | { decision: 'block', reason: string }}
+ */
+export function checkQuestionReflector(input, config, lastMessage) {
+  // Prevent infinite loops
+  if (input.stop_hook_active) {
+    return { ok: true };
+  }
+
+  // Skip enforcement in relay/turbo mode
+  if (shouldSkipEnforcement(config)) {
+    return { ok: true };
+  }
+
+  // If no message, allow
+  if (!lastMessage) {
+    return { ok: true };
+  }
+
+  // If marker present, allow
+  if (hasReflectorMarker(lastMessage)) {
+    return { ok: true };
+  }
+
+  // Check for questions
+  const detection = detectQuestion(lastMessage);
+  if (!detection.detected) {
+    return { ok: true };
+  }
+
+  // Question detected without marker - block
+  return {
+    decision: 'block',
+    reason: buildBlockReason(detection.type),
+  };
+}
+
+/**
+ * Check for AskUserQuestion PreToolUse hook
+ * @param {object} input - Hook input with tool_name, tool_input
+ * @param {object} config - Config with workflow settings
+ * @param {string} [recentOutput] - Recent assistant output to check for marker
+ * @returns {{ ok: true } | { decision: 'block', reason: string }}
+ */
+export function checkAskUserQuestion(input, config, recentOutput = '') {
+  // Skip enforcement in relay/turbo mode
+  if (shouldSkipEnforcement(config)) {
+    return { ok: true };
+  }
+
+  // If marker present in recent output, allow
+  if (recentOutput && hasReflectorMarker(recentOutput)) {
+    return { ok: true };
+  }
+
+  // Block - AskUserQuestion requires a marker
+  return {
+    decision: 'block',
+    reason: 'AskUserQuestion tool requires a CYCLIST marker. Add <!-- CYCLIST:QUESTION:yesno -->, <!-- CYCLIST:QUESTION:open -->, or <!-- CYCLIST:CHOICES:... --> before using this tool.',
+  };
+}
+
+// =============================================================================
+// CLI Entry Point (for bash wrapper)
+// =============================================================================
+
+/**
+ * Load config from .pennyfarthing/config.local.yaml
+ * @param {string} projectDir - The project directory
+ * @returns {object} The config object
+ */
+function loadConfig(projectDir) {
+  try {
+    const configPath = join(projectDir, '.pennyfarthing', 'config.local.yaml');
+    const content = readFileSync(configPath, 'utf-8');
+    // Simple YAML parsing for the fields we need
+    const config = { workflow: {} };
+
+    // Extract permission_mode
+    const modeMatch = content.match(/permission_mode:\s*(\w+)/);
+    if (modeMatch) {
+      config.workflow.permission_mode = modeMatch[1];
+    }
+
+    // Extract relay_mode
+    const relayMatch = content.match(/relay_mode:\s*(true|false)/);
+    if (relayMatch) {
+      config.workflow.relay_mode = relayMatch[1] === 'true';
+    }
+
+    return config;
+  } catch {
+    // Default config if file doesn't exist
+    return { workflow: { permission_mode: 'manual' } };
+  }
+}
+
+/**
+ * Read transcript and extract last assistant message
+ * @param {string} transcriptPath - Path to JSONL transcript
+ * @returns {string} The last assistant message
+ */
+function readTranscript(transcriptPath) {
+  try {
+    const content = readFileSync(transcriptPath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+
+    // Parse JSONL and build transcript array
+    const transcript = [];
+    for (const line of lines) {
+      try {
+        transcript.push(JSON.parse(line));
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return extractLastAssistantMessage(transcript);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Main CLI entry point
+ */
+async function main() {
+  // Read input from stdin
+  let inputData = '';
+  for await (const chunk of process.stdin) {
+    inputData += chunk;
+  }
+
+  let input;
+  try {
+    input = JSON.parse(inputData);
+  } catch {
+    // Invalid input - allow to prevent breaking
+    console.log(JSON.stringify({ ok: true }));
+    process.exit(0);
+  }
+
+  // Determine project directory
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  // Load config
+  const config = loadConfig(projectDir);
+
+  // Determine hook type based on input
+  if (input.tool_name === 'AskUserQuestion') {
+    // PreToolUse hook for AskUserQuestion
+    // For PreToolUse, we'd need the recent output - for now, just check config
+    const result = checkAskUserQuestion(input, config, '');
+    console.log(JSON.stringify(result));
+  } else {
+    // Stop hook
+    const transcriptPath = input.transcript_path || '';
+    const lastMessage = transcriptPath ? readTranscript(transcriptPath) : '';
+    const result = checkQuestionReflector(input, config, lastMessage);
+    console.log(JSON.stringify(result));
+  }
+
+  process.exit(0);
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((err) => {
+    console.error(err);
+    // On error, allow to prevent breaking
+    console.log(JSON.stringify({ ok: true }));
+    process.exit(0);
+  });
+}

package/pennyfarthing-dist/scripts/hooks/question-reflector-check.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+#
+# Question Reflector Enforcement Hook (Stop hook / PreToolUse hook)
+#
+# Thin wrapper that delegates to question-reflector-check.mjs for the actual logic.
+# This allows the hook to be written in JavaScript for easier testing and maintenance.
+#
+# Input (stdin): JSON with transcript_path, stop_hook_active, etc.
+# Output (stdout): JSON decision to allow or block
+#
+# Story: MSSCI-12393
+#
+
+set -euo pipefail
+
+# Get the directory where this script lives
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Delegate to JavaScript implementation
+exec node "$SCRIPT_DIR/question-reflector-check.mjs"

package/pennyfarthing-dist/scripts/hooks/tests/question-reflector.test.mjs

@@ -0,0 +1,545 @@
+#!/usr/bin/env node
+/**
+ * question-reflector.test.mjs - Tests for question reflector enforcement hook
+ *
+ * Story: MSSCI-12393
+ * TDD Phase: RED
+ *
+ * Run with: node --test pennyfarthing-dist/scripts/hooks/tests/question-reflector.test.mjs
+ */
+
+import { describe, it, beforeEach, mock } from 'node:test';
+import assert from 'node:assert';
+
+// The module under test
+import {
+  detectQuestion,
+  hasReflectorMarker,
+  shouldSkipEnforcement,
+  extractLastAssistantMessage,
+  checkQuestionReflector,
+  checkAskUserQuestion,
+} from '../question-reflector-check.mjs';
+
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+
+const MARKERS = {
+  yesno: '<!-- CYCLIST:QUESTION:yesno -->',
+  open: '<!-- CYCLIST:QUESTION:open -->',
+  choices: '<!-- CYCLIST:CHOICES:option1,option2,option3 -->',
+};
+
+const CONFIG_MANUAL = {
+  workflow: { permission_mode: 'manual' },
+};
+
+const CONFIG_ACCEPT = {
+  workflow: { permission_mode: 'accept' },
+};
+
+const CONFIG_TURBO_LEGACY = {
+  workflow: { permission_mode: 'turbo' },
+};
+
+const CONFIG_RELAY_ON = {
+  workflow: { permission_mode: 'accept', relay_mode: true },
+};
+
+const CONFIG_RELAY_OFF = {
+  workflow: { permission_mode: 'accept', relay_mode: false },
+};
+
+// =============================================================================
+// Relay/Turbo Mode Bypass Tests
+// =============================================================================
+
+describe('shouldSkipEnforcement', () => {
+  it('should skip enforcement when permission_mode is turbo (legacy)', () => {
+    const result = shouldSkipEnforcement(CONFIG_TURBO_LEGACY);
+    assert.strictEqual(result, true);
+  });
+
+  it('should skip enforcement when relay_mode is true', () => {
+    const result = shouldSkipEnforcement(CONFIG_RELAY_ON);
+    assert.strictEqual(result, true);
+  });
+
+  it('should NOT skip enforcement when relay_mode is false', () => {
+    const result = shouldSkipEnforcement(CONFIG_RELAY_OFF);
+    assert.strictEqual(result, false);
+  });
+
+  it('should NOT skip enforcement in manual mode without relay', () => {
+    const result = shouldSkipEnforcement(CONFIG_MANUAL);
+    assert.strictEqual(result, false);
+  });
+
+  it('should NOT skip enforcement in accept mode without relay', () => {
+    const result = shouldSkipEnforcement(CONFIG_ACCEPT);
+    assert.strictEqual(result, false);
+  });
+});
+
+// =============================================================================
+// Question Detection Tests - Direct Questions
+// =============================================================================
+
+describe('detectQuestion - direct questions', () => {
+  it('should detect question mark at end of message', () => {
+    const msg = 'What would you like me to do?';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'direct');
+  });
+
+  it('should detect question mark mid-message followed by new sentence', () => {
+    const msg = 'What do you need? I can help with several things.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'direct');
+  });
+
+  it('should detect question mark followed by newline and more content', () => {
+    const msg = 'What do you need?\n\nHere are your options:';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'direct');
+  });
+
+  it('should detect multiple questions in message', () => {
+    const msg = 'Should I proceed? Or would you prefer a different approach?';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+  });
+});
+
+// =============================================================================
+// Question Detection Tests - Implicit Questions
+// =============================================================================
+
+describe('detectQuestion - implicit questions', () => {
+  it('should detect "would you like"', () => {
+    const msg = 'I can fix this. Would you like me to proceed.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'implicit');
+  });
+
+  it('should detect "should I"', () => {
+    const msg = 'The tests are passing. Should I commit the changes.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'implicit');
+  });
+
+  it('should detect "do you want"', () => {
+    const msg = 'Do you want me to run the full test suite.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'implicit');
+  });
+
+  it('should detect "let me know if"', () => {
+    const msg = 'I made the changes. Let me know if you need anything else.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'implicit');
+  });
+
+  it('should detect "what do you think"', () => {
+    const msg = 'Here is my proposed solution. What do you think.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'implicit');
+  });
+
+  it('should detect "your preference"', () => {
+    const msg = 'Both approaches work. Your preference on which to use.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'implicit');
+  });
+
+  it('should detect "ready to proceed"', () => {
+    const msg = 'Everything is set up. Ready to proceed with the deployment.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'implicit');
+  });
+});
+
+// =============================================================================
+// Question Detection Tests - Choice Offerings
+// =============================================================================
+
+describe('detectQuestion - choice offerings', () => {
+  it('should detect "option A" style choices', () => {
+    const msg = 'We have two paths: Option A uses Redis, Option B uses memory.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'choices');
+  });
+
+  it('should detect "we could either"', () => {
+    const msg = 'We could either refactor now or defer to next sprint.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'choices');
+  });
+
+  it('should detect "alternatively"', () => {
+    const msg = 'I can add it inline. Alternatively, we create a helper function.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'choices');
+  });
+
+  it('should detect "or would you prefer"', () => {
+    const msg = 'I can use async/await, or would you prefer callbacks.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'choices');
+  });
+
+  it('should detect "choose between"', () => {
+    const msg = 'You can choose between TypeScript or JavaScript.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+    assert.strictEqual(result.type, 'choices');
+  });
+});
+
+// =============================================================================
+// Marker Detection Tests
+// =============================================================================
+
+describe('hasReflectorMarker', () => {
+  it('should detect QUESTION:yesno marker', () => {
+    const msg = `${MARKERS.yesno}\nShould I proceed?`;
+    const result = hasReflectorMarker(msg);
+    assert.strictEqual(result, true);
+  });
+
+  it('should detect QUESTION:open marker', () => {
+    const msg = `${MARKERS.open}\nWhat approach would you prefer?`;
+    const result = hasReflectorMarker(msg);
+    assert.strictEqual(result, true);
+  });
+
+  it('should detect CHOICES marker', () => {
+    const msg = `${MARKERS.choices}\nOption 1 or Option 2?`;
+    const result = hasReflectorMarker(msg);
+    assert.strictEqual(result, true);
+  });
+
+  it('should detect marker with extra whitespace', () => {
+    const msg = '<!--  CYCLIST:QUESTION:yesno  -->\nShould I proceed?';
+    const result = hasReflectorMarker(msg);
+    assert.strictEqual(result, true);
+  });
+
+  it('should return false when no marker present', () => {
+    const msg = 'Should I proceed?';
+    const result = hasReflectorMarker(msg);
+    assert.strictEqual(result, false);
+  });
+});
+
+// =============================================================================
+// False Positive Prevention Tests - Code Blocks
+// =============================================================================
+
+describe('detectQuestion - code block immunity', () => {
+  it('should NOT detect questions inside fenced code blocks', () => {
+    const msg = `Here is the code:
+\`\`\`javascript
+// What should this function return?
+function test() { return true; }
+\`\`\`
+The implementation is complete.`;
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+
+  it('should NOT detect questions inside inline code', () => {
+    const msg = 'The function `shouldIProceed()` returns a boolean.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+
+  it('should detect questions OUTSIDE code blocks', () => {
+    const msg = `Here is the code:
+\`\`\`javascript
+function test() { return true; }
+\`\`\`
+What do you think?`;
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, true);
+  });
+
+  it('should handle multiple code blocks correctly', () => {
+    const msg = `First block:
+\`\`\`
+code here?
+\`\`\`
+Second block:
+\`\`\`
+more code?
+\`\`\`
+Done.`;
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+});
+
+// =============================================================================
+// False Positive Prevention Tests - Rhetorical Questions
+// =============================================================================
+
+describe('detectQuestion - rhetorical question immunity', () => {
+  it('should NOT detect "the question was"', () => {
+    const msg = 'The question was whether to use async or sync. I chose async.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+
+  it('should NOT detect "the question is"', () => {
+    const msg = 'The question is rhetorical. Here is the answer.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+
+  it('should NOT detect "asked whether"', () => {
+    const msg = 'You asked whether this was possible. Yes, it is.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+
+  it('should NOT detect "wondering if"', () => {
+    const msg = 'I was wondering if this approach would work. It does.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+});
+
+// =============================================================================
+// No Question Tests
+// =============================================================================
+
+describe('detectQuestion - no question present', () => {
+  it('should NOT detect statements without questions', () => {
+    const msg = 'I have completed the implementation. All tests pass.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+
+  it('should NOT detect exclamations', () => {
+    const msg = 'Done! The feature is ready.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+
+  it('should NOT detect periods only', () => {
+    const msg = 'Task complete. Moving on to the next item.';
+    const result = detectQuestion(msg);
+    assert.strictEqual(result.detected, false);
+  });
+});
+
+// =============================================================================
+// Transcript Extraction Tests
+// =============================================================================
+
+describe('extractLastAssistantMessage', () => {
+  it('should extract last assistant message from JSONL', () => {
+    const transcript = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there!' },
+      { role: 'user', content: 'Help me' },
+      { role: 'assistant', content: 'What do you need?' },
+    ];
+    const result = extractLastAssistantMessage(transcript);
+    assert.strictEqual(result, 'What do you need?');
+  });
+
+  it('should handle content as array of text blocks', () => {
+    const transcript = [
+      {
+        role: 'assistant',
+        content: [
+          { type: 'text', text: 'First part. ' },
+          { type: 'text', text: 'What do you think?' },
+        ],
+      },
+    ];
+    const result = extractLastAssistantMessage(transcript);
+    assert.strictEqual(result, 'First part. What do you think?');
+  });
+
+  it('should return empty string when no assistant message', () => {
+    const transcript = [{ role: 'user', content: 'Hello' }];
+    const result = extractLastAssistantMessage(transcript);
+    assert.strictEqual(result, '');
+  });
+
+  it('should skip tool_use content blocks', () => {
+    const transcript = [
+      {
+        role: 'assistant',
+        content: [
+          { type: 'text', text: 'Let me check.' },
+          { type: 'tool_use', id: '123', name: 'Read' },
+        ],
+      },
+    ];
+    const result = extractLastAssistantMessage(transcript);
+    assert.strictEqual(result, 'Let me check.');
+  });
+});
+
+// =============================================================================
+// Integration Tests - Full Hook Logic
+// =============================================================================
+
+describe('checkQuestionReflector - integration', () => {
+  it('should return ok:true when no question detected', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: false,
+    };
+    const config = CONFIG_MANUAL;
+    const lastMessage = 'Task complete. All done.';
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('should return ok:true when question has marker', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: false,
+    };
+    const config = CONFIG_MANUAL;
+    const lastMessage = `${MARKERS.yesno}\nShould I proceed?`;
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('should return ok:true when in turbo mode (legacy)', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: false,
+    };
+    const config = CONFIG_TURBO_LEGACY;
+    const lastMessage = 'What do you need?'; // No marker, but turbo mode
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('should return ok:true when relay_mode is true', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: false,
+    };
+    const config = CONFIG_RELAY_ON;
+    const lastMessage = 'What do you need?'; // No marker, but relay on
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('should return ok:true when stop_hook_active is true', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: true, // Prevent infinite loops
+    };
+    const config = CONFIG_MANUAL;
+    const lastMessage = 'What do you need?';
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('should block when question detected without marker', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: false,
+    };
+    const config = CONFIG_MANUAL;
+    const lastMessage = 'What do you need?';
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.strictEqual(result.decision, 'block');
+    assert.ok(result.reason.includes('CYCLIST:QUESTION'));
+  });
+
+  it('should include appropriate marker hint for direct questions', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: false,
+    };
+    const config = CONFIG_MANUAL;
+    const lastMessage = 'Should I proceed?';
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.strictEqual(result.decision, 'block');
+    assert.ok(result.reason.includes('CYCLIST:QUESTION:yesno'));
+  });
+
+  it('should include appropriate marker hint for choices', () => {
+    const input = {
+      transcript_path: '/tmp/test.jsonl',
+      stop_hook_active: false,
+    };
+    const config = CONFIG_MANUAL;
+    const lastMessage = 'We could either use Option A or Option B.';
+    const result = checkQuestionReflector(input, config, lastMessage);
+    assert.strictEqual(result.decision, 'block');
+    assert.ok(result.reason.includes('CYCLIST:CHOICES'));
+  });
+});
+
+// =============================================================================
+// AskUserQuestion PreToolUse Hook Tests
+// =============================================================================
+
+describe('checkAskUserQuestion - PreToolUse hook', () => {
+  it('should return ok:true when relay_mode is true', () => {
+    const input = {
+      tool_name: 'AskUserQuestion',
+      tool_input: { questions: [{ question: 'Which option?' }] },
+    };
+    const config = CONFIG_RELAY_ON;
+    const result = checkAskUserQuestion(input, config);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('should return ok:true when in turbo mode (legacy)', () => {
+    const input = {
+      tool_name: 'AskUserQuestion',
+      tool_input: { questions: [{ question: 'Which option?' }] },
+    };
+    const config = CONFIG_TURBO_LEGACY;
+    const result = checkAskUserQuestion(input, config);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('should block AskUserQuestion without prior marker in transcript', () => {
+    const input = {
+      tool_name: 'AskUserQuestion',
+      tool_input: { questions: [{ question: 'Which option?' }] },
+    };
+    const config = CONFIG_MANUAL;
+    const transcriptWithoutMarker = 'Here are some choices.';
+    const result = checkAskUserQuestion(input, config, transcriptWithoutMarker);
+    assert.strictEqual(result.decision, 'block');
+  });
+
+  it('should allow AskUserQuestion when marker present in recent output', () => {
+    const input = {
+      tool_name: 'AskUserQuestion',
+      tool_input: { questions: [{ question: 'Which option?' }] },
+    };
+    const config = CONFIG_MANUAL;
+    const transcriptWithMarker = `${MARKERS.choices}\nHere are some choices.`;
+    const result = checkAskUserQuestion(input, config, transcriptWithMarker);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+});

package/pennyfarthing-dist/scripts/misc/deploy.sh

@@ -223,6 +223,7 @@ if $DRY_RUN; then
     log_dry "git tag -a $TAG_NAME -m 'Release $NEW_VERSION'"
     log_dry "git push origin develop main --tags"
     log_dry "gh release create $TAG_NAME --title 'Release $NEW_VERSION' --notes-from-tag --verify-tag"
+    log_dry "source .env && npm publish --access public"
     log_dry "git checkout develop"
 else
     log_info "Merging develop to main..."
@@ -261,7 +262,16 @@ else
         log_warn "Create release manually at: https://github.com/1898andCo/pennyfarthing/releases/new"
     fi
 
-    # Step 8: Return to develop
+    # Step 8: Publish to npm
+    log_info "Publishing to npm..."
+    if [[ -f "$PROJECT_ROOT/.env" ]]; then
+        source "$PROJECT_ROOT/.env"
+        npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
+    fi
+    (cd "$PROJECT_ROOT" && npm publish --access public)
+    log_info "Published @pennyfarthing/core@$NEW_VERSION to npm"
+
+    # Step 9: Return to develop
     log_info "Returning to develop..."
     git -C "$PROJECT_ROOT" checkout develop
 fi
@@ -273,12 +283,14 @@ if $DRY_RUN; then
     echo "  Would release version: $NEW_VERSION"
     echo "  Would create tag: $TAG_NAME"
     echo "  Would create GitHub release: $TAG_NAME"
+    echo "  Would publish: @pennyfarthing/core@$NEW_VERSION"
 else
     log_info "Deploy complete!"
     echo ""
     echo "  Version: $NEW_VERSION"
     echo "  Tag: $TAG_NAME"
     echo "  GitHub release: https://github.com/1898andCo/pennyfarthing/releases/tag/$TAG_NAME"
+    echo "  npm: @pennyfarthing/core@$NEW_VERSION"
     echo "  Branches pushed: develop, main"
 fi
 echo ""