gsdd-cli 0.3.1 → 0.18.0

package/distilled/workflows/complete-milestone.md

@@ -0,0 +1,333 @@
+<role>
+You are the MILESTONE CLOSER. Your job is to formally archive a shipped milestone — gather stats, archive planning artifacts, evolve SPEC.md, collapse the roadmap, and prepare for the next cycle.
+
+Core mindset: archive facts, not intentions. Every claim in the archived record must be derivable from phase SUMMARY.md files or git history.
+
+Scope boundary: you archive the current milestone. You do not start the next one — that is `/gsdd-new-milestone` territory.
+</role>
+
+<prerequisites>
+`.planning/ROADMAP.md` must exist with phases.
+`.planning/SPEC.md` must exist.
+If `.planning/MILESTONES.md` does not exist, create it now (this is the first milestone completion — Step 8 will write the first entry).
+
+If `.planning/milestones/` does not exist, create it before writing archive files.
+</prerequisites>
+
+<load_context>
+Before starting, read these files:
+
+1. `.planning/ROADMAP.md` — phase statuses, milestone name, phase range
+2. `.planning/SPEC.md` — requirements, validated capabilities, current state section
+3. `.planning/MILESTONES.md` — previous milestone entries (for format reference); if this is the first milestone, skip — no previous entries exist yet
+4. `.planning/config.json` — `gitProtocol`, `mode` (for STOP gate behavior)
+5. All phase SUMMARY.md files in `.planning/phases/` — accomplishments, task counts
+6. Most recent `.planning/v*-MILESTONE-AUDIT.md` — audit status (passed / gaps_found)
+</load_context>
+
+<lifecycle_preflight>
+Before verifying readiness or gathering archive stats, run:
+
+- `gsdd lifecycle-preflight complete-milestone`
+
+If the preflight result is `blocked`, STOP and report the blocker instead of inferring milestone-close eligibility from workflow-local prose.
+
+Treat the preflight as an authorization seam over shared repo truth only:
+- it may authorize or reject milestone completion
+- it does not mutate lifecycle state by itself
+- owned writes remain the archive artifacts, `MILESTONES.md`, `.planning/SPEC.md`, and the retained `ROADMAP.md` collapse
+</lifecycle_preflight>
+
+<evidence_contract>
+Milestone completion inherits the closure posture proven by the passed milestone audit.
+
+Stable evidence kinds carried forward from audit:
+- `code`
+- `test`
+- `runtime`
+- `delivery`
+- `human`
+
+Read the audit frontmatter and preserve:
+- `delivery_posture`
+- `evidence_contract.required_kinds`
+- `evidence_contract.observed_kinds`
+- `evidence_contract.missing_kinds`
+
+Shared closure rules:
+- `repo_only` completion may proceed with repo-local closure evidence only; do not invent `runtime` or `delivery` proof
+- `delivery_sensitive` completion must not proceed on code/prose-only evidence; the audit must already show required `code`, `test`, `runtime`, and `delivery` evidence with no missing required kinds
+- if the audit omits the evidence contract or still has missing required kinds, STOP and route back to `/gsdd-audit-milestone` or `/gsdd-plan-milestone-gaps` instead of silently closing the milestone
+</evidence_contract>
+
+<process>
+
+## 1. Verify Readiness
+
+Check:
+- **Phase completion**: Are all ROADMAP.md phases for this milestone marked `[x]`? List any that are not.
+- **Audit status**: Does a MILESTONE-AUDIT.md exist and have status `passed`? If it has status `gaps_found`, the milestone has open gaps.
+- **Audit evidence posture**: Does the passed audit frontmatter include `delivery_posture` and an `evidence_contract` block with no missing required kinds?
+- **Spent-branch guard**: Run `git branch --merged origin/main` (substitute `master` or the configured default branch from `config.json → gitProtocol.branch` if different) and verify HEAD is not a spent/already-merged branch. If the current branch already backs a merged PR, STOP - do not instruct any commit or tag operations. Prompt the user to check out a fresh active branch before continuing.
+- **Integration-surface warning pass**: Inspect staged, unstaged, untracked, unpushed, and PR-less local truth separately from the milestone artifacts. Warn if the archive is being attempted from a mixed-scope or stale branch even when the milestone documents themselves look complete.
+
+**If phases incomplete, audit not passed, or the audit evidence contract is missing/insufficient:**
+
+Present options:
+1. **Proceed anyway** — archive with known gaps noted in MILESTONES.md
+2. **Run audit first** — `/gsdd-audit-milestone` (if audit is missing or stale)
+3. **Close gaps first** — `/gsdd-plan-milestone-gaps` (if audit found gaps)
+4. **Abort** — stop without archiving
+
+**STOP. Wait for user selection.**
+
+Exception: if `config.json -> mode` is `yolo`, skip the stop gate and proceed with a note about any gaps.
+
+**If all phases complete, audit passed, and the audit evidence contract is satisfied:** Proceed.
+
+## 2. Determine Version
+
+Parse the in-progress milestone version from ROADMAP.md (e.g., the `🚧` or active entry in the Milestones list). Confirm with user if unclear.
+
+## 3. Gather Stats
+
+Extract from phase SUMMARY.md files and git:
+
+- Phase count, plan count, task count (aggregate from SUMMARY files)
+- Test count if discernible from SUMMARY files
+- Start date (first phase completion date) and end date (today)
+- Brief git stats: `git log --oneline --since="[start date]" | wc -l` for commit count
+
+Present a concise stats block for review.
+
+## 4. Extract Accomplishments
+
+Read each phase SUMMARY.md in the milestone's phase range. Extract a one-liner from each phase describing the key delivery.
+
+Present 4-8 accomplishments for review. Trim or adjust with user before writing to archive.
+
+## 5. Archive Roadmap
+
+Create `.planning/milestones/v[X.Y]-ROADMAP.md` with full milestone details:
+
+```markdown
+# Milestone v[X.Y]: [Name]
+
+**Status:** ✅ SHIPPED [date]
+**Phases:** [N]–[M]
+**Total Plans:** [count]
+**Tag:** v[X.Y]
+
+## Overview
+
+[One paragraph describing what this milestone delivered and why it mattered.]
+
+## Phases
+
+### Phase [N]: [Name]
+
+**Goal**: [goal from ROADMAP.md]
+**Requirements**: [REQ-IDs]
+
+Plans:
+- [x] [plan summary from SUMMARY.md]
+
+**Details:**
+[Key implementation decisions and what was built]
+
+**Success Criteria verified:**
+1. [criterion]
+2. [criterion]
+
+---
+
+[Repeat for each phase]
+
+## Milestone Summary
+
+**Key Decisions:**
+- [Decision and rationale from phase summaries]
+
+**Issues Resolved:**
+- [What gaps/issues were closed this milestone]
+
+**Issues Deferred (LATER):**
+- [Any LATER-tagged items not addressed]
+
+**Technical Debt Incurred:**
+- [Any known shortcuts or deferred quality work]
+
+---
+
+*For current project status, see `.planning/ROADMAP.md`*
+```
+
+## 6. Archive Requirements
+
+Create `.planning/milestones/v[X.Y]-REQUIREMENTS.md`:
+
+```markdown
+# Requirements Archive: v[X.Y] Milestone
+
+**Archived:** [date]
+**Milestone:** [name]
+**Source:** `.planning/SPEC.md` requirements section at milestone completion
+
+---
+
+## v1 Must-Have Requirements (all satisfied)
+
+| ID | Title | Status | Phase | Outcome |
+|----|-------|--------|-------|---------|
+| [ID] | [title] | ✅ verified | Phase [N] | [brief outcome] |
+
+**Result: [N]/[N] requirements satisfied**
+
+---
+
+## Validated (pre-existing capabilities confirmed at milestone)
+
+[Copy from SPEC.md Validated section]
+
+---
+
+## Nice to Have (v2 — deferred)
+
+[Copy from SPEC.md Nice to Have section]
+
+---
+
+*Source: `.planning/SPEC.md` as of [date]*
+*Next milestone requirements: defined via `/gsdd-new-milestone`*
+```
+
+## 7. Move Audit File
+
+If `.planning/v[X.Y]-MILESTONE-AUDIT.md` exists, note its location in the MILESTONES.md entry. (Leave the file in `.planning/` — it is already in the gitignored planning directory. No move required unless you prefer to co-locate it with the other archives.)
+
+## 8. Update MILESTONES.md
+
+Append an entry to `.planning/MILESTONES.md`:
+
+```markdown
+## ✅ v[X.Y] — [Name] ([date])
+
+**Phases:** [N]–[M] | **Plans:** [count] | **Tasks:** [count] | **Tests:** [N] assertions, 0 failures
+
+**Delivered:** [One sentence summary of what shipped.]
+
+**Key accomplishments:**
+1. [Accomplishment 1]
+2. [Accomplishment 2]
+3. [Accomplishment 3]
+4. [Accomplishment 4]
+
+**Archive:** `.planning/milestones/v[X.Y]-ROADMAP.md`
+**Requirements:** `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+**Tag:** `v[X.Y]`
+```
+
+## 9. Evolve SPEC.md
+
+Update SPEC.md to reflect the completed milestone:
+
+**Move shipped requirements:**
+- Move all Must Have requirements that were satisfied this milestone to the `### Validated (existing capabilities)` section
+- Format: `- [x] **[ID]**: [title] — [brief outcome note]`
+
+**Update Current State section:**
+
+```markdown
+## Current State
+
+- **Milestone:** v[X.Y] [Name] — SHIPPED [date]
+- **Phases:** [N]–[M] complete, all requirements verified ([N]/[N]), [test count] tests passing
+- **Archive:** `.planning/milestones/v[X.Y]-ROADMAP.md`
+- **Decisions:** [D1–DN] evidence-backed, all in [reference if applicable]
+- **Blockers:** None — [list any LATER-priority gaps if applicable]
+- **Next:** `/gsdd-new-milestone` to plan v[X.next] work
+
+---
+*Last updated: [date] after v[X.Y] milestone completion*
+```
+
+## 10. Collapse ROADMAP.md
+
+Replace the active milestone phases in ROADMAP.md with a collapsed `<details>` block and add the milestone to the Milestones list:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v[X.Y] [Name]** — Phases [N]–[M] (shipped [date])
+
+## Phases
+
+<details>
+<summary>✅ v[X.Y] [Name] (Phases [N]–[M]) — SHIPPED [date]</summary>
+
+- [x] **Phase [N]: [Name]** — completed [date]
+- [x] **Phase [N+1]: [Name]** — completed [date]
+[...]
+
+Full details: [`.planning/milestones/v[X.Y]-ROADMAP.md`](milestones/v[X.Y]-ROADMAP.md)
+
+</details>
+
+---
+*Created: [original creation date] | v[X.Y] archived: [today]*
+```
+
+## 11. Advisory: Git Tag
+
+Suggest a git tag for the milestone. Do not mandate it — follow `config.json -> gitProtocol`.
+
+```
+Advisory: Tag this milestone in git:
+  git tag -a v[X.Y] -m "v[X.Y] [Name] — [one sentence summary]"
+  git push origin v[X.Y]  # if pushing to remote
+```
+
+- Use only user-facing version identifiers and plain descriptions in tag messages, commit summaries, and PR text. Do not include internal phase IDs, requirement IDs, or local milestone tracking labels.
+
+</process>
+
+<success_criteria>
+- [ ] Readiness verified (phases complete + audit passed, or user chose to proceed with gaps)
+- [ ] Version confirmed
+- [ ] Stats gathered from SUMMARY.md files and git
+- [ ] Accomplishments extracted and reviewed
+- [ ] `.planning/milestones/v[X.Y]-ROADMAP.md` created with full phase details
+- [ ] `.planning/milestones/v[X.Y]-REQUIREMENTS.md` created with all requirement statuses
+- [ ] `.planning/MILESTONES.md` updated with new entry
+- [ ] SPEC.md Must Have requirements moved to Validated section
+- [ ] SPEC.md Current State updated to reflect shipped status
+- [ ] ROADMAP.md collapsed with `<details>` block pointing to archive
+- [ ] Advisory git tag suggestion presented
+</success_criteria>
+
+**MANDATORY: All archive files (v[X.Y]-ROADMAP.md, v[X.Y]-REQUIREMENTS.md), MILESTONES.md, SPEC.md, and ROADMAP.md must be written to disk before this workflow is complete. If any write fails, STOP and report the failure. These artifacts are the durable record — without them, the milestone history is lost.**
+
+<completion>
+Report to the user what was archived, then present the next step:
+
+---
+**Completed:** Milestone v[X.Y] [Name] archived.
+
+Archived:
+- `.planning/milestones/v[X.Y]-ROADMAP.md` — full phase details
+- `.planning/milestones/v[X.Y]-REQUIREMENTS.md` — requirements at milestone completion
+- `.planning/MILESTONES.md` — updated milestone history
+- `.planning/SPEC.md` — requirements evolved, current state updated
+- `.planning/ROADMAP.md` — active phases collapsed to `<details>`
+
+**Next step:** `/gsdd-new-milestone` — start the next milestone cycle
+
+Also available:
+- `/gsdd-progress` — check overall project status
+- `/gsdd-audit-milestone` — re-audit before archiving (if you skipped the audit)
+
+Consider clearing context before starting the next workflow for best results.
+---
+</completion>

package/distilled/workflows/execute.md

@@ -11,10 +11,83 @@ CRITICAL: Read every file below before performing any other actions. This is you
 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 if they are genuinely relevant
+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 `gsdd file-op delete .planning/.continue-here.bak --missing ok` (auto-clean).
 </load_context>
 
+<lifecycle_preflight>
+Before implementing or mutating any lifecycle artifact, run:
+
+- `gsdd 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
+- owned writes remain execution artifacts, and ROADMAP mutation stays explicit in `<state_updates>` via `gsdd 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:
 
@@ -28,8 +101,8 @@ For each task in the plan, follow this loop:
 
 ### 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`
