@exaudeus/workrail 3.42.0 → 3.43.0

package/dist/daemon/workflow-runner.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DAEMON_SIGNALS_DIR = exports.DAEMON_SOUL_TEMPLATE = exports.DAEMON_SOUL_DEFAULT = exports.DAEMON_SESSIONS_DIR = void 0;
+exports.DAEMON_SIGNALS_DIR = exports.DAEMON_SOUL_TEMPLATE = exports.DAEMON_SOUL_DEFAULT = exports.WORKTREES_DIR = exports.DAEMON_SESSIONS_DIR = void 0;
 exports.readDaemonSessionState = readDaemonSessionState;
 exports.readAllDaemonSessions = readAllDaemonSessions;
 exports.runStartupRecovery = runStartupRecovery;
@@ -83,7 +83,9 @@ function withWorkrailSession(sid) {
 }
 exports.DAEMON_SESSIONS_DIR = path.join(os.homedir(), '.workrail', 'daemon-sessions');
 const MAX_ORPHAN_AGE_MS = 2 * 60 * 60 * 1000;
+const MAX_WORKTREE_ORPHAN_AGE_MS = 24 * 60 * 60 * 1000;
 const WORKRAIL_DIR = path.join(os.homedir(), '.workrail');
+exports.WORKTREES_DIR = path.join(os.homedir(), '.workrail', 'worktrees');
 const WORKSPACE_CONTEXT_MAX_BYTES = 32 * 1024;
 const MAX_ASSEMBLED_CONTEXT_BYTES = 8192;
 const WORKSPACE_CONTEXT_CANDIDATE_PATHS = [
@@ -96,10 +98,10 @@ const soul_template_js_1 = require("./soul-template.js");
 var soul_template_js_2 = require("./soul-template.js");
 Object.defineProperty(exports, "DAEMON_SOUL_DEFAULT", { enumerable: true, get: function () { return soul_template_js_2.DAEMON_SOUL_DEFAULT; } });
 Object.defineProperty(exports, "DAEMON_SOUL_TEMPLATE", { enumerable: true, get: function () { return soul_template_js_2.DAEMON_SOUL_TEMPLATE; } });
-async function persistTokens(sessionId, continueToken, checkpointToken) {
+async function persistTokens(sessionId, continueToken, checkpointToken, worktreePath) {
     await fs.mkdir(exports.DAEMON_SESSIONS_DIR, { recursive: true });
     const sessionPath = path.join(exports.DAEMON_SESSIONS_DIR, `${sessionId}.json`);
-    const state = JSON.stringify({ continueToken, checkpointToken, ts: Date.now() }, null, 2);
+    const state = JSON.stringify({ continueToken, checkpointToken, ts: Date.now(), ...(worktreePath !== undefined ? { worktreePath } : {}) }, null, 2);
     const tmp = `${sessionPath}.tmp`;
     await fs.writeFile(tmp, state, 'utf8');
     await fs.rename(tmp, sessionPath);
@@ -145,6 +147,7 @@ async function readAllDaemonSessions(sessionsDir = exports.DAEMON_SESSIONS_DIR)
                 continueToken: parsed.continueToken,
                 checkpointToken: typeof parsed.checkpointToken === 'string' ? parsed.checkpointToken : null,
                 ts: parsed.ts,
+                ...(typeof parsed.worktreePath === 'string' ? { worktreePath: parsed.worktreePath } : {}),
             });
         }
         catch (err) {
@@ -153,7 +156,7 @@ async function readAllDaemonSessions(sessionsDir = exports.DAEMON_SESSIONS_DIR)
     }
     return sessions;
 }
