@pareto4/pp-core 1.7.0 → 1.7.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "PP Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "pareto4",

package/commands/pp-build-handoff.md

@@ -0,0 +1,40 @@
+---
+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.
+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/build-handoff.md
+</execution_context>
+
+<process>
+Execute end-to-end.
+</process>

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.7.0",
+  "version": "1.7.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.0",
+  "version": "1.7.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",

package/pp-core/workflows/build-handoff.md

@@ -0,0 +1,598 @@
+<purpose>
+Transition a completed Pareto Discovery Sprint into a pp-core-ready project. Validates
+Discovery completion (13/13 sessions), synthesizes every session file into a single
+handoff document optimized for pp-core's new-project generators, initializes `.planning/`
+(config, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md), and wires cross-references
+so pp-core agents can trace decisions back to their originating Discovery session.
+
+This workflow is self-contained: it does NOT depend on any external Pareto skills bundle.
+The GitHub board sync step degrades gracefully when the GitHub CLI is absent.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<available_agent_types>
+Valid pp-core subagent types (use exact names — do not fall back to 'general-purpose'):
+- Explore — read-only parallel search agent, used here to read all Discovery session files
+</available_agent_types>
+
+<context>
+**Flags (parse from `$ARGUMENTS`):**
+- `--skip-validation` — Skip the Discovery completion check (use when sessions are intentionally incomplete)
+- `--scaffold` — After initialization, also scaffold lightweight application structure from the Session 5 tech stack
+
+**Prerequisites:**
+- A Pareto project with a `Discovery/` folder (created by `pareto-project-setup`)
+- Discovery Sprint sessions (ideally 13/13 completed)
+- pp-core installed and resolvable via the standard `pp_run` shim
+</context>
+
+<process>
+
+**Step 0: Resolve pp-tools**
+
+Resolve the `pp_run` helper before anything else. Every `pp_run` call below uses this shim.
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi
+```
+
+---
+
+**Step 1: Validate environment**
+
+```bash
+ls Discovery/_progress.md 2>/dev/null && echo "DISCOVERY_OK" || echo "DISCOVERY_MISSING"
+ls .planning/PROJECT.md 2>/dev/null && echo "PPCORE_EXISTS" || echo "PPCORE_FRESH"
+```
+
+**If DISCOVERY_MISSING:** Error and stop.
+```
+Error: No Discovery Sprint found in this project.
+
+Expected: Discovery/_progress.md
+Run /pareto-project-setup to create a new project with the Discovery framework,
+then complete the Discovery Sprint sessions before transitioning to build.
+```
+
+**If PPCORE_EXISTS:** Error and stop.
+```
+Error: pp-core is already initialized (.planning/PROJECT.md exists).
+
+If you want to re-initialize, remove .planning/ first.
+Or use /pp-progress to continue where you left off.
+```
+
+---
+
+**Step 2: Validate Discovery completion**
+
+Read `Discovery/_progress.md` and parse the Session Progress table. Count sessions by
+status: **Completed**, **In Progress**, **Not Started**.
+
+**If `--skip-validation` is present:** Skip to Step 3 with a note.
+
+**If all 13 completed:** Proceed to Step 3.
+
+**If some incomplete:** Present findings and ask how to proceed:
+
+```
+AskUserQuestion([
+  {
+    header: "Discovery Incomplete",
+    question: "Discovery Sprint is {completed}/13 complete. {in_progress} in progress, {not_started} not started.\n\nIncomplete sessions:\n{list of incomplete session names}\n\nProceeding with incomplete discovery means pp-core will have gaps in context. How would you like to proceed?",
+    multiSelect: false,
+    options: [
+      { label: "Proceed anyway", description: "Synthesize what we have — fill gaps during pp-core discuss phases" },
+      { label: "Complete discovery first", description: "Go back and finish the remaining sessions before transitioning" }
+    ]
+  }
+])
+```
+
+**If "Complete discovery first":** Exit with guidance:
+```
+Run /pp-discovery to see progress and continue with the next session.
+When all sessions are complete, run /pp-build-handoff again.
+```
+
+**If "Proceed anyway":** Continue to Step 3, noting which sessions are incomplete.
+
+---
+
+**Step 3: Read and synthesize Discovery outputs**
+
+This is the core value of the workflow. Read all Discovery artifacts and synthesize
+them into a single document optimized for the pp-core new-project generators.
+
+### 3a. Read all sources
+
+Read these files (skip any that don't exist):
+
+1. `Discovery/_context.md` — accumulated cross-session context (primary source)
+2. `Discovery/_progress.md` — session completion status
+3. All 13 session files in `Discovery/` — for detail not captured in `_context.md`
+4. The Project Definition document (glob for `*-Project-Definition.md` in root)
+5. `prototype/README.md` — if a prototype exists, note its state
+
+**Spawn an Explore agent to read all session files in parallel** and extract every
+populated Notes Template table, all Key Decisions tables, all Action Items, and any
+authored content that replaces placeholder text.
+
+### 3b. Synthesize into the handoff document
+
+Write `Discovery/_pp-handoff.md` with the structure below. The new-project generators
+use it to produce PROJECT.md, REQUIREMENTS.md, and ROADMAP.md, so the structure must
+map cleanly onto what those generators expect.
+
+```markdown
+# Discovery Sprint Synthesis — pp-core Handoff
+
+> Auto-generated from {completed_count}/13 completed Discovery Sprint sessions.
+> Source: Discovery/_context.md + individual session files
+> Generated: {date}
+
+---
+
+## What We're Building
+{Synthesize from Session 1 + 3: business vision + one-paragraph description of the
+application — what it does, who it's for, why it matters}
+
+### Core Problem
+{From Session 2: the #1 pain point and supporting pains, as a clear problem statement}
+
+### Target Users
+{From Session 2+3: personas — role, tech proficiency, primary need}
+
+| Persona | Role | Key Need |
+|---------|------|----------|
+| {persona} | {role} | {primary need} |
+
+### Success Metrics
+{From Session 1+3: KPIs and measurable outcomes}
+
+| KPI | Target | Measurement |
+|-----|--------|-------------|
+| {kpi} | {target} | {how measured} |
+
+---
+
+## Scope
+
+### In Scope (MVP)
+{From Session 3+11: confirmed MVP scope items}
+
+### Out of Scope
+{From Session 3+11: explicitly excluded items with reasons}
+
+---
+
+## Functional Requirements
+{From Session 3: EPICs and user stories, structured for requirements generation}
+
+### EPIC Registry
+| ID | Title | Priority | Phase | Stories |
+|----|-------|----------|-------|---------|
+| {epic-id} | {title} | {must/should/could} | {phase} | {count} |
+
+### Requirements by EPIC
+
+#### {EPIC-001}: {Title}
+{Brief EPIC description}
+
+**User Stories:**
+| ID | Story | Priority | Acceptance Criteria Summary |
+|----|-------|----------|---------------------------|
+| {us-id} | As a {role}, I want {goal} so that {benefit} | {priority} | {brief AC} |
+
+### Non-Functional Requirements
+| ID | Category | Requirement | Target |
+|----|----------|-------------|--------|
+| {nfr-id} | {Performance/Security/Usability/Availability} | {requirement} | {target} |
+
+### Business Rules
+| ID | Rule | Applies To |
+|----|------|------------|
+| {br-id} | {rule} | {module/scope} |
+
+---
+
+## Architecture & Technology
+{From Session 5: architecture style, tech stack, ADRs, key components}
+
+### Technology Stack
+| Layer | Technology | Rationale |
+|-------|-----------|-----------|
+| Frontend | {tech} | {why} |
+| Backend | {tech} | {why} |
+| Database | {tech} | {why} |
+| Hosting | {tech} | {why} |
+| Auth | {tech} | {why} |
+
+### Architecture Decision Records
+| ADR | Decision | Context |
+|-----|----------|---------|
+| {adr-id} | {decision} | {why over alternatives} |
+
+---
+
+## Security & Compliance
+{From Session 6: data classification, compliance, encryption, auth, audit, SLA}
+
+## User Roles & Identity
+{From Session 7: RBAC roles + permissions, identity provider}
+
+| Role | Description | Key Permissions |
+|------|-------------|-----------------|
+| {role} | {description} | {permissions} |
+
+## Integrations
+{From Session 8: external systems, direction, protocol, data, phase}
+
+| System | Direction | Protocol | Data | Phase |
+|--------|-----------|----------|------|-------|
+| {system} | {in/out/bi} | {REST/webhook} | {data} | {when} |
+
+## Quality & Testing Strategy
+{From Session 9: framework, coverage target, test types, UAT, quality gates}
+
+## Infrastructure & Deployment
+{From Session 10: environments, deployment approach, monitoring, backup/DR}
+
+---
+
+## Roadmap & Phasing
+{From Session 11: planned release structure — used to generate the phase breakdown}
+
+### Phases
+| Phase | Scope | Duration |
+|-------|-------|----------|
+| {phase} | {included} | {sprints/weeks} |
+
+### Key Milestones
+| Milestone | Target | Criteria |
+|-----------|--------|----------|
+| {milestone} | {date/sprint} | {done criteria} |
+
+### Build Order Preferences
+{Sequencing constraints or preferences from Discovery}
+
+## Team & Delivery Model
+{From Session 12: team size, roles, sprint cadence, ceremonies}
+
+## Open Items & Risks
+
+### Open Action Items
+| Action | From Session | Status |
+|--------|-------------|--------|
+| {action} | {session} | {status} |
+
+### Risks
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| {risk} | {H/M/L} | {H/M/L} | {mitigation} |
+
+---
+
+## Discovery Traceability
+
+> pp-core agents: for deeper context on any decision above, reference the original
+> Discovery session files. Key mappings:
+
+| Topic | Primary Source | Secondary Sources |
+|-------|---------------|-------------------|
+| Business context & vision | `Discovery/01-discovery-sprint-kickoff.md` | `Discovery/_context.md` §1 |
+| Current state & pain points | `Discovery/02-business-process-mapping-as-is.md` | `Discovery/_context.md` §2 |
+| Requirements & user stories | `Discovery/03-business-requirements-to-be.md` | `Discovery/_context.md` §3 |
+| UX design principles | `Discovery/04-ux-design-principles.md` | `Discovery/_context.md` §4 |
+| Architecture & tech stack | `Discovery/05-application-integration-architecture.md` | `Discovery/_context.md` §5 |
+| Security & compliance | `Discovery/06-security-compliance-setup.md` | `Discovery/_context.md` §6 |
+| Roles & identity | `Discovery/07-user-identity-management.md` | `Discovery/_context.md` §7 |
+| Integrations | `Discovery/08-integration-interface-design.md` | `Discovery/_context.md` §8 |
+| QA & testing | `Discovery/09-quality-assurance-testing.md` | `Discovery/_context.md` §9 |
+| Infrastructure & deployment | `Discovery/10-infrastructure-deployment-readiness.md` | `Discovery/_context.md` §10 |
+| Roadmap & release plan | `Discovery/11-project-roadmap-release-planning.md` | `Discovery/_context.md` §11 |
+| Team & delivery model | `Discovery/12-team-delivery-model.md` | `Discovery/_context.md` §12 |
+| Wrap-up & go/no-go | `Discovery/13-discovery-sprint-wrapup.md` | `Discovery/_context.md` §13 |
+```
+
+**Synthesis rules:**
+- Use actual content from the session files, never placeholders
+- If a session is incomplete, note `[Session N incomplete — content pending]` in that section
+- Preserve requirement IDs (FR-xxx, NFR-xxx, US-xxx, EPIC-xxx) exactly as defined
+- Preserve role names (Session 7) and technology choices (Session 5) exactly
+- If the Project Definition document has content not in `_context.md`, merge it in
+- Keep it factual — no interpretation or recommendations, just structured outputs
+
+---
+
+**Step 4: User review**
+
+```
+AskUserQuestion([
+  {
+    header: "Handoff Ready",
+    question: "I've synthesized your Discovery Sprint into Discovery/_pp-handoff.md.\n\nSummary:\n- {epic_count} EPICs, {story_count} user stories\n- {fr_count} functional / {nfr_count} non-functional requirements\n- Tech stack: {stack_summary}\n- {role_count} user roles, {integration_count} integrations, {phase_count} phases\n- {incomplete_sessions} incomplete sessions (if any)\n\nReview the file and confirm to proceed with pp-core initialization.",
+    multiSelect: false,
+    options: [
+      { label: "Initialize pp-core", description: "Generate .planning/ from this handoff document (Recommended)" },
+      { label: "Review first", description: "Check Discovery/_pp-handoff.md before proceeding" },
+      { label: "Regenerate", description: "Something looks off — resynthesize from discovery" }
+    ]
+  }
+])
+```
+
+**If "Review first":** Wait for the user to review, then remind them to say "continue" or
+re-run `/pp-build-handoff` when ready.
+
+**If "Regenerate":** Ask what's wrong, adjust, and regenerate Step 3.
+
+**If "Initialize pp-core":** Proceed to Step 5.
+
+---
+
+**Step 5: Initialize pp-core**
+
+Do NOT literally run `/pp-new-project` as a slash command from within this workflow.
+Execute the initialization inline using the same `pp_run` tool calls the new-project
+workflow uses.
+
+### 5a. Run init
+
+```bash
+mkdir -p .planning
+INIT=$(pp_run query init.new-project 2>/dev/null)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+echo "$INIT"
+```
+
+### 5b. Collect preferences
+
+Ask the pp-core configuration questions — identical to `/pp-new-project` Step 2a:
+
+```
+AskUserQuestion([
+  { header: "Granularity", question: "How finely should scope be sliced into phases?", multiSelect: false, options: [
+      { label: "Coarse (Recommended)", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" } ] },
+  { header: "Execution", question: "Run plans in parallel?", multiSelect: false, options: [
+      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
+      { label: "Sequential", description: "One plan at a time" } ] },
+  { header: "Git Tracking", question: "Commit planning docs to git?", multiSelect: false, options: [
+      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
+      { label: "No", description: "Keep .planning/ local-only" } ] }
+])
+```
+
+```
+AskUserQuestion([
+  { header: "Research", question: "Research before planning each phase?", multiSelect: false, options: [
+      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
+      { label: "No", description: "Plan directly — Discovery already covered the research" } ] },
+  { header: "Plan Check", question: "Verify plans will achieve their goals?", multiSelect: false, options: [
+      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
+      { label: "No", description: "Execute plans without verification" } ] },
+  { header: "Verifier", question: "Verify work after each phase?", multiSelect: false, options: [
+      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
+      { label: "No", description: "Trust execution, skip verification" } ] },
+  { header: "AI Models", question: "Which models for planning agents?", multiSelect: false, options: [
+      { label: "Balanced (Recommended)", description: "Sonnet for most agents" },
+      { label: "Quality", description: "Opus for research/roadmap" },
+      { label: "Budget", description: "Haiku where possible" },
+      { label: "Inherit", description: "Use the current session model for all agents" } ] }
+])
+```
+
+### 5c. Create config.json
+
+```bash
+pp_run config-new-project '{"mode":"yolo","granularity":"{selected}","parallelization":{true|false},"commit_docs":{true|false},"model_profile":"{selected}","workflow":{"research":{true|false},"plan_check":{true|false},"verifier":{true|false},"nyquist_validation":false,"auto_advance":true}}'
+pp_run commit "chore: add project config" --files .planning/config.json
+```
+
+### 5d. Generate PROJECT.md
+
+Read `Discovery/_pp-handoff.md` and synthesize `.planning/PROJECT.md` using the pp-core
+project template structure: use "What We're Building" as the description, include all
+Key Decisions, list requirements in Validated/Active/Out-of-Scope form, and reference
+Discovery artifacts (the section is added in Step 6a).
+
+```bash
+pp_run commit "docs: initialize project from Discovery Sprint" --files .planning/PROJECT.md
+```
+
+### 5e. Generate REQUIREMENTS.md
+
+From the Functional Requirements section: map EPICs to requirement groups, user stories
+to individual requirements, include NFRs and Business Rules, preserve all original IDs
+(FR-xxx, NFR-xxx, US-xxx), and mark all requirements active.
+
+```bash
+pp_run commit "docs: requirements from Discovery Sprint" --files .planning/REQUIREMENTS.md
+```
+
+### 5f. Generate ROADMAP.md
+
+From the Roadmap & Phasing section: map Discovery phases to pp-core phases, derive phase
+goals from EPIC scope, set dependencies from build-order preferences, and include the
+milestone name (Session 11, or default "v1.0 — MVP").
+
+```bash
+pp_run commit "docs: roadmap from Discovery Sprint" --files .planning/ROADMAP.md
+```
+
+### 5g. Initialize STATE.md
+
+```bash
+pp_run state-init 2>/dev/null
+pp_run commit "docs: initialize state" --files .planning/STATE.md
+```
+
+---
+
+**Step 6: Wire Discovery references**
+
+### 6a. Patch PROJECT.md
+
+Append a Discovery Artifacts section to `.planning/PROJECT.md`:
+
+```markdown
+## Discovery Artifacts
+
+This project was initialized from a completed Pareto Discovery Sprint ({completed_count}/13 sessions).
+Discovery outputs are the source of truth for business decisions and requirements rationale.
+
+### Key References
+
+| Topic | File | Use When |
+|-------|------|----------|
+| All decisions (accumulated) | `Discovery/_context.md` | Understanding why a decision was made |
+| pp-core handoff synthesis | `Discovery/_pp-handoff.md` | Complete structured summary of all sessions |
+| Business requirements | `Discovery/03-business-requirements-to-be.md` | Detailed EPICs, user stories, acceptance criteria |
+| Architecture decisions | `Discovery/05-application-integration-architecture.md` | Tech stack rationale, ADRs, component design |
+| Security requirements | `Discovery/06-security-compliance-setup.md` | Compliance, encryption, audit requirements |
+| Role definitions | `Discovery/07-user-identity-management.md` | RBAC model, permissions, identity provider |
+| Integration specs | `Discovery/08-integration-interface-design.md` | External system interfaces, protocols, data flows |
+| QA strategy | `Discovery/09-quality-assurance-testing.md` | Test types, coverage targets, quality gates |
+| Release plan | `Discovery/11-project-roadmap-release-planning.md` | Sprint plan, milestones, build order |
+| Interactive prototype | `prototype/` | Visual reference for UI implementation |
+
+### How pp-core Agents Should Use Discovery
+
+- **During discuss phases:** Reference specific sessions when answering gray-area questions
+- **During research:** Check Discovery sessions before external research — many answers are already there
+- **During planning:** Use requirement IDs from Discovery (FR-xxx, US-xxx) in plan references
+- **During verification:** Trace completed work back to Discovery requirements
+```
+
+```bash
+pp_run commit "docs: add Discovery artifacts reference to PROJECT.md" --files .planning/PROJECT.md
+```
+
+### 6b. Update CLAUDE.md
+
+Inject a Discovery Sprint Context block into the project's `CLAUDE.md` (idempotent —
+replace an existing block if present, otherwise append):
+
+```markdown
+## Discovery Sprint Context
+
+This project has a completed Discovery Sprint in `Discovery/`. pp-core agents should:
+
+1. **Check Discovery before asking the user** — most business and architecture decisions are already documented
+2. **Reference `Discovery/_context.md`** for accumulated cross-session decisions
+3. **Reference `Discovery/_pp-handoff.md`** for the structured synthesis used to initialize pp-core
+4. **Use original requirement IDs** (FR-xxx, NFR-xxx, US-xxx, EPIC-xxx) from Discovery in plans and commits
+5. **Reference specific session files** when a phase involves topics covered in that session:
+   - Auth/roles → Session 7 (`Discovery/07-user-identity-management.md`)
+   - Integrations → Session 8 (`Discovery/08-integration-interface-design.md`)
+   - UI/UX → Session 4 (`Discovery/04-ux-design-principles.md`) + `prototype/`
+   - Security → Session 6 (`Discovery/06-security-compliance-setup.md`)
+   - Testing → Session 9 (`Discovery/09-quality-assurance-testing.md`)
+```
+
+```bash
+git add CLAUDE.md && git commit -m "docs: add Discovery Sprint context to CLAUDE.md"
+```
+
+### 6c. Create GitHub issues from requirements (optional, best-effort)
+
+Push EPICs and user stories to GitHub as issues so the backlog is visible on a project
+board. This step is optional and self-contained — it uses the GitHub CLI directly and
+skips cleanly when the CLI is unavailable.
+
+```bash
+gh auth status >/dev/null 2>&1 && gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null && echo "GH_OK" || echo "GH_SKIP"
+```
+
+**If GH_SKIP:** Skip to Step 7 with a note:
+```
+Skipping GitHub board sync — no authenticated GitHub CLI or no remote repo.
+You can create issues later once a remote is configured.
+```
+
+**If GH_OK:** Ask whether to push:
+
+```
+AskUserQuestion([
+  {
+    header: "GitHub Board",
+    question: "Push requirements to GitHub as issues?",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Create EPIC + user story issues in the repo" },
+      { label: "Skip", description: "I'll manage the board manually" }
+    ]
+  }
+])
+```
+
+**If "Yes":** For each EPIC and user story from the handoff document, create an issue
+with `gh issue create` (title, labels `epic`/`user-story`, body referencing the Discovery
+source). Then write `.planning/github-issues.json` mapping each requirement ID to its
+issue number, and commit it:
+
+```bash
+pp_run commit "docs: GitHub issue mapping" --files .planning/github-issues.json
+```
+
+Keep this step resilient: if any `gh` call fails, surface the error and continue — a
+failed board sync must not abort the handoff.
+
+---
+
+**Step 7: Scaffold application (optional)**
+
+**Only if `--scaffold` is present.** Read the tech stack from the handoff document
+(Session 5) and, after confirming with the user, create a lightweight application
+structure — folder layout, `package.json`/config files, and entry points. pp-core
+Phase 1 fleshes it out.
+
+---
+
+**Step 8: Handoff summary**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PARETO BUILD HANDOFF — Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Discovery Sprint → pp-core transition successful.
+
+Created:
+  Discovery/_pp-handoff.md        Synthesized discovery outputs
+  .planning/PROJECT.md            Project context for pp-core
+  .planning/REQUIREMENTS.md       {req_count} requirements from {epic_count} EPICs
+  .planning/ROADMAP.md            {phase_count} phases mapped from Discovery roadmap
+  .planning/STATE.md              Project state tracker
+  .planning/config.json           pp-core configuration
+  .planning/github-issues.json    Requirement → GitHub issue mapping (if pushed)
+  CLAUDE.md                       Updated with Discovery references
+
+Discovery Traceability:
+  Discovery sessions → _pp-handoff.md → pp-core artifacts → (optional) GitHub issues
+  Requirement IDs (FR-xxx, US-xxx) carry through the full chain
+
+Next steps:
+  1. Run /pp-plan-phase 1 to create the first phase plan
+  2. Or run /pp-autonomous to execute all phases automatically
+
+Quality drives speed. Discovery done, now build.
+```
+
+</process>
+
+<success_criteria>
+- Discovery completion validated (or the user acknowledged gaps)
+- All session content read and synthesized into `Discovery/_pp-handoff.md`
+- Synthesis preserves original requirement IDs, role names, and tech choices
+- pp-core initialized with PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json
+- PROJECT.md contains a Discovery Artifacts reference section
+- CLAUDE.md updated with Discovery Sprint context
+- GitHub issues created for EPICs and user stories when a repo is available (best-effort)
+- The user knows the next steps (plan phase 1 or autonomous)
+</success_criteria>