@exaudeus/workrail 3.67.0 → 3.68.0

package/docs/design/trigger-validator-candidates.md

@@ -0,0 +1,214 @@
+# Design Candidates: triggers.yml Validator
+
+*Raw investigative material for main agent synthesis. See trigger-validator.md for the full design doc.*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+**Tension A: Fail-fast vs. partial degradation**
+trigger-listener.ts currently uses skip-and-continue for invalid triggers (not daemon-fatal). Adding hard errors to validateAndResolveTrigger() causes affected triggers to be skipped at startup, not the daemon. This is the correct behavior for a multi-trigger deployment, but means the operator needs to notice the warning in startup logs.
+
+**Tension B: Explicit config vs. sensible defaults**
+Forcing maxSessionMinutes on every trigger adds config noise. The true danger fields are branchStrategy and concurrencyMode. The design must not over-constrain safe defaults.
+
+**Tension C: Startup validation vs. validate subcommand**
+Hard errors at startup (trigger skipped, logged) are the safety net. The validate subcommand is the observability tool. Both are needed for different jobs. An operator who never runs validate relies entirely on startup logs for safety warnings.
+
+**Tension D: Semantic vs. structural validation**
+Structural validation (is maxSessionMinutes a positive integer?) is already in validateAndResolveTrigger(). Semantic validation (should autoCommit:true require an explicit branchStrategy?) is a different concern. Conflating them makes the function harder to test and extend. Separating them clarifies responsibilities.
+
+### Likely Seam
+
+The correct boundaries are:
+1. `validateAndResolveTrigger()` in trigger-store.ts -- for safety violations (parse-time hard errors)
+2. New `validateTriggerStrict()` function (pure, post-parse) -- for observability warnings
+
+NOT trigger-listener.ts (out of scope). Hard error upgrades in validateAndResolveTrigger propagate automatically through trigger-listener.ts's existing loadTriggerConfigFromFile() call.
+
+### What Makes This Hard
+
+The severity decision for `autoCommit: true` + `branchStrategy: none` under **serial** concurrency. Under serial mode, only one session runs at a time -- no corruption risk today. But changing to parallel later (one field change) makes it dangerous immediately. The design must decide: warn now (footgun-prevention) or only error on the dangerous active combination (parallel + none + autoCommit).
+
+**Resolution chosen:** Hard error on autoCommit:true + branchStrategy absent-or-none regardless of concurrencyMode. The error message explains the latent danger.
+
+---
+
+## Philosophy Constraints
+
+### Principles That Matter Here
+
+- **Errors are data** -- new validation issues must be TriggerValidationIssue values, not exceptions. Already the pattern in trigger-store.ts (70+ Result<>/ok()/err() uses).
+- **Make illegal states unrepresentable** -- the correct fix is a type-level discriminated union. The runtime validator is a pragmatic patch. Note as follow-up.
+- **Explicit domain types** -- TriggerValidationIssue needs a `rule: string` discriminant (not just a message). Rules should be a finite named set to enable programmatic handling.
+- **Pure functions, DI** -- validateTriggerStrict must be a pure function taking TriggerDefinition; CLI command must inject I/O via a deps interface.
+- **Validate at boundaries** -- trigger-store.ts IS the boundary. No new boundary needed.
+
+### Philosophy Conflict
+
+**Stated:** make illegal states unrepresentable.
+**Practiced:** branchStrategy is `?: 'worktree' | 'none'` (optional) on TriggerDefinition, making the dangerous combination representable.
+
+The validator design is a runtime patch over this type-level gap. A follow-up task should explore replacing the optional field with a discriminated AutoCommitConfig union type.
+
+---
+
+## Impact Surface
+
+- **trigger-store.ts** -- new hard error checks in validateAndResolveTrigger(); new exported types TriggerValidationIssue, functions validateTriggerStrict() and validateAllTriggers()
+- **types.ts** -- new TriggerValidationIssue interface
+- **cli-worktrain.ts** -- new `worktrain trigger validate` subcommand under existing triggerCommand group
+- **trigger-listener.ts** (NOT TOUCHING) -- startup behavior changes automatically because it calls loadTriggerConfigFromFile()
+- **Test files** -- existing tests that construct TriggerDefinition with missing fields will now get those triggers skipped (behavior change consistent with new hard errors)
+
+---
+
+## Candidates
+
+### Candidate A: Minimal Safety Patch
+
+**Summary:** Add 3 hard error returns inside validateAndResolveTrigger() for safety violations; no new functions, no CLI change.
+
+**Tensions resolved:** A (hard errors at startup via skip), D (validation stays in existing boundary)
+**Tensions accepted:** B (no observability warnings), C (no validate subcommand)
+
+**Boundary:** validateAndResolveTrigger() -- correct seam, already handles structural validation.
+
+**Why this boundary:** It is the existing validation seam, called automatically at startup and via CLI. Adding checks here requires no new call sites.
+
+**Failure mode:** Triggers are silently skipped at startup. Operators who don't read logs won't know. No UX improvement over current behavior.
+
+**Repo-pattern relationship:** Exact follow -- same err() return pattern, same TriggerStoreError kinds.
+
+**Gains:** Zero new surface area, minimum risk, fixes safety violations.
+**Losses:** No validate CLI, no observability warnings, no per-trigger summary.
+
+**Scope judgment:** Too narrow for the full ask. Satisfies safety goal only.
+
+**Philosophy:** Honors errors-as-data, validate-at-boundaries. Does not progress on make-illegal-states-unrepresentable.
+
+---
+
+### Candidate B: Two-Layer Validation + CLI Subcommand (RECOMMENDED)
+
+**Summary:** (1) Add 3 hard error returns in validateAndResolveTrigger() for safety violations. (2) Add new pure exported function validateTriggerStrict(trigger: TriggerDefinition): readonly TriggerValidationIssue[] for observability warnings. (3) Add worktrain trigger validate subcommand that calls loadTriggerConfigFromFile() then validateAllTriggers() and prints per-trigger summary.
+
+**Tensions resolved:** All four -- safety violations become hard errors (A), observability gaps produce named warnings (B), static validate CLI exits 0/1 (C), semantic validation cleanly separated from structural parsing (D).
+
+**Boundary solved at:**
+1. validateAndResolveTrigger() -- structural + safety (parse-time errors, existing boundary)
+2. validateTriggerStrict() -- semantic (post-parse, new pure function)
+Both boundaries are correct for their respective concerns.
+
+**Why this boundary:** TriggerDefinition is fully resolved at validateTriggerStrict time (secrets expanded, defaults applied, branding done). Cross-field semantics like 'autoCommit:true + branchStrategy absent' can be checked cleanly on a fully-assembled value. The parse-time boundary is wrong for this -- at parse time, branchStrategy might still be absent for a legitimate reason (worktree isolation is optional for read-only triggers).
+
+**Failure mode:** Two validation layers = two places to add new rules. An operator who only runs the daemon (never validate CLI) won't see semantic warnings. Mitigation: loadTriggerConfig() can log 'run worktrain trigger validate for a full config health check' on successful parse.
+
+**Repo-pattern relationship:** Adapts -- extends existing function plus new exported function following same pure-function and DI patterns. New CLI subcommand follows WorktrainTriggerTestDeps injection pattern exactly.
+
+**New types (concrete specification):**
+```typescript
+// In types.ts
+export interface TriggerValidationIssue {
+  readonly severity: 'error' | 'warning';
+  readonly rule:
+    | 'auto_commit_requires_branch_isolation'
+    | 'auto_open_pr_requires_auto_commit'
+    | 'worktree_requires_base_branch'
+    | 'worktree_requires_branch_prefix'
+    | 'max_session_minutes_not_set'
+    | 'concurrent_without_worktree'
+    | 'goal_template_implicit'
+    | 'max_turns_not_set'
+    | 'auto_commit_without_secret_scan';
+  readonly triggerId: string;
+  readonly message: string;
+  readonly suggestedFix?: string;
+}
+```
+
+Note: `rule` is a closed string-literal union (not bare string) for exhaustiveness and programmatic handling.
+
+**New exports from trigger-store.ts:**
+```typescript
+export function validateTriggerStrict(trigger: TriggerDefinition): readonly TriggerValidationIssue[];
+export function validateAllTriggers(config: TriggerConfig): readonly TriggerValidationIssue[];
+```
+
+**New CLI file:** `src/cli/commands/worktrain-trigger-validate.ts` following WorktrainTriggerTestDeps injection pattern.
+
+**Gains:** Full solution -- safety + observability + CLI. Clean separation. Easy to test validateTriggerStrict in isolation. TriggerValidationIssue is an explicit domain type (not bare string). Closed rule enum enables exhaustiveness.
+**Losses:** More surface area than A. Two places to add new validation rules. Startup path only runs first layer.
+
+**Scope judgment:** Best-fit. Covers all five decision criteria within the stated scope.
+
+**Philosophy:** Honors all -- errors-as-data, immutability, explicit domain types, pure functions, DI. The closed rule union advances exhaustiveness. Does not yet fix the make-illegal-states-unrepresentable gap (follow-up).
+
+---
+
+### Candidate C: Type-Level Discriminated Union
+
+**Summary:** Replace `branchStrategy?: 'worktree' | 'none'` in TriggerDefinition with a discriminated union `type CommitConfig = { readonly autoCommit: false } | { readonly autoCommit: true; readonly branchStrategy: 'worktree'; readonly baseBranch: string; readonly branchPrefix: string }` so the dangerous combination is unrepresentable at compile time.
+
+**Tensions resolved:** Tension B (type-level guarantee, permanent prevention rather than runtime detection). Fully resolves make-illegal-states-unrepresentable.
+
+**Tensions accepted:** Tension A, C, D. Does not provide CLI. Large refactor.
+
+**Boundary:** types.ts (TriggerDefinition), trigger-store.ts (assembly code). Would cascade to all TriggerDefinition construction sites including trigger-listener.ts tests (out of scope).
+
+**Why this boundary is wrong for now:** trigger-listener.ts and test files are out of scope. The type change cascades beyond the allowed boundary.
+
+**Failure mode:** All test fixtures that construct TriggerDefinition objects must be updated. High risk for the stated scope.
+
+**Repo-pattern relationship:** Departs from existing flat-interface pattern. Follows philosophy strictly.
+
+**Gains:** Compiler catches dangerous combinations at build time. Zero runtime overhead.
+**Losses:** Large refactor, many files beyond scope. Does not address CLI observability.
+
+**Scope judgment:** Too broad.
+
+**Philosophy:** Best honors make-illegal-states-unrepresentable. Conflicts with YAGNI -- more complexity than needed for the immediate problem.
+
+---
+
+## Comparison and Recommendation
+
+| Criterion | A | B | C |
+|---|---|---|---|
+| Safety violations become hard errors | Yes | Yes | Yes (compile-time) |
+| Observability warnings | No | Yes | No |
+| Static validate CLI | No | Yes | No |
+| No API break | Yes | Yes | No (type break) |
+| Fits scope | Yes | Yes | No |
+| Easiest to evolve | Yes (tiny) | Yes (clean seams) | Risky |
+| Philosophy alignment | Good | Best | Highest (but scope-breaking) |
+
+**Recommendation: Candidate B.** It satisfies all five decision criteria, fits the scope, and follows established patterns. Candidate A is the right Phase 1 of B. Candidate C is the right long-term follow-up.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument against B:** Semantic warnings are only visible via `worktrain trigger validate`. An operator who never runs the CLI misses them entirely. The startup path only runs the structural validator. This means the observability improvement requires operator behavior change (run validate before deploying).
+
+**Why it still wins:** The alternative (putting semantic warnings in startup logs) is already partially implemented (see the existing console.warn for autoOpenPR without autoCommit). The problem is not that warnings are absent -- it is that they are scattered across trigger-store.ts console.warn calls with no structured output. Candidate B consolidates them into a proper reporting layer.
+
+**Narrower option considered:** Candidate A. It loses because it provides no observability improvement, which is half the stated goal.
+
+**Broader option considered:** Candidate C. It would be justified if the scope constraint is relaxed or if a follow-up task is planned immediately after this design.
+
+**Assumption that would invalidate this design:** If adding new hard errors to validateAndResolveTrigger() causes unexpected startup failures in production (e.g., a trigger that was loading with a bad default is now skipped entirely, breaking the deployment). Mitigation: the production triggers.yml was audited and passes all proposed checks. The hard errors only affect configs that would have caused production incidents anyway.
+
+---
+
+## Open Questions for Main Agent
+
+1. **autoCommit:true + branchStrategy:none + serial concurrency** -- should this be a hard error (latent danger) or a warning (safe today)? Design doc recommends hard error. Do you agree?
+
+2. **Migration path for self-improvement trigger** -- it has no explicit concurrencyMode (defaults to serial) and no explicit goalTemplate (defaults to {{$.goal}}). These are warnings under the proposed design. Is that the right call, or should we add these fields to the production triggers.yml as part of this work?
+
+3. **worktrain init template** -- should fixing the triggers.yml template scaffolding be part of this implementation? (The framing risk: if init generates missing fields, the validator catches hand-edits but not init-generated configs.) The init command is in `src/cli/commands/worktrain-init.ts` -- also in scope since cli-worktrain.ts is allowed.
+
+4. **TriggerValidationIssue.rule as closed union vs. bare string** -- the closed union enables exhaustiveness in switch statements but makes the rule set less extensible. Should it be `string` with a named constants object instead?

