@raquezha/norpiv 0.0.5 → 0.0.7

package/README.md

@@ -2,6 +2,10 @@
 
 RPIV: a gated workflow for reliable AI coding agents.
 
+RPIV is one implementation of the broader `nothing` Workflow Contract. The contract defines the generic shape for workflows such as RPIV and Research, focusing on 3 Real Modes (Chat, Research, RPIV) tracked by `.workflow/active.json`.
+
+Standalone package usage still works: `@raquezha/norpiv` includes the RPIV skills, `distill`, and helper scripts needed for handoff. The local Research workflow lives separately under `packages/workflows/noresearch`. The platform-level contract lives in the source repo at <https://github.com/raquezha/nothing/blob/main/docs/workflow.md>.
+
 ## 🔁 The Lifecycle
 
 The RPIV engine splits task execution into separate, focused phases:
@@ -20,7 +24,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 +55,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 +88,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
@@ -112,6 +116,8 @@ Obsidian note → /triage → RPIV             (only when ready to commit)
 
 `distill` is the missing layer before RPIV. Use `pi --notes` to load it.
 
+Research is a separate local workflow bundle in `packages/workflows/noresearch` and is loaded by the full `nothing` setup with `pi --research`.
+
 ## 🚀 Quick Start Example
 
 1. **Activate the RPIV Hat** from the full `nothing` setup:
@@ -152,7 +158,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/frame/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: frame
+workflow: rpiv
+workflowPhase: frame
 description: Define the task brief inside the active WORK.md. Use after /triage to convert issue data into a clear Problem or Proposal brief without creating separate PROBLEM.md or PRD.md files.
 ---
 
@@ -8,7 +10,7 @@ description: Define the task brief inside the active WORK.md. Use after /triage
 Turn raw task context into the stable "what/why" brief.
 
 ## Guardrails
-- READ: `.workflow/active_task.json`, `.workflow/tasks/[active_task]/WORK.md`, and `.reposcry/AI_CONTEXT.md` when present.
+- READ: `.workflow/active.json` / `.workflow/active_task.json`, active `WORK.md`, and `.reposcry/AI_CONTEXT.md` when present.
 - WRITE: `WORK.md` -> `[BRIEF]` section and append to `[LOG]` only; optional `.reposcry/AI_CONTEXT.md` when RepoScry is installed.
 - NEVER: create `PROBLEM.md`, `PRD.md`, or extra planning files.
 - NEVER: overwrite `[PLAN]` or `[GRILL]`.

package/grill-with-docs/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: grill-with-docs
+workflow: rpiv
+workflowPhase: grill-with-docs
 description: Stress-test the active WORK.md brief against docs, code, and domain language. Use after /frame before planning to clarify assumptions and update durable docs only when decisions are stable.
 ---
 
@@ -8,7 +10,7 @@ description: Stress-test the active WORK.md brief against docs, code, and domain
 Challenge the brief before planning. This replaces passive ubiquitous-language collection with active clarification.
 
 ## Guardrails
-- READ: `.workflow/active_task.json`, active `WORK.md` `[BRIEF]`, `CONTEXT.md`, relevant `docs/agents/*`, and `.reposcry/AI_CONTEXT.md` when present.
+- READ: `.workflow/active.json` / `.workflow/active_task.json`, active `WORK.md` `[BRIEF]`, `CONTEXT.md`, relevant `docs/agents/*`, and `.reposcry/AI_CONTEXT.md` when present.
 - WRITE: `WORK.md` -> append to `[GRILL]` and `[LOG]` only; durable docs only when a stable rule is confirmed.
 - NEVER: edit `[BRIEF]` silently; propose brief changes if contradictions are found.
 - NEVER: plan or implement during grilling.

package/implement/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: implement
+workflow: rpiv
+workflowPhase: implement
 description: Implement the next approved vertical slice from the active WORK.md and prepare a Draft PR/MR. Use when the plan is approved and the user explicitly asks to implement.
 ---
 
