@pennyfarthing/core 9.0.0 → 9.1.2

package/pennyfarthing-dist/guides/xml-tags.md

@@ -325,6 +325,298 @@ Assume the code is broken until you prove otherwise.
 | `<persona>` | Agent files (top) |
 | `<role>` | Agent files (after persona) |
 
+## Session Tags
+
+Tags used in session files (`.session/{story-id}-session.md`) for workflow state tracking.
+
+### `<session>`
+
+**Purpose:** Root container for all session data.
+
+**Usage:** Wraps entire session file content.
+
+```markdown
+<session story="MSSCI-12345" workflow="tdd">
+  <!-- session content -->
+</session>
+```
+
+**Attributes:**
+- `story` - Story identifier (Jira key or local ID)
+- `workflow` - Workflow type: `tdd`, `trivial`, `bdd`, `agent-docs`
+
+### `<meta>`
+
+**Purpose:** Story metadata that doesn't change during the session.
+
+**Usage:** Inside `<session>`, contains static story info.
+
+```markdown
+<meta>
+  <jira>MSSCI-12345</jira>
+  <epic>MSSCI-12300</epic>
+  <points>3</points>
+  <started>2026-02-03</started>
+</meta>
+```
+
+### `<status>`
+
+**Purpose:** Machine-readable workflow state for agent navigation.
+
+**Usage:** Self-closing element updated at phase transitions.
+
+```markdown
+<status phase="green" next-agent="reviewer" handoff-ready="true"/>
+```
+
+**Attributes:**
+- `phase` - Current workflow phase (`setup`, `red`, `green`, `review`, `finish`)
+- `next-agent` - Agent to handle next (`sm`, `tea`, `dev`, `reviewer`)
+- `handoff-ready` - Whether current work is complete (`true`/`false`)
+
+### `<acceptance-criteria>`
+
+**Purpose:** Track AC completion status in machine-parseable format.
+
+**Usage:** Contains `<ac>` child elements.
+
+```markdown
+<acceptance-criteria>
+  <ac id="1" status="done">User can create account</ac>
+  <ac id="2" status="pending">Email validation works</ac>
+</acceptance-criteria>
+```
+
+### `<ac>`
+
+**Purpose:** Individual acceptance criterion.
+
+**Attributes:**
+- `id` - Numeric identifier (1, 2, 3...)
+- `status` - `pending`, `in-progress`, `done`, `blocked`
+
+### `<work-log>`
+
+**Purpose:** Container for chronological agent contributions.
+
+**Usage:** Contains `<entry>` and `<assessment>` elements.
+
+### `<entry>`
+
+**Purpose:** Standard work log entry from any agent.
+
+**Attributes:**
+- `agent` - Agent identifier (`sm`, `tea`, `dev`, `reviewer`)
+- `date` - Entry date (YYYY-MM-DD)
+- `phase` - Optional TDD phase (`red`, `green`, `refactor`)
+
+```markdown
+<entry agent="tea" date="2026-02-03" phase="red">
+  Wrote failing tests for all ACs.
+</entry>
+```
+
+### `<assessment>`
+
+**Purpose:** Formal verdict from Reviewer agent.
+
+**Attributes:**
+- `agent` - Must be `reviewer`
+- `verdict` - `approved`, `rejected`, `needs-work`
+
+```markdown
+<assessment agent="reviewer" verdict="approved">
+  All ACs verified, code follows patterns.
+</assessment>
+```
+
+**See also:** `guides/session-schema.md` for complete session file schema.
+
+---
+
+## Skill Tags
+
+Tags used in skill files (`skills/{name}/SKILL.md`) for command documentation.
+
+### `<run>`
+
+**Purpose:** The exact command to execute for a skill command.
+
+**Usage:** One per command, contains shell command.
+
+```markdown
+<run>
+.pennyfarthing/scripts/sprint/sprint-status.sh [filter]
+</run>
+```
+
+### `<args>`
+
+**Purpose:** Document command arguments in table format.
+
+**Usage:** Follows `<run>`, contains markdown table.
+
+```markdown
+<args>
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `filter` | No | Filter by status: `todo`, `done` |
+</args>
+```
+
+### `<example>`
+
+**Purpose:** Show command usage with expected output.
+
+**Usage:** Realistic invocation followed by commented output.
+
+```markdown
+<example>
+.pennyfarthing/scripts/sprint/check-story.sh MSSCI-12038
+# Returns: {"type": "story", "available": true}
+</example>
+```
+
+### `<when>`
+
+**Purpose:** Document conditions for using a command and next steps.
+
+**Usage:** Trigger conditions or follow-up actions.
+
+```markdown
+<when>
+- Starting new development work
+- After promote, create Jira epic with `/jira create epic`
+</when>
+```
+
+### `<agent-activation>`
+
+**Purpose:** Command to load agent persona before using skill.
+
+**Usage:** Shell command for agent activation.
+
+```markdown
+<agent-activation>
+Load SM persona first:
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "sm"
+```
+</agent-activation>
+```
+
+**See also:** `guides/skill-schema.md` for complete skill file schema.
+
+---
+
+## Workflow Step Tags
+
+Tags used in workflow step files (`workflows/{name}/steps/step-*.md`) for BikeLane navigation.
+
+### `<step-meta>`
+
+**Purpose:** Machine-readable step metadata for workflow navigation.
+
+**Usage:** Required at top of every step file.
+
+```markdown
+<step-meta>
+number: 1
+name: initialize
+gate: false
+next: step-02-context
+</step-meta>
+```
+
+**Fields:**
+- `number` - Step number (integer)
+- `name` - Step identifier (kebab-case)
+- `gate` - Whether step has checkpoint (boolean)
+- `next` - Next step filename (optional)
+
+### `<purpose>`
+
+**Purpose:** Explain what the step accomplishes.
+
+**Usage:** Clear, concise goal statement.
+
+```markdown
+<purpose>
+Set up the architecture session by gathering inputs and establishing context.
+</purpose>
+```
+
+### `<prerequisites>`
+
+**Purpose:** What must be true before starting this step.
+
+**Usage:** Bullet list of requirements.
+
+```markdown
+<prerequisites>
+- PRD document exists
+- Previous step completed
+</prerequisites>
+```
+
+### `<instructions>`
+
+**Purpose:** Step-by-step execution guide.
+
+**Usage:** Numbered list of actions.
+
+```markdown
+<instructions>
+1. Read the PRD document
+2. Identify architectural concerns
+3. Document recommendation
+</instructions>
+```
+
+### `<actions>`
+
+**Purpose:** Specific file and script operations.
+
+**Usage:** Prefixed bullet list (Check:, Read:, Write:, Run:).
+
+```markdown
+<actions>
+- Read: `{planning_artifacts}/*prd*.md`
+- Write: `{output_file}` with session content
+</actions>
+```
+
+### `<collaboration-menu>`
+
+**Purpose:** Present user options after step completion.
+
+**Usage:** Standard menu with keyboard shortcuts.
+
+```markdown
+<collaboration-menu>
+- **[C] Continue** - Proceed to next step
+- **[R] Revise** - Make changes
+- **[H] Help** - Get guidance
+</collaboration-menu>
+```
+
+### `<next-step>`
+
+**Purpose:** Explicit navigation to the next step.
+
+**Usage:** Instruction on which file to load.
+
+```markdown
+<next-step>
+After gate passes, proceed to step-02-context.md
+</next-step>
+```
+
+**See also:** `guides/workflow-step-schema.md` for complete workflow step schema.
+
+---
+
 ## Adding New Tags
 
 Before adding a new tag type:

package/pennyfarthing-dist/scripts/hooks/context-circuit-breaker.sh

@@ -2,14 +2,17 @@
 # Context circuit breaker hook: Block tool execution at 85% context usage
 # Called by Claude Code before tool calls (PreToolUse)
 #
-# Input: JSON via stdin with tool_name, tool_input
+# Input: JSON via stdin with tool_name, tool_input, session_id
 # Output: Exit 0 to allow, Exit 2 to block (stderr shown to Claude)
 #
 # This hook provides a hard stop when context is critically high,
 # unlike context-warning.sh which only warns.
+#
+# When triggered, automatically saves the active agent to a checkpoint
+# so /continue-session can restore it with FULL tier.
 
-# Read and discard stdin (required by hook protocol)
-cat > /dev/null
+# Read stdin to get session_id (required by hook protocol)
+INPUT=$(cat)
 
 # Script location for sibling script references
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -34,6 +37,28 @@ CRITICAL_THRESHOLD="${CRITICAL_THRESHOLD:-80}"
 
 # Check if at or above critical threshold
 if [[ "$CONTEXT_PERCENT" -ge "$CRITICAL_THRESHOLD" ]] 2>/dev/null; then
+    # Auto-save active agent to checkpoint before blocking
+    # This allows /continue-session to restore with FULL tier
+    source "$SCRIPT_DIR/../lib/checkpoint.sh" 2>/dev/null || true
+
+    # Get session_id from input JSON
+    SESSION_ID=""
+    if command -v jq &>/dev/null && [[ -n "$INPUT" ]]; then
+        SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+    fi
+
+    # Look up active agent for this session
+    ACTIVE_AGENT=""
+    AGENT_FILE="${CLAUDE_PROJECT_DIR:-.}/.session/agents/${SESSION_ID}"
+    if [[ -n "$SESSION_ID" && -f "$AGENT_FILE" ]]; then
+        ACTIVE_AGENT=$(cat "$AGENT_FILE" 2>/dev/null)
+    fi
+
+    # Save agent checkpoint if we found one
+    if [[ -n "$ACTIVE_AGENT" ]]; then
+        checkpoint_save "circuit_breaker_agent" "$ACTIVE_AGENT" 2>/dev/null || true
+    fi
+
     # Send error message to stderr (Claude will see this)
     cat >&2 << EOF
 CONTEXT CIRCUIT BREAKER TRIGGERED
@@ -41,16 +66,26 @@ CONTEXT CIRCUIT BREAKER TRIGGERED
 Context usage: ${CONTEXT_PERCENT}% - CRITICAL (threshold: ${CRITICAL_THRESHOLD}%)
 
 Tool execution BLOCKED. You must stop and hand off.
+EOF
+
+    # Include agent info if available
+    if [[ -n "$ACTIVE_AGENT" ]]; then
+        cat >&2 << EOF
+
+Active agent saved: ${ACTIVE_AGENT}
+The agent will be restored with FULL context when you run /continue-session.
+EOF
+    fi
+
+    cat >&2 << EOF
 
 Required actions:
-1. Save checkpoint: Run checkpoint_save "{phase}" "{work_summary}"
-2. Update session file with current progress
-3. Commit any pending changes
-4. Hand off to next agent OR tell user to start fresh session
+1. Commit any pending changes
+2. Tell user to start fresh session with /continue-session
 
 DO NOT attempt further tool calls. This is a hard stop.
 
-To resume later: /continue-session (story 3-4)
+To resume later: /continue-session
 EOF
     # Exit 2 blocks the tool execution
     exit 2

package/pennyfarthing-dist/scripts/hooks/schema-validation.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env zsh
+# Schema Validation Hook
+# Validates XML schema for session, skill, and workflow step files on Write operations
+# Called by Claude Code PreToolUse hook
+#
+# Input: JSON via stdin with tool_name, tool_input
+# Output: JSON with decision (allow/deny)
+
+set -euo pipefail
+
+# Find script directory (zsh compatible)
+SCRIPT_DIR="${0:A:h}"
+source "$SCRIPT_DIR/../lib/find-root.sh"
+
+# Set PYTHONPATH for pennyfarthing_scripts
+PENNYFARTHING_SCRIPTS=""
+if [[ -d "$PROJECT_ROOT/pennyfarthing" ]]; then
+    # Dogfooding: framework inlined in orchestrator
+    PENNYFARTHING_SCRIPTS="$PROJECT_ROOT/pennyfarthing"
+elif [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core" ]]; then
+    # Normal install
+    PENNYFARTHING_SCRIPTS="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
+fi
+
+if [[ -n "$PENNYFARTHING_SCRIPTS" ]]; then
+    export PYTHONPATH="$PENNYFARTHING_SCRIPTS:${PYTHONPATH:-}"
+fi
+
+# Run Python validation hook
+python3 -m pennyfarthing_scripts.schema_validation_hook

package/pennyfarthing-dist/scripts/hooks/sprint-yaml-validation.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+#
+# Sprint YAML Validation Hook (PostToolUse)
+#
+# Validates sprint YAML files after Edit/Write operations to ensure
+# compatibility with the yaml npm package used by Cyclist's SprintPanel.
+#
+# The yaml npm package follows YAML 1.2 strictly and rejects:
+# - Single-quoted strings with blank lines
+# - Invalid multiline string formats
+#
+# When validation fails, returns additionalContext with an error message
+# prompting the agent to fix the YAML format.
+#
+# Input: JSON via stdin with tool_name, tool_input
+# Output: JSON with additionalContext on validation failure
+#
+# See also: .pennyfarthing/scripts/validation/validate-sprint-yaml.sh
+
+set -euo pipefail
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+# Extract tool name and file path from input
+TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || echo "")
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || echo "")
+
+# Only process Edit and Write operations on sprint YAML files
+if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+# Check if it's a sprint YAML file
+if [[ ! "$FILE_PATH" =~ sprint/.*\.(yaml|yml)$ ]]; then
+  exit 0
+fi
+
+# Check if the file exists
+if [[ ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Validate using Node.js yaml package (same parser Cyclist uses)
+VALIDATION_ERROR=$(node --input-type=module -e "
+import { parse } from 'yaml';
+import { readFileSync } from 'fs';
+
+try {
+  const content = readFileSync('$FILE_PATH', 'utf-8');
+  parse(content);
+  process.exit(0);
+} catch (e) {
+  console.error(e.message);
+  process.exit(1);
+}
+" 2>&1) && VALID=true || VALID=false
+
+if [[ "$VALID" == "true" ]]; then
+  # Valid YAML - exit silently
+  exit 0
+fi
+
+# Validation failed - return error context to agent
+# Escape special characters for JSON
+ESCAPED_ERROR=$(echo "$VALIDATION_ERROR" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | tr '\n' ' ')
+ESCAPED_PATH=$(echo "$FILE_PATH" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g')
+
+cat << EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "⚠️ SPRINT YAML VALIDATION FAILED\n\nFile: $ESCAPED_PATH\nError: $ESCAPED_ERROR\n\nThe sprint YAML file has invalid syntax that will break the Cyclist SprintPanel.\n\nCommon fix: Single-quoted strings cannot contain blank lines in YAML 1.2.\nUse literal block scalars (|) for multiline strings instead.\n\nTo auto-fix, run: yq eval -o=json '$ESCAPED_PATH' > /tmp/sprint.json && yq eval -P /tmp/sprint.json > '$ESCAPED_PATH'"
+  }
+}
+EOF
+
+exit 0

package/pennyfarthing-dist/scripts/lib/find-root.sh

@@ -1,12 +1,13 @@
 #!/usr/bin/env bash
-# Shared utility: Find project root by walking up to .pennyfarthing/
+# Shared utility: Find project root
 #
-# Usage:
-#   source "$SCRIPT_DIR/../lib/find-root.sh"
-#   # PROJECT_ROOT is now set
+# Resolution order:
+# 1. Honor explicit PROJECT_ROOT override (from Claude Code or user)
+# 2. BASH_SOURCE derivation (auto-detect caller's location)
+# 3. PWD walk looking for .pennyfarthing/ (fallback)
 #
-# Or simply:
-#   source /path/to/find-root.sh
+# Usage:
+#   source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 #   # PROJECT_ROOT is now set
 
 # Allow explicit override
@@ -15,7 +16,31 @@ if [[ -n "${PROJECT_ROOT:-}" ]]; then
     return 0 2>/dev/null || exit 0
 fi
 
-# Walk up from PWD looking for .pennyfarthing/
+# BASH_SOURCE approach: derive from caller's location
+# BASH_SOURCE[1] is the script that sourced us, BASH_SOURCE[0] is this file
+_caller_script="${BASH_SOURCE[1]:-}"
+if [[ -n "$_caller_script" ]]; then
+    _real_dir="$(cd "$(dirname "$_caller_script")" && pwd -P)"
+    if [[ "$_real_dir" == */pennyfarthing-dist/scripts/* ]] || \
+       [[ "$_real_dir" == */.pennyfarthing/scripts/* ]]; then
+        # Extract package root from path
+        _pkg="${_real_dir%/scripts/*}"
+        _pkg="${_pkg%/pennyfarthing-dist}"
+        _pkg="${_pkg%/.pennyfarthing}"
+        if [[ "$_pkg" == */node_modules/* ]]; then
+            PROJECT_ROOT="${_pkg%/node_modules/*}"
+        else
+            PROJECT_ROOT="$_pkg"
+        fi
+        unset _real_dir _pkg _caller_script
+        export PROJECT_ROOT
+        return 0 2>/dev/null || exit 0
+    fi
+    unset _real_dir
+fi
+unset _caller_script
+
+# Fallback: walk up from PWD looking for .pennyfarthing/
 _d="$PWD"
 while [[ ! -d "$_d/.pennyfarthing" ]] && [[ "$_d" != "/" ]]; do
     _d="$(dirname "$_d")"

package/pennyfarthing-dist/scripts/misc/generate-skill-docs.sh

@@ -19,8 +19,19 @@ set -euo pipefail
 
 # Self-locate: derive PROJECT_ROOT from this script's position
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-source "$SCRIPT_DIR/../lib/find-root.sh"
-# PROJECT_ROOT is now set
+
+# Detect if we're in framework development or a consumer project
+# In framework dev: scripts/misc/generate-skill-docs.sh is in pennyfarthing/pennyfarthing-dist/scripts/misc/
+# In consumer: this is symlinked from .pennyfarthing/scripts/misc/
+if [[ "$SCRIPT_DIR" == */pennyfarthing/pennyfarthing-dist/scripts/* ]]; then
+  # Framework development context - derive from script location
+  PROJECT_ROOT="${SCRIPT_DIR%/pennyfarthing-dist/scripts/*}"
+  export PROJECT_ROOT
+else
+  # Consumer project context - use find-root.sh
+  source "$SCRIPT_DIR/../lib/find-root.sh"
+  # PROJECT_ROOT is now set
+fi
 
 # Default paths
 REGISTRY_PATH="${PROJECT_ROOT}/pennyfarthing-dist/skills/skill-registry.yaml"