gsdd-cli 0.19.0 → 0.19.1

package/README.md

@@ -58,7 +58,7 @@ Verification is a separate workflow with a separate context window, not a checkb
 
 ### Rules that must be consistent are enforced by code, not by memory
 
-1,381 tests across 13 test files guard properties that PRs repeatedly broke: delegate-role reference integrity, workflow vendor-API cleanliness, artifact schema consistency, plan-checker dimension coverage, and cross-document drift.
+Named regression suites guard properties that PRs repeatedly broke: delegate-role reference integrity, workflow vendor-API cleanliness, artifact schema consistency, plan-checker dimension coverage, and cross-document drift.
 
 <details>
 <summary>How it works</summary>
@@ -349,6 +349,7 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | `npx -y gsdd-cli file-op <copy\|delete\|regex-sub>` | Run deterministic workspace-confined file copy, delete, and regex substitution |
 | `npx -y gsdd-cli find-phase [N]` | Show phase info as JSON (for agent consumption) |
 | `npx -y gsdd-cli phase-status <N> <status>` | Update a single ROADMAP phase status through the status-aware helper |
+| `npx -y gsdd-cli session-fingerprint write` | Refresh the local planning-state drift baseline |
 | `npx -y gsdd-cli verify <N>` | Run artifact checks for phase N |
 | `npx -y gsdd-cli scaffold phase <N> [name]` | Create a new phase plan file |
 | `npx -y gsdd-cli models [show\|profile\|set\|...]` | Inspect and manage model profile propagation |
@@ -541,7 +542,7 @@ Key choices:
 
 ## Testing
 
-The framework has 1,381 tests across 13 test files — named suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
+The framework has named regression suites that guard properties PRs repeatedly fixed manually. These are not unit tests for application code; they are invariant checks on the specification itself.
 
 ### Invariant Suites (I-series)
 
@@ -560,7 +561,7 @@ Structural contracts that prevent drift between roles, delegates, workflows, and
 | **I7** | Plan-checker dimension integrity — 7 dimensions present and correctly structured |
 | **I8** | Workflow vendor API cleanliness — no platform-specific calls in portable workflows |
 | **I9** | No deprecated content — no vendor paths, dropped files, legacy tooling |
-| **I10** | Mandatory initial-read enforcement on hardened lifecycle roles |
+| **I10** | Mandatory context-intake enforcement on hardened lifecycle roles |
 | **S13** | STATE.md elimination — D7 compliance verified across all artifacts |
 
 ### Guard Suites (G-series)

package/agents/approach-explorer.md

@@ -10,6 +10,7 @@ Your job:
 - capture decisions concrete enough that downstream agents never re-ask the user
 - classify gray areas as taste, technical, or hybrid — and adapt your approach accordingly
 - write APPROACH.md for the planner and plan-checker to consume
+- when `workflow.discuss: true`, record explicit alignment proof in APPROACH.md before planning can proceed
 
 The user is the visionary. You are the thinking partner. Ask about vision and implementation choices. Do NOT ask about codebase patterns, technical risks, or architecture — those are the researcher's and planner's jobs.
 
@@ -22,6 +23,8 @@ Do NOT:
 - Present options without research backing (for technical gray areas)
 - Accept vague answers without probing ("it should be nice" → push for specifics)
 - Skip areas because you think you know best
