@raquezha/norpiv 0.0.2

package/README.md

@@ -0,0 +1,154 @@
+# norpiv (Lean RPIV Workflow Engine)
+
+A disciplined task execution lifecycle for the Pi coding agent designed to maximize accuracy, control, and traceability through a step-by-step Staff Engineer planning process.
+
+## 🔁 The Lifecycle
+
+The RPIV engine splits task execution into separate, focused phases:
+
+| Phase | Command | Purpose | Input / Output Files |
+| :--- | :--- | :--- | :--- |
+| **1. Ingest** | `/triage [source]:[id]` | Initial task verification and workspace setup. | Creates `.workflow/tasks/[source-id]/WORK.md` & `metadata.json` |
+| **2. Scoping** | `/frame` | Author a clear, structured task brief. | Populates `WORK.md` ➔ `[BRIEF]` section |
+| **3. Interrogate**| `/grill-with-docs` | Stress-test brief against rules and docs. | Records decisions in `WORK.md` ➔ `[GRILL]` |
+| **4. Strategy** | `/plan` | Draft thin, independently testable slices. | Writes checkbox items in `WORK.md` ➔ `[PLAN]` |
+| **5. Coding** | `/implement` | Execute one approved plan slice (needs permission). | Modifies code; records updates in `WORK.md` ➔ `[LOG]` |
+| **6. Truth Test** | `/verify` | Run tests, lint, and verify quality. | Appends results to `[LOG]` |
+| **7. Close** | `/sync` | Bridge local progress with external trackers. | Posts summary updates to Jira, GitHub, or GitLab |
+
+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 |
+
+---
+
+## 🛡️ Critical Guardrails
+
+- **Measure Twice, Cut Once**: Never implement code during scoping or planning. The agent will wait for an explicit `EXECUTE` statement before modifying files.
+- **One Source of Truth**: All task state belongs in `.workflow/tasks/[source-id]/WORK.md`. Avoid creating separate `PROBLEM.md` or `PLAN.md` files.
+- **Safe Branching**: Triage and planning happen on the main branch. Create the feature branch (`feat/*` or `fix/*`) only when starting `/implement`.
+
+## 📦 Install as a skill bundle
+
+### From GitHub with `npx skills add`
+
+Best for trying or handing off RPIV skills without installing the full `nothing` setup:
+
+```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 \
+  -y
+```
+
+### From npm
+
+```bash
+npm install -g @raquezha/norpiv
+```
+
+Install the bundled skills for your agent runtime:
+
+```bash
+# Pi default: ~/.pi/agent/skills/{triage,frame,plan,...}
+norpiv-install
+
+# Other adapters
+norpiv-install --target claude
+norpiv-install --target codex
+norpiv-install --target all
+```
+
+Targets:
+- `pi` links skills into `~/.pi/agent/skills`.
+- `claude` links skills into `~/.claude/skills`.
+- `codex` installs the skill docs under `~/.codex/skills/norpiv` and writes an `AGENTS.md` adapter because Codex-style environments do not universally auto-load `SKILL.md` bundles.
+
+`norpiv-install` also installs the shared helper scripts under a sibling `scripts/` directory so skill references like `../scripts/triage_helper.sh` resolve after installation.
+
+## 🚀 Quick Start Example
+
+1. **Activate the RPIV Hat** from the full `nothing` setup:
+   ```bash
+   pi --rpiv
+   ```
+
+   If installed via `npx skills add` or `norpiv-install`, invoke the skills directly in your agent instead.
+
+2. **Triage an Issue**:
+   ```text
+   /triage github:45
+   ```
+
+3. **Frame the Work**:
+   ```text
+   /frame
+   ```
+
+4. **Verify Constraints**:
+   ```text
+   /grill-with-docs
+   ```
+
+5. **Write the Plan Slices**:
+   ```text
+   /plan
+   ```
+
+6. **Authorize Execution**:
+   Provide the agent explicit permission to implement:
+   ```text
+   EXECUTE
+   /implement
+   ```
+
+7. **Verify & Close**:
+   ```text
+   /verify
+   /sync
+   /cleanup
+   ```
+
+## 🧭 Shared helper scripts
+
+The bundle includes helper scripts used by the workflow skills:
+
+- `scripts/triage_helper.sh`
+- `scripts/validate_active_task.sh`
+- `scripts/reposcry-bootstrap.sh`
+- `scripts/reposcry-task-context.sh`
+- `scripts/reposcry-refresh.sh`
+
+When skills are loaded directly from this package, relative references like `../scripts/...` resolve against the package root. When skills are installed with `norpiv-install`, the same layout is recreated under the target runtime.
+
+## 🔎 Optional RepoScry integration
+
+RepoScry is an optional repo-memory layer for RPIV. norpiv does **not** require it.
+
+If `reposcry` is installed:
+
+```bash
+./scripts/reposcry-bootstrap.sh
+./scripts/reposcry-task-context.sh "fix dependency graph rebuild"
+# edit code
+./scripts/reposcry-refresh.sh main
+reposcry validate main HEAD
+```
+
+Typical usage by phase:
+
+- `/triage`: optionally seed `.reposcry/` with `scripts/reposcry-bootstrap.sh`
+- `/frame`: optionally generate `.reposcry/AI_CONTEXT.md` with `scripts/reposcry-task-context.sh`
+- `/grill-with-docs`: optionally use `reposcry query_graph`, `get_architecture_overview`, and `get_impact_radius`
+- `/implement`: optionally run `scripts/reposcry-refresh.sh` after edit batches
+- `/verify`: optionally add `reposcry validate main HEAD` and affected-flow output as extra evidence
+
+If RepoScry is absent, the helpers no-op and RPIV continues with normal repo reading, grep, and tests.
+
+RepoScry guardrails:
+
+- `.reposcry/` is generated local cache and must not be committed.
+- `scripts/reposcry-bootstrap.sh` automatically adds `.reposcry/` to the project `.gitignore` before initializing RepoScry.
+- If `.reposcry/` is already tracked or staged, bootstrap stops and tells you to remove it from the index.
+- `.reposcryignore` is indexing policy, not cache. Review and commit it when you want stable RepoScry behavior across machines.

