@raquezha/norpiv 0.0.5 → 0.0.6

package/README.md

@@ -20,7 +20,7 @@ Auxiliary hygiene:
 
 | Command | Purpose | Input / Output Files |
 | :--- | :--- | :--- |
-| `/cleanup` | Declutter Git branches and completed task folders after work is merged/closed. | Prunes finished task folders & resets pointer when safe |
+| `/post-merge-prune` | Delete stale local branches after a PR/MR is merged, prune remote refs, and clean completed task folders. | Post-merge branch cleanup plus safe task-folder cleanup |
 
 ---
 
@@ -51,7 +51,7 @@ Best for trying or handing off RPIV skills without installing the full `nothing`
 
 ```bash
 npx -y skills add raquezha/nothing --full-depth -g -a pi \
-  -s triage frame grill-with-docs plan implement verify sync cleanup update-docs distill \
+  -s triage frame grill-with-docs plan implement verify sync post-merge-prune update-docs distill \
   -y
 ```
 
@@ -84,7 +84,7 @@ Targets:
 
 | Hat | Purpose |
 | :--- | :--- |
-| `pi --rpiv` | Full RPIV workflow. Loads triage, frame, grill-with-docs, plan, implement, verify, sync, cleanup, and update-docs. |
+| `pi --rpiv` | Full RPIV workflow. Loads triage, frame, grill-with-docs, plan, implement, verify, sync, post-merge-prune, and update-docs. |
 | `pi --notes` | Conversation distiller. Saves useful thinking to Obsidian without RPIV ceremony. |
 
 ## 📝 Pre-RPIV note capture
@@ -152,7 +152,7 @@ Obsidian note → /triage → RPIV             (only when ready to commit)
    ```text
    /verify
    /sync
-   /cleanup
+   /post-merge-prune
    ```
 
 ## 🧭 Shared helper scripts

package/bin/norpiv-install.cjs

@@ -136,7 +136,7 @@ function writeCodexAdapter(root, names, sharedNames, opts) {
   const sharedLines = sharedNames.length
     ? `\nShared helpers:\n\n${sharedNames.map((name) => `- ${name}/`).join("\n")}\n`
     : "";
-  const body = `# norpiv RPIV skills for Codex\n\nCodex does not currently auto-load Pi/Claude SKILL.md bundles from npm.\n\nUse these installed skill instructions as a portable RPIV workflow reference:\n\n${names.map((name) => `- ${name}/SKILL.md`).join("\n")}\n${sharedLines}\nCore lifecycle: triage → frame → grill-with-docs → plan → implement → verify → sync → cleanup.\n\nIf your Codex environment supports AGENTS.md discovery, copy or reference this file from your project.\n`;
+  const body = `# norpiv RPIV skills for Codex\n\nCodex does not currently auto-load Pi/Claude SKILL.md bundles from npm.\n\nUse these installed skill instructions as a portable RPIV workflow reference:\n\n${names.map((name) => `- ${name}/SKILL.md`).join("\n")}\n${sharedLines}\nCore lifecycle: triage -> frame -> grill-with-docs -> plan -> implement -> verify -> sync -> post-merge-prune.\n\nIf your Codex environment supports AGENTS.md discovery, copy or reference this file from your project.\n`;
   log(opts, `write Codex adapter ${adapter}`);
   if (!opts.dryRun) fs.writeFileSync(adapter, body);
 }

package/distill/SKILL.md

@@ -180,7 +180,7 @@ If writing fails, output the markdown to stdout so the user can copy it manually
 - Does not require `WORK.md`
 - Does not interact with `.workflow/` directory
 - Does not sync to Jira, GitHub, or GitLab
-- Does not run cleanup
+- Does not run post-merge-prune
 - Does not require any existing task or ticket
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raquezha/norpiv",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Bundled RPIV workflow skills for Pi, Claude, and Codex-style coding agents",
   "type": "commonjs",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "files": [
     "bin",
-    "cleanup",
+    "post-merge-prune",
     "distill",
     "frame",
     "grill-with-docs",
@@ -44,7 +44,7 @@
       "verify",
       "sync",
       "update-docs",
-      "cleanup",
+      "post-merge-prune",
       "distill"
     ]
   }

