@pennyfarthing/core 11.1.1 → 11.2.1

package/pennyfarthing_scripts/schema_validation_hook.py

@@ -1,305 +1,10 @@
-#!/usr/bin/env python3
 """
-XML Schema Validation Hook for PreToolUse.
+Backward-compatibility shim — schema validation hook moved to hooks/schema_validation.py.
 
-Validates session, skill, and workflow step files on Write/Edit operations.
-Blocks the tool call if validation fails, providing immediate feedback.
-
-Usage in settings.json:
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Write|Edit",
-      "hooks": [{
-        "type": "command",
-        "command": "python3 -m pennyfarthing_scripts.schema_validation_hook"
-      }]
-    }]
-  }
-}
-
-Story: XML Schema Migration Tools
+This file will be removed in a future version.
 """
 
-import re
-import sys
-from pathlib import Path
-
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent))
-
-from hooks import (
-    HookResponse,
-    output_hook_response,
-    read_stdin_json,
-)
-
-# =============================================================================
-# File Type Detection
-# =============================================================================
-
-
-def is_session_file(file_path: str) -> bool:
-    """Check if path is a session file."""
-    return file_path.endswith("-session.md") and ".session/" in file_path
-
-
-def is_skill_file(file_path: str) -> bool:
-    """Check if path is a skill SKILL.md file."""
-    return file_path.endswith("/SKILL.md") and "/skills/" in file_path
-
-
-def is_step_file(file_path: str) -> bool:
-    """Check if path is a workflow step file."""
-    path = Path(file_path)
-    return (
-        path.name.startswith("step-")
-        and path.name.endswith(".md")
-        and "/workflows/" in file_path
-        and "/steps/" in file_path
-    )
-
-
-def get_file_type(file_path: str) -> str | None:
-    """Detect file type from path."""
-    if is_session_file(file_path):
-        return "session"
-    elif is_skill_file(file_path):
-        return "skill"
-    elif is_step_file(file_path):
-        return "step"
-    return None
-
-
-# =============================================================================
-# Content-Based Validation (inline to avoid import issues)
-# =============================================================================
-
-# Skill required tags
-SKILL_REQUIRED_TAGS = ["run", "output"]
-
-# Workflow step required tags
-STEP_REQUIRED_TAGS = ["purpose", "instructions", "output"]
-
-# Step meta required fields
-STEP_META_FIELDS = ["step", "workflow", "agent", "next"]
-
-
-def _has_tag(content: str, tag: str) -> bool:
-    """Check if content contains a specific XML tag."""
-    return f"<{tag}>" in content or f"<{tag} " in content
-
-
-def validate_session_content(content: str) -> list[str]:
-    """Validate session file content.
-
-    Args:
-        content: File content to validate
-
-    Returns:
-        List of error messages (empty if valid)
-    """
-    errors = []
-
-    # Check for XML format indicator
-    if "<session" not in content:
-        # Old markdown format - warn but don't block during migration
-        return []
-
-    # Validate <session> root with attributes
-    if not re.search(r'<session\s+story="[^"]+"', content):
-        errors.append("Missing story attribute on <session>")
-
-    if not re.search(r'<session[^>]+workflow="[^"]+"', content):
-        errors.append("Missing workflow attribute on <session>")
-
-    # Validate <meta> section
-    if not _has_tag(content, "meta"):
-        errors.append("Missing <meta> section")
-    else:
-        if "<jira>" not in content:
-            errors.append("Missing <jira> in <meta>")
-        if "<started>" not in content:
-            errors.append("Missing <started> in <meta>")
-
-    # Validate <status> element
-    if not _has_tag(content, "status"):
-        errors.append("Missing <status> element")
-    else:
-        if 'phase="' not in content:
-            errors.append("Missing phase attribute on <status>")
-
-    return errors
-
-
-def validate_skill_content(content: str) -> list[str]:
-    """Validate skill file content.
-
-    Args:
-        content: File content to validate
-
-    Returns:
-        List of error messages (empty if valid)
-    """
-    errors = []
-
-    # Check YAML frontmatter
-    if not content.startswith("---\n"):
-        errors.append("Missing YAML frontmatter")
-    else:
-        parts = content.split("---", 2)
-        if len(parts) >= 2:
-            frontmatter = parts[1]
-            if "name:" not in frontmatter:
-                errors.append("Missing 'name' in frontmatter")
-            if "description:" not in frontmatter:
-                errors.append("Missing 'description' in frontmatter")
-
-    # Check required tags
-    for tag in SKILL_REQUIRED_TAGS:
-        if not _has_tag(content, tag):
-            errors.append(f"Missing <{tag}> tag (required)")
-
-    return errors
-
-
-def validate_step_content(content: str) -> list[str]:
-    """Validate workflow step file content.
-
-    Args:
-        content: File content to validate
-
-    Returns:
-        List of error messages (empty if valid)
-    """
-    errors = []
-
-    # Check required tags
-    for tag in STEP_REQUIRED_TAGS:
-        if not _has_tag(content, tag):
-            errors.append(f"Missing <{tag}> tag")
-
-    # Check step-meta fields if tag exists
-    if _has_tag(content, "step-meta"):
-        meta_match = re.search(r"<step-meta>(.+?)</step-meta>", content, re.DOTALL)
-        if meta_match:
-            meta_content = meta_match.group(1)
-            for field_name in STEP_META_FIELDS:
-                if f"{field_name}:" not in meta_content:
-                    errors.append(f"Missing '{field_name}' in step-meta")
-
-    return errors
-
-
-def validate_content(file_path: str, content: str) -> list[str]:
-    """Validate content based on file type.
-
-    Args:
-        file_path: Path to file being written
-        content: Content being written
-
-    Returns:
-        List of error messages (empty if valid)
-    """
-    file_type = get_file_type(file_path)
-
-    if file_type == "session":
-        return validate_session_content(content)
-    elif file_type == "skill":
-        return validate_skill_content(content)
-    elif file_type == "step":
-        return validate_step_content(content)
-
-    return []
-
-
-# =============================================================================
-# Hook Entry Point
-# =============================================================================
-
-
-def main() -> None:
-    """Main entry point for schema validation hook."""
-    try:
-        # Read tool data from Claude Code
-        tool_data = read_stdin_json()
-
-        tool_name = tool_data.get("tool_name", "")
-        tool_input = tool_data.get("tool_input", {})
-
-        # Only process Write and Edit tools
-        if tool_name not in ("Write", "Edit"):
-            output_hook_response(HookResponse(
-                event_name="PreToolUse",
-                decision="allow",
-                reason="Not a Write/Edit operation",
-            ))
-            sys.exit(0)
-
-        # Get file path
-        file_path = tool_input.get("file_path", "")
-        if not file_path:
-            output_hook_response(HookResponse(
-                event_name="PreToolUse",
-                decision="allow",
-                reason="No file path",
-            ))
-            sys.exit(0)
-
-        # Check if this is a file we care about
-        file_type = get_file_type(file_path)
-        if not file_type:
-            output_hook_response(HookResponse(
-                event_name="PreToolUse",
-                decision="allow",
-                reason="Not a session/skill/step file",
-            ))
-            sys.exit(0)
-
-        # Get content to validate
-        # For Write: use 'content'
-        # For Edit: we need to simulate the edit result
-        if tool_name == "Write":
-            content = tool_input.get("content", "")
-        else:
-            # Edit operation - we can't easily validate without reading the file
-            # For now, allow Edits and validate on Write only
-            output_hook_response(HookResponse(
-                event_name="PreToolUse",
-                decision="allow",
-                reason="Edit operations validated post-hoc",
-            ))
-            sys.exit(0)
-
-        # Validate content
-        errors = validate_content(file_path, content)
-
-        if errors:
-            # Block the write
-            error_msg = f"Schema validation failed for {file_type} file:\n"
-            error_msg += "\n".join(f"  - {e}" for e in errors)
-            error_msg += f"\n\nFile: {file_path}"
-
-            output_hook_response(HookResponse(
-                event_name="PreToolUse",
-                decision="deny",
-                reason=error_msg,
-            ))
-            sys.exit(0)
-
-        # Validation passed
-        output_hook_response(HookResponse(
-            event_name="PreToolUse",
-            decision="allow",
-            reason=f"Schema validation passed for {file_type} file",
-        ))
-        sys.exit(0)
-
-    except Exception as e:
-        # On error, allow to avoid blocking legitimate work
-        print(f"[schema-validation-hook] Error: {e}", file=sys.stderr)
-        sys.exit(0)
-
+from pennyfarthing_scripts.hooks.schema_validation import main  # noqa: F401
 
 if __name__ == "__main__":
     main()

