Fix native approach alignment proof (#94)

* fix: enforce native approach alignment proof

* fix: align native plan checker schema

* fix: harden native approach proof gates

* fix: require canonical approach proof fields

* fix: align canonical approach proof schema

* fix: align checker severity schema

* fix: align planner checker contracts

* fix: align checker status examples

* fix: escalate unresolved checker warnings

Author: PatrickSys

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>

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,13 +192,37 @@ phase: 01-foundation
 plan: 01
 type: execute
 wave: 1
+runtime: claude-code
+assurance: self_checked
 depends_on: []
 files-modified:
   - src/lib/auth.ts
   - src/routes/session.ts
 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

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

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

bin/lib/plan-constants.mjs

@@ -7,6 +7,11 @@ export const PLAN_CHECK_DIMENSIONS = [
   'must_have_quality',
   'context_compliance',
   'goal_achievement',
+  'scope_boundaries',
+  'anti_regression_capture',
+  'escalation_integrity',
+  'closure_honesty',
+  'high_leverage_review',
   'approach_alignment',
 ];
 

distilled/DESIGN.md

@@ -1365,6 +1365,7 @@ Both paths produce identical output: `{padded_phase}-APPROACH.md` in the phase d
 | Questioning style | Rigid 4-question batched loop | Adaptive convergence (2-6 questions depending on complexity) | Fixed batch sizes don't match decision complexity. Some areas resolve in 2 questions, others need 6 |
 | Pre-question research | No research before asking | Research subagent per technical area returns structured summary before asking | Users make better decisions when presented with researched options and trade-offs |
 | Quality gate | None | Self-check before writing APPROACH.md (concrete decisions, no vague language, source backing, scope compliance) | Prevents weak outputs that force re-asking during planning |
+| Alignment proof gate | None | `APPROACH.md` records `alignment_status: user_confirmed` or explicit `approved_skip`, and planning validates this before goal-backward planning when `workflow.discuss: true` | Prevents native or existing-artifact paths from turning mandatory discussion into artifact theater |
 | Intermediate persistence | No persistence until final output | Confirmed decisions written to disk incrementally | Protects against context limits in long conversations |
 | Context loading | "Read everything" | JIT extraction guidance (e.g., "From SPEC.md read ONLY locked decisions") | Prevents context pollution with irrelevant content |
 | Plan-checker integration | None | New `approach_alignment` dimension in plan-checker | Verifies plans honor approach decisions, not just requirements |
@@ -1398,11 +1399,11 @@ Isolating research in subagents and returning compressed summaries follows the C
 
 **Trade-offs:**
 
-- Benefit: planner receives locked user decisions instead of guessing approaches; plan-checker can verify approach alignment; context stays lean via research isolation
+- Benefit: planner receives locked user decisions instead of guessing approaches; plan-checker can verify approach alignment; existing APPROACH artifacts are not trusted unless their alignment proof is valid; context stays lean via research isolation
 - Cost: adds one interactive step before planning (~5-15 minutes of user time per phase); hybrid architecture is more complex than a single monolithic workflow
 - Mitigation: `workflow.discuss: true|false` toggle in `.planning/config.json` allows skipping with explicit `reduced_alignment` reporting; taste areas skip research entirely. Default is `false` (opt-in) to stay consistent with GSDD's stripped-down identity; users enable it explicitly
 
-**GSDD implementation:** `agents/approach-explorer.md` (role contract), `distilled/templates/delegates/approach-explorer.md` (thin delegate), `distilled/templates/approach.md` (output template), `distilled/workflows/plan.md` (`<approach_exploration>` section), `agents/planner.md` (`<approach_decisions>` section), `distilled/templates/delegates/plan-checker.md` (`approach_alignment` dimension), `bin/adapters/claude.mjs` + `bin/adapters/opencode.mjs` + `bin/adapters/codex.mjs` (native agent rendering)
+**GSDD implementation:** `agents/approach-explorer.md` (role contract), `distilled/templates/delegates/approach-explorer.md` (thin delegate), `distilled/templates/approach.md` (output template), `distilled/workflows/plan.md` (`<approach_exploration>` section), `agents/planner.md` (`<approach_decisions>` section), `distilled/templates/delegates/plan-checker.md` (`approach_alignment` dimension), `bin/adapters/claude.mjs` + `bin/adapters/opencode.mjs` + `bin/adapters/codex.mjs` (native agent rendering), `tests/gsdd.guards.test.cjs`, `tests/gsdd.plan.adapters.test.cjs`, and `tests/gsdd.scenarios.test.cjs` (alignment-proof propagation coverage)
 
 ---