@pareto4/pp-core 1.11.0 → 1.12.0

package/pp-core/workflows/discovery-to-build/steps/architecture-deliverables.md

@@ -3,10 +3,10 @@
 > **Lazily-loaded.** Read this file from `pp-core/workflows/discovery-to-build.md`
 > at Step 5h, once all sessions are synthesized (after the `_pp-handoff.md`
 > synthesis and the `.planning/PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md`
-> generation steps have run). It is not `@`-imported and is not measured by
-> `tests/workflow-size-budget.test.cjs` (`listWorkflowStems()` is
-> non-recursive) — this is the sanctioned progressive-disclosure escape hatch
-> for a DEFAULT-tier workflow file, not a workaround.
+> generation steps have run). It is not `@`-imported — this is the sanctioned
+> progressive-disclosure pattern for a DEFAULT-tier workflow file, not a
+> workaround. Its own size is still guarded: `tests/workflow-size-budget.test.cjs`
+> measures nested step files too (32 KiB cap plus the per-file baseline).
 >
 > Purpose: answers an external-review finding — the client gets a real architect-grade
 > handoff, not just process state. This step is factored on purpose so it can
@@ -238,8 +238,8 @@ Introduction & Goals section.
    already defined it is harmless:
 
 ```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 [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/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" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 
+_PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; 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}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 FILES="docs/architecture/architecture.md"
 ls docs/architecture/adr/*.md >/dev/null 2>&1 && FILES="$FILES docs/architecture/adr/*.md"
 pp_run commit "docs: generate architect-grade handoff (arc42-lite architecture + ADRs)" --files $FILES

package/pp-core/workflows/discovery-to-build/steps/screen-inventory-gate.md

@@ -0,0 +1,70 @@
+# Discovery-to-Build Gates — the hard blocks of Step 2
+
+> **Lazily-loaded.** Read this file from `pp-core/workflows/discovery-to-build.md` at the start of
+> Step 2, before the completion check. It is not `@`-imported. Run the gates in order; a stop in any
+> of them ends the handoff. They are the only hard blocks in the workflow — every other check in
+> Step 2 is a confirmation prompt.
+
+**Screen-inventory contract gate (D-53)**
+
+This is the one gate in this workflow that hard-blocks; every other check in Step 2 is a
+confirmation prompt, deliberately. A percentage-based visual gate over a curated list cannot
+detect an omission — a surface dropped from the list is dropped from the denominator too — and
+this handoff is the last moment such an omission is still free to fix.
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _pp_root() { ( for _v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$_v"; done; _c=$(git rev-parse --git-common-dir 2>/dev/null); if [ "${_c##*/}" = .git ] && cd "$_c/.." 2>/dev/null; then pwd -P; else git rev-parse --show-toplevel 2>/dev/null || pwd; fi ); }; pp_run() { case "$PP_TOOLS" in *.cjs) node "$PP_TOOLS" "$@";; *) "$PP_TOOLS" "$@";; esac; }; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(_pp_root)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then :; 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}"; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+pp_run query discovery.screen-check
+SCREEN_CHECK_STATUS=$?
+echo "SCREEN_CHECK_STATUS=$SCREEN_CHECK_STATUS"
+pp_run query discovery.screen-check --require-processed >/dev/null
+FEEDBACK_STATUS=$?
+echo "FEEDBACK_STATUS=$FEEDBACK_STATUS"
+pp_run query discovery.element-sweep --check >/dev/null
+SWEEP_STATUS=$?
+echo "SWEEP_STATUS=$SWEEP_STATUS"
+```
+
+**If `SCREEN_CHECK_STATUS` is 0 and `FEEDBACK_STATUS` is 0:** Continue with the element-sweep gate below.
+
+**If `SCREEN_CHECK_STATUS` is 0 and `FEEDBACK_STATUS` is non-zero:** Stop with no option to
+proceed. Report the line the check printed, verbatim: an `Open` row in `_feedback.md` is a client
+comment the build would ignore. Process it with `/pp-discovery prototype` Step 7, then re-run.
+`--skip-validation` does not cover this gate.
+
+**If `SCREEN_CHECK_STATUS` is non-zero:** Report the engine's own fault list and stop. Offer no
+option to proceed and put no choice to the operator — this is a hard stop, not a confirmation.
+
+```
+Error: the screen-inventory contract has structural faults.
+
+{the report screen-check printed, verbatim}
+
+Resolve every item the report names in .planning/discovery/_screens.md and
+.planning/discovery/_feedback.md, then re-run /pp-discovery-to-build. The two that always
+block are D-53's: an MVP requirement that appears on no screen and in no bucket, and a surface
+that is neither REQUIRED nor DEFERRED with a reason. The report names each fault in the same
+vocabulary the Session 13 gate uses; that gate paragraph enumerates all of them.
+
+The --skip-validation flag does NOT cover this gate. That flag skips the Discovery completion
+check, for sessions that are intentionally incomplete; a surface nobody classified is a
+malformed artifact, not incompleteness (D-53).
+```
+
+**If the engagement never inventoried screens** and neither `.planning/discovery/_screens.md`
+nor `.planning/discovery/_feedback.md` exists, the check exits 0 by itself: the handoff
+proceeds exactly as it does today, so every pre-existing engagement is unaffected.
+
+**Element-sweep gate**
+
+Every functional element of the prototype must be decided before the build starts, or the build
+receives screens with fields, columns and actions that no requirement or decision explains.
+
+The check ran in the first fence above.
+
+**If `SWEEP_STATUS` is 0:** The gates pass. Return to Step 2 of `discovery-to-build.md`.
+
+**If `SWEEP_STATUS` is non-zero:** Stop with no option to proceed. Report the fault list the check
+printed, verbatim, and tell the user to finish the sweep with `/pp-discovery prototype` Step 8, then
+re-run `/pp-discovery-to-build`. `--skip-validation` does not cover this gate. Without a prototype
+the check exits 0 by itself.