package/post-merge-prune/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: post-merge-prune
+description: "Post-merge branch cleanup only. Use after a PR/MR is merged and the local feature branch is stale: prune remote refs and delete local branches already merged into the target branch."
+---
+
+# Skill: post-merge-prune
+
+> [!IMPORTANT]
+> **LLM INSTRUCTION**: This skill is a deliberate post-merge deletion tool. If the user invokes `post-merge-prune`, they want stale local branches removed after merge into the intended target branch. Do not offer a menu of options. Do not ask "Dry run or Execute?". Proceed directly.
+
+Use this skill after a PR/MR has been merged into its intended branch, typically `main`, to remove stale remote-tracking refs and delete the matching local branches because the work is done.
+
+## Goal
+- Switch to the intended target branch (`main` by default).
+- Prune deleted remote branches.
+- Delete local branches that are already merged into the target branch.
+- Optionally remove matching workflow task folders.
+
+## Workflow
+
+### Step 1: Go to the target branch
+- `git checkout main` (or the intended merge target)
+- If the tree is dirty, stash first.
+
+### Step 2: Prune remote-tracking refs
+- `git remote update origin --prune`
+- This removes local refs for remote branches that were deleted after merge.
+
+### Step 3: Delete merged local branches
+Iterate through local branches and delete the ones already merged into the target branch:
+- Use `git branch -d <branch>` for normal merges.
+- If `-d` refuses but `git log main..[branch]` is empty, the branch was squash-merged; use `git branch -D <branch>`.
+- Never delete the active target branch.
+
+### Step 4: Optional workflow cleanup
+If a deleted branch has a matching `.workflow/tasks/*` folder, remove it.
+If `.workflow/active_task.json` points to a deleted task, clear it.
+
+### Step 5: Verify
+- `git branch -a` should no longer show deleted refs.
+- `git branch --merged main` should only show branches you intend to keep.
+- `.workflow/tasks/` should not contain deleted tasks.
+
+## Guardrails
+- **RESOLUTION OVER REPORTING**: If merge status is unclear, check `git branch --merged main` or `git log main..branch` and resolve it.
+- **NO DRY RUNS BY DEFAULT**: Execute the cleanup unless the user explicitly asks for a preview.
+- **SMART DELETE**: If a branch is squash-merged, delete it with `git branch -D` after confirming there are no unique commits left.
+- **ACTIVE BRANCH PROTECTION**: Do not delete the current branch.
+- **UNMERGED WORK**: If a branch has unique commits and no remote, ask once before force-deleting.
+
+## Output Contract
+Return a concise report:
+- **Cleaned**: deleted branches / task folders
+- **Kept**: branches still in use
+- **Working Branch**: the branch left checked out (should be `main`)

package/scripts/validate_active_task.sh

@@ -289,7 +289,7 @@ if [[ -n "$WORK_MD" && -f "$WORK_MD" ]]; then
 fi
 
 if [[ "$META_STATUS" =~ ^(done|archived)$ ]]; then
-  warn "active pointer references a task with status=$META_STATUS; consider cleanup, archive handling, or reopening intentionally"
+  warn "active pointer references a task with status=$META_STATUS; consider post-merge-prune, archive handling, or reopening intentionally"
 fi
 
 echo
@@ -315,7 +315,7 @@ if [[ -n "$WORK_MD" && -f "$WORK_MD" ]]; then
 fi
 if [[ -n "$META_STATUS" && "$META_STATUS" =~ ^(done|archived)$ ]]; then
   echo "  - Choose intentionally: $TRIAGE_HELPER ${TASK_SOURCE:-local} ${TASK_ID:-task} reopen"
-  echo "  - Or leave closed and run cleanup when appropriate."
+  echo "  - Or leave closed and run post-merge-prune when appropriate."
 fi
 if [[ "$WARNINGS" -eq 0 && "$ERRORS" -eq 0 ]]; then
   echo "  - No fixes suggested."

package/sync/SKILL.md

@@ -128,4 +128,4 @@ Return a concise summary:
 - **Action**: no-op / updated existing status / created new status
 - **Reason**: marker found, body identical, marker missing, etc.
 - **Link**: remote comment/note URL if available
-- **Next step**: review, verify, cleanup, or continue implementation
+- **Next step**: review, verify, post-merge-prune, or continue implementation

package/verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify
-description: Verify the active slice or task against WORK.md, quality gates, and review readiness. Use after implementation or manual changes to decide whether work is ready for sync, review, or cleanup.
+description: Verify the active slice or task against WORK.md, quality gates, and review readiness. Use after implementation or manual changes to decide whether work is ready for sync, review, or post-merge-prune.
 ---
 
 # Skill: verify
