@pennyfarthing/core 7.6.1 → 7.8.0

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-05-complete.md

@@ -0,0 +1,71 @@
+# Step 5: Complete
+
+Cleanup workflow finished. Final summary and next steps.
+
+## Summary
+
+```
+## Git Cleanup Complete ✅
+
+### Session Summary
+- Groups committed: {n}
+- Files organized: {count}
+- Pushed to remote: {yes/no}
+
+### Commits
+{list of commit hashes and messages}
+
+### Time Saved
+Organizing {n} scattered changes into {m} proper commits
+with conventional commit messages and branch workflow.
+```
+
+## Post-Cleanup Tasks
+
+### If Changes Remain
+
+Intentionally skipped files can be:
+- Committed in next cleanup session
+- Added to .gitignore if generated
+- Discarded with `git checkout -- {file}`
+
+### Branch Maintenance
+
+Run periodically to clean up merged branches:
+
+```bash
+# Delete branches merged into develop
+git branch --merged develop | grep -v "develop\|main" | xargs -r git branch -d
+```
+
+### Stash Cleanup
+
+If old stashes accumulated:
+
+```bash
+# View stashes
+git stash list
+
+# Drop old cleanup stashes
+git stash drop stash@{n}
+```
+
+## Quick Re-run
+
+To run git-cleanup again:
+
+```
+/git-cleanup
+```
+
+Or for a quick status check:
+
+```bash
+./scripts/run.sh git/git-status-all.sh
+```
+
+---
+
+**Cleanup complete.** Working directory is organized.
+
+<!-- CYCLIST:CONTINUE -->

package/pennyfarthing-dist/workflows/git-cleanup.yaml

@@ -0,0 +1,59 @@
+# Git Cleanup Workflow - Organize uncommitted changes into proper commits
+# Stepped workflow for cleaning up scattered changes across repos
+#
+# Flow: Analyze → Categorize → [Approve] → Execute → Verify → [Push]
+# Use for: end-of-session cleanup, organizing mixed changes, git hygiene
+#
+# Key features:
+# - Multi-repo support (configured via repos.yaml)
+# - Conventional commit enforcement
+# - Branch workflow (never direct to develop)
+# - Stash-based change isolation
+
+workflow:
+  name: git-cleanup
+  description: Organize uncommitted changes into proper commits/branches by initiative
+  version: "1.0.0"
+  type: stepped
+
+  # Step configuration
+  steps:
+    path: ./git-cleanup/steps/
+    pattern: step-{nn}-*.md
+
+  # Variables available in step files
+  variables:
+    output_file: .session/git-cleanup-plan.md
+    repos_config: .claude/project/repos.yaml
+
+  # User approval gates
+  gates:
+    after_steps: [2, 4]  # After categorize and after execute
+    gate_marker: "<!-- GATE -->"
+
+  # Collaboration menus
+  collaboration:
+    menus:
+      - key: A
+        name: Analyze More
+        description: Dig deeper into a specific repo or change set
+      - key: E
+        name: Edit Groupings
+        description: Modify the proposed change groupings
+      - key: T
+        name: Track in Jira
+        description: Promote a group to a tracked Jira story (standalone-style)
+      - key: C
+        name: Continue
+        description: Approve and proceed to next step
+      - key: S
+        name: Skip Group
+        description: Skip a group (leave changes uncommitted)
+
+  # Agent assignment - uses orchestrator for cross-repo coordination
+  agent: orchestrator
+
+  # Triggers
+  triggers:
+    commands: [git-cleanup, cleanup]
+    tags: [git, cleanup, maintenance]

package/pennyfarthing-dist/guides/XML-TAGS.md

