@exaudeus/workrail 3.33.0 → 3.34.1

package/docs/design/bridge-removal-pr-a-implementation-plan.md

@@ -0,0 +1,203 @@
+# PR-A Bridge Removal -- Implementation Plan
+
+**Date:** 2026-04-17
+**Branch:** `feat/mcp-simplify-remove-bridge`
+**Confidence:** High
+
+---
+
+## Problem Statement
+
+The WorkRail MCP server contains a bridge mechanism (bridge-entry.ts, primary-tombstone.ts, bridge-events.ts) that was built to solve port contention between multiple Claude Code windows. PR #512 (merged) introduced `worktrain console` as a standalone process that owns the dashboard UI independently of the MCP server. The bridge mechanism's reason for existence is gone. It adds ~1127 lines of reconnect state machine, spawn coordination, and tombstone logic that make startup non-deterministic (150ms probe delay) and increase operational complexity.
+
+---
+
+## Acceptance Criteria
+
+1. `src/mcp/transports/bridge-entry.ts` does not exist
+2. `src/mcp/transports/primary-tombstone.ts` does not exist
+3. `src/mcp/transports/bridge-events.ts` does not exist
+4. `src/mcp-server.ts` no longer imports or re-exports `startBridgeServer`, `detectHealthyPrimary`, or `waitForStdinReadable`
+5. `src/mcp-server.ts` no longer contains the auto-bridge detection block (lines 89-118 in current file)
+6. `src/mcp/transports/stdio-entry.ts` no longer imports from `primary-tombstone.ts` or `bridge-events.ts`
+7. `src/mcp/transports/http-entry.ts` no longer imports from `primary-tombstone.ts` or `bridge-events.ts`
+8. `npm run build` exits 0 with 0 TypeScript errors
+9. `npm test` exits 0
+
+---
+
+## Non-Goals
+
+- HttpServer removal (PR-B)
+- ToolContext changes
+- DI token cleanup
+- Any change to http-entry.ts transport logic (MCP-over-HTTP for bot services)
+- Modifying http-listener.ts or http-listener.test.ts
+- Removing `ctx.httpServer?.stop()` from shutdown hooks (HttpServer still starts in PR-A state)
+- Cleaning up `worktrain-spawn.ts` / `worktrain-await.ts` dashboard.lock fallback (chore PR later)
+
+---
+
+## Philosophy-Driven Constraints
+
+- **Architectural fixes over patches:** Delete root cause, not add flags
+- **YAGNI:** Delete all three modules with no callers
+- **Determinism:** Startup path must be a single unconditional call to `startStdioServer()` for stdio mode
+- **Commit type:** `chore(mcp)` -- internal cleanup, no user-visible behavior change, no tool contract change
+
+---
+
+## Invariants
+
+1. `WORKRAIL_TRANSPORT=http` path must still work -- `startHttpServer()` is called unconditionally for http mode
+2. `WORKRAIL_TRANSPORT=stdio` must call `startStdioServer()` directly after removal -- no probe, no bridge detection
+3. `mcp/index.ts` exports must be unchanged (confirmed: no bridge symbols were re-exported)
+4. `tests/integration/mcp-http-transport.test.ts` must pass -- MCP-over-HTTP transport is untouched
+
+---
+
+## Selected Approach
+
+**Direct deletion with targeted import removal.** Delete 3 source files and 3 test files. Remove their imports and call sites from 3 modified source files. TypeScript compiler verifies completeness at the import boundary.
+
+**Runner-up:** None. All alternatives were anti-patterns.
+
+---
+
+## Vertical Slices
+
+### Slice 1: Create branch and verify baseline
+
+- Create git branch `feat/mcp-simplify-remove-bridge` from current HEAD
+- Run `npm run build` to confirm baseline is green
+- Run `npm test` to confirm baseline test suite is green
+- **Done when:** Both commands exit 0
+
+### Slice 2: Delete source files
+
+- Delete `src/mcp/transports/bridge-entry.ts`
+- Delete `src/mcp/transports/primary-tombstone.ts`
+- Delete `src/mcp/transports/bridge-events.ts`
+- **Done when:** Files do not exist on disk
+
+### Slice 3: Delete test files
+
+- Delete `tests/unit/mcp/transports/bridge-entry.test.ts`
+- Delete `tests/unit/mcp/transports/primary-tombstone.test.ts`
+- Delete `tests/unit/mcp/stdin-probe.test.ts`
+- **Done when:** Files do not exist on disk
+
+### Slice 4: Modify mcp-server.ts
+
+Remove the following from `src/mcp-server.ts`:
+- Import of `startBridgeServer`, `detectHealthyPrimary` from `./mcp/transports/bridge-entry.js`
+- Re-export of `startBridgeServer`, `detectHealthyPrimary` from `./mcp/transports/bridge-entry.js`
+- `STDIO_CLIENT_PROBE_MS` constant (line 49)
+- `waitForStdinReadable` function (lines 62-82)
+- Auto-bridge detection block inside `main()` (lines 88-118)
+- Top JSDoc comment block (lines 11-24) describing auto-bridge -- replace with simplified description
+- **Done when:** File compiles with no errors referencing bridge-entry; `main()` calls `startStdioServer()` unconditionally for stdio mode
+
+### Slice 5: Modify stdio-entry.ts
+
+Remove from `src/mcp/transports/stdio-entry.ts`:
+- Import: `import { writeTombstone, clearTombstone } from './primary-tombstone.js'`
+- Import: `import { logBridgeEvent } from './bridge-events.js'`
+- Call: `logBridgeEvent({ kind: 'primary_started', transport: 'stdio' })` (line 39)
+- Call: `clearTombstone()` (line 44)
+- In `onBeforeTerminate`: remove the tombstone write block (lines 124-127: `const port = ctx.httpServer?.getPort(); if (port != null) { writeTombstone(port, process.pid); }`)
+- **Done when:** File compiles with no imports or references to deleted modules; `onBeforeTerminate` only calls `await ctx.httpServer?.stop()`
+
+### Slice 6: Modify http-entry.ts
+
+Remove from `src/mcp/transports/http-entry.ts` (tombstone/bridge-events call sites ONLY):
+- Import: `import { clearTombstone, writeTombstone } from './primary-tombstone.js'`
+- Import: `import { logBridgeEvent } from './bridge-events.js'`
+- Call: `logBridgeEvent({ kind: 'primary_started', transport: 'http', port })` (line 32)
+- Call: `clearTombstone()` (line 35)
+- In `onBeforeTerminate`: remove `if (boundPort != null) { writeTombstone(boundPort, process.pid); }` (lines 111-113)
+- **Done when:** File compiles with no imports or references to deleted modules; ALL transport logic (bindWithPortFallback, MCP endpoint registration, health endpoint) is unchanged
+
+### Slice 7: Build and test verification
+
+- Run `npm run build` -- must exit 0 with 0 errors
+- Run `npm test` -- must exit 0
+- **Done when:** Both commands succeed
+
+### Slice 8: Commit and push PR
+
+- `git add` the 6 deleted files and 3 modified source files
+- Commit with message: `chore(mcp): remove bridge, tombstone, and bridge-events from MCP server`
+- Push branch and create PR against main
+- **Done when:** PR is open
+
+---
+
+## Test Design
+
+**Tests to delete:**
+- `tests/unit/mcp/transports/bridge-entry.test.ts` -- imports deleted module
+- `tests/unit/mcp/transports/primary-tombstone.test.ts` -- imports deleted module
+- `tests/unit/mcp/stdin-probe.test.ts` -- imports `waitForStdinReadable` from mcp-server.ts (also deleted)
+
+**Tests that must stay green:**
+- `tests/unit/mcp-server.test.ts` -- reads mcp-server.ts as string; no assertion for bridge exports
+- `tests/unit/mcp/http-listener.test.ts` -- tests createHttpListener lifecycle; no bridge dependency
+- `tests/integration/mcp-http-transport.test.ts` -- tests MCP-over-HTTP; no bridge dependency
+- All other tests (no bridge imports in non-deleted test files)
+
+**No new tests required.** The change is a deletion; the verification is `npm run build` (0 errors) + `npm test`.
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Missed import in unexpected file | Low | Build failure | Grep sweep confirmed before implementation: only 7 files (5 src, 2 tests) import from deleted modules |
+| http-entry.ts transport logic broken | Low | Runtime failure | Tombstone call sites are isolated lines; transport logic verified as non-overlapping |
+| mcp-server.test.ts string assertions fail | Low | Test failure | Test file read in full; no assertion for bridge exports |
+
+---
+
+## PR Packaging Strategy
+
+Single PR. Branch: `feat/mcp-simplify-remove-bridge`. All 8 slices in one commit.
+
+Commit message: `chore(mcp): remove bridge, tombstone, and bridge-events from MCP server`
+
+PR description must include:
+- What was deleted and why (bridge mechanism superseded by standalone worktrain console)
+- What was NOT changed (http-entry.ts transport logic, http-listener.ts, ToolContext)
+- Link to design doc: `docs/design/stdio-simplification-design-candidates.md` PR-A section
+
+---
+
+## Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| All slices | Architectural fixes over patches | Satisfied -- root cause deleted, no shim |
+| Slice 2-3 | YAGNI with discipline | Satisfied -- all 3 modules have zero callers post-removal |
+| Slice 4 | Determinism over cleverness | Satisfied -- startup becomes single unconditional call |
+| Slice 4 | Make illegal states unrepresentable | Satisfied -- waitForStdinReadable deleted |
+| Slice 4 | Document why, not what | Satisfied -- JSDoc updated to reflect simplified behavior |
+| Slice 5-6 | Type safety as first line | Satisfied -- compiler verifies no remaining references |
+| Slice 6 | Keep interfaces small | Satisfied -- http-entry.ts shrinks, transport logic unchanged |
+
+---
+
+## Follow-Up Tickets
+
+- `worktrain-spawn.ts` and `worktrain-await.ts` `dashboard.lock` fallback is now permanently dead code. Remove in a separate chore PR.
+- PR-B: Remove HttpServer from MCP server startup entirely.
+
+---
+
+## Unresolved Unknown Count
+
+**0.** All import surfaces verified, failure modes addressed, acceptance criteria measurable.
+
+## Plan Confidence Band
+
+**High.**

