@pennyfarthing/core 7.7.0 → 7.8.0

package/pennyfarthing-dist/scripts/hooks/question_reflector_check.py

@@ -69,6 +69,19 @@ CHOICE_PATTERNS = [
     re.compile(r'\bchoose between\b', re.IGNORECASE),
 ]
 
+# Handoff phrase patterns - SM saying they'll hand off but not actually doing it
+HANDOFF_PHRASE_PATTERNS = [
+    re.compile(r'\bhanding (off )?to\b', re.IGNORECASE),
+    re.compile(r'\bpassing to\b', re.IGNORECASE),
+    re.compile(r'\bhand(ing)? this (off )?to\b', re.IGNORECASE),
+    re.compile(r'\b(Naomi|Amos|Avasarala|Holden|Alex|Drummer) (will|can)\b', re.IGNORECASE),
+    re.compile(r'\bfor (the )?(GREEN|RED|REVIEW) phase\b', re.IGNORECASE),
+    re.compile(r'\bspawning .* agent\b', re.IGNORECASE),
+]
+
+# Task tool invocation pattern in transcript
+TASK_TOOL_PATTERN = re.compile(r'"tool_name":\s*"Task"', re.IGNORECASE)
+
 
 # =============================================================================
 # Helper Functions
@@ -147,6 +160,55 @@ def detect_question(message: str) -> dict[str, Any]:
     return {'detected': False, 'type': ''}
 
 
+def detect_handoff_phrase(message: str) -> bool:
+    """Detect if a message contains handoff language (promising to hand off).
+
+    Args:
+        message: The message to check
+
+    Returns:
+        True if handoff language detected
+    """
+    # Strip code blocks first
+    clean_message = strip_code_blocks(message)
+
+    for pattern in HANDOFF_PHRASE_PATTERNS:
+        if pattern.search(clean_message):
+            return True
+    return False
+
+
+def has_task_tool_in_turn(transcript: list[dict[str, Any]]) -> bool:
+    """Check if the current turn includes a Task tool invocation.
+
+    Args:
+        transcript: Array of message objects
+
+    Returns:
+        True if Task tool was used in the current turn
+    """
+    # Find messages in the current turn (after the last user message)
+    current_turn_start = -1
+    for i, entry in enumerate(transcript):
+        msg = entry.get('message', entry)
+        if msg.get('role') == 'user':
+            current_turn_start = i
+
+    if current_turn_start < 0:
+        return False
+
+    # Check all entries after last user message for Task tool
+    for entry in transcript[current_turn_start:]:
+        msg = entry.get('message', entry)
+        if msg.get('role') == 'assistant':
+            content = msg.get('content', [])
+            if isinstance(content, list):
+                for block in content:
+                    if block.get('type') == 'tool_use' and block.get('name') == 'Task':
+                        return True
+    return False
+
+
 def has_reflector_marker(message: str) -> bool:
     """Check if a message has ANY valid CYCLIST reflector marker.
 
@@ -195,33 +257,53 @@ def extract_last_assistant_message(transcript: list[dict[str, Any]]) -> str:
     return ''
 
 
-def build_block_reason(question_type: str) -> str:
+def build_block_reason(question_type: str, handoff_without_task: bool = False) -> str:
     """Build the block reason message.
 
+    Provides actionable guidance so Claude can emit JUST the marker
+    on retry rather than regenerating the entire response.
+
     Args:
         question_type: The type of question detected (or empty for general)
+        handoff_without_task: True if handoff language detected but no Task tool used
 
     Returns:
