@undeemed/get-shit-done-codex 1.20.3 → 1.20.7

package/agents/gsd-verifier.md

@@ -10,6 +10,9 @@ You are a GSD phase verifier. You verify that a phase achieved its GOAL, not jus
 
 Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Codex SAID it did. You verify what ACTUALLY exists in the code. These often differ.
 </role>
 
@@ -233,17 +236,31 @@ Status: WIRED (state displayed) | NOT_WIRED (state exists, not rendered)
 
 ## Step 6: Check Requirements Coverage
 
-If REQUIREMENTS.md has requirements mapped to this phase:
+**6a. Extract requirement IDs from PLAN frontmatter:**
 
 ```bash
-grep -E "Phase $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
+grep -A5 "^requirements:" "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ```
 
-For each requirement: parse description → identify supporting truths/artifacts → determine status.
+Collect ALL requirement IDs declared across plans for this phase.
+
+**6b. Cross-reference against REQUIREMENTS.md:**
+
+For each requirement ID from plans:
+1. Find its full description in REQUIREMENTS.md (`**REQ-ID**: description`)
+2. Map to supporting truths/artifacts verified in Steps 3-5
+3. Determine status:
+   - ✓ SATISFIED: Implementation evidence found that fulfills the requirement
+   - ✗ BLOCKED: No evidence or contradicting evidence
+   - ? NEEDS HUMAN: Can't verify programmatically (UI behavior, UX quality)
+
+**6c. Check for orphaned requirements:**
+
+```bash
+grep -E "Phase $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
+```
 
-- ✓ SATISFIED: All supporting truths verified
-- ✗ BLOCKED: One or more supporting truths failed
-- ? NEEDS HUMAN: Can't verify programmatically
+If REQUIREMENTS.md maps additional IDs to this phase that don't appear in ANY plan's `requirements` field, flag as **ORPHANED** — these requirements were expected but no plan claimed them. ORPHANED requirements MUST appear in the verification report.
 
 ## Step 7: Scan for Anti-Patterns
 
@@ -396,8 +413,8 @@ human_verification: # Only if status: human_needed
 
 ### Requirements Coverage
 
-| Requirement | Status | Blocking Issue |
-| ----------- | ------ | -------------- |
+| Requirement | Source Plan | Description | Status | Evidence |
+| ----------- | ---------- | ----------- | ------ | -------- |
 
 ### Anti-Patterns Found
 

package/commands/gsd/add-phase.md

@@ -19,11 +19,15 @@ Routes to the add-phase workflow which handles:
 </objective>
 
 <execution_context>
-@.planning/ROADMAP.md
-@.planning/STATE.md
 @~/.codex/get-shit-done/workflows/add-phase.md
 </execution_context>
 
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
 <process>
 **Follow the add-phase workflow** from `@~/.codex/get-shit-done/workflows/add-phase.md`.
 

package/commands/gsd/add-todo.md

@@ -23,10 +23,15 @@ Routes to the add-todo workflow which handles:
 </objective>
 
 <execution_context>
-@.planning/STATE.md
 @~/.codex/get-shit-done/workflows/add-todo.md
 </execution_context>
 
+<context>
+Arguments: $ARGUMENTS (optional todo description)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
 <process>
 **Follow the add-todo workflow** from `@~/.codex/get-shit-done/workflows/add-todo.md`.
 

package/commands/gsd/audit-milestone.md

@@ -23,13 +23,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
 <context>
 Version: $ARGUMENTS (optional — defaults to current milestone)
 