package/pennyfarthing_scripts/session_start_hook.py

@@ -1,192 +1,10 @@
-#!/usr/bin/env python3
-"""Session start hook — initialize environment for Claude Code session.
-
-Handles:
-1. Session directory setup and logging
-2. Checkpoint validation (cross-session drift detection)
-3. WheelHub auto-start (ensure BikeRack server is running)
-4. OTEL auto-configuration via CLAUDE_ENV_FILE
-
-Called by Claude Code SessionStart hook via shell wrapper.
 """
+Backward-compatibility shim — session start hook moved to hooks/session_start.py.
 
-from __future__ import annotations
-
-import json
-import os
-import sys
-from pathlib import Path
-
-
-def _read_input() -> dict:
-    """Read JSON from stdin (hook protocol)."""
-    raw = sys.stdin.read()
-    try:
-        return json.loads(raw)
-    except (json.JSONDecodeError, ValueError):
-        return {}
-
-
-def _setup_session_dir(project_dir: Path, session_id: str, source_type: str) -> None:
-    """Ensure .session directory exists and log session start."""
-    session_dir = project_dir / ".session"
-    session_dir.mkdir(parents=True, exist_ok=True)
-    (session_dir / "agents").mkdir(exist_ok=True)
-
-    from datetime import UTC, datetime
-
-    timestamp = datetime.now(UTC).isoformat()
-    log_file = session_dir / "session-log.txt"
-    with open(log_file, "a") as f:
-        f.write(f"{timestamp} | Session {source_type}: {session_id}\n")
-
-
-def _validate_checkpoint(project_dir: Path) -> None:
-    """Validate previous session checkpoint for cross-session drift detection."""
-    try:
-        import subprocess
-
-        script_dir = Path(__file__).resolve().parent.parent
-        checkpoint_lib = script_dir / "pennyfarthing-dist" / "scripts" / "lib" / "checkpoint.sh"
-
-        if not checkpoint_lib.exists():
-            return
-
-        result = subprocess.run(
-            ["bash", "-c", f'source "{checkpoint_lib}" && checkpoint_restore session_state'],
-            capture_output=True,
-            text=True,
-            cwd=str(project_dir),
-            timeout=5,
-        )
-
-        prev_state = result.stdout.strip()
-        if not prev_state:
-            return
-
-        # Parse checkpoint data
-        fields = {}
-        for part in prev_state.split(";"):
-            if "=" in part:
-                k, v = part.split("=", 1)
-                fields[k] = v
-
-        prev_sha = fields.get("sha", "")
-        if not prev_sha:
-            return
-
-        # Get current git SHA
-        result = subprocess.run(
-            ["git", "rev-parse", "--short", "HEAD"],
-            capture_output=True,
-            text=True,
-            cwd=str(project_dir),
-            timeout=5,
-        )
-        current_sha = result.stdout.strip()
-        if not current_sha or current_sha == prev_sha:
-            return
-
-        # Log drift
-        from datetime import UTC, datetime
-
-        timestamp = datetime.now(UTC).isoformat()
-        session_dir = project_dir / ".session"
-
-        warning = f"CROSS_SESSION_DRIFT: Git changed (was: {prev_sha}, now: {current_sha})"
-        if fields.get("story"):
-            warning += f" | Story: {fields['story']}"
-        if fields.get("agent"):
-            warning += f" | Agent: {fields['agent']}"
-
-        with open(session_dir / "session-log.txt", "a") as f:
-            f.write(f"{timestamp} | {warning}\n")
-
-        drift_entry = f"{timestamp} | prev_sha={prev_sha} | current_sha={current_sha}"
-        for key in ("story", "agent", "phase"):
-            if fields.get(key):
-                drift_entry += f" | {key}={fields[key]}"
-        with open(session_dir / "drift-log.txt", "a") as f:
-            f.write(drift_entry + "\n")
-
-    except Exception:
-        pass
-
-
-def _ensure_wheelhub(project_dir: Path) -> int | None:
-    """Auto-start WheelHub if not already running. Returns port or None."""
-    from pennyfarthing_scripts.bikerack.launcher import (
-        is_already_running,
-        poll_for_port_file,
-        start_wheelhub,
-        write_pid_file,
-    )
-
-    # Skip if full Cyclist is running
-    cyclist_port_file = project_dir / ".cyclist-port"
-    if cyclist_port_file.exists():
-        try:
-            return int(cyclist_port_file.read_text().strip())
-        except (ValueError, OSError):
-            return None
-
-    # Check if BikeRack WheelHub is already running
-    running, _pid, port = is_already_running(project_dir)
-    if running:
-        return port
-
-    # Start WheelHub
-    try:
-        proc = start_wheelhub(project_dir)
-        write_pid_file(project_dir, proc.pid)
-        return poll_for_port_file(project_dir)
-    except Exception:
-        return None
-
-
-def _write_env_file(project_dir: Path, session_id: str, otel_port: int | None) -> None:
-    """Write environment variables to CLAUDE_ENV_FILE."""
-    env_file = os.environ.get("CLAUDE_ENV_FILE")
-    if not env_file:
-        return
-
-    lines = [
-        "# Pennyfarthing core environment",
-        f'export PROJECT_ROOT="{project_dir}"',
-        f'export SESSION_ID="{session_id}"',
-    ]
-
-    if otel_port is not None:
-        lines.extend([
-            "# OTEL auto-configuration for Cyclist/WheelHub",
-            'export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"',
-            f'export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:{otel_port}"',
-        ])
-
-    with open(env_file, "a") as f:
-        f.write("\n".join(lines) + "\n")
-
-
-def main() -> None:
-    """Entry point for SessionStart hook."""
-    try:
-        input_data = _read_input()
-        session_id = input_data.get("session_id", "unknown")
-        source_type = input_data.get("source", "unknown")
-
-        project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
-
-        _setup_session_dir(project_dir, session_id, source_type)
-        _validate_checkpoint(project_dir)
-
-        otel_port = _ensure_wheelhub(project_dir)
-        _write_env_file(project_dir, session_id, otel_port)
-
-    except Exception:
-        pass
-
-    sys.exit(0)
+This file will be removed in a future version.
+"""
 
+from pennyfarthing_scripts.hooks.session_start import main  # noqa: F401
 
 if __name__ == "__main__":
     main()

package/pennyfarthing_scripts/sprint/loader.py

@@ -62,6 +62,17 @@ def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]
                 stacklevel=2,
             )
 
+    # Collect epic refs owned by initiatives so we don't warn about them.
+    initiative_refs: set[str] = set()
+    for init_file in sorted(sprint_dir.glob("initiative-*.yaml")):
+        init_data = load_yaml_config(init_file)
+        if init_data and isinstance(init_data, dict):
+            for ref in init_data.get("epics", []):
+                if isinstance(ref, str):
+                    initiative_refs.add(ref)
+                    # Also add normalized form (strip "epic-" prefix)
+                    initiative_refs.add(ref.replace("epic-", ""))
+
     # Log unindexed shard files on disk (but do NOT auto-merge —
     # orphan shards may belong to future initiatives).
     for shard_file in sorted(sprint_dir.glob("epic-*.yaml")):
@@ -74,7 +85,10 @@ def _merge_epic_shards(data: dict[str, Any], sprint_dir: Path) -> dict[str, Any]
         jira_key = str(epic_data.get("jira", ""))
         if eid in loaded_epic_ids or (jira_key and jira_key in loaded_epic_ids):
             continue
-        # Warn but don't merge
+        # Skip shards owned by initiatives (not orphans)
+        if eid in initiative_refs or jira_key in initiative_refs:
+            continue
+        # Warn only about truly orphaned shards
         warnings.warn(
             f"Unindexed shard {shard_file.name} (epic {eid}) not in epics list — skipping",
             stacklevel=2,

package/pennyfarthing_scripts/sprint/story_update.py

@@ -30,6 +30,8 @@ def update_story(
     completed_date: str | None = None,
     started_date: str | None = None,
     workflow: str | None = None,
+    review_findings: str | None = None,
+    review_verdict: str | None = None,
     dry_run: bool = False,
 ) -> dict[str, Any]:
     """Update fields on a story in the sprint YAML.
