@pareto4/pp-core 1.8.1 → 1.9.0

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

@@ -27,7 +27,7 @@ Valid pp-core subagent types (use exact names — do not fall back to 'general-p
 **Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call in this workflow with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 
 **Prerequisites:**
-- A Pareto project with a `Discovery/` folder (created by `pareto-project-setup`)
+- A Pareto project with Discovery Sprint sessions in `.planning/discovery/` (created via `/pp-discovery`)
 - Discovery Sprint sessions (ideally 13/13 completed)
 - pp-core installed and resolvable via the standard `pp_run` shim
 </context>
@@ -46,19 +46,80 @@ Resolve the `pp_run` helper before anything else. Every `pp_run` call below uses
 **Step 1: Validate environment**
 
 ```bash
-ls Discovery/_progress.md 2>/dev/null && echo "DISCOVERY_OK" || echo "DISCOVERY_MISSING"
+ls .planning/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.
+**If DISCOVERY_MISSING:** Before erroring, check for a legacy root-level Discovery tree
+(D-02) — an older `pareto-project-setup` scaffold that pre-dates the canonical
+`.planning/discovery/` path family. <!-- legacy-read-target -->
+
+```bash
+ls Discovery/_progress.md 2>/dev/null && echo "LEGACY_FOUND" || echo "LEGACY_ABSENT"  # legacy detection read target <!-- legacy-read-target -->
+```
+
+**If LEGACY_ABSENT:** 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.
+Expected: .planning/discovery/_progress.md
+Run /pp-discovery 1 to start a Discovery Sprint, then complete the sessions
+before transitioning to build.
+```
+
+**If LEGACY_FOUND:** A legacy pre-canonical tree exists with real client answers — this is
+business data, not disposable scaffolding. <!-- legacy-read-target --> Offer a one-time
+guided conversion into the canonical `.planning/discovery/` path family; no silent ignore,
+no hard error (D-02):
+
+```
+AskUserQuestion([
+  {
+    header: "Legacy Discovery Tree Found",
+    question: "Found a legacy pre-canonical Discovery tree (from an older pareto-project-setup scaffold) but no .planning/discovery/ tree. Convert it to the canonical .planning/discovery/ format now? This copies your 13 session files plus the progress and context files into .planning/discovery/ — the original legacy folder is left untouched.",
+    multiSelect: false,
+    options: [
+      { label: "Convert now (Recommended)", description: "Copy the legacy tree's content into .planning/discovery/session-NN.md and proceed" },
+      { label: "Cancel", description: "Stop here — I'll migrate manually or run /pp-discovery instead" }
+    ]
+  }
+])
+```
+
+**If "Cancel":** Exit with guidance:
+```
+No changes made. To migrate manually, copy each legacy session file's content into
+.planning/discovery/session-NN.md (see the Discovery Traceability mapping in this
+workflow's Step 3b for the exact legacy-filename-to-session-NN pairs), then re-run
+/pp-discovery-to-build.
+```
+
+**If "Convert now":** Perform the guided migration. For each of the 13 legacy session
+files (the exact legacy filenames are the primary-source column of the Discovery
+Traceability table in Step 3b), read the legacy file's frontmatter and content, then
+write `.planning/discovery/session-NN.md`: <!-- legacy-read-target -->
+
+- Preserve `status`, `completed_date`, and `completeness_score` frontmatter fields where
+  present in the legacy file; normalize any missing fields to the current session
+  template's defaults (do not blind-copy — read what exists, fill gaps honestly).
+- Copy the legacy progress and context files to `.planning/discovery/_context.md` and
+  `.planning/discovery/_progress.md` respectively <!-- legacy-read-target -->, adding a
+  `Parked` column to the progress table (default 0) if the legacy schema predates it.
+
+**Path safety (T-04-03, reused verbatim):** Reject any source or destination path that is
+absolute or contains `..`. Every migration write target MUST resolve under
+`.planning/discovery/` — never write outside it, and never delete or modify the original
+legacy tree. <!-- legacy-read-target -->
+
+```bash
+ls .planning/discovery/_progress.md 2>/dev/null && echo "DISCOVERY_OK" || echo "MIGRATION_FAILED"
 ```
 
+**If MIGRATION_FAILED:** Report the failure and stop — do not proceed with a partial
+migration.
+
+**If DISCOVERY_OK:** Proceed to Step 2 with the newly migrated canonical tree.
+
 **If PPCORE_EXISTS:** Error and stop.
 ```
 Error: pp-core is already initialized (.planning/PROJECT.md exists).
@@ -71,7 +132,7 @@ 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
+Read `.planning/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.
@@ -102,6 +163,39 @@ When all sessions are complete, run /pp-discovery-to-build again.
 
 **If "Proceed anyway":** Continue to Step 3, noting which sessions are incomplete.
 
+**Surface unresolved parked questions (D-12):** Scan `.planning/discovery/_progress.md`'s
+Parked column and every session file's `PARKED — needs business/senior input` markers to
+build the full list of unresolved parked questions across all sessions. This list carries
+forward into Step 3b's `## Open Items & Risks` synthesis section regardless of the outcome
+below.
+
+**If the parked list is non-empty:** Surface it and gate proceeding behind an explicit
+confirmation — never a hard block:
+
+```
+AskUserQuestion([
+  {
+    header: "Parked Questions Open",
+    question: "{parked_count} question(s) were parked during Discovery Sprint sessions as needing business/senior input:\n\n{list of parked questions, one per line, with session + topic}\n\nThese will be carried into the handoff synthesis as known gaps under Open Items & Risks — completeness scores already reflect them as not-covered. Proceed with them open?",
+    multiSelect: false,
+    options: [
+      { label: "Proceed with gaps noted (Recommended)", description: "Continue — parked items are tracked as known gaps, not blockers" },
+      { label: "Pause and resolve first", description: "Go back to Discovery to resolve the business/senior-input questions before continuing" }
+    ]
+  }
+])
+```
+
+**If "Pause and resolve first":** Exit with guidance:
+```
+Parked questions need business/senior input before proceeding. Resolve them in the
+relevant Discovery session (see /pp-discovery), then re-run /pp-discovery-to-build.
+```
+
+**If "Proceed with gaps noted":** Continue to Step 3, carrying the parked list forward.
+
+**If the parked list is empty:** Skip this confirmation silently and continue to Step 3.
+
 ---
 
 **Step 3: Read and synthesize Discovery outputs**
@@ -113,9 +207,9 @@ them into a single document optimized for the pp-core new-project generators.
 
 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`
+1. `.planning/discovery/_context.md` — accumulated cross-session context (primary source)
+2. `.planning/discovery/_progress.md` — session completion status
+3. All 13 session files in `.planning/discovery/session-NN.md` — 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
 
@@ -125,7 +219,7 @@ 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
+Write `.planning/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.
 
@@ -133,7 +227,7 @@ map cleanly onto what those generators expect.
 # Discovery Sprint Synthesis — pp-core Handoff
 
 > Auto-generated from {completed_count}/13 completed Discovery Sprint sessions.
-> Source: Discovery/_context.md + individual session files
+> Source: .planning/discovery/_context.md + individual session files
 > Generated: {date}
 
 ---
@@ -266,6 +360,14 @@ application — what it does, who it's for, why it matters}
 
 ## 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 |
 |--------|-------------|--------|
@@ -285,19 +387,19 @@ application — what it does, who it's for, why it matters}
 
 | 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 |
+| 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 |
 ```
 
 **Synthesis rules:**
@@ -307,6 +409,8 @@ application — what it does, who it's for, why it matters}
 - 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
+- List every unresolved parked question from Step 2's D-12 scan verbatim in the Parked
+  Questions (Unresolved) table — never inflate completeness by omitting them
 
 ---
 
@@ -316,11 +420,11 @@ application — what it does, who it's for, why it matters}
 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.",
+    question: "I've synthesized your Discovery Sprint into .planning/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: "Review first", description: "Check .planning/discovery/_pp-handoff.md before proceeding" },
       { label: "Regenerate", description: "Something looks off — resynthesize from discovery" }
     ]
   }
@@ -399,11 +503,19 @@ 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
+Read `.planning/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).
 
