@pennyfarthing/core 11.1.1 → 11.2.0

package/pennyfarthing_scripts/consultation/cli.py

@@ -0,0 +1,149 @@
+"""Click CLI for consultation dialogue management.
+
+Provides `pf consultation` group with subcommands matching
+the bash wrapper dialogue-manager.sh interface.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def consultation():
+    """Tandem consultation dialogue management.
+
+    \b
+    Subcommands:
+      init       - Create dialogue file
+      append     - Append exchange
+      outcome    - Update outcome
+      summarize  - Refresh summary
+      archive    - Archive dialogue file
+    """
+    pass
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.argument("workflow")
+@click.argument("leader")
+@click.argument("partner")
+def init(story_id: str, workflow: str, leader: str, partner: str) -> None:
+    """Create a new dialogue file."""
+    from pennyfarthing_scripts.consultation.dialogue_manager import (
+        DialogueHeader,
+        create_dialogue_content,
+    )
+
+    header = DialogueHeader(
+        story_id=story_id,
+        workflow=workflow,
+        leader=leader,
+        partner=partner,
+        started_at=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    )
+
+    content = create_dialogue_content(header)
+    session_dir = Path(".session")
+    session_dir.mkdir(parents=True, exist_ok=True)
+    dialogue_path = session_dir / f"{story_id}-dialogue.md"
+    dialogue_path.write_text(content, encoding="utf-8")
+
+    click.echo(f"Created {dialogue_path}")
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.argument("question")
+@click.argument("recommendation")
+@click.argument("confidence")
+def append(story_id: str, question: str, recommendation: str, confidence: str) -> None:
+    """Append an exchange to a dialogue file."""
+    from pennyfarthing_scripts.consultation.dialogue_manager import (
+        DialogueExchange,
+        append_exchange_to_file,
+        parse_dialogue_exchanges,
+    )
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    if not dialogue_path.exists():
+        click.echo(f"Dialogue file not found: {dialogue_path}", err=True)
+        raise SystemExit(1)
+
+    content = dialogue_path.read_text(encoding="utf-8")
+    existing = parse_dialogue_exchanges(content)
+    next_num = len(existing) + 1
+
+    exchange = DialogueExchange(
+        number=next_num,
+        timestamp=datetime.now(timezone.utc).strftime("%H:%M"),
+        leader="",
+        partner="",
+        question=question,
+        recommendation=recommendation,
+        confidence=confidence,
+    )
+
+    result = append_exchange_to_file(dialogue_path, exchange)
+    if result.success:
+        click.echo(f"Appended exchange {next_num}")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.argument("exchange_num", type=int)
+@click.argument("outcome_value")
+@click.option("--note", default=None, help="Outcome note")
+def outcome(story_id: str, exchange_num: int, outcome_value: str, note: str | None) -> None:
+    """Update outcome of an exchange."""
+    from pennyfarthing_scripts.consultation.dialogue_manager import (
+        update_outcome_in_file,
+    )
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    result = update_outcome_in_file(dialogue_path, exchange_num, outcome_value, note)  # type: ignore[arg-type]
+    if result.success:
+        click.echo(f"Updated exchange {exchange_num} outcome to {outcome_value}")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+
+
+@consultation.command()
+@click.argument("story_id")
+def summarize(story_id: str) -> None:
+    """Refresh dialogue summary."""
+    from pennyfarthing_scripts.consultation.dialogue_manager import refresh_summary
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    result = refresh_summary(dialogue_path)
+    if result.success:
+        total = result.data.get("totalExchanges", 0) if result.data else 0
+        click.echo(f"Summary refreshed ({total} exchanges)")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)
+
+
+@consultation.command()
+@click.argument("story_id")
+@click.option("--jira-key", default=None, help="Jira key for archive filename")
+def archive(story_id: str, jira_key: str | None) -> None:
+    """Archive dialogue file."""
+    from pennyfarthing_scripts.consultation.dialogue_manager import archive_dialogue
+
+    dialogue_path = Path(".session") / f"{story_id}-dialogue.md"
+    archive_dir = Path(".session") / "archive"
+    result = archive_dialogue(dialogue_path, archive_dir, jira_key=jira_key, story_id=story_id)
+    if result.success:
+        click.echo(f"Archived to {result.data.get('archivePath', archive_dir)}" if result.data else "Archived")
+    else:
+        click.echo(f"Error: {result.error}", err=True)
+        raise SystemExit(1)

package/pennyfarthing_scripts/consultation/dialogue_manager.py

@@ -0,0 +1,417 @@
+"""Dialogue file management for tandem agent consultation.
+
+Persistence layer for consultation exchanges between tandem agents.
+Port of packages/core/src/consultation/dialogue-manager.ts to Python.
+
+All pure functions use the same markdown format defined in ADR-0012.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+Outcome = Literal["applied", "deferred", "rejected"]
+
+SUMMARY_MARKER = "## Summary"
+EXCHANGE_RE = re.compile(r"^## Exchange (\d+)")
+OUTCOME_RE = re.compile(r"^\*\*Outcome:\*\*\s+(.+)")
+DIRECTION_RE = re.compile(r"^\*\*\[(\d{2}:\d{2})\]\s+(\S+)\s+→\s+(\S+)\*\*")
+PARTNER_RESP_RE = re.compile(r"^\*\*\[(\d{2}:\d{2})\]\s+(\S+):\*\*")
+CONFIDENCE_RE = re.compile(r"^\*\*Confidence:\*\*\s+(\S+)")
+
+
+@dataclass
+class DialogueHeader:
+    story_id: str
+    workflow: str
+    leader: str
+    partner: str
+    leader_character: str | None = None
+    partner_character: str | None = None
+    started_at: str = ""
+
+
+@dataclass
+class DialogueExchange:
+    number: int
+    timestamp: str  # HH:MM
+    leader: str
+    partner: str
+    question: str
+    recommendation: str
+    confidence: str
+    outcome: Outcome | None = None
+    outcome_note: str | None = None
+
+
+@dataclass
+class DialogueResult:
+    success: bool
+    data: dict | None = None
+    error: str | None = None
+
+
+# =============================================================================
+# Pure Functions
+# =============================================================================
+
+
+def create_dialogue_content(header: DialogueHeader) -> str:
+    """Create initial dialogue file content with header and empty summary."""
+    leader_label = (
+        f"{header.leader} ({header.leader_character})"
+        if header.leader_character
+        else header.leader
+    )
+    partner_label = (
+        f"{header.partner} ({header.partner_character})"
+        if header.partner_character
+        else header.partner
+    )
+
+    return (
+        f"# Tandem Dialogue: {header.story_id}\n"
+        f"\n"
+        f"**Workflow:** {header.workflow}\n"
+        f"**Leader:** {leader_label} | **Partner:** {partner_label}\n"
+        f"**Started:** {header.started_at}\n"
+        f"\n"
+        f"---\n"
+        f"\n"
+        f"{SUMMARY_MARKER}\n"
+        f"- **Total exchanges:** 0\n"
+        f"- **Key decisions:** None\n"
+        f"- **Time in tandem:** 0m\n"
+    )
+
+
+def format_exchange(exchange: DialogueExchange) -> str:
+    """Format a single exchange as markdown block."""
+    if exchange.outcome:
+        outcome_text = f"**Outcome:** {exchange.outcome}"
+        if exchange.outcome_note:
+            outcome_text += f" - {exchange.outcome_note}"
+    else:
+        outcome_text = "**Outcome:** _pending_"
+
+    return (
+        f"## Exchange {exchange.number}\n"
+        f"**[{exchange.timestamp}] {exchange.leader} \u2192 {exchange.partner}**\n"
+        f"\n"
+        f"> {exchange.question}\n"
+        f"\n"
+        f"**[{exchange.timestamp}] {exchange.partner}:**\n"
+        f"\n"
+        f"{exchange.recommendation}\n"
+        f"\n"
+        f"**Confidence:** {exchange.confidence}\n"
+        f"\n"
+        f"{outcome_text}\n"
+        f"\n"
+        f"---\n"
+    )
+
+
+def parse_dialogue_exchanges(content: str) -> list[DialogueExchange]:
+    """Parse exchanges from dialogue file content."""
+    exchanges: list[DialogueExchange] = []
+    lines = content.split("\n")
+
+    current: dict | None = None
+    in_question = False
+    in_recommendation = False
+    question_lines: list[str] = []
+    rec_lines: list[str] = []
+
+    for line in lines:
+        # New exchange starts
+        m = EXCHANGE_RE.match(line)
+        if m:
+            if current is not None and "number" in current:
+                current["question"] = "\n".join(question_lines)
+                current["recommendation"] = "\n".join(rec_lines)
+                exchanges.append(DialogueExchange(**current))
+            current = {"number": int(m.group(1))}
+            question_lines = []
+            rec_lines = []
+            in_question = False
+            in_recommendation = False
+            continue
+
+        if current is None:
+            continue
+
+        # Leader → Partner direction line
+        dm = DIRECTION_RE.match(line)
+        if dm:
+            current["timestamp"] = dm.group(1)
+            current["leader"] = dm.group(2)
+            current["partner"] = dm.group(3)
+            in_question = True
+            in_recommendation = False
+            continue
+
+        # Partner response line
+        pm = PARTNER_RESP_RE.match(line)
+        if pm:
+            in_question = False
+            in_recommendation = True
+            continue
+
+        # Confidence line
+        cm = CONFIDENCE_RE.match(line)
+        if cm:
+            current["confidence"] = cm.group(1)
+            in_recommendation = False
+            continue
+
+        # Outcome line
+        om = OUTCOME_RE.match(line)
+        if om:
+            outcome_raw = om.group(1).strip()
+            if outcome_raw != "_pending_":
+                dash_idx = outcome_raw.find(" - ")
+                if dash_idx >= 0:
+                    current["outcome"] = outcome_raw[:dash_idx].strip()
+                    current["outcome_note"] = outcome_raw[dash_idx + 3 :].strip()
+                else:
+                    current["outcome"] = outcome_raw
+            in_recommendation = False
+            continue
+
+        # Collect question text (blockquote lines)
+        if in_question:
+            stripped = line[2:] if line.startswith("> ") else line
+            if stripped.strip():
+                question_lines.append(stripped)
+            continue
+
+        # Collect recommendation text
+        if in_recommendation:
+            if line.strip():
+                rec_lines.append(line)
+            continue
+
+    # Push last exchange
+    if current is not None and "number" in current:
+        current["question"] = "\n".join(question_lines)
+        current["recommendation"] = "\n".join(rec_lines)
+        exchanges.append(DialogueExchange(**current))
+
+    return exchanges
+
+
+def generate_summary(exchanges: list[DialogueExchange], started_at: str) -> str:
+    """Generate summary markdown section from exchanges."""
+    total = len(exchanges)
+
+    # Key decisions from applied outcomes
+    applied = [e for e in exchanges if e.outcome == "applied" and e.outcome_note]
+    if applied:
+        decisions_text = "\n".join(f"  - {e.outcome_note}" for e in applied)
+    else:
+        decisions_text = "None"
+
+    # Time in tandem: span between first and last exchange timestamps
+    duration = "0m"
+    if exchanges:
+        first = _parse_time(exchanges[0].timestamp)
+        last = _parse_time(exchanges[-1].timestamp)
+        if first is not None and last is not None:
+            mins = last - first
+            duration = f"{mins}m" if mins > 0 else "0m"
+
+    return (
+        f"{SUMMARY_MARKER}\n"
+        f"- **Total exchanges:** {total}\n"
+        f"- **Key decisions:**\n"
+        f"{decisions_text}\n"
+        f"- **Time in tandem:** {duration}\n"
+    )
+
+
+# =============================================================================
+# File Operations
+# =============================================================================
+
+
+def append_exchange_to_file(
+    dialogue_path: Path,
+    exchange: DialogueExchange,
+    header: DialogueHeader | None = None,
+) -> DialogueResult:
+    """Append an exchange to a dialogue file. Creates the file if missing."""
+    try:
+        if not dialogue_path.exists():
+            if not header:
+                return DialogueResult(
+                    success=False, error="Header required for new dialogue file"
+                )
+            initial = create_dialogue_content(header)
+            dialogue_path.parent.mkdir(parents=True, exist_ok=True)
+            dialogue_path.write_text(initial, encoding="utf-8")
+
+        content = dialogue_path.read_text(encoding="utf-8")
+        formatted = format_exchange(exchange)
+
+        # Insert exchange before summary section
+        summary_idx = content.find(SUMMARY_MARKER)
+        if summary_idx < 0:
+            dialogue_path.write_text(
+                content + "\n" + formatted, encoding="utf-8"
+            )
+        else:
+            before = content[:summary_idx]
+            after = content[summary_idx:]
+            dialogue_path.write_text(
+                before + formatted + "\n" + after, encoding="utf-8"
+            )
+
+        return DialogueResult(
+            success=True, data={"exchangeNumber": exchange.number}
+        )
+    except Exception as err:
+        return DialogueResult(
+            success=False, error=f"Failed to append exchange: {err}"
+        )
+
+
+def update_outcome_in_file(
+    dialogue_path: Path,
+    exchange_num: int,
+    outcome: Outcome,
+    note: str | None = None,
+) -> DialogueResult:
+    """Update the outcome of a specific exchange in the dialogue file."""
+    try:
+        if not dialogue_path.exists():
+            return DialogueResult(
+                success=False,
+                error=f"Dialogue file not found: {dialogue_path}",
+            )
+
+        content = dialogue_path.read_text(encoding="utf-8")
+        lines = content.split("\n")
+
+        in_target = False
+        found = False
+
+        for i, line in enumerate(lines):
+            em = EXCHANGE_RE.match(line)
+            if em:
+                in_target = int(em.group(1)) == exchange_num
+
+            if in_target and OUTCOME_RE.match(line):
+                outcome_text = f"**Outcome:** {outcome}"
+                if note:
+                    outcome_text += f" - {note}"
+                lines[i] = outcome_text
+                found = True
+                break
+
+        if not found:
+            return DialogueResult(
+                success=False,
+                error=f"Exchange {exchange_num} not found in dialogue file",
+            )
+
+        dialogue_path.write_text("\n".join(lines), encoding="utf-8")
+        return DialogueResult(
+            success=True, data={"exchangeNum": exchange_num, "outcome": outcome}
+        )
+    except Exception as err:
+        return DialogueResult(
+            success=False, error=f"Failed to update outcome: {err}"
+        )
+
+
+def refresh_summary(dialogue_path: Path) -> DialogueResult:
+    """Regenerate the summary section in an existing dialogue file."""
+    try:
+        if not dialogue_path.exists():
+            return DialogueResult(
+                success=False,
+                error=f"Dialogue file not found: {dialogue_path}",
+            )
+
+        content = dialogue_path.read_text(encoding="utf-8")
+        exchanges = parse_dialogue_exchanges(content)
+
+        # Extract startedAt from header
+        started_match = re.search(r"\*\*Started:\*\*\s+(.+)", content)
+        started_at = (
+            started_match.group(1).strip() if started_match else ""
+        )
+
+        new_summary = generate_summary(exchanges, started_at)
+
+        # Replace existing summary section
+        summary_idx = content.find(SUMMARY_MARKER)
+        if summary_idx < 0:
+            dialogue_path.write_text(
+                content + "\n" + new_summary, encoding="utf-8"
+            )
+        else:
+            before = content[:summary_idx]
+            dialogue_path.write_text(before + new_summary, encoding="utf-8")
+
+        return DialogueResult(
+            success=True, data={"totalExchanges": len(exchanges)}
+        )
+    except Exception as err:
+        return DialogueResult(
+            success=False, error=f"Failed to refresh summary: {err}"
+        )
+
+
+def archive_dialogue(
+    dialogue_path: Path,
+    archive_dir: Path,
+    jira_key: str | None = None,
+    story_id: str | None = None,
+) -> DialogueResult:
+    """Copy dialogue file to archive directory."""
+    try:
+        if not dialogue_path.exists():
+            return DialogueResult(
+                success=False,
+                error=f"Dialogue file not found: {dialogue_path}",
+            )
+
+        archive_dir.mkdir(parents=True, exist_ok=True)
+
+        prefix = jira_key or story_id or "unknown"
+        archive_name = f"{prefix}-dialogue.md"
+        archive_path = archive_dir / archive_name
+
+        shutil.copy2(dialogue_path, archive_path)
+
+        return DialogueResult(
+            success=True, data={"archivePath": str(archive_path)}
+        )
+    except Exception as err:
+        return DialogueResult(
+            success=False, error=f"Failed to archive dialogue: {err}"
+        )
+
+
+# =============================================================================
+# Internal Helpers
+# =============================================================================
+
+
+def _parse_time(timestamp: str) -> int | None:
+    """Parse HH:MM timestamp to minutes since midnight."""
+    parts = timestamp.split(":")
+    if len(parts) != 2:
+        return None
+    try:
+        hours = int(parts[0])
+        minutes = int(parts[1])
+    except ValueError:
+        return None
+    return hours * 60 + minutes

