@pennyfarthing/core 10.0.5 → 10.1.0

package/pennyfarthing-dist/guides/prime.md

@@ -52,8 +52,8 @@ Prime selects a context tier based on session state to manage token overhead:
 ## Invocation
 
 ```bash
-# From agent commands (via CLI)
-python3 -m pennyfarthing_scripts.cli agent start "<agent>" --quiet
+# From agent commands (via pf CLI)
+pf agent start "<agent>" --quiet
 
 # TypeScript API (from Cyclist)
 getPrimeContext(agentName, projectDir)

package/pennyfarthing-dist/guides/skill-schema.md

@@ -292,7 +292,7 @@ Never manually edit sprint YAML. Use the provided commands.
 Add a new story to an epic.
 
 <run>
-python3 -m pennyfarthing_scripts.cli sprint story add <epic-id> "<title>" <points>
+pf sprint story add <epic-id> "<title>" <points>
 </run>
 
 <args>
@@ -304,7 +304,7 @@ python3 -m pennyfarthing_scripts.cli sprint story add <epic-id> "<title>" <point
 </args>
 
 <example>
-python3 -m pennyfarthing_scripts.cli sprint story add epic-76 "Add user authentication" 3
+pf sprint story add epic-76 "Add user authentication" 3
 </example>
 
 <output>
@@ -322,7 +322,7 @@ After creating, use `/sprint story size` for sizing guidelines.
 Complete a story after PR merge.
 
 <run>
-python3 -m pennyfarthing_scripts.cli sprint story finish <story-id>
+pf sprint story finish <story-id>
 </run>
 
 <args>
@@ -332,7 +332,7 @@ python3 -m pennyfarthing_scripts.cli sprint story finish <story-id>
 </args>
 
 <example>
-python3 -m pennyfarthing_scripts.cli sprint story finish MSSCI-12052
+pf sprint story finish MSSCI-12052
 # Archives story, updates Jira, cleans session files
 </example>
 

package/pennyfarthing-dist/scripts/core/agent-session.sh

@@ -91,7 +91,7 @@ check_theme_version() {
     echo "" >&2
     echo "Warning: Theme '${theme_name}' was created with Pennyfarthing ${theme_version}" >&2
     echo "         Current version: ${current_version} - agent roles may have changed." >&2
-    echo "         Run '/theme-maker --update ${theme_name}' to review." >&2
+    echo "         Run '/theme maker' to review and update." >&2
     echo "" >&2
   fi
 
@@ -232,7 +232,11 @@ case "$1" in
       PRIME_ARGS+=(--no-persona)
     fi
 
-    python3 -m pennyfarthing_scripts.prime "${PRIME_ARGS[@]}"
+    if command -v pf &>/dev/null; then
+      pf prime "${PRIME_ARGS[@]}"
+    else
+      python3 -m pennyfarthing_scripts.prime "${PRIME_ARGS[@]}"
+    fi
     ;;
   stop)
     # Use provided session ID, fall back to SESSION_ID env var

package/pennyfarthing-dist/scripts/core/prime.sh

@@ -2,29 +2,27 @@
 # prime.sh - Load essential project context at agent activation
 # Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]
 #
-# Thin wrapper around python -m pennyfarthing_scripts.prime
+# Uses the `pf` CLI (installed via uv/pipx during pennyfarthing init).
+# Falls back to python3 -m with PYTHONPATH if pf is not available.
 
-# Find the package root (where pennyfarthing_scripts lives)
-# Works for both npm installs (node_modules/@pennyfarthing/core) and local dev
-# Use pwd -P to resolve symlinks in the path (handles symlinked parent dirs)
+# Prefer pf CLI if available
+if command -v pf &>/dev/null; then
+    exec pf prime "$@"
+fi
+
+# Fallback: find pennyfarthing_scripts via PYTHONPATH
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd -P)"
 
-# Fallback: if pennyfarthing_scripts not found at expected location,
-# look in node_modules (handles edge cases like stale copies)
 if [[ ! -d "$PACKAGE_ROOT/pennyfarthing_scripts" ]]; then
-    # Find project root by looking for .pennyfarthing marker
     PROJECT_ROOT="$PWD"
     while [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]] && [[ "$PROJECT_ROOT" != "/" ]]; do
         PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
     done
-    # Try node_modules location
     if [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core/pennyfarthing_scripts" ]]; then
         PACKAGE_ROOT="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
     fi
 fi
 
-# Set PYTHONPATH so Python can find pennyfarthing_scripts
 export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
-
 exec python3 -m pennyfarthing_scripts.prime "$@"

package/pennyfarthing-dist/scripts/git/install-git-hooks.sh

@@ -1,10 +1,11 @@
 #!/bin/bash
-# install-git-hooks.sh - Install Pennyfarthing git hooks for dogfooding
+# install-git-hooks.sh - Install Pennyfarthing git hooks for framework development
 #
 # Usage: ./pennyfarthing-dist/scripts/install-git-hooks.sh
 #
-# For dogfooding only. Clients use `pennyfarthing init` which copies hooks
-# from node_modules. This script creates symlinks for development.
+# For the pennyfarthing framework repo and orchestrator repos that inline it.
+# End-user projects use `pennyfarthing init` which copies hooks from node_modules.
+# This script creates symlinks so hook changes in pennyfarthing-dist/ take effect immediately.
 
 set -euo pipefail
 
@@ -14,10 +15,11 @@ source "$SCRIPT_DIR/../lib/find-root.sh"
 HOOKS_SOURCE="$PROJECT_ROOT/pennyfarthing-dist/scripts/hooks"
 HOOKS_DEST="$PROJECT_ROOT/.git/hooks"
 
-# Check we're in the pennyfarthing repo (dogfooding)
+# Check we're in a repo with pennyfarthing-dist (framework or orchestrator)
 if [[ ! -d "$PROJECT_ROOT/pennyfarthing-dist" ]]; then
-    echo "Error: This script is for dogfooding only (pennyfarthing repo)"
-    echo "       Clients should use: pennyfarthing init"
+    echo "Error: This script requires pennyfarthing-dist/ at the project root"
+    echo "       (framework repo or orchestrator with inlined pennyfarthing/)"
+    echo "       End-user projects should use: pennyfarthing init"
     exit 1
 fi
 

package/pennyfarthing-dist/scripts/hooks/post-merge.sh

@@ -6,7 +6,8 @@
 # story branch is merged and automatically updating the sprint YAML status.
 #
 # Installation:
-#   Installed to .git/hooks/post-merge by pennyfarthing init or doctor --fix
+#   End-user projects: pennyfarthing init (copies to .git/hooks/)
+#   Framework/orchestrator: install-git-hooks.sh (symlinks to pennyfarthing-dist/)
 #
 # Dependencies:
 #   - yq (for YAML manipulation)
@@ -14,11 +15,17 @@
 
 set -uo pipefail
 
-# Self-locate (resolve symlink first for .git/hooks/ symlinks)
+# Find project root
+# Try find-root.sh via symlink resolution first, then fall back to .git location
 REAL_SCRIPT="$(readlink -f "${BASH_SOURCE[0]:-$0}" 2>/dev/null || realpath "${BASH_SOURCE[0]:-$0}" 2>/dev/null || echo "${BASH_SOURCE[0]:-$0}")"
-source "$(dirname "$REAL_SCRIPT")/../lib/find-root.sh"
-
-# PROJECT_ROOT is now set by find-root.sh
+FIND_ROOT="$(dirname "$REAL_SCRIPT")/../lib/find-root.sh"
+if [[ -f "$FIND_ROOT" ]]; then
+    source "$FIND_ROOT"
+else
+    # Running as a copy in .git/hooks/ — derive PROJECT_ROOT from git dir
+    PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)"
+    export PROJECT_ROOT
+fi
 SESSION_DIR="$PROJECT_ROOT/.session"
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 

package/pennyfarthing-dist/scripts/hooks/pre-commit.sh

@@ -8,8 +8,8 @@
 # 3. Validates sprint YAML files when sprint/*.yaml is modified
 #
 # Installation:
-#   Installed to .git/hooks/pre-commit by pennyfarthing init or doctor --fix
-#   Or symlink: ln -sf ../../pennyfarthing-dist/scripts/hooks/pre-commit.sh .git/hooks/pre-commit
+#   End-user projects: pennyfarthing init (copies to .git/hooks/)
+#   Framework/orchestrator: install-git-hooks.sh (symlinks to pennyfarthing-dist/)
 
 set -uo pipefail
 
@@ -114,7 +114,8 @@ fi
 
 SPRINT_YAML_FILES=$(git diff --cached --name-only -- 'sprint/*.yaml' 'sprint/archive/*.yaml' 2>/dev/null \
     | grep -v 'sprint-template\.yaml$' \
-    | grep -v 'sprint/completed\.yaml$' || true)
+    | grep -v 'sprint/completed\.yaml$' \
+    | grep -v 'sprint/context/archived/' || true)
 
 if [[ -n "$SPRINT_YAML_FILES" ]]; then
     echo "Sprint YAML files staged for commit:"

package/pennyfarthing-dist/scripts/hooks/pre-push.sh

@@ -4,15 +4,21 @@
 # Checks if sprint files were modified and reminds to sync to Jira.
 #
 # Installation:
-#   Installed to .git/hooks/pre-push by pennyfarthing init or doctor --fix
-#   Or symlink: ln -sf ../../pennyfarthing-dist/scripts/hooks/pre-push.sh .git/hooks/pre-push
+#   End-user projects: pennyfarthing init (copies to .git/hooks/)
+#   Framework/orchestrator: install-git-hooks.sh (symlinks to pennyfarthing-dist/)
 
 set -uo pipefail
 
-# Self-locate (resolve symlink first for .git/hooks/ symlinks)
+# Find project root
+# Try find-root.sh via symlink resolution first, then fall back to .git location
 REAL_SCRIPT="$(readlink -f "${BASH_SOURCE[0]:-$0}" 2>/dev/null || realpath "${BASH_SOURCE[0]:-$0}" 2>/dev/null || echo "${BASH_SOURCE[0]:-$0}")"
-if ! source "$(dirname "$REAL_SCRIPT")/../lib/find-root.sh" 2>/dev/null; then
-    exit 0
+FIND_ROOT="$(dirname "$REAL_SCRIPT")/../lib/find-root.sh"
+if [[ -f "$FIND_ROOT" ]]; then
+    source "$FIND_ROOT"
+else
+    # Running as a copy in .git/hooks/ — derive PROJECT_ROOT from git dir
+    PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)"
+    export PROJECT_ROOT
 fi
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"

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

@@ -7,7 +7,7 @@ Uncategorized utilities and one-off scripts.
 | Script | Purpose |
 |--------|---------|
 | `deploy.sh` | Deployment script |
-| `doctor-dogfood.sh` | Health check for dogfooding setup |
+| `doctor-dogfood.sh` | Health check for framework/orchestrator development setup |
 | `run-ci.sh` | Run CI locally |
 | `statusline.sh` | Status line configuration |
 | `uninstall.sh` | Uninstall Pennyfarthing from project |

package/pennyfarthing-dist/scripts/misc/validate-subagent-frontmatter.sh

@@ -31,9 +31,8 @@ NC='\033[0m' # No Color
 # Required fields in frontmatter
 REQUIRED_FIELDS=("name" "description" "tools" "model")
 
-# Expected subagent files (8 total - consolidated in Story 31-11/31-12)
+# Expected subagent files (7 total - consolidated in Story 31-11/31-12)
 EXPECTED_SUBAGENTS=(
-    "workflow-status-check.md"
     "sm-setup.md"
     "sm-finish.md"
     "sm-file-summary.md"

package/pennyfarthing-dist/scripts/tests/handoff-phase-update.test.sh

@@ -6,7 +6,7 @@
 # - AC1: Updating **Phase:** field to next phase
 # - AC2: Updating Phase History table with end timestamp and duration
 # - AC3: Adding Handoff History row with gate and status
-# - AC4: workflow-status-check correctly detects phase (integration)
+# - AC4: prime correctly detects phase (integration)
 # - AC5: All three transitions documented (TEA→Dev, Dev→Reviewer, Reviewer→SM)
 
 set -euo pipefail
@@ -190,14 +190,14 @@ run_test test_ac3_status_in_history
 run_test test_ac3_explicit_edit_for_history
 
 # ==============================================================================
-# AC4: workflow-status-check correctly detects current phase after handoff
+# AC4: prime correctly detects current phase after handoff
 # ==============================================================================
 echo ""
-echo "--- AC4: workflow-status-check compatibility ---"
+echo "--- AC4: prime/workflow.py compatibility ---"
 
 test_ac4_phase_field_format() {
-    # Phase field must use exact format that workflow-status-check expects
-    # workflow-status-check greps for: **Phase:**
+    # Phase field must use exact format that prime/workflow.py expects
+    # parse_session_header greps for: **Phase:**
     if echo "$HANDOFF_CONTENT" | grep -q '\*\*Phase:\*\*'; then
         pass "AC4.1: Uses correct **Phase:** format"
     else

package/pennyfarthing-dist/scripts/tests/test-drift-detection.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # test-drift-detection.sh - Tests for story 8-2: Startup Drift Detection
-# Verifies that workflow-status-check detects and reports drift between
+# Verifies that prime/sprint scripts detect and report drift between
 # merged branches and sprint YAML status
 #
 # RED STATE: These tests will FAIL until Dev implements the feature
@@ -38,7 +38,7 @@ echo "=== Story 8-2: Startup Drift Detection ==="
 echo ""
 
 # ==============================================================================
-# AC1: workflow-status-check detects merged-but-not-closed stories
+# AC1: prime detects merged-but-not-closed stories
 # ==============================================================================
 
 echo "--- AC1: Detects merged-but-not-closed stories ---"
@@ -293,28 +293,9 @@ test_drift_output_format() {
     fi
 }
 
-# Test: workflow-status-check.md references drift detection
-test_workflow_status_check_integration() {
-    local workflow_file="$PROJECT_ROOT/pennyfarthing-dist/agents/workflow-status-check.md"
-
-    if [[ ! -f "$workflow_file" ]]; then
-        fail "workflow-status-check includes drift detection" "file exists" "workflow-status-check.md not found"
-        return
-    fi
-
-    if grep -qi "drift\|detect_drift" "$workflow_file" 2>/dev/null; then
-        pass "workflow-status-check.md references drift detection"
-    else
-        fail "workflow-status-check includes drift detection" \
-             "drift or detect_drift reference in workflow-status-check.md" \
-             "no drift reference found"
-    fi
-}
-
 # Test: Drift report is user-friendly (mentions "merged" and "status")
 test_drift_report_clarity() {
     local sprint_common="$PROJECT_ROOT/pennyfarthing-dist/scripts/sprint/sprint-common.sh"
-    local workflow_file="$PROJECT_ROOT/pennyfarthing-dist/agents/workflow-status-check.md"
 
     local found=false
 
@@ -323,11 +304,6 @@ test_drift_report_clarity() {
         found=true
     fi
 
-    # Or check workflow-status-check.md for report format
-    if [[ -f "$workflow_file" ]] && grep -qi "merged.*status\|drift.*report\|drifted stories" "$workflow_file" 2>/dev/null; then
-        found=true
-    fi
-
     if [[ "$found" == "true" ]]; then
         pass "drift report uses clear terminology (merged, drift, status)"
     else
@@ -338,7 +314,6 @@ test_drift_report_clarity() {
 }
 
 test_drift_output_format
-test_workflow_status_check_integration
 test_drift_report_clarity
 
 echo ""
@@ -353,7 +328,6 @@ echo ""
 # Test: reconcile_drift function or auto-reconcile logic exists
 test_reconcile_function_exists() {
     local sprint_common="$PROJECT_ROOT/pennyfarthing-dist/scripts/sprint/sprint-common.sh"
-    local workflow_file="$PROJECT_ROOT/pennyfarthing-dist/agents/workflow-status-check.md"
 
     local found=false
 
@@ -362,11 +336,6 @@ test_reconcile_function_exists() {
         found=true
     fi
 
-    # Or check workflow-status-check.md for reconcile instructions
-    if [[ -f "$workflow_file" ]] && grep -qi "reconcile\|auto.reconcile\|update.*done" "$workflow_file" 2>/dev/null; then
-        found=true
-    fi
-
     if [[ "$found" == "true" ]]; then
         pass "auto-reconcile functionality exists"
     else
@@ -402,7 +371,6 @@ test_reconcile_uses_update() {
 # Test: Auto-reconcile logs to reconciliation.log
 test_reconcile_logs_event() {
     local sprint_common="$PROJECT_ROOT/pennyfarthing-dist/scripts/sprint/sprint-common.sh"
-    local workflow_file="$PROJECT_ROOT/pennyfarthing-dist/agents/workflow-status-check.md"
 
     local found=false
 
@@ -411,11 +379,6 @@ test_reconcile_logs_event() {
         found=true
     fi
 
-    # Or check workflow-status-check.md for logging instructions
-    if [[ -f "$workflow_file" ]] && grep -qi "log.*reconcil\|reconciliation.log" "$workflow_file" 2>/dev/null; then
-        found=true
-    fi
-
     if [[ "$found" == "true" ]]; then
         pass "auto-reconcile logs to reconciliation.log"
     else
@@ -425,25 +388,6 @@ test_reconcile_logs_event() {
     fi
 }
 
-# Test: workflow-status-check offers reconcile option to user
-test_offers_reconcile_option() {
-    local workflow_file="$PROJECT_ROOT/pennyfarthing-dist/agents/workflow-status-check.md"
-
-    if [[ ! -f "$workflow_file" ]]; then
-        fail "offers reconcile option" "file exists" "workflow-status-check.md not found"
-        return
-    fi
-
-    # Check for user prompt or option offering
-    if grep -qiE "auto.reconcile|offer.*reconcile|reconcile.*option|y/n|yes/no" "$workflow_file" 2>/dev/null; then
-        pass "workflow-status-check offers reconcile option to user"
-    else
-        fail "offers reconcile option" \
-             "user prompt for auto-reconcile in workflow-status-check.md" \
-             "reconcile prompt not found"
-    fi
-}
-
 # Test: reconcile_drift transitions Jira to Done
 test_reconcile_transitions_jira() {
     local sprint_common="$PROJECT_ROOT/pennyfarthing-dist/scripts/sprint/sprint-common.sh"
@@ -463,30 +407,10 @@ test_reconcile_transitions_jira() {
     fi
 }
 
-# Test: workflow-status-check mentions Jira in drift reconciliation
-test_workflow_mentions_jira_reconcile() {
-    local workflow_file="$PROJECT_ROOT/pennyfarthing-dist/agents/workflow-status-check.md"
-
-    if [[ ! -f "$workflow_file" ]]; then
-        fail "workflow mentions Jira reconcile" "file exists" "workflow-status-check.md not found"
-        return
-    fi
-
-    if grep -qiE 'jira.*done|transition.*jira|jira.*status' "$workflow_file" 2>/dev/null; then
-        pass "workflow-status-check mentions Jira in reconciliation"
-    else
-        fail "workflow mentions Jira reconcile" \
-             "Jira transition reference in workflow-status-check.md" \
-             "Jira reconcile not found"
-    fi
-}
-
 test_reconcile_function_exists
 test_reconcile_uses_update
 test_reconcile_transitions_jira
 test_reconcile_logs_event
-test_offers_reconcile_option
-test_workflow_mentions_jira_reconcile
 
 echo ""
 
@@ -580,7 +504,7 @@ if [[ $TESTS_FAILED -gt 0 ]]; then
     echo "  2. Output format: story_id:yaml_status:jira_status (AC2)"
     echo "     - Clear, user-friendly terminology"
     echo "     - Include both YAML and Jira status"
-    echo "  3. Add Step 2.5 to workflow-status-check.md (AC1, AC2)"
+    echo "  3. Add drift detection to prime/workflow.py (AC1, AC2)"
     echo "     - Call detect_drift after git scan"
     echo "     - Report drifted stories before state determination"
     echo "  4. Add auto-reconcile option (AC3)"