@exaudeus/workrail 3.32.0 → 3.34.0

package/docs/design/workflow-id-validation-design-review.md

@@ -0,0 +1,87 @@
+# Design Review: Workflow ID Validation at Daemon Startup
+
+**Design under review:** Candidate A -- injectable `getWorkflowByIdFn` on `StartTriggerListenerOptions`  
+**Date:** 2026-04-16
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Acceptable? | Condition that breaks it |
+|----------|-------------|--------------------------|
+| Validation silently skipped when fn not provided | Yes | A new production call site added without the fn |
+| New option field (API surface) | Yes | Interface is internal, non-breaking |
+
+Hidden assumption: single production call site for `startTriggerListener`. True today.
+
+**Mitigation added:** Log message when fn not provided, making the skip visible in startup logs.
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Handled? | Action Required |
+|--------------|----------|-----------------|
+| FM1: getWorkflowByIdFn throws/rejects | NOT YET | Add try/catch around each fn call; warn+skip on error |
+| FM2: transient workflow unavailability | Acceptable | warn+skip behavior is correct here |
+| FM3: Map mutation during iteration | NOT YET | Collect unknowns in first pass, delete in second pass |
+| FM4: ctx.workflowService undefined in production | Needs guard | Use optional chaining `?.` in default fn |
+
+**Highest-risk:** FM1. An unhandled rejection would crash `startTriggerListener`. Must fix.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+- Runner-up (Candidate B, ctx direct): no elements to borrow. Testability loss outweighs API surface saving.
+- No simpler variant satisfies both testability and correctness requirements.
+- Candidate A is already minimum viable for the acceptance criteria.
+
+---
+
+## Philosophy Alignment
+
+**Satisfied:** Dependency injection, validate at boundaries, errors are data, YAGNI, surface information.  
+**Under tension (acceptable):**
+- "Make illegal states unrepresentable" -- TriggerDefinition can still hold invalid workflowIds. Compile-time enforcement would require two-phase types; over-engineering for a Small task.
+- "Immutability by default" -- triggerIndex Map is mutated, but mutation is local (created and modified within `startTriggerListener`, not shared until passed to TriggerRouter).
+
+---
+
+## Findings
+
+**ORANGE -- FM1: Unhandled rejection from getWorkflowByIdFn**  
+The current design has no try/catch around the fn call. An I/O error in the workflow storage lookup would propagate as an unhandled rejection and crash `startTriggerListener`. Fix: wrap each `await getWorkflowByIdFn(trigger.workflowId)` in try/catch; on error, log warning and skip that trigger (same policy as other validation failures).
+
+**YELLOW -- FM3: Two-pass Map deletion**  
+Must not delete from `triggerIndex` while iterating it. Fix: collect unknown IDs in an array during the loop, then delete in a second pass.
+
+**YELLOW -- FM4: ctx.workflowService guard**  
+The default fn production expression `ctx.workflowService.getWorkflowById(id).then(...)` will throw if `workflowService` is undefined. Fix: use optional chaining `ctx.workflowService?.getWorkflowById(id).then(w => w !== null) ?? true` (treat unavailable service as "found" -- skip validation rather than crash).
+
+---
+
+## Recommended Revisions
+
+1. **Required:** Add try/catch in the validation loop; treat fn errors as warn+skip.
+2. **Required:** Collect unknowns first, delete after iteration.
+3. **Required:** Use optional chaining for the default production fn.
+4. **Nice-to-have:** Log `[TriggerListener] workflowId validation skipped (no resolver provided)` when fn is absent, for observability.
+
+---
+
+## Residual Concerns
+
+- The "silent skip when fn not provided" is acceptable but relies on a naming convention (option field) to communicate intent. Future callers won't get a compile-time reminder to provide the fn. This is a documentation concern, not a correctness concern.
+- `onComplete.workflowId` is not validated by this design. Out of scope for this task; should be a follow-up if `onComplete` usage grows.
+- No RED findings. All issues are fixable at implementation time with minor code additions.
+
+---
+
+## Pass 2 Findings (incremental)
+
+No new RED or ORANGE findings. Design revisions from pass 1 are sufficient.
+
+**New observation (YELLOW):** `onComplete.workflowId` (secondary workflow for completion hooks) is not validated. Accepted as out of scope -- add a comment in the implementation noting this limitation.
+
+**Performance:** Sequential validation of N triggers is acceptable at expected trigger counts (1-10). No action needed.