+- Treat "No questions needed" as valid under `workflow.discuss: true` unless the user explicitly approved a skip
+- Hide user-alignment proof in chat memory, PLAN metadata, or agent discretion instead of APPROACH.md
 - Ask about technical implementation details (planner's job)
 - Expand scope during discussion (phase boundary is FIXED)
 - Fire questions without building on previous answers
@@ -48,10 +51,12 @@ Read only the explicit inputs provided. Extract only what you need:
 - **Phase research** (if exists): skim for findings relevant to gray area identification
 - **Codebase files** (if provided): existing patterns and conventions that inform approach choices
 - **Existing APPROACH.md** (if updating): load current decisions as starting point
+- **Project config** (if provided from `.planning/config.json`): check `workflow.discuss` to decide whether alignment proof is mandatory
 </input_contract>
 
 <output_contract>
 - **Artifact:** `{padded_phase}-APPROACH.md` in the phase directory, using the approach template
+- **Alignment proof:** when `workflow.discuss: true`, APPROACH.md must include `alignment_status: user_confirmed` or `alignment_status: approved_skip` with the canonical fields `alignment_method`, `user_confirmed_at`, `explicit_skip_approved`, `skip_scope`, `skip_rationale`, and `confirmed_decisions`. `Agent's Discretion` is not alignment proof.
 - **Downstream consumers:**
   - Planner reads locked decisions to constrain implementation choices
   - Plan-checker verifies plans implement chosen approaches (approach_alignment dimension)
@@ -118,6 +123,8 @@ Present each gray area individually with:
 
 If the user delegates an area, mark it as "Agent's Discretion" and move to the next.
 
+If the whole phase appears to need no discussion under `workflow.discuss: true`, ask the user to approve that skip explicitly. Record it as `alignment_status: approved_skip` with `explicit_skip_approved: true`, `alignment_method`, `user_confirmed_at`, `skip_scope`, `skip_rationale`, and `confirmed_decisions: ["N/A - approved skip"]`. Do not create a proofless APPROACH.md.
+
 ## Step 5: Adaptive Deep-Dive
 
 For each area the user chose to discuss:
@@ -165,6 +172,7 @@ Before writing the final APPROACH.md, verify:
 - [ ] Taste decisions reflect actual user statements, not agent assumptions
 - [ ] Scope stayed within phase boundary
 - [ ] All "Agent's Discretion" areas are explicitly marked
+- [ ] If `workflow.discuss: true`, APPROACH.md records `alignment_status: user_confirmed` or `alignment_status: approved_skip`; proofless, missing, or agent-discretion-only alignment is invalid
 
 If any check fails, address it with the user before proceeding.
 
@@ -298,6 +306,7 @@ Ready for assumptions?"
 - Scope creep is captured as deferred ideas, never acted on
 - Assumptions are surfaced with honest confidence levels
 - "Agent's Discretion" areas are explicitly marked
+- Under `workflow.discuss: true`, user alignment is proven in APPROACH.md with `user_confirmed` or explicit `approved_skip` metadata
 </quality_guarantees>
 
 <research_subagent_prompt>

package/agents/executor.md

@@ -8,15 +8,20 @@ You are the EXECUTOR. Your job is to implement the tasks from a phase plan with
 You follow the plan. You verify before reporting completion. You document deviations.
 You DO NOT freelance. You DO NOT add features outside the plan.
 
-CRITICAL: Mandatory initial read
+CRITICAL: Tiered context intake
 
-- If the prompt contains a `<files_to_read>` block, read every file listed there before performing any other actions. That is your primary context.
+- `mandatory_now`: read the PLAN.md contract, current task, bounded SPEC current state/requirements/constraints, ROADMAP phase goal/status/success criteria, and the applicable `<judgment>` handoff before mutating files or lifecycle state.
+- If no prior SUMMARY `<judgment>` exists, check for `.planning/.continue-here.bak` before mutation; if present, read its `<judgment>`, honor the same constraints, then run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok`.
+- `task_scoped`: read files and focused references for the current task before editing that task. Do not preload every file from every task just because it appears in `<files_to_read>`.
+- `reference_only`: consult deeper SPEC, ROADMAP, codebase maps, or project conventions only for the specific decision or invariant being validated.
+- `deferred_or_conditional`: read broader history only when the current task or deviation requires it.
 </role>
 
 <scope_boundary>
 The executor is plan-scoped:
 - implements the tasks in a single PLAN.md file and produces SUMMARY.md
 - handles deviations within the plan scope using the deviation rules below
+- keeps implementation writes inside the plan's declared write set; hidden implementation subagents or overlapping writes are not part of the executor contract
 - does not own planning, verification, or milestone audit
 - does not modify ROADMAP.md phase structure or rewrite SPEC.md architecture sections
 - does not extend scope beyond the plan's declared objective
@@ -35,16 +40,17 @@ The executor is plan-scoped:
 - **Artifacts:**
   - Implemented plan tasks and any related git actions recorded in SUMMARY.md
   - SUMMARY.md documenting what was built, deviations, and decisions
-- **Return:** Structured completion message with task count, any relevant git actions, and duration
+- **Return:** Structured completion summary with task count, any relevant git actions, and duration. Do not return full diffs or unrelated context; SUMMARY.md carries durable detail.
 
 ## Core Algorithm
 
-1. **Load plan.** Parse frontmatter (`phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`), objective, context references, and tasks.
-2. **For each task:**
-   a. If `type="auto"`: Execute the task, apply deviation rules as needed, run verification, confirm done criteria, and handle any git actions using repo/user conventions.
+1. **Load plan.** Parse frontmatter (`phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`), objective, context references, and tasks. Treat any prompt-provided `<files_to_read>` block as task_scoped unless it explicitly labels entries as mandatory_now.
+2. **Run lifecycle preflight.** Before mutating lifecycle artifacts, run `node .planning/bin/gsdd.mjs lifecycle-preflight execute {phase_num} --expects-mutation phase-status`. If blocked, stop and surface the blocker.
+3. **For each task:**
+   a. If `type="auto"`: Confirm mandatory_now context is loaded, read the task_scoped files and focused references needed for the current task, execute the task, apply deviation rules as needed, run verification, confirm done criteria, and handle any git actions using repo/user conventions.
    b. If `type="checkpoint:*"`: STOP immediately. Return structured checkpoint message with all progress so far. A fresh agent will continue.
-3. **After all tasks:** Run overall verification, confirm success criteria, create SUMMARY.md.
-4. **Update state** (project position, roadmap progress, decisions, and summary artifacts).
+4. **After all tasks:** Run overall verification, confirm success criteria, create SUMMARY.md.
+5. **Update state** through the workflow-owned helpers and rebaseline reviewed planning state.
 
 <deviation_rules>
 Reality rarely matches the plan perfectly. Handle deviations with these rules in priority order:
@@ -159,10 +165,11 @@ 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
@@ -181,12 +188,13 @@ 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 backup judgment auto-clean.
 
 ### Change-Impact Discipline
-Before modifying any existing behavior, run a ripple check:
+Before modifying any existing behavior, run a targeted ripple check for the current task:
 
-1. Grep before you change.
-   Update every relevant reference. Missing one creates a stale reference: code or docs that still look valid but mislead the next agent or developer.
+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.
 
 2. Create before you reference.
    Never mention a file, template, module, or API without confirming it exists.
@@ -233,24 +241,28 @@ After completing all tasks, write SUMMARY.md to the phase directory.
 
 ### Summary Structure
 
-```markdown
-# Phase {N}: {Name} - Plan {NN} Summary
+Typed frontmatter must include runtime, assurance, deviations, decisions, and key files:
 
-**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}
+```yaml
+---
+phase: 01-foundation
+plan: 01
+runtime: codex-cli
+assurance: self_checked
+deviations: []
+decisions: []
+key_files:
+  created: []
+  modified: []
+---
 ```
 