-        The reason message
+        The reason message with suggested marker
     """
-    reason = 'Every turn MUST end with a CYCLIST reflector marker. '
+    # Special case: handoff language without Task tool
+    if handoff_without_task:
+        return (
+            'HANDOFF COMPLIANCE VIOLATION: You said you would hand off but did NOT use the Task tool.\n\n'
+            'SM Protocol: Task tool FIRST, narration SECOND.\n\n'
+            'Either:\n'
+            '1. Actually spawn the agent now using the Task tool, OR\n'
+            '2. If you completed the work yourself, remove handoff language and add <!-- CYCLIST:CONTINUE -->'
+        )
+
+    # Key insight: Tell Claude to ONLY emit the marker, not regenerate everything
+    reason = 'Missing CYCLIST marker. Your response content is fine - just APPEND the marker.\n\n'
 
     if question_type:
-        # Specific question type detected
+        # Specific question type detected - suggest exact marker
         if question_type == 'direct':
-            reason += 'You asked a question. Add <!-- CYCLIST:QUESTION:yesno --> or <!-- CYCLIST:QUESTION:open --> before your question.'
+            reason += 'Detected: direct question (?)\n'
+            reason += 'APPEND THIS: <!-- CYCLIST:QUESTION:open -->\n'
+            reason += '(Use yesno if it\'s a yes/no question)'
         elif question_type == 'implicit':
-            reason += 'You asked an implicit question. Add <!-- CYCLIST:QUESTION:yesno --> before phrases like "would you like" or "should I".'
+            reason += 'Detected: implicit question (would you like, should I, etc.)\n'
+            reason += 'APPEND THIS: <!-- CYCLIST:QUESTION:yesno -->'
         elif question_type == 'choices':
-            reason += 'You offered choices. Add <!-- CYCLIST:CHOICES:option1,option2,option3 --> listing the choices.'
+            reason += 'Detected: choice offering\n'
+            reason += 'APPEND THIS: <!-- CYCLIST:CHOICES:option1,option2 -->\n'
+            reason += '(Replace option1,option2 with actual choices)'
     else:
-        # No question detected, but still need a marker
-        reason += 'Valid markers:\n'
+        # No question detected - suggest CONTINUE marker
+        reason += 'No question detected - this looks like a status update.\n'
+        reason += 'APPEND THIS: <!-- CYCLIST:CONTINUE -->\n\n'
+        reason += 'Other markers if needed:\n'
         reason += '  <!-- CYCLIST:HANDOFF:/agent --> - workflow handoff\n'
         reason += '  <!-- CYCLIST:QUESTION:yesno --> - yes/no question\n'
-        reason += '  <!-- CYCLIST:QUESTION:open --> - open question\n'
-        reason += '  <!-- CYCLIST:CHOICES:a,b,c --> - multiple choice\n'
-        reason += '  <!-- CYCLIST:CONTINUE --> - status update, user may continue or redirect'
+        reason += '  <!-- CYCLIST:QUESTION:open --> - open question'
 
     return reason
 
@@ -229,14 +311,19 @@ def build_block_reason(question_type: str) -> str:
 def check_question_reflector(
     input_data: dict[str, Any],
     config: dict[str, Any],
-    last_message: str
+    last_message: str,
+    transcript: list[dict[str, Any]] | None = None
 ) -> dict[str, Any]:
     """Main check for Stop hook - validates ALL turns have reflector markers.
 
+    Also enforces handoff compliance: if handoff language detected without
+    Task tool usage, blocks the turn.
+
     Args:
         input_data: Hook input with transcript_path, stop_hook_active
         config: Config with workflow settings
         last_message: The last assistant message (pre-extracted for testing)
+        transcript: Full transcript for checking Task tool usage
 
     Returns:
         { 'ok': True } or { 'decision': 'block', 'reason': str }
