@pennyfarthing/core 9.2.0 → 9.3.0

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-01-analyze.md

@@ -1,103 +0,0 @@
-# Step 1: Analyze Current State
-
-<purpose>
-Gather the current git state across all configured repositories and build a complete picture of uncommitted changes across ALL repos.
-</purpose>
-
-<instructions>
-1. Run the multi-repo git status script to show branch, staged/unstaged changes, and unpushed commits
-2. For each repo with changes, gather detailed diffs and commit patterns
-3. Check for active work sessions to understand context
-4. Verify pre-flight checks (no merge conflicts, develop branches up to date, no secrets)
-5. Present findings in structured format with analysis results by repo
-</instructions>
-
-<output>
-Analysis results grouped by repo including:
-- Current branch name
-- Count of unpushed commits
-- List of uncommitted changes with status (M/A/D/??)
-- Any warnings or issues found
-- Ready for user choice: [A] to analyze specific repo, or [C] to continue
-</output>
-
-## Objective
-
-Build a complete picture of uncommitted changes across ALL repos defined in `.claude/project/pennyfarthing-settings.yaml`.
-
-## Execution
-
-### 1.1 Gather Git Status (All Repos)
-
-**CRITICAL: Use the multi-repo script, not plain `git status`.**
-
-```bash
-.pennyfarthing/scripts/git/git-status-all.sh
-```
-
-This shows branch, staged/unstaged changes, and unpushed commits for **all repos** defined in the project configuration.
-
-### 1.2 For Each Repo with Changes
-
-For repos with uncommitted changes, gather more detail:
-
-```bash
-# Show full diff for a specific repo
-git -C {repo_path} diff
-
-# Check the branch
-git -C {repo_path} branch --show-current
-```
-
-### 1.3 Check Recent Commit Patterns
-
-```bash
-# In each repo with changes, check commit style
-git -C {repo_path} log --oneline -5
-```
-
-### 1.4 Check Active Work Sessions
-
-```bash
-echo "=== Active Work Sessions ==="
-ls -la .session/*.md 2>/dev/null || echo "No active sessions"
-```
-
-If sessions exist, read headers to understand what work is in progress.
-
-## Pre-flight Checks
-
-| Check | Status | Action if Failed |
-|-------|--------|------------------|
-| No merge conflicts | ☐ | Resolve conflicts first |
-| Each repo's develop up to date | ☐ | `git -C {repo} pull origin develop` |
-| No uncommitted secrets | ☐ | Add to .gitignore |
-
-## Output Format
-
-Present findings in this structure:
-
-```
-## Analysis Results
-
-### Repo: {repo_name} (path: {repo_path})
-Branch: {current_branch}
-Unpushed: {count} commits
-
-**Uncommitted Changes:**
-- {file_path} ({status: M/A/D/??})
-- ...
-
-### Repo: {another_repo}
-...
-
-### Warnings
-- {any issues found}
-```
-
----
-
-**[A]** Analyze a specific repo in more detail
-**[C]** Continue to categorization
-
-<!-- CYCLIST:CHOICES:A,C -->

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-02-categorize.md

