@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-05-import-to-future.md

@@ -10,9 +10,6 @@ thisStepFile: './step-05-import-to-future.md'
 workflowFile: '{workflow_path}/workflow.yaml'
 outputFile: '{planning_artifacts}/epics.md'
 futureYaml: '{project_root}/sprint/future.yaml'
-
-# Script References
-importScript: '{project_root}/.pennyfarthing/scripts/sprint/import-epic-to-future.sh'
 ---
 
 <purpose>
@@ -21,12 +18,13 @@ To import the validated and complete epics and stories from the epics.md documen
 
 <instructions>
 1. Determine the initiative name from the epics document (prompt user if not obvious)
-2. Run the import script in dry-run mode to show what will be added
-3. Display the preview to the user showing epic numbers, initiative structure, and story IDs
-4. Get user confirmation that the preview looks correct
-5. If confirmed, run the import script without dry-run to apply changes to future.yaml
-6. Verify the import by checking that epic appears in future.yaml with correct numbering
-7. Display completion message with epic number, initiative name, and story count
+2. Read current future.yaml to find the next epic number (highest epic-N + 1)
+3. Read the validated epics.md output and construct the YAML structure
+4. Display a preview to the user showing epic numbers, initiative structure, and story IDs
+5. Get user confirmation that the preview looks correct
+6. If confirmed, append the new initiative and epics to future.yaml using yq
+7. Verify the import by checking that epic appears in future.yaml with correct numbering
+8. Display completion message with epic number, initiative name, and story count
 </instructions>
 
 <output>
@@ -72,34 +70,53 @@ Look at the epics document title and ask user:
 
 Wait for user confirmation or alternative name.
 
-### 2. Preview Import (Dry Run)
+### 2. Determine Next Epic Number
 
-Run the import script with `--dry-run` to show what will be added:
+Read `sprint/future.yaml` and find the highest `epic-N` ID currently in use:
 
 ```bash
-.pennyfarthing/scripts/sprint/import-epic-to-future.sh {outputFile} "{initiative_name}" --dry-run
+yq '.future.initiatives[].epics[].id' sprint/future.yaml | grep -oE 'epic-[0-9]+' | sed 's/epic-//' | sort -n | tail -1
+```
+
+The next epic gets `epic-{N+1}`. Stories use `{N+1}-{story_number}` format.
+
+### 3. Construct and Preview
+
+Read the validated epics.md output file. For each epic, construct the YAML structure:
+
+```yaml
+- id: epic-{N}
+  title: "Epic: {epic_title}"
+  points: {total_points}
+  priority: {priority}
+  repos: {repo}
+  stories:
+    - id: "{N}-1"
+      title: "{story_title}"
+      points: {points}
+      type: {type}
+      status: backlog
+      workflow: {workflow}
+      priority: {priority}
+      repos: {repo}
 ```
 
-Display the preview output to the user showing:
+Display the full preview to the user showing:
 - Next epic number that will be assigned
 - Initiative structure
 - All stories with IDs
 
-### 3. Confirm and Apply
+### 4. Confirm and Apply
 
 Ask user: "Does this look correct? [Y] Yes, import to future.yaml / [N] No, make changes"
 
 **If Y:**
-Run the import without `--dry-run`:
-
-```bash
-.pennyfarthing/scripts/sprint/import-epic-to-future.sh {outputFile} "{initiative_name}"
-```
+Append the new initiative and epics to `sprint/future.yaml` using yq or direct YAML editing.
 
 **If N:**
-Ask what changes are needed and help user adjust before re-running.
+Ask what changes are needed and help user adjust before re-applying.
 
-### 4. Verify Import
+### 5. Verify Import
 
 After successful import, verify by showing:
 
@@ -112,7 +129,7 @@ Confirm:
 - Epic number is correct
 - Stories have proper IDs
 
-### 5. Complete Workflow
+### 6. Complete Workflow
 
 Display completion message:
 
