@exaudeus/workrail 3.41.0 → 3.42.0

package/docs/design/context-assembly-implementation-plan.md

@@ -0,0 +1,211 @@
+# Implementation Plan: Context Assembly Layer v1
+
+*Authored during coding-task-workflow-agentic session | 2026-04-19*
+
+---
+
+## Problem Statement
+
+When the PR review coordinator dispatches a session, it passes only a goal string.
+The agent spends its first 2-3 turns re-establishing context (re-reading PR diff,
+starting cold with no memory of prior reviews). Before spawning each session, the
+coordinator should assemble a context bundle (git diff summary + prior session notes)
+and inject it into the system prompt via the existing `trigger.context` map.
+
+---
+
+## Acceptance Criteria
+
+1. `npm run build` compiles clean with zero TypeScript errors
+2. `npx vitest run tests/unit/context-assembly.test.ts` -- all 5 tests pass
+3. `npx vitest run` -- no regressions in full test suite
+4. New module `src/context-assembly/` exists with 4 files
+5. `CoordinatorDeps.contextAssembler?` optional field present
+6. `CoordinatorDeps.spawnSession` accepts optional 4th `context?` arg
+7. `buildSystemPrompt()` injects `## Prior Context` section when `assembledContextSummary` present in trigger context
+8. `src/cli-worktrain.ts` wires `contextAssembler` and forwards `context` through HTTP body
+
+---
+
+## Non-Goals
+
+1. No URL fetching from PR description bodies (v2)
+2. No full git diff content -- `--stat` output only
+3. No changes to `src/mcp/` or `src/v2/durable-core/`
+4. No knowledge graph source (`ts-morph` stays in devDependencies)
+5. No per-coordinator custom renderers
+6. No context window budget trimming
+7. No context assembly in `TriggerRouter.route()`
+8. No HTTP endpoint schema changes
+9. No workspace-scoped session filtering (v1 returns global sessions)
+
+---
+
+## Philosophy-Driven Constraints
+
+- All interface fields `readonly` (immutability by default)
+- `Result<T,E>` (`kind: 'ok'|'err'`) for all new code; bridge from neverthrow at `infra.ts` boundary
+- Factory function `createContextAssembler()`, not a class
+- `renderContextBundle()` is pure (no I/O)
+- `ContextAssemblerDeps` interface contains all I/O; core has zero direct imports of `fs`/`execFile`
+- Tests: fake deps, no `vi.mock()`, vitest `describe/it/expect`
+- Import paths use `.js` extension (TypeScript ESM)
+- JSDoc `WHY` comments on non-obvious decisions
+
+---
+
+## Invariants
+
+1. **Partial failure**: `gitDiff` and `priorSessionNotes` fail independently; session always starts
+2. **Zero agent turn cost**: Context injected in system prompt before turn 1
+3. **Coordinator-controlled opt-in**: Only coordinators calling `assembler.assemble()` get enriched context
+4. **Prior notes recency limit**: At most 3 prior sessions
+5. **Git summary size**: File names and change counts only (no full diff)
+6. **No engine/MCP changes**: `src/v2/durable-core/` and `src/mcp/` untouched
+7. **Optional contextAssembler**: Backward-compatible -- all existing `CoordinatorDeps` fakes work
+
+---
+
+## Selected Approach
+
+Use 4 new files in `src/context-assembly/` + 3 modified files, exactly as specified in
+the pitch. `infra.ts` uses a direct `SessionEventLogReadonlyStorePortV2` adapter
+(implementing only `load()` and `loadValidatedPrefix()` via `fs.promises` + existing Zod
+schemas) instead of `LocalSessionEventLogStoreV2`. This eliminates the need for
+`FileSystemPortV2` and `Sha256PortV2` shims.
+
+**Runner-up**: Use `LocalSessionEventLogStoreV2` with write stubs. Rejected: write stubs
+partially violate the interface contract even though they're provably unreachable.
+
+---
+
+## Vertical Slices
+
+### Slice 1: New module `src/context-assembly/` (4 files)
+
+**Files to create**:
+- `src/context-assembly/types.ts` (~60 LOC) - AssemblyTask, SessionNote, ContextBundle, RenderOpts, ContextAssembler interface
+- `src/context-assembly/deps.ts` (~35 LOC) - ContextAssemblerDeps interface (execGit, execGh, listRecentSessions, nowIso)
+- `src/context-assembly/index.ts` (~80 LOC) - createContextAssembler(), renderContextBundle(), private helpers
+- `src/context-assembly/infra.ts` (~80 LOC) - createListRecentSessions() adapter
+
+**Done when**: All 4 files compile clean in isolation
+
+**Key implementation details**:
+- `types.ts`: import `Result` from `'../runtime/result.js'`
+- `index.ts`: factory function `createContextAssembler(deps)`, pure `renderContextBundle(bundle, _opts?)`
+- `infra.ts`: `SessionEventLogReadonlyStorePortV2` adapter using `fs.promises.readFile` + `ManifestRecordV1Schema` + `DomainEventV1Schema`; `LocalDataDirV2(process.env)` + `LocalDirectoryListingV2(directoryListingOpsAdapter)` wired into `LocalSessionSummaryProviderV2`
+- `infra.ts`: `_workspacePath` named with leading underscore (intentional non-use in v1)
+- Bridge: `const result = await provider.loadHealthySummaries(); if (result.isErr()) return err(...);`
+
+### Slice 2: Modify `src/coordinators/pr-review.ts`
+
+**Changes**:
+1. Add `contextAssembler?: ContextAssembler` field to `CoordinatorDeps` (after `spawnSession`, before `awaitSessions`)
+2. Extend `spawnSession` signature: add optional 4th arg `context?: Readonly<Record<string, unknown>>`
+3. Add context assembly block before `spawnSession` call in `runPrReviewCoordinator` for-loop
+4. Forward same `spawnContext` to re-review spawn (~line 1265)
+5. Do NOT add context assembly to fix-agent spawn
+
+**Done when**: File compiles clean; existing tests still pass
+
+### Slice 3: Modify `src/daemon/workflow-runner.ts`
+
+**Change**: Insert 6-line block in `buildSystemPrompt()` BEFORE the `referenceUrls` block
+
+**Done when**: File compiles clean; `buildSystemPrompt` tests (if any) still pass
+
+### Slice 4: Modify `src/cli-worktrain.ts`
+
+**Changes**:
+1. Add imports for `createContextAssembler` and `createListRecentSessions`
+2. Extend `spawnSession` lambda to accept optional 4th `context?` arg and include it in JSON body
+3. Add `contextAssembler: createContextAssembler({...})` to deps object (after `spawnSession`)
+4. Wire `execGit`, `execGh` inline using `promisify(execFile)`
+
+**Done when**: File compiles clean
+
+### Slice 5: Tests
+
+**File**: `tests/unit/context-assembly.test.ts`
+
+**Tests**:
+1. `assemble()` with both sources succeeding -- returns bundle with `kind: 'ok'` on both fields
+2. `assemble()` with gitSummary failing -- priorNotes still returns `ok([])`; gitDiff returns `kind: 'err'`
+3. `renderBundle()` produces correct markdown sections (headings, git diff in code block)
+4. `renderBundle()` with all-failed bundle -- returns empty string
+5. `listRecentSessions` with no sessions directory -- returns `ok([])`
+
+**Done when**: All 5 tests pass with `npx vitest run tests/unit/context-assembly.test.ts`
+
+---
+
+## Test Design
+
+### Fake deps for context assembler
+
+```typescript
+function makeFakeDeps(overrides: Partial<ContextAssemblerDeps> = {}): ContextAssemblerDeps {
+  return {
+    execGit: async () => ({ kind: 'ok', value: 'src/foo.ts | 5 ++\n' }),
+    execGh: async () => ({ kind: 'err', error: 'gh not available' }),
+    listRecentSessions: async () => ({ kind: 'ok', value: [] }),
+    nowIso: () => '2026-04-19T00:00:00.000Z',
+    ...overrides,
+  };
+}
+```
+
+### Test for no sessions directory
+
+Uses a real temp directory (with no sessions subdirectory) to test the graceful `ok([])` return.
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| `infra.ts` SessionEventLogReadonlyStorePortV2 adapter has parsing bugs | Low | Medium | Tests verify behavior with fake data; manifest format well-documented |
+| `spawnSession` 4th arg breaks existing tests | Very Low | Low | Optional arg; TypeScript enforces backward compat |
+| `contextAssembler` not optional breaks existing tests | Very Low | Low | `?` makes it optional; existing fakes compile without it |
+| Full test suite regressions | Very Low | High | Run `npx vitest run` before PR |
+
+---
+
+## PR Packaging Strategy
+
+**Single PR**: `feat/context-assembly-layer`
+
+All 7 file changes ship together. They form a single coherent feature -- the 4 new
+files are meaningless without the 3 modifications, and the modifications are safe
+with or without the new files.
+
+**Commit message**: `feat(coordinator): add context assembly layer -- git summary and prior session notes`
+
+---
+
+## Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| Slice 1 (types) | Make illegal states unrepresentable (discriminated union) | Satisfied |
+| Slice 1 (index) | Functional/declarative (factory fn, pure render) | Satisfied |
+| Slice 1 (infra) | DI for boundaries (all I/O behind interface) | Satisfied |
+| Slice 1 (infra) | Architectural fixes over patches (reuse projection code) | Satisfied |
+| Slice 2 (coordinator) | Errors are data (Result<T,E>) | Satisfied |
+| Slice 2 (coordinator) | Backward compatibility via optional fields | Satisfied |
+| Slice 3 (workflow-runner) | Validate at boundaries (type check before inject) | Satisfied |
+| Slice 5 (tests) | Prefer fakes over mocks | Satisfied |
+
+---
+
+## Open Questions (Residual)
+
+None. All questions were resolved during design review:
+1. `ManifestRecordV1Schema` and `DomainEventV1Schema` -- confirmed exported
+2. `asSessionId` -- confirmed exported from ids/index.ts
+3. Re-review spawn context -- confirmed: forward same `spawnContext` from outer scope
+
+**`unresolvedUnknownCount`**: 0
+**`planConfidenceBand`**: High

