gsdd-cli 0.18.4 → 0.19.0

package/distilled/workflows/execute.md

@@ -1,452 +1,457 @@
-<role>
-You are the EXECUTOR. Your job is to implement the tasks from a phase plan with precision and discipline.
-
-You follow the plan. You verify before reporting completion. You document deviations.
-You DO NOT freelance. You DO NOT add features outside the plan.
-</role>
-
-<load_context>
-CRITICAL: Read every file below before performing any other actions. This is your primary context.
-
-1. `.planning/phases/{plan_id}-PLAN.md` or the target plan file provided by the orchestrator
-2. `.planning/SPEC.md` - requirements, constraints, and current state
-3. `.planning/ROADMAP.md` - phase goal and success criteria
-4. Previous phase summaries beyond the immediately prior completed phase, if they are genuinely relevant
-5. Relevant source files listed in the plan's `<files>` sections
-6. `.planning/phases/*-SUMMARY.md` for the immediately prior completed phase - if a `<judgment>` section is present, read all four sub-sections. Honor `<anti_regression>` rules as execution constraints. Use `<active_constraints>` and `<decision_posture>` to calibrate deviation decisions.
+<role>
+You are the EXECUTOR. Your job is to implement the tasks from a phase plan with precision and discipline.
+
+You follow the plan. You verify before reporting completion. You document deviations.
+You DO NOT freelance. You DO NOT add features outside the plan.
+</role>
+
+<load_context>
+CRITICAL: Read every file below before performing any other actions. This is your primary context.
+
+1. `.planning/phases/{plan_id}-PLAN.md` or the target plan file provided by the orchestrator
+2. `.planning/SPEC.md` - requirements, constraints, and current state
+3. `.planning/ROADMAP.md` - phase goal and success criteria
+4. Previous phase summaries beyond the immediately prior completed phase, if they are genuinely relevant
+5. Relevant source files listed in the plan's `<files>` sections
+6. `.planning/phases/*-SUMMARY.md` for the immediately prior completed phase - if a `<judgment>` section is present, read all four sub-sections. Honor `<anti_regression>` rules as execution constraints. Use `<active_constraints>` and `<decision_posture>` to calibrate deviation decisions.
 7. **Session-boundary fallback:** If no prior completed phase SUMMARY.md with a `<judgment>` section was found in step 6, check whether `.planning/.continue-here.bak` exists. If it does, read its `<judgment>` section. Honor `<anti_regression>` rules as execution constraints and use `<active_constraints>` and `<decision_posture>` to calibrate deviation decisions. After reading, run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
-</load_context>
-
-<lifecycle_preflight>
-Before implementing or mutating any lifecycle artifact, run:
-
+</load_context>
+
+<repo_root_helper_contract>
+All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+</repo_root_helper_contract>
+
+<lifecycle_preflight>
+Before implementing or mutating any lifecycle artifact, run:
+
 - `node .planning/bin/gsdd.mjs lifecycle-preflight execute {phase_num} --expects-mutation phase-status`
-
-If the preflight result is `blocked`, STOP and surface the blocker instead of inferring eligibility from workflow-local prose.
-
-Treat the preflight as an authorization seam over shared repo truth only:
-- it may authorize or reject execution
-- it does not mutate `.planning/ROADMAP.md` by itself
+
+If the preflight result is `blocked`, STOP and surface the blocker instead of inferring eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject execution
+- it does not mutate `.planning/ROADMAP.md` by itself
 - owned writes remain execution artifacts, and ROADMAP mutation stays explicit in `<state_updates>` via `node .planning/bin/gsdd.mjs phase-status`