@@ -44,6 +46,8 @@ def update_story(
         completed_date: Completed date (ISO format)
         started_date: Started date (ISO format)
         workflow: Workflow type (tdd, trivial, bdd, agent-docs)
+        review_findings: Reviewer findings text
+        review_verdict: Review verdict (approved, rejected, pending)
         dry_run: If True, report changes without writing
 
     Returns:
@@ -97,6 +101,15 @@ def update_story(
         story["started"] = started_date
     if workflow is not None:
         story["workflow"] = workflow
+    if review_findings is not None:
+        story["review_findings"] = review_findings
+    if review_verdict is not None:
+        if review_verdict not in ("approved", "rejected", "pending"):
+            return {
+                "success": False,
+                "error": f"Invalid review_verdict '{review_verdict}'. Must be one of: approved, rejected, pending",
+            }
+        story["review_verdict"] = review_verdict
 
     # Auto-cleanup rules
     if status == "done":
@@ -153,6 +166,8 @@ def update_story(
 @click.option("--priority", default=None)
 @click.option("--started", "started_date", default=None)
 @click.option("--workflow", default=None)
+@click.option("--review-findings", default=None, help="Reviewer findings text")
+@click.option("--review-verdict", type=click.Choice(["approved", "rejected", "pending"]), default=None)
 @click.option("--dry-run", is_flag=True)
 @click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
 def story_update_command(
@@ -164,6 +179,8 @@ def story_update_command(
     priority: str | None,
     started_date: str | None,
     workflow: str | None,
+    review_findings: str | None,
+    review_verdict: str | None,
     dry_run: bool,
     sprint_file: str | None,
 ) -> None:
@@ -184,6 +201,8 @@ def story_update_command(
         completed_date=completed_date,
         started_date=started_date,
         workflow=workflow,
+        review_findings=review_findings,
+        review_verdict=review_verdict,
         dry_run=dry_run,
     )