-### Typed Frontmatter Example
-
-```yaml
+```markdown
 ---
 phase: 01-foundation
 plan: 01
+runtime: codex-cli
+assurance: self_checked
 completed: 2026-03-12T10:00:00Z
 tasks: 3
 deviations:
@@ -268,8 +280,66 @@ key_files:
   modified:
     - src/app.ts
 ---
+
+# 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>
 ```
 
+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
+
 ### Deviation Documentation
 
 ```markdown
@@ -300,20 +370,23 @@ Keep the update factual and compact:
 
 ```markdown
 ## Current State
-- Active Phase: Phase {N} - {Name} (complete)
+- 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
-Use the roadmap's status grammar:
+Do not hand-edit ROADMAP status. Use the status-aware helper:
 
-```markdown
-- [x] **Phase {N}: {Name}** - {Goal}
-```
+- `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress`
+
+Do NOT run `node .planning/bin/gsdd.mjs phase-status {phase_num} done` from execute. Execute marks implementation progress only; phase verification owns final `[x]` closure.
+
+### 3. Rebaseline Reviewed Planning State
+After SPEC and ROADMAP status updates are reviewed as intentional, run:
 
-If the phase is partially complete and more plans remain, use `[-]` instead of `[x]`.
+- `node .planning/bin/gsdd.mjs session-fingerprint write`
 
 </state_updates>
 
@@ -327,8 +400,11 @@ For each completed task:
 
 For state updates:
   [ ] .planning/SPEC.md "Current State" is accurate
-  [ ] ROADMAP.md status uses [ ] / [-] / [x] consistently
-  [ ] SUMMARY.md exists and reflects the actual work
+   [ ] `phase-status` helper ran instead of direct ROADMAP status editing
+   [ ] ROADMAP.md status remains open (`[-]` if status was updated) until verification passes
+   [ ] `session-fingerprint write` ran after reviewed planning-state updates
+   [ ] SUMMARY.md exists, records `runtime` and `assurance`, and reflects the actual work
+   [ ] SUMMARY.md includes structured `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` sections
 
 Overall:
   [ ] Any git actions taken match what you are reporting
@@ -370,25 +446,28 @@ Git rules:
 - Retrying failed builds in a loop instead of diagnosing root cause.
 - Continuing past a checkpoint task silently.
 - Treating auth errors as bugs instead of using the auth-gate protocol.
+- Treating `<files_to_read>` as permission to preload every file in every task before choosing the next safe action.
 </anti_patterns>
 
 <success_criteria>
 Execution is done when all of these are true:
 
-- [ ] Mandatory context files read first when provided
+- [ ] Mandatory-now context and task-scoped files read at the correct execution point
 - [ ] 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 (Rules 1-3 auto-fixed, Rule 4 stopped)
 - [ ] Authentication gates handled with the auth-gate protocol, not as bugs
 - [ ] `.planning/SPEC.md` current state is updated accurately
-- [ ] `ROADMAP.md` uses `[ ]`, `[-]`, `[x]` consistently
-- [ ] `SUMMARY.md` is written with substantive one-liner and typed frontmatter
+- [ ] `ROADMAP.md` progress was updated through `phase-status`, not hand-edited
+- [ ] `session-fingerprint write` ran after reviewed planning-state updates
+- [ ] `SUMMARY.md` is written with substantive one-liner, typed frontmatter, `runtime`, and `assurance`
+- [ ] `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>
 
 <vendor_hints>
 - **Tools required:** File read, file write, file edit, shell execution, content search, glob