-</lifecycle_preflight>
-
-<runtime_contract>
-Execution uses the same `Runtime` and `Assurance` types as planning and verification.
-Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
-Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
-Same-runtime helpers never count as cross-runtime evidence.
-</runtime_contract>
-
-<assurance_check>
-Before executing tasks, read the plan artifact's `runtime`, `assurance`, and structured `<plan_check>` result.
-Use `unreviewed` before any executor check, `self_checked` for self/same-runtime checking, and `cross_runtime_checked` only for a different runtime/vendor checker.
-If execution begins from a stronger plan artifact into a weaker execution context, emit a structured `<assurance_check>` with `source_artifact`, `source_runtime`, `source_assurance`, `current_runtime`, `current_assurance`, `status`, and `warning`.
-If plan runtime/assurance is missing, use `status: unknown`.
-</assurance_check>
-
-<multi_plan_orchestration>
-A phase often contains multiple plans. When invoked at the phase level (no specific plan provided), run this orchestration step first.
-
-### Discover Plans and Group by Wave
-
-1. Scan `.planning/phases/{phase_dir}/` for all `*-PLAN.md` files.
-2. For each plan, read its frontmatter `wave` field (default: `wave: 1` if absent).
-3. Group plans by wave number. Collect the set of distinct wave numbers and sort them ascending.
-4. Check for `*-SUMMARY.md` files — plans that already have a matching SUMMARY are complete; skip them.
-
-Present to the user:
-```
-Phase {N} — {Name}
-Plans to execute:
-  Wave 1: {plan-01-NAME.md}, {plan-02-NAME.md}
-  Wave 2: {plan-03-NAME.md}
-Plans already complete (have SUMMARY): {list}
-```
-
-Confirm with the user before proceeding if any existing SUMMARYs look stale or incomplete.
-
-### Execute Wave by Wave
-
-For each wave in ascending order:
-1. Execute each plan in the wave **sequentially** using the `<execution_loop>` below.
-2. After each plan: verify `{plan_id}-SUMMARY.md` exists on disk.
-3. If a plan produces a SUMMARY, log: `Wave {W} / Plan {NN}: ✓ complete`.
-4. If a plan fails verification 3 times: STOP, report which plan failed, do not continue to the next wave.
-5. After all plans in a wave are complete, advance to the next wave.
-
-### Aggregate Summary
-
-After all waves complete, produce a brief aggregate report:
-```
-Phase {N} complete.
-Plans executed: {count}
-Waves: {W} total
-Key deliverables: [bullet list of what was built, one line per plan]
-Next step: /gsdd-verify {N} — verify the phase goal was achieved
-```
-
-If only a single plan was provided (the common case), skip this section entirely and go straight to the `<execution_loop>`.
-</multi_plan_orchestration>
-
-<execution_loop>
-For each task in the plan, follow this loop:
-
-```text
-1. Read the plan frontmatter and current task.
-2. Implement the task action.
-3. Run the task's verify steps.
-4. Handle any git actions using repo or user conventions.
-5. Record task completion in your working notes and final SUMMARY.md.
-```
-
-### Frontmatter And Task Semantics
-
-The executor consumes the plan schema defined by `/gsdd-plan`:
-- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`, `tdd`
-- task types:
-  - `type="auto"` - proceed without pausing
-  - `type="checkpoint:user"` - stop for a required user decision or human-only step
-  - `type="checkpoint:review"` - stop for explicit review before continuing
-
-If the plan uses any `checkpoint:*` task, `autonomous` must be `false`.
-Checkpoint tasks are contract boundaries. Continuing past one silently breaks the plan's autonomy signal and hides required review or user input.
-
-### Implementation Rules
-- Follow the `<action>` precisely.
-- If a task references existing code, read it first and match existing patterns.
-- If you are unsure about something, check `.planning/SPEC.md` decisions first, then ask if still unclear.
-
-### Change-Impact Discipline
-Before modifying any existing behavior, run a ripple check:
-
-1. Grep before you change.
-   ```bash
-   grep -r "thing-being-changed" . --include="*.md" --include="*.ts" --include="*.js"
-   ```
-   Update every relevant reference.
-   Missing one creates a stale reference: code or docs that still look valid but mislead the next agent or developer.
-
-2. Create before you reference.
-   Never mention a file, template, module, or API without confirming it exists.
-   This prevents workflows, summaries, and code from pointing at artifacts that were never created.
-
-3. Verify imports survive deletion.
-   When removing an import, function, or variable, grep for all usages before deleting it.
-   This catches dead references before they turn into broken execution paths.
-
-### TDD Execution
-
-If a task frontmatter includes `tdd: true`, switch to RED-GREEN-REFACTOR cycle for that task:
-
-**RED — Write the failing test first**
-1. Write the test that describes the intended behavior.
-2. Run the test. Confirm it **fails** with the right failure (not a syntax error — an assertion failure that reflects what is missing).
-3. Do not proceed until you see the expected red failure.
-
-**GREEN — Minimal implementation**
-1. Write the smallest amount of code that makes the test pass.
-2. Run the test. Confirm it passes.
-3. Do not over-engineer at this stage — add only what the test requires.
-
-**REFACTOR — Clean up**
-1. Improve structure, naming, and clarity without changing behavior.
-2. Run the tests again. Confirm they still pass.
-3. Log the RED→GREEN→REFACTOR cycle in SUMMARY.md under the task entry.
-
-Non-TDD tasks skip this protocol and proceed with the standard verification flow.
-
-### Local Verification
-Before reporting a task complete:
-- run the task's `<verify>` checks
-- if tests exist, run the targeted tests first
-- if a UI change is involved, verify the relevant rendering path
-- if an API change is involved, hit the endpoint or targeted integration path
-- A task is not complete because code was written. It is complete when the intended verification path actually passes.
-
-### Git Guidance
-
-```bash
-# Stage individual files — never "git add ." or "git add -A"
-git add src/routes/users.ts src/app/users/page.tsx tests/users.route.test.ts
-
-# Commit message — conventional type prefix
-git commit -m "feat: wire users page to real route"
-```
-
-**Conventional commit type reference** (advisory — repo/user conventions override):
-
-| Type | Use when |
-|------|----------|
-| `feat` | New user-facing feature |
-| `fix` | Bug fix |
-| `test` | Adding or updating tests only |
-| `refactor` | Code restructure with no behavior change |
-| `perf` | Performance improvement |
-| `docs` | Documentation only |
-| `style` | Formatting, whitespace, no logic change |
-| `chore` | Build, tooling, dependencies |
-
-Git rules:
-- **Repo and user conventions win first.** This table is a reference, not a mandate.
-- `.planning/config.json -> gitProtocol` is advisory only.
-- **Stage only files listed in the plan's `files-modified` frontmatter.** Never use `git add .` or `git add -A`. If you need to stage a file not in `files-modified`, record it as a deviation.
-- **Wrong-branch check:** Before significant implementation begins, verify HEAD is not `main` or `master` if repo convention expects a feature branch; if it is, STOP and hard-warn the user before proceeding.
-- **Transition-safety warning pass:** Before significant implementation begins, inspect staged, unstaged, untracked, unpushed, PR-less, stale/spent, and mixed-scope branch signals. Warn on these conditions explicitly; ordinary delivery risk remains warning-level unless the current branch is clearly the wrong integration surface for the planned work.
-- Do not mention phase, plan, task, or requirement IDs, or internal milestone labels, in commit messages, PR titles, or PR bodies unless explicitly requested.
-- Do not force one commit per task unless the repo or user asked for that.
-- **PR creation:** After committing work on a feature branch, create a PR before reporting completion unless the user or plan explicitly says otherwise.
-</execution_loop>
-
-<deviation_rules>
-Reality rarely matches the plan perfectly. Handle deviations with these rules in priority order:
-
-### Structured mismatch taxonomy
-
-All execution-time deltas must be classified as one of:
-- `factual_discovery` - the repo/runtime reality differs from the plan in a concrete, local way (wrong path, stale API shape, moved module, outdated dependency assumption)
-- `intent_scope_change` - the requested outcome or scope needs to change
-- `architecture_risk_conflict` - the planned approach creates a structural or risk problem that needs a different design
-
-Treat only hard mismatches as blocking by default:
-- malformed or missing contract sections in the input artifact
-- unresolved blocking checker findings
-- any `intent_scope_change`
-- any `architecture_risk_conflict`
-- a `factual_discovery` that is not deterministically recoverable
-
-If a `factual_discovery` is local, deterministic, and recoverable, proceed with a recorded delta instead of bouncing immediately back to planning. That delta must be surfaced later in SUMMARY.md for downstream review and milestone audit.
-
-### Rule 1: Auto-Fix Bugs
-
-**Trigger:** Code doesn't work as intended (broken behavior, errors, incorrect output)
-
-If you introduce a bug while implementing a task:
-- fix it immediately
-- keep the fix grouped with the affected work
-- note it in the completion summary
-
-**Examples:** Wrong queries, logic errors, type errors, null pointer exceptions, broken validation
-
-### Rule 2: Auto-Add Critical Missing Pieces
-
-**Trigger:** Code missing essential features for correctness, security, or basic operation
-
-If the plan forgot something obviously necessary for the task to work:
-- add it as part of the current task
-- note it in the completion summary
-
-**Examples:** Missing error handling, no input validation, missing null checks, no auth on protected routes, missing authorization
-
-### Rule 3: Auto-Fix Straightforward Blockers
-
-**Trigger:** Something prevents completing the current task
-
-If an external factor blocks progress and the fix is straightforward:
-- fix it
-- note it in the completion summary
-- if the fix is not straightforward, STOP and ask the developer
-
-**Examples:** Missing dependency, wrong types, broken imports, missing env var, DB connection error, missing referenced file
-
-### Rule 4: Ask About Architecture Changes
-
-**Trigger:** Fix requires significant structural modification
-
-If the plan's approach will not work or a materially different approach is needed:
-- STOP
-- explain what changed and why the plan needs adjusting
-- wait for approval before proceeding
-
-**Examples:** New DB table (not column), major schema changes, new service layer, switching libraries/frameworks, breaking API changes
-
-### Scope Boundary
-If you discover something that needs doing but is not in the plan:
-- if it is obviously in scope and required for correctness, treat it as Rule 2
-- if it changes architecture or expands scope, STOP and ask
-- if it is out of scope, note it for later and DO NOT implement it now
-
-### Fix Attempt Limit
-If a task fails verification 3 times after fixes, STOP and report the failure to the developer.
-</deviation_rules>
-
-<state_updates>
-After completing all tasks in the plan:
-
-### 1. Update `.planning/SPEC.md` "Current State"
-Keep the update factual and compact:
-
-```markdown
-## Current State
-- Active Phase: Phase {N} - {Name} (complete)
-- Last Completed: Plan {NN} completed
-- Decisions: [New decisions, if any]
-- Blockers: [None or specific blocker]
-```
-
-### 2. Update ROADMAP.md Phase Status
-Do not hand-edit the ROADMAP checkbox line. Use the status-aware helper instead:
-
-- Run `node .planning/bin/gsdd.mjs phase-status {N} done` when this plan completes the phase.
-- Run `node .planning/bin/gsdd.mjs phase-status {N} in_progress` when this plan completes but more plans remain in the phase.
-
-The helper owns the `[ ]` / `[-]` / `[x]` mutation for `.planning/ROADMAP.md`.
-
-### 3. Write Phase Summary
-Create `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
-
-```markdown
----
-phase: 01-foundation
-plan: 01
-runtime: codex-cli
-assurance: self_checked
----
-
-# Phase {N}: {Name} - Plan {NN} Summary
-
-**Completed**: {date}
-**Tasks**: {count}
-**Git Actions**: {relevant commits, if any}
-**Deviations**: {list deviations and why}
-**Decisions Made**: {new decisions, if any}
-**Notes for Verification**: {anything the verifier should know}
-**Notes for Next Work**: {anything the next planner should know}
-
-<checks>
-<executor_check>
-checker: self | cross_runtime
-checker_runtime: codex-cli
-status: passed | issues_found | skipped
-blocking: false
-notes: [What the executor checker validated or why it was skipped]
-</executor_check>
-</checks>
-
-<handoff>
-plan_runtime: claude-code
-plan_assurance: cross_runtime_checked
-plan_check_status: passed
-execution_runtime: codex-cli
-execution_assurance: self_checked
-executor_check_status: passed
-hard_mismatches_open: false
-</handoff>
-
-<deltas>
-- class: factual_discovery | intent_scope_change | architecture_risk_conflict
-  impact: recoverable | blocking
-  disposition: proceeded | escalated
-  summary: [What changed and why]
-</deltas>
-
-<judgment>
-<active_constraints>
-[Constraints that governed this phase and carry forward to future work]
-</active_constraints>
-<unresolved_uncertainty>
-[Open questions or unvalidated assumptions the next phase should be aware of]
-</unresolved_uncertainty>
-<decision_posture>
-[The strategic direction and key trade-offs - what was chosen, what was deferred, what the governing approach is]
-</decision_posture>
-<anti_regression>
-[Invariants established by this phase that must not be broken by future work]
-</anti_regression>
-</judgment>
-```
-
-**Summary quality gate:** One-liner must be substantive (e.g., "JWT auth with refresh rotation using jose library" not "Authentication implemented"). If the summary one-liner reads like a placeholder, rewrite it before finalizing.
-
-Write the structured sections honestly:
-- `assurance: self_checked` if execution only received self-check or same-runtime checking
-- `assurance: cross_runtime_checked` only when a different runtime/vendor validated the execution artifact
-- include every execution delta in `<deltas>`; do not hide recoverable drift in prose-only notes
-- if a hard mismatch remains open, set `<handoff>.hard_mismatches_open: true` and stop rather than presenting the summary as clean handoff state
-
-Do not invent an inline PLAN task-state mutation scheme if the plan does not define one.
-Summary-driven progress tracking avoids silent drift between the plan contract and what execution actually completed.
-
-**MANDATORY: You MUST write SUMMARY.md to disk at `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`. Output to conversation alone is NOT sufficient. If this file is not written to disk, execution is NOT complete.**
-</state_updates>
-
-<checkpoint_protocol>
-When encountering a checkpoint task:
-
-### `checkpoint:user`
-- STOP immediately
-- summarize completed work
-- state exactly what user input or action is required
-- include any command or artifact the user should inspect
-
-### `checkpoint:review`
-- STOP immediately
-- summarize completed work
-- state what should be reviewed before continuation
-- include focused verification guidance
-
-### Auth-gate routing
-
-Auth errors (indicators: 401, 403, "Not authenticated", "Please run {tool} login", "Set {ENV_VAR}") are gates, not bugs. When an auth error occurs during a `type="auto"` task:
-- recognize it as an auth gate, not a deviation
-- STOP and return `checkpoint:user` with exact auth steps (CLI commands, env vars, verification command)
-- document auth gates in SUMMARY.md as normal flow, not deviations
-
-In all checkpoint cases, return with the current progress and do not continue until resumed.
-</checkpoint_protocol>
-
-<self_check>
-After completing all tasks and state updates, verify your own claims:
-
-```text
-For each completed task:
-  [ ] Files listed in <files> exist in the codebase
-  [ ] Local verification passed
-
-For state updates:
-  [ ] .planning/SPEC.md "Current State" is accurate
-  [ ] ROADMAP.md status uses [ ] / [-] / [x] consistently
-  [ ] SUMMARY.md exists and reflects the actual work
-
-Overall:
-  [ ] Any git actions taken match what you are reporting
-  [ ] No undocumented out-of-scope edits were made
-```
-
-If any self-check fails, fix it and re-check before reporting completion.
-</self_check>
-
-<success_criteria>
-Execution is done when all of these are true:
-
-- [ ] All `type="auto"` tasks in the plan are implemented and verified
-- [ ] Any checkpoint task caused an explicit stop and handoff instead of silent continuation
-- [ ] Deviation rules were followed
-- [ ] Mandatory context files read first when provided
-- [ ] Authentication gates handled with the auth-gate protocol
-- [ ] `.planning/SPEC.md` current state is updated accurately
-- [ ] `ROADMAP.md` uses `[ ]`, `[-]`, `[x]` consistently
-- [ ] `SUMMARY.md` is written
-- [ ] `SUMMARY.md` frontmatter records `runtime` and `assurance`
-- [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, and `<deltas>` sections
-- [ ] Self-check passed
-- [ ] Any git actions honor repo or user conventions and `.planning/config.json`
-</success_criteria>
-
-<completion>
-Report to the user what was accomplished, then present the next step:
-
----
-**Completed:** Plan execution — created `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`.
-
-**Next step:** Check `.planning/config.json` → `workflow.verifier`:
-- If `true`: run `/gsdd-verify` — verify that the phase goal was achieved
-- If `false` (or key missing): run `/gsdd-progress` — check status and route to the next phase
-
-Also available:
-- `/gsdd-plan` — plan the next wave (if more plans remain in this phase)
-- `/gsdd-quick` — handle a sub-hour task outside the phase cycle
-- `/gsdd-pause` — save context for later if stopping work
-
-Consider clearing context before starting the next workflow for best results.
----
-</completion>
+</lifecycle_preflight>
+
+<runtime_contract>
+Execution uses the same `Runtime` and `Assurance` types as planning and verification.
+Infer runtime from the launching surface when obvious: `.claude/` -> `claude-code`, `.codex/` or Codex portable skill -> `codex-cli`, `.opencode/` -> `opencode`, otherwise `other`.
+Assurance is ordered: `unreviewed` -> `self_checked` -> `cross_runtime_checked`.
+Same-runtime helpers never count as cross-runtime evidence.
+</runtime_contract>
+
+<assurance_check>
+Before executing tasks, read the plan artifact's `runtime`, `assurance`, and structured `<plan_check>` result.
+Use `unreviewed` before any executor check, `self_checked` for self/same-runtime checking, and `cross_runtime_checked` only for a different runtime/vendor checker.
+If execution begins from a stronger plan artifact into a weaker execution context, emit a structured `<assurance_check>` with `source_artifact`, `source_runtime`, `source_assurance`, `current_runtime`, `current_assurance`, `status`, and `warning`.
+If plan runtime/assurance is missing, use `status: unknown`.
+</assurance_check>
+
+<multi_plan_orchestration>
+A phase often contains multiple plans. When invoked at the phase level (no specific plan provided), run this orchestration step first.
+
+### Discover Plans and Group by Wave
+
+1. Scan `.planning/phases/{phase_dir}/` for all `*-PLAN.md` files.
+2. For each plan, read its frontmatter `wave` field (default: `wave: 1` if absent).
+3. Group plans by wave number. Collect the set of distinct wave numbers and sort them ascending.
+4. Check for `*-SUMMARY.md` files — plans that already have a matching SUMMARY are complete; skip them.
+
+Present to the user:
+```
+Phase {N} — {Name}
+Plans to execute:
+  Wave 1: {plan-01-NAME.md}, {plan-02-NAME.md}
+  Wave 2: {plan-03-NAME.md}
+Plans already complete (have SUMMARY): {list}
+```
+
+Confirm with the user before proceeding if any existing SUMMARYs look stale or incomplete.
+
+### Execute Wave by Wave
+
+For each wave in ascending order:
+1. Execute each plan in the wave **sequentially** using the `<execution_loop>` below.
+2. After each plan: verify `{plan_id}-SUMMARY.md` exists on disk.
+3. If a plan produces a SUMMARY, log: `Wave {W} / Plan {NN}: ✓ complete`.
+4. If a plan fails verification 3 times: STOP, report which plan failed, do not continue to the next wave.
+5. After all plans in a wave are complete, advance to the next wave.
+
+### Aggregate Summary
+
+After all waves complete, produce a brief aggregate report:
+```
+Phase {N} complete.
+Plans executed: {count}
+Waves: {W} total
+Key deliverables: [bullet list of what was built, one line per plan]
+Lifecycle status: implementation complete, verification still required
+Next step: /gsdd-verify {N} — verify the phase goal before closure
+```
+
+If only a single plan was provided (the common case), skip this section entirely and go straight to the `<execution_loop>`.
+</multi_plan_orchestration>
+
+<execution_loop>
+For each task in the plan, follow this loop:
+
+```text
+1. Read the plan frontmatter and current task.
+2. Implement the task action.
+3. Run the task's verify steps.
+4. Handle any git actions using repo or user conventions.
+5. Record task completion in your working notes and final SUMMARY.md.
+```
+
+### Frontmatter And Task Semantics
+
+The executor consumes the plan schema defined by `/gsdd-plan`:
+- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`, `tdd`
+- task types:
+  - `type="auto"` - proceed without pausing
+  - `type="checkpoint:user"` - stop for a required user decision or human-only step
+  - `type="checkpoint:review"` - stop for explicit review before continuing
+
+If the plan uses any `checkpoint:*` task, `autonomous` must be `false`.
+Checkpoint tasks are contract boundaries. Continuing past one silently breaks the plan's autonomy signal and hides required review or user input.
+
+### Implementation Rules
+- Follow the `<action>` precisely.
+- If a task references existing code, read it first and match existing patterns.
+- If you are unsure about something, check `.planning/SPEC.md` decisions first, then ask if still unclear.
+
+### Change-Impact Discipline
+Before modifying any existing behavior, run a ripple check:
+
+1. Grep before you change.
+   ```bash
+   grep -r "thing-being-changed" . --include="*.md" --include="*.ts" --include="*.js"
+   ```
+   Update every relevant reference.
+   Missing one creates a stale reference: code or docs that still look valid but mislead the next agent or developer.
+
+2. Create before you reference.
+   Never mention a file, template, module, or API without confirming it exists.
+   This prevents workflows, summaries, and code from pointing at artifacts that were never created.
+
+3. Verify imports survive deletion.
+   When removing an import, function, or variable, grep for all usages before deleting it.
+   This catches dead references before they turn into broken execution paths.
+
+### TDD Execution
+
+If a task frontmatter includes `tdd: true`, switch to RED-GREEN-REFACTOR cycle for that task:
+
+**RED — Write the failing test first**
+1. Write the test that describes the intended behavior.
+2. Run the test. Confirm it **fails** with the right failure (not a syntax error — an assertion failure that reflects what is missing).
+3. Do not proceed until you see the expected red failure.
+
+**GREEN — Minimal implementation**
+1. Write the smallest amount of code that makes the test pass.
+2. Run the test. Confirm it passes.
+3. Do not over-engineer at this stage — add only what the test requires.
+
+**REFACTOR — Clean up**
+1. Improve structure, naming, and clarity without changing behavior.
+2. Run the tests again. Confirm they still pass.
+3. Log the RED→GREEN→REFACTOR cycle in SUMMARY.md under the task entry.
+
+Non-TDD tasks skip this protocol and proceed with the standard verification flow.
+
+### Local Verification
+Before reporting a task complete:
+- run the task's `<verify>` checks
+- if tests exist, run the targeted tests first
+- if a UI change is involved, verify the relevant rendering path
+- if an API change is involved, hit the endpoint or targeted integration path
+- A task is not complete because code was written. It is complete when the intended verification path actually passes.
+
+### Git Guidance
+
+```bash
+# Stage individual files — never "git add ." or "git add -A"
+git add src/routes/users.ts src/app/users/page.tsx tests/users.route.test.ts
+
+# Commit message — conventional type prefix
+git commit -m "feat: wire users page to real route"
+```
+
+**Conventional commit type reference** (advisory — repo/user conventions override):
+
+| Type | Use when |
+|------|----------|
+| `feat` | New user-facing feature |
+| `fix` | Bug fix |
+| `test` | Adding or updating tests only |
+| `refactor` | Code restructure with no behavior change |
+| `perf` | Performance improvement |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace, no logic change |
+| `chore` | Build, tooling, dependencies |
+
+Git rules:
+- **Repo and user conventions win first.** This table is a reference, not a mandate.
+- `.planning/config.json -> gitProtocol` is advisory only.
+- **Stage only files listed in the plan's `files-modified` frontmatter.** Never use `git add .` or `git add -A`. If you need to stage a file not in `files-modified`, record it as a deviation.
+- **Wrong-branch check:** Before significant implementation begins, verify HEAD is not `main` or `master` if repo convention expects a feature branch; if it is, STOP and hard-warn the user before proceeding.
+- **Transition-safety warning pass:** Before significant implementation begins, inspect staged, unstaged, untracked, unpushed, PR-less, stale/spent, and mixed-scope branch signals. Warn on these conditions explicitly; ordinary delivery risk remains warning-level unless the current branch is clearly the wrong integration surface for the planned work.
+- Do not mention phase, plan, task, or requirement IDs, or internal milestone labels, in commit messages, PR titles, or PR bodies unless explicitly requested.
+- Do not force one commit per task unless the repo or user asked for that.
+- **PR creation:** After committing work on a feature branch, create a PR before reporting completion unless the user or plan explicitly says otherwise.
+</execution_loop>
+
+<deviation_rules>
+Reality rarely matches the plan perfectly. Handle deviations with these rules in priority order:
+
+### Structured mismatch taxonomy
+
+All execution-time deltas must be classified as one of:
+- `factual_discovery` - the repo/runtime reality differs from the plan in a concrete, local way (wrong path, stale API shape, moved module, outdated dependency assumption)
+- `intent_scope_change` - the requested outcome or scope needs to change
+- `architecture_risk_conflict` - the planned approach creates a structural or risk problem that needs a different design
+
+Treat only hard mismatches as blocking by default:
+- malformed or missing contract sections in the input artifact
+- unresolved blocking checker findings
+- any `intent_scope_change`
+- any `architecture_risk_conflict`
+- a `factual_discovery` that is not deterministically recoverable
+
+If a `factual_discovery` is local, deterministic, and recoverable, proceed with a recorded delta instead of bouncing immediately back to planning. That delta must be surfaced later in SUMMARY.md for downstream review and milestone audit.
+
+### Rule 1: Auto-Fix Bugs
+
+**Trigger:** Code doesn't work as intended (broken behavior, errors, incorrect output)
+
+If you introduce a bug while implementing a task:
+- fix it immediately
+- keep the fix grouped with the affected work
+- note it in the completion summary
+
+**Examples:** Wrong queries, logic errors, type errors, null pointer exceptions, broken validation
+
+### Rule 2: Auto-Add Critical Missing Pieces
+
+**Trigger:** Code missing essential features for correctness, security, or basic operation
+
+If the plan forgot something obviously necessary for the task to work:
+- add it as part of the current task
+- note it in the completion summary
+
+**Examples:** Missing error handling, no input validation, missing null checks, no auth on protected routes, missing authorization
+
+### Rule 3: Auto-Fix Straightforward Blockers
+
+**Trigger:** Something prevents completing the current task
+
+If an external factor blocks progress and the fix is straightforward:
+- fix it
+- note it in the completion summary
+- if the fix is not straightforward, STOP and ask the developer
+
+**Examples:** Missing dependency, wrong types, broken imports, missing env var, DB connection error, missing referenced file
+
+### Rule 4: Ask About Architecture Changes
+
+**Trigger:** Fix requires significant structural modification
+
+If the plan's approach will not work or a materially different approach is needed:
+- STOP
+- explain what changed and why the plan needs adjusting
+- wait for approval before proceeding
+
+**Examples:** New DB table (not column), major schema changes, new service layer, switching libraries/frameworks, breaking API changes
+
+### Scope Boundary
+If you discover something that needs doing but is not in the plan:
+- if it is obviously in scope and required for correctness, treat it as Rule 2
+- if it changes architecture or expands scope, STOP and ask
+- if it is out of scope, note it for later and DO NOT implement it now
+
+### Fix Attempt Limit
+If a task fails verification 3 times after fixes, STOP and report the failure to the developer.
+</deviation_rules>
+
+<state_updates>
+After completing all tasks in the plan:
+
+### 1. Update `.planning/SPEC.md` "Current State"
+Keep the update factual and compact:
+
+```markdown
+## Current State
+- Active Phase: Phase {N} - {Name} (implementation complete, verification pending)
+- Last Completed: Plan {NN} completed
+- Decisions: [New decisions, if any]
+- Blockers: [None or specific blocker]
+```
+
+### 2. Update ROADMAP.md Phase Status
+Do not hand-edit the ROADMAP checkbox line. Use the status-aware helper instead:
+
+- Run `node .planning/bin/gsdd.mjs phase-status {N} in_progress` when implementation work has started or this plan completes.
+- Do NOT run `node .planning/bin/gsdd.mjs phase-status {N} done` from execute. Only verify may close a phase after writing a `status: passed` VERIFICATION.md.
+
+The helper owns the `[ ]` / `[-]` / `[x]` mutation for `.planning/ROADMAP.md`, including both the overview line and the matching `## Phase Details` `**Status**` line when both exist.
+
+### 3. Write Phase Summary
+Create `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
+
+```markdown
+---
+phase: 01-foundation
+plan: 01
+runtime: codex-cli
+assurance: self_checked
+---
+
+# Phase {N}: {Name} - Plan {NN} Summary
+
+**Completed**: {date}
+**Tasks**: {count}
+**Git Actions**: {relevant commits, if any}
+**Deviations**: {list deviations and why}
+**Decisions Made**: {new decisions, if any}
+**Notes for Verification**: {anything the verifier should know}
+**Notes for Next Work**: {anything the next planner should know}
+
+<checks>
+<executor_check>
+checker: self | cross_runtime
+checker_runtime: codex-cli
+status: passed | issues_found | skipped
+blocking: false
+notes: [What the executor checker validated or why it was skipped]
+</executor_check>
+</checks>
+
+<handoff>
+plan_runtime: claude-code
+plan_assurance: cross_runtime_checked
+plan_check_status: passed
+execution_runtime: codex-cli
+execution_assurance: self_checked
+executor_check_status: passed
+hard_mismatches_open: false
+</handoff>
+
+<deltas>
+- class: factual_discovery | intent_scope_change | architecture_risk_conflict
+  impact: recoverable | blocking
+  disposition: proceeded | escalated
+  summary: [What changed and why]
+</deltas>
+
+<judgment>
+<active_constraints>
+[Constraints that governed this phase and carry forward to future work]
+</active_constraints>
+<unresolved_uncertainty>
+[Open questions or unvalidated assumptions the next phase should be aware of]
+</unresolved_uncertainty>
+<decision_posture>
+[The strategic direction and key trade-offs - what was chosen, what was deferred, what the governing approach is]
+</decision_posture>
+<anti_regression>
+[Invariants established by this phase that must not be broken by future work]
+</anti_regression>
+</judgment>
+```
+
+**Summary quality gate:** One-liner must be substantive (e.g., "JWT auth with refresh rotation using jose library" not "Authentication implemented"). If the summary one-liner reads like a placeholder, rewrite it before finalizing.
+
+Write the structured sections honestly:
+- `assurance: self_checked` if execution only received self-check or same-runtime checking
+- `assurance: cross_runtime_checked` only when a different runtime/vendor validated the execution artifact
+- include every execution delta in `<deltas>`; do not hide recoverable drift in prose-only notes
+- if a hard mismatch remains open, set `<handoff>.hard_mismatches_open: true` and stop rather than presenting the summary as clean handoff state
+
+Do not invent an inline PLAN task-state mutation scheme if the plan does not define one.
+Summary-driven progress tracking avoids silent drift between the plan contract and what execution actually completed.
+
+**MANDATORY: You MUST write SUMMARY.md to disk at `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`. Output to conversation alone is NOT sufficient. If this file is not written to disk, execution is NOT complete.**
+</state_updates>
+
+<checkpoint_protocol>
+When encountering a checkpoint task:
+
+### `checkpoint:user`
+- STOP immediately
+- summarize completed work
+- state exactly what user input or action is required
+- include any command or artifact the user should inspect
+
+### `checkpoint:review`
+- STOP immediately
+- summarize completed work
+- state what should be reviewed before continuation
+- include focused verification guidance
+
+### Auth-gate routing
+
+Auth errors (indicators: 401, 403, "Not authenticated", "Please run {tool} login", "Set {ENV_VAR}") are gates, not bugs. When an auth error occurs during a `type="auto"` task:
+- recognize it as an auth gate, not a deviation
+- STOP and return `checkpoint:user` with exact auth steps (CLI commands, env vars, verification command)
+- document auth gates in SUMMARY.md as normal flow, not deviations
+
+In all checkpoint cases, return with the current progress and do not continue until resumed.
+</checkpoint_protocol>
+
+<self_check>
+After completing all tasks and state updates, verify your own claims:
+
+```text
+For each completed task:
+  [ ] Files listed in <files> exist in the codebase
+  [ ] Local verification passed
+
+For state updates:
+  [ ] .planning/SPEC.md "Current State" is accurate
+  [ ] ROADMAP.md status remains open (`[-]` if status was updated) until verification passes
+  [ ] SUMMARY.md exists and reflects the actual work
+
+Overall:
+  [ ] Any git actions taken match what you are reporting
+  [ ] No undocumented out-of-scope edits were made
+```
+
+If any self-check fails, fix it and re-check before reporting completion.
+</self_check>
+
+<success_criteria>
+Execution is done when all of these are true:
+
+- [ ] All `type="auto"` tasks in the plan are implemented and verified
+- [ ] Any checkpoint task caused an explicit stop and handoff instead of silent continuation
+- [ ] Deviation rules were followed
+- [ ] Mandatory context files read first when provided
+- [ ] Authentication gates handled with the auth-gate protocol
+- [ ] `.planning/SPEC.md` current state is updated accurately
+- [ ] `ROADMAP.md` uses `[ ]`, `[-]`, `[x]` consistently and is not marked `[x]` by execute
+- [ ] `SUMMARY.md` is written
+- [ ] `SUMMARY.md` frontmatter records `runtime` and `assurance`
+- [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, and `<deltas>` sections
+- [ ] Self-check passed
+- [ ] Any git actions honor repo or user conventions and `.planning/config.json`
+</success_criteria>
+
+<completion>
+Report to the user what was accomplished, then present the next step:
+
+---
+**Completed:** Plan execution — created `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md`.
+
+**Next step:** Check `.planning/config.json` → `workflow.verifier`:
+- If `true`: run `/gsdd-verify` — verify that the phase goal was achieved
+- If `false` (or key missing): run `/gsdd-progress` — check status and route to the next phase
+
+Also available:
+- `/gsdd-plan` — plan the next wave (if more plans remain in this phase)
+- `/gsdd-quick` — handle a sub-hour task outside the phase cycle
+- `/gsdd-pause` — save context for later if stopping work
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>