gsdd-cli 0.19.0 → 0.19.2

package/distilled/templates/delegates/plan-checker.md

@@ -5,6 +5,7 @@ You are the fresh-context plan checker for `/gsdd-plan`.
 Read only the explicit inputs provided by the orchestrator:
 - target phase goal and requirement IDs
 - relevant locked decisions or deferred items from `.planning/SPEC.md`
+- project config from `.planning/config.json`, especially `workflow.discuss` and `workflow.planCheck`
 - approach decisions from `.planning/phases/*-APPROACH.md` (if provided)
 - any relevant phase research file
 - the produced `.planning/phases/*-PLAN.md` file(s)
@@ -29,7 +30,16 @@ Verify these dimensions:
   - **Goal addressed?** Compare the phase goal statement to the plan's collective task outputs. Would successful completion of all tasks deliver the goal? If the goal says "users can authenticate" but tasks only set up database schema → `blocker`.
   - **Success criteria reachable?** Are the phase success criteria from ROADMAP.md achievable through the planned tasks? Each success criterion should be traceable to at least one task's verify output → `blocker` if unreachable.
   - **Outcome observable?** After execution, could a human or automated check confirm the goal was met? Plans that produce only internal artifacts with no user-visible or testable outcome → `warning`.
+- `scope_boundaries`: hard boundaries, anti-goals, and explicit out-of-scope items are preserved in task scope.
+- `anti_regression_capture`: known prior failures, compatibility risks, and behavior that must not regress are represented in tasks or verification.
+- `escalation_integrity`: tasks include checkpoints or escalation when evidence, permissions, user decisions, or risky ambiguity are required.
+- `closure_honesty`: the plan's done criteria and evidence limits support only claims that execution can actually prove.
+- `high_leverage_review`: high-leverage surfaces have a second-pass review or equivalent contradiction/staleness check before completion.
 - `approach_alignment`: when APPROACH.md is provided, verify that plan tasks implement the chosen approaches from the user's decisions. Check:
+  - **Alignment proof valid?** When `workflow.discuss` is `true`, APPROACH.md must record `alignment_status: user_confirmed` or `alignment_status: approved_skip`. Missing alignment proof, unknown status, or agent-discretion-only proof -> `blocker` with `fix_hint` telling the planner to revise APPROACH.md through real user alignment or an explicit user-approved skip.
+  - **Canonical proof fields present?** APPROACH.md must include all canonical proof fields: `alignment_status`, `alignment_method`, `user_confirmed_at`, `explicit_skip_approved`, `skip_scope`, `skip_rationale`, and `confirmed_decisions`. Missing fields -> `blocker`.
+  - **User confirmation present?** For `alignment_status: user_confirmed`, `confirmed_decisions` must include at least one non-placeholder locked decision; `explicit_skip_approved` may be `false`, and `skip_scope`/`skip_rationale` may be `N/A`. Empty `confirmed_decisions`, chat-memory-only proof, or decisions attributed only to the agent -> `blocker`.
+  - **Approved skip explicit?** For `alignment_status: approved_skip`, APPROACH.md must include `explicit_skip_approved: true`, `alignment_method`, `user_confirmed_at`, substantive `skip_scope`, substantive `skip_rationale`, and `confirmed_decisions` may be `N/A - approved skip`. Agent-only "No questions needed" or `explicit_skip_approved: false` -> `blocker`.
   - **Chosen honored?** Does each plan task align with the approach chosen in APPROACH.md for its gray area? A task that implements an alternative the user explicitly rejected -> `blocker`.
   - **Discretion respected?** "Agent's Discretion" items allow planner flexibility — do NOT flag these as misalignment.
   - **Deferred excluded?** Deferred ideas from APPROACH.md must not appear in plan tasks -> `blocker` if found.