package/docs/design/trigger-validator-review.md

@@ -0,0 +1,109 @@
+# Design Review Findings: triggers.yml Validator (Candidate B)
+
+*Concise actionable findings for main agent synthesis.*
+
+---
+
+## Tradeoff Review
+
+### T1: Semantic warnings only visible via validate CLI (not daemon startup)
+**Severity: Yellow**
+Acceptable under realistic conditions. Observability gaps (missing maxSessionMinutes, implicit goalTemplate) are non-blocking. Hard errors still protect against safety violations at startup. The design does not make the current situation worse.
+
+**Hidden assumption:** Operators know to run `worktrain trigger validate` before deploying new triggers.
+**Mitigation required:** Add a console.log hint in loadTriggerConfig() on successful parse: "Loaded N trigger(s). Run `worktrain trigger validate` for a full config health check."
+
+### T2: Two validation layers = two places to add rules
+**Severity: Orange**
+Manageable with documentation and tests, but creates a meaningful maintenance risk. The specific dangerous scenario: a rule is added to validateAndResolveTrigger (causes trigger skip at startup) but not to validateTriggerStrict (so validate CLI reports Status: OK for a trigger that will be skipped). This actively misleads operators.
+
+**Mitigation required:** (1) Add a contract comment in validateTriggerStrict documenting that all error-severity rules in validateAndResolveTrigger must have a counterpart in validateTriggerStrict. (2) Unit test that verifies TriggerDefinitions which fail structural validation also produce error-severity issues from validateTriggerStrict.
+
+### T3: autoOpenPR+no autoCommit upgraded from warning to hard error
+**Severity: Yellow**
+Breaking behavioral change. Safe for the production config (no such combination exists). Must be documented as a breaking change in the implementation PR. Clear error message required.
+
+---
+
+## Failure Mode Review
+
+### FM1: Operator never runs validate, misses observability warnings
+**Severity: Yellow**
+The startup hint (T1 mitigation) reduces this risk substantially. Worst case is the current situation (confusing startup messages about missing fields), not a regression.
+
+### FM2: validate CLI says OK but daemon skips trigger (sync failure)
+**Severity: Orange -- MOST DANGEROUS**
+If a safety rule is in validateAndResolveTrigger but not in validateTriggerStrict, the validate CLI is actively misleading. This is the highest-risk failure mode.
+
+**Required mitigation:** Implement validateTriggerStrict to reproduce all error-severity rules from validateAndResolveTrigger as TriggerValidationIssue with severity:'error'. The validate CLI must be a strict superset of what the daemon checks. Document this invariant in code comments.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate A (minimal patch):** No simplification opportunity. Candidate A is Phase 1 of Candidate B. No elements to borrow -- B already includes A's changes.
+
+**Simpler variant (single-layer: validateTriggerStrict only):** Analyzed. Does not work. Hard errors in validateAndResolveTrigger prevent dangerous triggers from being dispatched. Moving them to validateTriggerStrict would let dangerous triggers load and dispatch (the validate CLI would show errors, but the daemon would still run the trigger). The two-layer architecture is required.
+
+**Verdict:** No simplification satisfies all acceptance criteria. Candidate B as specified is the minimal correct design.
+
+---
+
+## Philosophy Alignment
+
+### Fully Satisfied
+- Errors are data (TriggerValidationIssue is a value, not an exception)
+- Explicit domain types (closed rule union, named interface)
+- Exhaustiveness (closed rule union enables switch exhaustiveness)
+- Immutability (all readonly fields and return types)
+- Pure functions (validateTriggerStrict has no I/O)
+- Dependency injection (CLI uses WorktrainTriggerValidateDeps interface)
+- Validate at boundaries (trigger-store.ts is the boundary)
+
+### Under Tension (Acceptable)
+- **Make illegal states unrepresentable:** branchStrategy still optional on TriggerDefinition. Runtime patch accepted for scope constraint. Follow-up: Candidate C (discriminated union).
+- **Architectural fixes over patches:** The validator is a runtime patch. Documented as follow-up.
+- **YAGNI with discipline:** Slight over-engineering vs. Candidate A, but all new surface is directly required by the stated goal.
+
+---
+
+## Findings
+
+### Red (blocking)
+None.
+
+### Orange (important, requires mitigation before implementation)
+
+**O1: Sync invariant must be documented in code** -- validateTriggerStrict must reproduce all error-severity rules from validateAndResolveTrigger as TriggerValidationIssue errors. Without this contract, the two-layer architecture creates a misleading validate CLI.
+
+**O2: Unit test required for sync coverage** -- A test that constructs a TriggerDefinition that would cause a startup-skip (e.g., autoCommit:true + branchStrategy:none) and verifies validateTriggerStrict reports it as severity:'error'. This prevents regression.
+
+### Yellow (recommended, not blocking)
+
+**Y1: Startup hint required** -- loadTriggerConfig() should log "Run `worktrain trigger validate` for a full config health check" on successful parse. Without this, observability warnings are effectively invisible.
+
+**Y2: Breaking change documentation** -- The autoOpenPR+no autoCommit upgrade from warning to hard error must be documented in the implementation PR and in the changelog as a breaking change.
+
+**Y3: Closed rule union vs. constants** -- Open question: should TriggerValidationIssue.rule be a closed string-literal union or a `string` with a named constants object? The closed union is better for exhaustiveness but less extensible. Recommendation: closed union for now (9 rules is a small set); switch to constants if the rule set grows beyond ~15.
+
+---
+
+## Recommended Revisions to Design Doc
+
+1. Add to Phase 2 implementation notes: "validateTriggerStrict must reproduce all error-severity checks from validateAndResolveTrigger as TriggerValidationIssue with severity:'error'. Document this as a maintained invariant in code comments."
+
+2. Add to Phase 1 implementation notes: "loadTriggerConfig() should log a hint to run `worktrain trigger validate` on successful parse of any triggers."
+
+3. Add to Phase 3 implementation notes: "Add unit tests verifying that TriggerDefinitions which would be skipped by validateAndResolveTrigger also produce error-severity issues from validateTriggerStrict."
+
+4. Note Y3 (rule union vs. constants) as an open implementation decision for the coding task.
+
+---
+
+## Residual Concerns
+
+1. **worktrain init template not in scope:** The framing risk (init generates configs without required fields) is unresolved. It is recommended but not required to check worktrain-init.ts during implementation and add the missing explicit field scaffolding. This is a separate, smaller task.
+
+2. **Candidate C deferred:** The type-level discriminated union for AutoCommitConfig is the correct long-term fix. It should be tracked as a follow-up issue. The runtime validator does not prevent a developer from constructing a TriggerDefinition with the dangerous combination programmatically (only from parsing a triggers.yml with it).
+
+3. **Self-improvement trigger warnings:** The production `self-improvement` trigger will produce 2 warnings from validateTriggerStrict (goalTemplate implicit, concurrencyMode not set). These should be fixed in the triggers.yml file as part of this implementation (add explicit `goalTemplate: "{{$.title}}"` and `concurrencyMode: serial`).