@@ -1,156 +0,0 @@
-# XML Tag Taxonomy
-
-Pennyfarthing uses XML-style tags to structure agent definitions and skill documentation. These tags help LLMs identify and prioritize different types of content.
-
-## Priority Tags
-
-Tags that affect LLM behavior and attention.
-
-### `<critical>`
-
-**Purpose:** Non-negotiable rules that MUST be followed. LLMs should treat these as hard constraints.
-
-**Usage:** Gates, invariants, protocol requirements, things that break the system if ignored.
-
-```markdown
-<critical>
-**Never edit sprint YAML directly.** Use scripts.
-</critical>
-```
-
-**Examples:**
-- "Subagent output is NOT visible to Cyclist"
-- "NEVER mark acceptance criteria as complete" (for subagents)
-- "Write assessment BEFORE spawning handoff subagent"
-
-### `<gate>`
-
-**Purpose:** Prerequisites that MUST be verified before proceeding. Checklist-style validation.
-
-**Usage:** Entry/exit conditions for workflows, handoff requirements, quality gates.
-
-```markdown
-<gate>
-## Handoff Checklist
-1. Session file exists
-2. Acceptance criteria defined
-3. Feature branches created
-</gate>
-```
-
-**Difference from `<critical>`:** Gates are procedural checkpoints; critical items are invariant rules.
-
-### `<info>`
-
-**Purpose:** Contextual information that helps but doesn't constrain. Reference material.
-
-**Usage:** Background context, defaults, file locations, tips.
-
-```markdown
-<info>
-**Workflow:** SM → TEA → Dev → Reviewer → SM
-**Skills:** `/sprint`, `/jira`, `/testing`
-</info>
-```
-
-## Identity Tags
-
-Tags that define agent personality and role.
-
-### `<persona>`
-
-**Purpose:** Character personality from the active theme. Loaded at agent activation.
-
-**Usage:** Top of agent files, sets tone and style.
-
-```markdown
-<persona>
-Auto-loaded by `agent-session.sh start` from theme config.
-**Fallback if not loaded:** Supportive, methodical, detail-oriented
-</persona>
-```
-
-### `<role>`
-
-**Purpose:** Agent's position in the workflow and primary responsibility.
-
-**Usage:** Brief statement of what the agent does and when it's invoked.
-
-```markdown
-<role>
-Test specification, RED phase execution, handoff to Dev
-</role>
-```
-
-## Structure Tags
-
-Tags that organize agent content.
-
-### `<helpers>`
-
-**Purpose:** Describes Haiku subagents and their invocation pattern.
-
-**Usage:** Lists subagents, their purposes, and how to spawn them.
-
-### `<responsibilities>`
-
-**Purpose:** Bullet list of what this agent does vs delegates.
-
-### `<skills>`
-
-**Purpose:** Slash commands this agent commonly uses.
-
-### `<context>`
-
-**Purpose:** Guide files and sidecars to reference.
-
-### `<reasoning-mode>`
-
-**Purpose:** Verbose/quiet toggle for showing thought process.
-
-### `<on-activation>`
-
-**Purpose:** Startup checklist - what to do when agent is invoked.
-
-### `<exit>`
-
-**Purpose:** How to leave agent mode and cleanup.
-
-## Usage Guidelines
-
-1. **`<critical>` sparingly** - If everything is critical, nothing is. Reserve for true invariants.
-
-2. **`<gate>` for checkpoints** - Use when there's a clear pass/fail condition.
-
-3. **`<info>` generously** - Helpful context improves agent performance.
-
-4. **Order matters:**
-   ```
-   <persona>      # Who am I?
-   <role>         # What do I do?
-   <helpers>      # Who helps me?
-   <critical>     # What must I never violate?
-   <gate>         # What must I check?
-   <info>         # What's helpful to know?
-   ```
-
-5. **Close your tags** - Always use `</tag>` even though markdown parsers are lenient.
-
-## Tag Locations
-
-| Tag | Typical Location |
-|-----|------------------|
-| `<critical>` | Agent files, skill files, workflow instructions |
-| `<gate>` | Subagent files (handoff, finish, setup) |
-| `<info>` | Agent files, guide files |
-| `<persona>` | Agent files (top) |
-| `<role>` | Agent files (after persona) |
-
-## Adding New Tags
-
-Before adding a new tag type:
-
-1. Check if existing tags cover the use case
-2. Document the tag's purpose and priority level
-3. Update this file
-4. Be consistent across all files using the tag

