@pennyfarthing/core 10.1.0 → 10.3.0

package/pennyfarthing_scripts/preflight/finish.py

@@ -8,7 +8,6 @@ concurrent execution regardless of model behavior.
 import asyncio
 import json
 import re
-import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any

package/pennyfarthing_scripts/pretooluse_hook.py

@@ -40,15 +40,14 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from hooks import (
-    find_project_root,
-    get_cyclist_port,
-    send_to_cyclist,
-    read_stdin_json,
-    output_hook_response,
     HookResponse,
-    load_settings,
-    is_cyclist_running,
+    find_project_root,
     get_context_state,
+    is_cyclist_running,
+    load_settings,
+    output_hook_response,
+    read_stdin_json,
+    send_to_cyclist,
 )
 
 

package/pennyfarthing_scripts/prime/__init__.py

@@ -47,6 +47,7 @@ from pennyfarthing_scripts.prime.loader import (
     load_agent_definition,
     load_behavior_guide,
     load_domain_docs,
+    load_repos_topology,
     load_session_context,
     load_sidecars,
     load_sprint_context,
@@ -94,6 +95,7 @@ __all__ = [
     "load_session_context",
     "load_sidecars",
     "load_domain_docs",
+    "load_repos_topology",
     # Workflow detection
     "detect_workflow_state",
     "check_redirect",

package/pennyfarthing_scripts/prime/cli.py

@@ -22,6 +22,10 @@ import argparse
 import json
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
 
 from pennyfarthing_scripts.common.config import get_project_root
 from pennyfarthing_scripts.prime.loader import (
@@ -42,7 +46,7 @@ from pennyfarthing_scripts.prime.persona import (
     load_persona,
 )
 from pennyfarthing_scripts.prime.session import cleanup_old_sessions, register_session
-from pennyfarthing_scripts.prime.tiers import ContextTier, tier_from_string, load_tier_components
+from pennyfarthing_scripts.prime.tiers import ContextTier, load_tier_components, tier_from_string
 from pennyfarthing_scripts.prime.workflow import check_redirect, detect_workflow_state
 
 
@@ -98,6 +102,7 @@ def _component_header(name: str, agent_name: str | None) -> str:
         "persona_compressed": f"Persona: {agent_name} (compressed)",
         "behavior_guide": "Agent Behavior Guide",
         "sprint_context": "Sprint Context",
+        "repos_topology": "Repos Topology",
         "session_header": "Active Session",
         "session_assessment": "Session Assessment",
         "sidecars": f"Agent Sidecar: {agent_name}",
@@ -114,6 +119,7 @@ def _component_source(name: str, agent_name: str | None, root: Path) -> str | No
         "persona_compressed": None,
         "behavior_guide": ".pennyfarthing/guides/agent-behavior.md",
         "sprint_context": "sprint/current-sprint.yaml",
+        "repos_topology": ".pennyfarthing/repos.yaml",
         "session_header": None,
         "session_assessment": None,
         "sidecars": f".pennyfarthing/sidecars/{agent_name}/",
@@ -470,6 +476,17 @@ def prime(
             _print_header("Sprint Context", quiet)
             print(sprint_content)
 
+    # ==========================================================================
+    # PRIORITY 5.5: Repos Topology
+    # ==========================================================================
+    if not json_output:
+        from pennyfarthing_scripts.prime.loader import load_repos_topology
+
+        topology_content = load_repos_topology(root)
+        if topology_content:
+            _print_header("Repos Topology", quiet)
+            print(topology_content)
+
     # ==========================================================================
     # PRIORITY 6: Session context
     # ==========================================================================

package/pennyfarthing_scripts/prime/loader.py

@@ -14,7 +14,6 @@ from __future__ import annotations
 
 import re
 from pathlib import Path
-from typing import Any
 
 from pennyfarthing_scripts.common.config import get_project_root
 
@@ -68,7 +67,7 @@ def load_sprint_context(project_root: Path | None = None) -> str | None:
         Formatted sprint summary, or None if no sprint data
     """
     # Import here to avoid circular imports
-    from pennyfarthing_scripts.sprint.loader import load_sprint, get_sprint_info
+    from pennyfarthing_scripts.sprint.loader import load_sprint
     from pennyfarthing_scripts.sprint.status import get_sprint_status
 
     root = project_root or get_project_root()
@@ -136,7 +135,7 @@ def _extract_session_parts(content: str) -> tuple[str, str]:
 
     # Header: everything before first ## heading
     header_lines = []
-    for i, line in enumerate(lines):
+    for line in lines:
         if line.startswith("## "):
             break
         header_lines.append(line)
@@ -237,3 +236,73 @@ def load_domain_docs(project_root: Path | None = None) -> list[tuple[str, str]]:
         docs.append((doc_file.name, doc_file.read_text()))
 
     return docs
+
+
+def load_repos_topology(project_root: Path | None = None) -> str | None:
+    """Load repos.yaml topology as formatted context for agents.
+
+    Reads .pennyfarthing/repos.yaml and formats the topology fields
+    (owns, never_edit, symlinks, ui_layer, components_path) as a
+    readable manifest for agent spatial awareness.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Formatted topology context string, or None if unavailable
+    """
+    import yaml
+
+    root = project_root or get_project_root()
+    repos_file = root / ".pennyfarthing" / "repos.yaml"
+
+    if not repos_file.exists():
+        return None
+
+    try:
+        data = yaml.safe_load(repos_file.read_text())
+    except Exception:
+        return None
+
+    if not isinstance(data, dict) or "repos" not in data:
+        return None
+
+    repos = data["repos"]
+    if not repos:
+        return None
+
+    lines: list[str] = []
+    for name, config in repos.items():
+        lines.append(f"## {name}")
+        if config.get("path"):
+            lines.append(f"Path: {config['path']}")
+        if config.get("type"):
+            lines.append(f"Type: {config['type']}")
+        if config.get("description"):
+            lines.append(f"Description: {config['description']}")
+
+        owns = config.get("owns", [])
+        if owns:
+            lines.append(f"Owns: {', '.join(owns)}")
+
+        never_edit = config.get("never_edit", [])
+        if never_edit:
+            lines.append(f"Never Edit: {', '.join(never_edit)}")
+
+        symlinks = config.get("symlinks", {})
+        if symlinks:
+            lines.append("Symlinks:")
+            for src, dest in symlinks.items():
+                lines.append(f"  {src} → {dest}")
+
+        ui_layer = config.get("ui_layer")
+        if ui_layer:
+            lines.append(f"UI Layer: {ui_layer}")
+
+        components_path = config.get("components_path")
+        if components_path:
+            lines.append(f"Components: {components_path}")
+
+        lines.append("")
+
+    return "\n".join(lines).strip() if lines else None

package/pennyfarthing_scripts/prime/persona.py

@@ -14,15 +14,17 @@ import yaml
 from pennyfarthing_scripts.common.config import get_project_root, load_yaml_config
 from pennyfarthing_scripts.common.themes import (
     get_current_theme as _get_current_theme,
+)
+from pennyfarthing_scripts.common.themes import (
     resolve_theme_path,
 )
 from pennyfarthing_scripts.prime.models import CrewMember, Persona
 
-
 # Standard agent roles for crew manifest
 AGENT_ROLES = [
     "sm", "tea", "dev", "reviewer", "architect",
     "pm", "tech-writer", "ux-designer", "devops", "orchestrator",
+    "ba",
 ]
 
 
@@ -128,7 +130,7 @@ def get_crew_manifest(project_root: Path | None = None) -> list[CrewMember]:
         project_root: Project root path (auto-detected if not provided)
 
     Returns:
-        List of CrewMember objects for all 10 standard roles
+        List of CrewMember objects for all 11 standard roles
     """
     root = project_root or get_project_root()
     theme = get_current_theme(root)

package/pennyfarthing_scripts/prime/tiers.py

@@ -35,21 +35,22 @@ def estimate_tokens(text: str) -> int:
     return max(1, len(text) // 4)
 
 
-from pennyfarthing_scripts.prime.loader import (
+from pennyfarthing_scripts.prime.loader import (  # noqa: E402
     load_agent_definition,
     load_behavior_guide,
+    load_repos_topology,
     load_session_context,
     load_sidecars,
     load_sprint_context,
 )
-from pennyfarthing_scripts.prime.persona import (
+from pennyfarthing_scripts.prime.persona import (  # noqa: E402
     format_persona_compressed,
     get_crew_manifest,
     get_user_title,
     is_character_voice_enabled,
     load_persona,
 )
-from pennyfarthing_scripts.prime.workflow import detect_workflow_state
+from pennyfarthing_scripts.prime.workflow import detect_workflow_state  # noqa: E402
 
 
 class ContextTier(Enum):
@@ -78,7 +79,7 @@ def tier_from_string(value: str) -> ContextTier:
         return ContextTier(normalized)
     except ValueError:
         valid = ", ".join(t.value for t in ContextTier)
-        raise ValueError(f"Invalid tier '{value}'. Must be one of: {valid}")
+        raise ValueError(f"Invalid tier '{value}'. Must be one of: {valid}") from None
 
 
 def load_tier_components(
@@ -134,6 +135,10 @@ def load_tier_components(
         if sprint_content:
             add_component("sprint_context", sprint_content)
 
+        topology_content = load_repos_topology(project_root)
+        if topology_content:
+            add_component("repos_topology", topology_content)
+
         session_result = load_session_context(project_root)
         if session_result:
             filename, header, _ = session_result
@@ -156,6 +161,10 @@ def load_tier_components(
                 compressed = format_persona_compressed(persona, theme, agent_name)
                 add_component("persona_compressed", compressed)
 
+        topology_content = load_repos_topology(project_root)
+        if topology_content:
+            add_component("repos_topology", topology_content)
+
         components["token_counts"] = token_counts
         components["total_tokens"] = sum(token_counts.values())
         return components
@@ -185,6 +194,10 @@ def load_tier_components(
     if sprint_content:
         add_component("sprint_context", sprint_content)
 
+    topology_content = load_repos_topology(project_root)
+    if topology_content:
+        add_component("repos_topology", topology_content)
+
     session_result = load_session_context(project_root)
     if session_result:
         filename, header, assessment = session_result

package/pennyfarthing_scripts/schema_validation_hook.py

@@ -29,12 +29,11 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent))
 
 from hooks import (
-    read_stdin_json,
-    output_hook_response,
     HookResponse,
+    output_hook_response,
+    read_stdin_json,
 )
 
-
 # =============================================================================
 # File Type Detection
 # =============================================================================

package/pennyfarthing_scripts/sprint/__init__.py

@@ -18,6 +18,16 @@ Usage:
 """
 
 # Re-export from loader for backwards compatibility
+# Import submodules to make them accessible
+# CLI entry point - import module, not function, so "from sprint import cli" gets the module
+from pennyfarthing_scripts.sprint import (
+    archive,
+    cli,
+    loader,
+    status,
+    work,
+)
+from pennyfarthing_scripts.sprint.cli import main
 from pennyfarthing_scripts.sprint.loader import (
     find_epic,
     find_story,
@@ -31,18 +41,6 @@ from pennyfarthing_scripts.sprint.loader import (
     load_sprint,
 )
 
-# Import submodules to make them accessible
-from pennyfarthing_scripts.sprint import (
-    archive,
-    loader,
-    status,
-    work,
-)
-
-# CLI entry point - import module, not function, so "from sprint import cli" gets the module
-from pennyfarthing_scripts.sprint import cli
-from pennyfarthing_scripts.sprint.cli import main
-
 __all__ = [
     # Loader functions
     "find_epic",

package/pennyfarthing_scripts/sprint/__main__.py

@@ -4,7 +4,7 @@ Entry point for python -m pennyfarthing_scripts.sprint
 
 import sys
 
-from pennyfarthing_scripts.sprint.cli import cli
+from pennyfarthing_scripts.sprint.cli import sprint
 
 if __name__ == "__main__":
-    sys.exit(cli())
+    sys.exit(sprint())

package/pennyfarthing_scripts/sprint/archive.py

@@ -4,7 +4,6 @@ Sprint story archiving.
 Provides functions for archiving completed stories.
 """
 
-from pathlib import Path
 from typing import Any
 
 from pennyfarthing_scripts.common.config import get_project_root

package/pennyfarthing_scripts/sprint/archive_epic.py

@@ -18,7 +18,6 @@ from pennyfarthing_scripts.sprint.yaml_io import (
     _read_yaml_file,
     _write_yaml_file,
     read_sprint,
-    write_sprint,
 )
 
 
@@ -252,13 +251,11 @@ def archive_epic(
 
     # Find the epic in merged data
     epic = None
-    epic_index = None
-    for i, e in enumerate(sprint_data["epics"]):
+    for e in sprint_data["epics"]:
         eid = str(e.get("id", ""))
         ejira = str(e.get("jira", ""))
         if eid == epic_id or ejira == epic_id:
             epic = e
-            epic_index = i
             break
 
     if not epic:

package/pennyfarthing_scripts/sprint/cli.py

@@ -150,7 +150,7 @@ def work(story_id: str | None, dry_run: bool):
         click.echo(f"Story: {story.get('id')}")
         click.echo(f"Title: {story.get('title')}")
         click.echo(f"Points: {story.get('points')}")
-        click.echo(f"Status: Available")
+        click.echo("Status: Available")
     else:
         error_msg = result.get("error") or result.get("reason")
         raise click.ClickException(f"Not available: {error_msg}")
@@ -334,12 +334,12 @@ def story_claim(story_id: str, claim: bool):
 
 
 # Register story-add as story.add
-from pennyfarthing_scripts.sprint.story_add import story_add_command
+from pennyfarthing_scripts.sprint.story_add import story_add_command  # noqa: E402
 
 story.add_command(story_add_command, "add")
 
 # Register story-update as story.update
-from pennyfarthing_scripts.sprint.story_update import story_update_command
+from pennyfarthing_scripts.sprint.story_update import story_update_command  # noqa: E402
 
 story.add_command(story_update_command, "update")
 
@@ -501,7 +501,6 @@ def epic_cancel(epic_id: str, jira: bool, dry_run: bool):
       pf sprint epic cancel epic-42 --jira
     """
     from pennyfarthing_scripts.common.config import get_project_root
-    from pennyfarthing_scripts.sprint.loader import load_sprint
     from pennyfarthing_scripts.sprint.yaml_io import read_sprint, write_sprint
 
     root = get_project_root()
@@ -583,7 +582,7 @@ def _cancel_epic_in_initiatives(epic_id: str, root, *, jira: bool, dry_run: bool
         init_name = init_data.get("name", init_file.stem)
         epics = init_data.get("epics", [])
 
-        for i, e in enumerate(epics):
+        for _i, e in enumerate(epics):
             matched = False
             epic_dict = None
 
@@ -663,6 +662,8 @@ def epic_archive(epic_id: str | None, dry_run: bool, jira: bool):
     # Lazy import
     from pennyfarthing_scripts.sprint.archive_epic import (
         archive_all_completed,
+    )
+    from pennyfarthing_scripts.sprint.archive_epic import (
         archive_epic as do_archive_epic,
     )
 
@@ -757,7 +758,6 @@ def epic_remove(epic_id: str, dry_run: bool):
       pf sprint epic remove epic-41
       pf sprint epic remove epic-41 --dry-run
     """
-    from pathlib import Path
 
     import yaml
 
@@ -886,20 +886,23 @@ def epic_promote(epic_id: str):
     new_epic_id = original_id
     existing_ids = {str(e.get("id", "")) for e in sprint_data["epics"] if isinstance(e, dict)}
 
+    # Normalize to numeric ID (ADR-0022: strip epic- prefix from values)
+    new_epic_id = new_epic_id.replace("epic-", "") if new_epic_id.startswith("epic-") else new_epic_id
+
     if new_epic_id in existing_ids:
         max_num = 0
         for eid in existing_ids:
-            if eid.startswith("epic-"):
-                try:
-                    max_num = max(max_num, int(eid.replace("epic-", "")))
-                except ValueError:
-                    pass
-        new_epic_id = f"epic-{max_num + 1}"
+            clean_eid = eid.replace("epic-", "") if eid.startswith("epic-") else eid
+            try:
+                max_num = max(max_num, int(clean_eid))
+            except ValueError:
+                pass
+        new_epic_id = str(max_num + 1)
         click.echo(f"Warning: Epic ID {original_id} already exists. Assigning new ID: {new_epic_id}")
 
     # Transform epic for current sprint
     old_id_num = original_id.replace("epic-", "")
-    new_id_num = new_epic_id.replace("epic-", "")
+    new_id_num = new_epic_id.replace("epic-", "") if new_epic_id.startswith("epic-") else new_epic_id
 
     epic_data["id"] = new_epic_id
     epic_data["status"] = "backlog"
@@ -928,6 +931,13 @@ def epic_promote(epic_id: str):
     click.echo(f"  Stories: {story_count}")
     click.echo("")
 
+    # Validate epic shard before writing (ADR-0022)
+    from pennyfarthing_scripts.sprint.validator import validate_epic_shard
+    validation = validate_epic_shard(dict(epic_data))
+    if not validation.valid:
+        error_msgs = "; ".join(e.message for e in validation.errors)
+        raise click.ClickException(f"Epic validation failed: {error_msgs}")
+
     # Append to sprint
     sprint_data["epics"].append(epic_data)
 
@@ -960,7 +970,6 @@ def epic_promote(epic_id: str):
         click.echo(f"Removed {original_id} from {source_init_file.name}")
     else:
         # Initiative is empty — remove shard and future.yaml reference
-        init_name = init_data.get("name", "")
         init_slug = source_init_file.stem.replace("initiative-", "")
         source_init_file.unlink()
         click.echo(f"Removed empty initiative shard: {source_init_file.name}")
@@ -987,7 +996,7 @@ def epic_promote(epic_id: str):
 
 
 # Register epic-add as epic.add
-from pennyfarthing_scripts.sprint.epic_add import epic_add_command
+from pennyfarthing_scripts.sprint.epic_add import epic_add_command  # noqa: E402
 
 epic.add_command(epic_add_command, "add")
 
@@ -1161,7 +1170,7 @@ def initiative_cancel(name: str, jira: bool, dry_run: bool):
         return
 
     # Cancel all epics
-    for i, e in enumerate(epics):
+    for _i, e in enumerate(epics):
         if isinstance(e, str):
             shard = _epic_shard_path(sprint_dir, e)
             if shard.exists():
@@ -1216,7 +1225,6 @@ def check(id: str):
 
     from pennyfarthing_scripts.sprint.loader import (
         find_epic,
-        get_all_stories,
         load_sprint,
     )
     from pennyfarthing_scripts.sprint.work import check_story, get_next_story
@@ -1328,10 +1336,10 @@ def _find_epic_for_story(data: dict | None, story_id: str) -> str:
 
 @sprint.command()
 def info():
-    """Output sprint info as JSON for Cyclist sidebar.
+    """Output sprint info as JSON.
 
     \b
-    Returns: {"remaining": N, "inProgress": N, "endDate": "YYYY-MM-DD"}
+    Returns sprint header fields plus computed story point totals.
     """
     import json
 
@@ -1340,8 +1348,6 @@ def info():
     sprint_data = get_sprint_info()
     stories = get_all_stories()
 
-    end_date = sprint_data.get("end_date")
-
     remaining = sum(
         s.get("points", 0) or 0
         for s in stories
@@ -1353,11 +1359,11 @@ def info():
         if s.get("status") == "in_progress"
     )
 
-    click.echo(json.dumps({
-        "remaining": remaining,
-        "inProgress": in_progress,
-        "endDate": str(end_date) if end_date else None,
-    }))
+    result = {str(k): str(v) if hasattr(v, 'isoformat') else v for k, v in sprint_data.items()}
+    result["remaining"] = remaining
+    result["inProgress"] = in_progress
+
+    click.echo(json.dumps(result))
 
 
 # --- Metrics command (replaces sprint-metrics.sh) ---
@@ -1783,7 +1789,7 @@ completed:
     click.echo(f"Created {archive_file}")
 
     click.echo("")
-    click.echo(f"New sprint initialized:")
+    click.echo("New sprint initialized:")
     click.echo(f"  Name: TO Sprint {sprint_yyww}")
     click.echo(f"  Jira ID: {jira_id}")
     click.echo(f"  Dates: {start_date} to {end_date}")
@@ -1854,7 +1860,7 @@ sprint.commands["epic-add"].hidden = True
 
 
 # Register validate command from validate_cmd module
-from pennyfarthing_scripts.sprint.validate_cmd import validate_command
+from pennyfarthing_scripts.sprint.validate_cmd import validate_command  # noqa: E402
 
 sprint.add_command(validate_command)
 

package/pennyfarthing_scripts/sprint/epic_add.py

@@ -14,11 +14,12 @@ from typing import Any
 import click
 from ruamel.yaml.comments import CommentedMap, CommentedSeq
 
+from pennyfarthing_scripts.sprint import validator as _shard_validator
 from pennyfarthing_scripts.sprint.yaml_io import (
     EPIC_KEY_ORDER,
+    _get_epic_ref,
     _read_yaml_file,
     _write_yaml_file,
-    _get_epic_ref,
 )
 
 
@@ -76,6 +77,12 @@ def add_epic(
         if key not in EPIC_KEY_ORDER:
             epic[key] = fields[key]
 
+    # Validate epic shard before writing
+    validation = _shard_validator.validate_epic_shard(dict(epic))
+    if not validation.valid:
+        error_msgs = "; ".join(e.message for e in validation.errors)
+        return {"success": False, "error": f"Epic validation failed: {error_msgs}"}
+
     # Determine the shard reference
     ref = _get_epic_ref(epic)
     shard_file = sprint_dir / f"epic-{ref}.yaml"