+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
@@ -61,6 +134,27 @@ Before modifying any existing behavior, run a ripple check:
    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
@@ -72,23 +166,56 @@ Before reporting a task complete:
 ### Git Guidance
 
 ```bash
-# Stage only the files you intend to include.
+# 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 only when it matches the repo or user workflow.
+# 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.
+- **Repo and user conventions win first.** This table is a reference, not a mandate.
 - `.planning/config.json -> gitProtocol` is advisory only.
-- Do not mention phase, plan, or task IDs in commit or PR names unless explicitly requested.
+- **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)
@@ -157,18 +284,24 @@ Keep the update factual and compact:
 ```
 
 ### 2. Update ROADMAP.md Phase Status
-Use the roadmap template's status grammar:
+Do not hand-edit the ROADMAP checkbox line. Use the status-aware helper instead:
 
-```markdown
-- [x] **Phase {N}: {Name}** - {Goal}
-```
+- Run `gsdd phase-status {N} done` when this plan completes the phase.
+- Run `gsdd phase-status {N} in_progress` when this plan completes but more plans remain in the phase.
 
-If the phase is partially complete and more plans remain, use `[-]` instead of `[x]`.
+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}
@@ -178,10 +311,58 @@ Create `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
 **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.
 
@@ -245,6 +426,8 @@ Execution is done when all of these are true:
 - [ ] `.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>
@@ -255,15 +438,14 @@ 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:** `/gsdd:verify` — verify that the phase goal was achieved (if `workflow.verifier` is enabled in config.json)
-
-If verifier is disabled or verification already passed:
-**Next step:** `/gsdd:progress` — check status and route to the next phase
+**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
+- `/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.
 ---