@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/design/layer3b-ghost-nodes-design-review.md

@@ -0,0 +1,93 @@
+# Layer 3b Ghost Nodes -- Design Review Findings
+
+*Design review of the Candidate B approach: backend-emitted `skippedSteps` with label resolution.*
+
+---
+
+## Tradeoff Review
+
+### Approximate positioning (trace event index order)
+Safe. `nextTopLevel` iterates `compiled.steps` in array order, so trace event index IS workflow definition order. Hidden assumption (compiler preserves step order) is guaranteed by the workflow compiler. Tradeoff accepted.
+
+### Ghost nodes not clickable
+Acceptable. The `[ TRACE ]` tab in session detail already shows all `evaluated_condition` SKIP items. Ghost nodes can surface the SKIP reason via a hover tooltip (using `hoveredLabel` state already in `RunLineageDag`). No dedicated panel needed.
+
+### Two manually-mirrored type files
+Acceptable with mitigation. Both files updated in the same PR. Frontend adds `run.skippedSteps ?? []` defensive fallback at consumption site in `RunLineageDag`.
+
+### Labels fall back to null when no workflow hash
+Safe. The null fallback is unreachable in practice (no-workflow sessions cannot have `runCondition`). Fallback degrades gracefully to showing raw stepId.
+
+---
+
+## Failure Mode Review
+
+### FM1: Compiled workflow not pinned -> null labels
+**Coverage**: Adequate. Graceful degradation to stepId display. Low risk.
+
+### FM2: Frontend receives skippedSteps as undefined
+**Coverage**: Needs explicit mitigation. Add `run.skippedSteps ?? []` at the `useMemo` consumption site in `RunLineageDag.tsx`. Medium risk in rollback scenarios.
+
+### FM3: Duplicate SKIP entries for same stepId
+**Coverage**: Needs explicit implementation. Backend `resolveSkippedSteps` must deduplicate by stepId using a `Set<string>`. Without this, a step appears as multiple ghost nodes, which is confusing. Medium risk.
+
+### FM4: Ghost nodes clipping at canvas right edge
+**Coverage**: Needs explicit implementation. `graphWidth` in `buildLineageDagModel` (or the ghost positioning function) must ensure the canvas is wide enough to include the ghost column (`depth = maxActiveDepth + 1`). Medium risk -- visually obvious if missed.
+
+### FM5: Ghost nodes in OverviewRail
+**Coverage**: Handled by construction. Ghost nodes never enter `model.nodes`. No action needed.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+Candidate A (frontend-only, no labels) loses on UX value -- raw step IDs are not readable to users. No elements worth borrowing.
+
+No simpler variant exists that preserves label quality without backend involvement. The named `ConsoleGhostStep` interface is the correct type-safe representation; `nodeKind: 'ghost'` on `ConsoleDagNode` would pollute all existing node-handling code.
+
+---
+
+## Philosophy Alignment
+
+All core principles satisfied:
+- Make illegal states unrepresentable: ghost steps cannot masquerade as `ConsoleDagNode`
+- Immutability: all `readonly`
+- Validate at boundaries: label resolution at backend
+- Small pure functions: three single-responsibility functions
+- YAGNI: no exact positioning, no click handling, no rail integration
+- Errors are data: `stepLabel: null` not thrown
+
+One acceptable tension: exhaustiveness enforcement is not needed for `ConsoleGhostStep` (not a discriminated union participant).
+
+---
+
+## Findings
+
+### Yellow: FM2 -- Type mismatch fallback missing
+The design does not explicitly specify `run.skippedSteps ?? []` at the consumption site. If `skippedSteps` arrives as `undefined` (old backend, rollback), ghost nodes silently disappear. Not a crash, but invisible feature loss.
+**Severity**: Yellow (not a crash, graceful but invisible).
+
+### Yellow: FM3 -- Deduplication not in spec
+Backend `resolveSkippedSteps` spec does not explicitly require dedup by stepId. A session with multiple condition evaluations of the same step would produce duplicate ghost nodes.
+**Severity**: Yellow (confusing UX, not broken).
+
+### Yellow: FM4 -- graphWidth extension not specified
+The `graphWidth` formula in `buildLineageDagModel` does not account for the ghost column. Ghost nodes at `depth = maxActiveDepth + 1` would clip at the right edge of the canvas.
+**Severity**: Yellow (visually broken but easy to fix once noticed).
+
+---
+
+## Recommended Revisions
+
+1. **Add `run.skippedSteps ?? []` fallback** in `RunLineageDag.tsx` at the `useMemo` that reads skipped steps.
+2. **Specify dedup requirement** in `resolveSkippedSteps`: collect stepIds into a `Set<string>` and skip already-seen stepIds.
+3. **Extend graphWidth** in the ghost positioning function or in `buildLineageDagModel` to ensure the ghost column is within canvas bounds: `ghostDepth = maxActiveDepth + 1; canvasWidth = max(current, LINEAGE_SCROLL_OVERHANG * 2 + LINEAGE_PADDING * 2 + ghostDepth * LINEAGE_COLUMN_WIDTH + ACTIVE_NODE_WIDTH)`.
+4. **Add hover tooltip** for ghost nodes using the existing `hoveredLabel`/`tooltipPos` state in `RunLineageDag` (shows the step label or SKIP reason on hover). Low-effort, improves usability.
+
+---
+
+## Residual Concerns
+
+None that would block implementation. All three yellow findings are implementation-level details (not architectural) and are addressed by the recommended revisions above.
+
+The design is sound for implementation.