@@ -43,8 +53,8 @@ Return JSON only as a single object with this shape:
   "summary": "One sentence overall assessment",
   "issues": [
     {
-      "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
-      "severity": "blocker",
+      "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | scope_boundaries | anti_regression_capture | escalation_integrity | closure_honesty | high_leverage_review | approach_alignment",
+      "severity": "blocker | warning",
       "description": "What is wrong",
       "plan": "01-PLAN",
       "task": "1-02",
@@ -56,8 +66,8 @@ Return JSON only as a single object with this shape:
 
 Rules:
 - Status must be either `"passed"` or `"issues_found"`.
-- Use `"status": "passed"` only when no blockers remain. Warnings may still be listed.
-- Use `"status": "issues_found"` when any blocker exists or when warnings should be surfaced for revision.
+- Use `"status": "passed"` only when `"issues": []`.
+- Use `"status": "issues_found"` when any blocker or warning exists so the orchestrator must surface it for revision or explicit acceptance.
 - Keep `fix_hint` targeted. The planner should patch the existing plan, not replan from scratch, unless the issue is fundamental.
 - If there are no issues, return `"issues": []`.
 

package/distilled/workflows/audit-milestone.md

@@ -42,6 +42,11 @@ Determine milestone `delivery_posture` before grading requirements or flows:
 - `repo_only` — the milestone claim is still repo-local and does not depend on shipped runtime or release proof
 - `delivery_sensitive` — the milestone claims shipped UX, release/install behavior, published proof, or other externally consumed runtime outcomes
 
+Determine `release_claim_posture` as the release wording boundary layered over `delivery_posture`:
+- `repo_closeout` — default. The milestone can be described as repo-local closeout only; do not imply shipped availability, public support, runtime validation, generated-surface freshness, tags, packages, or GitHub Releases.
+- `runtime_validated_closeout` — a named runtime behavior or generated/runtime surface was directly executed and observed. The claim must name only the validated runtime or surface and must include `runtime` evidence.
+- `delivery_supported_closeout` — the milestone supports externally consumed release, install, support, or public-facing delivery claims. The audit must satisfy the `delivery_sensitive` evidence bar and include concrete `delivery` evidence appropriate to the claim.
+
 Apply the shared `audit-milestone` matrix:
 
 | delivery_posture     | required evidence                | recommended evidence | cannot carry closure alone |
@@ -54,6 +59,12 @@ Rules:
 - delivery-sensitive audits must not pass on phase prose, code inspection, or tests alone; required `runtime` and `delivery` evidence must be explicitly present
 - `human` evidence is supportive only at audit level unless the audit is already otherwise satisfied
 - record the selected `delivery_posture`, `required_kinds`, `observed_kinds`, and `missing_kinds` in audit frontmatter so completion inherits the same closure contract
+- record `release_claim_posture`, unsupported claims, waivers, deferrals, and contradiction checks in audit frontmatter; completion inherits these fields
+- missing required evidence cannot be waived while preserving a stronger release claim. A waiver is valid only when it narrows the claim posture or records a deferred unsupported claim.
+- deferrals must name the unsupported claim, missing evidence kind(s), and later workflow or milestone candidate when known
+- contradiction checks must cover evidence, public-surface, runtime, delivery, planning-drift, and generated-surface contradictions; stop or downgrade when the claim outruns the evidence
+- `delivery_posture` and `release_claim_posture` must remain compatible: `repo_closeout` and `runtime_validated_closeout` pair with `repo_only`; `delivery_supported_closeout` pairs with `delivery_sensitive`
+- local-only `.planning/` proof may support `repo_closeout`, but public-facing release/support claims need tracked public or repo-visible evidence when intended for external readers
 </evidence_contract>
 
 <process>
@@ -114,6 +125,7 @@ Combine:
 - Phase-level gaps and tech debt (from step 2)
 - Integration checker's report (wiring gaps, auth gaps, broken flows, requirements integration map)
 - Evidence observations by kind (`code`, `test`, `runtime`, `delivery`, `human`) from phase verifications, summaries, integration findings, and delivery metadata
+- Release claim posture observations: selected `release_claim_posture`, unsupported claims, waivers, deferrals, and contradiction checks for public, runtime, delivery, planning-drift, and generated-surface claims
 
 ## 5. 3-Source Cross-Reference
 
@@ -170,10 +182,22 @@ audited: {ISO-8601 timestamp}
 status: passed | gaps_found | tech_debt
 reduced_assurance: false
 delivery_posture: repo_only | delivery_sensitive
+release_claim_posture: repo_closeout | runtime_validated_closeout | delivery_supported_closeout
 evidence_contract:
   required_kinds: [code, test]
   observed_kinds: [code, test]
   missing_kinds: []
+release_claim_contract:
+  unsupported_claims: []
+  waivers: []
+  deferrals: []
+  contradiction_checks:
+    evidence: passed | failed
+    public_surface: passed | failed | not_applicable
+    runtime: passed | failed | not_applicable
+    delivery: passed | failed | not_applicable
+    planning_drift: passed | failed
+    generated_surface: passed | failed | not_applicable
 scores:
   requirements: N/M
   phases: N/M
@@ -213,6 +237,10 @@ Evidence gate:
 - a `passed` audit must have no `missing_kinds` for the selected `delivery_posture`
 - `delivery_sensitive` audits cannot pass without explicit `runtime` and `delivery` evidence
 - `repo_only` audits cannot be downgraded merely because `runtime` or `delivery` evidence was never relevant
+- a `passed` audit must have no unsupported stronger release claims unless they are explicitly downgraded or deferred in `release_claim_contract`
+- invalid waivers are blockers: human approval cannot replace missing `code`, `test`, `runtime`, or `delivery` evidence for a stronger claim
+- public/support wording must be scoped to tracked public or repo-visible evidence; local-only `.planning/` artifacts cannot carry public release claims by themselves
+- generated-surface freshness is claim-scoped: W11-style drift blocks only claims that depend on generated runtime/helper freshness, not unrelated repo-only closeout
 
 **MANDATORY: The milestone audit report must exist at `.planning/v{version}-MILESTONE-AUDIT.md` on disk before presenting results. If the file was not written, STOP and report the write failure. Do NOT present audit results from conversation context alone — this is the highest-cost artifact to regenerate. Do NOT downgrade a write failure into "results shown inline anyway."**
 
@@ -222,7 +250,7 @@ Route by audit status:
 
 ### If passed:
 - Report: all requirements covered, cross-phase integration verified, auth protection verified, E2E flows complete
-- Next step: complete the milestone (archive and tag)
+- Next step: complete the milestone (archive; any tag remains advisory and evidence-scoped)
 
 ### If gaps_found:
 - Report: list unsatisfied requirements, auth or cross-phase issues, broken flows

package/distilled/workflows/complete-milestone.md

@@ -1,5 +1,5 @@
 <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.
+You are the MILESTONE CLOSER. Your job is to formally archive a completed 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.
 
@@ -54,14 +54,27 @@ Stable evidence kinds carried forward from audit:
 
 Read the audit frontmatter and preserve:
 - `delivery_posture`
+- `release_claim_posture`
 - `evidence_contract.required_kinds`
 - `evidence_contract.observed_kinds`
 - `evidence_contract.missing_kinds`
+- `release_claim_contract.unsupported_claims`
+- `release_claim_contract.waivers`
+- `release_claim_contract.deferrals`
+- `release_claim_contract.contradiction_checks`
 
 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
+- release claim postures are inherited from audit:
+  - `repo_closeout` permits repo-local milestone closure only and must not imply public support, delivery, runtime validation, generated-surface freshness, package publication, tags, or GitHub Releases
+  - `runtime_validated_closeout` may name only the runtime or surface with explicit `runtime` evidence
+  - `delivery_supported_closeout` requires the audit's `delivery_sensitive` bar plus concrete `delivery` evidence for the public/release/support claim
+- inherited `delivery_posture` and `release_claim_posture` must be compatible: `repo_closeout` and `runtime_validated_closeout` use `repo_only`; `delivery_supported_closeout` uses `delivery_sensitive`
+- waivers are valid only when they narrow the release claim or defer an unsupported claim. Deferrals must name the unsupported claim, missing evidence kind(s), and later workflow or milestone candidate when known. STOP if a waiver preserves a stronger claim while required evidence is missing.
+- STOP if `release_claim_contract.unsupported_claims` remain without downgrade or deferral, if unsupported claims, invalid waivers, or failed contradiction checks remain, or if completion wording would claim more than the audit evidence supports. Failed contradiction checks are claim-scoped: generated-surface failures block only runtime/generated freshness claims, not unrelated `repo_closeout` completion.
+- local-only `.planning/` proof can support repo closeout, but cannot become public release proof by itself.
 </evidence_contract>
 
 <process>
@@ -72,22 +85,18 @@ 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?
+- **Release claim posture**: Does the passed audit include compatible `delivery_posture`/`release_claim_posture` values and `release_claim_contract`, with unsupported claims either downgraded or deferred, no invalid waivers, and no failed claim-scoped contradiction checks?
 - **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:**
+**If phases incomplete, audit not passed, the audit evidence contract is missing/insufficient, or the inherited release claim contract has unsupported claims, invalid waivers, missing/failed claim-scoped contradiction checks, incompatible posture metadata, or invalid posture metadata:**
 
-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 without archiving. Route to the narrowest corrective workflow instead:
+1. **Run audit first** — `/gsdd-audit-milestone` if audit is missing, stale, or missing required release-claim schema.
+2. **Close gaps first** — `/gsdd-plan-milestone-gaps` if audit found gaps or the release claim outruns available evidence.
+3. **Abort** — stop without archiving if the user does not want corrective work now.
 
-**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.
+**If all phases complete, audit passed, the audit evidence contract is satisfied, and the inherited release claim contract has no unsupported stronger claims:** Proceed.
 
 ## 2. Determine Version
 
@@ -101,6 +110,7 @@ Extract from phase SUMMARY.md files and git:
 - 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
+- Inherited closeout posture: `delivery_posture`, `release_claim_posture`, waivers, deferrals, and contradiction check result from the passed audit
 
 Present a concise stats block for review.
 
@@ -117,10 +127,10 @@ Create `.planning/milestones/v[X.Y]-ROADMAP.md` with full milestone details:
 ```markdown
 # Milestone v[X.Y]: [Name]
 
-**Status:** ✅ SHIPPED [date]
+**Status:** ✅ COMPLETED [date]
 **Phases:** [N]–[M]
 **Total Plans:** [count]
-**Tag:** v[X.Y]
+**Suggested tag:** v[X.Y] (advisory only; do not imply this tag exists unless git confirms it)
 
 ## Overview
 
@@ -218,7 +228,10 @@ Append an entry to `.planning/MILESTONES.md`:
 
 **Phases:** [N]–[M] | **Plans:** [count] | **Tasks:** [count] | **Tests:** [N] assertions, 0 failures
 
-**Delivered:** [One sentence summary of what shipped.]
+**Completed:** [One sentence summary of what the milestone closed.]
+
+**Release claim posture:** [repo_closeout | runtime_validated_closeout | delivery_supported_closeout]
+**Unsupported claims deferred:** [none or concise list]
 
 **Key accomplishments:**
 1. [Accomplishment 1]
@@ -228,14 +241,14 @@ Append an entry to `.planning/MILESTONES.md`:
 
 **Archive:** `.planning/milestones/v[X.Y]-ROADMAP.md`
 **Requirements:** `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
-**Tag:** `v[X.Y]`
+**Suggested tag:** `v[X.Y]` (advisory; omit or mark not created unless git confirms it exists)
 ```
 
 ## 9. Evolve SPEC.md
 
 Update SPEC.md to reflect the completed milestone:
 
-**Move shipped requirements:**
+**Move completed requirements:**
 - Move all Must Have requirements that were satisfied this milestone to the `### Validated (existing capabilities)` section
 - Format: `- [x] **[ID]**: [title] — [brief outcome note]`
 
@@ -244,7 +257,7 @@ Update SPEC.md to reflect the completed milestone:
 ```markdown
 ## Current State
 
-- **Milestone:** v[X.Y] [Name] — SHIPPED [date]
+- **Milestone:** v[X.Y] [Name] — COMPLETED [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]
@@ -264,12 +277,12 @@ Replace the active milestone phases in ROADMAP.md with a collapsed `<details>` b
 
 ## Milestones
 
-- ✅ **v[X.Y] [Name]** — Phases [N]–[M] (shipped [date])
+- ✅ **v[X.Y] [Name]** — Phases [N]–[M] (completed [date])
 
 ## Phases
 
 <details>
-<summary>✅ v[X.Y] [Name] (Phases [N]–[M]) — SHIPPED [date]</summary>
+<summary>✅ v[X.Y] [Name] (Phases [N]–[M]) — COMPLETED [date]</summary>
 
 - [x] **Phase [N]: [Name]** — completed [date]
 - [x] **Phase [N+1]: [Name]** — completed [date]
@@ -298,7 +311,7 @@ Advisory: Tag this milestone in git:
 </process>
 
 <success_criteria>
-- [ ] Readiness verified (phases complete + audit passed, or user chose to proceed with gaps)
+- [ ] Readiness verified (phases complete, audit passed, evidence contract satisfied, and inherited release claim contract valid)
 - [ ] Version confirmed
 - [ ] Stats gathered from SUMMARY.md files and git
 - [ ] Accomplishments extracted and reviewed
@@ -306,7 +319,7 @@ Advisory: Tag this milestone in git:
 - [ ] `.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
+- [ ] SPEC.md Current State updated to reflect completed status
 - [ ] ROADMAP.md collapsed with `<details>` block pointing to archive
 - [ ] Advisory git tag suggestion presented
 </success_criteria>
@@ -330,7 +343,7 @@ Archived:
 
 Also available:
 - `/gsdd-progress` — check overall project status
-- `/gsdd-audit-milestone` — re-audit before archiving (if you skipped the audit)
+- `/gsdd-audit-milestone` — re-audit if source truth changed before archive
 
 Consider clearing context before starting the next workflow for best results.
 ---

package/distilled/workflows/execute.md

@@ -6,15 +6,20 @@ 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 only the context needed for the next safe action. Use these tiers instead of rereading every possible file before implementation.
+
+### mandatory_now
+Read before mutation: target `PLAN.md` frontmatter/current task/boundaries; bounded `.planning/SPEC.md` current state, active requirement IDs, and relevant constraints; `.planning/ROADMAP.md` phase goal/status/success criteria; immediately prior `.planning/phases/*-SUMMARY.md` `<judgment>` when present; and the preflight result from `<lifecycle_preflight>`.
+If no immediately prior SUMMARY `<judgment>` exists, check whether `.planning/.continue-here.bak` exists before mutation. If it exists, read its `<judgment>`, honor `<anti_regression>`, `<active_constraints>`, and `<decision_posture>`, then run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok` (workflow-owned auto-clean).
+
+### task_scoped
+Read before editing each task, not all at startup: current task `<files>` entries, relevant source needed for current symbols/callers/tests/generated surfaces, and focused neighboring references found by targeted search.
+
+### reference_only
+Consult deeper `.planning/SPEC.md` and `.planning/ROADMAP.md` sections only for the specific decision, requirement, or status being validated.
+
+### deferred_or_conditional
+Read only when the current task or a deviation needs them: older phase summaries and broader historical context beyond the mandatory-now handoff.
 </load_context>
 
 <repo_root_helper_contract>
@@ -23,9 +28,7 @@ All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current w
 
 <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:
@@ -52,7 +55,6 @@ If plan runtime/assurance is missing, use `status: unknown`.
 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.
@@ -70,7 +72,6 @@ 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.
@@ -79,7 +80,6 @@ For each wave in ascending order:
 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.
@@ -98,14 +98,14 @@ 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.
+2. Read the task_scoped files and focused references needed for that task.
+3. Implement the task action.
+4. Run the task's verify steps.
+5. Handle any git actions using repo or user conventions.
+6. 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:
@@ -120,15 +120,12 @@ Checkpoint tasks are contract boundaries. Continuing past one silently breaks th
 - 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.
+- Do not run destructive git, broad cleanup, or file deletion actions without explicit human approval, except explicitly named workflow-owned housekeeping commands such as `.planning/.continue-here.bak` auto-clean.
 
 ### 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.
+Before modifying any existing behavior, run a targeted ripple check for the current task:
+1. Search before you change.
+   Search for the specific symbol, file path, command, status word, or contract term being changed. Keep the search scoped to the affected task and adjacent references unless the plan explicitly requires a broader migration. Update every relevant reference you find.
    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.
@@ -136,11 +133,10 @@ Before modifying any existing behavior, run a ripple check:
    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.
+   When removing an import, function, or variable, search 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**
@@ -290,13 +286,17 @@ Keep the update factual and compact:
 
 ### 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
+### 3. Rebaseline Reviewed Planning State
+After `.planning/SPEC.md` and `phase-status` updates are complete and reviewed as intentional, run:
+- `node .planning/bin/gsdd.mjs session-fingerprint write`
+This is the explicit planning-state handoff. Do not rely on a no-op `phase-status` command to rebaseline SPEC drift.
+
+### 4. Write Phase Summary
 Create `.planning/phases/{phase_dir}/{plan_id}-SUMMARY.md` with:
 
 ```markdown
@@ -410,7 +410,8 @@ For each completed task:
 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
+  [ ] `node .planning/bin/gsdd.mjs session-fingerprint write` ran after reviewed SPEC and phase-status updates
+  [ ] SUMMARY.md exists with `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` and reflects the actual work
 
 Overall:
   [ ] Any git actions taken match what you are reporting
@@ -426,13 +427,14 @@ 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
+- [ ] Mandatory-now context and task-scoped files read at the correct execution point
 - [ ] 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
+- [ ] `node .planning/bin/gsdd.mjs session-fingerprint write` was run after reviewed planning-state updates
 - [ ] `SUMMARY.md` is written
 - [ ] `SUMMARY.md` frontmatter records `runtime` and `assurance`
-- [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, and `<deltas>` sections
+- [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` sections
 - [ ] Self-check passed
 - [ ] Any git actions honor repo or user conventions and `.planning/config.json`
 </success_criteria>