docs(agent): PR body comment-only frustration chain + Layer 0 rules/hooks

Author: diazMelgarejo

.agent/memory/working/PR_BODY_COMMENT_ONLY_FRUSTRATION_CHAIN_2026-08-01.md

@@ -0,0 +1,62 @@
+# PR body frustration chain — comment-only doctrine (2026-08-01)
+
+> **Status:** active Layer 0 prohibition on Cursor agents  
+> **Open PR:** [#319](https://github.com/diazMelgarejo/Perpetua-Tools/pull/319) (`cursor/guard-audit-hardening-f559`)  
+> **Canonical ledger:** `orama-system/bin/orama-system/references/pr-body-anti-clobber-incident-ledger.md`
+
+## User intent (spirit of the plan)
+
+Stop agents from **automatically rewriting PR summaries**. Progress belongs in **comments**,
+not in the description field. The description is a historical record; agents kept treating
+turn-end "update the PR" as permission to replace the whole body with the latest paragraph.
+
+If a human **explicitly** authorizes a body edit, append-only rules still apply — never
+delta-only clobber.
+
+## Frustration chain (this wave)
+
+| Step | What happened | Why it hurt |
+| ---- | ------------- | ----------- |
+| 1 | PT #314 merged guard manifest; CodeRabbit nitpicks left open | Drift between "merged" and "done" |
+| 2 | PR #315 falsely claimed to supersede #314 | Would have removed tests — duplicate PR trap |
+| 3 | Blind orama→PT `sync-attribution-guard-scripts.sh` risked clobbering PT hardening | Anti-clobber divergence guard born |
+| 4 | PT #319 opened as **one PR** for guard wave | Correct consolidation |
+| 5 | Agent `ManagePullRequest update_pr` with **delta-only** body on #319 | Erased original Summary + template sections |
+| 6 | User asked if PR bodies were clobbered across 3 repos | PT #319 yes; orama #255 / AC #26 no |
+| 7 | Integrative restore + Layer 7 hooks (append-only) | Still not enough — agents bypass by habit |
+| 8 | **Layer 0** — comment only, hooks block **all** body writes | Top prohibition; override → Layers 1–6 |
+
+## Layer 0 — what agents do now
+
+| Do | Never (automatic) |
+| -- | ----------------- |
+| `ManagePullRequest post_comment` | `update_pr` with `body=` |
+| `gh pr comment` | `gh pr edit`, `append-pr-body.sh` |
+
+## Human override
+
+```bash
+export CURSOR_PR_BODY_HUMAN_OVERRIDE_ACK=1
+```
+
+Then: READ → BACKUP → MERGE → WRITE (`append-pr-body.sh` or `gh pr edit --body-file`).
+
+## Enforcement stack
+
+1. `.cursor/rules/pr-body-comment-only.mdc` (alwaysApply, top)
+2. `.cursor/rules/append-only-pr-body.mdc` (override only)
+3. Cursor hooks: `beforeSubmitPrompt`, `preToolUse`, `beforeMCPExecution`, `beforeShellExecution`
+4. `scripts/cursor/hooks/pr-body-guard-core.py` (single decision core)
+5. Hookify: `.claude/hookify.pr-body-comment-only.local.md`
+6. `remind-pr-body-append-only.sh` at push time
+7. CI: `verify-pr-body-not-clobbered.sh`
+
+## Related memory on this branch
+
+- `GUARD_SYNC_EPIC_SAGA_COMPLETION_2026-08-01.md`
+- `GUARD_SYNC_DIVERGENCE_GUARD_2026-08-01.md`
+- `PR_BODY_ANTI_CLOBBER_ENFORCEMENT_PLAN.md`
+
+## Merge order (unchanged)
+
+PT #319 → orama #255 → AlphaClaw #26

.cursor/rules/append-only-pr-body.mdc

@@ -1,60 +1,32 @@
 ---
-description: Append-only PR body updates — never clobber existing PR descriptions (READ → backup → merge → write)
+description: Append-only PR body updates when human override authorizes a body edit (Layers 1–6)
 alwaysApply: true
 ---
 
-# Append-only PR body workflow
+# Append-only PR body workflow (Layers 1–6 — after human override only)
 
-`ManagePullRequest update_pr`, `gh pr edit`, and GitHub's API **replace the entire PR body** when `body` is set. Passing only the latest follow-up paragraph deletes the original Summary and any CodeRabbit release notes.
+**Layer 0 applies first:** `.cursor/rules/pr-body-comment-only.mdc` — Cursor agents
+**comment only** by default. This file governs body writes **only** when the human
+set `CURSOR_PR_BODY_HUMAN_OVERRIDE_ACK=1` in the current session.
 
-**NEVER** use `ManagePullRequest update_pr` with delta-only `body=`. Use `append-pr-body.sh` instead.
+`ManagePullRequest update_pr`, `gh pr edit`, and GitHub's API **replace the entire PR body**
+when `body` is set. Passing only the latest follow-up paragraph deletes the original Summary.
 
 **Canonical skill:** `bin/orama-system/skills/cursor-pr-body/SKILL.md`  
 **Incident ledger:** `bin/orama-system/references/pr-body-anti-clobber-incident-ledger.md`  
-**Canonical script:** `scripts/cursor/append-pr-body.sh`  
-**Curriculum:** `bin/orama-system/cidf/references/integrative-editing-examples.md` §1
+**Canonical script:** `scripts/cursor/append-pr-body.sh`
 
-## Non-negotiable workflow
+## Non-negotiable workflow (human-authorized body edit only)
 
 | Step | Action |
-|------|--------|
+| ---- | ------ |
 | 1. **READ** | `gh pr view <N> --repo <owner/repo> --json body --jq .body` |
 | 2. **BACKUP** | Save to `.git/pr-body-backups/<repo-slug>-pr<N>-<UTC-timestamp>.md` |
-| 3. **MERGE** | Keep original `## Summary` and scope at top; append `## Follow-up: …` blocks chronologically; preserve CodeRabbit auto-generated sections and Cursor metadata below unchanged |
-| 4. **WRITE** | Full merged body only — never delta-only |
+| 3. **MERGE** | Keep original `## Summary`; append `## Follow-up:` chronologically |
+| 4. **WRITE** | `append-pr-body.sh` or `gh pr edit --body-file` with **full** merged body |
 
-## Preferred write path
+## Forbidden (even with human override)
 
-```bash
-bash scripts/cursor/append-pr-body.sh <owner/repo> <pr-number> \
-  --title "Follow-up: <short title>" \
-  --file follow-up.md
-```
-
-Or: edit the backup copy integratively, then `gh pr edit <N> --repo <owner/repo> --body-file merged-body.md`.
-
-## Tool-specific constraints
-
-| Tool | Rule |
-|------|------|
-| `append-pr-body.sh` | Inserts before `<!-- CURSOR_AGENT_PR_BODY_END -->` or CodeRabbit marker; aborts if body changed since read |
-| `ManagePullRequest update_pr` | **Avoid.** Agent-managed PRs only; if unavoidable, pass **full** integrative merged body — never delta-only. Prefer `append-pr-body.sh` |
-| `gh pr edit` | Requires token with `updatePullRequest` scope; same full-body rule applies |
-
-## Forbidden
-
-- `update_pr` / `gh pr edit` with `body=` containing only the latest paragraph or CI delta
-- Rewriting or deleting the original Summary to match a side quest (aguara, harmonization, etc.)
+- Delta-only `body=` containing only the latest paragraph or CI delta
 - Skipping backup because "it's a small follow-up"
-- Hand-editing CodeRabbit `<!-- release notes by coderabbit.ai -->` blocks unless explicitly fixing a factual error
-
-## When to append
-
-- Stack harmonization / rebase notes after resolving conflicts
-- CodeRabbit or human review fixes applied in a follow-up commit
-- CI failure root cause + verification command output
-- Post-merge integration status across a PR chain (#244 → #245 → …)
-
-## Insertion order
-
-New `## Follow-up:` blocks go **below** the original agent summary and **above** CodeRabbit auto-generated release notes (when present). Chronological order — never reorder prior follow-ups.
+- Reordering or deleting prior follow-ups

.cursor/rules/pr-body-comment-only.mdc

@@ -0,0 +1,47 @@
+---
+description: >-
+  Layer 0 — Cursor agents never auto-change PR descriptions. Comment only
+  (post_comment / gh pr comment). Body writes require explicit human override.
+alwaysApply: true
+---
+
+# Layer 0 — PR body comment-only (Cursor agents)
+
+**This rule is the top prohibition.** Hooks, hookify, skills, and CI layers below
+cannot be bypassed by habit, turn-end checklists, or "small follow-up" reasoning.
+
+## Positive instructions (what to do)
+
+| Situation | Required action |
+| --------- | ---------------- |
+| Report progress on an open PR | `ManagePullRequest post_comment` or `gh pr comment` |
+| CI failed / fix landed | Post a **comment** with job URL, root cause, verification command |
+| Stack harmonization / rebase | Post a **comment** with base SHA and commits preserved |
+| User asks "update the PR" | **Comment only** unless they explicitly authorize a body edit |
+| End of turn with code pushed | Push commits; **comment** on PR if status changed — do **not** edit description |
+
+## Negative instructions (never do automatically)
+
+- `ManagePullRequest update_pr` with `body=` on an **existing** PR
+- `gh pr edit` with `--body` or `--body-file`
+- `bash scripts/cursor/append-pr-body.sh` …
+- `gh api` PATCH/PUT that changes pull request `body` or description
+- Replacing, shortening, or "refreshing" the Summary to match the latest side quest
+- Turn-end "update PR before summary" that mutates the description field
+
+## Human override (rare)
+
+Only when the **human explicitly** authorizes a body edit in the current turn:
+
+```bash
+export CURSOR_PR_BODY_HUMAN_OVERRIDE_ACK=1
+```
+
+Then **Layers 1–6 still apply** (append-only, READ→BACKUP→MERGE→WRITE). Delta-only
+writes remain forbidden. See `.cursor/rules/append-only-pr-body.mdc`.
+
+## Enforcement
+
+- Cursor hooks: `preToolUse` (ManagePullRequest), `beforeMCPExecution`, `beforeShellExecution`, `beforeSubmitPrompt`
+- Skill: `bin/orama-system/skills/cursor-pr-body/SKILL.md`
+- Incident ledger: `bin/orama-system/references/pr-body-anti-clobber-incident-ledger.md`

scripts/cursor/hooks/before-mcp-pr-body-guard.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# preToolUse / beforeMCPExecution — Layer 0: never auto-mutate PR bodies (comment only).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=pr-body-backup-lib.sh
+source "$SCRIPT_DIR/pr-body-backup-lib.sh"
+
+input="$(cat)"
+decision="ALLOW"
+deny_msg=""
+
+while IFS= read -r line; do
+  case "$line" in
+    BACKUP\|*)
+      repo="${line#BACKUP|}"
+      pr="${repo##*|}"
+      repo="${repo%|*}"
+      pr_body_backup_if_needed "$repo" "$pr" "mcp-preflight"
+      ;;
+    DENY\|*)
+      decision="DENY"
+      deny_msg="${line#DENY|}"
+      ;;
+    DENY)
+      decision="DENY"
+      ;;
+  esac
+done < <(python3 "$SCRIPT_DIR/pr-body-guard-core.py" manage_pr <<<"$input")
+
+if [[ "$decision" == "DENY" ]]; then
+  deny_msg="${deny_msg:-Layer 0: comment only — never auto-change PR body.}"
+  python3 - "$deny_msg" <<'PY'
+import json, sys
+msg = sys.argv[1]
+print(json.dumps({
+    "permission": "deny",
+    "agent_message": msg,
+    "user_message": "Cursor agent blocked from changing PR description. Use post_comment only.",
+}))
+PY
+  exit 0
+fi
+
+printf '%s\n' '{"permission":"allow"}'