package/docs/design/layer3b-ghost-nodes-implementation-plan.md

@@ -0,0 +1,219 @@
+# Layer 3b Ghost Nodes -- Implementation Plan
+
+*Execution-ready plan. Design is locked. Do not re-open design questions during implementation.*
+
+---
+
+## 1. Problem Statement
+
+The console's session detail DAG only shows nodes that were actually executed. When a workflow has `runCondition` on top-level steps, the DAG can look sparse -- jumping from phase 0 to phase 6 with no explanation. Users cannot tell whether the missing steps were skipped intentionally or represent a bug.
+
+Layer 3b adds "ghost nodes" for skipped steps: rendered at 0.25 opacity with a `[ SKIPPED ]` badge, positioned after the active lineage. This makes the full workflow shape visible and explains sparse DAGs.
+
+---
+
+## 2. Acceptance Criteria
+
+- [ ] When a session has `executionTraceSummary` with `evaluated_condition` items whose summaries start with `SKIP:` and have `step_id` refs, the DAG renders ghost nodes for those step IDs
+- [ ] Ghost nodes are rendered at 0.25 opacity
+- [ ] Ghost nodes show a `[ SKIPPED ]` MonoLabel badge
+- [ ] Ghost nodes show the human-readable step label (from compiled workflow) or fall back to the raw stepId
+- [ ] Ghost nodes are NOT clickable (no node detail panel opens)
+- [ ] Ghost nodes appear ONLY when `run.executionTraceSummary !== null`
+- [ ] Ghost nodes do NOT appear in the OverviewRail
+- [ ] Duplicate skipped step IDs (same step evaluated multiple times) produce a single ghost node
+- [ ] Ghost nodes are positioned within canvas bounds (no visual clipping)
+- [ ] Ghost nodes show a hover tooltip with the full step label or SKIP summary
+- [ ] All existing tests pass: `npx vitest run` from repo root AND `cd console && npx vitest run`
+- [ ] New pure-function tests cover: SKIP item extraction, deduplication, non-SKIP items excluded
+
+---
+
+## 3. Non-Goals
+
+- Ghost nodes for loop body steps skipped inside loops (only top-level `runCondition` skips)
+- Ghost nodes clickable / showing node detail panel
+- Ghost nodes in the OverviewRail
+- Exact workflow-step-order column positioning (approximate ordering by trace event index is sufficient)
+- Any new domain events or changes to the session event schema
+- Ghost nodes when no `executionTraceSummary` is present (legacy sessions)
+
+---
+
+## 4. Philosophy-Driven Constraints
+
+- `ConsoleGhostStep` must be a named interface with all-`readonly` fields -- not an inline type
+- Ghost steps must never appear in `run.nodes` -- they are a separate array `run.skippedSteps`
+- Ghost step extraction is a pure function in `session-detail-use-cases.ts` (no logic in view)
+- Ghost node rendering is a separate `useMemo` block in `RunLineageDag.tsx` (sub-feature D), not mixed with `flowNodes`/`flowEdges`
+- Backend label resolution reuses `extractStepTitlesFromCompiled` -- no new I/O paths
+- `run.skippedSteps ?? []` defensive fallback at frontend consumption site
+
+---
+
+## 5. Invariants
+
+- `ConsoleGhostStep` has shape: `{ readonly stepId: string; readonly stepLabel: string | null }`
+- `ConsoleDagRun.skippedSteps` is always an array (never undefined) -- initialized to `[]` by backend
+- Ghost steps are deduplicated by `stepId` (same step only appears once)
+- Ghost node `x` position: `LINEAGE_SCROLL_OVERHANG + LINEAGE_PADDING + ghostDepth * LINEAGE_COLUMN_WIDTH` where `ghostDepth = maxActiveLineageDepth + 1`
+- `graphWidth` must accommodate the ghost column: `max(current graphWidth, LINEAGE_SCROLL_OVERHANG * 2 + LINEAGE_PADDING * 2 + ghostDepth * LINEAGE_COLUMN_WIDTH + ACTIVE_NODE_WIDTH)`
+- Ghost nodes are never ReactFlow `Node` objects in the `flowNodes` array -- they are absolute-positioned overlays
+- Ghost nodes only rendered when `run.executionTraceSummary !== null`
+
+---
+
+## 6. Selected Approach
+
+**Candidate B: Backend-emitted `skippedSteps` with label resolution**
+
+Backend assembles `skippedSteps: readonly ConsoleGhostStep[]` by scanning `executionTraceSummary.items` for `evaluated_condition` items with `SKIP:` summaries and `step_id` refs, then resolves step labels from the already-loaded compiled workflow via `extractStepTitlesFromCompiled`. Frontend renders as absolute-positioned overlays (sub-feature D), following the Layer 3a pattern for edge diamonds and loop brackets.
+
+**Runner-up**: Candidate A (frontend-only, no labels) -- rejected because raw step IDs are unreadable to users.
+
+**Rationale**: Labels are the primary user-facing value. Backend label resolution reuses existing infrastructure. The Layer 3a pattern (separate `useMemo` + absolute overlay) is well-established.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1: Backend types and DTO assembly
+**Scope**: Add `ConsoleGhostStep` interface and `skippedSteps` field to both mirrored type files. Implement `resolveSkippedSteps` helper in `console-service.ts`. Wire it into `projectSessionDetail`.
+
+**Files**:
+- `src/v2/usecases/console-types.ts` -- add `ConsoleGhostStep`, add `skippedSteps` to `ConsoleDagRun`
+- `console/src/api/types.ts` -- mirror the same changes
+- `src/v2/usecases/console-service.ts` -- add `resolveSkippedSteps` helper, call it in `projectSessionDetail`
+
+**Done when**: Backend assembles `skippedSteps` correctly; existing tests still pass.
+
+**Verification**: `npx vitest run` passes. Manual inspection: a session with skipped steps shows populated `skippedSteps` array in the API response.
+
+---
+
+### Slice 2: Frontend use-case helper and tests
+**Scope**: Add `getSkippedStepsFromTrace` pure function to `session-detail-use-cases.ts`. Add unit tests.
+
+**Files**:
+- `console/src/views/session-detail-use-cases.ts` -- add `getSkippedStepsFromTrace`
+- `tests/unit/console-session-detail-use-cases.test.ts` -- add tests
+
+**Done when**: Pure function correctly extracts and deduplicates skipped step IDs from trace items; tests pass.
+
+**Verification**: `npx vitest run` passes. Tests cover: SKIP items extracted, non-SKIP items excluded, dedup by stepId, items with no step_id ref excluded, empty input returns empty array.
+
+---
+
+### Slice 3: Ghost node positioning
+**Scope**: Add `positionGhostNodes` pure function (takes `skippedSteps` + `LineageDagModel`, returns `readonly PositionedGhostNode[]`). Define `PositionedGhostNode` interface. Add `graphWidth` extension logic.
+
+**Files**:
+- `console/src/lib/lineage-dag-layout.ts` -- add `PositionedGhostNode` interface and `positionGhostNodes` function; or add as a new dedicated file `console/src/lib/ghost-node-layout.ts`
+- `tests/unit/console-lineage-dag-layout.test.ts` (new) -- test positioning logic
+
+**Done when**: `positionGhostNodes` places ghost nodes at correct coordinates; canvas width accommodates the ghost column.
+
+**Verification**: Unit tests cover: no skipped steps returns empty array; N skipped steps produces N positioned nodes at `ghostDepth = maxActiveDepth + 1`; Y positions are spaced correctly; `requiredWidth` accounts for ghost column.
+
+---
+
+### Slice 4: Ghost node rendering
+**Scope**: Add sub-feature D `useMemo` in `RunLineageDag.tsx`. Add `GhostNodeOverlay` component. Wire hover tooltip.
+
+**Files**:
+- `console/src/components/RunLineageDag.tsx` -- sub-feature D useMemo, GhostNodeOverlay component, `?? []` fallback
+
+**Done when**: Ghost nodes render at 0.25 opacity with `[ SKIPPED ]` badge and step label; hover tooltip works; ghost nodes are not clickable; ghost nodes only appear when `executionTraceSummary !== null`.
+
+**Verification**: Visual inspection in browser. No existing tests broken. `cd console && npx vitest run` passes.
+
+---
+
+## 8. Test Design
+
+### New unit tests in `tests/unit/console-session-detail-use-cases.test.ts`
+
+```
+getSkippedStepsFromTrace:
+- returns [] for empty items
+- extracts stepId from evaluated_condition with SKIP: summary and step_id ref
+- excludes evaluated_condition without SKIP: prefix (loop conditions, PASS conditions)
+- excludes evaluated_condition with no step_id ref
+- deduplicates by stepId (same step evaluated twice -> one entry)
+- preserves order by recordedAtEventIndex
+- excludes items of other kinds (selected_next_step, entered_loop, etc.)
+```
+
+### New unit tests in `tests/unit/console-lineage-dag-layout.test.ts`
+
+```
+positionGhostNodes:
+- returns [] for empty skippedSteps
+- returns [] when model has no active lineage nodes
+- places ghost nodes at depth = maxActiveLineageDepth + 1
+- stacks multiple ghost nodes in separate Y lanes
+- requiredWidth >= x + ACTIVE_NODE_WIDTH for rightmost ghost node
+```
+
+### No new integration tests needed (ghost nodes are purely visual / read-only)
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Type file sync mismatch | Low | Medium | Update both files in same commit; `?? []` fallback at frontend |
+| Ghost nodes clip at right edge | Medium | Medium | FM4: extend graphWidth; unit test covers this |
+| Duplicate ghost nodes | Medium | Low | FM3: dedup in backend helper; unit test covers this |
+| `WorkflowInterpreter` not emitting SKIP traces for all workflow types | Low | High | Verified: `outcome-success.ts` uses `WorkflowInterpreter.next()` -> `traceStepRunConditionSkipped` |
+
+---
+
+## 10. PR Packaging
+
+Single PR: `feature/etienneb/execution-trace-layer3b`
+
+All 4 slices in one PR. They are tightly coupled (backend type -> use-case helper -> positioning -> rendering). Splitting would create intermediate states where the backend field exists but the frontend doesn't render it, which is confusing.
+
+Commit sequence (each squashed into the PR final commit):
+1. Backend types + DTO assembly (Slice 1)
+2. Use-case helper + tests (Slice 2)
+3. Ghost positioning + tests (Slice 3)
+4. Ghost rendering (Slice 4)
+
+Final PR commit message: `feat(console): add ghost nodes for skipped steps in execution trace DAG`
+
+---
+
+## 11. Philosophy Alignment Per Slice
+
+### Slice 1 (Backend types + DTO)
+- Immutability by default -> satisfied: all fields `readonly`
+- Make illegal states unrepresentable -> satisfied: `ConsoleGhostStep` separate from `ConsoleDagNode`
+- Validate at boundaries -> satisfied: label resolution at backend I/O boundary
+- Errors are data -> satisfied: `stepLabel: null` not thrown
+
+### Slice 2 (Use-case helper)
+- Compose with small pure functions -> satisfied: single-responsibility `getSkippedStepsFromTrace`
+- Exhaustiveness everywhere -> N/A: no discriminated union switch needed
+- Prefer fakes over mocks -> satisfied: pure function, no mocks needed
+
+### Slice 3 (Positioning)
+- Determinism over cleverness -> satisfied: same inputs always produce same layout
+- Compose with small pure functions -> satisfied: `positionGhostNodes` is standalone
+
+### Slice 4 (Rendering)
+- YAGNI with discipline -> satisfied: no click handling, no rail integration
+- Functional/declarative over imperative -> satisfied: useMemo pattern, no mutation
+
+---
+
+## Metadata
+
+- `implementationPlan`: complete
+- `slices`: 4
+- `estimatedPRCount`: 1
+- `unresolvedUnknownCount`: 0
+- `planConfidenceBand`: High
+- `followUpTickets`: none identified

