@pennyfarthing/core 9.0.0 → 9.0.3

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/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/skills/agentic-patterns/SKILL.md

@@ -6,6 +6,10 @@ allowed_tools: [Read, Glob, Grep, Task]
 
 # Agentic Patterns Skill
 
+<run>When designing agent behavior, debugging agent failures, improving agent reliability.</run>
+
+<output>Core reasoning patterns for building effective LLM agents. Includes ReAct, Plan-and-Execute, Self-Reflection, confidence calibration, error recovery, multi-agent coordination, and context management strategies.</output>
+
 **Purpose:** Core reasoning patterns for building effective LLM agents.
 
 **Use when:** Designing agent behavior, debugging agent failures, improving agent reliability.

package/pennyfarthing-dist/skills/changelog/SKILL.md

@@ -3,6 +3,24 @@ name: changelog
 description: Maintain changelogs following Keep a Changelog format. Use when creating release notes, parsing conventional commits for changelog entries, auto-generating changelog sections from git history, or preparing CHANGELOG.md for releases.
 ---
 
+<run>
+Commands for changelog maintenance:
+- Parse conventional commits for changelog entries
+- Auto-generate changelog sections from git history
+- Version bump decisions using semantic versioning
+- Create release notes and CHANGELOG.md updates
+</run>
+
+<output>
+Changelog entries in Keep a Changelog format:
+- Added (new features from `feat:` commits)
+- Changed (changes from `perf:` commits, breaking changes)
+- Deprecated (features marked for removal)
+- Removed (removed features)
+- Fixed (bug fixes from `fix:` commits)
+- Security (vulnerability fixes)
+</output>
+
 # Changelog Management Skill
 
 ## When to Use This Skill

package/pennyfarthing-dist/skills/code-review/SKILL.md

@@ -3,7 +3,11 @@ name: code-review
 description: Code review checklists and patterns for Pennyfarthing. Use when reviewing PRs, self-reviewing code, or checking for common issues before commit.
 ---
 
-# Code Review Skill 
+# Code Review Skill
+
+<run>Review code against the checklists below. Focus on authorization, error handling, TypeScript/React patterns, and performance.</run>
+
+<output>Code review comments using [MUST FIX], [SUGGESTION], [QUESTION], [NICE] prefixes</output>
 
 ## Overview
 

package/pennyfarthing-dist/skills/context-engineering/SKILL.md

@@ -6,6 +6,9 @@ allowed_tools: [Read, Glob, Grep, Task]
 
 # Context Engineering Skill
 
+<run>context-engineering</run>
+<output>strategies for managing context windows in long-running agent sessions</output>
+
 **Purpose:** Strategies for managing context windows efficiently in long-running agent sessions.
 
 **Use when:** Working on complex tasks, approaching context limits, designing subagent prompts.

package/pennyfarthing-dist/skills/cyclist/SKILL.md

@@ -15,7 +15,7 @@ args: "[check|status]"
 Check if running inside Cyclist visual terminal.
 
 <run>
-.pennyfarthing/scripts cyclist/is-cyclist.sh
+.pennyfarthing/scripts/cyclist/is-cyclist.sh
 </run>
 
 <output>
@@ -23,7 +23,7 @@ JSON: `{"cyclist": true}` with exit 0 if in Cyclist, `{"cyclist": false}` with e
 </output>
 
 <example>
-.pennyfarthing/scripts cyclist/is-cyclist.sh
+.pennyfarthing/scripts/cyclist/is-cyclist.sh
 # Returns: {"cyclist": true}
 </example>
 

package/pennyfarthing-dist/skills/dev-patterns/SKILL.md

@@ -4,6 +4,30 @@ description: Common development patterns, fixes, and gotchas. Use when implement
 allowed_tools: [Read, Glob, Grep, Task]
 ---
 
+<run>
+Reference this skill when implementing features, debugging issues, or avoiding known pitfalls in development. Use these patterns to guide:
+- Working directory management in bash commands
+- TypeScript type system decisions
+- Error handling in Go
+- Test structure and isolation
+- HTTP status code selection
+- Turn-efficient coding practices
+- Background task execution
+
+The patterns capture common gotchas and solutions across multiple languages and frameworks.
+</run>
+
+<output>
+Following these patterns produces:
+- Reliable bash commands that work regardless of current directory
+- TypeScript builds that pass verbatimModuleSyntax validation
+- Go code with proper error handling and validation
+- Well-isolated, maintainable test suites
+- Consistent HTTP API behavior
+- Faster task completion through turn-efficient techniques
+- Properly tracked background operations
+</output>
+
 # Dev Patterns Skill
 
 ## Overview

