@pareto4/pp-core 1.7.1 → 1.8.1

package/commands/pp-build-handoff.md

@@ -1,6 +1,6 @@
 ---
 name: pp:build-handoff
-description: Transition a completed Pareto Discovery Sprint into a pp-core-ready project — synthesize sessions into .planning/ and wire cross-references.
+description: "[DEPRECATED] Alias for /pp-discovery-to-build; removed in a future major."
 argument-hint: "[--skip-validation] [--scaffold]"
 allowed-tools:
   - Read
@@ -18,6 +18,12 @@ requires: [new-project]
 **Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
 </runtime_note>
 
+<deprecation_note>
+**Deprecated:** `/pp-build-handoff` was renamed to `/pp-discovery-to-build` in v1.8.0. This
+alias runs the identical workflow and is kept for back-compat with v1.7.x. Prefer
+`/pp-discovery-to-build`; this alias will be removed in a future major release.
+</deprecation_note>
+
 <objective>
 Bridge the gap between a completed Pareto Discovery Sprint and pp-core execution.
 
@@ -32,7 +38,7 @@ execution, or `/pp-autonomous` to run all phases.
 </objective>
 
 <execution_context>
-@~/.claude/pp-core/workflows/build-handoff.md
+@~/.claude/pp-core/workflows/discovery-to-build.md
 </execution_context>
 
 <process>

package/commands/pp-discovery-to-build.md

@@ -0,0 +1,40 @@
+---
+name: pp:discovery-to-build
+description: Transition a completed Pareto Discovery Sprint into a pp-core-ready project.
+argument-hint: "[--skip-validation] [--scaffold]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [new-project]
+---
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API.
+</runtime_note>
+
+<objective>
+Bridge the gap between a completed Pareto Discovery Sprint and pp-core execution.
+
+Validates all 13 Discovery sessions are complete, synthesizes their outputs into a
+single structured handoff document, bootstraps the `.planning/` project state
+(PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json), and wires up
+cross-references so pp-core agents can trace every decision back to the Discovery
+session that produced it.
+
+**After this command:** pp-core is initialized. Run `/pp-plan-phase 1` to start
+execution, or `/pp-autonomous` to run all phases.
+</objective>
+
+<execution_context>
+@~/.claude/pp-core/workflows/discovery-to-build.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/commands/pp-ns-project.md

@@ -5,7 +5,7 @@ argument-hint: ""
 allowed-tools:
   - Read
   - Skill