package/docs/design/context-assembly-review-findings.md

@@ -0,0 +1,112 @@
+# Design Review Findings: Context Assembly Layer v1
+
+*Generated during coding-task-workflow-agentic session | 2026-04-19*
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Condition for Failure |
+|---|---|---|
+| FileSystemPortV2 write stubs | RESOLVED -- switching to direct SessionEventLogReadonlyStorePortV2 adapter | N/A |
+| Inline DI wiring in infra.ts | Acceptable -- explicitly endorsed by pitch R1 mitigation | N/A |
+| Global session list (no workspace filtering) | Accepted -- v2 improvement documented in pitch | Multiple simultaneous workspaces with unrelated sessions |
+| Promise.all partial failure | Adequately handled -- each source returns Result, try/catch in infra | N/A |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Covered By | Residual Risk |
+|---|---|---|
+| Write stubs called | Outer try/catch in createListRecentSessions | Low -- FM1 resolved by switching adapter |
+| Git commands fail | execGit/execGh return err(), fallback chain | None |
+| Sessions dir missing | LocalDirectoryListingV2 returns [] for FS_NOT_FOUND | None |
+| Corrupt session data | LocalSessionSummaryProviderV2 graceful skip | None |
+| spawnSession backward compat | Optional 4th arg | None |
+| contextAssembler not provided | Optional field + if-guard in coordinator | None |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Runner-up** (Candidate B: raw fs.promises) has no elements worth borrowing into the
+selected design.
+
+**Simpler variant identified**: Use a direct `SessionEventLogReadonlyStorePortV2`
+adapter in `infra.ts` instead of `LocalSessionEventLogStoreV2`. This eliminates all
+`FileSystemPortV2` and `Sha256PortV2` stubs while still reusing `LocalSessionSummaryProviderV2`
+and the full projection pipeline. The adapter implements only `load()` and
+`loadValidatedPrefix()` using `fs.promises` + existing Zod schemas (`ManifestRecordV1Schema`,
+`DomainEventV1Schema`). Approximately 40 lines. This is strictly cleaner.
+
+**Recommendation**: Use the simpler `SessionEventLogReadonlyStorePortV2` adapter approach.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Alignment |
+|---|---|
+| Errors are data | STRONG -- Result<T,E> throughout |
+| DI for boundaries | STRONG -- ContextAssemblerDeps, inline construction accepted for separate process |
+| Prefer fakes over mocks | STRONG -- test spec uses fake deps |
+| Immutability by default | STRONG -- readonly everywhere |
+| Make illegal states unrepresentable | STRONG -- AssemblyTask discriminated union |
+| Functional/declarative | STRONG -- factory functions, pure renderContextBundle |
+| YAGNI | MILD TENSION -- empty RenderOpts interface (accepted, documented) |
+| Architectural fixes over patches | STRONG with adapter approach |
+
+---
+
+## Findings
+
+### YELLOW: Empty RenderOpts interface
+
+**Severity**: Yellow (minor)
+
+**Finding**: `RenderOpts` is an empty interface in v1. TypeScript `{}` and `interface RenderOpts {}` are equivalent. The empty interface is only useful as a future extension point.
+
+**Assessment**: Acceptable -- the pitch explicitly documents this as an intentional v1 placeholder. No action needed.
+
+### YELLOW: Global session filtering (no workspace scope)
+
+**Severity**: Yellow (minor, known)
+
+**Finding**: `listRecentSessions` returns the 3 most recent sessions globally, not scoped to the coordinator's workspace path. For users running multiple workspaces, prior notes from unrelated workspaces may appear.
+
+**Assessment**: Acceptable for v1 -- pitch explicitly documents this as a known limitation. The `_workspacePath` parameter should be named with a leading `_` to signal intentional non-use.
+
+### GREEN: All other design elements
+
+Tradeoffs, failure modes, and philosophy alignment are all sound. No RED or ORANGE findings.
+
+---
+
+## Recommended Revisions
+
+1. **Use direct `SessionEventLogReadonlyStorePortV2` adapter** in `infra.ts` instead of
+   `LocalSessionEventLogStoreV2`. Eliminates all write stubs. Implements `load()` using
+   `fs.promises.readFile` + `ManifestRecordV1Schema` + `DomainEventV1Schema` parsing.
+   Approximately 40 lines.
+
+2. **Name unused parameter** `_workspacePath` in `createListRecentSessions` to signal
+   intentional non-use.
+
+---
+
+## Residual Concerns
+
+1. **Import path for Zod schemas**: `ManifestRecordV1Schema` and `DomainEventV1Schema`
+   must be importable from `src/v2/durable-core/schemas/session/index.ts`. Verify before
+   implementing that these schemas are exported.
+
+2. **`asSessionId` usage**: The `SessionEventLogReadonlyStorePortV2.load()` adapter
+   receives a `SessionId` branded type. When reading session directories and mapping
+   entry names to `SessionId`, the `asSessionId` import from
+   `src/v2/durable-core/ids/index.ts` must be used correctly.
+
+3. **Neverthrow ResultAsync wrapping**: The adapter must return neverthrow `ResultAsync`
+   objects (using `okAsync`/`errAsync` from neverthrow), not the custom `Result` type.
+   The bridge from neverthrow to custom Result happens in the `createListRecentSessions`
+   function via `const result = await resultAsync; if (result.isErr()) return err(...)`.

