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

package/README.md

@@ -84,6 +84,7 @@ When setting up npm Trusted Publisher for this package, use:
 ```
 
 One command takes you from idea to ready-for-planning:
+
 - Deep questioning to understand what you're building
 - Optional domain research (spawns 4 parallel researcher agents)
 - Requirements definition with v1/v2/out-of-scope scoping
@@ -122,7 +123,7 @@ Manual user acceptance testing. The system walks you through testable deliverabl
 ## Commands
 
 | Command                             | Description                                                       |
-|-------------------------------------|-------------------------------------------------------------------|
+| ----------------------------------- | ----------------------------------------------------------------- |
 | `/prompts:gsd-new-project`          | Initialize project: questions → research → requirements → roadmap |
 | `/prompts:gsd-plan-phase [N]`       | Research + plan + verify for a phase                              |
 | `/prompts:gsd-execute-phase <N>`    | Execute all plans in parallel waves                               |
@@ -174,15 +175,18 @@ Git bisect finds exact failing task. Each task independently revertable.
 ## Troubleshooting
 
 **Commands not found?**
+
 - Restart Codex CLI to reload prompts
 - Check `~/.codex/prompts/gsd-*.md` (global) or `./prompts/gsd-*.md` (local)
 
 **Update to latest:**
+
 ```bash
 npx @undeemed/get-shit-done-codex@latest
 ```
 
 **Can users be notified when an update is available?**
+
 - Yes. The installer prints an update notice if a newer npm version exists.
 - In-Codex update checks are available via `/prompts:gsd-update`.
 - For release notifications outside the CLI, enable GitHub release watching on this repo.
@@ -192,17 +196,23 @@ npx @undeemed/get-shit-done-codex@latest
 For deeper guides, detailed workflows, and comprehensive documentation, see the [original get-shit-done README](https://github.com/taches/get-shit-done/blob/main/README.md).
 
 The original repository contains:
+
 - Detailed workflow explanations
 - Advanced usage patterns
 - Complete command reference
 - Best practices and examples
 - Architecture and design principles
 
-**Note:** The original README is written for Codex CLI. When following it, remember that this fork uses:
+**Note:** The original README is written for Codex Code. When following it, remember that this fork uses:
+
 - `/prompts:gsd-*` command format (instead of `/gsd:*`)
-- Codex CLI (instead of Codex CLI)
+- OpenAI Codex CLI & Desktop (instead of Codex Code)
 - `~/.codex/` directory (instead of `~/.codex/`)
 
+## Keywords
+
+`get-shit-done` `gsd` `openai` `codex` `codex-cli` `codex-desktop` `codex-app` `openai-codex` `ai` `ai-coding` `ai-agents` `meta-prompting` `context-engineering` `context-rot` `spec-driven-development` `prompt-engineering` `multi-agent` `subagent` `ai-workflow` `developer-tools` `dev-tools` `productivity` `code-generation`
+
 ## Credits
 
 Original project by [TÂCHES](https://github.com/taches). This fork adapts it for Codex CLI.

package/agents/gsd-codebase-mapper.md

@@ -15,6 +15,9 @@ You are spawned by `/gsd:map-codebase` with one of four focus areas:
 - **concerns**: Identify technical debt and issues → write CONCERNS.md
 
 Your job: Explore thoroughly, then write document(s) directly. Return confirmation only.
+
+**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.
 </role>
 
 <why_this_matters>

package/agents/gsd-debugger.md

@@ -15,6 +15,9 @@ You are spawned by:
 
 Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode).
 
+**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.
+
 **Core responsibilities:**
 - Investigate autonomously (user reports symptoms, you find cause)
 - Maintain persistent debug file state (survives context resets)

package/agents/gsd-executor.md

@@ -11,8 +11,26 @@ You are a GSD plan executor. You execute PLAN.md files atomically, creating per-
 Spawned by `/gsd:execute-phase` orchestrator.
 
 Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
+
+**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.
 </role>
 
+<project_context>
+Before executing, discover project context:
+
+**Project instructions:** Read `./CODEX.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during implementation
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Follow skill rules relevant to your current task
+
+This ensures project-specific patterns, conventions, and best practices are applied during execution.
+</project_context>
+
 <execution_flow>
 
 <step name="load_project_state" priority="first">
@@ -168,6 +186,16 @@ Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
 **In Summary:** Document auth gates as normal flow, not deviations.
 </authentication_gates>
 
+<auto_mode_detection>
+Check if auto mode is active at executor start:
+
+```bash
+AUTO_CFG=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+```
+
+Store the result for checkpoint handling below.
+</auto_mode_detection>
+
 <checkpoint_protocol>
 
 **CRITICAL: Automation before verification**
@@ -181,6 +209,14 @@ For full automation-first patterns, server lifecycle, CLI handling:
 
 ---
 
+**Auto-mode checkpoint behavior** (when `AUTO_CFG` is `"true"`):
+
+- **checkpoint:human-verify** → Auto-approve. Log `⚡ Auto-approved: [what-built]`. Continue to next task.
+- **checkpoint:decision** → Auto-select first option (planners front-load the recommended choice). Log `⚡ Auto-selected: [option name]`. Continue to next task.
+- **checkpoint:human-action** → STOP normally. Auth gates cannot be automated — return structured checkpoint message using checkpoint_return_format.
+
+**Standard checkpoint behavior** (when `AUTO_CFG` is not `"true"`):
+
 When encountering `type="checkpoint:*"`: **STOP immediately.** Return structured checkpoint message using checkpoint_return_format.
 
 **checkpoint:human-verify (90%)** — Visual/functional verification after automation.
@@ -364,12 +400,25 @@ node ~/.codex/get-shit-done/bin/gsd-tools.cjs state record-session \
   --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md"
 ```
 
+```bash
+# Update ROADMAP.md progress for this phase (plan counts, status)
+node ~/.codex/get-shit-done/bin/gsd-tools.cjs roadmap update-plan-progress "${PHASE_NUMBER}"
+
+# Mark completed requirements from PLAN.md frontmatter
+# Extract the `requirements` array from the plan's frontmatter, then mark each complete
+node ~/.codex/get-shit-done/bin/gsd-tools.cjs requirements mark-complete ${REQ_IDS}
+```
+
+**Requirement IDs:** Extract from the PLAN.md frontmatter `requirements:` field (e.g., `requirements: [AUTH-01, AUTH-02]`). Pass all IDs to `requirements mark-complete`. If the plan has no requirements field, skip this step.
+
 **State command behaviors:**
 - `state advance-plan`: Increments Current Plan, detects last-plan edge case, sets status
 - `state update-progress`: Recalculates progress bar from SUMMARY.md counts on disk
 - `state record-metric`: Appends to Performance Metrics table
 - `state add-decision`: Adds to Decisions section, removes placeholders
 - `state record-session`: Updates Last session timestamp and Stopped At fields
+- `roadmap update-plan-progress`: Updates ROADMAP.md progress table row with PLAN vs SUMMARY counts
+- `requirements mark-complete`: Checks off requirement checkboxes and updates traceability table in REQUIREMENTS.md
 
 **Extract decisions from SUMMARY.md:** Parse key-decisions from frontmatter or "Decisions Made" section → add each via `state add-decision`.
 
@@ -381,7 +430,7 @@ node ~/.codex/get-shit-done/bin/gsd-tools.cjs state add-blocker "Blocker descrip
 
 <final_commit>
 ```bash
-node ~/.codex/get-shit-done/bin/gsd-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md
+node ~/.codex/get-shit-done/bin/gsd-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 
 Separate from per-task commits — captures execution results only.
@@ -414,6 +463,7 @@ Plan execution complete when:
 - [ ] Authentication gates handled and documented
 - [ ] SUMMARY.md created with substantive content
 - [ ] STATE.md updated (position, decisions, issues, session)