scripts/cursor/hooks/before-shell-pr-body-guard.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# beforeShellExecution — Layer 0: block gh pr edit / append-pr-body; allow gh pr comment.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=pr-body-backup-lib.sh
+source "$SCRIPT_DIR/pr-body-backup-lib.sh"
+
+input="$(cat)"
+decision="ALLOW"
+deny_msg=""
+
+while IFS= read -r line; do
+  case "$line" in
+    BACKUP\|*)
+      repo="${line#BACKUP|}"
+      pr="${repo##*|}"
+      repo="${repo%|*}"
+      pr_body_backup_if_needed "$repo" "$pr" "shell-preflight"
+      ;;
+    DENY\|*)
+      decision="DENY"
+      deny_msg="${line#DENY|}"
+      ;;
+    DENY)
+      decision="DENY"
+      ;;
+  esac
+done < <(python3 "$SCRIPT_DIR/pr-body-guard-core.py" shell <<<"$input")
+
+if [[ "$decision" == "DENY" ]]; then
+  deny_msg="${deny_msg:-Layer 0: comment only — never auto-change PR body.}"
+  python3 - "$deny_msg" <<'PY'
+import json, sys
+msg = sys.argv[1]
+print(json.dumps({
+    "permission": "deny",
+    "agent_message": msg,
+    "user_message": "Cursor agent blocked from changing PR description. Use gh pr comment.",
+}))
+PY
+  exit 0
+fi
+
+printf '%s\n' '{"permission":"allow"}'