@@ -8,7 +10,7 @@ description: Implement the next approved vertical slice from the active WORK.md
 Execute one functional vertical slice and hand it to the human for review.
 
 ## Guardrails
-- READ: `.workflow/active_task.json` then active `WORK.md` `[PLAN]`, `[BRIEF]`, and relevant `[LOG]` evidence.
+- READ: `.workflow/active.json` / `.workflow/active_task.json` then active `WORK.md` `[PLAN]`, `[BRIEF]`, and relevant `[LOG]` evidence.
 - WRITE: code changes and `WORK.md` -> append to `[LOG]` only; optional `.reposcry/` cache refresh when RepoScry is installed.
 - NEVER: edit `[BRIEF]` or `[GRILL]`.
 - NEVER: implement without explicit user instruction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raquezha/norpiv",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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/plan/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: plan
+workflow: rpiv
+workflowPhase: plan
 description: Create or revise vertical implementation slices in the active WORK.md. Use after /grill-with-docs to produce a concise, reviewable plan for implementation.
 ---
 
@@ -8,7 +10,7 @@ description: Create or revise vertical implementation slices in the active WORK.
 Map the "how" into tracer-bullet vertical slices.
 
 ## Guardrails
-- READ: `.workflow/active_task.json` then active `WORK.md` `[BRIEF]` and `[GRILL]`.
+- READ: `.workflow/active.json` / `.workflow/active_task.json` then active `WORK.md` `[BRIEF]` and `[GRILL]`.
 - WRITE: `WORK.md` -> `[PLAN]` and append to `[LOG]` only.
 - NEVER: implement code during planning.
 - NEVER: create standalone `PLAN.md`.

package/scripts/triage_helper.sh