-async function runStartupRecovery(sessionsDir = exports.DAEMON_SESSIONS_DIR) {
+async function runStartupRecovery(sessionsDir = exports.DAEMON_SESSIONS_DIR, execFn = execFileAsync) {
     const sessions = await readAllDaemonSessions(sessionsDir);
     if (sessions.length === 0) {
         await clearStrayTmpFiles(sessionsDir);
@@ -168,6 +171,22 @@ async function runStartupRecovery(sessionsDir = exports.DAEMON_SESSIONS_DIR) {
         const ageSec = Math.round(ageMs / 1000);
         const label = isStale ? 'stale orphaned session' : 'orphaned session';
         console.log(`[WorkflowRunner] Clearing ${label}: sessionId=${session.sessionId} age=${ageSec}s`);
+        if (session.worktreePath && ageMs > MAX_WORKTREE_ORPHAN_AGE_MS) {
+            console.log(`[WorkflowRunner] Removing orphan worktree: sessionId=${session.sessionId} worktreePath=${session.worktreePath}`);
+            try {
+                await execFn('git', ['worktree', 'remove', '--force', session.worktreePath]);
+                console.log(`[WorkflowRunner] Removed orphan worktree: ${session.worktreePath}`);
+            }
+            catch (err) {
+                console.warn(`[WorkflowRunner] Could not remove orphan worktree ${session.worktreePath}: ` +
+                    `${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else if (session.worktreePath && ageMs <= MAX_WORKTREE_ORPHAN_AGE_MS) {
+            const ageHours = (ageMs / (60 * 60 * 1000)).toFixed(1);
+            console.log(`[WorkflowRunner] Keeping recent orphan worktree: sessionId=${session.sessionId} ` +
+                `age=${ageHours}h (threshold=24h) worktreePath=${session.worktreePath}`);
+        }
         try {
             await fs.unlink(path.join(sessionsDir, `${session.sessionId}.json`));
             cleared++;
@@ -1430,12 +1449,53 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
     if (startContinueToken) {
         await persistTokens(sessionId, startContinueToken, startCheckpointToken);
     }
+    let sessionWorkspacePath = trigger.workspacePath;
+    let sessionWorktreePath;
+    if (trigger.branchStrategy === 'worktree') {
+        const branchPrefix = trigger.branchPrefix ?? 'worktrain/';
+        const baseBranch = trigger.baseBranch ?? 'main';
+        sessionWorkspacePath = path.join(exports.WORKTREES_DIR, sessionId);
+        sessionWorktreePath = sessionWorkspacePath;
+        try {
+            await fs.mkdir(exports.WORKTREES_DIR, { recursive: true });
+            await execFileAsync('git', ['-C', trigger.workspacePath, 'fetch', 'origin', baseBranch]);
+            await execFileAsync('git', [
+                '-C', trigger.workspacePath,
+                'worktree', 'add',
+                sessionWorkspacePath,
+                '-b', `${branchPrefix}${sessionId}`,
+                `origin/${baseBranch}`,
+            ]);
+            await persistTokens(sessionId, startContinueToken ?? currentContinueToken, startCheckpointToken, sessionWorktreePath);
+            console.log(`[WorkflowRunner] Worktree created: sessionId=${sessionId} ` +
+                `branch=${branchPrefix}${sessionId} path=${sessionWorkspacePath}`);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            console.error(`[WorkflowRunner] Worktree creation failed: sessionId=${sessionId} error=${errMsg}`);
+            emitter?.emit({ kind: 'session_completed', sessionId, workflowId: trigger.workflowId, outcome: 'error', detail: errMsg.slice(0, 200), ...withWorkrailSession(workrailSessionId) });
+            if (workrailSessionId !== null)
+                daemonRegistry?.unregister(workrailSessionId, 'failed');
+            return {
+                _tag: 'error',
+                workflowId: trigger.workflowId,
+                message: `Worktree creation failed: ${errMsg}`,
+                stopReason: 'error',
+            };
+        }
+    }
     if (firstStep.isComplete) {
         await fs.unlink(path.join(exports.DAEMON_SESSIONS_DIR, `${sessionId}.json`)).catch(() => { });
         emitter?.emit({ kind: 'session_completed', sessionId, workflowId: trigger.workflowId, outcome: 'success', detail: 'stop', ...withWorkrailSession(workrailSessionId) });
         if (workrailSessionId !== null)
             daemonRegistry?.unregister(workrailSessionId, 'completed');
-        return { _tag: 'success', workflowId: trigger.workflowId, stopReason: 'stop' };
+        return {
+            _tag: 'success',
+            workflowId: trigger.workflowId,
+            stopReason: 'stop',
+            ...(sessionWorktreePath !== undefined ? { sessionWorkspacePath: sessionWorktreePath } : {}),
+            ...(sessionWorktreePath !== undefined ? { sessionId } : {}),
+        };
     }
     const schemas = getSchemas();
     const spawnCurrentDepth = trigger.spawnDepth ?? 0;
@@ -1444,12 +1504,12 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
     const tools = [
         makeCompleteStepTool(sessionId, ctx, () => currentContinueToken, onAdvance, onComplete, (t) => { currentContinueToken = t; }, schemas, index_js_1.executeContinueWorkflow, emitter, workrailSessionId),
         makeContinueWorkflowTool(sessionId, ctx, onAdvance, onComplete, schemas, index_js_1.executeContinueWorkflow, emitter, workrailSessionId),
-        makeBashTool(trigger.workspacePath, schemas, sessionId, emitter, workrailSessionId),
+        makeBashTool(sessionWorkspacePath, schemas, sessionId, emitter, workrailSessionId),
         makeReadTool(readFileState, schemas, sessionId, emitter, workrailSessionId),
         makeWriteTool(readFileState, schemas, sessionId, emitter, workrailSessionId),
-        makeGlobTool(trigger.workspacePath, schemas, sessionId, emitter, workrailSessionId),
-        makeGrepTool(trigger.workspacePath, schemas, sessionId, emitter, workrailSessionId),
-        makeEditTool(trigger.workspacePath, readFileState, schemas, sessionId, emitter, workrailSessionId),
+        makeGlobTool(sessionWorkspacePath, schemas, sessionId, emitter, workrailSessionId),
+        makeGrepTool(sessionWorkspacePath, schemas, sessionId, emitter, workrailSessionId),
+        makeEditTool(sessionWorkspacePath, readFileState, schemas, sessionId, emitter, workrailSessionId),
         makeReportIssueTool(sessionId, emitter, workrailSessionId, undefined, (summary) => {
             if (issueSummaries.length < MAX_ISSUE_SUMMARIES) {
                 issueSummaries.push(summary);
@@ -1670,5 +1730,7 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter, steerR
         stopReason,
         ...(lastStepNotes !== undefined ? { lastStepNotes } : {}),
         ...(lastStepArtifacts !== undefined ? { lastStepArtifacts } : {}),
+        ...(sessionWorktreePath !== undefined ? { sessionWorkspacePath: sessionWorktreePath } : {}),
+        ...(sessionWorktreePath !== undefined ? { sessionId } : {}),
     };
 }

package/dist/manifest.json

@@ -453,12 +453,12 @@
       "sha256": "3bdb55ec0957928e0ebbb86a7d6b36d28f7ba7d5c0f3e236fd8f2e2aacee2fa4",
       "bytes": 60631
     },
-    "console-ui/assets/index-DwfWMKvv.js": {
-      "sha256": "14a935b1b1ed6b4d2a178a1f21bd657c5f9bcede837ac06b35fbb713114e99d0",
+    "console-ui/assets/index-Sb57DW4B.js": {
+      "sha256": "54d09def45773f707ebf2bc17d109411a36ae1098d97d1f81a7423c69686520a",
       "bytes": 760528
     },
     "console-ui/index.html": {
-      "sha256": "d0fec3b4d1f1156b9f4df60f7e5fe72af7f12fa8a29c90a331f0706dda67b908",
+      "sha256": "5f4e96c20ab0286c7be620fbaa3fd18728866e25b320ea8622fdda58f81b047a",
       "bytes": 417
     },
     "console/standalone-console.d.ts": {
@@ -550,12 +550,12 @@
       "bytes": 1512
     },
     "daemon/workflow-runner.d.ts": {
-      "sha256": "7025b0023c763c6899511c5d3635e9ab99bdc361616249aa25b36508753bf3a0",
-      "bytes": 6154
+      "sha256": "ba96e9b4437632c760a6da9b3d70e676a2ad0a0f0a6ae037ec83419d7ffaf7a8",
+      "bytes": 6529
     },
     "daemon/workflow-runner.js": {
-      "sha256": "94fad3401dca1d854c3d254ac8b6e7ab5ae9a942c47e9c5900383a4e017c820e",
-      "bytes": 84923
+      "sha256": "24acc5dce22f6619a05d7a5268a82f801a25d99e1fd8d7c021d2b47ce01deba8",
+      "bytes": 88602
     },
     "di/container.d.ts": {
       "sha256": "003bb7fb7478d627524b9b1e76bd0a963a243794a687ff233b96dc0e33a06d9f",
@@ -1566,12 +1566,12 @@
       "bytes": 5471
     },
     "trigger/delivery-action.d.ts": {
-      "sha256": "58109eaa7124d2864e1d872ff0148548932d2fa4d7e672f5fd83d4bbe40afdda",
-      "bytes": 1188
+      "sha256": "2b3f165759b0de49b7f49023a05efa50848331ab6cd9969b49c1409346959994",
+      "bytes": 1257
     },
     "trigger/delivery-action.js": {
-      "sha256": "453931945078ee15656f7a89f9e804d1db8edcc14b756beeb9cfadfcb9e83102",
-      "bytes": 8026
+      "sha256": "1a9c0d097dc0f14e66765366f878f5f8386a4a1b0c5eb9572fa90a2b60643bab",
+      "bytes": 9016
     },
     "trigger/delivery-client.d.ts": {
       "sha256": "0cb2be24b854cb31e3d2fe7eeaba6032de7a9b2a5290c8bc886df94faf5306f7",
@@ -1626,20 +1626,20 @@
       "bytes": 2123
     },
     "trigger/trigger-router.js": {
-      "sha256": "6584949ecc6bd8fe5d23bfe5b3b7feb3a488804987b2edd90733d2c0142aeec2",
-      "bytes": 15973
+      "sha256": "605cdce397bd19e5b991fe7378faf17b4f25b4421749e1b5349413a208a4f3dd",
+      "bytes": 17250
     },
     "trigger/trigger-store.d.ts": {
       "sha256": "7afb05127d55bc3757a550dd15d4b797766b3fff29d1bfe76b303764b93322e7",
       "bytes": 1588
     },
     "trigger/trigger-store.js": {
-      "sha256": "4e03bf0bea132c67087d69e07f3d9abddb504396438437705c26c9e7870b0680",
-      "bytes": 34667
+      "sha256": "f4e5c6d28db4c9c05df07b29eb627bc7a48f234a2c16ea4adfe57de24ca6bf38",
+      "bytes": 36591
     },
     "trigger/types.d.ts": {
-      "sha256": "c0f14b59c95cae52e06f8d9fe841292886587fad20497fd6686e842cc5696d3a",
-      "bytes": 2808
+      "sha256": "f9ccdc2bea0bee7557362cc7b64d89ed3ab26f7cd954e05395ce4cabe536ab02",
+      "bytes": 2929
     },
     "trigger/types.js": {
       "sha256": "45b4e4f23a6d1a2b07350196871b0c53840e5d8142b47f7acedd2f40ae7a6b73",

package/dist/trigger/delivery-action.d.ts

@@ -11,6 +11,8 @@ export interface HandoffArtifact {
 export interface DeliveryFlags {
     readonly autoCommit?: boolean;
     readonly autoOpenPR?: boolean;
+    readonly sessionId?: string;
+    readonly branchPrefix?: string;
 }
 export type DeliveryResult = {
     readonly _tag: 'committed';

package/dist/trigger/delivery-action.js

@@ -146,6 +146,30 @@ async function runDelivery(artifact, workspacePath, flags, execFn) {
             reason: 'filesChanged is empty -- cannot stage files safely (no git add -A fallback)',
         };
     }
+    if (flags.sessionId) {
+        const expectedBranch = `${flags.branchPrefix ?? 'worktrain/'}${flags.sessionId}`;
+        let headBranch;
+        try {
+            const result = await execFn('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: workspacePath, timeout: DELIVERY_TIMEOUT_MS });
+            headBranch = result.stdout.trim();
+        }
+        catch (e) {
+            return {
+                _tag: 'error',
+                phase: 'commit',
+                details: `HEAD branch check failed (cannot stage): ${formatExecError(e)}`,
+            };
+        }
+        if (headBranch !== expectedBranch) {
+            return {
+                _tag: 'error',
+                phase: 'commit',
+                details: `HEAD branch mismatch: expected "${expectedBranch}" but found "${headBranch}". ` +
+                    `Refusing to stage or push -- the agent may have switched branches. ` +
+                    `Worktree path: ${workspacePath}`,
+            };
+        }
+    }
     const commitMessage = artifact.commitSubject.startsWith(`${artifact.commitType}(`)
         ? artifact.commitSubject
         : `${artifact.commitType}(${artifact.commitScope}): ${artifact.commitSubject}`;

package/dist/trigger/trigger-router.js

@@ -136,7 +136,17 @@ async function maybeRunDelivery(triggerId, trigger, result, execFn) {
             `Ensure the workflow's final step produces a JSON block with commitType, filesChanged, etc.`);
         return;
     }
-    const deliveryResult = await (0, delivery_action_js_1.runDelivery)(parseResult.value, trigger.workspacePath, { autoCommit: trigger.autoCommit, autoOpenPR: trigger.autoOpenPR }, execFn);
+    const deliveryCwd = result.sessionWorkspacePath ?? trigger.workspacePath;
+    const deliveryResult = await (0, delivery_action_js_1.runDelivery)(parseResult.value, deliveryCwd, {
+        autoCommit: trigger.autoCommit,
+        autoOpenPR: trigger.autoOpenPR,
+        ...(trigger.branchStrategy === 'worktree' && result.sessionWorkspacePath
+            ? {
+                sessionId: result.sessionId ?? '',
+                branchPrefix: trigger.branchPrefix ?? 'worktrain/',
+            }
+            : {}),
+    }, execFn);
     switch (deliveryResult._tag) {
         case 'committed':
             console.log(`[TriggerRouter] Delivery committed: triggerId=${triggerId} sha=${deliveryResult.sha}`);
@@ -152,6 +162,16 @@ async function maybeRunDelivery(triggerId, trigger, result, execFn) {
                 `details=${deliveryResult.details}`);
             break;
     }
+    if (trigger.branchStrategy === 'worktree' && result.sessionWorkspacePath) {
+        try {
+            await execFn('git', ['-C', trigger.workspacePath, 'worktree', 'remove', '--force', result.sessionWorkspacePath], { cwd: trigger.workspacePath, timeout: 60000 });
+            console.log(`[TriggerRouter] Worktree removed: triggerId=${triggerId} path=${result.sessionWorkspacePath}`);
+        }
+        catch (err) {
+            console.warn(`[TriggerRouter] Could not remove worktree: triggerId=${triggerId} ` +
+                `path=${result.sessionWorkspacePath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
 }
 class Semaphore {
     constructor(max) {
@@ -246,6 +266,9 @@ class TriggerRouter {
             ...(trigger.referenceUrls !== undefined ? { referenceUrls: trigger.referenceUrls } : {}),
             ...(trigger.agentConfig !== undefined ? { agentConfig: trigger.agentConfig } : {}),
             ...(trigger.soulFile !== undefined ? { soulFile: trigger.soulFile } : {}),
+            ...(trigger.branchStrategy !== undefined ? { branchStrategy: trigger.branchStrategy } : {}),
+            ...(trigger.baseBranch !== undefined ? { baseBranch: trigger.baseBranch } : {}),
+            ...(trigger.branchPrefix !== undefined ? { branchPrefix: trigger.branchPrefix } : {}),
         };
         this.emitter?.emit({ kind: 'trigger_fired', triggerId: trigger.id, workflowId: trigger.workflowId });
         const queueKey = trigger.concurrencyMode === 'parallel'

package/dist/trigger/trigger-store.js

@@ -391,6 +391,15 @@ function setTriggerField(trigger, key, value) {
         case 'soulFile':
             trigger.soulFile = value;
             break;
+        case 'branchStrategy':
+            trigger.branchStrategy = value;
+            break;
+        case 'baseBranch':
+            trigger.baseBranch = value;
+            break;
+        case 'branchPrefix':
+            trigger.branchPrefix = value;
+            break;
         default:
             break;
     }
@@ -602,6 +611,36 @@ function validateAndResolveTrigger(raw, env, workspaces = {}) {
         console.warn(`[TriggerStore] Warning: trigger "${rawId}" has autoOpenPR: true but autoCommit is not true. ` +
             `A PR requires a commit -- delivery will be skipped unless autoCommit is also set to true.`);
     }
+    const rawBranchStrategy = raw.branchStrategy?.trim();
+    if (rawBranchStrategy !== undefined && rawBranchStrategy !== 'worktree' && rawBranchStrategy !== 'none') {
+        return (0, result_js_1.err)({
+            kind: 'invalid_field_value',
+            field: `branchStrategy (must be "worktree" or "none", got: "${rawBranchStrategy}")`,
+            triggerId: rawId,
+        });
+    }
+    const branchStrategy = rawBranchStrategy === 'worktree' ? 'worktree' : rawBranchStrategy === 'none' ? 'none' : undefined;
+    const baseBranch = raw.baseBranch?.trim() || undefined;
+    const branchPrefix = raw.branchPrefix?.trim() || undefined;
+    const GIT_SAFE_RE = /^[a-zA-Z0-9._/-]+$/;
+    if (baseBranch !== undefined) {
+        if (!GIT_SAFE_RE.test(baseBranch) || baseBranch.startsWith('-')) {
+            return (0, result_js_1.err)({
+                kind: 'invalid_field_value',
+                field: `baseBranch (must match /^[a-zA-Z0-9._/-]+$/ and not start with "-", got: "${baseBranch}")`,
+                triggerId: rawId,
+            });
+        }
+    }
+    if (branchPrefix !== undefined) {
+        if (!GIT_SAFE_RE.test(branchPrefix) || branchPrefix.startsWith('-')) {
+            return (0, result_js_1.err)({
+                kind: 'invalid_field_value',
+                field: `branchPrefix (must match /^[a-zA-Z0-9._/-]+$/ and not start with "-", got: "${branchPrefix}")`,
+                triggerId: rawId,
+            });
+        }
+    }
     function parsePollIntervalSeconds(raw2, triggerId2) {
         const intervalRaw = raw2.pollIntervalSeconds?.trim();
         if (!intervalRaw)
@@ -741,6 +780,9 @@ function validateAndResolveTrigger(raw, env, workspaces = {}) {
         ...(pollingSource !== undefined ? { pollingSource } : {}),
         ...(resolvedWorkspaceName !== undefined ? { workspaceName: resolvedWorkspaceName } : {}),
         ...(resolvedSoulFile ? { soulFile: resolvedSoulFile } : {}),
+        ...(branchStrategy !== undefined ? { branchStrategy } : {}),
+        ...(baseBranch !== undefined ? { baseBranch } : {}),
+        ...(branchPrefix !== undefined ? { branchPrefix } : {}),
     };
     return (0, result_js_1.ok)(trigger);
 }

package/dist/trigger/types.d.ts

@@ -68,6 +68,9 @@ export interface TriggerDefinition {
     readonly pollingSource?: PollingSource;
     readonly workspaceName?: WorkspaceName;
     readonly soulFile?: string;
+    readonly branchStrategy?: 'worktree' | 'none';
+    readonly baseBranch?: string;
+    readonly branchPrefix?: string;
 }
 export interface TriggerConfig {
     readonly triggers: readonly TriggerDefinition[];

package/docs/design/adaptive-coordinator-context-candidates.md

@@ -0,0 +1,265 @@
+# Inter-Phase Context Passing: Design Candidates
+
+*Working analysis document -- raw investigative material, not a final decision.*
+*Produced during wr.discovery workflow for adaptive-coordinator-context.md.*
+
+---
+
+## Problem Understanding
+
+### Core tensions
+
+1. **Concern separation vs. convenience:** ContextAssembler is the only session injection mechanism but was designed for startup context (git diff, prior session notes), not inter-phase structured contracts. Using it for inter-phase handoff is convenient but muddles its purpose and change rate.
+
+2. **Coupling vs. simplicity:** File-based handoff (pitch.md) is simple and already works for Shaping->Coding. Extending the pattern to all transitions requires each workflow's final step to write to a fixed `.workrail/` path -- coupling pipeline topology to workflow authoring.
+
+3. **Uniform bridge vs. typed contracts:** Coordinator-injected freetext (assembledContextSummary) is uniform across all transitions but imprecise -- no schema enforcement. Typed artifacts per transition are precise and Zod-validated but add per-transition schema overhead.
+
+4. **Coordinator responsibility vs. session responsibility:** Coordinator can bridge at spawn time (reads lastStepNotes, builds context, injects at spawn). Sessions can self-discover (Phase 0.5 already does this for pitch.md). Self-discovery is more robust but requires each session to know the file conventions.
+
+### Likely seam
+
+The problem does NOT live in ContextAssembler. The coordinator already passes arbitrary context at spawn time via the 4th parameter to `spawnSession`. The real seam is: **what to put in that context object and how to extract it from the previous phase's output.**
+
+The problem is narrower than it appears:
+- Shaping->Coding: already solved (Phase 0.5 + pitch.md)
+- Review->Fix: already solved (wr.review_verdict + pr-review.ts)
+- Remaining gap: Discovery->Shaping only
+
+### What makes this hard
+
+- Coordinator and session are in different systems; workflow prompt changes can silently break coordinator parsing
+- The only injection point (`assembledContextSummary`) is a freetext markdown string, not a typed contract
+- Two transitions need structured coordinator routing (D->S needs direction; Review->Fix already solved). Three transitions are pass-through.
+- Silent failure is the dominant risk
+
+---
+
+## Philosophy Constraints
+
+**Principles that constrain this design:**
+- Immutability by default: all new types use `readonly`
+- Make illegal states unrepresentable: discriminated unions for AssemblyTask; typed artifacts for coordinator contracts
+- Errors are data: new ContextBundle sources should use `Result<T, string>`
+- Validate at boundaries: Zod for external inputs (typed artifacts, notes parsing)
+- Compose with small pure functions: handoff builder/parser functions must be pure
+- Dependency injection: file reads go through CoordinatorDeps
+- YAGNI: only add typed artifacts for transitions where coordinator branches on structured values
+
+**Active conflict:** YAGNI vs. "make illegal states unrepresentable" -- typed artifacts everywhere would enforce all contracts but add schema overhead for 3 transitions that don't need it.
+
+---
+
+## Impact Surface
+
+Must stay consistent with:
+- `src/context-assembly/types.ts` (AssemblyTask union)
+- `src/context-assembly/index.ts` (assemble() switch on task.kind)
+- `src/coordinators/pr-review.ts` (CoordinatorDeps interface)
+- `src/v2/durable-core/schemas/artifacts/` (typed artifact schemas)
+- `workflows/wr.discovery.json` (Phase 7 -- if emitting artifact)
+- `workflows/wr.shaping.json` (Step 1 -- if adding file search)
+- `workflows/coding-task-workflow-agentic.json` (Phase 0.5 -- no changes expected)
+
+---
+
+## Candidates
+
+### Candidate A: Goal string composition + notes injection
+
+**Summary:** Coordinator composes a rich goal string from the previous phase's `lastStepNotes` and passes notes as `assembledContextSummary` at spawn time -- no new mechanisms required.
+
+**Mechanism:**
+When spawning wr.shaping, coordinator constructs:
+```
+goal = "Shape the following problem discovered in our discovery session:\n\n[lastStepNotes summary]"
+context = { assembledContextSummary: lastStepNotes }
+```
+wr.shaping Step 1 reads from "goal text, discovery notes, tickets, user stories" -- both injection points land in session context.
+
+**Tensions resolved:** Workflow independence, coordinator simplicity, coherence
+
+**Tensions accepted:** No mechanism clarity, no schema validation, silent failure when notes format changes
+
+**Boundary:** Coordinator spawn site only
+
+**Failure mode:** wr.discovery notes format changes silently. Shaping session starts from degraded context. No error surfaced.
+
+**Repo pattern:** Follows existing assembledContextSummary pattern. No departure.
+
+**Gains:** Zero new code outside coordinator. Zero workflow changes. Works today.
+**Losses:** No machine-parseable contract. Coordinator cannot extract structured fields programmatically.
+
+**Scope judgment:** Best-fit for pass-through transitions. Too narrow for transitions where coordinator branches on structured values.
+
+**Philosophy:** Honors YAGNI, DI. Conflicts with "make illegal states unrepresentable", "validate at boundaries".
+
+---
+
+### Candidate B: File convention extension (adapt pitch.md)
+
+**Summary:** wr.discovery Phase 7 writes `.workrail/current-discovery.md`; wr.shaping Step 1 searches for it -- the same file convention that already works for Shaping->Coding.
+
+**Mechanism:**
+- wr.discovery Phase 7 updated to write `.workrail/current-discovery.md`
+- wr.shaping Step 1 updated to search for `.workrail/current-discovery.md` when no goal text provides discovery context
+- Coordinator passes correct workspacePath -- that's the only coordinator involvement
+
+**Tensions resolved:** Discoverable handoff (session self-discovers), coordinator logic (no bridging for D->S)
+
+**Tensions accepted:** 2 workflow changes, stale file risk (failed discovery leaves wrong file)
+
+**Boundary:** Filesystem at `.workrail/`
+
+**Failure mode:** Discovery fails before Phase 7. File is stale from prior session. Shaping reads wrong discovery output. No timestamp check.
+
+**Repo pattern:** Directly adapts pitch.md convention from wr.shaping Step 9.
+
+**Gains:** Sessions self-discover. Coordinator unchanged for D->S. Clean separation.
+**Losses:** Two workflow changes. Stale file risk. Conventions must be maintained.
+
+**Scope judgment:** Best-fit for D->S specifically. Over-engineered for other transitions.
+
+**Philosophy:** Honors YAGNI, "make illegal states unrepresentable" (file presence checkable). Conflicts with "validate at boundaries" (stale file not caught at coordinator boundary).
+
+---
+
+### Candidate C: Coordinator-injected structured context (pure builder functions)
+
+**Summary:** Add a pure `buildDiscoveryHandoffContext(notes: string): PhaseHandoffContext` function in the coordinator that extracts structured fields from discovery notes and passes them as spawn context.
+
+**Type shape:**
+```typescript
+interface PhaseHandoffContext {
+  readonly phaseFrom: string;
+  readonly phaseTo: string;
+  readonly keyFindings: string;
+  readonly selectedDirection?: string;
+  readonly designDocPath?: string;
+}
+```
+
+**Tensions resolved:** Coordinator simplicity (named pure function per transition), no workflow changes, coordinator owns contracts
+
+**Tensions accepted:** Notes format still unconstrained. Builder functions must be maintained when format changes.
+
+**Boundary:** Coordinator spawn site + named pure function (slightly better than A)
+
+**Failure mode:** Notes format changes silently break builder. Same failure as A but slightly more visible (named function can be tested).
+
+**Repo pattern:** Adapts parseFindingsFromNotes() pattern (pure function + coordinator uses result). Direct precedent in pr-review.ts.
+
+**Gains:** Named, testable, pure functions. Coordinator owns contracts. No workflow changes.
+**Losses:** Notes format still unconstrained. Per-transition builder functions as pipeline grows.
+
+**Scope judgment:** Best-fit for coordinator-centric design with intermediate rigor.
+
+**Philosophy:** Honors "compose with small pure functions", DI. Conflicts with "validate at boundaries", "make illegal states unrepresentable".
+
+---
+
+### Candidate D: Typed handoff artifact for decision-critical transitions only (wr.discovery_handoff)
+
+**Summary:** Add a `wr.discovery_handoff` typed artifact emitted in wr.discovery Phase 7, Zod-validated by the coordinator -- applied only to D->S; all other transitions use goal string composition.
+
+**Schema:**
+```typescript
+interface DiscoveryHandoffArtifactV1 {
+  readonly kind: 'wr.discovery_handoff';
+  readonly version: 1;
+  readonly selectedDirection: string;
+  readonly designDocPath: string;
+  readonly confidenceBand: 'high' | 'medium' | 'low';
+  readonly keyInvariants: readonly string[];
+}
+```
+
+**Coordinator parsing:**
+```typescript
+const handoffArtifact = readDiscoveryHandoffArtifact(lastStepArtifacts, sessionHandle);
+const spawnContext = handoffArtifact
+  ? { selectedDirection: handoffArtifact.selectedDirection, designDocPath: handoffArtifact.designDocPath, assembledContextSummary: render(handoffArtifact) }
+  : { assembledContextSummary: lastStepNotes };
+await deps.spawnSession('wr.shaping', buildShapingGoal(handoffArtifact ?? notes), workspace, spawnContext);
+```
+
+**Transition coverage:**
+- D->S: wr.discovery_handoff (NEW)
+- Review->Fix: wr.review_verdict (already exists)
+- S->C: goal string + pitch.md self-discovery via Phase 0.5 (no typed artifact)
+- C->PR: PR number in goal string (no typed artifact)
+- PR->Review: PR number (no typed artifact)
+
+**Tensions resolved:** Mechanism clarity (schema IS the contract), validates at boundaries (Zod), makes illegal states unrepresentable for D->S
+
+**Tensions accepted:** 1 workflow change (wr.discovery Phase 7 must emit artifact). Two-tier fallback complexity. Schema maintenance.
+
+**Boundary:** wr.discovery Phase 7 (emitter) + coordinator lastStepArtifacts handling (consumer)
+
+**Failure mode:** Agent doesn't emit artifact. Coordinator falls back to notes parsing. Two-tier failure, same as wr.review_verdict today.
+
+**Repo pattern:** Directly follows wr.review_verdict pattern in every structural detail.
+
+**Gains:** Machine-parseable D->S contract. Coordinator can route on confidenceBand. Type-safe. Explicit failure.
+**Losses:** 1 workflow change. Schema maintenance. Two-tier parsing. Agent must reliably emit artifact.
+
+**Scope judgment:** Best-fit for D->S. Combined with A for other transitions = minimum typed surface.
+
+**Philosophy:** Fully honors "make illegal states unrepresentable", "validate at boundaries", "type safety as first line of defense", YAGNI (applied only to 2 decision-critical transitions).
+
+---
+
+## Comparison and Recommendation
+
+### Comparison matrix
+
+| Criterion | A | B | C | D |
+|-----------|---|---|---|---|
+| Mechanism clarity | Low | Medium | Medium | High |
+| Coordinator logic minimality | High | High | Medium | Medium |
+| Workflow independence | High | Low | High | Medium |
+| Coherence with existing patterns | Medium | High | Medium | High |
+| Discoverable handoff | Low | High | Low | Low |
+| Philosophy fit | Medium | Medium | Medium | High |
+| Failure mode explicitness | Low | Medium | Medium | High |
+
+### Recommendation: Hybrid D + A
+
+**D for Discovery->Shaping:**
+Coordinator branches on `selectedDirection` -- this is a routing decision, not just context enrichment. Mirrors the wr.review_verdict precedent. Schema overhead proportionate to decision weight.
+
+**A for all other pass-through transitions:**
+- Shaping->Coding: Phase 0.5 finds pitch.md automatically (confirmed in workflow prompt)
+- Coding->PR: PR number in goal string
+- PR->Review: pr-review.ts already handles this
+
+**No ContextAssembler change needed:**
+Coordinator passes `{ selectedDirection, designDocPath, assembledContextSummary }` as spawn context keys. The existing `context: Record<string, unknown>` parameter on `spawnSession` is sufficient.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument against D:**
+The workflow change to wr.discovery Phase 7 is a point of failure. If the agent emits a malformed artifact or omits it, coordinator falls back to notes parsing -- same fragility as Candidate A. The typed contract only helps when the artifact IS correctly emitted.
+
+**Why A is a legitimate simpler answer:**
+wr.shaping Step 1 explicitly reads "goal text, discovery notes, tickets, user stories." If coordinator goal string includes discovery summary, this may be sufficient. No structured routing on selectedDirection may be needed. Validate this when the first adaptive coordinator is written.
+
+**Pivot condition to A:**
+When the first adaptive coordinator is written, if wr.shaping Step 1 produces sound results without structured `selectedDirection` access, Candidate A is correct and D's overhead is unjustified.
+
+**Broader option:**
+D for all transitions (add wr.shaping_handoff, wr.coding_handoff). Justified only if coordinator needs to branch on pitch content or implementation scope. Not justified now.
+
+---
+
+## Open Questions for the Main Agent
+
+1. Does the coordinator need to branch on `selectedDirection` from discovery, or is passing the full notes blob sufficient for wr.shaping Step 1? This determines whether D is needed at all.
+
+2. Is there a planned use case where the adaptive coordinator skips Shaping based on discovery confidence band? If yes, D is clearly justified. If not, A may be sufficient.
+
+3. What does the routing agent (adaptive-coordinator-routing.md) expect from context passing? Its design may have specific requirements for structured fields at routing decision time.
+
+4. Is `.workrail/current-pitch.md` reliably found by Phase 0.5 in practice? If Phase 0.5 sometimes misses it, the coordinator may need to inject `pitchPath` explicitly.