fix(plan-phase): pass CONTEXT.md to all downstream agents

CONTEXT.md from /gsd:discuss-phase now flows through entire pipeline: - Loaded early in step 4, stored for all agent spawns - Researcher: constrains research scope (locked decisions vs discretion) - Planner: explicit guidance to honor locked decisions - Checker: new Context Compliance dimension to verify plans respect user vision - Revision: reminder to maintain context compliance during fixes Adds Dimension 7 (Context Compliance) to gsd-plan-checker: - Verifies locked decisions have implementing tasks - Flags if tasks contradict locked decisions - Flags if deferred ideas included in plans Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 14:49:10 -06:00
parent 5ee22e6256
commit 325713903b
2 changed files with 128 additions and 18 deletions
--- a/agents/gsd-plan-checker.md
+++ b/agents/gsd-plan-checker.md
@@ -21,10 +21,26 @@ Your job: Goal-backward verification of PLANS before execution. Start from what
 - Dependencies are broken or circular
 - Artifacts are planned but wiring between them isn't
 - Scope exceeds context budget (quality will degrade)
+- **Plans contradict user decisions from CONTEXT.md**

 You are NOT the executor (verifies code after execution) or the verifier (checks goal achievement in codebase). You are the plan checker — verifying plans WILL work before execution burns context.
 </role>

+<upstream_input>
+**CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
+
+| Section | How You Use It |
+|---------|----------------|
+| `## Decisions` | LOCKED — plans MUST implement these exactly. Flag if contradicted. |
+| `## Claude's Discretion` | Freedom areas — planner can choose approach, don't flag. |
+| `## Deferred Ideas` | Out of scope — plans must NOT include these. Flag if present. |
+
+If CONTEXT.md exists, add a verification dimension: **Context Compliance**
+- Do plans honor locked decisions?
+- Are deferred ideas excluded?
+- Are discretion areas handled appropriately?
+</upstream_input>
+
 <core_principle>
 **Plan completeness =/= Goal achievement**

@@ -235,6 +251,49 @@ issue:
  fix_hint: "Reframe as user-observable: 'User can log in', 'Session persists'"
 ```

+## Dimension 7: Context Compliance (if CONTEXT.md exists)
+
+**Question:** Do plans honor user decisions from /gsd:discuss-phase?
+
+**Only check this dimension if CONTEXT.md was provided in the verification context.**
+
+**Process:**
+1. Parse CONTEXT.md sections: Decisions, Claude's Discretion, Deferred Ideas
+2. For each locked Decision, find task(s) that implement it
+3. Verify no tasks implement Deferred Ideas (scope creep)
+4. Verify Discretion areas are handled (planner's choice is valid)
+
+**Red flags:**
+- Locked decision has no implementing task
+- Task contradicts a locked decision (e.g., user said "cards layout", plan says "table layout")
+- Task implements something from Deferred Ideas
+- Plan ignores user's stated preference
+
+**Example issue:**
+```yaml
+issue:
+  dimension: context_compliance
+  severity: blocker
+  description: "Plan contradicts locked decision: user specified 'card layout' but Task 2 implements 'table layout'"
+  plan: "01"
+  task: 2
+  user_decision: "Layout: Cards (from Decisions section)"
+  plan_action: "Create DataTable component with rows..."
+  fix_hint: "Change Task 2 to implement card-based layout per user decision"
+```
+
+**Example issue - scope creep:**
+```yaml
+issue:
+  dimension: context_compliance
+  severity: blocker
+  description: "Plan includes deferred idea: 'search functionality' was explicitly deferred"
+  plan: "02"
+  task: 1
+  deferred_idea: "Search/filtering (Deferred Ideas section)"
+  fix_hint: "Remove search task - belongs in future phase per user decision"
+```
+
 </verification_dimensions>

 <verification_process>
@@ -243,6 +302,8 @@ issue:

 Gather verification context from the phase directory and project state.

+**Note:** The orchestrator provides CONTEXT.md content in the verification prompt. If provided, parse it for locked decisions, discretion areas, and deferred ideas.
+
 ```bash
 # Normalize phase and find directory
 PADDED_PHASE=$(printf "%02d" $PHASE_ARG 2>/dev/null || echo "$PHASE_ARG")
@@ -261,7 +322,9 @@ ls "$PHASE_DIR"/*-BRIEF.md 2>/dev/null
 **Extract:**
 - Phase goal (from ROADMAP.md)
 - Requirements (decompose goal into what must be true)
- Phase context (from BRIEF.md if exists)
+- Phase context (from CONTEXT.md if provided by orchestrator)
+- Locked decisions (from CONTEXT.md Decisions section)
+- Deferred ideas (from CONTEXT.md Deferred Ideas section)

 ## Step 2: Load All Plans

@@ -738,6 +801,10 @@ Plan verification complete when:
 - [ ] Key links checked (wiring planned, not just artifacts)
 - [ ] Scope assessed (within context budget)
 - [ ] must_haves derivation verified (user-observable truths)
+- [ ] Context compliance checked (if CONTEXT.md provided):
+  - [ ] Locked decisions have implementing tasks
+  - [ ] No tasks contradict locked decisions
+  - [ ] Deferred ideas not included in plans
 - [ ] Overall status determined (passed | issues_found)
 - [ ] Structured issues returned (if any found)
 - [ ] Result returned to orchestrator
--- a/commands/gsd/plan-phase.md
+++ b/commands/gsd/plan-phase.md
@@ -106,7 +106,7 @@ grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null

 **If not found:** Error with available phases. **If found:** Extract phase number, name, description.

-## 4. Ensure Phase Directory Exists
+## 4. Ensure Phase Directory Exists and Load CONTEXT.md

 ```bash
 # PHASE is already normalized (08, 02.1, etc.) from step 2
@@ -117,8 +117,19 @@ if [ -z "$PHASE_DIR" ]; then
  mkdir -p ".planning/phases/${PHASE}-${PHASE_NAME}"
  PHASE_DIR=".planning/phases/${PHASE}-${PHASE_NAME}"
 fi
+
+# Load CONTEXT.md immediately - this informs ALL downstream agents
+CONTEXT_CONTENT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null)
 ```

+**CRITICAL:** Store `CONTEXT_CONTENT` now. It must be passed to:
+- **Researcher** — constrains what to research (locked decisions vs Claude's discretion)
+- **Planner** — locked decisions must be honored, not revisited
+- **Checker** — verifies plans respect user's stated vision
+- **Revision** — context for targeted fixes
+
+If CONTEXT.md exists, display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md`
+
 ## 5. Handle Research

 **If `--gaps` flag:** Skip research (gap closure uses VERIFICATION.md instead).
@@ -160,7 +171,7 @@ Proceed to spawn researcher

 ### Spawn gsd-phase-researcher

-Gather context for research prompt:
+Gather additional context for research prompt:

 ```bash
 # Get phase description from roadmap
@@ -172,8 +183,7 @@ REQUIREMENTS=$(cat .planning/REQUIREMENTS.md 2>/dev/null | grep -A100 "## Requir
 # Get prior decisions from STATE.md
 DECISIONS=$(grep -A20 "### Decisions Made" .planning/STATE.md 2>/dev/null)

-# Get phase context if exists
-PHASE_CONTEXT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null)
+# CONTEXT_CONTENT already loaded in step 4
 ```

 Fill research prompt and spawn:
@@ -185,19 +195,26 @@ Research how to implement Phase {phase_number}: {phase_name}
 Answer: "What do I need to know to PLAN this phase well?"
 </objective>

-<context>
+<phase_context>
+**IMPORTANT:** If CONTEXT.md exists below, it contains user decisions from /gsd:discuss-phase.
+
+- **Decisions section** = Locked choices — research THESE deeply, don't explore alternatives
+- **Claude's Discretion section** = Your freedom areas — research options, make recommendations
+- **Deferred Ideas section** = Out of scope — ignore completely
+
+{context_content}
+</phase_context>
+
+<additional_context>
 **Phase description:**
 {phase_description}

 **Requirements (if any):**
 {requirements}

-**Prior decisions:**
+**Prior decisions from STATE.md:**
 {decisions}
-
-**Phase context (if any):**
-{phase_context}
-</context>
+</additional_context>

 <output>
 Write research findings to: {phase_dir}/{phase}-RESEARCH.md
@@ -243,7 +260,7 @@ ROADMAP_CONTENT=$(cat .planning/ROADMAP.md)

 # Read optional files (empty string if missing)
 REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null)
-CONTEXT_CONTENT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null)
+# CONTEXT_CONTENT already loaded in step 4
 RESEARCH_CONTENT=$(cat "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null)

 # Gap closure files (only if --gaps mode)
@@ -280,6 +297,12 @@ Fill prompt with inlined content and spawn:
 {requirements_content}

 **Phase Context (if exists):**
+
+IMPORTANT: If phase context exists below, it contains USER DECISIONS from /gsd:discuss-phase.
+- **Decisions** = LOCKED — honor these exactly, do not revisit or suggest alternatives
+- **Claude's Discretion** = Your freedom — make implementation choices here
+- **Deferred Ideas** = Out of scope — do NOT include in this phase
+
 {context_content}

 **Research (if exists):**
@@ -352,14 +375,14 @@ Display:
 ◆ Spawning plan checker...
 ```

-Read plans and requirements for the checker:
+Read plans for the checker:

 ```bash
 # Read all plans in phase directory
 PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)

-# Read requirements (reuse from step 7 if available)
-REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null)
+# CONTEXT_CONTENT already loaded in step 4
+# REQUIREMENTS_CONTENT already loaded in step 7
 ```

 Fill checker prompt with inlined content and spawn:
@@ -376,6 +399,17 @@ Fill checker prompt with inlined content and spawn:
 **Requirements (if exists):**
 {requirements_content}

+**Phase Context (if exists):**
+
+IMPORTANT: If phase context exists below, it contains USER DECISIONS from /gsd:discuss-phase.
+Plans MUST honor these decisions. Flag as issue if plans contradict user's stated vision.
+
+- **Decisions** = LOCKED — plans must implement these exactly
+- **Claude's Discretion** = Freedom areas — plans can choose approach
+- **Deferred Ideas** = Out of scope — plans must NOT include these
+
+{context_content}
+
 </verification_context>

 <expected_output>
@@ -418,6 +452,7 @@ Read current plans for revision context:

 ```bash
 PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
+# CONTEXT_CONTENT already loaded in step 4
 ```

 Spawn gsd-planner with revision prompt:
@@ -434,11 +469,18 @@ Spawn gsd-planner with revision prompt:
 **Checker issues:**
 {structured_issues_from_checker}

+**Phase Context (if exists):**
+
+IMPORTANT: If phase context exists, revisions MUST still honor user decisions.
+
+{context_content}
+
 </revision_context>

 <instructions>
 Make targeted updates to address checker issues.
 Do NOT replan from scratch unless issues are fundamental.
+Revisions must still honor all locked decisions from Phase Context.
 Return what changed.
 </instructions>
 ```
@@ -513,12 +555,13 @@ Verification: {Passed | Passed with override | Skipped}
 - [ ] .planning/ directory validated
 - [ ] Phase validated against roadmap
 - [ ] Phase directory created if needed
+- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
 - [ ] Research completed (unless --skip-research or --gaps or exists)
- [ ] gsd-phase-researcher spawned if research needed
+- [ ] gsd-phase-researcher spawned with CONTEXT.md (constrains research scope)
 - [ ] Existing plans checked
- [ ] gsd-planner spawned with context (including RESEARCH.md if available)
+- [ ] gsd-planner spawned with context (CONTEXT.md + RESEARCH.md)
 - [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
- [ ] gsd-plan-checker spawned (unless --skip-verify)
+- [ ] gsd-plan-checker spawned with CONTEXT.md (verifies context compliance)
 - [ ] Verification passed OR user override OR max iterations with user decision
 - [ ] User sees status between agent spawns
 - [ ] User knows next steps (execute or review)