package/docs/design/list-workflows-latency-fix-plan.md

@@ -0,0 +1,128 @@
+# list_workflows Latency Fix -- Implementation Plan
+
+## Problem Statement
+
+`list_workflows` latency exceeds 20 seconds (measured at 36.9s for zillow-android-2). Root cause: `walkForRootedWorkflowDirectories` in `src/mcp/handlers/shared/request-workflow-reader.ts` runs a fresh, unbounded recursive DFS on every call across all accumulated remembered roots. Four compounding factors: no walk cache, insufficient skip list, indefinitely accumulated roots, and the 30s timeout wrapping the wrong operation (AFTER the walk).
+
+## Acceptance Criteria
+
+1. `shouldSkipDirectory` skips: `build`, `dist`, `out`, `target`, `.gradle`, `.gradle-cache`, `.cache`, `DerivedData`, `Pods`, `vendor`, `__pycache__`, `.venv`, `venv`, `.next`, `.nuxt`, `.turbo`, `.parcel-cache`, `coverage`, `.nyc_output`
+2. `walkForRootedWorkflowDirectories` stops recursing at depth 5
+3. `discoverRootedWorkflowDirectories` caches the result with a 30s TTL, keyed on sorted root paths
+4. All existing tests in `tests/unit/mcp/request-workflow-reader.test.ts` continue to pass
+5. `npx vitest run` passes with no failures
+
+## Non-Goals
+
+- No changes to remembered-roots eviction policy
+- No persistent disk cache
+- No changes to `v2-workflow.ts` or the 30s loadAllWorkflows timeout
+- No parallelization of the walk
+- No explicit cache invalidation from write paths (TTL-only)
+
+## Philosophy-Driven Constraints
+
+- Cache value must be `readonly` (immutability by default)
+- Cache miss must fall through to fresh walk -- no thrown exceptions (errors are data)
+- Cache key must be deterministic: sorted root paths joined with null byte (determinism over cleverness)
+- Comments must explain TTL rationale and depth limit reasoning (document why, not what)
+
+## Invariants
+
+- Stale path semantics: a root that does not exist (ENOENT) is reported as stale, not thrown
+- Non-ENOENT errors from the root directory are re-thrown
+- Subdirectory ENOENT mid-walk is silently swallowed (the root is not stale)
+- Discovery order is deterministic (directory entries sorted lexicographically)
+- All three invariants are covered by existing tests and must remain green
+
+## Selected Approach
+
+**Candidate C**: Expand skip list + add depth limit (5) + module-level 30s TTL cache in `discoverRootedWorkflowDirectories`.
+
+Runner-up: Candidate B (skip list + depth, no cache) -- loses because repeated calls within a session still re-walk.
+
+Rationale: All three compounding factors are addressed. The staleness window is explicitly specified in the acceptance criteria and is self-healing.
+
+## Vertical Slices
+
+### Slice 1: Expand shouldSkipDirectory
+- File: `src/mcp/handlers/shared/request-workflow-reader.ts`
+- Change: add 18 entries to the `shouldSkipDirectory` predicate
+- Risk: none -- pure additive change to a pure function
+- Test: no new tests needed; existing tests exercise `shouldSkipDirectory` indirectly
+
+### Slice 2: Add depth limit to walkForRootedWorkflowDirectories
+- File: `src/mcp/handlers/shared/request-workflow-reader.ts`
+- Change: add `depth: number` parameter (default 0), stop at `depth >= 5`
+- Risk: low -- theoretical miss for `.workrail` nested deeper than 5 levels
+- Test: add one test: walk with `.workrail` at depth exactly 5 is found; at depth 6 is not found (validates the boundary)
+
+### Slice 3: Add module-level TTL cache to discoverRootedWorkflowDirectories
+- File: `src/mcp/handlers/shared/request-workflow-reader.ts`
+- Change: module-level `Map<string, {readonly result: WorkflowRootDiscoveryResult, readonly expiresAt: number}>`, cache key = `[...roots].sort().join('\0')`, TTL = 30_000ms
+- Risk: low -- mutable module state; acceptable given Node.js single-threaded execution
+- Test: add one test: calling `discoverRootedWorkflowDirectories` twice with the same roots returns the same object reference (proves cache hit, not re-walk)
+
+## Test Design
+
+### Existing tests (must stay green)
+All 9 tests in `tests/unit/mcp/request-workflow-reader.test.ts` -- cover deterministic ordering, stale paths, ENOENT handling, mid-walk disappearance. No changes needed to these tests.
+
+### New tests to add (in the same file)
+
+**Slice 2 test**: depth limit boundary
+```
+it('discovers .workrail at depth 5 but not depth 6', async () => {
+  // create dir structure: root/a/b/c/d/.workrail/workflows (depth 5 -- found)
+  //                       root/a/b/c/d/e/.workrail/workflows (depth 6 -- not found)
+  // assert discovered contains depth-5 path, not depth-6 path
+})
+```
+
+**Slice 3 test**: cache hit returns same result
+```
+it('returns cached result on second call with same roots within TTL', async () => {
+  // call discoverRootedWorkflowDirectories([root]) twice
+  // assert result1 === result2 (same object reference -- proves cache hit)
+})
+```
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| .workrail at depth > 5 missed | Very low | Medium | Convention places .workrail at project root; document in comment |
+| 30s staleness confuses users | Low | Low | Self-healing; acceptable per acceptance criteria |
+| Cache state leaks between tests | Very low | Low | Unique temp dir paths per test = unique cache keys |
+
+## PR Packaging Strategy
+
+Single PR. All three changes are in one file, are tightly related, and address a single root cause. Splitting would not add clarity.
+
+Commit message: `perf(mcp): bound walk depth, expand skip list, cache discovery results`
+
+## Philosophy Alignment per Slice
+
+### Slice 1 (skip list)
+- Immutability by default -> satisfied (pure function, no state)
+- Architectural fixes over patches -> satisfied (changes the structural constraint)
+- YAGNI with discipline -> satisfied (known real dirs, no speculation)
+
+### Slice 2 (depth limit)
+- Determinism over cleverness -> satisfied (fixed depth, predictable behavior)
+- Compose with small pure functions -> satisfied (depth flows through recursion cleanly)
+- Immutability by default -> satisfied (no new state)
+
+### Slice 3 (cache)
+- Immutability by default -> tension (module-level Map is mutable) -- acceptable, confined
+- Dependency injection for boundaries -> tension (Date.now() not injected) -- acceptable, unique per-test keys prevent leakage
+- Determinism over cleverness -> satisfied (sorted key = stable behavior)
+- YAGNI with discipline -> satisfied (TTL-only, no persistent cache)
+
+## Summary
+
+- `implementationPlan`: Candidate C, all changes in `request-workflow-reader.ts`
+- `slices`: 3 (skip list, depth limit, TTL cache)
+- `estimatedPRCount`: 1
+- `unresolvedUnknownCount`: 0
+- `planConfidenceBand`: High