package/pennyfarthing_scripts/context.py

@@ -269,7 +269,7 @@ def detect_cyclist(project_dir: str | None = None) -> bool:
 
     Checks:
     1. CYCLIST env var set to '1' (Electron mode - definitive)
-    2. .cyclist-port file exists AND port is responding (Web mode)
+    2. .wheelhub-port file exists AND port is responding (Web mode)
     """
     # Env var is definitive - set by Cyclist when it spawns Claude
     if os.environ.get("CYCLIST") == "1":
@@ -284,8 +284,8 @@ def detect_cyclist(project_dir: str | None = None) -> bool:
     )
 
     port_files = [
-        Path(project_dir) / "packages" / "cyclist" / ".cyclist-port",
-        Path(os.getcwd()) / ".cyclist-port",
+        Path(project_dir) / "packages" / "cyclist" / ".wheelhub-port",
+        Path(os.getcwd()) / ".wheelhub-port",
     ]
 
     for port_file in port_files:

package/pennyfarthing_scripts/git/__init__.py

@@ -4,14 +4,22 @@ Git utilities for Pennyfarthing.
 Story: MSSCI-12402 - Port git utility scripts to Python
 
 This package provides async git operations for multi-repo management:
+- repos: Repository configuration from repos.yaml
 - status_all: Check git status across all repos in parallel
 - create_branches: Create feature branches across repos in parallel
+- worktree: Git worktree management for parallel development
+- hooks_installer: Git hooks installation with .d/ dispatcher pattern
 """
 
 from pennyfarthing_scripts.git.create_branches import (
     BranchResult,
     create_feature_branches,
 )