@@ -257,6 +344,16 @@ def check_question_reflector(
     if has_reflector_marker(last_message):
         return {'ok': True}
 
+    # HANDOFF COMPLIANCE CHECK:
+    # If handoff language detected but no Task tool was used, block
+    if detect_handoff_phrase(last_message):
+        has_task = transcript and has_task_tool_in_turn(transcript)
+        if not has_task:
+            return {
+                'decision': 'block',
+                'reason': build_block_reason('', handoff_without_task=True),
+            }
+
     # No marker found - block
     # Check if it's a question to give more specific guidance
     detection = detect_question(last_message)
@@ -331,21 +428,21 @@ def load_config(project_dir: str) -> dict[str, Any]:
         return {'workflow': {'permission_mode': 'manual'}}
 
 
-def read_transcript(transcript_path: str) -> str:
+def read_transcript(transcript_path: str) -> tuple[str, list[dict[str, Any]]]:
     """Read transcript and extract last assistant message.
 
     Args:
         transcript_path: Path to JSONL transcript
 
     Returns:
-        The last assistant message
+        Tuple of (last assistant message, full transcript)
     """
     try:
         content = Path(transcript_path).read_text()
         lines = [line for line in content.strip().split('\n') if line]
 
         # Parse JSONL and build transcript array
-        transcript = []
+        transcript: list[dict[str, Any]] = []
         for line in lines:
             try:
                 transcript.append(json.loads(line))
@@ -353,9 +450,9 @@ def read_transcript(transcript_path: str) -> str:
                 # Skip malformed lines
                 pass
 
-        return extract_last_assistant_message(transcript)
+        return extract_last_assistant_message(transcript), transcript
     except Exception:
-        return ''
+        return '', []
 
 
 def main() -> None:
@@ -385,8 +482,8 @@ def main() -> None:
     else:
         # Stop hook
         transcript_path = input_data.get('transcript_path', '')
-        last_message = read_transcript(transcript_path) if transcript_path else ''
-        result = check_question_reflector(input_data, config, last_message)
+        last_message, transcript = read_transcript(transcript_path) if transcript_path else ('', [])
+        result = check_question_reflector(input_data, config, last_message, transcript)
         print(json.dumps(result))
 
     sys.exit(0)

package/pennyfarthing-dist/scripts/jira/README.md

@@ -7,18 +7,21 @@ Scripts for Jira integration, synchronization, and story management.
 | Script | Purpose |
 |--------|---------|
 | `jira-lib.sh` | Shared Jira bash utilities (library) |
-| `jira-lib.mjs` | Shared Jira JavaScript utilities (library) |
 | `jira-claim-story.sh` | Claim a story (assign and move to In Progress) |
 | `jira-reconcile.sh` | Reconcile Jira with sprint YAML |
-| `jira-sync.sh` | Sync story to Jira |
-| `jira-sync.mjs` | Sync story to Jira (JavaScript) |
-| `jira-sync-story.sh` | Sync individual story |
-| `jira-sync-story.mjs` | Sync individual story (JavaScript) |
+| `jira-sync.sh` | Sync story to Jira (wrapper → Python) |
+| `jira-sync-story.sh` | Sync individual story (wrapper → Python) |
 | `create-jira-epic.sh` | Create Jira epic with stories |
 | `create-jira-story.sh` | Create individual Jira story |
-| `sync-epic-jira.sh` | Sync epic to Jira |
+| `sync-epic-jira.sh` | Sync epic to Jira (wrapper → Python) |
 | `sync-epic-to-jira.sh` | Sync epic to Jira (alternate) |
-| `jira-bidirectional-sync.mjs` | Bidirectional sync between YAML and Jira |
+
+## Python Implementation
+
+Core logic lives in `pennyfarthing_scripts/jira/`:
+- `sync.py` — Epic and story sync
+- `bidirectional.py` — Two-way YAML ↔ Jira sync
+- `story.py` — Story operations
 
 ## Usage
 

package/pennyfarthing-dist/scripts/misc/add-short-names.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# add-short-names.sh - Pre-generate shortName field for theme characters
+#
+# Usage:
+#   add-short-names.sh                    # Dry run - show what would change
+#   add-short-names.sh --write            # Actually write changes
+#   add-short-names.sh --theme discworld  # Only process one theme
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+exec python3 "$SCRIPT_DIR/add_short_names.py" "$@"

package/pennyfarthing-dist/scripts/misc/add_short_names.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+add_short_names.py - Pre-generate shortName field for theme characters
+
+Finds the shortest unique identifier that distinguishes each character.
+
+Usage:
+  python add_short_names.py                    # Dry run - show what would change
+  python add_short_names.py --write            # Actually write changes
+  python add_short_names.py --theme discworld  # Only process one theme
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("Error: PyYAML required. Install with: pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+
+def find_project_root() -> Path:
+    """Find project root by looking for .claude directory."""
+    current = Path.cwd()
+    while current != current.parent:
+        if (current / ".claude").is_dir():
+            return current
+        current = current.parent
+    return Path.cwd()
+
+
+# Common titles/prefixes to strip for comparison
+SKIP_PREFIXES = {
+    'the', 'dr.', 'dr', 'captain', 'admiral', 'colonel', 'lieutenant', 'commander',
+    'president', 'lord', 'lady', 'sir', 'professor', 'inspector', 'sergeant',
+    'mr.', 'mr', 'mrs.', 'mrs', 'miss', 'ms.', 'ms', 'chief', 'major', 'general',
+    'king', 'queen', 'prince', 'princess', 'duke', 'earl', 'count', 'baron',
+    'first', 'grand', 'arch', 'high',
+    'uncle', 'aunt', 'brother', 'sister', 'father', 'mother', 'friar',
+    'avatar', 'agent', 'detective', 'officer', 'private', 'corporal',
+    'chancellor', 'ambassador', 'senator', 'governor', 'minister',
+    'master', 'young', 'old', 'elder', 'reverend', 'bishop', 'cardinal'
+}
+
+# Words that make poor short names on their own
+POOR_SHORT_NAMES = {
+    'big', 'little', 'old', 'young', 'true', 'false', 'good', 'bad',
+    'thought', 'ministry', 'situation', 'room', 'place', 'house',
+    'superintendent', 'commander', 'speaker', 'council',
+    'mode', 'narrator', 'chronicler',
+    'h.m.', 'j.f.', 'a.w.', 'e.b.', 'l.'
+}
+
+# Names that should use the full form (iconic two-word names)
+USE_FULL_NAME = {'big brother', 'sun tzu'}
+
+
+def extract_nickname(name: str) -> str | None:
+    """Extract quoted nickname from character name if present."""
+    match = re.search(r'["\']([^"\']+)["\']', name)
+    if match:
+        nickname = match.group(1).strip()
+        if nickname and ' ' not in nickname:
+            return nickname
+    return None
+
+
+def clean_name(name: str) -> str:
+    """Clean character name by removing parenthetical annotations and slash alternatives."""
+    cleaned = re.sub(r'\s*\([^)]+\)\s*', ' ', name).strip()
+    cleaned = re.sub(r'\b\w+/(\w+)\s', r'\1 ', cleaned)
+    cleaned = re.sub(r'\s*["\'][^"\']+["\']\s*', ' ', cleaned).strip()
+    cleaned = re.sub(r'\s+', ' ', cleaned).strip()
+    return cleaned
+
+
+def tokenize(name: str) -> list[str]:
+    """Tokenize a name into meaningful parts."""
+    cleaned = clean_name(name)
+    words = [w for w in cleaned.split() if w]
+
+    filtered = [
+        w for w in words
+        if w.lower() not in SKIP_PREFIXES
+        and not re.match(r'^[A-Z]\.$', w)
+        and not re.match(r'^[IVXLCDM]+$', w)
+    ]
+
+    return filtered if filtered else words
+
+
+def compute_short_names(agents: dict) -> dict[str, str]:
+    """Compute display name map for all characters in a theme."""
+    characters = [
+        a['character'] for a in agents.values()
+        if a and a.get('character')
+    ]
+
+    def is_unique(candidate: str, except_for: str) -> bool:
+        candidate_lower = candidate.lower()
+        for char in characters:
+            if char == except_for:
+                continue
+            tokens = tokenize(char)
+            if any(t.lower() == candidate_lower for t in tokens):
+                return False
+        return True
+
+    def is_good_short_name(candidate: str) -> bool:
+        return candidate.lower() not in POOR_SHORT_NAMES and len(candidate) > 1
+
+    def find_short_name(full_name: str) -> str:
+        cleaned = clean_name(full_name)
+
+        if cleaned.lower() in USE_FULL_NAME:
+            return cleaned
+
+        nickname = extract_nickname(full_name)
+        if nickname and is_good_short_name(nickname):
+            return nickname
+
+        tokens = tokenize(full_name)
+
+        if not tokens:
+            return cleaned
+
+        if len(tokens) == 1:
+            return tokens[0]
+
+        # Strategy 1: First token (if good and unique)
+        if is_good_short_name(tokens[0]) and is_unique(tokens[0], full_name):
+            return tokens[0]
+
+        # Strategy 2: Last token (surname, if good and unique)
+        last_token = tokens[-1]
+        if is_good_short_name(last_token) and is_unique(last_token, full_name):
+            return last_token
+
+        # Strategy 3: First + Last
+        if len(tokens) >= 2:
+            first_last = f"{tokens[0]} {last_token}"
+            if is_unique(first_last, full_name):
+                return first_last
+
+        return clean_name(full_name)
+
+    return {char: find_short_name(char) for char in characters}
+
+
+def process_theme(filepath: Path, dry_run: bool = True) -> dict:
+    """Process a single theme file."""
+    content = filepath.read_text()
+    theme = yaml.safe_load(content)
+
+    if not theme or 'agents' not in theme:
+        print(f"  Skipping {filepath.name} - no agents found")
+        return {'changes': 0, 'filename': filepath.name}
+
+    short_names = compute_short_names(theme['agents'])
+    changes = 0
+
+    for role, agent in theme['agents'].items():
+        if not agent or 'character' not in agent:
+            continue
+
+        short_name = short_names.get(agent['character'])
+        existing = agent.get('shortName')
+
+        if short_name and short_name != existing:
+            if dry_run:
+                existing_note = f' (was: "{existing}")' if existing else ''
+                print(f'  {role}: "{agent["character"]}" -> "{short_name}"{existing_note}')
+            agent['shortName'] = short_name
+            changes += 1
+
+    if not dry_run and changes > 0:
+        with open(filepath, 'w') as f:
+            yaml.dump(theme, f, default_flow_style=False, allow_unicode=True, width=1000)
+        print(f"  Wrote {changes} changes to {filepath.name}")
+
+    return {'changes': changes, 'filename': filepath.name}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Pre-generate shortName field for theme characters"
+    )
+    parser.add_argument('--write', action='store_true',
+                        help='Actually write changes (default: dry run)')
+    parser.add_argument('--theme', type=str,
+                        help='Only process one theme')
+    args = parser.parse_args()
+
+    dry_run = not args.write
+
+    project_root = find_project_root()
+    themes_dir = project_root / 'pennyfarthing-dist' / 'personas' / 'themes'
+
+    print('DRY RUN - No files will be modified\n' if dry_run else 'WRITING CHANGES\n')
+
+    files = sorted(themes_dir.glob('*.yaml'))
+    if args.theme:
+        theme_file = f"{args.theme}.yaml" if not args.theme.endswith('.yaml') else args.theme
+        files = [f for f in files if f.name == theme_file]
+
+    total_changes = 0
+    for file in files:
+        print(f"\n{file.name}:")
+        result = process_theme(file, dry_run)
+        total_changes += result['changes']
+        if result['changes'] == 0:
+            print('  (no changes needed)')
+
+    print(f"\n{'=' * 50}")
+    print(f"Total: {total_changes} changes across {len(files)} themes")
+    if dry_run and total_changes > 0:
+        print("\nRun with --write to apply changes")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/pennyfarthing-dist/scripts/misc/migrate-bmad-workflow.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
-# migrate-bmad-workflow.sh - Thin wrapper for migrate-bmad-workflow.mjs
+# migrate-bmad-workflow.sh - Migrate BMAD workflows to Pennyfarthing format
 #
 # Usage: ./scripts/migrate-bmad-workflow.sh [--dry-run] <source-dir> [target-dir]
-#
-# Delegates to Node script for cleaner YAML parsing and variable conversion.
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-exec node "${SCRIPT_DIR}/migrate-bmad-workflow.mjs" "$@"
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+exec python3 "$SCRIPT_DIR/migrate_bmad_workflow.py" "$@"