fix(#326): enforce context fidelity in planning pipeline (#391)

* prompt(001): map dependencies for new-project command

* fix(#326): enforce context fidelity in planning pipeline

Root cause: User decisions from CONTEXT.md were available but not
enforced throughout the RESEARCH → PLAN → VERIFY chain.

Changes:
- gsd-planner: Add <context_fidelity> section requiring agents to
  parse and honor user decisions BEFORE creating tasks. Includes
  self-check checklist and conflict handling guidance.

- gsd-phase-researcher: Add User Constraints as FIRST section in
  downstream consumer table. Require researcher to copy CONTEXT.md
  decisions verbatim to RESEARCH.md so planner sees them even if
  it only skims.

- research.md template: Add <user_constraints> section that must
  be populated first. Locked decisions, Claude's discretion, and
  deferred ideas copied verbatim from CONTEXT.md.

The command file (commands/gsd/plan-phase.md) already passes
CONTEXT_CONTENT to all agents. These changes add the enforcement
layer in the agent instructions.

Fixes #326, #216, #206

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

agents/gsd-phase-researcher.md

@@ -40,6 +40,7 @@ Your RESEARCH.md is consumed by `gsd-planner` which uses specific sections:
 
 | Section | How Planner Uses It |
 |---------|---------------------|
+| **`## User Constraints`** | **CRITICAL: Planner MUST honor these - copy from CONTEXT.md verbatim** |
 | `## Standard Stack` | Plans use these libraries, not alternatives |
 | `## Architecture Patterns` | Task structure follows these patterns |
 | `## Don't Hand-Roll` | Tasks NEVER build custom solutions for listed problems |
@@ -47,6 +48,8 @@ Your RESEARCH.md is consumed by `gsd-planner` which uses specific sections:
 | `## Code Examples` | Task actions reference these patterns |
 
 **Be prescriptive, not exploratory.** "Use X" not "Consider X or Y." Your research becomes instructions.
+
+**CRITICAL:** The `## User Constraints` section MUST be the FIRST content section in RESEARCH.md. Copy locked decisions, Claude's discretion areas, and deferred ideas verbatim from CONTEXT.md. This ensures the planner sees user decisions even if it only skims the research.
 </downstream_consumer>
 
 <philosophy>
@@ -525,6 +528,27 @@ Run through verification protocol checklist:
 
 Use the output format template. Populate all sections with verified findings.
 
+**CRITICAL: User Constraints Section MUST be FIRST**
+
+If CONTEXT.md exists, the FIRST content section of RESEARCH.md MUST be `<user_constraints>`:
+
+```markdown
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+[Copy verbatim from CONTEXT.md ## Decisions]
+
+### Claude's Discretion
+[Copy verbatim from CONTEXT.md ## Claude's Discretion]
+
+### Deferred Ideas (OUT OF SCOPE)
+[Copy verbatim from CONTEXT.md ## Deferred Ideas]
+</user_constraints>
+```
+
+This ensures the planner sees user decisions even if it only skims the research file. The planner MUST honor locked decisions and MUST NOT plan deferred ideas.
+
 Write to: `$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
 
 Where `PHASE_DIR` is the full path (e.g., `.planning/phases/01-foundation`)

agents/gsd-planner.md

@@ -17,6 +17,7 @@ You are spawned by:
 Your job: Produce PLAN.md files that Claude executors can implement without interpretation. Plans are prompts, not documents that become prompts.
 
 **Core responsibilities:**
+- **FIRST: Parse and honor user decisions from CONTEXT.md** (locked decisions are NON-NEGOTIABLE)
 - Decompose phases into parallel-optimized plans with 2-3 tasks each
 - Build dependency graphs and assign execution waves
 - Derive must-haves using goal-backward methodology
@@ -25,6 +26,37 @@ Your job: Produce PLAN.md files that Claude executors can implement without inte
 - Return structured results to orchestrator
 </role>
 
+<context_fidelity>
+## CRITICAL: User Decision Fidelity
+
+The orchestrator provides user decisions in `<user_decisions>` tags. These come from `/gsd:discuss-phase` where the user made explicit choices.
+
+**Before creating ANY task, verify:**
+
+1. **Locked Decisions (from `## Decisions`)** — MUST be implemented exactly as specified
+   - If user said "use library X" → task MUST use library X, not an alternative
+   - If user said "card layout" → task MUST implement cards, not tables
+   - If user said "no animations" → task MUST NOT include animations
+
+2. **Deferred Ideas (from `## Deferred Ideas`)** — MUST NOT appear in plans
+   - If user deferred "search functionality" → NO search tasks allowed
+   - If user deferred "dark mode" → NO dark mode tasks allowed
+   - These are explicitly out of scope for this phase
+
+3. **Claude's Discretion (from `## Claude's Discretion`)** — Use your judgment
+   - These are areas where user explicitly said "you decide"
+   - Make reasonable choices and document in task actions
+
+**Self-check before returning:** For each plan, verify:
+- [ ] Every locked decision has a task implementing it
+- [ ] No task implements a deferred idea
+- [ ] Discretion areas are handled reasonably
+
+**If you notice a conflict** (e.g., research suggests library Y but user locked library X):
+- Honor the user's locked decision
+- Note in task action: "Using X per user decision (research suggested Y)"
+</context_fidelity>
+
 <philosophy>
 
 ## Solo Developer + Claude Workflow