@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/commands/git-cleanup.md

@@ -0,0 +1,340 @@
+---
+description: Clean up git repos by organizing changes into proper commits/branches by initiative
+---
+
+# Git Cleanup Command
+
+Analyze and organize uncommitted changes across all repos into proper commits and branches based on initiative/feature groupings.
+
+## Git Workflow Rules
+
+**CRITICAL: Never commit directly to develop. Branch protection hooks will reject direct commits.**
+
+All changes MUST follow this workflow:
+1. Create a branch from develop
+2. Commit changes to the branch
+3. Merge to develop locally
+4. Push develop (branches don't need to be pushed)
+
+## Analysis Phase
+
+### 1. Gather Current State and Check for Unpushed Commits
+
+```bash
+./scripts/run.sh git/git-status-all.sh
+```
+
+This shows branch, changes, and unpushed commits for all repos.
+
+### 2. Check Recent Commits for Patterns
+
+```bash
+echo "=== Recent Commit Patterns ==="
+git log --oneline -10 | head -10
+echo ""
+echo "=== Recent Branches ==="
+git branch --sort=-committerdate | head -10
+```
+
+### 3. Check Active Work Sessions
+
+```bash
+echo "=== Active Work ==="
+if [ -f ".session/{STORY_ID}-session.md" ]; then
+  head -30 .session/{STORY_ID}-session.md
+else
+  echo "No active work session"
+fi
+```
+
+### 4. Check Worktree Status
+
+```bash
+echo "=== Worktree Status ==="
+./scripts/run.sh git/worktree-manager.sh status
+```
+
+This shows all active worktrees with their branches and uncommitted changes.
+
+### 5. Check Epics for Story Context
+
+```bash
+echo "=== Active Epics ==="
+head -60 docs/epics.md
+```
+
+## Categorization Guidelines
+
+Group changes by these initiative types (based on conventional commits):
+
+| Prefix | Type | Branch Pattern | Example |
+|--------|------|----------------|---------|
+| `docs:` | Documentation | `docs/description` | docs/update-epics |
+| `chore:` | Maintenance | `chore/description` | chore/sprint-cleanup |
+| `chore(sprint):` | Sprint tracking | `chore/sprint-update` | - |
+| `chore(pennyfarthing):` | Pennyfarthing config | `chore/pennyfarthing-cleanup` | - |
+| `feat:` | New feature | `feat/story-id-desc` | feat/4-12-risk-scoring |
+| `fix:` | Bug fix | `fix/issue-desc` | fix/validation-error |
+| `refactor:` | Code improvement | `refactor/description` | refactor/seed-data |
+
+## Common Change Categories
+
+### Sprint/Docs Changes
+Files: `docs/*.md`, `sprint/*.yaml`, `sprint/*.md`
+- Branch: `chore/sprint-cleanup` or `docs/update-[topic]`
+- Commit: `chore(sprint): update sprint tracking` or `docs: update documentation`
+
+### Pennyfarthing Configuration
+Files: `.claude/**/*`
+- Branch: `chore/pennyfarthing-[description]`
+- Commit: `chore(pennyfarthing): description`
+
+### Feature Work
+Files: `internal/**`, `src/**`, `migrations/**`
+- Branch: `feat/[story-id]-description`
+- Commit: `feat: description`
+
+### Seed/Test Data
+Files: `internal/seed/**`, `cmd/seed/**`
+- Branch: `chore/seed-improvements` or part of feature branch
+- Commit: `chore(seed): description`
+
+### Bug Fixes
+Files: Various
+- Branch: `fix/[issue-description]`
+- Commit: `fix: description`
+
+## Execution Phase - Branch Workflow
+
+**For each group of changes, follow this exact workflow:**
+
+### Step 1: Stash All Changes First
+```bash
+# Stash everything to start clean
+git stash push -m "cleanup-wip"
+```
+
+### Step 2: Create Branch from Develop
+```bash
+# Ensure on develop and up to date
+git checkout develop
+git pull origin develop
+
+# Create feature branch
+git checkout -b type/description
+```
+
+### Step 3: Apply Relevant Changes
+```bash
+# Pop stash
+git stash pop
+
+# Stage only files for this group
+git add <specific-files>
+
+# Stash remaining changes for next group
+git stash push -m "remaining-cleanup"
+```
+
+### Step 4: Commit
+```bash
+# Commit with proper message
+git commit -m "$(cat <<'EOF'
+type(scope): description
+
+Details if needed.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Step 5: Merge to Develop
+```bash
+# Switch to develop
+git checkout develop
+
+# Merge the branch
+git merge type/description
+
+# Delete local branch
+git branch -d type/description
+```
+
+### Step 6: Repeat for Next Group
+```bash
+# Pop remaining stash and repeat from Step 2
+git stash pop
+```
+
+## Multi-Repo Cleanup Pattern
+
+When cleaning up changes across multiple repos (configured in `.claude/project/repos.yaml`):
+
+```bash
+# Source repo utilities
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+
+# For each configured repo, run the same workflow
+for_each_repo '
+  # ... branch workflow ...
+  git status --short
+'
+```
+
+Or manually iterate:
+
+```bash
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+for repo in $(get_repos); do
+  repo_path=$(get_repo_full_path "$repo")
+  echo "=== Processing $repo ==="
+  cd "$repo_path"
+  # ... branch workflow ...
+  cd -
+done
+```
+
+## Interactive Cleanup Process
+
+When running this command, Claude should:
+
+1. **Show current state** - Display all uncommitted changes grouped by repo
+2. **Check for unpushed commits** - Identify any commits on develop not yet pushed
+3. **Analyze changes** - Look for patterns in file paths, recent commits, and epics
+4. **Propose groupings** - Suggest how to organize changes:
+   ```
+   Group 1: Sprint Updates
+   - docs/epics.md
+   - sprint/current-sprint.yaml
+   → Branch: chore/sprint-cleanup
+   → Commit: "chore(sprint): clean up sprint tracking files"
+
+   Group 2: Migration Fix
+   - migrations/056_*.sql
+   → Branch: fix/risk-scoring-migration
+   → Commit: "fix(db): add missing risk scoring migration"
+
+   Group 3: Seed Improvements
+   - internal/seed/*.go
+   → Branch: chore/seed-improvements
+   → Commit: "chore(seed): improve demo data generation"
+   ```
+4. **Ask for confirmation** - Let user approve or modify groupings
+5. **Execute** - Create branches, commit, merge to develop for each group
+6. **Push develop** - Push all merged changes at the end
+7. **Verify** - Show clean git status at the end
+
+## Safety Rules
+
+- **NEVER commit directly to develop** - hooks will reject it
+- **Never force push**
+- **Never commit secrets** (.env, credentials, etc.)
+- **Show diff before committing**
+- **Respect .gitignore**
+- **Handle unpushed commits on develop before starting cleanup**
+
+## Quick Reference
+
+```bash
+# View what needs cleanup (all repos)
+./scripts/run.sh git/git-status-all.sh
+
+# Create cleanup branch
+git checkout develop && git pull
+git checkout -b chore/cleanup-$(date +%Y%m%d)
+
+# Stage specific files
+git add "docs/*.md"
+git add "sprint/*.yaml"
+
+# Commit with proper message (use heredoc for multiline)
+git commit -m "$(cat <<'EOF'
+chore(sprint): update sprint status
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+
+# Merge to develop (local)
+git checkout develop
+git merge chore/cleanup-$(date +%Y%m%d)
+git branch -d chore/cleanup-$(date +%Y%m%d)
+
+# Push develop after all merges complete
+git push origin develop
+```
+
+## Branch Cleanup
+
+Stale feature branches can accumulate over time. Include branch cleanup as part of git hygiene.
+
+### Check for Stale Branches
+
+```bash
+echo "=== Branch Status ==="
+
+./scripts/run.sh misc/check-status.sh
+```
+
+### Remove Merged Branches
+
+**Only remove branches that are fully merged:**
+
+```bash
+# Source repo utilities
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+
+# For each configured repo
+for repo in $(get_repos); do
+  repo_path=$(get_repo_full_path "$repo")
+  echo "=== $repo ==="
+  cd "$repo_path"
+
+  git checkout develop
+  git pull origin develop
+
+  # List branches merged into develop
+  git branch --merged develop | grep -v "develop\|main"
+
+  # Delete merged branches
+  git branch --merged develop | grep -v "develop\|main" | xargs -r git branch -d
+
+  cd -
+done
+```
+
+### Branch Cleanup Criteria
+
+| Branch Type | When to Remove |
+|-------------|----------------|
+| `feat/*` | After PR merged to develop |
+| `fix/*` | After PR merged to develop |
+| `chore/*` | After PR merged to develop |
+
+**Note:** Never delete `main` or `develop` branches.
+
+## Post-Cleanup Verification
+
+```bash
+echo "=== Final State ==="
+./scripts/run.sh git/git-status-all.sh
+echo ""
+echo "=== Branches ==="
+
+# Source repo utilities
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+
+for repo in $(get_repos); do
+  repo_path=$(get_repo_full_path "$repo")
+  echo "$repo:" && git -C "$repo_path" branch
+done
+```
+
+---
+
+**Start by analyzing, then propose groupings, then execute with user approval. Always use branches!**

package/pennyfarthing-dist/commands/health-check.md

@@ -0,0 +1,141 @@
+---
+description: Check Pennyfarthing installation health and apply updates
+---
+
+```bash
+./scripts/run.sh core/agent-session.sh start "devops"
+```
+
+<agent-activation>
+1. Load DevOps agent for infrastructure work
+2. Run health check via CLI
+</agent-activation>
+
+<purpose>
+Examine current Pennyfarthing installation, detect drift from expected state, and guide user through fixes/updates.
+</purpose>
+
+<when-to-use>
+- After updating Pennyfarthing (`pennyfarthing update`)
+- When something seems broken
+- Periodic health verification
+- Before starting new sprint
+</when-to-use>
+
+<health-checks>
+
+## Health Check
+
+Use the pennyfarthing CLI:
+
+```bash
+# Full health check
+pennyfarthing doctor
+
+# Or via npx
+npx pennyfarthing doctor
+
+# Auto-fix issues
+pennyfarthing doctor --fix
+```
+
+The CLI checks:
+- manifest.json exists and is valid
+- All managed files present in .claude/pennyfarthing/
+- Symlinks point to correct targets
+- User directories exist (.claude/project/)
+- Settings paths are correct
+- Hook scripts are executable
+
+## Check for Updates
+
+```bash
+# Check if update available
+pennyfarthing update --check
+
+# Apply update
+pennyfarthing update
+```
+
+</health-checks>
+
+<output-format>
+
+```markdown
+# Pennyfarthing Health Check
+
+## Installation: npm v2.2.x
+## Status: [HEALTHY | NEEDS_UPDATE | NEEDS_FIX]
+
+### Checks
+| Check | Status | Detail |
+|-------|--------|--------|
+| Installation | OK | npm v2.2.0 |
+| Core Files | OK | All present |
+| Symlinks | OK | All valid |
+| User Files | OK | 10 sidecars |
+| Directories | OK | sprint/, .session/ |
+| Hooks | WARN | Not executable |
+
+### Recommended Actions
+1. [Action with command to run]
+2. [Action with command to run]
+```
+
+</output-format>
+
+<auto-fixes>
+
+```bash
+pennyfarthing doctor --fix
+```
+
+The CLI can auto-fix:
+- Broken symlinks
+- Missing directories
+- Outdated settings format
+- Non-executable hooks
+
+**Always ask before applying fixes.**
+
+</auto-fixes>
+
+<drift-detection>
+
+## Agent Behavior Drift Detection
+
+Check if agents are following expected behavioral patterns:
+
+```bash
+# Run drift detection
+.pennyfarthing/scripts/core/run.sh health/drift-detection.sh
+
+# Verbose mode (see individual files)
+.pennyfarthing/scripts/core/run.sh health/drift-detection.sh --verbose
+```
+
+The script analyzes archived session files for:
+
+| Agent | Checks For |
+|-------|------------|
+| **Reviewer** | Substantive comments (not just approvals) |
+| **Dev** | Test evidence when declaring GREEN |
+| **SM** | Structured handoff sections with target agent |
+| **TEA** | Test file references before Dev handoff |
+
+**Healthy rates:** Under 10% drift is considered normal.
+
+**When drift is high:**
+- Review agent behavior files for clarity
+- Add explicit gates/checklists
+- Consider making critical behaviors automatic via scripts
+
+</drift-detection>
+
+<reference>
+- **CLI:** `pennyfarthing doctor`, `pennyfarthing update`
+- **Manifest:** `.claude/manifest.json` (tracks version and file hashes)
+- **Source:** `.claude/pennyfarthing/` (managed files)
+- **Symlinks:** `.pennyfarthing/agents/`, `.claude/commands/`, etc.
+- **Drift Detection:** `.pennyfarthing/scripts/health/drift-detection.sh`
+</reference>