+from pennyfarthing_scripts.git.repos import (
+    RepoConfig,
+    get_repo_paths,
+    load_repos_config,
+)
 from pennyfarthing_scripts.git.status_all import (
     RepoStatus,
     format_status_brief,
@@ -20,10 +28,13 @@ from pennyfarthing_scripts.git.status_all import (
 )
 
 __all__ = [
+    "RepoConfig",
     "RepoStatus",
+    "BranchResult",
     "get_all_repo_status",
     "format_status_brief",
     "format_status_full",
-    "BranchResult",
     "create_feature_branches",
+    "load_repos_config",
+    "get_repo_paths",
 ]

package/pennyfarthing_scripts/git/create_branches.py

@@ -395,7 +395,7 @@ async def main(branch_name: str, repos_filter: RepoFilter = "all") -> int:
     Returns:
         0 if all repos succeeded, 1 if any had errors
     """
-    from pennyfarthing_scripts.common.config import get_project_root
+    from pennyfarthing_scripts.git.repos import get_repo_paths
 
     # Detect worktree
     is_worktree, worktree_name, base_path = detect_worktree()
@@ -405,9 +405,8 @@ async def main(branch_name: str, repos_filter: RepoFilter = "all") -> int:
     else:
         print("📂 Using main checkout")
 
-    # For now, just use the current project
-    project_root = get_project_root()
-    repos = [("pennyfarthing", project_root)]
+    # Load repos from configuration
+    repos = get_repo_paths()
 
     # Apply filter
     filtered_repos = filter_repos(repos, repos_filter)