package/pennyfarthing-dist/skills/finalize-run/SKILL.md

@@ -5,6 +5,9 @@ description: Validate and save benchmark run results. Use when completing a benc
 
 # Finalize Run Skill
 
+<run>Validates and saves benchmark run results</run>
+<output>JSON with validation success status and saved file path</output>
+
 All runs MUST pass through this skill before saving. This is the guardrail.
 
 ## Invocation

package/pennyfarthing-dist/skills/judge/SKILL.md

@@ -7,6 +7,14 @@ description: Evaluate agent responses using standardized rubrics. Use when scori
 
 Canonical evaluation of agent responses. All judging goes through this skill.
 
+<run>
+Judge is invoked via CLI with `/judge --mode <mode> --data <json>` to evaluate agent responses using standardized rubrics. Modes include solo (single response), compare (two responses), phase-specific modes (SM/TEA/Dev/Reviewer), coherence (chain coherence), swebench (SWE-bench evaluation), and ground-truth (patch comparison).
+</run>
+
+<output>
+Judge returns structured JSON output containing evaluation scores, weighted totals, reasoning, and token usage information. Output format varies by mode: solo/compare return individual or comparative scores with dimensions (correctness, depth, quality, persona); phase modes return team evaluations; coherence returns a rating (excellent/good/poor); swebench/ground-truth return deterministic scores via Python scripts. All responses include validation of results and error handling for failed evaluations.
+</output>
+
 ## Invocation
 
 ```

package/pennyfarthing-dist/skills/just/SKILL.md

@@ -8,6 +8,17 @@ args: "[recipe] [args...]"
 
 # /just - Project Task Runner
 
+<run>
+Main commands:
+- `just --list` - List all available recipes
+- `just <recipe>` - Run a specific recipe (e.g., `just build`, `just test`, `just cyclist`)
+</run>
+
+<output>
+- `just --list` outputs a list of available recipes with their descriptions
+- Individual recipe commands output their execution results (build logs, test results, etc.) depending on the recipe
+</output>
+
 `just` is a command runner for project tasks. All commands run from the **project root**.
 
 ## Commands

package/pennyfarthing-dist/skills/mermaid/SKILL.md

@@ -3,6 +3,22 @@ name: mermaid
 description: Generate diagrams using Mermaid syntax. Use this skill when creating architecture diagrams, sequence diagrams, ER diagrams, flowcharts, or any visual documentation in markdown files.
 ---
 
+<run>
+Generate Mermaid diagrams by writing code blocks with the `mermaid` language identifier in markdown files. Mermaid syntax is rendered natively by GitHub, GitLab, and most markdown editors. Choose the appropriate diagram type (flowchart, sequence, ER, class, or state) based on what you need to visualize.
+</run>
+
+<output>
+Mermaid code blocks that render as diagrams. Example output format:
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+
+The diagram renders visually in GitHub, GitLab, and compatible markdown viewers.
+</output>
+
 # Mermaid Diagram Skill
 
 ## When to Use This Skill

package/pennyfarthing-dist/skills/otel/skill.md

@@ -6,6 +6,10 @@ allowed_tools: [Read, Glob, Grep, Task]
 
 # OTEL Skill - Claude Code Telemetry
 
+<run>Enable OTEL debug logging and inspect telemetry data to understand span structure, attributes, and correlation patterns.</run>
+
+<output>Enriched span data with tool metadata, file information, and correlation IDs for UI visualization and telemetry analysis.</output>
+
 ## Purpose
 
 Document the actual OTEL data Claude Code emits. This is ground truth, not speculation.

package/pennyfarthing-dist/skills/permissions/skill.md

@@ -5,6 +5,9 @@ description: Manage runtime permission grants - list active grants, add/revoke t
 
 # Permission Management Skill
 
+<run>/permissions</run>
+<output>List all active permission grants</output>
+
 ## Overview
 
 Pennyfarthing uses a runtime permission system for tool access control. This skill provides commands to view and manage permission grants.

package/pennyfarthing-dist/skills/persona-benchmark/SKILL.md

@@ -7,6 +7,15 @@ description: Run benchmarks to compare persona effectiveness across themes. Use
 
 Run benchmarks to compare persona effectiveness.
 
+<run>
+/persona-benchmark <test-case-id> <persona>
+/persona-benchmark <test-case-id> <persona> [--analyze] [--suite]
+</run>
+
+<output>
+Benchmark results saved to `.claude/benchmarks/results/{timestamp}-{persona}-{test-case-id}.yaml` with quantitative and qualitative metrics, or analysis summary when using `--analyze`.
+</output>
+
 ## Usage
 
 ```