scripts/cursor/hooks/before-submit-pr-body-reminder.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# beforeSubmitPrompt — inject Layer 0 reminder so agents cannot "forget" between turns.
+set -euo pipefail
+
+input="$(cat)"
+python3 - "$input" <<'PY'
+import json, sys
+
+raw = sys.argv[1]
+try:
+    data = json.loads(raw) if raw.strip() else {}
+except json.JSONDecodeError:
+    data = {}
+
+prompt = str(data.get("prompt") or data.get("user_message") or "")
+lower = prompt.lower()
+triggers = (
+    "update_pr", "pr body", "pull request", "managepullrequest",
+    "append-pr-body", "gh pr edit", "pr description", "pr summary",
+)
+if not any(t in lower for t in triggers):
+    print(json.dumps({"continue": True}))
+    sys.exit(0)
+
+print(json.dumps({
+    "continue": True,
+    "additional_context": (
+        "LAYER-0 PR BODY RULE (Cursor agents): NEVER automatically change an existing "
+        "PR description. Use post_comment / gh pr comment ONLY. "
+        "ManagePullRequest update_pr with body=, gh pr edit, and append-pr-body.sh are "
+        "BLOCKED by hooks unless the human set CURSOR_PR_BODY_HUMAN_OVERRIDE_ACK=1 — "
+        "then append-only rules still apply (no delta-only writes)."
+    ),
+}))
+PY