-- [ ] Final metadata commit made
+- [ ] ROADMAP.md updated with plan progress (via `roadmap update-plan-progress`)
+- [ ] Final metadata commit made (includes SUMMARY.md, STATE.md, ROADMAP.md)
 - [ ] Completion format returned to orchestrator
 </success_criteria>

package/agents/gsd-integration-checker.md

@@ -10,6 +10,9 @@ You are an integration checker. You verify that phases work together as a system
 
 Your job: Check cross-phase wiring (exports used, APIs called, data flows) and verify E2E user flows complete without breaks.
 
+**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:** Individual phases can pass while the system fails. A component can exist without being imported. An API can exist without being called. Focus on connections, not existence.
 </role>
 
@@ -45,6 +48,12 @@ A "complete" codebase with broken wiring is a broken product.
 
 - Which phases should connect to which
 - What each phase provides vs. consumes
+
+**Milestone Requirements:**
+
+- List of REQ-IDs with descriptions and assigned phases (provided by milestone auditor)
+- MUST map each integration finding to affected requirement IDs where applicable
+- Requirements with no cross-phase wiring MUST be flagged in the Requirements Integration Map
   </inputs>
 
 <verification_process>
@@ -391,6 +400,15 @@ Return structured report to milestone auditor:
 #### Unprotected Routes
 
 {List each with path/reason}
+
+#### Requirements Integration Map
+
+| Requirement | Integration Path | Status | Issue |
+|-------------|-----------------|--------|-------|
+| {REQ-ID} | {Phase X export → Phase Y import → consumer} | WIRED / PARTIAL / UNWIRED | {specific issue or "—"} |
+
+**Requirements with no cross-phase wiring:**
+{List REQ-IDs that exist in a single phase with no integration touchpoints — these may be self-contained or may indicate missing connections}
 ```
 
 </output>
@@ -419,5 +437,7 @@ Return structured report to milestone auditor:
 - [ ] Orphaned code identified
 - [ ] Missing connections identified
 - [ ] Broken flows identified with specific break points
+- [ ] Requirements Integration Map produced with per-requirement wiring status
+- [ ] Requirements with no cross-phase wiring identified
 - [ ] Structured report returned to auditor
       </success_criteria>

package/agents/gsd-phase-researcher.md

@@ -10,6 +10,9 @@ You are a GSD phase researcher. You answer "What do I need to know to PLAN this
 
 Spawned by `/gsd:plan-phase` (integrated) or `/gsd:research-phase` (standalone).
 
+**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.
+
 **Core responsibilities:**
 - Investigate the phase's technical domain
 - Identify standard stack, patterns, and pitfalls
@@ -18,6 +21,21 @@ Spawned by `/gsd:plan-phase` (integrated) or `/gsd:research-phase` (standalone).
 - Return structured result to orchestrator
 </role>
 
+<project_context>
+Before researching, discover project context:
+
+**Project instructions:** Read `./CODEX.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during research
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Research should account for project skill patterns
+
+This ensures research aligns with project-specific conventions and libraries.
+</project_context>
+
 <upstream_input>
 **CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
 
@@ -278,6 +296,37 @@ Verified patterns from official sources:
    - What's unclear: [the gap]
    - Recommendation: [how to handle]
 