package/pp-core/workflows/discovery-to-build/templates/discovery-references.md

@@ -0,0 +1,54 @@
+# Discovery reference blocks — Step 6 of discovery-to-build
+
+> **Lazily-loaded.** Read this file from `pp-core/workflows/discovery-to-build.md` at Step 6. It is
+> not `@`-imported. Step 6a appends the PROJECT.md block; Step 6b injects the CLAUDE.md block.
+
+## PROJECT.md block (Step 6a)
+
+```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) | `.planning/discovery/_context.md` | Understanding why a decision was made |
+| pp-core handoff synthesis | `.planning/discovery/_pp-handoff.md` | Complete structured summary of all sessions |
+| Business requirements | `.planning/discovery/session-03.md` | Detailed EPICs, user stories, acceptance criteria |
+| Architecture decisions | `.planning/discovery/session-05.md` | Tech stack rationale, ADRs, component design |
+| Security requirements | `.planning/discovery/session-06.md` | Compliance, encryption, audit requirements |
+| Role definitions | `.planning/discovery/session-07.md` | RBAC model, permissions, identity provider |
+| Integration specs | `.planning/discovery/session-08.md` | External system interfaces, protocols, data flows |
+| QA strategy | `.planning/discovery/session-09.md` | Test types, coverage targets, quality gates |
+| Release plan | `.planning/discovery/session-11.md` | Sprint plan, milestones, build order |
+| Interactive prototype | `.planning/discovery/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
+```
+
+## CLAUDE.md block (Step 6b)
+
+```markdown
+## Discovery Sprint Context
+
+This project has a completed Discovery Sprint in `.planning/discovery/`. pp-core agents should:
+
+1. **Check Discovery before asking the user** — most business and architecture decisions are already documented
+2. **Reference `.planning/discovery/_context.md`** for accumulated cross-session decisions
+3. **Reference `.planning/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 (`.planning/discovery/session-07.md`)
+   - Integrations → Session 8 (`.planning/discovery/session-08.md`)
+   - UI/UX → Session 4 (`.planning/discovery/session-04.md`) + `.planning/discovery/prototype/`
+   - Security → Session 6 (`.planning/discovery/session-06.md`)
+   - Testing → Session 9 (`.planning/discovery/session-09.md`)
+```

package/pp-core/workflows/discovery-to-build/templates/pp-handoff.md

@@ -0,0 +1,184 @@
+# `_pp-handoff.md` template — Step 3b of discovery-to-build
+
+> **Lazily-loaded.** Read this file from `pp-core/workflows/discovery-to-build.md` at Step 3b. It is
+> not `@`-imported. Write `.planning/discovery/_pp-handoff.md` with exactly this structure; the
+> synthesis rules stay in Step 3b.
+
+```markdown
+# Discovery Sprint Synthesis — pp-core Handoff
+
+> Auto-generated from {completed_count}/13 completed Discovery Sprint sessions.
+> Source: .planning/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
+
+### Parked Questions (Unresolved)
+{From the D-12 scan of every session's PARKED — needs business/senior input markers:
+list each parked question verbatim, honestly, as a known gap — never silently dropped}
+
+| Question | Session | Owner |
+|----------|---------|-------|
+| {parked question, verbatim} | {session} | business/senior |
+
+### 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 | `.planning/discovery/session-01.md` | `.planning/discovery/_context.md` §1 |
+| Current state & pain points | `.planning/discovery/session-02.md` | `.planning/discovery/_context.md` §2 |
+| Requirements & user stories | `.planning/discovery/session-03.md` | `.planning/discovery/_context.md` §3 |
+| UX design principles | `.planning/discovery/session-04.md` | `.planning/discovery/_context.md` §4 |
+| Architecture & tech stack | `.planning/discovery/session-05.md` | `.planning/discovery/_context.md` §5 |
+| Security & compliance | `.planning/discovery/session-06.md` | `.planning/discovery/_context.md` §6 |
+| Roles & identity | `.planning/discovery/session-07.md` | `.planning/discovery/_context.md` §7 |
+| Integrations | `.planning/discovery/session-08.md` | `.planning/discovery/_context.md` §8 |
+| QA & testing | `.planning/discovery/session-09.md` | `.planning/discovery/_context.md` §9 |
+| Infrastructure & deployment | `.planning/discovery/session-10.md` | `.planning/discovery/_context.md` §10 |
+| Roadmap & release plan | `.planning/discovery/session-11.md` | `.planning/discovery/_context.md` §11 |
+| Team & delivery model | `.planning/discovery/session-12.md` | `.planning/discovery/_context.md` §12 |
+| Wrap-up & go/no-go | `.planning/discovery/session-13.md` | `.planning/discovery/_context.md` §13 |
+```