package/docs/discovery/design-candidates.md

@@ -0,0 +1,180 @@
+# Design Candidates: wr.discovery Goal Reframing
+
+**Status:** Candidate generation complete -- for main agent review  
+**Date:** 2026-04-18  
+**Session:** wr.discovery (improving goal reframing)
+
+---
+
+## Problem Understanding
+
+### Core tensions
+
+**T1: Early interrogation vs late-discovered context**  
+Goal interrogation in Phase 0 happens before any landscape work. Some hidden assumptions only become visible after reading the codebase. An early interrogation catches structural goal-type issues (solution-framed vs problem-framed) but misses context-dependent assumptions. Phase 1g retriage catches these later -- but only if the agent explicitly sets `retriageNeeded = true`.
+
+**T2: Non-interactive constraint vs interrogation quality**  
+The best reframing comes from dialogue. Daemon sessions have no human. Non-interactive interrogation means the agent interrogates itself, which risks circular reasoning (surfacing expected assumptions rather than genuinely hidden ones).
+
+**T3: Overhead for well-framed goals**  
+Any mandatory goal-challenge step adds overhead to every session, including correctly-framed ones. The mechanism must be lightweight for good goals, substantial for misframed ones.
+
+**T4: Workflow enforcement vs agent judgment**  
+The workflow can instruct the agent to classify a goal, but the classification itself is still LLM output. A `runCondition` on `goalType = solution_framed` is structural, but the `goalType` value is agent judgment. There is no escape from this.
+
+### Likely seam
+
+Phase 0's `procedure` block -- specifically the `Capture` step that lists context variables and the path selection logic. This is where goal misframing has the highest downstream impact (wrong `pathRecommendation` propagates through all subsequent steps).
+
+### What makes this hard
+
+1. The agent interrogates itself -- self-adversarial reasoning is weaker than adversarial reasoning against a well-defined artifact
+2. Solution-framed goals can look like problem-framed goals ('improve discovery' looks like a problem frame but contains hidden assumptions)
+3. Adding required output fields to Phase 0 means sessions starting mid-workflow (without Phase 0 context) need graceful fallback
+
+---
+
+## Philosophy Constraints
+
+| Principle | Constraint |
+|---|---|
+| Validate at boundaries, trust inside | Phase 0 is the input boundary; it must validate goal framing |
+| Make illegal states unrepresentable | Solution-framed goal processed without interrogation should not be a valid state |
+| YAGNI with discipline | The mechanism must add near-zero cost for well-framed goals |
+| Architectural fixes over patches | The fix should change structural invariants, not add 'be careful' reminders |
+| Determinism over cleverness | Same goalType -> same downstream path bias |
+
+**Philosophy conflict:** 'Make illegal states unrepresentable' conflicts with 'YAGNI with discipline' when it comes to adding a mandatory interrogation step. A mandatory step is more enforceable but adds overhead for every session.
+
+---
+
+## Impact Surface
+
+| Surface | Must stay consistent |
+|---|---|
+| `pathRecommendation` context variable | Set by Phase 0; used by all phase-1 `runCondition` gates |
+| `problemStatement` context variable | Should reflect the actual problem, not the stated solution |
+| `designDocPath` content | Problem framing section becomes misleading if it reflects a solution-framed goal verbatim |
+| Phase 1g `retriageNeeded` trigger | If retriage condition changes, existing sessions may behave differently |
+| Daemon sessions | Cannot be blocked on interactive responses |
+
+---
+
+## Candidates
+
+### Candidate 1: Minimal -- Extend Phase 0 `Capture` with `goalType` and `impliedProblem`
+
+**Summary:** Add `goalType` (4-value closed enum: `solution_framed | problem_framed | opportunity_framed | decision_framed`) and `impliedProblem` to the Phase 0 `Capture` step. Add a procedure instruction: classify first, derive `impliedProblem` when `solution_framed`, then select path with `goalType` awareness.
+
+**Tensions resolved:** T3 (near-zero overhead for well-framed goals -- classification is lightweight), T4 partially (structural variable exists)  
+**Tensions accepted:** T1 (pre-context), T2 (self-interrogation), T4 fully (goalType is still agent judgment)
+
+**Boundary:** Phase 0 `Capture` list and `procedure` text
+
+**Why best fit:** Phase 0 already captures 12+ context variables. Adding `goalType` and `impliedProblem` follows the established pattern. No new step IDs, no new `runCondition` chains, fully backward compatible.
+
+**Failure mode:** Agent classifies a solution-framed goal as `opportunity_framed`, skipping `impliedProblem` derivation. No structural enforcement prevents this.
+
+**Repo pattern:** Follows the existing 'Phase 0 captures context variables for downstream use' pattern.
+
+**Gains:** Zero new steps. Backward compatible. `goalType` available for all downstream phases.  
+**Gives up:** No enforcement that classification happens before path selection. Still relies on procedure text instructions, not structural ordering.
+
+**Scope judgment: best-fit as a minimal change.** Not too narrow (introduces the structural signal). Not too broad (no new steps).
+
+**Philosophy:** Honors 'YAGNI', 'Determinism'. Conflicts with 'Make illegal states unrepresentable' (misframings are still structurally possible).
+
+---
+
+### Candidate 2: Structural -- New mandatory Phase 0a before current Phase 0
+
+**Summary:** Add a new step `phase-0a-goal-interrogation` that runs before the current Phase 0. Always runs. Required outputs: `goalType` (4-value enum), `impliedProblem` (string, required when `solution_framed`), `hiddenAssumptions` (array, min 1 when `goalType != problem_framed`), `alternativeFraming` (string, optional). Phase 0 then reads `goalType` from context rather than deriving it.
+
+**Tensions resolved:** T3 partially (well-framed goals produce trivial Phase 0a output fast), T4 (structural enforcement -- path selection cannot happen without Phase 0a having run)  
+**Tensions accepted:** T1 (still pre-landscape), T2 (self-interrogation)
+
+**Boundary:** A new step with ID `phase-0a-goal-interrogation`, inserted as the first step of the workflow. Phase 0 becomes a consumer of `goalType` rather than its producer.
+
+**Why best fit:** True structural enforcement. Phase 0a is a required step. The interrogation runs before path selection by design, not by instruction. Mirrors the existing `phase-0b-capability-setup` pattern (a pre-phase setup step before the main classification phase).
+
+**Failure mode:** For well-framed goals, Phase 0a adds overhead. More importantly: Phase 0a and Phase 0 can produce contradictory conclusions if the agent reconsiders its interpretation between steps.
+
+**Repo pattern:** Adapts the `phase-0b-capability-setup` pattern. Departs in that Phase 0a runs before Phase 0 (changes existing step order).
+
+**Gains:** True enforcement. `hiddenAssumptions` and `alternativeFraming` become required outputs with engine validation. Sets a seam for a future reusable `routine-goal-interrogation`.  
+**Gives up:** Adds a step to every session (overhead for well-framed goals). Changes step order (Phase 0 is no longer the first step).
+
+**Scope judgment: best-fit for structural correctness, slightly overbroad for immediate need.** The structural separation is the correct long-term architecture.
+
+**Philosophy:** Honors 'Architectural fixes over patches', 'Make illegal states unrepresentable', 'Validate at boundaries'. Conflicts with 'YAGNI with discipline'.
+
+---
+
+### Candidate 3: Distributed -- Three targeted strengthening changes to existing steps
+
+**Summary:** No new steps. Three changes: (1) add `goalType` classification + `impliedProblem` to Phase 0 procedure (same as C1). (2) Make `problemFrameTemplate`'s 'What would make this framing wrong' field a required non-empty output contract in Phase 1e/1f steps. (3) Change Phase 1g `runCondition` from `retriageNeeded = true` to `pathRecommendation == design_first || pathRecommendation == full_spectrum` (retriage always runs for these paths).
+
+**Tensions resolved:** T1 (distributed checkpoints catch both pre-context issues at Phase 0 and post-landscape issues at Phase 1g), T3 (no new steps)  
+**Tensions accepted:** T2 (self-interrogation at all checkpoints), T4 partially
+
+**Boundary:** Three existing steps: Phase 0 (procedure text), Phase 1e/1f (output contract), Phase 1g (runCondition).
+
+**Why best fit:** Fixes the three specific weak points in the existing design without adding new steps. Distributed checkpoints catch more than a single-point interrogation.
+
+**Failure mode:** An agent anchored to the original framing can produce weak 'what would make this wrong' answers -- required non-empty output enforces form but not quality. Phase 1g always-on for `design_first` runs a (potentially unnecessary) retriage step for sessions where the path was correct from the start.
+
+**Repo pattern:** Adapts existing `outputRequired` contract pattern. Adapts `runCondition` pattern. Follows (not departs from) established mechanisms.
+
+**Gains:** No new steps. Reinforces three existing weak mechanisms. Catches both early and late misframings.  
+**Gives up:** No single strong enforcement point. Effect is diffuse. Does not fix path-selection bias (wrong path can still be chosen in Phase 0 before Phase 1g runs).
+
+**Scope judgment: too narrow as standalone, best-fit as complement to C1 or C2.**
+
+**Philosophy:** Honors 'YAGNI with discipline', 'Architectural fixes over patches'. Conflicts with 'Make illegal states unrepresentable' (path selection still uses raw stated goal).
+
+---
+
+## Comparison and Recommendation
+
+### Tension resolution matrix
+
+| Tension | C1 (Phase 0 extension) | C2 (new Phase 0a) | C3 (distributed) |
+|---|---|---|---|
+| T1: pre-context interrogation | Accepts | Accepts | Resolves (Phase 1g post-landscape) |
+| T2: self-interrogation quality | Accepts (same for all) | Accepts | Accepts |
+| T3: overhead for well-framed goals | **Resolves** (lightweight) | Accepts (adds step) | **Resolves** (absorbed) |
+| T4: structural enforcement | Partial | **Resolves** (mandatory step) | Partial |
+
+### Recommendation: C1 + C3 hybrid, with C2 as future evolution
+
+**Primary (immediate):** C1 extended with procedural strength: add `goalType`, `impliedProblem`, `hiddenAssumptions` to Phase 0 Capture as required context variables. Add explicit procedure: classify goal type first, derive implied problem before path selection, let goalType influence path bias toward `design_first` for `solution_framed` goals.
+
+**Secondary (no new steps):** Three C3 changes: (a) `goalType` in Phase 0 (same as C1), (b) make 'What would make this framing wrong' a required non-empty output in Phase 1e/1f, (c) change Phase 1g `runCondition` to always run for `design_first` and `full_spectrum` paths.
+
+**Future evolution:** If the C1+C3 hybrid proves insufficient for daemon sessions, extract Phase 0a as a mandatory pre-step (C2).
+
+---
+
+## Self-Critique
+
+**Strongest argument against this recommendation:** C1's enforcement is procedural (instructions), not structural (step ordering). A capable LLM running in QUICK mode or under context pressure can skip the classification step and proceed to path selection. C2's mandatory separate step is the only way to structurally guarantee the interrogation happened.
+
+**Counter:** Both approaches ultimately rely on the LLM following instructions. The difference is in how much structural scaffolding supports following those instructions. C2 enforces 'the step ran' not 'the step ran well.'
+
+**Narrower option:** Just add `goalType` to the Capture list with no procedure change. Too narrow -- introduces the variable without the interrogation mechanism.
+
+**Broader option:** Extract a reusable `routine-goal-interrogation` callable from any workflow. Justified if pattern proves valuable in other workflows. Not warranted now.
+
+**Assumption that would invalidate this:** Claude Sonnet already implicitly reframes solution-framed goals. Counter-evidence: two real examples (MCP simplification, structured output session) show this is not reliably true.
+
+---
+
+## Open Questions for the Main Agent
+
+1. **Should `goalType` influence path selection automatically** (e.g., `solution_framed` -> force `design_first`) or **only as a soft bias**? Automatic enforcement is stronger but may override user intent for cases where the solution IS the right framing.
+
+2. **How should `impliedProblem` flow to the design doc?** Should Phase 0 write it as the `problemStatement` in the design doc (replacing the stated goal), or record it as a separate field ('stated goal' vs 'implied problem')?
+
+3. **Phase 1g runCondition change:** Making Phase 1g always run for `design_first` and `full_spectrum` is a behavior change for existing sessions. Is this backward compatible enough?
+
+4. **`hiddenAssumptions` format:** Should this be a free-text field or a structured array? Free-text is easier to author; structured allows downstream steps to reference specific assumptions.