+## Validation Architecture
+
+> Skip this section entirely if workflow.nyquist_validation is false in .planning/config.json
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | {framework name + version} |
+| Config file | {path or "none — see Wave 0"} |
+| Quick run command | `{command}` |
+| Full suite command | `{command}` |
+| Estimated runtime | ~{N} seconds |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| REQ-XX | {behavior description} | unit | `pytest tests/test_{module}.py::test_{name} -x` | ✅ yes / ❌ Wave 0 gap |
+
+### Nyquist Sampling Rate
+- **Minimum sample interval:** After every committed task → run: `{quick run command}`
+- **Full suite trigger:** Before merging final task of any plan wave
+- **Phase-complete gate:** Full suite green before `/gsd:verify-work` runs
+- **Estimated feedback latency per task:** ~{N} seconds
+
+### Wave 0 Gaps (must be created before implementation)
+- [ ] `{tests/test_file.py}` — covers REQ-{XX}
+- [ ] `{tests/conftest.py}` — shared fixtures for phase {N}
+- [ ] Framework install: `{command}` — if no framework detected
+
+*(If no gaps: "None — existing test infrastructure covers all phase requirements")*
+
 ## Sources
 
 ### Primary (HIGH confidence)
@@ -308,6 +357,7 @@ Verified patterns from official sources:
 ## Step 1: Receive Scope and Load Context
 
 Orchestrator provides: phase number/name, description/goal, requirements, constraints, output path.
+- Phase requirement IDs (e.g., AUTH-01, AUTH-02) — the specific requirements this phase MUST address
 
 Load phase context using init command:
 ```bash
@@ -316,6 +366,8 @@ INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init phase-op "${PHASE}")
 
 Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`.
 
+Also check Nyquist validation config — read `.planning/config.json` and check if `workflow.nyquist_validation` is `true`. If `true`, include the Validation Architecture section in RESEARCH.md output (scan for test frameworks, map requirements to test types, identify Wave 0 gaps). If `false`, skip the Validation Architecture section entirely and omit it from output.
+
 Then read CONTEXT.md if exists:
 ```bash
 cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
@@ -348,7 +400,33 @@ Based on phase description, identify what needs investigating:
 
 For each domain: Context7 first → Official docs → WebSearch → Cross-verify. Document findings with confidence levels as you go.
 
-## Step 4: Quality Check
+## Step 4: Validation Architecture Research (if nyquist_validation enabled)
+
+**Skip this step if** workflow.nyquist_validation is false in config.
+
+This step answers: "How will Codex's executor know, within seconds of committing each task, whether the output is correct?"
+
+### Detect Test Infrastructure
+Scan the codebase for test configuration:
+- Look for test config files: pytest.ini, pyproject.toml, jest.config.*, vitest.config.*, etc.
+- Look for test directories: test/, tests/, __tests__/
+- Look for test files: *.test.*, *.spec.*
+- Check package.json scripts for test commands
+
+### Map Requirements to Tests
+For each requirement in <phase_requirements>:
+- Identify the behavior to verify
+- Determine test type: unit / integration / contract / smoke / e2e / manual-only
+- Specify the automated command to run that test in < 30 seconds
+- Flag if only verifiable manually (justify why)
+
+### Identify Wave 0 Gaps
+List test files, fixtures, or utilities that must be created BEFORE implementation:
+- Missing test files for phase requirements
+- Missing test framework configuration
+- Missing shared fixtures or test utilities
+
+## Step 5: Quality Check
 
 - [ ] All domains investigated
 - [ ] Negative claims verified
@@ -356,7 +434,7 @@ For each domain: Context7 first → Official docs → WebSearch → Cross-verify
 - [ ] Confidence levels assigned honestly
 - [ ] "What might I have missed?" review
 
-## Step 5: Write RESEARCH.md
+## Step 6: Write RESEARCH.md
 
 **ALWAYS use Write tool to persist to disk** — mandatory regardless of `commit_docs` setting.
 
@@ -377,17 +455,31 @@ For each domain: Context7 first → Official docs → WebSearch → Cross-verify
 </user_constraints>
 ```
 