package/docs/design/trigger-validator-shaping-phase0.md

@@ -0,0 +1,239 @@
+# Phase 0: Understand and Path Recommendation -- WorkTrain Trigger Validator
+
+**Generated:** 2026-04-20 | **Workflow:** wr.shaping | **Session:** sess_d47ycoddoji3ml5dl5qib2ag7u  
+**Status:** Phase 0b complete -- capabilities confirmed, artifact strategy recorded
+
+---
+
+## Artifact Strategy
+
+**This document is human-readable reference only.** It is NOT execution truth.
+
+- Execution truth lives in WorkRail session notes and context variables
+- If a chat rewind occurs, notes and context variables survive; this file may not
+- Do not treat this file as a source of truth for what was decided -- check the session context
+
+**What this doc is for:** A human reading back through the design history, or a coding agent needing to understand why certain decisions were made.
+
+**What this doc is NOT for:** Recovering session state after a rewind. That comes from session notes.
+
+---
+
+## Capability Observations (Phase 0b)
+
+| Capability | Available | Evidence | Used Here |
+|---|---|---|---|
+| Web browsing (curl/HTTP) | Yes | `curl https://example.com` returned HTTP 200 | No -- no external research needed; all context is local |
+| Structured web research (MCP browser tool) | Not observed | No browser MCP tool in session context | N/A |
+| Delegation (spawn_agent) | Yes | Tool is defined in session | No -- setup step; delegation adds overhead without benefit |
+| `worktrain` CLI (local dist) | Yes | `node dist/cli-worktrain.js --version` → `0.0.3` | N/A -- validate subcommand not yet built |
+| `worktrain trigger validate` | Not yet available | `trigger --help` shows only `test` subcommand | Will exist after Phase 4 is implemented |
+
+**Web browsing fallback:** Network is reachable, but no structured web research tool is available. All required context for this shaping task exists locally (design docs, codebase, existing pitch). Web research is not needed and was not used.
+
+**Delegation fallback:** `spawn_agent` is available but was not used in Phases 0-0b. These phases are sequential analytical work where parallelism adds no value. Delegation will be considered in later phases (e.g., parallel assumption challenges in Step 3) if independent cognitive perspectives would improve output quality.
+
+**Retriage needed:** No. Path recommendation (`design_first`) is confirmed by capability assessment -- there are no external sources that would change the design direction, and the local codebase state is the authoritative landscape.
+
+---
+
+---
+
+## Context / Ask
+
+### Stated Goal (original -- solution-framed)
+
+> Produce a pitch at .workrail/current-pitch.md for the WorkTrain trigger validator (Candidate B two-layer validation + CLI subcommand), covering all 4 implementation phases with concrete implementation details
+
+**This is a `solution_statement`, not a `problem_statement`.** It names a specific output, prescribes a design candidate, and asks for "concrete implementation details" -- language that the wr.shaping metaGuidance explicitly prohibits in a pitch.
+
+### Reframed Problem Statement
+
+When an operator adds or modifies a trigger in `triggers.yml`, they have no way to detect dangerous or confusing misconfiguration before deploying, so production incidents are their first signal that the config was wrong.
+
+---
+
+## Critical Finding: Landscape Has Changed Since the Pitch Was Written
+
+**The existing pitch (`2026-04-19-worktrain-trigger-validator.md`) is partially obsolete.** Phase 1 is already implemented.
+
+### What the pitch specified vs. current codebase state (Apr 20, 2026):
+
+| Phase 1 item | Pitch says | Codebase now |
+|---|---|---|
+| `autoOpenPR + !autoCommit` → hard error | Upgrade from warning | **DONE** (lines 941-947) |
+| `autoCommit + branchStrategy absent/none` → hard error | New hard error | **DONE** (lines 977-987) |
+| Startup hint mentioning `worktrain trigger validate` | Add to `loadTriggerConfig()` | **DONE** (3 references in trigger-store.ts) |
+
+**Phase 1 is fully implemented in the current codebase. Phases 2, 3, and 4 are not.**
+
+### What still needs to be built:
+
+| Phase | Item | Status |
+|---|---|---|
+| Phase 2 | `TriggerValidationIssue` interface in `types.ts` | **Missing** |
+| Phase 2 | `validateTriggerStrict()` export in `trigger-store.ts` | **Missing** |
+| Phase 2 | `validateAllTriggers()` export in `trigger-store.ts` | **Missing** |
+| Phase 3 | `src/cli/commands/worktrain-trigger-validate.ts` new file | **Missing** |
+| Phase 4 | `worktrain trigger validate` CLI subcommand in `cli-worktrain.ts` | **Missing** |
+
+---
+
+## Path Recommendation
+
+**Recommended path: `design_first`**
+
+### Justification
+
+**Why not `landscape_first`:** The landscape is now fully known from code inspection. trigger-store.ts is readable, the design docs are complete, and Phase 1 implementation is already in the codebase. There is no landscape knowledge gap to fill.
+
+**Why not `full_spectrum`:** The problem framing was already done rigorously in the prior `wr.discovery` session (`trigger-validator.md`). Candidate B was selected after a full three-candidate evaluation and design review. The candidates are not open questions.
+
+**Why `design_first`:** The stated goal has a specific framing distortion that needs resolution before any artifacts are produced:
+1. The goal asks for "concrete implementation details" in a pitch -- which violates wr.shaping's own metaGuidance
+2. The existing pitch already contains implementation-level detail (function signatures, TypeScript types, specific line numbers) making it closer to an engineering spec than a product pitch
+3. Phase 1 is already implemented, which changes what the pitch needs to say about the problem's solved/unsolved state
+4. Three prior coding sessions (`sess_5fk`, `sess_ntum`, `sess_v6r`) were started with implementation-level goals and appear to have stalled -- suggesting the problem may be that the "pitch" is being used as the context bundle for a coding agent, which is an architectural misuse of the shaping workflow
+
+**The core design question to resolve:** Should this workflow produce a product-level pitch (as wr.shaping intends) OR a coding-task context bundle (what the goal actually requests)? These are different artifacts with different shapes and different downstream uses. Producing the wrong one wastes work or sends a coding agent in the wrong direction.
+
+---
+
+## Constraints / Anti-Goals
+
+### Constraints (from design history + AGENTS.md)
+
+- Scope: only `src/trigger/trigger-store.ts`, `src/trigger/types.ts`, `src/cli-worktrain.ts` + new `src/cli/commands/worktrain-trigger-validate.ts`
+- No `src/mcp/` changes
+- No `src/trigger/trigger-listener.ts` changes (hard errors propagate automatically)
+- No external dependencies for the validator
+- `loadTriggerConfig()` public signature must not change
+- Result types, not exceptions -- consistent with TriggerStoreError pattern
+
+### Anti-Goals
+
+- Do not produce implementation-level detail (function signatures, line numbers, test code) in the pitch portion
+- Do not re-design what Phase 1 already implemented
+- Do not add a `--strict` flag to daemon config (introduces hidden behavior)
+- Do not build a general-purpose YAML schema validator
+- Do not auto-fix config files
+
+---
+
+## Landscape Packet
+
+### Current State: trigger-store.ts validation after PR 685 (Apr 20, 2026)
+
+| Check | Behavior | Source |
+|---|---|---|
+| `autoOpenPR: true` without `autoCommit: true` | **Hard error** | lines 941-947 |
+| `autoCommit: true` + `branchStrategy` absent or `'none'` | **Hard error** | lines 977-987 |
+| `branchStrategy` invalid value | **Hard error** | lines 969-975 |
+| Startup hint: "Run 'worktrain trigger validate'" | **Logged** | ~line 940, 979, 1333 |
+
+### What is still missing (Phases 2-4)
+
+| What | Why it matters |
+|---|---|
+| `TriggerValidationIssue` interface | Enables structured reporting; named rule IDs for programmatic use |
+| `validateTriggerStrict()` | Pure function for semantic validation; required by CLI |
+| `validateAllTriggers()` | Applies validateTriggerStrict across a full TriggerConfig |
+| `worktrain trigger validate` CLI | Pre-deploy observability; surfaces warnings before production |
+
+### Prior Coding Sessions
+
+Three coding sessions (`sess_5fk`, `sess_ntum`, `sess_v6r`) were started with detailed implementation goals. Session `sess_5fk` reached the implementation plan phase (event index 120) but shows no `run_completed` event -- suggesting it stalled or timed out. None produced a merged PR for the validator. The blocker appears to be that coding sessions were started without a clean context bundle, leading to repeated discovery work.
+
+---
+
+## Problem Frame Packet
+
+### The Real Problem Behind the Goal
+
+The goal asks for a pitch. But three prior coding sessions were started with the implementation-level goals derived from that pitch and appear to have stalled. The real problem is not "we don't have a pitch" -- it is "we don't have a clean, current, executable context bundle that a coding agent can run against without rediscovering the landscape."
+
+The pitch at `2026-04-19-worktrain-trigger-validator.md` covers all 4 phases including concrete types and function signatures -- it is already functioning as a context bundle. Its one gap: it was written before Phase 1 was implemented, so it describes Phase 1 as work to do (which would cause a coding agent to try to re-implement it and fail or conflict).
+
+### The Core Tension
+
+The wr.shaping workflow is designed to produce a **product-level pitch** (user story, appetite, breadboard, rabbit holes). The goal asks it to produce a **coding context bundle** (function signatures, test cases, file paths, phase sequencing). These are different artifacts:
+
+| Product Pitch | Coding Context Bundle |
+|---|---|
+| What the feature does for users | What files to change and how |
+| Appetite in calendar days | Phase breakdown in LOC |
+| Breadboard in words/arrows | Function signatures in TypeScript |
+| Rabbit holes at product level | Implementation risks with line numbers |
+| No-gos as user-visible exclusions | No-gos as explicit non-goals |
+
+**Resolution path:** The wr.shaping workflow should produce a product-level pitch (what it is designed for). The implementation detail from the existing pitch should be preserved in the design docs (`docs/design/trigger-validator.md`), which already contains it. The coding agent should be pointed at the design doc, not at the pitch.
+
+### Challenge Notes (from Step 1)
+
+**A1:** A pitch is the right output -- *challenged*. The existing pitch is already complete and marked ready for implementation. The work may be as small as updating `current-pitch.md` with Phase 1's done status.
+
+**A2:** Concrete implementation details belong in the pitch -- *challenged*. The wr.shaping metaGuidance explicitly prohibits this. The goal misuses the shaping workflow as an engineering spec generator.
+
+**A3:** The existing pitch is insufficient -- *challenged*. Its only gap is that it describes Phase 1 as pending when Phase 1 is already implemented. A targeted update addresses this without a full re-shape.
+
+---
+
+## Candidate Directions
+
+### Direction 1: Update the existing pitch to reflect current state (RECOMMENDED)
+
+Update `2026-04-19-worktrain-trigger-validator.md` (or produce a revised `current-pitch.md`) with:
+- Phase 1 marked as **IMPLEMENTED** (not pending)
+- The remaining work clearly labeled as Phases 2-4
+- Problem statement updated to reflect that the two most dangerous safety violations are now caught at startup
+- Appetite revised: the remaining work is smaller than the original `m` estimate (only Phases 2-4, ~200 LOC, 3 files not 4)
+
+**Pros:** Respects the existing design work. Accurate about what's done. Gives a coding agent a true picture.  
+**Cons:** This is not the "full shaping run" the goal asks for.
+
+### Direction 2: Full wr.shaping re-run with a corrected problem framing
+
+Run the full shaping workflow (Steps 1-9) but with the reframed problem statement (not the solution-framed original), producing a genuine product-level pitch that:
+- Treats Phase 1 as already solved context (background)
+- Focuses the shaped solution on Phases 2-4 (the observability layer + CLI)
+- Produces a pitch that is actually product-level (not an engineering spec)
+
+**Pros:** Produces a clean, product-level document following wr.shaping's intended output contract.  
+**Cons:** Loses the implementation detail that the existing pitch already contains and that a coding agent needs. May be solving a solved problem.
+
+### Direction 3: Produce a coding task context bundle directly (bypass wr.shaping intent)
+
+Acknowledge that the real need is a coding context bundle (not a product pitch), and produce the right artifact directly: a context bundle for `wr.coding-task` that:
+- States the current codebase state (Phase 1 done)
+- Specifies the 9 rules with exact names and severities
+- Lists the 3 remaining files and exact changes needed
+- Provides test requirements
+
+**Pros:** Most directly addresses what the three stalled coding sessions needed.  
+**Cons:** Bypasses the wr.shaping workflow's output contract. Produces something that is not a pitch.
+
+---
+
+## Resolution Notes
+
+**Chosen path: Direction 2 (full re-shape with corrected framing), with Direction 1 elements preserved.**
+
+**Rationale:**
+- The goal explicitly asks for a pitch at `current-pitch.md`. The workflow should produce what it is designed for.
+- The reframed problem is the right framing: the problem is now "operators have no pre-deploy observability tool" (Phase 1 solved the dangerous silent default; Phase 2-4 solve the observability gap).
+- The existing design docs (`trigger-validator.md`, `trigger-validator-candidates.md`, `trigger-validator-review.md`) contain the full implementation detail a coding agent needs. The pitch should reference them, not reproduce them.
+- The pitch should be accurate about what has already been shipped (Phase 1) and what remains (Phases 2-4).
+
+**Path to pitch:** The shaping should reframe from "add validator + CLI" to "add pre-deploy observability for trigger configurations." Phase 1 is already solved and becomes background. The shaped solution is the observability layer: `validateTriggerStrict`, `validateAllTriggers`, and `worktrain trigger validate`.
+
+---
+
+## Decision Log
+
+| Date | Decision | Rationale |
+|---|---|---|
+| 2026-04-20 | `goalWasSolutionStatement: true` | Goal names specific design candidate, output path, and asks for implementation detail |
+| 2026-04-20 | `pathRecommendation: design_first` | Framing distortion requires design-level correction before artifact production |
+| 2026-04-20 | Phase 1 is already implemented | Code inspection confirmed all Phase 1 items in trigger-store.ts post PR 685 |
+| 2026-04-20 | Direction 2 chosen | Produce a clean product-level pitch focused on Phases 2-4, with Phase 1 as background |
+| 2026-04-20 | Capability assessment: no delegation needed | All required context is in local files; analytical work only |