@@ -138,8 +155,8 @@ Next steps:
 
 ## FAILURE MODES:
 
-- ❌ Import script not found - check .pennyfarthing symlinks
 - ❌ future.yaml not found - ensure sprint/ directory exists
-- ❌ Duplicate epic number - script should handle this automatically
+- ❌ Duplicate epic number - check existing IDs before assigning
+- ❌ yq not installed - required for YAML manipulation (`brew install yq`)
 
 **Master Rule:** The workflow is not complete until epics are in future.yaml and accessible via sprint commands.

package/pennyfarthing-dist/workflows/tdd-tandem.yaml

@@ -0,0 +1,61 @@
+# TDD Tandem Workflow - TDD with Full Tandem Chain
+# Extends standard TDD with tandem observers on every phase:
+#   - Architect backseats TEA during red phase
+#   - TEA backseats Dev during green phase
+#   - PM backseats Reviewer during review phase
+#
+# Flow: SM → TEA (+Architect) → Dev (+TEA) → Reviewer (+PM) → SM
+
+workflow:
+  name: tdd-tandem
+  description: TDD with full tandem chain across all phases
+  version: "2.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: red
+      agent: tea
+      input: [session_file, story_context]
+      output: [failing_tests]
+      gate:
+        type: tests_fail
+        condition: All acceptance criteria have test coverage
+      tandem:
+        partner: architect
+        scope: file-watch
+
+    - name: green
+      agent: dev
+      input: [failing_tests, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        type: tests_pass
+        condition: All tests passing, no skipped tests
+      tandem:
+        partner: tea
+        scope: file-watch
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        type: approval
+        condition: Code review approved, no blocking issues
+      tandem:
+        partner: pm
+        scope: file-watch
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [tandem]
+    points:
+      min: 3
+    default: false

package/pennyfarthing_scripts/bellmode_hook.py

@@ -1,30 +1,23 @@
 #!/usr/bin/env python3
 """
-Bell Mode PostToolUse Hook (Python)
+PostToolUse Hook — Bell Mode + Tandem Injection (Python)
 
-This hook is called by Claude Code after each tool execution.
-When bell mode is enabled and there are queued messages, it returns
-the first queued message as additionalContext to be injected into
-Claude's next API call.
+Called by Claude Code after each tool execution. Handles two independent
+injection systems:
 
-Configuration files:
-  .pennyfarthing/config.local.yaml - workflow.bell_mode: true/false
-  .pennyfarthing/bell-queue.json - [{"text": "...", "images": [...]}, ...]
+1. Bell queue (Cyclist only) — injects queued user messages when Cyclist
+   is running and bell_mode is enabled. In CLI sessions this is a no-op.
+2. Tandem observations (always active) — injects backseat agent observations
+   when tandem observation files exist. No configuration required.
 
-Output format (when injecting):
-  {
-    "hookSpecificOutput": {
-      "hookEventName": "PostToolUse",
-      "additionalContext": "User feedback: <message>"
-    }
-  }
-
-Output when disabled or queue empty: (nothing - exit 0)
+Bell queue takes precedence: if a queued message exists, tandem is
+deferred to the next hook invocation.
 
 Story: MSSCI-12409 - Hook consistency and WheelHub consolidation
 """
 
 import json
+import re
 import sys
 from pathlib import Path
 
@@ -32,12 +25,13 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from hooks import (
-    find_project_root,
-    get_cyclist_port,
-    send_to_cyclist,
-    output_hook_response,
+    CYCLIST_PORT_FILE,
     HookResponse,
+    find_project_root,
     is_bell_mode_enabled,
+    output_hook_response,
+    read_port_file,
+    send_to_cyclist,
 )
 
 
@@ -106,8 +100,170 @@ def notify_cyclist(project_root: Path, message_text: str) -> None:
         pass
 
 
+# =============================================================================
+# Tandem Observation Injection (Story 95-7 / MSSCI-14672)
+# =============================================================================
+# Stubs for tandem observation injection. Dev will implement.
+
+
+def read_tandem_observations(project_root: Path) -> list[Path]:
+    """Find tandem observation files in .session/ directory.
+
+    Looks for files matching .session/*-tandem-*.md pattern.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        List of Path objects for tandem observation files
+    """
+    session_dir = project_root / ".session"
+    if not session_dir.is_dir():
+        return []
+    return sorted(session_dir.glob("*-tandem-*.md"))
+
+
+def get_latest_observation(file_content: str) -> dict | None:
+    """Extract the latest observation entry from a tandem observation file.
+
+    Parses the markdown format to extract the most recent ## [HH:MM] Observation
+    block, including the observer persona name from the file header.
+
+    Args:
+        file_content: Full text content of the tandem observation file
+
+    Returns:
+        Dict with 'persona' and 'text' keys, or None if no observations found
+    """
+    # Extract persona from header: **Observer:** agent (Persona Name)
+    persona_match = re.search(r"\*\*Observer:\*\*\s*\w+\s*\(([^)]+)\)", file_content)
+    persona = persona_match.group(1) if persona_match else "Unknown"
+
+    # Split on observation headers: ## [HH:MM] Observation
+    entries = re.split(r"## \[\d{1,2}:\d{2}\] Observation\n", file_content)
+    if len(entries) < 2:
+        return None
+
+    # Last entry is the most recent observation
+    last_entry = entries[-1].strip()
+    # Remove trailing --- separator
+    last_entry = re.sub(r"\n---\s*$", "", last_entry).strip()
+    # Remove the **Trigger:** line
+    lines = last_entry.split("\n")
+    text_lines = [l for l in lines if not l.startswith("**Trigger:**")]
+    text = "\n".join(text_lines).strip()
+
+    if not text:
+        return None
+
+    return {"persona": persona, "text": text}
+
+
+def format_tandem_message(persona_name: str, observation_text: str) -> str:
+    """Format a tandem observation as a bell mode injection message.
+
+    Args:
+        persona_name: The backseat agent's persona name
+        observation_text: The observation summary text
+
+    Returns:
+        Formatted string: [Tandem] {persona_name}: {observation_text}
+    """
+    return f"[Tandem] {persona_name}: {observation_text}"
+
+
+def get_tandem_mtime(project_root: Path, agent: str) -> float:
+    """Read the last-checked mtime for a tandem agent's observation file.
+
+    Args:
+        project_root: Project root directory
+        agent: Agent name (e.g. 'reviewer', 'tea')
+
+    Returns:
+        Last-checked mtime as float, or 0.0 if no sidecar exists
+    """
+    sidecar = project_root / ".session" / f".tandem-mtime-{agent}"
+    if not sidecar.exists():
+        return 0.0
+    try:
+        return float(sidecar.read_text().strip())
+    except (ValueError, OSError):
+        return 0.0
+
+
+def save_tandem_mtime(project_root: Path, agent: str, mtime: float) -> None:
+    """Save the mtime for a tandem agent's observation file.
+
+    Writes to .session/.tandem-mtime-{agent} sidecar file.
+
+    Args:
+        project_root: Project root directory
+        agent: Agent name (e.g. 'reviewer', 'tea')
+        mtime: The mtime value to save
+    """
+    sidecar = project_root / ".session" / f".tandem-mtime-{agent}"
+    try:
+        sidecar.write_text(str(mtime))
+    except OSError:
+        pass
+
+
+def check_tandem_files(project_root: Path) -> list[dict]:
+    """Check for new tandem observations and return injection messages.
+
+    Main entry point for tandem injection in the PostToolUse hook.
+    Always active — no configuration required. The presence of tandem
+    observation files in .session/ is the only signal needed.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        List of dicts with 'agent', 'message' keys for each new observation
+    """
+    tandem_files = read_tandem_observations(project_root)
+    if not tandem_files:
+        return []
+
+    results = []
+    for obs_file in tandem_files:
+        # Extract agent name from filename: *-tandem-{agent}.md
+        agent_match = re.search(r"-tandem-(\w+)\.md$", obs_file.name)
+        if not agent_match:
+            continue
+        agent = agent_match.group(1)
+
+        # Compare mtime
+        try:
+            file_mtime = obs_file.stat().st_mtime
+        except OSError:
+            continue
+        saved_mtime = get_tandem_mtime(project_root, agent)
+        if file_mtime == saved_mtime:
+            continue
+
+        # Read and parse
+        try:
+            content = obs_file.read_text()
+        except OSError:
+            continue
+        obs = get_latest_observation(content)
+        if not obs:
+            # Update mtime even for unparseable files to avoid re-checking
+            save_tandem_mtime(project_root, agent, file_mtime)
+            continue
+
+        message = format_tandem_message(obs["persona"], obs["text"])
+        results.append({"agent": agent, "message": message})
+
+        # Update mtime sidecar
+        save_tandem_mtime(project_root, agent, file_mtime)
+
+    return results
+
+
 def main() -> None:
-    """Main entry point for PostToolUse bell mode hook."""
+    """Main entry point for PostToolUse hook."""
     try:
         # Read and discard stdin (required by hook protocol)
         sys.stdin.read()
@@ -117,35 +273,34 @@ def main() -> None:
         if not project_root:
             sys.exit(0)
 
-        # Check if bell mode is enabled
-        if not is_bell_mode_enabled(project_root):
-            sys.exit(0)
-
-        # Read queue
-        queue = read_bell_queue(project_root)
-        if not queue:
-            sys.exit(0)
-
-        # Get first message
-        first_message = queue[0]
-        message_text = first_message.get("text", "")
-        if not message_text:
-            sys.exit(0)
-
-        # Output hook response with additionalContext
-        output_hook_response(HookResponse(
-            event_name="PostToolUse",
-            additional_context=f"User feedback: {message_text}",
-        ))
-
-        # Dequeue message and notify Cyclist (in background-ish - after output)
-        dequeue_message(project_root)
-        notify_cyclist(project_root, message_text)
+        # --- Bell queue (Cyclist only, requires bell_mode: true) ---
+        # Takes precedence over tandem when active.
+        is_cyclist = read_port_file(CYCLIST_PORT_FILE, project_root) is not None
+        if is_cyclist and is_bell_mode_enabled(project_root):
+            queue = read_bell_queue(project_root)
+            if queue:
+                first_message = queue[0]
+                message_text = first_message.get("text", "")
+                if message_text:
+                    output_hook_response(HookResponse(
+                        event_name="PostToolUse",
+                        additional_context=f"User feedback: {message_text}",
+                    ))
+                    dequeue_message(project_root)
+                    notify_cyclist(project_root, message_text)
+                    sys.exit(0)
+
+        # --- Tandem observations (always active, no config required) ---
+        tandem_results = check_tandem_files(project_root)
+        if tandem_results:
+            output_hook_response(HookResponse(
+                event_name="PostToolUse",
+                additional_context=tandem_results[0]["message"],
+            ))
 
         sys.exit(0)
 
     except Exception as e:
-        # On error, exit silently
         print(f"[bellmode-hook] Error: {e}", file=sys.stderr)
         sys.exit(0)
 

package/pennyfarthing_scripts/brownfield/__init__.py

@@ -6,17 +6,17 @@ Analyzes existing codebases and generates AI-ready documentation.
 
 from pennyfarthing_scripts.brownfield.discover import (
     DepthLevel,
-    ProjectType,
     DiscoveryResult,
+    ProjectType,
+    detect_architecture_patterns,
     detect_project_type,
     detect_tech_stack,
-    scan_directory_structure,
-    detect_architecture_patterns,
+    discover,
+    generate_ai_guidance_doc,
     generate_project_overview,
-    generate_tech_stack_doc,
     generate_source_tree_doc,
-    generate_ai_guidance_doc,
-    discover,
+    generate_tech_stack_doc,
+    scan_directory_structure,
 )
 
 __all__ = [

package/pennyfarthing_scripts/brownfield/__main__.py

@@ -1,6 +1,7 @@
 """Entry point for python -m pennyfarthing_scripts.brownfield."""
 
 import sys
+
 from pennyfarthing_scripts.brownfield.cli import cli
 
 if __name__ == "__main__":

package/pennyfarthing_scripts/brownfield/cli.py

@@ -12,7 +12,6 @@ import argparse
 import asyncio
 import sys
 from pathlib import Path
-from typing import Any
 
 from pennyfarthing_scripts.brownfield.discover import (
     DepthLevel,

package/pennyfarthing_scripts/brownfield/discover.py

@@ -11,7 +11,6 @@ import re
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
-from typing import Literal
 
 # Try to import tomllib (Python 3.11+) or fall back to tomli
 try:
@@ -642,7 +641,7 @@ def generate_ai_guidance_doc(result: DiscoveryResult) -> str:
 
     if result.tech_stack:
         # Get unique tech names
-        tech_names = sorted(set(item.name.lower() for item in result.tech_stack))[:10]
+        tech_names = sorted({item.name.lower() for item in result.tech_stack})[:10]
         lines.extend([
             "## Key Technologies",
             "",

package/pennyfarthing_scripts/cli.py

@@ -31,20 +31,40 @@ def cli():
 
 
 # Import and register sprint group (lazy registration preserves startup time)
-from pennyfarthing_scripts.sprint.cli import sprint
+from pennyfarthing_scripts.sprint.cli import sprint  # noqa: E402
 
 cli.add_command(sprint)
 
 # Import and register hotspots group
-from pennyfarthing_scripts.hotspots.cli import hotspots
+from pennyfarthing_scripts.hotspots.cli import hotspots  # noqa: E402
 
 cli.add_command(hotspots)
 
 # Import and register jira group
-from pennyfarthing_scripts.jira.cli import jira
+from pennyfarthing_scripts.jira.cli import jira  # noqa: E402
 
 cli.add_command(jira)
 
+# Import and register deadcode group
+from pennyfarthing_scripts.deadcode.cli import deadcode  # noqa: E402
+
+cli.add_command(deadcode)
+
+# Import and register theme group
+from pennyfarthing_scripts.theme.cli import theme  # noqa: E402
+
+cli.add_command(theme)
+
+# Import and register healthscore group
+from pennyfarthing_scripts.healthscore.cli import healthscore  # noqa: E402
+
+cli.add_command(healthscore)
+
+# Import and register validate group
+from pennyfarthing_scripts.validate.cli import validate  # noqa: E402
+
+cli.add_command(validate)
+
 
 @cli.group()
 def agent():

package/pennyfarthing_scripts/codemarkers/__init__.py

@@ -0,0 +1,23 @@
+"""
+Code marker analysis — TODO, FIXME, HACK, XXX detection with git blame.
+
+Story 80-1: Python codemarkers module.
+Story 80-2: @deprecated detection and caller cross-reference.
+"""
+
+from pennyfarthing_scripts.codemarkers.analyze import analyze_deprecations, analyze_repo
+from pennyfarthing_scripts.codemarkers.models import (
+    CodeMarker,
+    CodeMarkersResult,
+    DeprecationMarker,
+    MarkerSummary,
+)
+
+__all__ = [
+    "CodeMarker",
+    "CodeMarkersResult",
+    "DeprecationMarker",
+    "MarkerSummary",
+    "analyze_deprecations",
+    "analyze_repo",
+]

package/pennyfarthing_scripts/codemarkers/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as: python -m pennyfarthing_scripts.codemarkers"""
+
+from pennyfarthing_scripts.codemarkers.cli import codemarkers
+
+if __name__ == "__main__":
+    codemarkers()