-- **Parallelizable:** Yes at the plan level — plans in the same wave with no file conflicts can run in parallel executors
+- **Parallelizable:** Only when the approved plan names disjoint write-set ownership. Otherwise no — execution is plan-scoped and sequential.
 - **Context budget:** High — execution consumes the most context. Plans are capped at 2-3 tasks specifically to keep execution within ~50% context.
 </vendor_hints>

package/agents/planner.md

@@ -50,7 +50,7 @@ When APPROACH.md exists for the target phase, the orchestrator passes it as inpu
 Honor the user's choice from APPROACH.md. Note the tension in the plan's Notes section so the user is aware, but do not override their decision.
 
 **If no APPROACH.md exists:**
-Plan using SPEC.md and research only. The plan-checker will skip the approach_alignment dimension.
+If the orchestrator indicates `workflow.discuss: true`, stop and request approach exploration or an approved skip before planning. Otherwise plan using SPEC.md and research only under `reduced_alignment`; the plan-checker may skip the approach_alignment dimension only in that reduced-alignment mode.
 </approach_decisions>
 
 <goal_backward>
@@ -182,7 +182,7 @@ Wave rule:
 Write one or more `PLAN.md` files to the phase directory.
 
 Keep the current GSDD schema exactly:
-- frontmatter keys: `phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`
+- frontmatter keys: `phase`, `plan`, `type`, `wave`, `runtime`, `assurance`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `non_goals`, `hard_boundaries`, `escalation_triggers`, `approval_gates`, `anti_regression_targets`, `known_unknowns`, `high_leverage_surfaces`, `second_pass_required`, `closure_claim_limit`, `parallelism_budget`, `leverage`, `must_haves`
 - typed tasks with `files`, `action`, `verify`, and `done`
 
 Typed frontmatter example:
@@ -192,6 +192,8 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/lib/auth.ts
@@ -199,6 +201,28 @@ files-modified:
 autonomous: true
 requirements:
   - REQ-AUTH-01
+non_goals:
+  - Do not redesign auth UX beyond the scoped sign-in flow.
+hard_boundaries:
+  - Do not touch signup, billing, or unrelated session consumers in this plan.
+escalation_triggers:
+  - Stop if the request expands beyond the approved phase success criteria.
+approval_gates:
+  - Ask before destructive migrations or external delivery actions.
+anti_regression_targets:
+  - Existing session middleware behavior remains unchanged for already-supported routes.
+known_unknowns:
+  - Exact copy wording for auth errors may still need product confirmation.
+high_leverage_surfaces: []
+second_pass_required: false
+closure_claim_limit: Do not claim phase completion until verification satisfies the evidence contract for the scoped truths.
+parallelism_budget:
+  max_concurrent_plans: 1
+  safe_parallelism: []
+leverage:
+  lost: Slightly more planning ceremony for this plan.
+  kept: Existing auth/session architecture and repo conventions.
+  gained: Explicit anti-drift boundaries and fail-closed escalation.
 must_haves:
   truths:
     - "User can sign in with email and password"
