code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/review.md

@@ -0,0 +1,304 @@
+---
+name: review
+argument-hint: pr_number(optional) | additional_instructions
+description: Code review with smart parent branch detection and optional PR posting
+---
+
+# CODE REVIEW WORKFLOW
+
+**Argument:** `$ARGUMENTS` (optional PR number)
+
+## STEP 1: Branch setup
+
+### 1a. If PR number provided:
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+PR_NUMBER="${ARGUMENTS}"
+PR_BRANCH=$(gh pr view $PR_NUMBER --json headRefName -q '.headRefName')
+PARENT_BRANCH=$(gh pr view $PR_NUMBER --json baseRefName -q '.baseRefName')
+if [ "$PR_BRANCH" != "$CURRENT_BRANCH" ]; then
+  git fetch origin "$PR_BRANCH" && git checkout "$PR_BRANCH"
+fi
+git fetch origin "$PARENT_BRANCH"
+echo "PARENT_BRANCH: $PARENT_BRANCH"
+```
+
+### 1b. If no PR number:
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+PARENT_BRANCH=""
+for branch in main master develop; do
+  if git rev-parse --verify "origin/$branch" >/dev/null 2>&1; then
+    MERGE_BASE=$(git merge-base HEAD "origin/$branch" 2>/dev/null)
+    if [ -n "$MERGE_BASE" ] && [ "$branch" != "$CURRENT_BRANCH" ]; then
+      PARENT_BRANCH="$branch"; break
+    fi
+  fi
+done
+PARENT_BRANCH="${PARENT_BRANCH:-main}"
+echo "PARENT_BRANCH: $PARENT_BRANCH"
+```
+
+## STEP 2: Detect stack
+
+```bash
+FLUX_ROOT="${FLUX_ROOT:-$HOME/.flux}"
+FLUX_DIR=$(printf '%s' "$(pwd -P)" | tr -cs 'a-zA-Z0-9' '-')
+FLUX_BASE="$FLUX_ROOT/$FLUX_DIR"
+echo "FLUX_BASE=$FLUX_BASE"
+```
+
+If a file called `stack.env` exists at `$FLUX_BASE/stack.env`, read it and set `$STACK` from its contents. Otherwise, run the following detection script to determine `$STACK` and save it (this only ever runs the first time for this directory):
+
+```bash
+STACK="software"
+if [ -f "package.json" ]; then
+  STACK=$(bun -e "
+    const d=JSON.parse(require('fs').readFileSync('./package.json','utf8'));
+    const deps=Object.assign({}, d.dependencies, d.devDependencies, d.peerDependencies);
+    const frameworks=['ink','react','vue','angular','next','express'];
+    const fw=frameworks.find(f=>deps[f]);
+    const ts=deps['typescript']?'TypeScript':'JavaScript';
+    console.log(fw?fw+' + '+ts:ts);
+  " 2>/dev/null || echo "JavaScript/TypeScript")
+elif [ -f "Cargo.toml" ]; then STACK="Rust"
+elif [ -f "go.mod" ]; then STACK="Go"
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then STACK="Python"
+elif [ -f "pom.xml" ] || [ -f "build.gradle" ]; then STACK="Java/Kotlin"
+fi
+mkdir -p "$FLUX_BASE"
+echo "$STACK" > "$FLUX_BASE/stack.env"
+echo "Detected stack: $STACK (saved)"
+```
+
+## STEP 3: Branch ownership & merge base
+
+```bash
+MERGE_BASE=$(git merge-base HEAD "origin/$PARENT_BRANCH")
+BRANCH_AUTHOR=$(git log --format='%an' --reverse "$MERGE_BASE..HEAD" 2>/dev/null | head -1)
+CURRENT_USER=$(git config user.name)
+[ "$BRANCH_AUTHOR" = "$CURRENT_USER" ] && IS_MY_BRANCH="true" || IS_MY_BRANCH="false"
+echo "MERGE_BASE: $MERGE_BASE  IS_MY_BRANCH: $IS_MY_BRANCH"
+```
+
+## SCOPE CONSTRAINTS (CRITICAL)
+
+**ONLY** flag issues **newly introduced** by changes vs `$MERGE_BASE` in files **directly modified**.
+
+**DO NOT** flag: pre-existing issues in unchanged code, files/lines not touched, missing tests/benchmarks, style preferences.
+
+> Why `$MERGE_BASE` not `origin/$PARENT_BRANCH`: upstream commits that landed after this branch was created would pollute the diff. Merge-base is the exact divergence point.
+
+## STEP 4: Identify changed files
+
+```bash
+git diff --name-only "$MERGE_BASE"
+```
+
+## STEP 5: Analyze diffs
+
+```bash
+git diff "$MERGE_BASE"
+```
+
+Group files by: key modules, logical areas, high-risk changes (security, performance, data handling).
+
+## STEP 6: Spawn code review sub-agents
+
+Launch with `invoke_agent` tool, `run_in_background: false`.
+
+**Agent count:**
+| Changed Files | Agents | Strategy |
+|---|---|---|
+| 1-5 | 1-3 | Group related files |
+| 6-15 | 4-8 | One per module/feature area |
+| 16-50 | 8-12 | Group by directory |
+| 50+ | 12-15 max | By directory, prioritize high-risk |
+
+Per agent, provide: file paths + line ranges, relevant diff snippets, module/area name, PR context.
+
+### Sub-agent prompt template
+
+````
+# CODE REVIEW: {{MODULE_NAME}}
+
+## Files: {{FILE_LIST_WITH_LINE_RANGES}}
+
+## Diffs
+```diff
+{{RELEVANT_DIFF_SNIPPETS}}
+```
+
+## Checklist — flag only issues in code CHANGED by this PR vs `$MERGE_BASE`:
+- [ ] Stubs/Placeholders: non-functional required code (TODOs, NotImplemented)
+- [ ] Race Conditions: concurrency, async/await problems
+- [ ] Performance: O(n²) loops, memory leaks, excessive allocations, blocking calls
+- [ ] Logic Errors: off-by-one, null checks, edge cases, wrong conditionals
+- [ ] Dead Code: unwired code, unreachable paths
+- [ ] Security: input validation, injection risks, exposed secrets
+- [ ] Requirements Mismatch: code doesn't fulfill intended purpose
+- [ ] Complexity: functions >50 lines, cyclomatic complexity >10 branches, nesting >4 levels
+- [ ] Duplication: repeated code blocks >5 lines, duplicate constants/magic strings used 3+ times
+- [ ] Maintainability: unused variables/imports, dead code paths, hardcoded magic numbers
+- [ ] Design: commented-out code blocks >3 lines, inconsistent naming, TODO/FIXME in changed code
+- [ ] Language-specific (TypeScript): missing async/await handling, unhandled promise rejections, `var` usage, `==` vs `===` in changed lines
+
+DO NOT create tasks for: missing tests, benchmarks, style preferences, pre-existing issues.
+
+## Task File Creation
+
+For each issue, create `$FLUX_BASE/review/<issue-slug>.md`:
+
+```markdown
+---
+severity: critical|high|medium|low
+file: <filepath>
+lines: <start>-<end>
+introduced: true
+---
+
+# <Issue Title>
+
+## Problem
+<description>
+
+## Evidence
+<code snippet or diff>
+
+## Impact
+<what could go wrong>
+
+## Suggested Fix
+<recommended approach>
+```
+
+Before creating any task, verify: issue is in CHANGED code, did NOT exist before these changes, is genuinely problematic.
+````
+
+## STEP 7: Categorize by severity
+
+```bash
+FLUX_ROOT="${FLUX_ROOT:-$HOME/.flux}"
+FLUX_DIR=$(printf '%s' "$(pwd -P)" | tr -cs 'a-zA-Z0-9' '-')
+FLUX_BASE="$FLUX_ROOT/$FLUX_DIR"
+mkdir -p "$FLUX_BASE/todo" "$FLUX_BASE/done" "$FLUX_BASE/review" "$FLUX_BASE/research"
+mkdir -p "$FLUX_BASE/review/critical" "$FLUX_BASE/review/high" "$FLUX_BASE/review/medium" "$FLUX_BASE/review/low"
+echo "FLUX_BASE=$FLUX_BASE"
+```
+
+Launch sub-agents (groups of 10) to move `$FLUX_BASE/review/*.md` to the appropriate severity subdirectory.
+
+| Severity | Criteria                                                            |
+| -------- | ------------------------------------------------------------------- |
+| Critical | Security vulns, data loss, crashes, blocking bugs                   |
+| High     | Significant logic errors, perf issues affecting UX, race conditions |
+| Medium   | Minor logic issues, clarity problems, non-blocking bugs             |
+| Low      | Minor improvements, low-probability edge cases                      |
+
+## PATH REFRESH (after STEP 7)
+
+Flat paths `$FLUX_BASE/review/*.md` no longer exist after categorization. All subsequent steps must locate files via:
+
+```bash
+find "$FLUX_BASE/review/" -name "*.md" -type f | sort
+```
+
+Steps 8, 10, and 11 sub-agents must use `find` or explicit subdirectory paths — never assume flat paths still exist.
+
+## STEP 8: Verify newly introduced issues
+
+Enumerate all task files with `find "$FLUX_BASE/review/" -name "*.md" -type f | sort`, then launch sub-agents. Each agent diffs the flagged file:
+
+```bash
+git diff "$MERGE_BASE" -- <filepath>
+```
+
+Classify each issue:
+| Classification | Definition |
+|---|---|
+| Introduced | Exists only in new changes; parent branch is clean |
+| Pre-existing | Exists in parent branch; these changes didn't create it |
+| Aggravated | Pre-existing but made worse by these changes |
+
+## STEP 9: Summarize findings
+
+Enumerate with `find "$FLUX_BASE/review/" -name "*.md" -type f | sort`. Report: introduced issues requiring attention, aggravated issues to consider, pre-existing issues flagged for removal.
+
+## STEP 10: User checkpoint
+
+```bash
+find "$FLUX_BASE/review/" -name "*.md" -type f | sort
+```
+
+Use `ask_user_question`: present pre-existing issues (full paths), ask which to keep. Default if no response: DELETE pre-existing issue tasks.
+
+## STEP 11: Consolidation & deduplication
+
+```bash
+find "$FLUX_BASE/review/" -name "*.md" -type f | sort
+```
+
+Divide into groups, assign to sub-agents. Sub-agents use full paths from `find` (e.g. `$FLUX_BASE/review/high/auth-race-condition.md`).
+
+| Classification          | Action                   |
+| ----------------------- | ------------------------ |
+| Exact Duplicate         | Remove one               |
+| Semantic Duplicate      | Merge into one           |
+| Consolidation Candidate | Combine into single task |
+| Unique                  | Keep as-is               |
+
+## STEP 12: Final summary & post-review actions
+
+```
+Total Issues Found: X
++-- Critical: A  +-- High: B  +-- Medium: C  +-- Low: D
+
+Duplicates Removed: Y  Tasks Consolidated: Z -> W  Final Task Count: N
+```
+
+**Recommendation:** `APPROVE` / `REQUEST CHANGES` / `NEEDS DISCUSSION`
+
+**If PR provided OR reviewing someone else's branch (`IS_MY_BRANCH=false`):**
+
+```bash
+REVIEW_COUNT=$(find "$FLUX_BASE/review/" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+if [ "$REVIEW_COUNT" -eq 0 ]; then
+  echo "No issues found — no zip created."
+else
+  FLAT_BRANCH=$(echo "$(git branch --show-current)" | tr '/' '-')
+  ZIP_NAME="${FLAT_BRANCH}-review.zip"
+  cd "$FLUX_BASE" && zip -r "$ZIP_NAME" review/
+  echo "Review package: $FLUX_BASE/$ZIP_NAME"
+fi
+```
+
+Report zip location. If PR provided: "share with PR author or attach manually." If no PR, someone else's branch: "share with the branch author."
+
+**If `IS_MY_BRANCH=true`:** Leave files in `$FLUX_BASE/review/`. Report: "Issues saved to `$FLUX_BASE/review/` organized by severity."
+
+## ERROR HANDLING
+
+- Git command fails → report and stop
+- Sub-agent fails → log, continue with remaining agents
+- No changes found → report "No files changed vs parent branch" and exit
+- 100+ issues found → pause and ask user how to proceed before categorization
+- gh CLI fails → report but continue with local review
+
+## HARD CONSTRAINTS
+
+- **Path**: All `create_file`/`replace_in_file`/`mv`/`cp` file paths MUST use the exact `FLUX_BASE` value printed by STEP 2 or STEP 7 bash output (e.g. `FLUX_BASE=/Users/...`). Copy it character-for-character — never reconstruct it from `cwd` or memory.
+- `/flux/review` MUST NOT modify any source files. The only permitted file operations are: creating issue task files in `$FLUX_BASE/review/`, moving/deleting those files during deduplication, and creating the zip archive. No changes to `./src/`, no git commits, no pushes.
+
+## NEXT STEP
+
+Then propose the next step:
+
+- if user is reviewing their own branch: `/flux/address-feedback`
+- if user is reviewing someone else's PR: `share the zip with the author`
+
+Valid `//flux` commands: `/flux/config`, `/flux/new`, `/flux/ask`, `/flux/split`, `/flux/aug`, `/flux/exec`, `/flux/qa`, `/flux/tests`, `/flux/commit`, `/flux/create-pr`, `/flux/review`, `/flux/address-feedback`, `/flux/status`, `/flux/auto-pilot`, `/flux/rebase`. Do NOT suggest any command not on this list.
+
+=================
+$ARGUMENTS

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/split.md