@@ -120,13 +120,13 @@ PY
 
 write_active_pointer() {
     mkdir -p ".workflow"
-    python3 - ".workflow/active_task.json" "$TASK_FOLDER" "$SOURCE" "$ID" "$TASK_DIR" "$BRANCH_NAME" <<'PY'
+    python3 - ".workflow/active_task.json" ".workflow/active.json" "$TASK_FOLDER" "$SOURCE" "$ID" "$TASK_DIR" "$WORK_MD" "$BRANCH_NAME" "$ISO_NOW" <<'PY'
 import json
 import sys
 from pathlib import Path
 
-path, active_task, source, raw_id, task_path, branch = sys.argv[1:]
-data = {
+active_task_path, active_workflow_path, active_task, source, raw_id, task_path, state_file, branch, now = sys.argv[1:]
+legacy_data = {
     "active_task": active_task,
     "source": source,
     "id": raw_id,
@@ -135,7 +135,22 @@ data = {
     "path": task_path,
     "branch": branch,
 }
-Path(path).write_text(json.dumps(data, indent=2) + "\n")
+workflow_data = {
+    "workflow": "rpiv",
+    "id": active_task,
+    "taskId": active_task,
+    "source": source,
+    "sourceId": raw_id,
+    "stateFile": state_file,
+    "taskPath": task_path,
+    "path": task_path,
+    "branch": branch,
+    "startedAt": now,
+    "updatedAt": now,
+    "compatPointer": ".workflow/active_task.json",
+}
+Path(active_task_path).write_text(json.dumps(legacy_data, indent=2) + "\n")
+Path(active_workflow_path).write_text(json.dumps(workflow_data, indent=2) + "\n")
 PY
 }
 

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

@@ -1,5 +1,7 @@
 ---
 name: sync
+workflow: rpiv
+workflowPhase: sync
 description: Synchronizes local RPIV task state (WORK.md) to external trackers (Jira, GitHub, GitLab). Use this to publish progress, update implementation status, and maintain a durable audit trail between local development and remote project management tools.
 ---
 
@@ -8,7 +10,7 @@ description: Synchronizes local RPIV task state (WORK.md) to external trackers (
 Maintains consistency between local `.workflow` state and the remote source of truth using a single Pi-owned living status comment per task.
 
 ## Guardrails
-- **Pre-flight**: Always read `.workflow/active_task.json` and the active `WORK.md` before executing.
+- **Pre-flight**: Always read `.workflow/active.json` / `.workflow/active_task.json` and the active `WORK.md` before executing.
 - **Privacy**: NEVER sync secrets, environment variables, or private notes not intended for stakeholders.
 - **Integrity**: Do not modify `[BRIEF]` or `[GRILL]` sections.
 - **Idempotency**: If the remote Pi status already reflects the current local state, do not post or update.
@@ -44,7 +46,7 @@ Do **not** use latest-comment ownership as the primary decision. Latest-comment-
 ## Workflow
 
 ### 1. Discovery & State Loading
-- Identify the platform and ID from `.workflow/active_task.json`.
+- Identify the platform and ID from `.workflow/active.json` or compatibility `.workflow/active_task.json`.
 - Extract **Slices** from `[PLAN]`, **Status** from `[LOG]`, and **Artifacts** such as PR/MR links, commit hashes, and verification output.
 
 ### 2. Payload Preparation
@@ -128,4 +130,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/triage/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: triage
+workflow: rpiv
+workflowPhase: triage
 description: "Ingest or resume a tracked/local task in the RPIV workspace. Use when starting or returning to jira:, github:, gitlab:, or local: work and you need canonical WORK.md state without duplicating the scaffold."
 ---
 
@@ -8,10 +10,10 @@ description: "Ingest or resume a tracked/local task in the RPIV workspace. Use w
 Start RPIV by creating, resuming, or explicitly reopening a task workspace.
 
 ## Guardrails
-- READ: user argument, `.workflow/active_task.json` if present, target `metadata.json`, and target `WORK.md` if resuming.
-- WRITE: `.workflow/tasks/[source-id]/WORK.md`, `.workflow/tasks/[source-id]/metadata.json`, `.workflow/active_task.json`; optional `.reposcry/` cache files only if RepoScry is installed.
+- READ: user argument, `.workflow/active.json` / `.workflow/active_task.json` if present, target `metadata.json`, and target `WORK.md` if resuming.
+- WRITE: `.workflow/tasks/[source-id]/WORK.md`, `.workflow/tasks/[source-id]/metadata.json`, `.workflow/active.json`, `.workflow/active_task.json`; optional `.reposcry/` cache files only if RepoScry is installed.
 - On **create**, initialize required guarded sections only if absent: `[BRIEF]`, `[GRILL]`, `[PLAN]`, `[LOG]`, `[META]`.
-- On **resume**, only update `.workflow/active_task.json`, metadata timestamps/state as needed, and `[META]`, then append one concise `[LOG]` entry.
+- On **resume**, only update `.workflow/active.json`, `.workflow/active_task.json`, metadata timestamps/state as needed, and `[META]`, then append one concise `[LOG]` entry.
 - NEVER: duplicate guarded sections.
 - NEVER: overwrite existing `[BRIEF]`, `[GRILL]`, or `[PLAN]` during triage.
 - NEVER: create `PROBLEM.md`, `PRD.md`, `PLAN.md`, or `EVIDENCE.md`.

package/verify/SKILL.md

@@ -1,6 +1,8 @@
 ---
 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.
+workflow: rpiv
+workflowPhase: 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 post-merge-prune.
 ---
 
 # Skill: verify
@@ -8,7 +10,7 @@ description: Verify the active slice or task against WORK.md, quality gates, and
 The final gate for a slice or task. Verify truth before reporting progress.
 
 ## Guardrails
-- READ: `.workflow/active_task.json`, active `WORK.md` `[BRIEF]`, `[PLAN]`, and `[LOG]`.
+- READ: `.workflow/active.json` / `.workflow/active_task.json`, active `WORK.md` `[BRIEF]`, `[PLAN]`, and `[LOG]`.
 - WRITE: `WORK.md` -> `[PLAN]` checkboxes and append to `[LOG]` only.
 - NEVER: add `Signed-off-by`; tell the human to sign if needed.
 - NEVER: transition tracker state if verification fails.
@@ -21,7 +23,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`.