+**Inline source refs (D-05):** Every Key Decision and every requirement summary carried
+into PROJECT.md gets a compact trailing ref at its point of use — `(source: session-NN
+§Section)`, e.g. `Auth uses magic links, not passwords (source: session-05 §Auth Strategy)`
+— naming the canonical `.planning/discovery/session-NN.md` file and the section within it
+the item was synthesized from. Then append one `## Discovery Traceability` table (same
+shape as the table already in this workflow's Step 3b handoff synthesis) mapping each
+PROJECT.md section to its canonical `.planning/discovery/session-NN.md` source(s).
+
 ```bash
 pp_run commit "docs: initialize project from Discovery Sprint" --files .planning/PROJECT.md
 ```
@@ -414,6 +526,15 @@ From the Functional Requirements section: map EPICs to requirement groups, user
 to individual requirements, include NFRs and Business Rules, preserve all original IDs
 (FR-xxx, NFR-xxx, US-xxx), and mark all requirements active.
 
+**Inline source refs (D-05):** Every generated requirement line — FR/NFR/EPIC/US — carries
+a trailing `(source: session-NN §Section)` ref at point of use, e.g. `FR-012: User can
+export a report as CSV (source: session-03 §Order Intake)`, naming the canonical
+`.planning/discovery/session-NN.md` file and section it was derived from. Then append one
+`## Discovery Traceability` table (same shape as Step 3b's table) mapping each requirement
+category (Authentication, EPIC group, NFRs, Business Rules, …) to its canonical
+`.planning/discovery/session-NN.md` source(s) — the file-level map that complements the
+per-item inline refs above.
+
 ```bash
 pp_run commit "docs: requirements from Discovery Sprint" --files .planning/REQUIREMENTS.md
 ```
@@ -424,17 +545,62 @@ From the Roadmap & Phasing section: map Discovery phases to pp-core phases, deri
 goals from EPIC scope, set dependencies from build-order preferences, and include the
 milestone name (Session 11, or default "v1.0 — MVP").
 
+**Canonical refs producer (D-06):** For every generated phase entry, emit a
+`**Canonical refs:** .planning/discovery/session-NN.md, ...` line listing every canonical
+session file that fed that phase's requirements — placed immediately after the
+`**Requirements**:` line and before `**Success Criteria**`, per `pp-core/templates/roadmap.md`'s
+phase-entry field order:
+
+```markdown
+### Phase [N]: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: [...]
+**Requirements**: [REQ-01, REQ-02]
+**Canonical refs:** .planning/discovery/session-03.md, .planning/discovery/session-05.md
+**Success Criteria** (what must be TRUE):
+```
+
+Use the exact label string `Canonical refs:` — the existing `discuss-phase.md:313` consumer
+already copies this line unchanged into `CONTEXT.md`'s canonical refs accumulator. Do not
+modify `discuss-phase.md`, the researcher, or the planner — this workflow is the first
+*producer* of a line those consumers already read.
+
 ```bash
 pp_run commit "docs: roadmap from Discovery Sprint" --files .planning/ROADMAP.md
 ```
 
 ### 5g. Initialize STATE.md
 
+No `pp_run` CLI command initializes STATE.md — author `.planning/STATE.md` directly via
+`Write`, following `pp-core/templates/state.md`'s schema (the same approach `new-project.md`'s
+roadmapper agent uses). Populate it from what Step 5f already established:
+
+- `status: planning`, `progress.total_phases`/`total_plans` from the generated ROADMAP.md,
+  `completed_phases`/`completed_plans` at 0
+- **Project Reference:** core value from `.planning/PROJECT.md`, current focus = Phase 1
+- **Current Position:** Phase 1 of N, "Ready to plan", today's date, 0% progress bar
+- **Accumulated Context › Decisions:** none yet (fresh project)
+- **Accumulated Context › Blockers/Concerns:** any unresolved parked questions carried
+  forward from Step 2's D-12 confirmation (see below), so they stay visible after handoff
+- **Session Continuity:** last session = now, stopped at "Discovery handoff complete", no
+  resume file
+
 ```bash
-pp_run state-init 2>/dev/null
 pp_run commit "docs: initialize state" --files .planning/STATE.md
 ```
 
+### 5h. Generate architecture deliverables
+
+`Read(workflows/discovery-to-build/steps/architecture-deliverables.md)` and execute it
+end-to-end — it produces `docs/architecture/architecture.md` (arc42-lite) and one
+`docs/architecture/adr/NNNN-title.md` per Session 5 ADR row from the already-synthesized
+handoff content (D-13). The generation instructions live entirely in that sub-file
+(lazily loaded, unmeasured by `tests/workflow-size-budget.test.cjs`) — do not inline them
+here. The sub-file performs its own commit of these files as the final step of its
+"Completing the step" section (its own `pp_run` resolver guard makes it safe to run
+standalone too) — do NOT re-run a commit for `docs/architecture/` here; that would be
+a duplicate of the sub-file's own commit.
+
 ---
 
 **Step 6: Wire Discovery references**
@@ -453,15 +619,15 @@ Discovery outputs are the source of truth for business decisions and requirement
 
 | 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 |
+| 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 | `prototype/` | Visual reference for UI implementation |
 
 ### How pp-core Agents Should Use Discovery
@@ -484,18 +650,18 @@ 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:
+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 `Discovery/_context.md`** for accumulated cross-session decisions
-3. **Reference `Discovery/_pp-handoff.md`** for the structured synthesis used to initialize pp-core
+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 (`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`)
+   - 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`) + `prototype/`
+   - Security → Session 6 (`.planning/discovery/session-06.md`)
+   - Testing → Session 9 (`.planning/discovery/session-09.md`)
 ```
 
 ```bash
@@ -567,7 +733,7 @@ Phase 1 fleshes it out.
 Discovery Sprint → pp-core transition successful.
 
 Created:
-  Discovery/_pp-handoff.md        Synthesized discovery outputs
+  .planning/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
@@ -591,7 +757,11 @@ Quality drives speed. Discovery done, now build.
 
 <success_criteria>
 - Discovery completion validated (or the user acknowledged gaps)
-- All session content read and synthesized into `Discovery/_pp-handoff.md`
+- A legacy root-level Discovery tree, if found with no canonical tree present, triggers a
+  one-time guided migration offer — never a silent ignore, never a hard error (D-02)
+- Unresolved parked questions are surfaced in the completion check and require explicit
+  user confirmation before proceeding — never a hard block (D-12)
+- All session content read and synthesized into `.planning/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

package/pp-core/workflows/discuss-phase/modes/chain.md

@@ -1,5 +1,10 @@
 # --chain mode — interactive discuss, then auto-advance
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
+
 > **Lazy-loaded.** Read this file from `workflows/discuss-phase.md` when
 > `--chain` is present in `$ARGUMENTS`, or when the parent's `auto_advance`
 > step needs to dispatch to plan-phase under `--auto`.

package/pp-core/workflows/discuss-phase.md

@@ -11,6 +11,10 @@ Extract implementation decisions that downstream agents need. Analyze the phase
 You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` is a placeholder — substitute the active `--ws <name>` (drop in flat mode); never emit it literally.
+</workstream_flag_substitution>
+
 <required_reading>
 @~/.claude/pp-core/references/domain-probes.md
 @~/.claude/pp-core/references/gate-prompts.md

package/pp-core/workflows/execute-phase.md

@@ -9,6 +9,10 @@ consumes: PLAN.md
 Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` is a placeholder — substitute the active `--ws <name>` (drop in flat mode); never emit it literally.
+</workstream_flag_substitution>
+
 <core_principle>
 Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results.
 </core_principle>

package/pp-core/workflows/new-milestone.md

@@ -4,6 +4,10 @@ Start a new milestone cycle for an existing project. Loads project context, gath
 
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
 <required_reading>
 
 Read all files referenced by the invoking prompt's execution_context before starting.

package/pp-core/workflows/plan-phase.md

@@ -9,6 +9,10 @@ consumes: CONTEXT.md
 Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates pp-phase-researcher, pp-planner, and pp-plan-checker agents with a revision loop (max 3 iterations).
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` is a placeholder — substitute the active `--ws <name>` (drop in flat mode); never emit it literally.
+</workstream_flag_substitution>
+
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 

package/pp-core/workflows/progress.md

@@ -2,6 +2,10 @@
 Check project progress, summarize recent work and what's ahead, then intelligently route to the next action — either executing an existing plan or creating the next one. Provides situational awareness before continuing work.
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>

package/pp-core/workflows/quick.md

@@ -12,6 +12,10 @@ With `--research` flag: spawns a focused research agent before planning. Investi
 Granular flags are composable: `--discuss --research --validate` gives the same result as `--full`.
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>

package/pp-core/workflows/resume-project.md

@@ -10,6 +10,10 @@ Use this workflow when:
 Instantly restore full project context so "Where were we?" has an immediate, complete answer.
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
 <required_reading>
 @~/.claude/pp-core/references/continuation-format.md
 </required_reading>

package/pp-core/workflows/ship.md

@@ -9,6 +9,10 @@ consumes: UAT.md
 Create a pull request from completed phase/milestone work, generate a rich PR body from planning artifacts, optionally run code review, and prepare for merge. Closes the plan → execute → verify → ship loop.
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>

package/pp-core/workflows/transition.md

@@ -34,6 +34,10 @@ Mark current phase complete and advance to next. This is the natural point where
 
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
 <process>
 
 <step name="load_project_state" priority="first">

package/pp-core/workflows/validate-phase.md

@@ -2,6 +2,10 @@
 Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
 </purpose>
 
+<workstream_flag_substitution>
+`${GSD_WS}` / `{GSD_WS}` in emitted "Next:" commands and `Skill()` args and agent dispatch prompts is a placeholder, not a shell variable — nothing expands it automatically. Substitute the active `--ws <name>`, or remove it entirely in flat mode. Never print the literal token in user-facing output. See `pp-core/references/workstream-flag.md` § Substitution rule.
+</workstream_flag_substitution>
+
 <required_reading>
 @~/.claude/pp-core/references/ui-brand.md
 </required_reading>

package/scripts/changeset/lint.cjs

@@ -24,20 +24,35 @@ const OPT_OUT_LABEL = 'no-changelog';
 
 // Files counted as "user-facing" — touching any of these requires either a
 // fragment or an explicit opt-out label. Test/CI/docs/lock files do not.
+// This list mirrors package.json's npm-shipped `files` array so that
+// everything reaching an end user's install is gate-covered. Two `files`
+// entries are deliberately EXCLUDED here: `LICENSE` and `NOTICE` — a
+// licence-text edit carries no changelog-worthy behavior change, so it is
+// not a gate trigger even though it ships in the tarball.
+//
+// `src/` is the load-bearing addition (BUS-02, 21-10): the compiled
+// `pp-core/bin/lib/*.cjs` output is gitignored, so a CLI behavior change
+// reaches users through `src/*.cts` alone. Before this widening such a
+// diff matched zero prefixes here (see historical bypass commit 3320c0a4).
 const USER_FACING_PREFIXES = [
   'bin/',
-  'gsd-core/',
+  'pp-core/',
   'agents/',
   'commands/',
   'hooks/',
-  'sdk/src/',
-  'sdk/prompts/',
+  'src/',
+  'pareto-skills/',
+  'assets/',
+  '.claude-plugin/',
+  'scripts/',
 ];
 
 // Exact-match user-facing files. Any direct edit to one of these without a
 // fragment also fails the lint — closes the bypass where a contributor edits
-// CHANGELOG.md directly to sneak past the new workflow.
-const USER_FACING_FILES = new Set(['CHANGELOG.md']);
+// CHANGELOG.md directly to sneak past the new workflow. `gemini-extension.json`
+// and `GEMINI.md` are the other two exact-match npm-shipped files (package.json
+// `files`) that are not already covered by a directory prefix above.
+const USER_FACING_FILES = new Set(['CHANGELOG.md', 'gemini-extension.json', 'GEMINI.md']);
 
 function isUserFacing(file) {
   if (USER_FACING_FILES.has(file)) return true;

package/scripts/lint-docs-required.cjs

@@ -38,8 +38,10 @@ function isFragmentPath(file) {
   return /^\.changeset\/[^/]+\.md$/.test(file) && !file.endsWith('/README.md');
 }
 
+// Phase 21 BUS-02/D-03: CONTRIBUTING.md is a gated deliverable in addition to
+// anything under docs/, so engine MRs that touch it are recognized by the gate.
 function isDocsFile(file) {
-  return file.startsWith(DOCS_PREFIX);
+  return file === 'CONTRIBUTING.md' || file.startsWith(DOCS_PREFIX);
 }
 
 // Per-fragment escape hatch: parse.cjs extracts `<!-- docs-exempt: <reason> -->`
@@ -193,9 +195,14 @@ function main() {
     for (const f of fragments.filter((f) => TRIGGERING_TYPES.has(f.type))) {
       process.stderr.write(`  ${f.path}  (type: ${f.type})\n`);
     }
-    process.stderr.write(`\nNo files under docs/ were modified in this PR.\n\n`);
     process.stderr.write(
-      `Update the relevant docs/ file(s), or add the \`${OPT_OUT_LABEL}\` label if this change\n`,
+      `\nNo gate-satisfying documentation file was modified in this PR — neither anything\n`,
+    );
+    process.stderr.write(
+      `under \`${DOCS_PREFIX}\` nor \`CONTRIBUTING.md\`.\n\n`,
+    );
+    process.stderr.write(
+      `Update a file under \`${DOCS_PREFIX}\` or \`CONTRIBUTING.md\`, or add the \`${OPT_OUT_LABEL}\` label if this change\n`,
     );
     process.stderr.write(
       `is genuinely internal-only (infrastructure, refactor, test-only). Per-fragment\n`,