@@ -0,0 +1,120 @@
+---
+name: split
+argument-hint: task_file | additional_instructions
+description: Decompose a large task into smaller, single-session tasks.
+---
+
+# DECOMPOSE A LARGE TASK
+
+**Argument:** `$ARGUMENTS`
+
+## STEP 1: Mark as in-progress
+
+Before anything else, update the input task file's frontmatter (replace existing values, or prepend if no frontmatter exists):
+
+```yaml
+---
+stage: split
+status: in-progress
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+## STEP 2: Resolve path & setup
+
+If `$ARGUMENTS` has no `/`, prepend `$FLUX_BASE/todo/`. If no `.md`, append `.md`. (e.g. `NOTIFS` → `$FLUX_BASE/todo/NOTIFS.md`)
+
+```bash
+FLUX_ROOT="${FLUX_ROOT:-$HOME/.flux}"
+FLUX_DIR=$(printf '%s' "$(pwd -P)" | tr -cs 'a-zA-Z0-9' '-')
+FLUX_BASE="$FLUX_ROOT/$FLUX_DIR"
+mkdir -p "$FLUX_BASE/todo" "$FLUX_BASE/done" "$FLUX_BASE/review" "$FLUX_BASE/research"
+echo "FLUX_BASE=$FLUX_BASE"
+```
+
+## STEP 3: Decompose into subtask files
+
+### 3.1 Choose a prefix
+
+Short, uppercase, human-meaningful, fewer than 8 characters. Example: tasks about "in production" stubs → `IN_PROD_1.md`, `IN_PROD_2.md`, etc.
+
+### 3.2 Write subtask files
+
+Output files:
+
+- `$FLUX_BASE/todo/PREFIX_1.md`
+- `$FLUX_BASE/todo/PREFIX_2.md`
+- `$FLUX_BASE/todo/PREFIX_3.md`
+- ... etc.
+
+Each task must be:
+
+- Focused on a single area of concern
+- Achievable in **one Claude session** — after writing, ask yourself "is this really doable in one session?" If no, split into A/B/C variants
+- Free of research tasks (all research is done prior to execution)
+- Free of tests and benchmarks (see 3.3 and 3.4)
+
+**Frontmatter (required at top of every subtask file):**
+
+```yaml
+---
+stage: new
+status: done
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+**Body must include:**
+
+- `OBJECTIVE:` — what this task accomplishes
+- Numbered subtasks: SUBTASK1, SUBTASK2, SUBTASK3...
+- For each: what changes, where it changes, why it changes
+- Clear definition of done
+- Research notes and locations of relevant docs/source code
+
+### 3.3 No tests
+
+Another team owns tests. Writing any test code makes their work harder. Each task file must explicitly state: no tests to be written.
+
+### 3.4 No benchmarks
+
+Another team owns benchmarks. Writing any benchmark code makes their work harder. Each task file must explicitly state: no benchmarks to be written.
+
+## STEP 4: Preserve the original task file
+
+Update the original task file's frontmatter to mark it as split, then move it to the session done directory.
+
+1. Update the original file's frontmatter (replace `stage`, `status`, `updated` — keep body unchanged):
+
+```yaml
+---
+stage: split
+status: complete
+updated: <YYYY-MM-DD HH:MM>
+---
+```
+
+2. Read the session timestamp and move to the session done subdirectory:
+
+```bash
+SESSION_TS=$(grep '^SESSION_TS=' "$FLUX_BASE/session.env" 2>/dev/null | cut -d= -f2)
+SESSION_TS="${SESSION_TS:-$(date +%Y-%m-%d-%H-%M)}"
+mkdir -p "$FLUX_BASE/done/$SESSION_TS"
+mv "<original_task_file_path>" "$FLUX_BASE/done/$SESSION_TS/"
+```
+
+The original file is preserved in `done/$SESSION_TS/` as an audit trail of the pre-split specification.
+
+## HARD CONSTRAINTS
+
+- **Path**: All `create_file` file paths MUST use the exact `FLUX_BASE` value printed by the STEP 2 bash output (e.g. `FLUX_BASE=/Users/...`). Copy it character-for-character — never reconstruct it from `cwd` or memory.
+- `/flux/split` is a **decompose-only** command. You MUST NOT modify any source files, run any tests, or touch any file outside of `$FLUX_BASE/todo/`. The only file operations allowed are: writing the new subtask files and deleting the original task file. If you find yourself about to do anything else, stop immediately.
+
+## PROPOSE NEXT STEP
+
+Then propose the next step: `/flux/aug` (include arguments if needed).
+
+Valid `//flux` commands: `/flux/config`, `/flux/new`, `/flux/ask`, `/flux/split`, `/flux/aug`, `/flux/exec`, `/flux/qa`, `/flux/tests`, `/flux/commit`, `/flux/create-pr`, `/flux/review`, `/flux/address-feedback`, `/flux/status`, `/flux/auto-pilot`, `/flux/rebase`. Do NOT suggest any command not on this list.
+
+=================
+$ARGUMENTS

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/squash-commits.md