package/docs/design/list-workflows-latency-fix-review.md

@@ -0,0 +1,55 @@
+# list_workflows Latency Fix -- Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Safe? | Condition for failure | Hidden assumption |
+|---|---|---|---|
+| Module-level mutable Map | Yes | Would fail with concurrent writes -- not possible in single-threaded Node.js | Module loaded once per process (true for Node.js ESM/CJS) |
+| 30s staleness window | Yes | Explicitly specified in acceptance criteria; self-healing | Roots list change within TTL causes cache miss automatically (new key = cache miss) |
+| Depth limit of 5 | Yes | `.workrail` nested > 5 levels deep -- no real-world evidence | `.workrail` is always near the top of a project tree by convention |
+
+## Failure Mode Review
+
+| Failure mode | Handled? | Missing mitigation | Danger |
+|---|---|---|---|
+| `.workrail` at depth > 5 | No (silently missed) | Optional: log when depth limit hit | Low -- no real-world evidence of this pattern |
+| 30s staleness for new `.workrail` dir | Yes (self-heals) | Optional: expose `invalidateWalkCache()` | Low -- edge case scenario |
+| Skip list misses large dir | Depth limit backstop | None needed | Low -- two independent mitigations |
+| Cache key collision | Not possible | None needed | None |
+
+## Runner-Up / Simpler Alternative Review
+
+- **Runner-up (B: no cache)**: the only difference is absence of cache -- a weakness, not a strength. Nothing to borrow.
+- **Simpler (skip list + cache, no depth)**: saves 4 lines but removes depth safety net. Not worth it.
+- **Hybrid**: no uncomfortable tradeoff to resolve. Candidate C stands.
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Determinism over cleverness | Satisfied -- sorted cache key, stable behavior |
+| Compose with small pure functions | Satisfied -- each function stays focused |
+| YAGNI with discipline | Satisfied -- TTL-only, no persistent cache |
+| Architectural fixes over patches | Satisfied -- structural constraints changed |
+| Immutability by default | Tension -- module-level Map is mutable; acceptable, confined behind pure interface |
+| Dependency injection for boundaries | Tension -- `Date.now()` not injected; acceptable, unique per-test keys prevent leakage |
+
+## Findings
+
+### Yellow: Mutable module-level cache
+The module-level `Map` is the only mutable state in the file. Acceptable given Node.js single-threaded execution and confinement behind the public functional interface. Not a blocking concern.
+
+### Yellow: Injected clock not used
+`Date.now()` is called directly in the cache check. Tests work correctly without fake clocks because each test uses unique temp dir paths. If future tests need to verify TTL expiry behavior, they would need to restructure the test rather than inject a clock. Document this as a known limitation in the code comment.
+
+## Recommended Revisions
+
+None required. The design satisfies all acceptance criteria without revision.
+
+Optional improvements (low priority):
+- Add a debug log when depth limit is reached (helps diagnose missed `.workrail` dirs in exotic repos)
+- Export `clearWalkCache()` for testing TTL expiry behavior (not needed for current test suite)
+
+## Residual Concerns
+
+None blocking. The 30s staleness window is the most user-visible issue but is explicitly specified in the acceptance criteria and self-heals.