package/bin/norpiv-install.cjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const bundleName = "norpiv";
+const sharedDirCandidates = ["scripts"];
+
+function usage() {
+  console.log(`Usage: norpiv-install [--target pi|claude|codex|all] [--dest PATH] [--copy] [--force] [--dry-run]
+
+Installs the bundled RPIV skill workflow and shared helper scripts for agent runtimes.
+
+Targets:
+  pi      Link skills into ~/.pi/agent/skills (default)
+  claude  Link skills into ~/.claude/skills
+  codex   Link skills into ~/.codex/skills/norpiv and generate an AGENTS.md adapter
+  all     Install all targets
+
+Options:
+  --dest PATH  Override target skill directory
+  --copy       Copy directories instead of symlinking
+  --force      Replace existing paths instead of backing them up
+  --dry-run    Print actions without changing files
+  --help       Show this help`);
+}
+
+function parseArgs(argv) {
+  const opts = { target: "pi", dest: "", copy: false, force: false, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      usage();
+      process.exit(0);
+    } else if (arg === "--target") {
+      opts.target = argv[++i] || "";
+    } else if (arg.startsWith("--target=")) {
+      opts.target = arg.slice("--target=".length);
+    } else if (arg === "--dest") {
+      opts.dest = argv[++i] || "";
+    } else if (arg.startsWith("--dest=")) {
+      opts.dest = arg.slice("--dest=".length);
+    } else if (arg === "--copy") {
+      opts.copy = true;
+    } else if (arg === "--force") {
+      opts.force = true;
+    } else if (arg === "--dry-run" || arg === "-n") {
+      opts.dryRun = true;
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      usage();
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function skillNames() {
+  return fs.readdirSync(packageRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => fs.existsSync(path.join(packageRoot, name, "SKILL.md")))
+    .sort();
+}
+
+function sharedDirNames() {
+  return sharedDirCandidates.filter((name) => fs.existsSync(path.join(packageRoot, name)));
+}
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function targetRoot(target, dest) {
+  if (dest) return path.resolve(expandHome(dest));
+  if (target === "pi") return path.join(os.homedir(), ".pi", "agent", "skills");
+  if (target === "claude") return path.join(os.homedir(), ".claude", "skills");
+  if (target === "codex") return path.join(os.homedir(), ".codex", "skills", bundleName);
+  throw new Error(`Unsupported target: ${target}`);
+}
+
+function log(opts, message) {
+  console.log(`${opts.dryRun ? "[dry-run] " : ""}${message}`);
+}
+
+function rmrf(target, opts) {
+  if (opts.dryRun) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function cpdir(src, dest, opts) {
+  if (opts.dryRun) return;
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function symlinkDir(src, dest, opts) {
+  if (opts.dryRun) return;
+  fs.symlinkSync(src, dest, "dir");
+}
+
+function installOne(src, dest, opts) {
+  if (!fs.existsSync(src)) throw new Error(`Missing source: ${src}`);
+  log(opts, `install ${src} -> ${dest}${opts.copy ? " (copy)" : " (symlink)"}`);
+  if (!opts.dryRun) fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+  if (fs.existsSync(dest)) {
+    const stat = fs.lstatSync(dest);
+    if (stat.isSymbolicLink()) {
+      const current = fs.readlinkSync(dest);
+      const resolved = path.resolve(path.dirname(dest), current);
+      if (!opts.copy && resolved === src) {
+        log(opts, `already linked ${dest}`);
+        return;
+      }
+    }
+    if (opts.force) {
+      log(opts, `remove existing ${dest}`);
+      rmrf(dest, opts);
+    } else {
+      const backup = `${dest}.backup.${Date.now()}`;
+      log(opts, `backup existing ${dest} -> ${backup}`);
+      if (!opts.dryRun) fs.renameSync(dest, backup);
+    }
+  }
+
+  if (opts.copy) cpdir(src, dest, opts);
+  else symlinkDir(src, dest, opts);
+}
+
+function writeCodexAdapter(root, names, sharedNames, opts) {
+  const adapter = path.join(root, "AGENTS.md");
+  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`;
+  log(opts, `write Codex adapter ${adapter}`);
+  if (!opts.dryRun) fs.writeFileSync(adapter, body);
+}
+
+function installTarget(target, opts) {
+  const root = targetRoot(target, opts.dest);
+  const names = skillNames();
+  const sharedNames = sharedDirNames();
+  if (!names.length) throw new Error(`No SKILL.md directories found in ${packageRoot}`);
+  if (!opts.dryRun) fs.mkdirSync(root, { recursive: true });
+  for (const name of names) {
+    const src = path.join(packageRoot, name);
+    const dest = path.join(root, name);
+    installOne(src, dest, opts);
+  }
+  for (const name of sharedNames) {
+    const src = path.join(packageRoot, name);
+    const dest = path.join(root, name);
+    installOne(src, dest, opts);
+  }
+  if (target === "codex") writeCodexAdapter(root, names, sharedNames, opts);
+  console.log(`Installed ${bundleName} skills for ${target} at ${root}`);
+}
+
+const opts = parseArgs(process.argv.slice(2));
+const targets = opts.target === "all" ? ["pi", "claude", "codex"] : [opts.target];
+for (const target of targets) installTarget(target, opts);

package/cleanup/SKILL.md

@@ -0,0 +1,53 @@
+---
+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`.

package/frame/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: 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.
+---
+
+# Skill: frame
+
+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.
+- 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]`.
+- NEVER: ask whether to frame if the user invoked `/frame`; do it.
+
+## Workflow
+1. Read the active task and remote metadata.
+2. If RepoScry is available, run the bundled `../scripts/reposcry-task-context.sh "<task summary>"` helper to generate `.reposcry/AI_CONTEXT.md`, then use that file as supplemental repo context. The helper path must preserve RepoScry guardrails: `.reposcry/` ignored, cache never tracked, `.reposcryignore` treated as reviewable indexing policy. Continue normally when unavailable.
+3. Determine brief type:
+   - **Problem** for bugs, regressions, crashes, broken behavior.
+   - **Proposal** for features, enhancements, refactors, new behavior.
+4. Create or replace only the `[BRIEF]` section with:
+   - type and source id
+   - current understanding
+   - desired outcome
+   - constraints / non-goals
+   - acceptance hints if available
+5. Keep the brief concise and reviewable.
+6. **Log Activity**: Append a timestamped summary of the framing/re-framing to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`). Include why the change was made if it is a pivot.
+7. End by recommending `/grill-with-docs`.
+
+## Output contract
+End with:
+- **Brief type**: Problem / Proposal
+- **Updated section**: `[BRIEF]`
+- **Open questions**: only if blocking
+- **Next step**: `/grill-with-docs`

package/grill-with-docs/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: 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.
+---
+
+# Skill: grill-with-docs
+
+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.
+- 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.
+- NEVER: ask questions the codebase can answer; inspect first.
+
+## Workflow
+1. **Context Loading**: Read the active brief, `CONTEXT.md`, relevant `docs/agents/*`, and `.reposcry/AI_CONTEXT.md` when available.
+2. **Investigation & Trace**:
+   - Locate the files/lines mentioned in the brief.
+   - Trace the data flow related to the problem/proposal.
+   - Search for "Impact Surface": Who else uses or depends on these components?
+3. **Optional RepoScry graph pass**: if `reposcry` is available, use it to ground architecture and blast radius. Before relying on it, ensure the bundled bootstrap/context helper has kept `.reposcry/` ignored and untracked. Use commands such as:
+   - `reposcry --repo . get_architecture_overview --format json`
+   - `reposcry --repo . query_graph "callers_of <symbol>"`
+   - `reposcry --repo . query_graph "tests_for <symbol>"`
+   - `reposcry --repo . get_impact_radius <symbol> --depth 4`
+   Proceed normally when RepoScry is absent.
+4. **Cross-check**: Compare findings against docs, ADRs, and repo patterns.
+5. **Relentless Interview**:
+   - Ask one question at a time to resolve contradictions or clarify ambiguity.
+   - Challenge the brief if the code behaves differently than described.
+6. **Log Evidence**: Append resolved decisions, technical findings, edge cases, and constraints to `[GRILL]`.
+7. **Log Activity**: Append a timestamped summary of the grilling session to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`).
+8. **Context Curation**: If a durable term/rule emerges, propose or apply a concise `docs/agents/*` update.
+
+## Output contract
+End with:
+- **Investigation Summary**: (Technical findings & Impact Surface)
+- **Resolved decisions**
+- **Remaining blockers**
+- **Docs updates proposed/applied**
+- **Next step**: `/plan` only when the brief is stable and code reality is verified.

package/implement/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: 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.
+---
+
+# Skill: implement
+
+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.
+- 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.
+- NEVER: commit a Jira-tracked task with a Jira-less subject; if the active task source is `jira`, the commit subject MUST include the Jira key from `.workflow/active_task.json` (e.g. `fix(PROJ-123): ...`).
+- NEVER: hide the Jira key only in the commit body/footer when the task is Jira-tracked; the subject itself must carry the key.
+- NEVER: add `Signed-off-by`; only the human can certify DCO.
+- NEVER: freestyle PR/MR descriptions; use the Draft PR/MR body contract below.
+
+## Workflow
+1. Identify the first approved unchecked slice in `[PLAN]`.
+2. Move tracked task to **In Progress** only when implementation actually starts.
+3. **Mandatory Branch Check**: You MUST run the branch enforcement script before modifying any code.
+   - Use the absolute path if possible: `<skill_location>/scripts/enforce-branch.sh`.
+   - This script prevents accidental implementation on `main`/`master`.
+   - If the script switches branches, you must update the `[META]` section of `WORK.md` to reflect the new branch name.
+   - If the script fails, STOP and ask the human for help. Do not proceed with code changes.
+4. Optional RepoScry blast-radius pass: if `reposcry` is available, inspect impact before wide edits (`reposcry --repo . get_impact_radius <symbol> --depth 4` or related graph queries). Continue normally when RepoScry is absent.
+5. Implement test-first where practical; otherwise document why not in `[LOG]`.
+6. After each edit batch, if the bundled `../scripts/reposcry-refresh.sh` helper is present and `reposcry-update` is installed, run it. RepoScry refresh failure should not block implementation. Never stage or commit `.reposcry/`; it is generated cache. `.reposcryignore` may be committed only after review as indexing policy.
+7. Run the slice verification command and available quality gates.
+8. Commit with a Conventional Commit header and `Assisted-by: [AGENT]:[MODEL] [tools]` footer (populating the agent name and model ID from the current session context).
+   - For Jira-tracked tasks, the header MUST include the Jira key in the scope position: `fix(PROJ-123): ...` or `feat(PROJ-123): ...`.
+   - If release-note tooling also needs the key in parsed text, add `Refs: PROJ-123` in the body/footer as well.
+9. Push and open a Draft PR/MR with `gh` or `glab` when a remote exists.
+   - For Jira-tracked tasks, the PR/MR title MUST also include the Jira key and should mirror the commit subject.
+10. Use a temporary body file (`--body-file` or API equivalent) for PR/MR descriptions to avoid shell quoting and markdown escaping bugs.
+11. Append summary, commit hash, and PR/MR link to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`).
+
+## Draft PR/MR body contract
+
+Generate the Draft PR/MR body from the active `WORK.md`, implemented slice, commit(s), and verification evidence. If a section has no evidence yet, say so explicitly; do not omit the section.
+
+Use this exact section order:
+
+```md
+## Summary
+- <one to three bullets describing what changed and why>
+
+## Scope
+- <files/areas changed>
+- <notable behavior or workflow changes>
+
+## Verification
+- [x] <command or check that passed>
+- [ ] <manual check still needed, if any>
+
+## Risk / Rollback
+- Risk: <main regression or operational risk, or "Low" with reason>
+- Rollback: <revert commit, disable feature, or restore previous behavior>
+
+## RPIV Task
+- Task: `<source>:<id>`
+- Slice: <slice name>
+- Branch: `<branch>`
+
+## Human Review Checklist
+- [ ] Review changed files for repo conventions.
+- [ ] Confirm verification evidence is sufficient.
+- [ ] Confirm no secrets, local-only paths, or scratch artifacts are included.
+```
+
+### PR/MR body rules
+- Keep the body concise and reviewer-focused.
+- Prefer bullets over paragraphs.
+- Include verification commands exactly as run.
+- Include failed or skipped verification as explicit unchecked items with reasons.
+- Include known risks instead of saying “none” unless risk is genuinely low and explained.
+- Include the RPIV task id and slice name so review can trace back to `WORK.md`.
+- Do not include private notes, secrets, environment variable values, or local scratch paths.
+
+### GitHub example
+```bash
+body_file=$(mktemp)
+cat > "$body_file" <<'EOF'
+## Summary
+- ...
+
+## Scope
+- ...
+
+## Verification
+- [x] ...
+
+## Risk / Rollback
+- Risk: ...
+- Rollback: ...
+
+## RPIV Task
+- Task: `local:setup-v2`
+- Slice: Slice 1 — Idempotent `/triage` helper
+- Branch: `feat/setup-v2`
+
+## Human Review Checklist
+- [ ] Review changed files for repo conventions.
+- [ ] Confirm verification evidence is sufficient.
+- [ ] Confirm no secrets, local-only paths, or scratch artifacts are included.
+EOF
+
+gh pr create --draft --title "<title>" --body-file "$body_file"
+```
+
+### GitLab example
+```bash
+body_file=$(mktemp)
+cat > "$body_file" <<'EOF'
+## Summary
+- ...
+EOF
+
+glab mr create --draft --title "<title>" --description "$(cat "$body_file")"
+```
+
+Prefer true body-file flags when available. If the CLI only supports a string description, write the body to a temp file first and read it from there to avoid inline shell quoting mistakes.
+
+## Output contract
+End with:
+- **Slice implemented**
+- **Verification run**
+- **Commit**
+- **Draft PR/MR**
+- **Human review required**