@pareto4/pp-core 1.7.1 → 1.8.0

package/pareto-skills/_shared/pp-claude-md-protocol.md

@@ -0,0 +1,306 @@
+<!--
+  pp-claude-md-protocol.md
+
+  Canonical pp-core ↔ GitHub protocol injected into a project's CLAUDE.md.
+
+  Used by:
+    - pareto-build-handoff (Step 6b: CLAUDE.md update)
+    - pareto-push-issues   (Step 5.5: CLAUDE.md injection)
+
+  To inject: append the block below `## GitHub Board Sync` (if a section of
+  that name already exists, replace it — idempotent).
+
+  Single source of truth — edit here, not in the skills. Every repo that
+  runs build-handoff or push-issues gets the same protocol.
+-->
+
+## GitHub Board Sync
+
+Requirements are tracked as GitHub issues on a project board. The mapping
+between pp-core requirement IDs (EPIC-xxx, US-xxx, FR-xxx) and GitHub issue
+numbers lives in `.planning/github-issues.json`.
+
+**Status flow:**
+
+```
+Backlog → Discuss → Planned → In Progress → Verification → PR Raised → Done
+```
+
+Every phase runs on its own branch and merges to `main` via a pull request
+after verification passes. Stories only close when their phase PR is merged.
+
+### Per-phase lifecycle
+
+**1. Phase starts (executing begins)**
+
+Create a branch from `main` named `phase/{N}-{slug}` (slug from ROADMAP.md
+phase title, kebab-case). All phase commits — code AND `.planning/` artifacts
+— land on this branch.
+
+```bash
+git checkout main && git pull
+git checkout -b "phase/${N}-${SLUG}"
+```
+
+Move each story issue covered by the phase to **In Progress**:
+
+```bash
+gh issue edit {number} --add-label "in-progress,phase:{N}" \
+  --remove-label "verification" -R {repo}
+```
+
+Also set the `Phase` custom field on the board item to the phase number.
+
+**2. Phase implementation complete (SUMMARY.md written)**
+
+Push the branch (first push uses `-u origin HEAD`) and move the stories to
+**Verification**:
+
+```bash
+git push -u origin HEAD
+gh issue edit {number} --add-label "verification" \
+  --remove-label "in-progress" -R {repo}
+```
+
+**3. Verification passes (VERIFICATION.md result = PASS)**
+
+Open a pull request from the phase branch to `main`. The PR body MUST use
+`Closes #N` for every story issue so GitHub auto-closes them on merge.
+
+```bash
+PR_BODY=$(cat <<EOF
+# Phase ${N}: ${PHASE_TITLE}
+
+## Summary
+${SUMMARY_FROM_SUMMARY_MD}
+
+## Requirements delivered
+Closes #${ISSUE1}  — ${US_ID_1}: ${STORY_TITLE_1}
+Closes #${ISSUE2}  — ${US_ID_2}: ${STORY_TITLE_2}
+
+## Verification
+VERIFICATION.md result: PASS
+- ${KEY_OUTCOMES}
+
+## Phase artifacts
+- \`.planning/phases/${N}-${SLUG}/PLAN.md\`
+- \`.planning/phases/${N}-${SLUG}/SUMMARY.md\`
+- \`.planning/phases/${N}-${SLUG}/VERIFICATION.md\`
+
+---
+Generated by pp-core phase execution.
+EOF
+)
+
+gh pr create \
+  --base main \
+  --head "phase/${N}-${SLUG}" \
+  --title "Phase ${N}: ${PHASE_TITLE}" \
+  --body "$PR_BODY" \
+  --label "phase:${N}"
+```
+
+**Do not close the story issues at this step.** They stay in Verification
+until the PR merges. Keeping them open until merge is what makes the board
+reflect *merged* reality, not just *verified* intent.
+
+If verification fails: fix the code on the same phase branch, re-run
+verification, update the PR (it auto-updates from new commits). No new
+branch.
+
+**4. PR merged**
+
+GitHub auto-closes linked issues. The sync protocol then reconciles:
+
+```bash
+# Sync loop — run after merge (or via /pareto-sync-board)
+gh issue edit {number} --remove-label "in-progress,verification" -R {repo}
+```
+
+Update `.planning/github-issues.json`: set each story's `status` to `"Done"`
+and each EPIC's `status` based on whether all its stories are now closed.
+
+If the merged phase closed ALL stories under an EPIC, also close the EPIC
+issue with a delivery note:
+
+```bash
+gh issue close {epic_number} -R {repo} \
+  -c "All stories delivered across phases {list}."
+```
+
+### Status map for .planning/github-issues.json
+
+```json
+"status_map": {
+  "Backlog":    "Backlog",
+  "discussing": "Discuss",
+  "planned":    "Planned",
+  "executing":  "In Progress",
+  "verifying":  "Verification",
+  "pr_open":    "PR Raised",
+  "complete":   "Done"
+}
+```
+
+### Filtered code-only PRs (optional)
+
+If the team wants PR diffs without `.planning/` noise, run `/pp-pr-branch`
+after Step 3 to produce a filtered branch. The filtered branch becomes the
+PR head instead of `phase/{N}-{slug}`. The original phase branch stays as
+the auditable work record.
+
+### MANDATORY: Board sync after pp-core phase transitions
+
+**These instructions are project-level overrides.** When `.planning/github-issues.json`
+exists, you MUST run the sync script and issue updates at each lifecycle transition
+below. Sync is non-blocking — failures must never stop the pp-core workflow (always
+append `|| true`).
+
+**After `/pp-discuss-phase` completes** (CONTEXT.md written):
+
+Move stories to **Discuss** and comment on each with key decisions:
+
+```bash
+[ -f ".planning/github-issues.json" ] && bash "$HOME/.claude/skills/pareto/_shared/sync-phase-status.sh" "${PHASE_NUMBER}" "Discuss" 2>&1 || true
+```
+
+Comment on each story issue for this phase with key decisions that affect it:
+
+```bash
+if [ -f ".planning/github-issues.json" ]; then
+  REPO=$(jq -r '.repo' .planning/github-issues.json)
+  # For each story in the phase, add a comment with relevant decisions from CONTEXT.md
+  jq -r --argjson p "${PHASE_NUMBER}" '.issues | to_entries[] | select(.value.phase == $p and .value.type == "story") | "\(.key) \(.value.number)"' .planning/github-issues.json | while read REQ_ID ISSUE_NUM; do
+    gh issue comment "$ISSUE_NUM" -R "$REPO" --body "## Phase ${PHASE_NUMBER} — Context gathered
+
+Decisions from \`/pp-discuss-phase\` that affect ${REQ_ID}:
+
+${DECISIONS_RELEVANT_TO_THIS_STORY}
+
+---
+_Auto-posted by pp-core discuss-phase_" 2>/dev/null || true
+  done
+fi
+```
+
+Replace `${DECISIONS_RELEVANT_TO_THIS_STORY}` with the actual decisions from CONTEXT.md
+that are relevant to each story. Extract from `<decisions>` section.
+
+**After `/pp-plan-phase` completes planning** (plans pass all gates, STATE.md updated):
+
+Move stories to **Planned** and comment with plan assignment:
+
+```bash
+[ -f ".planning/github-issues.json" ] && bash "$HOME/.claude/skills/pareto/_shared/sync-phase-status.sh" "${PHASE_NUMBER}" "Planned" 2>&1 || true
+```
+
+Then comment on each story issue with which plan covers it:
+
+```bash
+if [ -f ".planning/github-issues.json" ]; then
+  REPO=$(jq -r '.repo' .planning/github-issues.json)
+  # For each story, find which PLAN.md references its requirement ID and comment
+  jq -r --argjson p "${PHASE_NUMBER}" '.issues | to_entries[] | select(.value.phase == $p and .value.type == "story") | "\(.key) \(.value.number)"' .planning/github-issues.json | while read REQ_ID ISSUE_NUM; do
+    gh issue comment "$ISSUE_NUM" -R "$REPO" --body "## Phase ${PHASE_NUMBER} — Planned
+
+Covered by: \`${PLAN_FILE}\` (Wave ${WAVE})
+Key tasks: ${TASK_SUMMARY}
+
+---
+_Auto-posted by pp-core plan-phase_" 2>/dev/null || true
+  done
+fi
+```
+
+Replace `${PLAN_FILE}`, `${WAVE}`, and `${TASK_SUMMARY}` with actual values from the
+PLAN.md that contains this story's requirement ID in its `requirements` frontmatter field.
+
+**After `/pp-execute-phase` begins execution** (branch created, STATE.md shows phase active):
+
+```bash
+[ -f ".planning/github-issues.json" ] && bash "$HOME/.claude/skills/pareto/_shared/sync-phase-status.sh" "${PHASE_NUMBER}" "In Progress" --label-add "in-progress" --label-remove "verification" 2>&1 || true
+```
+
+**After `/pp-execute-phase` verification passes** (VERIFICATION.md written, ROADMAP.md updated):
+
+Move stories to **Verification**:
+
+```bash
+[ -f ".planning/github-issues.json" ] && bash "$HOME/.claude/skills/pareto/_shared/sync-phase-status.sh" "${PHASE_NUMBER}" "Verification" --label-add "verification" --label-remove "in-progress" 2>&1 || true
+```
+
+**After PR is created** (push branch, create PR):
+
+Push the branch and create a PR, then move stories to **PR Raised**:
+
+```bash
+# 1. Push the phase branch
+git push -u origin HEAD 2>&1 || true
+```
+
+```bash
+# 2. Build PR body with Closes links for every story in this phase
+if [ -f ".planning/github-issues.json" ]; then
+  REPO=$(jq -r '.repo' .planning/github-issues.json)
+  CLOSES_LINES=$(jq -r --argjson p "${PHASE_NUMBER}" '
+    .issues | to_entries[]
+    | select(.value.phase == $p and .value.type == "story")
+    | "Closes #\(.value.number) — \(.key): \(.value.title)"
+  ' .planning/github-issues.json)
+
+  gh pr create \
+    --base main \
+    --head "phase/${PHASE_NUMBER}-${PHASE_SLUG}" \
+    --title "Phase ${PHASE_NUMBER}: ${PHASE_NAME}" \
+    --body "$(cat <<EOF
+## Summary
+
+${SUMMARY_FROM_VERIFICATION_MD}
+
+## Requirements delivered
+
+${CLOSES_LINES}
+
+## Verification
+
+VERIFICATION.md result: PASS
+
+## Phase artifacts
+
+- \`.planning/phases/${PADDED_PHASE}-${PHASE_SLUG}/PLAN.md\`
+- \`.planning/phases/${PADDED_PHASE}-${PHASE_SLUG}/SUMMARY.md\`
+- \`.planning/phases/${PADDED_PHASE}-${PHASE_SLUG}/VERIFICATION.md\`
+
+---
+Generated by pp-core phase execution.
+EOF
+)" 2>/dev/null || true
+fi
+```
+
+```bash
+# 4. Move stories to PR Raised
+[ -f ".planning/github-issues.json" ] && bash "$HOME/.claude/skills/pareto/_shared/sync-phase-status.sh" "${PHASE_NUMBER}" "PR Raised" 2>&1 || true
+```
+
+Stories stay in **PR Raised** until the PR is merged. GitHub auto-closes
+the linked issues via `Closes #N`, which moves them to **Done** on the board.
+
+After PR merge, clean up labels:
+
+```bash
+[ -f ".planning/github-issues.json" ] && bash "$HOME/.claude/skills/pareto/_shared/sync-phase-status.sh" "${PHASE_NUMBER}" "Done" --label-remove "in-progress,verification" 2>&1 || true
+```
+
+If any sync is missed or the board drifts, use the recovery steps below.
+
+### Recovery
+
+If any step is missed, run `/pareto-sync-board` to reconcile. It:
+- Reads `.planning/STATE.md`, `ROADMAP.md`, and every phase directory
+- Checks `gh pr list --head phase/{N}-*` for PR state
+- Only closes stories whose phase PR shows state `MERGED`
+- Rewrites `github-issues.json` to match live board state
+
+If `.planning/github-issues.json` is missing entirely, run
+`/pareto-push-issues` to rebuild it from `.planning/REQUIREMENTS.md`.