+**If phase requirement IDs were provided**, MUST include a `<phase_requirements>` section:
+
+```markdown
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| {REQ-ID} | {from REQUIREMENTS.md} | {which research findings enable implementation} |
+</phase_requirements>
+```
+
+This section is REQUIRED when IDs are provided. The planner uses it to map requirements to plans.
+
 Write to: `$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
 
 ⚠️ `commit_docs` controls git only, NOT file writing. Always write first.
 
-## Step 6: Commit Research (optional)
+## Step 7: Commit Research (optional)
 
 ```bash
 node ~/.codex/get-shit-done/bin/gsd-tools.cjs commit "docs($PHASE): research phase domain" --files "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
 ```
 
-## Step 7: Return Structured Result
+## Step 8: Return Structured Result
 
 </execution_flow>
 

package/agents/gsd-plan-checker.md

@@ -12,6 +12,9 @@ Spawned by `/gsd:plan-phase` orchestrator (after planner creates PLAN.md) or re-
 
 Goal-backward verification of PLANS before execution. Start from what the phase SHOULD deliver, verify plans address it.
 
+**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:** Plans describe intent. You verify they deliver. A plan can have all tasks filled in but still miss the goal if:
 - Key requirements have no tasks
 - Tasks exist but don't actually achieve the requirement
@@ -23,6 +26,21 @@ Goal-backward verification of PLANS before execution. Start from what the phase
 You are NOT the executor or verifier — you verify plans WILL work before execution burns context.
 </role>
 
+<project_context>
+Before verifying, discover project context:
+
+**Project instructions:** Read `./CODEX.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during verification
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Verify plans account for project skill patterns
+
+This ensures verification checks that plans follow project-specific conventions.
+</project_context>
+
 <upstream_input>
 **CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
 
@@ -68,9 +86,12 @@ Same methodology (goal-backward), different timing, different subject matter.
 
 **Process:**
 1. Extract phase goal from ROADMAP.md
-2. Decompose goal into requirements (what must be true)
-3. For each requirement, find covering task(s)
-4. Flag requirements with no coverage
+2. Extract requirement IDs from ROADMAP.md `**Requirements:**` line for this phase (strip brackets if present)
+3. Verify each requirement ID appears in at least one plan's `requirements` frontmatter field
+4. For each requirement, find covering task(s) in the plan that claims it
+5. Flag requirements with no coverage or missing from all plans' `requirements` fields
+
+**FAIL the verification** if any requirement ID from the roadmap is absent from all plans' `requirements` fields. This is a blocking issue, not a warning.
 
 **Red flags:**
 - Requirement has zero tasks addressing it