@@ -21,7 +21,7 @@ The final gate for a slice or task. Verify truth before reporting progress.
 4. Check for AI artifacts: placeholder comments, fake APIs, dead code, inconsistent naming.
 5. Confirm commit messages include Conventional Commit format. When AI contributed, you MUST append an `Assisted-by` trailer. Do NOT guess or hallucinate the model name from your system prompt. You must run `bash ~/RQZ/personal/nothing/packages/norpiv/scripts/get-pi-model.sh` and use its exact output to construct the trailer: `Assisted-by: <EXACT_OUTPUT> [tools]`.
 6. If passing, mark the slice checkbox complete in `[PLAN]` and append verification evidence to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`).
-7. Recommend `/sync` for tracker update, or cleanup if the task is fully merged and user approves.
+7. Recommend `/sync` for tracker update, or `/post-merge-prune` if the task is fully merged and user approves.
 
 ## Output contract
 End with:

package/cleanup/SKILL.md

@@ -1,53 +0,0 @@
----
-name: cleanup
-description: "DIRECT EXECUTION: Immediately prunes local branches and task folders. User activation of this skill constitutes explicit permission to execute deletions. Do not ask for confirmation or offer dry runs unless requested. Reconciles stale Git refs and workflow artifacts."
----
-
-# Skill: cleanup (Durable Repo Hygiene)
-
-> [!IMPORTANT]
-> **LLM INSTRUCTION**: This skill is a DIRECT ACTION tool. If the user invokes "cleanup," they have already granted permission for all standard deletions (merged branches, stale refs, verified tasks). DO NOT offer a menu of options. DO NOT ask "Dry run or Execute?". Proceed directly to Step 1.
-
-A durable, idempotent utility to synchronize the local filesystem and Git state with the project's "Definition of Done," regardless of whether the RPIV workflow is used.
-
-## Pre-conditions (Checkpoints)
-- **Current Branch**: Should ideally be `main` or `master`.
-- **Durable State Source**: `git branch` refs and (optionally) `.workflow/tasks/*/WORK.md`.
-
-## Workflow (Durable Steps)
-
-### Step 1: Remote Reconciliation
-- `git remote update origin --prune`
-- Identify branches deleted on remote.
-
-### Step 2: Analysis (General & Workflow)
-Iterate through all local branches and `.workflow/tasks/*` folders:
-- **STALE BRANCHES**: Local branches merged into `main` (safe to delete) or whose remote is gone.
-- **VERIFIED TASKS**: `.workflow/tasks/*` where `WORK.md` state is `MERGED` or `CLOSED`.
-- **ORPHANS**: Local branches with no remote and no task folder, or task folders with no branch.
-
-### Step 3: Atomic Execution
-1. **Branch Pruning**: 
-   - Use `git branch -d` for merged branches.
-   - **Smart Merge Check**: If `-d` fails, check `git log main..[branch]`. If empty, the branch was squash-merged; use `git branch -D` quietly.
-2. **Artifact Cleanup**: If a `.workflow/tasks/` folder exists for a pruned branch, `rm -rf` it.
-3. **Active Task Reset**: Clear `.workflow/active_task.json` if it points to a deleted task.
-
-### Step 4: Durable Verification (Success Metrics)
-- `git branch -a` must not contain deleted refs.
-- `.workflow/tasks/` must not contain folders for deleted tasks.
-
-## Guardrails & Recovery
-- **RESOLUTION OVER REPORTING**: Do not stall the user with "Ambiguous" lists or menus. If a status is unclear, the agent must check merge status (`git branch --merged` or `git log main..branch`) immediately and resolve it.
-- **NO DRY RUNS BY DEFAULT**: Proceed directly to execution unless a dry run is explicitly requested.
-- **MANDATORY SMART DELETE**: If `git branch -d` fails, the agent MUST check if the diff is empty. If empty (squash-merged), use `git branch -D` quietly.
-- **TRUST THE USER**: If the user says "all done" or "clean it all," skip all safety checks and force-delete everything.
-- **Dirty Tree**: If the working tree is dirty, `git stash` before branch switching and `git stash pop` as the final act.
-- **Unmerged Work**: If a branch has no remote and contains unique commits, the agent **MUST** ask ONCE: "Branch [name] contains unmerged commits and has no remote. Force delete? (y/N)".
-
-## Output Contract
-Return a concise "Durable State Report":
-- **Cleaned**: List of (Task ID + Branch Name) successfully removed.
-- **Skipped/Active**: List of tasks kept and why (e.g., "Contains unmerged commits").
-- **Working Branch**: The branch left active (should be `main`).
-- **Next step**: Ready for `/triage`.