package/docs/design/list-workflows-latency-fix.md

@@ -0,0 +1,109 @@
+# list_workflows Latency Fix -- Design Candidates
+
+## Problem Understanding
+
+### Core tensions
+1. **Correctness vs speed**: A deeper skip list and depth limit could miss legitimately nested `.workrail` directories. Chosen conservatively -- standard monorepo conventions don't nest `.workrail` deeper than 5 levels.
+2. **Simplicity vs invalidation accuracy**: A TTL cache may serve stale results if a user creates a new `.workrail` dir within the 30s window. Explicit invalidation would require threading a cache-invalidation signal through unrelated write paths.
+3. **Module-level mutable state vs dependency injection**: The cache as a module-level Map is pragmatic. Injecting a clock for testability would be over-engineered for a 30s TTL.
+
+### Likely seam
+All three fixes are confined to `src/mcp/handlers/shared/request-workflow-reader.ts`. No API surface changes. No callers need to change.
+
+### What makes this hard
+Nothing technically hard. The risk is under-fixing (skip list only) or over-engineering (persistent cross-process cache).
+
+---
+
+## Philosophy Constraints
+
+Source: `/Users/etienneb/git/personal/workrail/AGENTS.md`
+
+- **Immutability by default** -- cache value should be `readonly`; the Map is mutable but confined
+- **Errors are data** -- cache miss falls through to fresh walk, no exceptions
+- **Determinism over cleverness** -- sort roots for stable cache key
+- **YAGNI with discipline** -- TTL only, no persistent cache
+
+No conflicts between stated philosophy and existing repo patterns.
+
+---
+
+## Impact Surface
+
+- `discoverRootedWorkflowDirectories` is called once per `createWorkflowReaderForRequest` invocation
+- The cache is internal to the function -- callers observe no API change
+- Tests in `tests/unit/mcp/request-workflow-reader.test.ts` use fresh temp dirs per test, so cache keys never collide between test cases (TTL won't cause cross-test leakage)
+
+---
+
+## Candidates
+
+### Candidate A: Skip list expansion only
+
+Expand `shouldSkipDirectory` to skip: `build`, `dist`, `out`, `target`, `.gradle`, `.gradle-cache`, `.cache`, `DerivedData`, `Pods`, `vendor`, `__pycache__`, `.venv`, `venv`, `.next`, `.nuxt`, `.turbo`, `.parcel-cache`, `coverage`, `.nyc_output`.
+
+- **Tensions resolved**: width of walk (88% of Android monorepo eliminated)
+- **Tensions accepted**: repeated calls still re-walk; no depth bound
+- **Boundary**: `shouldSkipDirectory` pure predicate
+- **Failure mode**: large tree with unusual directory names not in the list
+- **Repo pattern**: follows exactly -- extends an existing two-entry check
+- **Gains**: zero added complexity, zero new state
+- **Losses**: no protection against deep trees or repeated calls
+- **Scope**: too narrow for the stated acceptance criteria
+- **Philosophy fit**: perfect -- pure function, no mutable state
+
+### Candidate B: Skip list + depth limit
+
+All of A, plus `depth: number` parameter (default 0) passed through `walkForRootedWorkflowDirectories`, stopping recursion at `depth >= 5`.
+
+- **Tensions resolved**: wide trees and deep trees both bounded
+- **Tensions accepted**: repeated calls still re-walk
+- **Boundary**: `walkForRootedWorkflowDirectories` internal function; depth flows through the recursion
+- **Failure mode**: `.workrail` at depth > 5 (e.g., `root/a/b/c/d/e/.workrail`) -- no real-world evidence of this
+- **Repo pattern**: adapts -- passing context through recursion already done with `discoveredPaths[]`
+- **Gains**: worst-case walk is bounded even for exotic directory structures
+- **Losses**: minor theoretical miss for very deep repos
+- **Scope**: best-fit if cache is not required
+- **Philosophy fit**: honors determinism, small pure functions
+
+### Candidate C: Skip list + depth limit + module-level TTL cache (full fix)
+
+All of B, plus a `Map<string, {readonly result: WorkflowRootDiscoveryResult, readonly expiresAt: number}>` at module level in `discoverRootedWorkflowDirectories`. Cache key = root paths sorted and joined with `\0`. TTL = 30 seconds (matches diagnosis acceptance criteria).
+
+- **Tensions resolved**: all three compounding factors; repeated calls within a session are near-zero cost
+- **Tensions accepted**: up to 30s staleness if a new `.workrail` dir is created while cache is warm
+- **Boundary**: `discoverRootedWorkflowDirectories` -- the public API for the discovery step; cache is entirely internal
+- **Failure mode**: new `.workrail` directory not visible until TTL expires
+- **Repo pattern**: departs -- no precedent for in-memory caching in this module, but pattern is standard
+- **Gains**: eliminates 30s wall-clock penalty for repeated calls in the same process lifetime
+- **Losses**: module-level mutable state; slight staleness window
+- **Scope**: best-fit -- all changes in one file, no API changes, matches stated acceptance criteria
+- **Philosophy fit**: slight tension with immutability (module Map is mutable) -- mitigated by confining it behind a pure functional interface
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate C**
+
+The diagnosis identified four compounding factors and three required fixes. Candidate C addresses all of them. The skip list alone eliminates the bulk of the Android walk but leaves repeated-call overhead and offers no protection against other large monorepos. The depth limit adds a safety net. The cache converts a 30s wall-clock penalty into a sub-millisecond repeat for the common case.
+
+The 30s staleness window is the most manageable failure mode: it self-heals, requires no user action, and matches the stated acceptance criteria from the prior investigation.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument**: The cache introduces the only real mutable state in the module. If a test runner reuses the module between test cases, cache state could leak. Mitigation: cache keys are based on the actual root paths, which are unique temp dirs per test -- no leakage in practice.
+
+**Narrower option (B)**: Would lose the cache benefit for repeated calls within a session. Even with the skip list, repeated walks without cache cost real latency on large monorepos.
+
+**Broader option (persistent disk cache)**: Not justified. The 30s in-memory TTL is sufficient; persistent cache adds I/O and invalidation complexity with no material gain.
+
+**Pivot condition**: If `.workrail` conventions change to allow deeper nesting, increase the depth limit. If the 30s staleness window causes user-reported issues, add explicit cache invalidation triggered from the remembered-roots write path.
+
+---
+
+## Open Questions
+
+None requiring human decision. The diagnosis and acceptance criteria are fully specified.

package/docs/design/native-context-management-api.md

@@ -0,0 +1,11 @@
+# Native Context Management: API Design
+
+> **Not pursuing**
+>
+> WorkRail is not planning to implement native context management.
+>
+> This file is kept only as a stable tombstone so old links do not break.
+>
+> See:
+> - `docs/roadmap/legacy-planning-status.md`
+> - `docs/plans/native-context-management-epic.md`