package/pennyfarthing-dist/scripts/hooks/question-reflector-check.mjs

@@ -1,380 +0,0 @@
-#!/usr/bin/env node
-/**
- * question-reflector-check.mjs - Question reflector enforcement hook
- *
- * Story: MSSCI-12393
- *
- * Validates that any question asked by the agent has an appropriate
- * CYCLIST reflector marker. Used by both Stop hook and PreToolUse hook.
- *
- * Question types detected:
- *   - Direct questions (ends with ?)
- *   - Implicit questions (would you like, should I, let me know if)
- *   - Choice offerings (option A or B, we could do X or Y)
- *
- * Required markers:
- *   <!-- CYCLIST:QUESTION:yesno -->
- *   <!-- CYCLIST:QUESTION:open -->
- *   <!-- CYCLIST:CHOICES:opt1,opt2,opt3 -->
- */
-
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-
-// =============================================================================
-// Constants
-// =============================================================================
-
-// Marker patterns
-const QUESTION_MARKER_PATTERN = /<!--\s*CYCLIST:QUESTION:(yesno|open)\s*-->/i;
-const CHOICES_MARKER_PATTERN = /<!--\s*CYCLIST:CHOICES:[^>]+\s*-->/i;
-
-// Question patterns - direct (with ?)
-// Match: end of line, followed by space+capital (new sentence), or followed by newline
-const DIRECT_QUESTION_PATTERN = /\?(\s*$|\s+[A-Z]|\s*\n)/;
-
-// Rhetorical patterns to exclude
-const RHETORICAL_PATTERNS = /\b(the question (was|is)|asked whether|wondering if)\b/i;
-
-// Implicit question patterns
-const IMPLICIT_PATTERNS = [
-  /\bwould you like\b/i,
-  /\bshould I\b/i,
-  /\bdo you want\b/i,
-  /\blet me know if\b/i,
-  /\bwhat do you (think|prefer)\b/i,
-  /\byour (preference|thoughts)\b/i,
-  /\bcould you (clarify|confirm|specify)\b/i,
-  /\bwhich (option|approach)\b/i,
-  /\bready to proceed\b/i,
-];
-
-// Choice offering patterns
-const CHOICE_PATTERNS = [
-  /\boption [A-D]\b/i,
-  /\bchoice [0-9]\b/i,
-  /\bwe could (either|do)\b/i,
-  /\balternatively\b/i,
-  /\bor would you prefer\b/i,
-  /\bpick one\b/i,
-  /\bchoose between\b/i,
-];
-
-// =============================================================================
-// Helper Functions
-// =============================================================================
-
-/**
- * Strip fenced code blocks from text to avoid false positives
- * @param {string} text - The text to process
- * @returns {string} Text with code blocks removed
- */
-function stripCodeBlocks(text) {
-  // Remove fenced code blocks (```...```)
-  let result = text.replace(/```[\s\S]*?```/g, '');
-  // Remove inline code (`...`)
-  result = result.replace(/`[^`]+`/g, '');
-  return result;
-}
-
-// =============================================================================
-// Exported Functions
-// =============================================================================
-
-/**
- * Check if enforcement should be skipped based on config
- * @param {object} config - The config object with workflow settings
- * @returns {boolean} True if enforcement should be skipped
- */
-export function shouldSkipEnforcement(config) {
-  const workflow = config?.workflow || {};
-
-  // Legacy: turbo mode skips enforcement
-  if (workflow.permission_mode === 'turbo') {
-    return true;
-  }
-
-  // New: relay_mode skips enforcement (for auto-handoff flows)
-  if (workflow.relay_mode === true) {
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Detect if a message contains a question
- * @param {string} message - The message to check
- * @returns {{ detected: boolean, type: string }} Detection result
- */
-export function detectQuestion(message) {
-  // Strip code blocks first
-  const cleanMessage = stripCodeBlocks(message);
-
-  // Check for rhetorical patterns - if found, not a real question
-  if (RHETORICAL_PATTERNS.test(cleanMessage)) {
-    return { detected: false, type: '' };
-  }
-
-  // Check for direct questions (with ?)
-  if (DIRECT_QUESTION_PATTERN.test(cleanMessage)) {
-    return { detected: true, type: 'direct' };
-  }
-
-  // Check for implicit questions
-  for (const pattern of IMPLICIT_PATTERNS) {
-    if (pattern.test(cleanMessage)) {
-      return { detected: true, type: 'implicit' };
-    }
-  }
-
-  // Check for choice offerings
-  for (const pattern of CHOICE_PATTERNS) {
-    if (pattern.test(cleanMessage)) {
-      return { detected: true, type: 'choices' };
-    }
-  }
-
-  return { detected: false, type: '' };
-}
-
-/**
- * Check if a message has a CYCLIST reflector marker
- * @param {string} message - The message to check
- * @returns {boolean} True if a marker is present
- */
-export function hasReflectorMarker(message) {
-  return QUESTION_MARKER_PATTERN.test(message) || CHOICES_MARKER_PATTERN.test(message);
-}
-
-/**
- * Extract the last assistant message from a transcript
- * @param {Array} transcript - Array of message objects
- * @returns {string} The last assistant message content
- */
-export function extractLastAssistantMessage(transcript) {
-  // Find the last assistant message (reverse order)
-  for (let i = transcript.length - 1; i >= 0; i--) {
-    const msg = transcript[i];
-    if (msg.role === 'assistant') {
-      // Handle content as string or array
-      if (typeof msg.content === 'string') {
-        return msg.content;
-      }
-      if (Array.isArray(msg.content)) {
-        // Extract text from text blocks, skip tool_use blocks
-        return msg.content
-          .filter(block => block.type === 'text')
-          .map(block => block.text)
-          .join('');
-      }
-      return '';
-    }
-  }
-  return '';
-}
-
-/**
- * Build the block reason message
- * @param {string} questionType - The type of question detected
- * @returns {string} The reason message
- */
-function buildBlockReason(questionType) {
-  let reason = 'You asked a question but did not emit a CYCLIST reflector marker. ';
-
-  switch (questionType) {
-    case 'direct':
-      reason += 'Add <!-- CYCLIST:QUESTION:yesno --> for yes/no questions or <!-- CYCLIST:QUESTION:open --> for open-ended questions before your question.';
-      break;
-    case 'implicit':
-      reason += 'Add <!-- CYCLIST:QUESTION:yesno --> before phrases like "would you like" or "should I".';
-      break;
-    case 'choices':
-      reason += 'Add <!-- CYCLIST:CHOICES:option1,option2,option3 --> listing the choices before presenting options.';
-      break;
-    default:
-      reason += 'Add the appropriate marker before your question.';
-  }
-
-  reason += ' Re-state your question with the appropriate marker.';
-  return reason;
-}
-
-/**
- * Main check for Stop hook - validates question reflector markers
- * @param {object} input - Hook input with transcript_path, stop_hook_active
- * @param {object} config - Config with workflow settings
- * @param {string} lastMessage - The last assistant message (pre-extracted for testing)
- * @returns {{ ok: true } | { decision: 'block', reason: string }}
- */
-export function checkQuestionReflector(input, config, lastMessage) {
-  // Prevent infinite loops
-  if (input.stop_hook_active) {
-    return { ok: true };
-  }
-
-  // Skip enforcement in relay/turbo mode
-  if (shouldSkipEnforcement(config)) {
-    return { ok: true };
-  }
-
-  // If no message, allow
-  if (!lastMessage) {
-    return { ok: true };
-  }
-
-  // If marker present, allow
-  if (hasReflectorMarker(lastMessage)) {
-    return { ok: true };
-  }
-
-  // Check for questions
-  const detection = detectQuestion(lastMessage);
-  if (!detection.detected) {
-    return { ok: true };
-  }
-
-  // Question detected without marker - block
-  return {
-    decision: 'block',
-    reason: buildBlockReason(detection.type),
-  };
-}
-
-/**
- * Check for AskUserQuestion PreToolUse hook
- * @param {object} input - Hook input with tool_name, tool_input
- * @param {object} config - Config with workflow settings
- * @param {string} [recentOutput] - Recent assistant output to check for marker
- * @returns {{ ok: true } | { decision: 'block', reason: string }}
- */
-export function checkAskUserQuestion(input, config, recentOutput = '') {
-  // Skip enforcement in relay/turbo mode
-  if (shouldSkipEnforcement(config)) {
-    return { ok: true };
-  }
-
-  // If marker present in recent output, allow
-  if (recentOutput && hasReflectorMarker(recentOutput)) {
-    return { ok: true };
-  }
-
-  // Block - AskUserQuestion requires a marker
-  return {
-    decision: 'block',
-    reason: 'AskUserQuestion tool requires a CYCLIST marker. Add <!-- CYCLIST:QUESTION:yesno -->, <!-- CYCLIST:QUESTION:open -->, or <!-- CYCLIST:CHOICES:... --> before using this tool.',
-  };
-}
-
-// =============================================================================
-// CLI Entry Point (for bash wrapper)
-// =============================================================================
-
-/**
- * Load config from .pennyfarthing/config.local.yaml
- * @param {string} projectDir - The project directory
- * @returns {object} The config object
- */
-function loadConfig(projectDir) {
-  try {
-    const configPath = join(projectDir, '.pennyfarthing', 'config.local.yaml');
-    const content = readFileSync(configPath, 'utf-8');
-    // Simple YAML parsing for the fields we need
-    const config = { workflow: {} };
-
-    // Extract permission_mode
-    const modeMatch = content.match(/permission_mode:\s*(\w+)/);
-    if (modeMatch) {
-      config.workflow.permission_mode = modeMatch[1];
-    }
-
-    // Extract relay_mode
-    const relayMatch = content.match(/relay_mode:\s*(true|false)/);
-    if (relayMatch) {
-      config.workflow.relay_mode = relayMatch[1] === 'true';
-    }
-
-    return config;
-  } catch {
-    // Default config if file doesn't exist
-    return { workflow: { permission_mode: 'manual' } };
-  }
-}
-
-/**
- * Read transcript and extract last assistant message
- * @param {string} transcriptPath - Path to JSONL transcript
- * @returns {string} The last assistant message
- */
-function readTranscript(transcriptPath) {
-  try {
-    const content = readFileSync(transcriptPath, 'utf-8');
-    const lines = content.trim().split('\n').filter(Boolean);
-
-    // Parse JSONL and build transcript array
-    const transcript = [];
-    for (const line of lines) {
-      try {
-        transcript.push(JSON.parse(line));
-      } catch {
-        // Skip malformed lines
-      }
-    }
-
-    return extractLastAssistantMessage(transcript);
-  } catch {
-    return '';
-  }
-}
-
-/**
- * Main CLI entry point
- */
-async function main() {
-  // Read input from stdin
-  let inputData = '';
-  for await (const chunk of process.stdin) {
-    inputData += chunk;
-  }
-
-  let input;
-  try {
-    input = JSON.parse(inputData);
-  } catch {
-    // Invalid input - allow to prevent breaking
-    console.log(JSON.stringify({ ok: true }));
-    process.exit(0);
-  }
-
-  // Determine project directory
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
-  // Load config
-  const config = loadConfig(projectDir);
-
-  // Determine hook type based on input
-  if (input.tool_name === 'AskUserQuestion') {
-    // PreToolUse hook for AskUserQuestion
-    // For PreToolUse, we'd need the recent output - for now, just check config
-    const result = checkAskUserQuestion(input, config, '');
-    console.log(JSON.stringify(result));
-  } else {
-    // Stop hook
-    const transcriptPath = input.transcript_path || '';
-    const lastMessage = transcriptPath ? readTranscript(transcriptPath) : '';
-    const result = checkQuestionReflector(input, config, lastMessage);
-    console.log(JSON.stringify(result));
-  }
-
-  process.exit(0);
-}
-
-// Run if called directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch((err) => {
-    console.error(err);
-    // On error, allow to prevent breaking
-    console.log(JSON.stringify({ ok: true }));
-    process.exit(0);
-  });
-}