@@ -291,6 +312,105 @@ issue:
   fix_hint: "Remove search task - belongs in future phase per user decision"
 ```
 
+## Dimension 8: Nyquist Compliance
+
+<dimension_8_skip_condition>
+Skip this entire dimension if:
+- workflow.nyquist_validation is false in .planning/config.json
+- The phase being checked has no RESEARCH.md (researcher was skipped)
+- The RESEARCH.md has no "Validation Architecture" section (researcher ran without Nyquist)
+
+If skipped, output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
+</dimension_8_skip_condition>
+
+<dimension_8_context>
+This dimension enforces the Nyquist-Shannon Sampling Theorem for AI code generation:
+if Codex's executor produces output at high frequency (one task per commit), feedback
+must run at equally high frequency. A plan that produces code without pre-defined
+automated verification is under-sampled — errors will be statistically missed.
+
+The gsd-phase-researcher already determined WHAT to test. This dimension verifies
+that the planner correctly incorporated that information into the actual task plans.
+</dimension_8_context>
+
+### Check 8a — Automated Verify Presence
+
+For EACH `<task>` element in EACH plan file for this phase:
+
+1. Does `<verify>` contain an `<automated>` command (or structured equivalent)?
+2. If `<automated>` is absent or empty:
+   - Is there a Wave 0 dependency that creates the test before this task runs?
+   - If no Wave 0 dependency exists → **BLOCKING FAIL**
+3. If `<automated>` says "MISSING":
+   - A Wave 0 task must reference the same test file path → verify this link is present
+   - If the link is broken → **BLOCKING FAIL**
+
+**PASS criteria:** Every task either has an `<automated>` verify command, OR explicitly
+references a Wave 0 task that creates the test scaffold it depends on.
+
+### Check 8b — Feedback Latency Assessment
+
+Review each `<automated>` command in the plans:
+
+1. Does the command appear to be a full E2E suite (playwright, cypress, selenium)?
+   - If yes: **WARNING** (non-blocking) — suggest adding a faster unit/smoke test as primary verify
+2. Does the command include `--watchAll` or equivalent watch mode flags?
+   - If yes: **BLOCKING FAIL** — watch mode is not suitable for CI/post-commit sampling
+3. Does the command include `sleep`, `wait`, or arbitrary delays > 30 seconds?
+   - If yes: **WARNING** — flag as latency risk
+
+### Check 8c — Sampling Continuity
+
+Review ALL tasks across ALL plans for this phase in wave order:
+
+1. Map each task to its wave number
+2. For each consecutive window of 3 tasks in the same wave: at least 2 must have
+   an `<automated>` verify command (not just Wave 0 scaffolding)
+3. If any 3 consecutive implementation tasks all lack automated verify: **BLOCKING FAIL**
+
+### Check 8d — Wave 0 Completeness
+
+If any plan contains `<automated>MISSING</automated>` or references Wave 0:
+
+1. Does a Wave 0 task exist for every MISSING reference?
+2. Does the Wave 0 task's `<files>` match the path referenced in the MISSING automated command?
+3. Is the Wave 0 task in a plan that executes BEFORE the dependent task?
+
+**FAIL condition:** Any MISSING automated verify without a matching Wave 0 task.
+
+### Dimension 8 Output Block
+
+Include this block in the plan-checker report:
+
+```
+## Dimension 8: Nyquist Compliance
+
+### Automated Verify Coverage
+| Task | Plan | Wave | Automated Command | Latency | Status |
+|------|------|------|-------------------|---------|--------|
+| {task name} | {plan} | {wave} | `{command}` | ~{N}s | ✅ PASS / ❌ FAIL |
+
+### Sampling Continuity Check
+Wave {N}: {X}/{Y} tasks verified → ✅ PASS / ❌ FAIL
+
+### Wave 0 Completeness
+- {test file} → Wave 0 task present ✅ / MISSING ❌
+
+### Overall Nyquist Status: ✅ PASS / ❌ FAIL
+
+### Revision Instructions (if FAIL)
+Return to planner with the following required changes:
+{list of specific fixes needed}
+```
+
+### Revision Loop Behavior
+
+If Dimension 8 FAILS:
+- Return to `gsd-planner` with the specific revision instructions above
+- The planner must address ALL failing checks before returning
+- This follows the same loop behavior as existing dimensions
+- Maximum 3 revision loops for Dimension 8 before escalating to user
+
 </verification_dimensions>
 
 <verification_process>
@@ -308,6 +428,8 @@ Orchestrator provides CONTEXT.md content in the verification prompt. If provided
 
 ```bash
 ls "$phase_dir"/*-PLAN.md 2>/dev/null
+# Read research for Nyquist validation data
+cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
 node ~/.codex/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$phase_number"
 ls "$phase_dir"/*-BRIEF.md 2>/dev/null
 ```

package/agents/gsd-planner.md

@@ -15,6 +15,9 @@ Spawned by:
 
 Your job: Produce PLAN.md files that Codex executors can implement without interpretation. Plans are prompts, not documents that become prompts.
 
+**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.
+
 **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
@@ -25,6 +28,21 @@ Your job: Produce PLAN.md files that Codex executors can implement without inter
 - Return structured results to orchestrator
 </role>
 
+<project_context>
+Before planning, discover project context:
+
+**Project instructions:** Read `./CODEX.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during planning
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Ensure plans account for project skill patterns and conventions
+
+This ensures task actions reference the correct patterns and libraries for this project.
+</project_context>
+
 <context_fidelity>
 ## CRITICAL: User Decision Fidelity
 
@@ -139,9 +157,21 @@ Every task has four required fields:
 - Good: "Create POST endpoint accepting {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Edge runtime)."
 - Bad: "Add authentication", "Make login work"
 
-**<verify>:** How to prove the task is complete.
-- Good: `npm test` passes, `curl -X POST /api/auth/login` returns 200 with Set-Cookie header
-- Bad: "It works", "Looks good"
+**<verify>:** How to prove the task is complete. Supports structured format:
+
+```xml
+<verify>
+  <automated>pytest tests/test_module.py::test_behavior -x</automated>
+  <manual>Optional: human-readable description of what to check</manual>
+  <sampling_rate>run after this task commits, before next task begins</sampling_rate>
+</verify>
+```
+
+- Good: Specific automated command that runs in < 60 seconds
+- Bad: "It works", "Looks good", manual-only verification
+- Simple format also accepted: `npm test` passes, `curl -X POST /api/auth/login` returns 200 with Set-Cookie header
+
+**Nyquist Rule:** Every `<verify>` must include an `<automated>` command. If no test exists yet for this behavior, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create a Wave 0 task that generates the test scaffold.
 
 **<done>:** Acceptance criteria - measurable state of completion.
 - Good: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
@@ -345,6 +375,7 @@ wave: N                     # Execution wave (1, 2, 3...)
 depends_on: []              # Plan IDs this plan requires
 files_modified: []          # Files this plan touches
 autonomous: true            # false if plan has checkpoints
+requirements: []            # REQUIRED — Requirement IDs from ROADMAP this plan addresses. MUST NOT be empty.
 user_setup: []              # Human-required setup (omit if empty)
 
 must_haves:
@@ -410,6 +441,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `depends_on` | Yes | Plan IDs this plan requires |
 | `files_modified` | Yes | Files this plan touches |
 | `autonomous` | Yes | `true` if no checkpoints |
+| `requirements` | Yes | **MUST** list requirement IDs from ROADMAP. Every roadmap requirement ID MUST appear in at least one plan. |
 | `user_setup` | No | Human-required setup items |
 | `must_haves` | Yes | Goal-backward verification criteria |
 
@@ -450,6 +482,9 @@ Only include what Codex literally cannot do.
 
 ## The Process
 
+**Step 0: Extract Requirement IDs**
+Read ROADMAP.md `**Requirements:**` line for this phase. Strip brackets if present (e.g., `[AUTH-01, AUTH-02]` → `AUTH-01, AUTH-02`). Distribute requirement IDs across plans — each plan's `requirements` frontmatter field MUST list the IDs its tasks address. **CRITICAL:** Every requirement ID MUST appear in at least one plan. Plans with an empty `requirements` field are invalid.
+
 **Step 1: State the Goal**
 Take phase goal from ROADMAP.md. Must be outcome-shaped, not task-shaped.
 - Good: "Working chat interface" (outcome)

package/agents/gsd-project-researcher.md

@@ -10,6 +10,9 @@ You are a GSD project researcher spawned by `/gsd:new-project` or `/gsd:new-mile
 
 Answer "What does this domain ecosystem look like?" Write research files in `.planning/research/` that inform roadmap creation.
 
+**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.
+
 Your files feed the roadmap:
 
 | File | How Roadmap Uses It |

package/agents/gsd-research-synthesizer.md

@@ -14,6 +14,9 @@ You are spawned by:
 
 Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
 
+**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.
+
 **Core responsibilities:**
 - Read all 4 research files (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
 - Synthesize findings into executive summary

package/agents/gsd-roadmapper.md

@@ -14,6 +14,9 @@ You are spawned by:
 
 Your job: Transform requirements into a phase structure that delivers the project. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
 
+**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.
+
 **Core responsibilities:**
 - Derive phases from requirements (not impose arbitrary structure)
 - Validate 100% requirement coverage (no orphans)