package/pareto-skills/_shared/sync-phase-status.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# sync-phase-status.sh
+#
+# Move GitHub issues for a pp-core phase to a target board status.
+# Reads .planning/github-issues.json to find issues mapped to the phase,
+# then updates labels and board column.
+#
+# Used by pp-core workflows (plan-phase, execute-phase) at lifecycle transitions.
+# Non-blocking — failures are logged but never stop the pp-core workflow.
+#
+# Usage:
+#   bash sync-phase-status.sh <phase_number> <target_status> [--label-add X] [--label-remove Y]
+#
+# Examples:
+#   bash sync-phase-status.sh 4 "To Do"
+#   bash sync-phase-status.sh 4 "In Progress"   --label-add in-progress --label-remove verification
+#   bash sync-phase-status.sh 4 "Verification"  --label-add verification --label-remove in-progress
+#
+# Environment:
+#   GITHUB_ISSUES_JSON  — path to mapping file (default: .planning/github-issues.json)
+#
+# Exit code: always 0 (non-blocking). Errors go to stderr.
+
+set -uo pipefail
+
+PHASE="$1"
+TARGET_STATUS="$2"
+shift 2
+
+LABEL_ADD=""
+LABEL_REMOVE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --label-add)    LABEL_ADD="$2"; shift 2 ;;
+    --label-remove) LABEL_REMOVE="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+MAPPING="${GITHUB_ISSUES_JSON:-.planning/github-issues.json}"
+
+if [ ! -f "$MAPPING" ]; then
+  echo "sync-phase-status: no mapping file at $MAPPING — skipping board sync" >&2
+  exit 0
+fi
+
+# Extract repo and board info
+REPO=$(jq -r '.repo // empty' "$MAPPING" 2>/dev/null)
+BOARD_NUM=$(jq -r '.board.number // empty' "$MAPPING" 2>/dev/null)
+BOARD_OWNER=$(jq -r '.board.owner // empty' "$MAPPING" 2>/dev/null)
+
+if [ -z "$REPO" ]; then
+  echo "sync-phase-status: no repo in mapping file — skipping" >&2
+  exit 0
+fi
+
+# Get all issue numbers for this phase (stories only — EPICs are derived)
+ISSUE_NUMBERS=$(jq -r --arg p "$PHASE" '
+  [.issues | to_entries[]
+   | select(.value.phase == ($p | tonumber) and .value.type == "story")
+   | .value.number] | .[]
+' "$MAPPING" 2>/dev/null)
+
+if [ -z "$ISSUE_NUMBERS" ]; then
+  echo "sync-phase-status: no stories mapped to phase $PHASE — skipping" >&2
+  exit 0
+fi
+
+COUNT=$(echo "$ISSUE_NUMBERS" | wc -l | tr -d ' ')
+echo "sync-phase-status: moving $COUNT stories for phase $PHASE → $TARGET_STATUS"
+
+# Update labels on each issue
+for NUM in $ISSUE_NUMBERS; do
+  LABEL_CMD="gh issue edit $NUM -R $REPO"
+  [ -n "$LABEL_ADD" ]    && LABEL_CMD="$LABEL_CMD --add-label $LABEL_ADD"
+  [ -n "$LABEL_REMOVE" ] && LABEL_CMD="$LABEL_CMD --remove-label $LABEL_REMOVE"
+
+  if [ -n "$LABEL_ADD" ] || [ -n "$LABEL_REMOVE" ]; then
+    eval "$LABEL_CMD" 2>/dev/null || echo "  warn: label update failed for #$NUM" >&2
+  fi
+done
+
+# Update board column (if board info available)
+if [ -n "$BOARD_NUM" ] && [ -n "$BOARD_OWNER" ]; then
+  # Resolve board project ID and Status field
+  PROJECT_ID=$(gh project view "$BOARD_NUM" --owner "$BOARD_OWNER" --format json --jq '.id' 2>/dev/null)
+
+  if [ -z "$PROJECT_ID" ]; then
+    echo "sync-phase-status: could not resolve project board — skipping column update" >&2
+    exit 0
+  fi
+
+  STATUS_FIELD_ID=$(gh project field-list "$BOARD_NUM" --owner "$BOARD_OWNER" --format json \
+    --jq '.fields[] | select(.name=="Status") | .id' 2>/dev/null)
+
+  OPTION_ID=$(gh project field-list "$BOARD_NUM" --owner "$BOARD_OWNER" --format json \
+    --jq ".fields[] | select(.name==\"Status\") | .options[] | select(.name==\"$TARGET_STATUS\") | .id" 2>/dev/null)
+
+  if [ -z "$STATUS_FIELD_ID" ] || [ -z "$OPTION_ID" ]; then
+    echo "sync-phase-status: could not resolve Status field or option '$TARGET_STATUS' — skipping column update" >&2
+    exit 0
+  fi
+
+  # Get all board items and match by issue number (--limit 200 to avoid default 30 cap)
+  ITEMS_JSON=$(gh project item-list "$BOARD_NUM" --owner "$BOARD_OWNER" --format json --limit 200 2>/dev/null)
+
+  for NUM in $ISSUE_NUMBERS; do
+    ITEM_ID=$(echo "$ITEMS_JSON" | jq -r --argjson n "$NUM" '
+      .items[] | select(.content.number == $n) | .id
+    ' 2>/dev/null)
+
+    if [ -n "$ITEM_ID" ] && [ "$ITEM_ID" != "null" ]; then
+      gh project item-edit \
+        --project-id "$PROJECT_ID" \
+        --id "$ITEM_ID" \
+        --field-id "$STATUS_FIELD_ID" \
+        --single-select-option-id "$OPTION_ID" 2>/dev/null \
+        && echo "  ✓ #$NUM → $TARGET_STATUS" \
+        || echo "  warn: board update failed for #$NUM" >&2
+    else
+      echo "  warn: #$NUM not found on board — skipping column update" >&2
+    fi
+  done
+fi
+
+# Update status in the mapping file
+jq --arg p "$PHASE" --arg s "$TARGET_STATUS" '
+  .issues |= with_entries(
+    if (.value.phase == ($p | tonumber) and .value.type == "story")
+    then .value.status = $s
+    else .
+    end
+  )
+  | .last_synced = (now | strftime("%Y-%m-%d"))
+' "$MAPPING" > "${MAPPING}.tmp" && mv "${MAPPING}.tmp" "$MAPPING"
+
+echo "sync-phase-status: done — $COUNT stories updated in mapping"
+exit 0