-**Original Intent:**
-@.planning/PROJECT.md
-@.planning/REQUIREMENTS.md
-
-**Planned Work:**
-@.planning/ROADMAP.md
-@.planning/config.json (if exists)
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
 
 **Completed Work:**
 Glob: .planning/phases/*/*-SUMMARY.md

package/commands/gsd/check-todos.md

@@ -21,11 +21,15 @@ Routes to the check-todos workflow which handles:
 </objective>
 
 <execution_context>
-@.planning/STATE.md
-@.planning/ROADMAP.md
 @~/.codex/get-shit-done/workflows/check-todos.md
 </execution_context>
 
+<context>
+Arguments: $ARGUMENTS (optional area filter)
+
+Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
+</context>
+
 <process>
 **Follow the check-todos workflow** from `@~/.codex/get-shit-done/workflows/check-todos.md`.
 

package/commands/gsd/debug.md

@@ -129,7 +129,9 @@ Continue debugging {slug}. Evidence is in the debug file.
 </objective>
 
 <prior_state>
-Debug file: @.planning/debug/{slug}.md
+<files_to_read>
+- .planning/debug/{slug}.md (Debug session state)
+</files_to_read>
 </prior_state>
 
 <checkpoint_response>

package/commands/gsd/discuss-phase.md

@@ -32,11 +32,7 @@ Extract implementation decisions that downstream agents need — researcher and
 <context>
 Phase number: $ARGUMENTS (required)
 
-**Load project state:**
-@.planning/STATE.md
-
-**Load roadmap:**
-@.planning/ROADMAP.md
+Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
 </context>
 
 <process>

package/commands/gsd/execute-phase.md

@@ -32,8 +32,7 @@ Phase: $ARGUMENTS
 **Flags:**
 - `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
 
-@.planning/ROADMAP.md
-@.planning/STATE.md
+Context files are resolved inside the workflow via `gsd-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
 </context>
 
 <process>

package/commands/gsd/insert-phase.md

@@ -23,8 +23,7 @@ Purpose: Handle urgent work discovered during execution without renumbering enti
 <context>
 Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
 
-@.planning/ROADMAP.md
-@.planning/STATE.md
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
 </context>
 
 <process>

package/commands/gsd/list-phase-assumptions.md

@@ -23,11 +23,7 @@ Output: Conversational output only (no file creation) - ends with "What do you t
 <context>
 Phase number: $ARGUMENTS (required)
 
-**Load project state first:**
-@.planning/STATE.md
-
-**Load roadmap:**
-@.planning/ROADMAP.md
+Project state and roadmap are loaded in-workflow using targeted reads.
 </context>
 
 <process>

package/commands/gsd/new-milestone.md

@@ -35,14 +35,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 <context>
 Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
-**Load project context:**
-@.planning/PROJECT.md
-@.planning/STATE.md
-@.planning/MILESTONES.md
-@.planning/config.json
-
-**Load milestone context (if exists, from /gsd:discuss-milestone):**
-@.planning/MILESTONE-CONTEXT.md
+Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
 </context>
 
 <process>

package/commands/gsd/pause-work.md

@@ -19,10 +19,13 @@ Routes to the pause-work workflow which handles:
 </objective>
 
 <execution_context>
-@.planning/STATE.md
 @~/.codex/get-shit-done/workflows/pause-work.md
 </execution_context>
 
+<context>
+State and phase progress are gathered in-workflow with targeted reads.
+</context>
+
 <process>
 **Follow the pause-work workflow** from `@~/.codex/get-shit-done/workflows/pause-work.md`.
 

package/commands/gsd/plan-milestone-gaps.md

@@ -25,13 +25,7 @@ One command creates all fix phases — no manual `/gsd:add-phase` per gap.
 **Audit results:**
 Glob: .planning/v*-MILESTONE-AUDIT.md (use most recent)
 
-**Original intent (for prioritization):**
-@.planning/PROJECT.md
-@.planning/REQUIREMENTS.md
-
-**Current state:**
-@.planning/ROADMAP.md
-@.planning/STATE.md
+Original intent and current planning state are loaded on demand inside the workflow.
 </context>
 
 <process>

package/commands/gsd/quick.md

@@ -30,8 +30,9 @@ Quick mode is the same system with a shorter path:
 </execution_context>
 
 <context>
-@.planning/STATE.md
 $ARGUMENTS
+
+Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
 </context>
 
 <process>

package/commands/gsd/remove-phase.md

@@ -22,8 +22,7 @@ Output: Phase deleted, all subsequent phases renumbered, git commit as historica
 <context>
 Phase: $ARGUMENTS
 
-@.planning/ROADMAP.md
-@.planning/STATE.md
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted reads.
 </context>
 
 <process>

package/commands/gsd/research-phase.md

@@ -37,7 +37,7 @@ Normalize phase input in step 1 before any directory lookups.
 INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init phase-op "$ARGUMENTS")
 ```
 
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`.
+Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
 
 Resolve researcher model:
 ```bash
@@ -64,15 +64,12 @@ ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
 
 ## 3. Gather Phase Context
 
-```bash
-# Phase section already loaded in PHASE_INFO
-echo "$PHASE_INFO" | jq -r '.section'
-cat .planning/REQUIREMENTS.md 2>/dev/null
-cat .planning/phases/${PHASE}-*/*-CONTEXT.md 2>/dev/null
-grep -A30 "### Decisions Made" .planning/STATE.md 2>/dev/null
-```
+Use paths from INIT (do not inline file contents in orchestrator context):
+- `requirements_path`
+- `context_path`
+- `state_path`
 
-Present summary with phase description, requirements, prior decisions.
+Present summary with phase description and what files the researcher will load.
 
 ## 4. Spawn gsd-phase-researcher Agent
 
@@ -101,12 +98,15 @@ Research implementation approach for Phase {phase_number}: {phase_name}
 Mode: ecosystem
 </objective>
 
-<context>
+<files_to_read>
+- {requirements_path} (Requirements)
+- {context_path} (Phase context from discuss-phase, if exists)
+- {state_path} (Prior project decisions and blockers)
+</files_to_read>
+
+<additional_context>
 **Phase description:** {phase_description}
-**Requirements:** {requirements_list}
-**Prior decisions:** {decisions_if_any}
-**Phase context:** {context_md_content}
-</context>
+</additional_context>
 
 <downstream_consumer>
 Your RESEARCH.md will be loaded by `/gsd:plan-phase` which uses specific sections:
@@ -158,7 +158,9 @@ Continue research for Phase {phase_number}: {phase_name}
 </objective>
 
 <prior_state>
-Research file: @.planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
+<files_to_read>
+- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
+</files_to_read>
 </prior_state>
 
 <checkpoint_response>

package/commands/gsd/verify-work.md

@@ -29,8 +29,7 @@ Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")
 - If not provided: Check for active sessions or prompt for phase
 
-@.planning/STATE.md
-@.planning/ROADMAP.md
+Context files are resolved inside the workflow (`init verify-work`) and delegated via `<files_to_read>` blocks.
 </context>
 
 <process>