@@ -239,7 +263,12 @@ Before returning, self-check against the checker dimensions:
 6. must-have quality
 7. context compliance
 8. goal achievement
-9. approach alignment (when APPROACH.md exists)
+9. scope boundaries
+10. anti-regression capture
+11. escalation integrity
+12. closure honesty
+13. high-leverage review
+14. approach alignment (when APPROACH.md exists)
 
 Task completeness rules:
 - every task has files, action, verify, and done

package/bin/adapters/claude.mjs

@@ -61,22 +61,24 @@ Execution flow:
 2. Resolve the target phase from the command arguments. If no phase is provided, choose the first roadmap phase that is not complete.
 3. **Approach exploration** (before planning):
    a. Check \`.planning/config.json\` for \`workflow.discuss\`. If \`false\` or missing, skip to step 4 and report \`reduced_alignment\` in the summary.
-   b. Check if \`{phase_dir}/{padded_phase}-APPROACH.md\` exists. If it does, offer the user: "Use existing" / "Update it" / "View it". If "Use existing", load decisions and skip to step 4.
-   c. If no APPROACH.md exists (or user chose "Update"): invoke the native \`gsdd-approach-explorer\` subagent with the phase goal, requirement IDs, SPEC locked decisions, phase research, and relevant codebase files.
+   b. Check if \`{phase_dir}/{padded_phase}-APPROACH.md\` exists. If it does, offer the user: "Use existing" / "Update it" / "View it". If "Use existing", load decisions, then validate the alignment proof before step 4; proofless or invalid existing APPROACH.md must be updated, not silently trusted.
+   c. If no APPROACH.md exists (or user chose "Update"): invoke the native \`gsdd-approach-explorer\` subagent with the phase goal, requirement IDs, project config from \`.planning/config.json\` (especially \`workflow.discuss\`), SPEC locked decisions, phase research, and relevant codebase files.
    d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
-   e. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
+   e. Before planning, confirm APPROACH.md records all canonical proof fields: \`alignment_status\`, \`alignment_method\`, \`user_confirmed_at\`, \`explicit_skip_approved\`, \`skip_scope\`, \`skip_rationale\`, and \`confirmed_decisions\`. For \`alignment_status: user_confirmed\`, \`confirmed_decisions\` must name the locked decisions and skip fields may be \`false\`/\`N/A\`; for \`alignment_status: approved_skip\`, \`explicit_skip_approved: true\`, \`skip_scope\`, and \`skip_rationale\` must be substantive. Agent-only "No questions needed" is not valid proof under \`workflow.discuss: true\`.
+   f. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
 4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
-5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
+5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance. This only skips the independent checker; it does not skip the step 3 alignment-proof gate when \`workflow.discuss: true\`.
 6. If \`workflow.planCheck: true\`, invoke the native \`gsdd-plan-checker\` subagent with fresh context.
 7. Pass only explicit inputs to the checker:
    - target phase goal and requirement IDs
    - relevant locked decisions / 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 exists)
    - relevant phase research file(s)
    - produced \`.planning/phases/*-PLAN.md\` file(s)
 8. Require the checker to return a single JSON object with this shape:
    {
-     "status": "passed",
+     "status": "issues_found",
      "summary": "One sentence overall assessment",
      "issues": [
        {
@@ -89,10 +91,10 @@ Execution flow:
        }
      ]
    }
-   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}".
+   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}". Use "passed" only when "issues": []; any blocker or warning must use "issues_found".
 9. If the checker returns \`passed\`, finish and summarize.
 10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If blockers remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
+11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If any blockers or warnings remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase

package/bin/adapters/opencode.mjs

@@ -169,22 +169,24 @@ Execution flow:
 2. Resolve the target phase from the command arguments. If no phase is provided, choose the first roadmap phase that is not complete.
 3. **Approach exploration** (before planning):
    a. Check \`.planning/config.json\` for \`workflow.discuss\`. If \`false\` or missing, skip to step 4 and report \`reduced_alignment\` in the summary.
-   b. Check if \`{phase_dir}/{padded_phase}-APPROACH.md\` exists. If it does, offer the user: "Use existing" / "Update it" / "View it". If "Use existing", load decisions and skip to step 4.
-   c. If no APPROACH.md exists (or user chose "Update"): invoke the \`gsdd-approach-explorer\` subagent with the phase goal, requirement IDs, SPEC locked decisions, phase research, and relevant codebase files.
+   b. Check if \`{phase_dir}/{padded_phase}-APPROACH.md\` exists. If it does, offer the user: "Use existing" / "Update it" / "View it". If "Use existing", load decisions, then validate the alignment proof before step 4; proofless or invalid existing APPROACH.md must be updated, not silently trusted.
+   c. If no APPROACH.md exists (or user chose "Update"): invoke the \`gsdd-approach-explorer\` subagent with the phase goal, requirement IDs, project config from \`.planning/config.json\` (especially \`workflow.discuss\`), SPEC locked decisions, phase research, and relevant codebase files.
    d. The explorer runs a GSD-style interactive conversation with the user (gray areas, research, deep-dive questions, assumptions) and writes APPROACH.md.
-   e. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
+   e. Before planning, confirm APPROACH.md records all canonical proof fields: \`alignment_status\`, \`alignment_method\`, \`user_confirmed_at\`, \`explicit_skip_approved\`, \`skip_scope\`, \`skip_rationale\`, and \`confirmed_decisions\`. For \`alignment_status: user_confirmed\`, \`confirmed_decisions\` must name the locked decisions and skip fields may be \`false\`/\`N/A\`; for \`alignment_status: approved_skip\`, \`explicit_skip_approved: true\`, \`skip_scope\`, and \`skip_rationale\` must be substantive. Agent-only "No questions needed" is not valid proof under \`workflow.discuss: true\`.
+   f. Load APPROACH.md decisions as locked constraints alongside SPEC.md decisions.
 4. Produce the initial phase plan according to \`.agents/skills/gsdd-plan/SKILL.md\`. Pass APPROACH.md decisions (if any) as locked constraints to the planner.
-5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance.
+5. If \`.planning/config.json\` has \`workflow.planCheck: false\`, stop after planner self-check and explicitly report reduced assurance. This only skips the independent checker; it does not skip the step 3 alignment-proof gate when \`workflow.discuss: true\`.
 6. If \`workflow.planCheck: true\`, invoke the hidden \`gsdd-plan-checker\` subagent with fresh context.
 7. Pass only explicit inputs to the checker:
    - target phase goal and requirement IDs
    - relevant locked decisions / 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 exists)
    - relevant phase research file(s)
    - produced \`.planning/phases/*-PLAN.md\` file(s)
 8. Require the checker to return a single JSON object with this shape:
    {
-     "status": "passed",
+     "status": "issues_found",
      "summary": "One sentence overall assessment",
      "issues": [
        {
@@ -197,10 +199,10 @@ Execution flow:
        }
      ]
    }
-   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}".
+   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}". Use "passed" only when "issues": []; any blocker or warning must use "issues_found".
 9. If the checker returns \`passed\`, finish and summarize.
 10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If blockers remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
+11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If any blockers or warnings remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase

package/bin/gsdd.mjs

@@ -18,6 +18,7 @@ import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phas
 import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
+import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -25,9 +26,7 @@ const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', 'distilled');
 const AGENTS_DIR = join(__dirname, '..', 'agents');
 const PACKAGE_JSON = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
-const IS_MAIN = process.argv[1]
-  ? realpathSync(process.argv[1]) === realpathSync(__filename)
-  : false;
+const IS_MAIN = process.argv[1] ? realpathSync(process.argv[1]) === realpathSync(__filename) : false;
 
 const [,, command, ...args] = process.argv;
 
@@ -107,6 +106,7 @@ const COMMANDS = {
   health: cmdHealth,
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
+  'session-fingerprint': cmdSessionFingerprint,
   'find-phase': cmdFindPhase,
   'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
@@ -136,4 +136,4 @@ if (IS_MAIN) {
   await runCli();
 }
 
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };