@exaudeus/workrail 3.41.0 → 3.43.0

package/docs/design/context-assembly-design-candidates.md

@@ -0,0 +1,199 @@
+# Design Candidates: Context Assembly Layer v1
+
+*Generated during coding-task-workflow-agentic session | 2026-04-19*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Clean DI vs. pragmatic inline construction**: `LocalSessionSummaryProviderV2` is
+   wired through the full DI container in the MCP server process. The coordinator runs
+   as a CLI in a separate process. We cannot share the DI container. The coordinator
+   composition root (`src/cli-worktrain.ts`) must construct the provider inline.
+
+2. **Neverthrow ResultAsync vs. custom Result**: Storage layer uses neverthrow. New
+   `src/context-assembly/` uses the repo's custom `Result<T,E>` (`kind: 'ok'|'err'`).
+   The bridge must happen at the `infra.ts` boundary.
+
+3. **Partial failure semantics**: Each source (gitDiff, priorNotes) must fail
+   independently without aborting context assembly. `Promise.all()` is safe because
+   each source always resolves to a `Result` (never throws) when implemented correctly.
+
+4. **Backward compatibility vs. interface evolution**: Adding `contextAssembler?` as
+   optional to `CoordinatorDeps` and optional 4th arg to `spawnSession` keeps all
+   existing tests and callers working without modification.
+
+### Likely Seam
+
+The real seam is `CoordinatorDeps.spawnSession`. The coordinator calls this to dispatch
+a session. Context bundle assembly belongs immediately before this call.
+
+### What Makes This Hard
+
+- `LocalSessionEventLogStoreV2` requires `FileSystemPortV2` (a composite of 5 sub-ports
+  including write/fd ops). But `load()` only calls `readFileUtf8`. All write methods
+  can be stubs for read-only use, but this is a partial lie against the interface contract.
+- `LocalDirectoryListingV2` takes `DirectoryListingOpsPortV2` (separate, simpler) --
+  NOT the full `FileSystemPortV2`. These are separate ports.
+- Two Result type systems (neverthrow vs custom) must coexist without leaking across
+  the `infra.ts` boundary.
+- `Sha256PortV2` is injected into `LocalSessionEventLogStoreV2` but only called in
+  `append()`, not `load()`. Safe to stub.
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` (system-wide agent instructions):
+
+- **Errors are data**: Use `Result<T,E>` values. No throwing for expected failures.
+- **DI for boundaries**: Inject I/O effects; keep core logic testable.
+- **Prefer fakes over mocks**: Tests use realistic substitutes (no `vi.mock()`).
+- **YAGNI with discipline**: No speculative abstractions.
+- **Architectural fixes over patches**: Reuse canonical parsing logic.
+- **Immutability by default**: `readonly` on all fields.
+
+**Potential conflict**: Creating write stubs on `FileSystemPortV2` is pragmatic but
+technically lies about the contract. The pitch (R1 mitigation) explicitly endorses this
+approach. Acceptable given the inline-construction pattern is already acknowledged as
+a special case.
+
+---
+
+## Impact Surface
+
+- `src/coordinators/pr-review.ts`: `CoordinatorDeps.spawnSession` (add optional 4th arg),
+  `contextAssembler?` optional field. Backward-compatible.
+- `src/daemon/workflow-runner.ts`: `buildSystemPrompt()` reads `trigger.context['assembledContextSummary']`.
+  No signature change needed -- `trigger.context` already typed as `Readonly<Record<string,unknown>>`.
+- `src/cli-worktrain.ts`: `spawnSession` impl forwards 4th arg; `contextAssembler` wired.
+- All existing tests that construct `CoordinatorDeps` fakes: safe (optional fields).
+- No changes to `src/mcp/` or `src/v2/durable-core/`.
+
+---
+
+## Candidates
+
+### Candidate A: Real local infra classes with minimal read-only shims (SELECTED)
+
+**Summary**: Construct `LocalDataDirV2`, `LocalDirectoryListingV2`, and
+`LocalSessionEventLogStoreV2` directly inside `infra.ts`. Create inline adapters:
+- `DirectoryListingOpsPortV2`: wraps `fs.promises.readdir` + `stat` with `okAsync/errAsync`
+- `FileSystemPortV2`: only `readFileUtf8` is real; write/fd methods throw 'context-assembly: write ops not supported'
+- `Sha256PortV2`: stub that throws (never called during `load()`)
+
+**Tensions resolved**: R1 (DI wiring scope). Uses battle-tested session loading and
+projection code. Neverthrow/custom Result bridge stays at `infra.ts` boundary only.
+
+**Tensions accepted**: Write stubs on `FileSystemPortV2` are a partial lie.
+
+**Boundary solved at**: `src/context-assembly/infra.ts` -- coordinator composition root.
+
+**Why this boundary is best-fit**: The coordinator is already a composition root
+(`src/cli-worktrain.ts` wires all real deps). `infra.ts` is a thin adapter layer that
+belongs exactly here.
+
+**Failure mode**: If `LocalSessionEventLogStoreV2.load()` ever internally calls a write
+method (unlikely but possible in future refactors), `infra.ts` would throw at runtime
+rather than returning `err()`. This would be caught immediately by tests.
+
+**Repo-pattern relationship**: Follows existing local infra pattern exactly.
+`LocalDataDirV2`, `LocalDirectoryListingV2`, `LocalSessionEventLogStoreV2` are already
+the canonical local implementations.
+
+**Gains**: Reuses battle-tested store loading and projection code. No risk of format
+divergence if session file structure changes.
+
+**Losses**: Write stubs feel slightly dishonest. Minor complexity in `infra.ts`.
+
+**Scope judgment**: Best-fit. Stays within `src/context-assembly/` with no v2 changes.
+
+**Philosophy fit**: Honors DI for boundaries (composition root pattern), errors-as-data
+(Result bridge), architectural fixes over patches (reuses canonical code). Minor
+tension with YAGNI (write stubs) and interface honesty.
+
+---
+
+### Candidate B: Read session files directly with fs.promises
+
+**Summary**: Skip the port hierarchy. Read `manifest.jsonl` and `events/*.jsonl` directly
+using `fs.promises.readFile`. Parse manually or reuse just the schema validators.
+
+**Tensions resolved**: R1 completely -- no DI wiring at all.
+
+**Tensions accepted**: Duplicates session reading logic. Any change to session file
+format requires updates in two places.
+
+**Failure mode**: Silent breakage if session file format changes.
+
+**Repo-pattern relationship**: Departs from established pattern (re-implements existing logic).
+
+**Scope judgment**: Too narrow -- creates a fragile parallel implementation.
+
+**Philosophy fit**: Conflicts with 'architectural fixes over patches'.
+
+---
+
+### Candidate C: Add createLocalSessionSummaryProvider() factory to v2 module
+
+**Summary**: Add a `createLocalSessionSummaryProvider()` factory function to
+`src/v2/infra/local/session-summary-provider/index.ts` that wires real deps and
+returns a `SessionSummaryProviderPortV2`. Import and call from `infra.ts`.
+
+**Tensions resolved**: Cleanest DI wiring.
+
+**Tensions accepted**: Modifies an existing v2 infra module.
+
+**Failure mode**: Entangles CLI-coordinator concerns into the storage layer.
+
+**Scope judgment**: Slightly too broad -- modifies v2 module with no functional benefit
+over Candidate A.
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate A**
+
+All candidates agree on the high-level approach (4 new files, 3 modified files, exact
+pitch interfaces). The only real design decision is `infra.ts` implementation.
+
+Candidate A wins because:
+1. It reuses battle-tested code for session reading and health projection
+2. It stays within `src/context-assembly/` -- no v2 module changes
+3. The write stubs are safe: `load()` provably does not call write methods
+4. The pitch explicitly endorses this approach as R1 mitigation
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument**: The write stubs on `FileSystemPortV2` create a silent
+contract violation. If a future `load()` implementation adds a write call internally,
+the error would surface at runtime (throw) rather than compile-time.
+
+**Narrower option that lost**: Candidate B (raw fs.promises). Lost because it duplicates
+canonical parsing logic and diverges from existing patterns.
+
+**Broader option and evidence required**: Candidate C would be justified if multiple
+other CLI commands needed access to session summaries -- adding a factory to the v2
+module would be worth the scope increase. No evidence of this need in v1.
+
+**Assumption that would invalidate this design**: If `LocalSessionEventLogStoreV2.load()`
+internally calls any of the stubbed write methods (currently provably false by code
+inspection of `loadImpl()`, `loadValidatedPrefixImpl()`, `readManifestOrEmpty()`).
+
+---
+
+## Open Questions for Main Agent
+
+1. Verify: does `Sha256PortV2` have a simple interface that can be satisfied with a
+   1-line `node:crypto` implementation? (If so, use real impl rather than throw stub.)
+2. Verify: does the `FileSystemPortV2` shim need anything beyond `readFileUtf8` for
+   the `load()` path? (Current analysis: no -- `readManifestOrEmpty` and segment loading
+   both use `readFileUtf8` only.)
+3. The re-review spawn (line ~1265 in pr-review.ts) should forward `spawnContext` from
+   the outer scope per the pitch. Confirm this is the correct approach (vs. reassembling
+   context for re-reviews).

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-layer-design-review.md

@@ -0,0 +1,110 @@
+# Context Assembly Layer -- Design Review Findings
+
+**Reviewing:** Candidate B-hybrid (ContextAssembler service + typed assembledContext field on WorkflowTrigger)
+**Date:** 2026-04-19
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Acceptable? | What would make it unacceptable |
+|---|---|---|
+| Context serialized to string for agent consumption | YES (agents consume natural language) | If coordinators need to inspect bundle content for dispatch decisions -- not a planned use case |
+| 150 LOC new module vs. 50 LOC inline | YES (justified by multi-coordinator reuse) | If second coordinator never arrives within 6 months |
+| buildSystemPrompt() change (3 lines) | YES (daemon-only, not engine) | If buildSystemPrompt() is treated as a versioned public API -- it is not |
+| workflow-runner.ts imports ContextBundle | YES (coupling direction is correct) | If ContextBundle grows to include I/O -- it must remain a pure value type |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Design handling | Missing mitigation | Risk |
+|---|---|---|---|
+| renderContextBundle() accumulates coordinator-specific formatting | Not addressed in v1 | Add `RenderOpts` interface with optional section labels | LOW |
+| Agent ignores assembled context (attention threshold) | Section appended at end of system prompt | Test with prior session notes first; add reference in step prompts | **MEDIUM -- existential** |
+| gitDiff source fails silently | Per-field Result<T,string> -- fails gracefully | Add WARN log in coordinator when source fails | LOW |
+| Second coordinator wants different rendering | Not addressed | RenderOpts mitigation from FM1 | LOW (v1) |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate A strength incorporated:** Typed `assembledContext?: ContextBundle` field on `WorkflowTrigger` is cleaner than string-in-context-map. This is the B-hybrid improvement over pure Candidate B.
+
+**Simpler alternative (prior session notes only):** Would satisfy 3/5 acceptance criteria but NOT criterion 4 (pr-review.ts shrinks by 100 LOC). Not sufficient.
+
+**Hybrid adopted:** B + typed field from A. This is the recommended design.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Dependency injection for boundaries | SATISFIED |
+| Errors are data | SATISFIED |
+| Immutability by default | SATISFIED |
+| Make illegal states unrepresentable | SATISFIED (discriminated union) |
+| Compose with small, pure functions | SATISFIED |
+| Validate at boundaries | SATISFIED |
+| YAGNI | ACCEPTABLE TENSION (coding_task kind is speculative but planned) |
+| Explicit domain types | MINOR TENSION -- define SessionNote as a proper interface, not string |
+
+---
+
+## Findings
+
+### RED (blocking)
+
+None.
+
+### ORANGE (should be addressed before implementation)
+
+**O1: Assembled context visibility to agent is unverified**
+
+The system prompt injection in `buildSystemPrompt()` adds the assembled context section AFTER the base system prompt and workspace context. In a dense system prompt (32KB CLAUDE.md + soul file), the assembled context may receive insufficient agent attention. This is the existential risk for the design.
+
+**Required action before implementation:** Run one session with only `priorSessionNotes` injected. Verify the agent cites or references the prior session notes in its first turn. If it does not, investigate prompt positioning.
+
+### YELLOW (note before implementation)
+
+**Y1: SessionNote is not defined as a domain type**
+
+`ContextAssemblerDeps.listRecentSessions` returns `Result<readonly SessionNote[], string>`. `SessionNote` must be defined as a proper `readonly` interface:
+```typescript
+export interface SessionNote {
+  readonly sessionId: string;
+  readonly recapSnippet: string;
+  readonly sessionTitle: string | null;
+  readonly gitBranch: string | null;
+  readonly lastModifiedMs: number;
+}
+```
+This maps directly to `HealthySessionSummary` fields in `LocalSessionSummaryProviderV2`.
+
+**Y2: renderContextBundle needs RenderOpts stub**
+
+Even in v1, add an optional `RenderOpts` parameter to `renderContextBundle()` (empty interface for now). This preserves the extension point without implementing it.
+
+**Y3: WARN logging for source failures**
+
+When `bundle.gitDiff.kind === 'err'`, the coordinator should log at WARN level. Add this to the coordinator refactor spec.
+
+---
+
+## Recommended Revisions
+
+1. **Keep B-hybrid:** ContextAssembler service + typed `assembledContext?: ContextBundle` field on `WorkflowTrigger`. Do NOT use string-in-context-map.
+2. **Add O1 mitigation:** Pilot test with `priorSessionNotes` source only before wiring all three sources.
+3. **Define `SessionNote` interface** in `src/context-assembly/types.ts` before implementation.
+4. **Add `RenderOpts` stub** to `renderContextBundle()` signature.
+5. **Add WARN logs** in coordinator when source fails.
+6. **Position assembled context section** in `buildSystemPrompt()` BEFORE the referenceUrls section (higher attention) -- small positioning change.
+
+---
+
+## Residual Concerns
+
+1. **Second coordinator timeline is unscheduled.** The multi-coordinator reuse argument for Candidate B over A depends on a second coordinator being built. If this is more than 6 months away, Candidate A is the pragmatic choice.
+2. **`LocalSessionSummaryProviderV2` wiring.** The session summary provider is currently wired only to the MCP server/console path. Using it from `ContextAssemblerDeps` requires either re-exporting its ports or constructing a lightweight adapter. Scope should be confirmed during shaping.
+3. **git diff strategy.** `git diff HEAD~1 --stat` gives a file list; `git diff HEAD~1` gives full diff content. Full diff for large PRs could be 50-100KB. The v1 strategy should be `--stat` (file names and change counts only) -- this fits in the assembled context without hitting budget limits.