package/docs/discovery/design-review-findings.md

@@ -0,0 +1,110 @@
+# Design Review Findings: wr.discovery Goal Reframing
+
+*Concise, actionable findings for main-agent synthesis. Not a final decision.*
+**Date:** 2026-04-18
+
+---
+
+## Tradeoff Review
+
+**Tradeoff 1: goalType classification remains agent judgment**
+
+- Acceptable: this pattern is established in the workflow (rigorMode, pathRecommendation are all agent-derived)
+- Classification examples in the procedure reduce misclassification probability
+- **Finding: YELLOW.** Add goalType classification examples to procedure text to reduce ambiguity at the problem_framed / opportunity_framed boundary.
+
+**Tradeoff 2: overhead for well-framed goals is nonzero**
+
+- A few additional context variable captures and procedure lines in Phase 0
+- Well-framed goals produce minimal output ('goalType = problem_framed, no impliedProblem needed')
+- **Finding: NON-ISSUE.** Overhead is trivial.
+
+**Tradeoff 3: Phase 1g always-on for design_first/full_spectrum**
+
+- One additional advance per session for these paths
+- Produces trivially short output for well-framed sessions ('pathChangedAfterContext = false')
+- **CRITICAL CORRECTION NEEDED:** Phase 1g runCondition must be an OR (`retriageNeeded = true OR pathRecommendation in [design_first, full_spectrum]`) not a replacement. Otherwise landscape_first sessions that explicitly need retriage will not trigger it.
+- **Finding: YELLOW.** Runnable as-designed if the OR condition is used correctly.
+
+---
+
+## Failure Mode Review
+
+**Failure mode 1: Agent misclassifies solution-framed goal as opportunity_framed**
+- Status: **Partially mitigated.** C3's Phase 1e/1f required 'what would make this framing wrong' output provides a downstream catch. Classification examples in Phase 0 reduce probability.
+- Missing mitigation: examples in procedure (address in revisions)
+- **Finding: MEDIUM risk, mitigated.**
+
+**Failure mode 2: 'What would make this framing wrong' output is formulaic**
+- Status: **Partially mitigated.** Making it required non-empty enforces form but not quality.
+- Missing mitigation: specificity instruction ('name ONE concrete condition, not a general caveat')
+- **Finding: LOW-MEDIUM risk.**
+
+**Failure mode 3: Phase 1g doesn't surface new insights for well-framed sessions**
+- Status: **Non-issue by design.** For well-framed sessions, Phase 1g is a graceful no-op that confirms the path is still correct. One advance wasted, nothing more.
+- **Finding: LOW risk, acceptable.**
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**C2 (mandatory Phase 0a):** The structural enforcement advantage is real but comes at the cost of a mandatory overhead step for all sessions. The C1+C3 hybrid achieves most of C2's value via procedure-level enforcement plus structural runCondition changes. C2 is the right escalation if the hybrid proves insufficient.
+
+**Simpler variant:** Just one sentence added to Phase 0: 'If the goal is solution-framed, derive the underlying problem.' Too narrow -- no context variables means no downstream reference to the reframing.
+
+**`alternativeFraming` addition from C2:** Borrowing C2's `alternativeFraming` requirement (one reframe even when the original goal seems correct) is high-value, low-cost. Add to Phase 0 design doc entry, not as a context variable.
+
+**Finding: C1+C3 hybrid with two refinements (examples, alternativeFraming) stands. No direction change needed.**
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Validate at boundaries, trust inside | SATISFIED -- Phase 0 becomes an active validator |
+| Make illegal states unrepresentable | PARTIALLY SATISFIED -- C3 structural changes help; C2 would fully satisfy |
+| YAGNI with discipline | SATISFIED -- no new steps, minimal additions |
+| Architectural fixes over patches | SATISFIED -- runCondition changes and required output contracts are structural |
+| Determinism over cleverness | SATISFIED -- same goalType input produces same path behavior |
+
+**One explicit philosophy tension:** 'Make illegal states unrepresentable' vs 'YAGNI with discipline' -- deliberately accepted, C2 is escalation path.
+
+---
+
+## Findings
+
+### Yellow findings
+
+**Y1: goalType classification boundary ambiguity**
+The boundary between `problem_framed` and `opportunity_framed` is unclear without examples. Add classification examples to Phase 0 procedure to reduce misclassification at this boundary.
+
+**Y2: Phase 1g runCondition must be OR, not replacement**
+The retriage step runCondition must be: `retriageNeeded = true OR pathRecommendation == design_first OR pathRecommendation == full_spectrum`. A straight replacement would break landscape_first sessions that legitimately need retriage.
+
+**Y3: 'What would make this framing wrong' needs specificity instruction**
+The required output field should specify 'name ONE concrete falsification condition, not a general caveat.' Without this, the field can be satisfied by formulaic responses.
+
+### No Red or Orange findings
+
+The selected C1+C3 direction has no material structural weaknesses.
+
+---
+
+## Recommended Revisions
+
+1. **Add goalType classification examples** to Phase 0 procedure (solution_framed: 'add X', 'implement Y', 'build X'; problem_framed: 'reduce X', 'fix Y'; opportunity_framed: 'explore X', 'decide whether Y'; decision_framed: 'choose between A and B')
+
+2. **Add `alternativeFraming`** as a required design doc entry in Phase 0: 'Before selecting a path, generate one alternative framing -- if the stated goal is wrong, what would a better goal be?'
+
+3. **Use OR condition for Phase 1g runCondition:** `retriageNeeded = true OR pathRecommendation in [design_first, full_spectrum]`
+
+4. **Add specificity instruction** to Phase 1e/1f 'what would make this framing wrong' field: require naming one concrete falsification condition.
+
+---
+
+## Residual Concerns
+
+1. The goalType classification is LLM-dependent. Without empirical testing on real sessions, we cannot confirm the classification is reliable. This is an inherent limitation of the approach.
+
+2. The C1+C3 hybrid does not prevent path-selection bias for the window between Phase 0 path selection and Phase 1g retriage. A session that selects the wrong path in Phase 0 runs several steps in the wrong direction before Phase 1g can correct it. Acceptable for STANDARD rigor; C2 is the correct escalation if this proves problematic.