Merge pull request #1118 from trek-e/fix/evolution-block-visibility-1039

docs/ARCHITECTURE.md

@@ -358,7 +358,7 @@ Equivalent paths for other runtimes:
 
 ```
 .planning/
-├── PROJECT.md              # Project vision, constraints, decisions
+├── PROJECT.md              # Project vision, constraints, decisions, evolution rules
 ├── REQUIREMENTS.md         # Scoped requirements (v1/v2/out-of-scope)
 ├── ROADMAP.md              # Phase breakdown with status tracking
 ├── STATE.md                # Living memory: position, decisions, blockers, metrics

docs/FEATURES.md

@@ -75,7 +75,7 @@
 **Produces:**
 | Artifact | Description |
 |----------|-------------|
-| `PROJECT.md` | Project vision, constraints, technical decisions |
+| `PROJECT.md` | Project vision, constraints, technical decisions, evolution rules |
 | `REQUIREMENTS.md` | Scoped requirements with unique IDs (REQ-XX) |
 | `ROADMAP.md` | Phase breakdown with status tracking and requirement mapping |
 | `STATE.md` | Initial project state with position, decisions, metrics |

get-shit-done/templates/project.md

@@ -127,6 +127,8 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 <evolution>
 
 PROJECT.md evolves throughout the project lifecycle.
+These rules are embedded in the generated PROJECT.md (## Evolution section)
+and implemented by workflows/transition.md and workflows/complete-milestone.md.
 
 **After each phase transition:**
 1. Requirements invalidated? → Move to Out of Scope with reason

get-shit-done/workflows/execute-phase.md

@@ -215,6 +215,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        <files_to_read>
        Read these files at execution start using the Read tool:
        - {phase_dir}/{plan_file} (Plan)
+       - .planning/PROJECT.md (Project context — core value, requirements, evolution rules)
        - .planning/STATE.md (State)
        - .planning/config.json (Config, if exists)
        - ./CLAUDE.md (Project instructions, if exists — follow project-specific guidelines and coding conventions)

get-shit-done/workflows/new-milestone.md

@@ -54,6 +54,27 @@ Add/update:
 
 Update Active requirements section and "Last updated" footer.
 
+Ensure the `## Evolution` section exists in PROJECT.md. If missing (projects created before this feature), add it before the footer:
+
+```markdown
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+```
+
 ## 5. Update STATE.md
 
 ```markdown

get-shit-done/workflows/new-project.md

@@ -335,6 +335,27 @@ Initialize with any decisions made during questioning:
 *Last updated: [date] after initialization*
 ```
 
+**Evolution section** (include at the end of PROJECT.md, before the footer):
+
+```markdown
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+```
+
 Do not compress. Capture everything gathered.
 
 **Commit PROJECT.md:**