@pennyfarthing/core 7.9.0 → 7.9.2

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

@@ -1,101 +0,0 @@
-# Step 1: Analyze Current State
-
-Gather the current git state across all configured repositories.
-
-## Objective
-
-Build a complete picture of:
-- Uncommitted changes in each repo
-- Unpushed commits on develop
-- Active worktrees and their state
-- Active work sessions that might explain changes
-
-## Execution
-
-### 1.0 Check Stash (CRITICAL - DO THIS FIRST)
-
-```bash
-echo "=== Stash Status (CRITICAL) ==="
-git stash list
-```
-
-**If stash has ANY entries:**
-1. Show the stash contents to user
-2. Ask: "Stash contains saved work. Clear it completely before proceeding?"
-3. If user agrees: `git stash clear`
-4. If user declines: **STOP** - do not proceed with cleanup
-
-**This prevents:**
-- Losing work that was stashed from a previous interrupted cleanup
-- Confusion about what changes belong to what
-- Accidentally clearing someone else's stashed work
-
-### 1.1 Gather Git Status (All Repos)
-
-```bash
-./scripts/run.sh git/git-status-all.sh
-```
-
-This shows branch, staged/unstaged changes, and unpushed commits for all repos.
-
-### 1.2 Check Recent Commit Patterns
-
-```bash
-echo "=== Recent Commits (for message style) ==="
-git log --oneline -10
-echo ""
-echo "=== Recent Branches ==="
-git branch --sort=-committerdate | head -10
-```
-
-### 1.3 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.
-
-### 1.4 Check Worktree Status
-
-```bash
-echo "=== Worktree Status ==="
-./scripts/run.sh git/worktree-manager.sh status 2>/dev/null || echo "No worktrees"
-```
-
-### 1.5 Pre-flight Checks
-
-**Before proceeding, verify:**
-
-| Check | Status | Action if Failed |
-|-------|--------|------------------|
-| No merge conflicts | ☐ | Resolve conflicts first |
-| develop is up to date | ☐ | `git pull origin develop` |
-| No uncommitted secrets | ☐ | Add to .gitignore |
-
-## Output Format
-
-Present findings in this structure:
-
-```
-## Analysis Results
-
-### Repo: {repo_name}
-Branch: {current_branch}
-Unpushed: {count} commits
-
-**Uncommitted Changes:**
-- {file_path} ({status: M/A/D/??})
-- ...
-
-### 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,116 +0,0 @@
-# Step 2: Categorize Changes
-
-Group uncommitted changes by initiative type using conventional commit categories.
-
-## Objective
-
-Organize scattered changes into logical groups that can be committed separately with proper branch names and commit messages.
-
-## 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 Directory** - Files in same directory often belong together
-3. **By File Type** - Docs together, configs together, source together
-4. **By Semantic Coupling** - Migration + model + handler for same feature
-
-## Execution
-
-### 2.1 Analyze Change Patterns
-
-For each changed file, determine:
-- Which initiative type it belongs to
-- If it relates to an active story
-- If it should group with other files
-
-### 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}`
-
-Files:
-- `{file_path}` ({status})
-- `{file_path}` ({status})
-
-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 |
-
-### Promoting to Tracked Story
-
-If a group deserves Jira tracking (retroactive story):
-
-1. Mark group with **[T]** Track in Jira
-2. Provide: title, description, points (default: 2)
-3. Workflow will: create Jira → branch → commit → PR → merge
-
-This is the `/standalone` pattern integrated into cleanup.
-
-## Approval Gate
-
-**This step requires user approval before execution.**
-
-Present summary:
-
-```
-## Summary
-
-Total groups: {n}
-- Quick commits: {count}
-- Tracked stories: {count}
-- Skipped: {count}
-
-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,224 +0,0 @@
-# Step 3: Execute Commits
-
-Create branches, commit changes, and merge to develop for each approved group.
-
-## Objective
-
-Execute the approved change groupings following the branch workflow:
-1. Stash all changes
-2. For each group: branch → stage → commit → merge (or PR for tracked)
-3. Track progress and handle failures gracefully
-
-## Two Execution Paths
-
-| Type | Flow | Merge Method |
-|------|------|--------------|
-| **Quick** | branch → commit → local merge | Fast-forward |
-| **Tracked** | Jira → branch → commit → push → PR → squash merge | PR squash |
-
-## 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
-
-### 3.1 Stash All Changes
-
-```bash
-# Stash everything to start clean - MARK CLEARLY
-git stash push -m "CLEANUP-WIP: git-cleanup-$(date +%Y%m%d-%H%M%S)"
-```
-
-**Verify stash worked:**
-```bash
-git stash list  # Should show your CLEANUP-WIP entry
-```
-
-### 3.2 For Each Group
-
-Execute this sequence for each approved group:
-
-#### Create Branch
-
-```bash
-# Ensure on develop and up to date
-git checkout develop
-git pull origin develop
-
-# Create feature branch
-git checkout -b {branch_name}
-```
-
-#### Apply and Stage Changes
-
-```bash
-# Pop stash
-git stash pop
-
-# Stage only files for this group
-git add {file1} {file2} ...
-
-# Re-stash remaining changes - MARK CLEARLY
-git stash push -m "CLEANUP-WIP: remaining changes"
-```
-
-#### Show Diff for Verification
-
-```bash
-# Show what will be committed
-git diff --cached --stat
-```
-
-#### Commit
-
-```bash
-git commit -m "$(cat <<'EOF'
-{type}({scope}): {description}
-
-{body if needed}
-EOF
-)"
-```
-
-#### Merge to Develop (Quick Path)
-
-```bash
-# Switch to develop
-git checkout develop
-
-# Merge the branch (creates merge commit)
-git merge {branch_name} --no-ff -m "Merge {branch_name}"
-
-# Or fast-forward merge for clean history
-git merge {branch_name}
-
-# Delete local branch
-git branch -d {branch_name}
-```
-
-### 3.3 For Tracked Groups (Standalone Path)
-
-Groups marked for Jira tracking follow the full PR workflow:
-
-#### Create Jira Story
-
-```bash
-# Create story in Jira
-JIRA_KEY=$(jira issue create \
-  --project MSSCI \
-  --type Story \
-  --summary "{title}" \
-  --body "{description}" \
-  --label pennyfarthing \
-  --custom story-points="{points}" \
-  --no-input 2>&1 | grep -oE 'MSSCI-[0-9]+' | head -1)
-
-echo "Created: $JIRA_KEY"
-
-# Add to current sprint and mark done
-jira sprint add {sprint_id} "$JIRA_KEY"
-jira issue move "$JIRA_KEY" "Done"
-```
-
-#### Create Branch with Jira Key
-
-```bash
-SLUG=$(echo "{title}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-30)
-BRANCH="feat/${JIRA_KEY}-${SLUG}"
-git checkout -b "$BRANCH"
-```
-
-#### Commit with Jira Reference
-
-```bash
-git commit -m "$(cat <<'EOF'
-feat: {title} ({JIRA_KEY})
-
-{description}
-EOF
-)"
-```
-
-#### Push and Create PR
-
-```bash
-git push -u origin "$BRANCH"
-
-gh pr create \
-  --title "feat: {title} (${JIRA_KEY})" \
-  --body "## Summary
-{description}
-
-## Jira
-[${JIRA_KEY}](https://1898andco.atlassian.net/browse/${JIRA_KEY})
-
-## Test plan
-- [x] Changes verified locally
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)"
-```
-
-#### Merge PR and Cleanup
-
-```bash
-gh pr merge --squash --delete-branch
-git checkout develop
-git pull origin develop
-```
-
-### 3.4 Progress Tracking
-
-Report progress after each group:
-
-```
-## Execution Progress
-
-| Group | Type | Status | Branch | Jira |
-|-------|------|--------|--------|------|
-| Sprint cleanup | Quick | ✅ Done | chore/sprint-update | - |
-| Docs update | Quick | ✅ Done | docs/update-readme | - |
-| Prime module | Tracked | ✅ Done | feat/MSSCI-12500-prime | MSSCI-12500 |
-| Config changes | Quick | ⏳ Pending | - | - |
-```
-
-### 3.5 Error Handling
-
-If a commit fails:
-1. **Hook rejection**: Check commit message format, try again
-2. **Merge conflict**: Report to user, offer to abort or resolve
-3. **Test failure**: Report which tests failed, offer to proceed or abort
-
-**CRITICAL: Before panicking about lost work, CHECK STASH:**
-```bash
-git stash list              # Work is probably here!
-git stash show -p stash@{0} # See what's in it
-git stash pop               # Restore it
-```
-
-When a pre-commit hook blocks a commit, staged changes may be auto-stashed. Always check.
-
-## Output
-
-After all groups processed:
-
-```
-## Execution Complete
-
-Commits created: {n}
-Branches merged: {n}
-Remaining stashed: {yes/no}
-
-Ready to verify and push?
-```
-
----
-
-**[A]** Abort (revert all changes, restore stash)
-**[C]** Continue to verification
-
-<!-- GATE -->
-<!-- CYCLIST:CHOICES:A,C -->

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

@@ -1,88 +0,0 @@
-# Step 4: Verify and Push
-
-Verify the cleanup was successful and optionally push to remote.
-
-## Objective
-
-1. Confirm all changes are properly committed
-2. Verify no uncommitted changes remain (or only intentionally skipped)
-3. Show commit history for review
-4. Push to remote if requested
-
-## Verification
-
-### 4.1 Final Git Status
-
-```bash
-echo "=== Final State ==="
-./scripts/run.sh git/git-status-all.sh
-```
-
-Expected: Clean working directory or only intentionally skipped files.
-
-### 4.2 Review Commits
-
-```bash
-echo "=== New Commits ==="
-git log --oneline develop@{1}..develop 2>/dev/null || git log --oneline -5
-```
-
-### 4.3 Branch Cleanup Check
-
-```bash
-echo "=== Remaining Branches ==="
-git branch | grep -v "develop\|main"
-```
-
-All cleanup branches should be deleted after merge.
-
-### 4.4 Stash Status
-
-```bash
-echo "=== Stash Status ==="
-git stash list | head -5
-```
-
-If stash entries remain from cleanup, either:
-- Pop and commit (if intentional skip)
-- Drop (if no longer needed)
-
-## Summary Report
-
-```
-## Git Cleanup Summary
-
-### Commits Created
-| Commit | Type | Message |
-|--------|------|---------|
-| abc1234 | chore | chore(sprint): update tracking |
-| def5678 | docs | docs: update README |
-
-### Final State
-- Working directory: {clean / X files remaining}
-- Unpushed commits: {n}
-- Stash entries: {n}
-
-### Remaining Work
-{list any skipped files or deferred changes}
-```
-
-## Push Decision
-
-**Push to remote?**
-
-- **Yes**: Push develop to origin
-- **No**: Keep commits local for now
-
-```bash
-# If pushing
-git push origin develop
-```
-
----
-
-**[P]** Push to remote now
-**[L]** Keep local (don't push)
-**[R]** Review commits again before deciding
-
-<!-- CYCLIST:CHOICES:P,L,R -->

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

@@ -1,79 +0,0 @@
-# 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 Verification (MANDATORY)
-
-**Before completing, verify stash is empty:**
-
-```bash
-git stash list
-```
-
-**If stash has entries:**
-- If CLEANUP-WIP entries: These are leftover from this session - pop or clear them
-- If other entries: Ask user before clearing
-
-**Clear stash completely when done:**
-```bash
-# After confirming with user
-git stash clear
-```
-
-**Why this matters:** Leftover stash entries cause confusion in future cleanups and can lead to lost work if forgotten.
-
-## 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

@@ -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]