@@ -0,0 +1,179 @@
+---
+name: squash-commits
+description: Squash all unmerged commits on the current branch into a single commit
+---
+
+# SQUASH ALL UNMERGED COMMITS INTO ONE
+
+Collapses every commit on your branch that hasn't landed on the default branch yet into a single commit. Useful before opening a PR or when you want a clean history.
+
+**Example:** 7 work-in-progress commits on `luc/my-feature` → squashed into 1 clean commit, preserving all changes.
+
+## STEP 1: Capture current state
+
+```bash
+BRANCH=$(git branch --show-current)
+TICKET=$(echo "$BRANCH" | grep -oE '[A-Z]+-[0-9]+' | head -1 || echo "")
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
+echo "BRANCH: $BRANCH"
+echo "TICKET: $TICKET"
+echo "DEFAULT_BRANCH: $DEFAULT_BRANCH"
+
+# Commits on our branch that aren't on the default branch
+COMMIT_COUNT=$(git log "$DEFAULT_BRANCH"..HEAD --oneline | wc -l | tr -d ' ')
+echo "Commits to squash: $COMMIT_COUNT"
+git log "$DEFAULT_BRANCH"..HEAD --oneline
+
+# Files we touch
+git diff "$DEFAULT_BRANCH" --stat
+```
+
+**Guards — stop if any of the following are true:**
+
+- `$BRANCH` is empty or equals `HEAD` (detached HEAD state) → stop and tell the user: "You are in a detached HEAD state. Please checkout a real feature branch before squashing."
+- `$COMMIT_COUNT` == 0 → stop and tell the user: "No commits found on this branch ahead of `$DEFAULT_BRANCH`. Nothing to squash."
+- `$COMMIT_COUNT` == 1 → stop and tell the user: "This branch has only 1 commit ahead of `$DEFAULT_BRANCH`. There is nothing to squash — you already have a single commit."
+
+## STEP 2: Working tree must be clean
+
+```bash
+git status --porcelain
+```
+
+If there is **any** output (staged or unstaged changes, untracked files you care about):
+
+`ask_user_question` — question: "Your working tree is not clean. Squashing requires a clean tree (or stashed work). How do you want to proceed?" / header: "Unclean working tree" / options:
+
+- `Stash changes and continue` → run `git stash push -u -m "myproj-flux-squash-wip"`. Set an internal flag that a stash was created — STEP 9 will offer to pop it.
+- `Abort` → stop. Do not squash.
+
+If the tree is already clean, continue to STEP 3.
+
+## STEP 3: Check remote sync
+
+Fetch the remote branch ref (quietly, so offline environments don't hard-fail), then check if the remote is ahead of the local branch:
+
+```bash
+git fetch origin "$BRANCH" 2>/dev/null || true
+
+REMOTE_AHEAD=$(git rev-list HEAD..origin/"$BRANCH" --count 2>/dev/null || echo "0")
+echo "Remote ahead by: $REMOTE_AHEAD commit(s)"
+```
+
+If `$REMOTE_AHEAD` > 0 → **stop** and inform the user:
+
+> ⚠️ Your local branch `$BRANCH` is behind its remote counterpart (`origin/$BRANCH`) by **$REMOTE_AHEAD commit(s)**. Squashing now would rewrite history on top of a stale base, causing a push conflict.
+>
+> **What to do first:**
+>
+> 1. Run `/flux/rebase` to bring your branch up to date with the latest `$DEFAULT_BRANCH` while incorporating the remote's changes.
+> 2. Once your branch is in sync, run `/flux/squash-commits` again.
+>
+> Alternatively, run `git pull --rebase origin $BRANCH` to sync with the remote, then re-run `/flux/squash-commits`.
+
+If `$REMOTE_AHEAD` == 0 (or the remote branch doesn't exist yet), continue to STEP 4.
+
+## STEP 4: Show commits and confirm
+
+Display the commits that will be squashed:
+
+```bash
+echo "The following $COMMIT_COUNT commits will be squashed into one:"
+git log "$DEFAULT_BRANCH"..HEAD --oneline
+```
+
+`ask_user_question` — question: "Squash these $COMMIT_COUNT commits into one?" / header: "Confirm squash" / options:
+
+- `Yes, squash them` → continue to STEP 5.
+- `Abort` → stop. Do not squash.
+
+## STEP 5: Build the combined commit message
+
+Collect all commit subjects and bodies, in chronological order (oldest first), and format as a bulleted list:
+
+```bash
+SQUASH_MSG=$(git log "$DEFAULT_BRANCH"..HEAD --format="- %s%n%b" --reverse | sed '/^$/d' | sed 's/^- -/  -/')
+echo "Proposed commit message:"
+echo "---"
+echo "$SQUASH_MSG"
+echo "---"
+```
+
+`ask_user_question` — question: "Use this combined commit message for the squashed commit?" / header: "Commit message" / options:
+
+- `Yes, use this message` → use `$SQUASH_MSG` as-is. Continue to STEP 6.
+- `Let me write my own` → `ask_user_question` — question: "Enter your commit message:" / header: "Custom message" / options: _(free text — user selects Other)_. Use the user's input as `$SQUASH_MSG`.
+
+## STEP 6: Squash
+
+Perform the squash using a soft reset to the merge base, then commit:
+
+```bash
+MERGE_BASE=$(git merge-base HEAD "$DEFAULT_BRANCH")
+echo "Merge base: $MERGE_BASE"
+git reset --soft "$MERGE_BASE"
+git commit -m "$SQUASH_MSG"
+```
+
+> **What this does:** `git reset --soft` moves HEAD back to the merge base while keeping all changes staged, then a single `git commit` creates one new commit containing everything.
+
+## STEP 7: Verify
+
+Confirm the squash produced exactly 1 commit and that all changes are intact:
+
+```bash
+echo "Commits on branch after squash:"
+git log "$DEFAULT_BRANCH"..HEAD --oneline
+
+echo ""
+echo "Changed files vs $DEFAULT_BRANCH:"
+git diff "$DEFAULT_BRANCH" --stat
+```
+
+Expected: exactly 1 commit in the log. Changed files should match what was there before the squash. If the log shows more than 1 commit or the diff looks wrong — stop and investigate before pushing.
+
+## STEP 8: Confirm push
+
+After a squash, commit hashes differ from any previous push of the same branch. Choose the right push: first-time upstream vs `--force-with-lease` when the branch already exists on the remote.
+
+```bash
+git rev-parse @{u} >/dev/null 2>&1 && echo HAS_UPSTREAM || echo NO_UPSTREAM
+```
+
+- **`NO_UPSTREAM`** (first push of this branch): `ask_user_question` — question: "Squash is complete and verified. Push this branch and set upstream with `git push -u origin \"$BRANCH\"`? (No force needed.)" / header: "Push branch" / options: `Yes, push now` | `No, I'll push manually later`
+
+  - Yes → `git push -u origin "$BRANCH"`
+  - No → skip push; say so in STEP 9.
+
+- **`HAS_UPSTREAM`**: `ask_user_question` — question: "Squash rewrote history. Push with `git push --force-with-lease origin \"$BRANCH\"`? Refuses if someone else pushed in the meantime. Only do this for your own feature branch — never `$DEFAULT_BRANCH`." / header: "Push squashed branch" / options: `Yes, force-with-lease now` | `No, I'll push manually later`
+  - Yes → `git push --force-with-lease origin "$BRANCH"`
+  - No → skip push; say so in STEP 9.
+
+If `--force-with-lease` fails because the remote moved, run `git fetch origin`, re-evaluate (and re-ask if appropriate), then retry.
+
+> ⚠️ Never `git push --force` without lease, and never force-push `$DEFAULT_BRANCH`.
+
+## STEP 9: Summarize
+
+Report:
+
+- `$TICKET` (if any) and `$BRANCH`
+- How many commits were squashed into 1 (the original `$COMMIT_COUNT`)
+- The final commit message used
+- Push: done vs deferred by user choice
+- If STEP 2 stashed: use `ask_user_question` — question: "You stashed changes before squashing. Do you want to pop the stash now?" / header: "Restore stash" / options: `Yes, pop stash now` | `No, I'll pop it manually later`
+  - Yes → run `git stash pop`. If it produces conflicts, list the conflicted files and instruct the user to resolve them manually (`git add <file>` after editing, then `git stash drop` once done — do NOT run `git stash pop` again).
+  - No → remind the user to run `git stash pop` manually when ready.
+
+## HARD CONSTRAINT
+
+`/flux/squash-commits` MUST NOT modify commit content beyond the squash itself. MUST NOT commit to `$DEFAULT_BRANCH`. MUST NOT use `git push --force` (use `--force-with-lease` when updating an existing remote branch). MUST NOT touch any commits already present on `$DEFAULT_BRANCH`.
+
+## Propose next step
+
+Then propose the next step: `/flux/create-pr` (include arguments if needed).
+
+Valid `//flux` commands: `/flux/config`, `/flux/new`, `/flux/ask`, `/flux/split`, `/flux/aug`, `/flux/exec`, `/flux/qa`, `/flux/tests`, `/flux/commit`, `/flux/create-pr`, `/flux/review`, `/flux/address-feedback`, `/flux/status`, `/flux/auto-pilot`, `/flux/rebase`, `/flux/squash-commits`. Do NOT suggest any command not on this list.
+
+=================
+$ARGUMENTS

code_puppy_core_plugins/flux_bootstrap/bundled/commands/flux/status.md

@@ -0,0 +1,46 @@
+---
+name: status
+description: Display the pipeline stage and status of all task files
+ui-mode: flux-status
+exec: {python} {script:flux_status.py}
+---
+
+# /flux/status — PIPELINE STATUS
+
+Show the current pipeline stage and status of every active task file in `todo/`.
+
+> **Note:** This command is handled natively by the bundled flux_status.py
+> script (resolved under code-puppy's config dir). The markdown below is
+> reference documentation only — it is not executed by the AI.
+
+## DATA SOURCE
+
+Reads `~/.flux/<flattened-dir>/todo/*.md` only. `<flattened-dir>` is derived from
+the current working directory at the time `/flux/status` is invoked — every
+non-alphanumeric character in the absolute path is replaced with a hyphen.
+Completed tasks moved to `done/` by `/flux/qa` are intentionally excluded.
+
+## DISPLAY
+
+Renders a floating overlay panel (upper-right corner) with:
+
+- One row per task file: filename | stage | status
+- Summary footer with counts per status value
+- ESC to close
+
+### Example output
+
+```
+𝕱 PIPELINE STATUS        (Ctrl+F to close)
+══════════════════════════════════════════════
+ ─────────────────────────────────────────────
+ FIX_COMMAND_HINTS.md  exec   🔄 in-progress
+ DARK_MODE.md          qa     🔁 needs-rework
+═══════════════════════════════════════════════
+```
+
+If there are no task files in `todo/`, the panel shows:
+
+```
+(no todos)
+```