@@ -1,147 +0,0 @@
-# Step 2: Categorize Changes
-
-<purpose>
-Group uncommitted changes by initiative type (docs, chore, feat, fix, refactor, test) and organize them into logical groups that can be committed separately, accounting for multi-repo structure where changes may span multiple repositories.
-</purpose>
-
-<instructions>
-1. Analyze change patterns for each file across all repos to determine initiative type and groupings
-2. Use categorization rules (prefix reference) to classify each change
-3. Apply grouping heuristics (by story ID, feature, directory, file type)
-4. Propose groups in structured format showing which files belong together
-5. Present summary with approval gate requiring user decision before execution
-6. Allow editing, tracking in Jira, skipping groups, or continuing to execution
-</instructions>
-
-<output>
-Proposed change groups with:
-- Descriptive name for each group
-- Type (feat|fix|chore|docs|refactor|test)
-- Branch name format
-- Commit message format
-- Files listed by repo with their status
-- Rationale for grouping
-- Summary of total groups (quick commits, tracked stories, skipped)
-- User choices: [E] edit, [T] track, [S] skip, [C] continue
-</output>
-
-## Objective
-
-Organize scattered changes into logical groups that can be committed separately. Each group becomes one branch + commit.
-
-## Multi-Repo Awareness
-
-Changes may span multiple repos. Group by **initiative**, not by repo:
-
-```
-Group: "Todos WebSocket feature"
-  - pennyfarthing/packages/cyclist/src/main.ts
-  - pennyfarthing/packages/cyclist/src/websocket.ts
-  - pennyfarthing/packages/cyclist/src/public/hooks/useTodos.ts
-```
-
-All files in a group get committed together in their respective repos.
-
-## Categorization Rules
-
-### Prefix Reference
-
-| Prefix | Type | Branch Pattern | Files Typically |
-|--------|------|----------------|-----------------|
-| `docs:` | Documentation | `docs/description` | `docs/*.md`, `README.md` |
-| `chore:` | Maintenance | `chore/description` | configs, dependencies |
-| `chore(sprint):` | Sprint tracking | `chore/sprint-update` | `sprint/*.yaml` |
-| `chore(pennyfarthing):` | PF config | `chore/pf-description` | `.claude/**`, `.pennyfarthing/**` |
-| `feat:` | New feature | `feat/story-id-desc` | `src/**`, `internal/**` |
-| `fix:` | Bug fix | `fix/issue-desc` | various |
-| `refactor:` | Code improvement | `refactor/description` | `src/**` |
-| `test:` | Test changes | `test/description` | `**/tests/**`, `*.test.*` |
-
-### Grouping Heuristics
-
-1. **By Story ID** - If changes relate to a known story (check session files)
-2. **By Feature** - Related functionality across files/repos
-3. **By Directory** - Files in same directory often belong together
-4. **By File Type** - Docs together, configs together, source together
-
-## Execution
-
-### 2.1 Analyze Change Patterns
-
-For each changed file across all repos, determine:
-- Which initiative type it belongs to
-- If it relates to an active story
-- If it should group with other files
-- Which repo it's in
-
-### 2.2 Propose Groupings
-
-Present proposed groups in this format:
-
-```
-## Proposed Change Groups
-
-### Group 1: {descriptive_name}
-**Type:** {feat|fix|chore|docs|refactor|test}
-**Branch:** `{type}/{description}`
-**Commit:** `{type}({scope}): {message}`
-
-**Repo: pennyfarthing**
-- `packages/cyclist/src/main.ts` (M)
-- `packages/cyclist/src/websocket.ts` (M)
-
-**Repo: pennyfarthing-orchestrator**
-- `sprint/current-sprint.yaml` (M)
-
-Rationale: {why these files belong together}
-
----
-
-### Group 2: ...
-```
-
-### 2.3 Handle Ambiguous Changes
-
-For files that could belong to multiple groups:
-- Present options to user
-- Default to the smaller/more focused group
-- Allow "skip" to leave uncommitted
-
-## Tracking Decision
-
-For each group, decide tracking level:
-
-| Level | Branch | Jira | PR | Use When |
-|-------|--------|------|-----|----------|
-| **Quick** | `chore/*` | No | No | Maintenance, configs |
-| **Tracked** | `feat/MSSCI-*` | Yes | Yes | Features worth tracking |
-
-## Approval Gate
-
-**This step requires user approval before execution.**
-
-Present summary:
-
-```
-## Summary
-
-Total groups: {n}
-- Quick commits: {count}
-- Tracked stories: {count}
-- Skipped: {count}
-
-Repos affected: {list}
-Files to commit: {count}
-
-Ready to proceed?
-```
-
----
-
-**[E]** Edit groupings (modify a group)
-**[T]** Track a group in Jira (promote to standalone story)
-**[S]** Skip a group (leave those files uncommitted)
-**[C]** Continue to execution
-
-<!-- GATE -->
-<!-- CYCLIST:CHOICES:E,T,S,C -->

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-03-execute.md

@@ -1,215 +0,0 @@
-# Step 3: Execute Commits
-
-<purpose>
-Execute the approved change groupings by creating branches, staging and committing files, and merging to develop in each affected repo. Process groups sequentially without stashing changes.
-</purpose>
-
-<instructions>
-1. For each approved group, create branches in affected repos following naming conventions
-2. Stage only the files belonging to the current group (never commit directly to develop)
-3. Show diffs for verification before committing
-4. Commit with proper message format including Co-Authored-By line
-5. Merge branches to develop and delete local branches after merge
-6. For tracked groups, create Jira story, update branch with story ID, push and create PR
-7. Report progress after each group with status table
-8. Handle errors appropriately (hook rejection, merge conflicts, test failures)
-</instructions>
-
-<output>
-Execution progress report showing:
-- Status table with Group | Repo | Status | Branch
-- Commits created count
-- Branches merged count
-- List of repos updated
-- Confirmation ready to verify and push
-- User choices: [A] abort current group, [C] continue to verification
-</output>
-
-## Objective
-
-Execute the approved change groupings using a simple branch workflow. No stashing required.
-
-## Approach: One Group at a Time
-
-Process groups sequentially. For each group:
-1. Create branch in each affected repo
-2. Stage and commit the group's files
-3. Merge to develop
-4. Move to next group
-
-## Critical Rules
-
-- **NEVER commit directly to develop** - Branch protection hooks will reject it
-- **NEVER force push** - Data loss is not recoverable
-- **NEVER commit secrets** - Check for .env, credentials, API keys
-
-## Execution
-
-### For Each Group
-
-#### 3.1 Create Branch (in each affected repo)
-
-```bash
-# For each repo that has changes in this group
-git -C {repo_path} checkout develop
-git -C {repo_path} pull origin develop
-git -C {repo_path} checkout -b {branch_name}
-```
-
-**Branch naming:**
-- `feat/description` for features
-- `fix/description` for bug fixes
-- `chore/description` for maintenance
-- `docs/description` for documentation
-
-#### 3.2 Stage Files for This Group
-
-```bash
-# Stage only files belonging to this group
-git -C {repo_path} add {file1} {file2} ...
-```
-
-#### 3.3 Show Diff for Verification
-
-```bash
-# Show what will be committed
-git -C {repo_path} diff --cached --stat
-```
-
-#### 3.4 Commit
-
-```bash
-git -C {repo_path} commit -m "$(cat <<'EOF'
-{type}({scope}): {description}
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-EOF
-)"
-```
-
-#### 3.5 Merge to Develop
-
-```bash
-# Switch to develop
-git -C {repo_path} checkout develop
-
-# Merge the branch (fast-forward)
-git -C {repo_path} merge {branch_name}
-
-# Delete local branch
-git -C {repo_path} branch -d {branch_name}
-```
-
-#### 3.6 Repeat for Next Group
-
-Move to the next group and repeat steps 3.1-3.5.
-
-## Multi-Repo Groups
-
-When a group spans multiple repos, execute steps 3.1-3.5 in **each repo** before moving to the next group:
-
-```
-Group: "Todos WebSocket"
-  1. pennyfarthing: checkout -b feat/todos-websocket
-  2. pennyfarthing: add main.ts websocket.ts useTodos.ts
-  3. pennyfarthing: commit
-  4. pennyfarthing: merge to develop
-
-  (If orchestrator also had changes in this group, repeat there)
-
-  ✓ Group complete, move to next group
-```
-
-## Tracked Groups (Jira + PR Path)
-
-For groups marked for Jira tracking:
-
-#### Create Jira Story
-
-```bash
-JIRA_KEY=$(jira issue create \
-  --project MSSCI \
-  --type Story \
-  --summary "{title}" \
-  --body "{description}" \
-  --label pennyfarthing \
-  --no-input 2>&1 | grep -oE 'MSSCI-[0-9]+' | head -1)
-
-echo "Created: $JIRA_KEY"
-```
-
-#### Use Jira Key in Branch
-
-```bash
-BRANCH="feat/${JIRA_KEY}-${slug}"
-git -C {repo_path} checkout -b "$BRANCH"
-```
-
-#### Push and Create PR
-
-```bash
-git -C {repo_path} push -u origin "$BRANCH"
-
-gh pr create \
-  --repo {repo_owner}/{repo_name} \
-  --title "feat: {title} (${JIRA_KEY})" \
-  --body "## Summary
-{description}
-
-## Jira
-[${JIRA_KEY}](https://your-jira.atlassian.net/browse/${JIRA_KEY})
-
-## Test plan
-- [x] Changes verified locally"
-```
-
-#### Merge PR
-
-```bash
-gh pr merge --squash --delete-branch
-git -C {repo_path} checkout develop
-git -C {repo_path} pull origin develop
-```
-
-## Progress Tracking
-
-Report progress after each group:
-
-```
-## Execution Progress
-
-| Group | Repo | Status | Branch |
-|-------|------|--------|--------|
-| Sprint cleanup | orchestrator | ✅ Done | chore/sprint-update |
-| Todos WebSocket | pennyfarthing | ✅ Done | feat/todos-websocket |
-| Config changes | both | ⏳ In Progress | chore/config-update |
-```
-
-## Error Handling
-
-If a commit fails:
-1. **Hook rejection**: Check commit message format, fix and retry
-2. **Merge conflict**: Report to user, resolve manually
-3. **Test failure**: Report which tests failed, decide whether to proceed
-
-## Output
-
-After all groups processed:
-
-```
-## Execution Complete
-
-Commits created: {n}
-Branches merged: {n}
-Repos updated: {list}
-
-Ready to verify and push?
-```
-
----
-
-**[A]** Abort current group (leave those changes uncommitted)
-**[C]** Continue to verification
-
-<!-- GATE -->
-<!-- CYCLIST:CHOICES:A,C -->

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-04-verify.md