package/docs/design/workflow-id-validation-implementation-plan.md

@@ -0,0 +1,185 @@
+# Implementation Plan: Workflow ID Validation at Daemon Startup
+
+**Status:** Ready to implement  
+**Branch:** `fix/workflow-id-validation-at-startup`  
+**Date:** 2026-04-16
+
+---
+
+## 1. Problem Statement
+
+When a user writes an incorrect `workflowId` in `triggers.yml` (e.g., `coding-task-workflow-agentic.lean.v2` instead of `coding-task-workflow-agentic`), the daemon starts successfully, accepts webhooks, but every dispatch silently fails with `workflow_not_found`. The error only appears in logs during actual webhook events -- not at startup. This is a silent-failure bug.
+
+---
+
+## 2. Acceptance Criteria
+
+- [x] At daemon startup, after loading and indexing triggers, validate that each trigger's `workflowId` resolves to a known workflow
+- [x] Triggers with unknown `workflowId` are logged with a clear warning (naming the triggerId and the bad workflowId) and removed from the active index
+- [x] Triggers with valid `workflowId` start normally
+- [x] If `getWorkflowByIdFn` throws or rejects, that trigger is also warned+skipped (not a daemon crash)
+- [x] Existing behavior when `getWorkflowByIdFn` is not provided: validation is skipped (backward compat, logged)
+- [x] Existing tests continue to pass without modification
+
+---
+
+## 3. Non-Goals
+
+- No hard-fail policy (daemon does not refuse to start; it starts with fewer triggers)
+- No validation of `onComplete.workflowId` (secondary workflow ID -- follow-up ticket)
+- No changes to `trigger-store.ts` or `TriggerDefinition` type
+- No re-validation on webhook arrival
+- No dynamic reload / hot-reload of trigger config
+- No change to `trigger-router.ts` (it already handles `workflow_not_found` at dispatch)
+
+---
+
+## 4. Philosophy-Driven Constraints
+
+- **Dependency injection**: `getWorkflowByIdFn` must be injectable -- no direct `ctx.workflowService` access
+- **Validate at boundaries**: validation runs at `startTriggerListener` (startup boundary), not inside routing
+- **Errors are data**: validation failures are warnings + skip, not thrown exceptions
+- **Document why**: implementation must include WHY comments on the key decisions
+- **Warn+skip over hard-fail**: consistent with `loadTriggerConfig` existing behavior
+
+---
+
+## 5. Invariants
+
+1. The `triggerIndex` passed to `TriggerRouter` contains ONLY triggers whose `workflowId` was confirmed to exist (when `getWorkflowByIdFn` is provided)
+2. The validation loop MUST NOT mutate `triggerIndex` during iteration (collect unknowns first, delete after)
+3. A `getWorkflowByIdFn` rejection/throw MUST NOT propagate -- it is caught, the trigger is warned+skipped
+4. When `getWorkflowByIdFn` is absent, validation is skipped entirely (backward compat) and a log message says so
+5. `DefaultWorkflowService.getWorkflowById` delegates directly to storage (no compilation cache interference) -- validation results are authoritative
+
+---
+
+## 6. Selected Approach
+
+**Add `getWorkflowByIdFn?: (id: string) => Promise<boolean>` to `StartTriggerListenerOptions`.**
+
+In `startTriggerListener`, after `buildTriggerIndex()` returns ok, if `getWorkflowByIdFn` is provided:
+1. Iterate `triggerIndex` entries (read-only pass), collect unknown workflowIds
+2. For each, try `await getWorkflowByIdFn(trigger.workflowId)` -- catch rejection, treat as false
+3. Collect trigger IDs where result is false or threw
+4. After iteration: delete collected IDs from `triggerIndex`, log warnings
+5. Log summary if any were skipped
+
+Production default (not on the option -- called inline): `async (id) => (await ctx.workflowService?.getWorkflowById(id)) !== null`.
+
+**Runner-up:** Candidate B (ctx direct with null guard) -- lost because `FAKE_CTX = {} as V2ToolContext` makes the behavior untestable.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1 -- Core validation logic in `startTriggerListener`
+
+**Files:** `src/trigger/trigger-listener.ts`
+
+**Changes:**
+- Add `getWorkflowByIdFn?: (id: string) => Promise<boolean>` to `StartTriggerListenerOptions`
+- After `buildTriggerIndex()` returns ok (before `new TriggerRouter`): add validation block
+- Validation block logic:
+  ```
+  if (getWorkflowByIdFn) {
+    const unknownTriggerIds: string[] = []
+    for (const [triggerId, trigger] of triggerIndex) {
+      let found: boolean
+      try {
+        found = await getWorkflowByIdFn(trigger.workflowId)
+      } catch (e) {
+        found = false
+        console.warn(`[TriggerListener] Error validating workflowId '${trigger.workflowId}' for trigger '${triggerId}': ${e}`)
+      }
+      if (!found) {
+        unknownTriggerIds.push(triggerId)
+        console.warn(`[TriggerListener] Skipping trigger '${triggerId}': workflowId '${trigger.workflowId}' not found`)
+      }
+    }
+    for (const id of unknownTriggerIds) { triggerIndex.delete(id) }
+    if (unknownTriggerIds.length > 0) {
+      console.warn(`[TriggerListener] Skipped ${unknownTriggerIds.length} trigger(s) with unknown workflowId(s)`)
+    }
+  } else {
+    console.log(`[TriggerListener] workflowId validation skipped (no resolver provided)`)
+  }
+  ```
+- Add production default invocation: pass `async (id) => (await ctx.workflowService?.getWorkflowById(id)) !== null` as the default when option not provided
+
+**Acceptance criterion:** Unknown workflowId triggers are not present in the index passed to `TriggerRouter`.
+
+### Slice 2 -- Tests in `trigger-router.test.ts`
+
+**Files:** `tests/unit/trigger-router.test.ts`
+
+**New test cases (in a new describe block `startTriggerListener workflowId validation`):**
+1. Triggers with unknown workflowId are warned and skipped (index excludes them, server starts)
+2. Triggers with valid workflowId are kept in the index
+3. When `getWorkflowByIdFn` is not provided, validation is skipped and all triggers are kept
+4. When `getWorkflowByIdFn` rejects, that trigger is warned and skipped (daemon doesn't crash)
+5. Mix: some valid, some invalid -- only valid triggers remain
+
+**Acceptance criterion:** All 5 test cases pass.
+
+---
+
+## 8. Test Design
+
+**Pattern to follow:** `startTriggerListener` tests in `trigger-router.test.ts` (~line 432). Same structure:
+- Use `tmpPath()` for workspacePath
+- `env: { WORKRAIL_TRIGGERS_ENABLED: 'true' }`
+- `port: 0` for OS-assigned port
+- `runWorkflowFn: vi.fn()`
+- `workspaces: {}` to skip workspace config loading
+
+**Fixtures needed:**
+- A minimal `triggers.yml` with two triggers: one with valid workflowId, one with invalid
+- `getWorkflowByIdFn` stub: `vi.fn().mockImplementation(async (id: string) => id === 'coding-task-workflow-agentic')`
+
+**Note:** Tests write real `triggers.yml` files to `tmpPath()` directories (pattern established in existing tests). Check how existing `startTriggerListener` tests set up workspace directories.
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| `ctx.workflowService` undefined in production | Low | Medium | Optional chaining `?.` in default fn |
+| FM1: getWorkflowByIdFn throws | Low-Medium | High | try/catch per call, warn+skip |
+| FM3: Map mutation during iteration | Low (easy to avoid) | Medium | Two-pass (collect then delete) |
+| False positive (valid workflow not found due to I/O error) | Low | Low | Same as FM1 -- warn+skip, operator can restart |
+| `onComplete.workflowId` still silent-fails | Medium | Low | Accepted, documented, follow-up ticket |
+
+---
+
+## 10. PR Packaging
+
+**Single PR.** Small task, all changes in 2 files. Branch: `fix/workflow-id-validation-at-startup`.
+
+PR title: `fix(trigger): warn and skip triggers with unknown workflowId at startup`
+
+---
+
+## 11. Philosophy Alignment Per Slice
+
+| Principle | Slice 1 | Slice 2 |
+|-----------|---------|---------|
+| Dependency injection for boundaries | Satisfied -- fn injectable | Satisfied -- tests inject stub |
+| Validate at boundaries | Satisfied -- startup boundary | N/A |
+| Errors are data | Satisfied -- warn+skip, no throw | Satisfied -- tests verify no crash |
+| Document why | Satisfied -- WHY comments required | N/A |
+| Warn+skip over hard-fail | Satisfied | Verified by tests |
+| Immutability by default | Tension -- triggerIndex mutated, but local scope | N/A |
+
+---
+
+## 12. Follow-up Tickets
+
+- `onComplete.workflowId` validation (secondary workflow IDs in completion hooks)
+
+---
+
+**unresolvedUnknownCount:** 0  
+**planConfidenceBand:** High  
+**estimatedPRCount:** 1

package/docs/design/worktrain-system-prompt-report-issue-candidates.md

@@ -0,0 +1,135 @@
+# WorkTrain: System Prompt Preamble + report_issue Tool -- Design Candidates
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Preamble richness vs. existing test assertions** -- The current `buildSystemPrompt()` preamble is ~15 lines (identity, tools, execution contract, session state). The new spec replaces it with ~55 lines covering oracle hierarchy, self-directed reasoning, workflow-as-contract, silent failure, and tools-as-hands. The existing tests assert specific strings (`'You are WorkRail Auto'`, `'## Your tools'`, `'## Execution contract'`) must be present. The new content must include those strings or the tests break.
+
+2. **report_issue write durability vs. fire-and-forget contract** -- The JSONL file must be written reliably enough for a future coordinator to read it, but a disk-full or permission error must never interrupt the agent session. Resolution: same void+catch pattern as `DaemonEventEmitter`.
+
+3. **Purity of buildSystemPrompt vs. tool name references in prose** -- The new preamble mentions `report_issue` by name in the "silent failure" section. If the tool name ever changes, the system prompt text becomes stale. This is an accepted documentation-drift risk; tool names are stable identifiers.
+
+4. **YAGNI (no coordinator yet) vs. extractability (coordinator coming soon)** -- The auto-fix coordinator that will read the issue JSONL doesn't exist. Building a dedicated `IssueStore` class now is speculative. However, the file write must still work for the coordinator when it arrives.
+
+### Likely Seam
+
+- **Preamble:** `buildSystemPrompt()` lines 1086-1108 in `src/daemon/workflow-runner.ts`. This is the correct seam -- pure function, all callers go through it.
+- **report_issue tool:** The tools array in `runWorkflow()` at lines 1318-1323. New tool factory `makeReportIssueTool()` slots in here.
+- **DaemonEvent union:** `src/daemon/daemon-events.ts` -- add `IssueReportedEvent` + extend union.
+
+### What Makes This Hard
+
+- Existing test assertions constrain the new preamble content -- `'## Your tools'` and `'## Execution contract'` must survive the rewrite.
+- `report_issue.execute()` must be fire-and-forget for the JSONL write. Junior devs would `await` it directly and let I/O errors propagate.
+- `IssueReportedEvent` fields must be typed as literal union strings (not `string`), otherwise illegal kind/severity values are representable at compile time.
+
+---
+
+## Philosophy Constraints
+
+From `/Users/etienneb/CLAUDE.md` and `~/.workrail/daemon-soul.md`:
+
+- **Exhaustiveness everywhere** -- `DaemonEvent` must remain a discriminated union; new variant must follow the pattern
+- **Make illegal states unrepresentable** -- `kind` and `severity` on IssueReportedEvent must be literal unions, not strings
+- **YAGNI with discipline** -- don't build IssueStore class until the coordinator needs it
+- **Observability as a constraint** -- fire-and-forget writes must never block correctness
+- **Document 'why' not 'what'** -- JSDoc on BASE_SYSTEM_PROMPT explaining why it's a constant
+- **Immutability by default** -- all DaemonEvent interfaces use `readonly` fields
+- **Functional core, imperative shell** -- buildSystemPrompt is pure; JSONL write is at the shell boundary
+
+---
+
+## Impact Surface
+
+- `tests/unit/workflow-runner-system-prompt.test.ts` -- 3 assertions on preamble content that must pass after rewrite
+- `tests/unit/daemon-events.test.ts` -- existing event tests; adding a new event kind must not break exhaustiveness checks
+- Any future TypeScript code that does `switch (event.kind)` on `DaemonEvent` -- must handle `'issue_reported'` or get a compile error (desired)
+- `runWorkflow()` tools array -- adding `makeReportIssueTool` here; `sessionId` and `emitter` are already in scope
+- The `BASE_SYSTEM_PROMPT` constant mentions the tool by name -- documentation drift if tool is renamed later
+
+---
+
+## Candidates
+
+### Part 1: New Preamble
+
+#### Candidate A -- Inline replacement (no constant)
+- **Summary:** Replace the 4-item preamble lines directly in the `lines` array inside `buildSystemPrompt()`.
+- **Tensions resolved:** Existing tests still pass (required strings included). **Accepted:** Preamble not readable in isolation; harder to document with JSDoc.
+- **Boundary:** Inside `buildSystemPrompt()`, same as today.
+- **Failure mode:** If session state tag position shifts, tests break. Manageable.
+- **Repo pattern:** Departs -- existing code has no named constant but the soul-template.ts extraction is a precedent.
+- **Gains:** No indirection. **Losses:** Not visible as a document; can't be verified without calling buildSystemPrompt.
+- **Scope:** Too narrow.
+
+#### Candidate B -- Named `BASE_SYSTEM_PROMPT` constant (recommended)
+- **Summary:** Extract the static preamble into `export const BASE_SYSTEM_PROMPT: string` defined above `buildSystemPrompt()`. The function uses it as the first element of the lines array. JSDoc explains why it's a constant vs inline.
+- **Tensions resolved:** Preamble visible as a document; existing test assertions pass; honors 'Document why not what'.
+- **Accepted:** Slight indirection; tool name drift risk (prose mentions `report_issue`).
+- **Boundary:** Module-scoped constant, not exported (callers use `buildSystemPrompt`). Dynamic content (session state, soul, workspace) remains in the function.
+- **Failure mode:** If a future author edits `BASE_SYSTEM_PROMPT` and removes `'## Your tools'` or `'## Execution contract'`, tests catch it immediately.
+- **Repo pattern:** Follows soul-template.ts precedent (constant for stable content, function for dynamic assembly).
+- **Gains:** Readable, documentable, testable in isolation. **Losses:** None significant.
+- **Scope:** Best-fit.
+- **Philosophy:** Honors 'Immutability by default' (const), 'Document why not what' (JSDoc), 'Determinism' (pure function unchanged).
+
+---
+
+### Part 2: report_issue Tool
+
+#### Candidate A -- Inline tool factory with private async helper (recommended)
+- **Summary:** `makeReportIssueTool(sessionId: string, emitter?: DaemonEventEmitter): AgentTool` -- custom inline JSON schema (no schemas param), `execute()` fires a void Promise for the JSONL write (same pattern as DaemonEventEmitter), emits `issue_reported` event, returns string confirmation. A module-level private `appendIssueAsync()` function handles the actual fs writes to keep execute() clean.
+- **Tensions resolved:** Fire-and-forget (never blocks), type-safe kind/severity, YAGNI (no IssueStore class), natural tool-factory shape.
+- **Accepted:** Less isolated unit-testability for the JSONL write path (no dirOverride). Extractable later.
+- **Boundary:** Tool factory in `workflow-runner.ts` alongside make*Tool siblings. Private helper in same file.
+- **Failure mode:** JSONL write fails silently. Accepted -- same contract as DaemonEventEmitter.
+- **Repo pattern:** Follows tool factory pattern exactly (name, description, inputSchema, label, execute).
+- **Gains:** Simple, correct, consistent with existing code. **Losses:** JSONL write not unit-testable in isolation today.
+- **Scope:** Best-fit.
+- **Philosophy:** Honors 'YAGNI with discipline', 'Exhaustiveness everywhere' (literal unions), 'Make illegal states unrepresentable', 'Observability as a constraint'.
+
+#### Candidate B -- Dedicated `IssueStore` class (parallel to DaemonEventEmitter)
+- **Summary:** Extract a class `IssueStore` with `append(sessionId, issue)` and `dirOverride` for tests. Injected into `makeReportIssueTool`. Separate file or same file.
+- **Tensions resolved:** Full unit-testability with dirOverride, separation of concerns.
+- **Accepted:** Over-engineering for current scope (coordinator doesn't exist). YAGNI violated.
+- **Boundary:** New abstraction layer. Only one caller today.
+- **Failure mode:** Premature abstraction; adds complexity with no current benefit.
+- **Repo pattern:** Matches DaemonEventEmitter exactly -- but DaemonEventEmitter was built when multiple callers needed it immediately.
+- **Gains:** Testable in isolation, clean interface for future coordinator. **Losses:** Speculative complexity today.
+- **Scope:** Too broad (no coordinator in this PR).
+- **Philosophy:** Conflicts with 'YAGNI with discipline'. Honors 'Prefer fakes over mocks'.
+
+---
+
+## Comparison and Recommendation
+
+### Part 1
+Candidate B (BASE_SYSTEM_PROMPT constant) dominates on every axis. Not a close call.
+
+### Part 2
+Candidate A (inline tool factory) wins on YAGNI. The only real loss is JSONL write isolation in tests -- acceptable since the write is purely observational (fire-and-forget), not correctness-affecting.
+
+**If the auto-fix coordinator were being built in this PR**, Candidate B would be justified. It isn't.
+
+---
+
+## Self-Critique
+
+### Part 1 strongest counter-argument
+'The constant is 55 lines and clutters the file.' Counter: it's in a clearly labeled `## System prompt` section. A 55-line constant is readable. The alternative (55 lines of array items with string literals) is worse. Not a real objection.
+
+### Part 2 strongest counter-argument
+'DaemonEventEmitter is a class -- to be consistent, IssueStore should also be a class.' True in the abstract. But DaemonEventEmitter was built when the event stream was a first-class concern. Issue recording is secondary observability for a future feature. The consistency argument applies when there are multiple callers, not one.
+
+### Pivot conditions
+- **Part 2:** If the coordinator PR is planned for this sprint, extract IssueStore now to save rework later.
+- **Part 1:** If the BASE_SYSTEM_PROMPT constant is exported and used in tests directly, add it to the test file's import.
+
+---
+
+## Open Questions for the Main Agent
+
+1. Should `BASE_SYSTEM_PROMPT` be exported (for tests to import directly) or left module-private? Current test assertions only check the output of `buildSystemPrompt()`, so private is sufficient.
+2. Should `IssueReportedEvent` include `continueToken` (for coordinator to resume)? The spec says optional -- include it as `readonly continueToken?: string`.
+3. The new preamble's `## Your tools` section should list `report_issue` -- does it also list `Bash`, `Read`, `Write`, `continue_workflow`? Yes, for completeness.

package/docs/design/worktrain-system-prompt-report-issue-design-review.md

@@ -0,0 +1,73 @@
+# WorkTrain: System Prompt Preamble + report_issue Tool -- Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Assessment |
+|---|---|
+| Tool name drift: preamble prose mentions `report_issue` | Acceptable. Prose is guidance, not tool registration. Agent uses the tools array. |
+| JSONL write not unit-testable in isolation | **Resolved** by adding `issuesDirOverride?: string` to `makeReportIssueTool`. |
+| No IssueStore class (YAGNI) | Acceptable. Coordinator doesn't exist in this PR. Extractable later. |
+| Fatal severity doesn't abort the loop | Accepted limitation. Tool returns instructional text. Agent is told to stop. Recording the issue is the priority. |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Handling | Risk |
+|---|---|---|
+| Missing issues dir | `mkdir recursive` before appendFile (DaemonEventEmitter pattern) | Low |
+| Preamble loses required test strings | Caught immediately by existing vitest assertions | Low (self-healing) |
+| Agent ignores fatal severity and continues | Instructional return value. Can't force stop from inside tool without violating 'errors are data'. | Medium (accepted) |
+| sessionId is process-local UUID not server ID | Consistent with all other tools in this file. Coordinator correlates via sessionId. | Low |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Part 1:** Inline preamble (runner-up) offers no advantages over the named constant. Candidate B dominates.
+
+**Part 2:** IssueStore class (runner-up) offers `dirOverride` for isolated testing. A hybrid was adopted: add `issuesDirOverride?: string` parameter to `makeReportIssueTool` without extracting a full class. This resolves the testability weakness at negligible complexity cost.
+
+**Simpler alternative (no dirOverride):** Technically satisfies acceptance criteria. Rejected because it violates 'prefer fakes over mocks' and departs from the established DaemonEventEmitter precedent for no benefit.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Immutability by default | Satisfied: `const BASE_SYSTEM_PROMPT`; readonly IssueReportedEvent fields |
+| Make illegal states unrepresentable | Satisfied: `kind` and `severity` are literal union types |
+| Exhaustiveness everywhere | Satisfied: new DaemonEvent variant triggers TS compile error on unhandled switch |
+| Errors are data | Satisfied: report_issue returns string confirmation, never throws |
+| YAGNI with discipline | Satisfied: no IssueStore class |
+| Observability as a constraint | Satisfied: fire-and-forget, never blocks correctness |
+| Prefer fakes over mocks | Satisfied (after hybrid): issuesDirOverride allows temp-dir testing |
+| Document why not what | Satisfied: JSDoc on BASE_SYSTEM_PROMPT constant; WHY comments on void+catch |
+
+---
+
+## Findings
+
+### Yellow (low-risk, note for implementer)
+
+**Y1:** `BASE_SYSTEM_PROMPT` must include `'You are WorkRail Auto'`, `'## Your tools'`, and `'## Execution contract'` to preserve existing test assertions. The implementer must verify these strings survive the rewrite verbatim.
+
+**Y2:** The new preamble's `## Your tools` section should list all 5 tools: `continue_workflow`, `Bash`, `Read`, `Write`, `report_issue`. If any tool is added/removed in the future, the preamble prose becomes stale. Accepted documentation-drift risk.
+
+**Y3:** The `issuesDirOverride` parameter changes the signature of `makeReportIssueTool`. Wire it through `runWorkflow()` with `undefined` (production path). A test for the file write path should be added to `tests/unit/`.
+
+---
+
+## Recommended Revisions
+
+1. **Add `issuesDirOverride?: string` to `makeReportIssueTool`** -- adopt the hybrid over inline-only. (Already decided above.)
+2. **Use `void appendIssueAsync(...).catch(() => {})` idiom** -- identical to DaemonEventEmitter._append; don't await.
+3. **IssueReportedEvent fields:** Use `readonly` on all fields; `issueKind` not `kind` for the payload (since `kind` is the discriminant `'issue_reported'`). Wait -- looking at the spec: the tool's input schema field is `kind` (the issue type), but the event discriminant is also `kind: 'issue_reported'`. Rename the payload field to `issueKind` in `IssueReportedEvent` to avoid shadowing, while keeping the JSON input schema field as `kind` (per spec).
+
+---
+
+## Residual Concerns
+
+- **Fatal severity + agent continuation:** The design cannot enforce stopping. This is a known limitation of the instruction-based approach. The coordinator will need to detect "fatal issue recorded, then agent continued for N more steps" and flag it. Out of scope for this PR.
+- **Issue file format:** The spec says 'JSON line' but doesn't specify the schema. The implementer should include all input fields plus `ts: Date.now()` and `sessionId` for correlation -- consistent with how daemon events are written.