scripts/cursor/hooks/pr-body-backup-lib.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# pr-body-backup-lib.sh — shared READ→BACKUP helpers for Cursor PR-body hooks.
+# Source from hook scripts; do not execute directly.
+set -euo pipefail
+
+pr_body_backup_dir() {
+  local git_common_dir
+  if ! git_common_dir="$(git rev-parse --git-common-dir 2>/dev/null)"; then
+    printf '%s\n' "${TMPDIR:-/tmp}"
+    return 0
+  fi
+  if [[ "$git_common_dir" != /* ]]; then
+    git_common_dir="$(git rev-parse --show-toplevel 2>/dev/null)/$git_common_dir"
+  fi
+  printf '%s/pr-body-backups\n' "$(cd "$git_common_dir" && pwd)"
+}
+
+pr_body_backup_if_needed() {
+  local repo_slug="$1"
+  local pr_number="$2"
+  local reason="${3:-preflight-read}"
+
+  if ! command -v gh >/dev/null 2>&1; then
+    return 0
+  fi
+  if [[ -z "$repo_slug" || -z "$pr_number" ]]; then
+    return 0
+  fi
+
+  local backup_dir body ts safe_slug path
+  backup_dir="$(pr_body_backup_dir)"
+  mkdir -p "$backup_dir"
+  body="$(gh pr view "$pr_number" --repo "$repo_slug" --json body --jq .body 2>/dev/null || true)"
+  [[ -n "$body" ]] || return 0
+
+  ts="$(date -u +%Y%m%dT%H%M%SZ)"
+  safe_slug="${repo_slug//\//-}"
+  path="${backup_dir}/${safe_slug}-pr${pr_number}-${ts}-${reason}.md"
+  printf '%s\n' "$body" >"$path"
+  printf 'PR-BODY-BACKUP: %s (%s)\n' "$path" "$reason" >&2
+}