@@ -1,97 +0,0 @@
-# Step 4: Verify and Push
-
-<purpose>
-Verify that all changes have been properly committed across all repos, confirm no uncommitted changes remain (except intentionally skipped), review commit history, and push to remote.
-</purpose>
-
-<instructions>
-1. Run multi-repo git status script to confirm clean working directories
-2. Review commits in each repo that had changes using git log
-3. Check for cleanup branches that should have been deleted (expected: none)
-4. Generate summary report showing commits created by repo and final state
-5. Verify any intentionally skipped files
-6. Push develop to remote for each repo with new commits
-7. Offer user choices to push, keep local, or review again
-</instructions>
-
-<output>
-Git cleanup summary report including:
-- Commits created table by repo with commit hashes and messages
-- Final state for each repo (clean or files remaining)
-- List of any remaining work or skipped files
-- User choices: [P] push all to remote, [L] keep local, [R] review again
-</output>
-
-## Objective
-
-1. Confirm all changes are properly committed across all repos
-2. Verify no uncommitted changes remain (or only intentionally skipped)
-3. Show commit history for review
-4. Push to remote
-
-## Verification
-
-### 4.1 Final Git Status (All Repos)
-
-```bash
-.pennyfarthing/scripts/git/git-status-all.sh
-```
-
-Expected: Clean working directory in all repos, or only intentionally skipped files.
-
-### 4.2 Review Commits (Each Repo)
-
-```bash
-# For each repo that had changes
-git -C {repo_path} log --oneline -5
-```
-
-### 4.3 Branch Cleanup Check
-
-```bash
-# For each repo
-git -C {repo_path} branch | grep -v "develop\|main"
-```
-
-All cleanup branches should be deleted after merge.
-
-## Summary Report
-
-```
-## Git Cleanup Summary
-
-### Commits Created
-
-**pennyfarthing:**
-| Commit | Message |
-|--------|---------|
-| abc1234 | feat(cyclist): replace todos REST polling with WebSocket |
-
-**pennyfarthing-orchestrator:**
-| Commit | Message |
-|--------|---------|
-| (none) | |
-
-### Final State
-- pennyfarthing: {clean / X files remaining}
-- orchestrator: {clean / X files remaining}
-
-### Remaining Work
-{list any skipped files or deferred changes}
-```
-
-## Push
-
-Push develop to remote for each repo with new commits:
-
-```bash
-git -C {repo_path} push origin develop
-```
-
----
-
-**[P]** Push all repos to remote
-**[L]** Keep local (don't push yet)
-**[R]** Review commits again
-
-<!-- CYCLIST:CHOICES:P,L,R -->

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

@@ -1,78 +0,0 @@
-# Step 5: Complete
-
-<purpose>
-Complete the cleanup workflow by providing final summary of work performed, guidance for post-cleanup tasks, and quick re-run instructions for future cleanup sessions.
-</purpose>
-
-<instructions>
-1. Display summary showing groups committed, files organized, repos updated, and push status
-2. List all commit hashes and messages by repo for reference
-3. Provide guidance for handling any remaining changes (intentional skips, branch maintenance)
-4. Show quick re-run commands for future cleanup sessions
-5. Mark workflow as complete with confirmation message
-</instructions>
-
-<output>
-Final summary showing:
-- Groups committed count
-- Files organized count
-- Repos updated list
-- Push status (yes/no)
-- Complete list of commits by repo with hashes and messages
-- Post-cleanup task recommendations
-- Quick re-run instructions
-- Completion confirmation message
-</output>
-
-## Summary
-
-```
-## Git Cleanup Complete ✅
-
-### Session Summary
-- Groups committed: {n}
-- Files organized: {count}
-- Repos updated: {list}
-- Pushed to remote: {yes/no}
-
-### Commits
-{list of commit hashes and messages by repo}
-```
-
-## Post-Cleanup Tasks
-
-### If Changes Remain
-
-Intentionally skipped files can be:
-- Committed in next cleanup session
-- Added to .gitignore if generated
-- Discarded with `git -C {repo} checkout -- {file}`
-
-### Branch Maintenance
-
-Run periodically to clean up merged branches:
-
-```bash
-# For each repo
-git -C {repo_path} branch --merged develop | grep -v "develop\|main" | xargs -r git branch -d
-```
-
-## Quick Re-run
-
-To run git-cleanup again:
-
-```
-/git-cleanup
-```
-
-Or for a quick status check across all repos:
-
-```bash
-.pennyfarthing/scripts/git/git-status-all.sh
-```
-
----
-
-**Cleanup complete.** All repos are organized.
-
-<!-- CYCLIST:CONTINUE -->

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

@@ -1,59 +0,0 @@
-# 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]