-requires: [init, new-project, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
+requires: [init, new-project, discovery-to-build, build-handoff, new-milestone, complete-milestone, audit-milestone, milestone-summary, import, ingest-docs, profile-user, review-backlog]
 ---
 
 Route to the appropriate project / milestone skill based on the user's intent.
@@ -16,6 +16,8 @@ inline as part of `pp-audit-milestone`'s output.
 |---|---|
 | Initialize a project (canonical front door) | pp-init |
 | Start a new project | pp-new-project |
+| Hand off a completed Discovery Sprint into the build flow | pp-discovery-to-build |
+| (deprecated) Discovery→build handoff alias | pp-build-handoff |
 | Create a new milestone | pp-new-milestone |
 | Complete the current milestone | pp-complete-milestone |
 | Audit a milestone for issues | pp-audit-milestone |

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "PP Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads pp-core's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pareto4/pp-core",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "Pareto pp-core — The Pareto Project's AI-assisted engineering framework: meta-prompting, context engineering, and spec-driven development for AI coding agents.",
   "bin": {
     "pp-core": "bin/install.js",
@@ -13,6 +13,7 @@
     "pp-core",
     "assets",
     "agents",
+    "pareto-skills",
     ".claude-plugin",
     "gemini-extension.json",
     "GEMINI.md",

package/pareto-skills/_shared/create-project-board.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# create-project-board.sh
+#
+# Canonical GitHub Project v2 board creation for Pareto skills.
+# Creates (or updates) a project board for a given owner/repo with the
+# standard Pareto status columns, custom fields, and label palette.
+#
+# Used by:
+#   - pareto-project-setup (initial scaffold)
+#   - pareto-build-handoff (Discovery → pp-core handoff)
+#   - pareto-push-issues  (standalone requirements push)
+#
+# Single source of truth — edit here, not in the skills.
+#
+# Usage:
+#   source _shared/create-project-board.sh
+#   create_project_board "<owner>" "<project_title>" "<repo_slug>"
+#
+# Example:
+#   create_project_board "pareto-project" "my-app" "pareto-project/my-app"
+#
+# Environment variables honored:
+#   BOARD_OWNER_FALLBACK (default: "@me")  — used if org create fails
+#
+# Returns (via stdout, space-separated): <board_number> <owner>
+# Exits non-zero on fatal error.
+
+set -euo pipefail
+
+# -----------------------------------------------------------------------------
+# Canonical column schema
+# -----------------------------------------------------------------------------
+# Any change here propagates to every skill that sources this file.
+#
+# Status flow:
+#   Backlog → Discuss → Planned → In Progress → Verification → PR Raised → Done
+#
+# Each column maps 1:1 to a pp-core workflow step:
+#   Discuss      = /pp-discuss-phase (CONTEXT.md written)
+#   Planned      = /pp-plan-phase (PLAN.md created)
+#   In Progress  = /pp-execute-phase (branch active, executing)
+#   Verification = VERIFICATION.md written, tests passing
+#   PR Raised    = PR created from phase branch, awaiting merge
+#   Done         = PR merged, issue closed
+#
+PARETO_STATUS_OPTIONS='[
+  {name: "Backlog",       color: GRAY,   description: "Not yet started"},
+  {name: "Discuss",       color: PINK,   description: "Context gathering via /pp-discuss-phase"},
+  {name: "Planned",       color: BLUE,   description: "Plans created via /pp-plan-phase"},
+  {name: "In Progress",   color: YELLOW, description: "Executing via /pp-execute-phase"},
+  {name: "Verification",  color: ORANGE, description: "Verification passed — VERIFICATION.md written"},
+  {name: "PR Raised",     color: PURPLE, description: "PR created from phase branch, awaiting merge"},
+  {name: "Done",          color: GREEN,  description: "PR merged, issue closed"}
+]'
+
+# Label color palette for per-EPIC labels. Cycle through these in order.
+PARETO_EPIC_COLORS=(
+  "0E8A16" "1AA393" "D93F0B" "B44EFF"
+  "4A9EFF" "EF4444" "F5C842" "8B5CF6"
+)
+
+# -----------------------------------------------------------------------------
+# create_project_board <owner> <title> <owner/repo>
+# -----------------------------------------------------------------------------
+create_project_board() {
+  local OWNER="$1"
+  local TITLE="$2"
+  local REPO="$3"
+  local BOARD_NUM
+
+  # 1. Check for existing board matching title
+  BOARD_NUM=$(gh project list --owner "$OWNER" --format json 2>/dev/null \
+    | jq -r ".projects[] | select(.title==\"$TITLE\") | .number" || true)
+
+  if [ -z "$BOARD_NUM" ]; then
+    # 2. Try to create under the given owner
+    BOARD_NUM=$(gh project create --owner "$OWNER" --title "$TITLE" \
+      --format json 2>/dev/null | jq -r '.number' || true)
+
+    # 3. Fall back to personal projects if org creation failed
+    if [ -z "$BOARD_NUM" ]; then
+      OWNER="${BOARD_OWNER_FALLBACK:-@me}"
+      BOARD_NUM=$(gh project create --owner "$OWNER" --title "$TITLE" \
+        --format json | jq -r '.number')
+    fi
+
+    # 4. Link board to repo
+    gh project link "$BOARD_NUM" --owner "$OWNER" --repo "$REPO" >/dev/null
+  fi
+
+  # 5. Configure Status field with Pareto schema (idempotent — safe to re-run)
+  configure_status_field "$BOARD_NUM" "$OWNER"
+
+  # 6. Ensure custom fields exist (Priority, Sprint, Estimate, Phase)
+  ensure_custom_fields "$BOARD_NUM" "$OWNER"
+
+  echo "$BOARD_NUM $OWNER"
+}
+
+# -----------------------------------------------------------------------------
+# configure_status_field <board_num> <owner>
+# -----------------------------------------------------------------------------
+configure_status_field() {
+  local BOARD_NUM="$1"
+  local OWNER="$2"
+  local STATUS_FIELD_ID
+
+  STATUS_FIELD_ID=$(gh project field-list "$BOARD_NUM" --owner "$OWNER" --format json \
+    --jq '.fields[] | select(.name=="Status") | .id')
+
+  if [ -z "$STATUS_FIELD_ID" ]; then
+    echo "ERROR: Status field not found on board $BOARD_NUM" >&2
+    return 1
+  fi
+
+  gh api graphql -f query="
+    mutation {
+      updateProjectV2Field(input: {
+        fieldId: \"$STATUS_FIELD_ID\"
+        singleSelectOptions: $PARETO_STATUS_OPTIONS
+      }) {
+        projectV2Field { ... on ProjectV2SingleSelectField { id name } }
+      }
+    }
+  " >/dev/null
+}
+
+# -----------------------------------------------------------------------------
+# ensure_custom_fields <board_num> <owner>
+# -----------------------------------------------------------------------------
+ensure_custom_fields() {
+  local BOARD_NUM="$1"
+  local OWNER="$2"
+
+  # Priority (single-select)
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Priority" --data-type "SINGLE_SELECT" \
+    --single-select-options "Must Have,Should Have,Could Have,Won't Have" \
+    2>/dev/null || true
+
+  # Sprint (iteration — created manually in UI if needed)
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Sprint" --data-type "ITERATION" 2>/dev/null || true
+
+  # Estimate (number)
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Estimate" --data-type "NUMBER" 2>/dev/null || true
+
+  # Phase (text — pp-core phase number reference, e.g. "3" or "3.1")
+  gh project field-create "$BOARD_NUM" --owner "$OWNER" \
+    --name "Phase" --data-type "TEXT" 2>/dev/null || true
+}
+
+# -----------------------------------------------------------------------------
+# ensure_core_labels <owner/repo>
+# -----------------------------------------------------------------------------
+# Idempotent — uses --force so existing labels get updated.
+ensure_core_labels() {
+  local REPO="$1"
+
+  gh label create "epic"         -c "3E4B9E" -d "Epic — high-level feature group"       --force -R "$REPO"
+  gh label create "user-story"   -c "1D76DB" -d "User story"                            --force -R "$REPO"
+  gh label create "must-have"    -c "B60205" -d "Must Have — MVP required"              --force -R "$REPO"
+  gh label create "should-have"  -c "FBCA04" -d "Should Have — important"               --force -R "$REPO"
+  gh label create "could-have"   -c "0E8A16" -d "Could Have — nice to have"             --force -R "$REPO"
+  gh label create "in-progress"  -c "FBCA04" -d "Phase branch actively executing"       --force -R "$REPO"
+  gh label create "verification" -c "D93F0B" -d "In pp-core verification + PR review"       --force -R "$REPO"
+}
+
+# -----------------------------------------------------------------------------
+# create_epic_label <owner/repo> <slug> <epic_id> <epic_title> <index>
+# -----------------------------------------------------------------------------
+# Color cycles through PARETO_EPIC_COLORS by index.
+create_epic_label() {
+  local REPO="$1"
+  local SLUG="$2"
+  local EPIC_ID="$3"
+  local TITLE="$4"
+  local IDX="$5"
+  local COLOR="${PARETO_EPIC_COLORS[$((IDX % ${#PARETO_EPIC_COLORS[@]}))]}"
+
+  gh label create "epic:${SLUG}" -c "$COLOR" -d "${EPIC_ID}: ${TITLE}" --force -R "$REPO"
+}
+
+# -----------------------------------------------------------------------------
+# If sourced, functions above are exported to the caller. If executed directly,
+# run create_project_board with positional args.
+# -----------------------------------------------------------------------------
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  if [ $# -lt 3 ]; then
+    echo "Usage: $0 <owner> <title> <owner/repo>" >&2
+    exit 1
+  fi
+  create_project_board "$@"
+fi

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`.