package/docs/ideas/backlog.md

@@ -6183,3 +6183,67 @@ The daemon tool approach is only better for ad-hoc mid-session queries the agent
 ### Anti-pattern to avoid
 
 Adding knowledge graph calls directly into `pr-review.ts` or any other coordinator script. That immediately creates the god class we're trying to avoid and couples the orchestration layer to a specific context source.
+
+---
+
+## Scheduled tasks (Apr 19, 2026)
+
+**The idea:** WorkTrain runs tasks on a schedule -- not triggered by an external event, but by time. "Every Monday morning, run the code health scan." "Every night at 2am, check for new GitHub issues and triage them." "First of the month, run the production readiness audit."
+
+### Why this matters for the autonomous pipeline vision
+
+The full autonomous pipeline (prioritize → discover → shape → implement → test → PR → review → fix → merge) needs a way to start without a human pushing a button. Scheduled tasks are the trigger layer for proactive, time-driven work. Without them, WorkTrain is purely reactive -- it only acts when a webhook fires or a human dispatches it.
+
+### What exists today
+
+The trigger system (`src/trigger/`) supports `generic` (webhook) and polling providers (`gitlab_poll`, `github_issues_poll`, `github_prs_poll`). There is no native cron/schedule provider. The workaround today is OS crontab calling `curl` to fire a webhook.
+
+### What to build
+
+A `schedule` provider in triggers.yml:
+
+```yaml
+triggers:
+  - id: weekly-code-health
+    provider: schedule
+    cron: "0 9 * * 1"          # every Monday at 9am
+    workflowId: architecture-scalability-audit
+    workspacePath: /path/to/repo
+    goal: "Run weekly code health scan -- identify coupling violations, complexity hotspots, and performance anti-patterns introduced this week"
+
+  - id: nightly-issue-triage
+    provider: schedule
+    cron: "0 2 * * *"          # every night at 2am
+    workflowId: wr.discovery
+    workspacePath: /path/to/repo
+    goal: "Review open GitHub issues created in the last 24 hours and triage them: classify severity, identify duplicates, suggest which to prioritize"
+
+  - id: backlog-next-task
+    provider: schedule
+    cron: "0 8 * * 1-5"        # weekday mornings at 8am
+    workflowId: coding-task-workflow-agentic
+    workspacePath: /path/to/repo
+    goal: "Pick the highest-priority unstarted task from docs/ideas/backlog.md and implement it"
+```
+
+### Key design decisions
+
+- **Cron syntax**: standard 5-field cron (`min hour dom month dow`). Parsed by `node-cron` or equivalent -- already a pattern in the codebase (backlog mentions cron).
+- **Timezone**: configurable per trigger, defaults to system timezone. Important for "weekday morning" schedules that need to fire in the user's timezone.
+- **Missed runs**: if the daemon was down when a scheduled run should have fired, it does NOT catch up on missed runs by default. "Run at 9am Monday" means "run the next time 9am Monday arrives." Optional `catchUp: true` flag for cases where missing a run should be recovered.
+- **Overlap prevention**: if a scheduled run fires while the previous run is still active, it should be skipped (not queued). A `coding-task` that takes 2 hours should not spawn a second instance at the next cron tick.
+- **Manual trigger**: `worktrain run schedule <trigger-id>` to fire a scheduled trigger immediately without waiting for the cron time. Useful for testing.
+
+### Integration with the autonomous pipeline
+
+Scheduled tasks are the entry point for fully autonomous work:
+- "Every weekday morning, pick the next backlog item and run the full pipeline" -- this is how WorkTrain improves WorkTrain without any human input.
+- "Every time a PR is opened, run the MR review pipeline" -- this is github_prs_poll, already exists.
+- "Every Monday, run the architecture audit and file GitHub issues for findings" -- new scheduled capability.
+
+### Implementation notes
+
+- The `PollingScheduler` in `src/trigger/polling-scheduler.ts` already runs time-based loops for GitLab/GitHub polling. The schedule provider would be a similar loop, using cron expression matching instead of API polling.
+- `node-cron` or `croner` npm package for cron expression parsing and next-fire-time calculation. Lightweight, no daemon dependencies.
+- Scheduled triggers have no webhook payload -- `contextMapping` is empty, `goalTemplate` uses only static text or env vars.
+- The schedule state (last-fired-at per trigger) persists to `~/.workrail/schedule-state.json` so the daemon can detect missed runs on restart.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.41.0",
+  "version": "3.42.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {