@exaudeus/workrail 3.9.2 → 3.10.0

package/dist/manifest.json

@@ -946,8 +946,8 @@
       "bytes": 68013
     },
     "mcp/output-schemas.js": {
-      "sha256": "f390f2c853580c63dbaa204354dd2199f282e47c0bcd162d2accf3ab27d7ec04",
-      "bytes": 15326
+      "sha256": "d8e73b9f2722193eac8f68887a11644752efb35d341775dd18296f51cc1de26f",
+      "bytes": 15428
     },
     "mcp/render-envelope.d.ts": {
       "sha256": "22e83e1aba52968a7136cf289125a217b5f462a5a66a1eebe4669006e3326fdb",
@@ -1446,12 +1446,12 @@
       "bytes": 447
     },
     "v2/durable-core/constants.d.ts": {
-      "sha256": "2cdc1fe66cb2024e17977e024c73b9bb50845b70c9ac3925c2635e843a94f7f8",
-      "bytes": 3699
+      "sha256": "60311085ea51d86307877bd952623effcafeddf935fbe0f2cde8a21a165dd932",
+      "bytes": 3754
     },
     "v2/durable-core/constants.js": {
-      "sha256": "29372d3e7f868b5c40d6270a1f39477a680524688e73b03613305fafef4a9553",
-      "bytes": 3558
+      "sha256": "41e0aabd3754c79c9453c8496128610b1bd4a328cf7f55c4f0a8d7bc527c94a2",
+      "bytes": 3642
     },
     "v2/durable-core/domain/ack-advance-append-plan.d.ts": {
       "sha256": "2e802606656a0c1938192e5533aa46c74bc42789b5c315c79f6de4850017b30e",
@@ -1594,8 +1594,8 @@
       "bytes": 1175
     },
     "v2/durable-core/domain/prompt-renderer.js": {
-      "sha256": "2ac48cd9cdcecd19bec6bec710e6f45437f68a62df6fac60ce3eff1cdb821b32",
-      "bytes": 18266
+      "sha256": "f3e7cc34b753c082ee310e88839948e225ab10f13cedae1d35b2bd64869eb848",
+      "bytes": 17166
     },
     "v2/durable-core/domain/reason-model.d.ts": {
       "sha256": "650fcb2d9969a4e6123cccbd4913f4d57aeab21a19bb907aa1e11f95e5a95089",
@@ -1621,6 +1621,14 @@
       "sha256": "cc53453a1617b9adc526f7d3f49a40b1491bbe63dbaff98ddc187e1f8f6d125f",
       "bytes": 1454
     },
+    "v2/durable-core/domain/retrieval-contract.d.ts": {
+      "sha256": "9d130876a9584ab24fcb65e145958404d5636ff96ee1c5a02a2f64b219d5eda4",
+      "bytes": 4747
+    },
+    "v2/durable-core/domain/retrieval-contract.js": {
+      "sha256": "083a2e7d9fbbf4865f3960ad232774fd416b226919c3c39ea36e8ca3102df0cf",
+      "bytes": 12217
+    },
     "v2/durable-core/domain/risk-policy-guardrails.d.ts": {
       "sha256": "4720f9fe6e6ae68d7f989b31070d73661eb96652109dac7d30961e7937ff55e5",
       "bytes": 637
@@ -2430,12 +2438,12 @@
       "bytes": 732
     },
     "v2/projections/resume-ranking.d.ts": {
-      "sha256": "b1d9e7d6fb3e59ced42f7c2e5fd9d8f9a18308aa6f4411a8aabf5dc174aa8dad",
-      "bytes": 3960
+      "sha256": "3ac0db8e9d154eff9fba21c40eedaf981ea844d3f536f2b69b3840af8653b8f1",
+      "bytes": 4033
     },
     "v2/projections/resume-ranking.js": {
-      "sha256": "1b256c992ded9ec52150b229799716d118ca2a3659a0cc523e727cde2ebf7b0c",
-      "bytes": 13660
+      "sha256": "5f1ee9888446caa23653543fc8cae69ac4398e73232d71bac3d16722c9cd2158",
+      "bytes": 13596
     },
     "v2/projections/run-context.d.ts": {
       "sha256": "a4d57470a435ac9860f60b3244d1b828853995027cd510d8da42762d21b2a687",

package/dist/mcp/output-schemas.js

@@ -5,6 +5,7 @@ exports.toPendingStep = toPendingStep;
 const zod_1 = require("zod");
 const state_js_1 = require("../domain/execution/state.js");
 const token_patterns_js_1 = require("../v2/durable-core/tokens/token-patterns.js");
+const constants_js_1 = require("../v2/durable-core/constants.js");
 const JsonPrimitiveSchema = zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()]);
 exports.JsonValueSchema = zod_1.z.lazy(() => zod_1.z.union([JsonPrimitiveSchema, zod_1.z.array(exports.JsonValueSchema), zod_1.z.record(exports.JsonValueSchema)]));
 exports.WorkflowSummarySchema = zod_1.z.object({
@@ -264,7 +265,7 @@ exports.V2ResumeSessionOutputSchema = zod_1.z.object({
         sessionTitle: zod_1.z.string().nullable().describe('Human-readable task/session title derived from persisted workflow context or early recap text.'),
         gitBranch: zod_1.z.string().nullable().describe('Git branch associated with the session, if available.'),
         resumeToken: zod_1.z.string().regex(token_patterns_js_1.STATE_TOKEN_PATTERN, 'Invalid resumeToken format'),
-        snippet: zod_1.z.string().max(1024),
+        snippet: zod_1.z.string().max(constants_js_1.MAX_RESUME_PREVIEW_BYTES),
         confidence: zod_1.z.enum(['strong', 'medium', 'weak']).describe('Coarse confidence band for how likely this candidate is the intended session.'),
         matchExplanation: zod_1.z.string().min(1).describe('Short natural-language explanation of why this candidate ranked here.'),
         pendingStepId: zod_1.z.string().nullable().describe('The current pending step ID (e.g. "phase-3-implement") if the workflow is in progress. ' +

package/dist/v2/durable-core/constants.d.ts

@@ -15,7 +15,8 @@ export declare const MAX_OBSERVATION_SHORT_STRING_LENGTH = 80;
 export declare const SESSION_LOCK_RETRY_AFTER_MS = 1000;
 export declare const DEFAULT_RETRY_AFTER_MS = 1000;
 export declare const TRUNCATION_MARKER = "\n\n[TRUNCATED]";
-export declare const RECOVERY_BUDGET_BYTES = 12288;
+export declare const RECOVERY_BUDGET_BYTES: number;
+export declare const MAX_RESUME_PREVIEW_BYTES: number;
 export declare const SHA256_DIGEST_PATTERN: RegExp;
 export declare const DELIMITER_SAFE_ID_PATTERN: RegExp;
 export declare const EVENT_KIND: {

package/dist/v2/durable-core/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTONOMY_MODE = exports.ADVANCE_INTENT = exports.MANIFEST_KIND = exports.EDGE_CAUSE = exports.ADVANCE_OUTCOME = exports.ENGINE_STATE = exports.EDGE_KIND = exports.PAYLOAD_KIND = exports.OUTPUT_CHANNEL = exports.EVENT_KIND = exports.DELIMITER_SAFE_ID_PATTERN = exports.SHA256_DIGEST_PATTERN = exports.RECOVERY_BUDGET_BYTES = exports.TRUNCATION_MARKER = exports.DEFAULT_RETRY_AFTER_MS = exports.SESSION_LOCK_RETRY_AFTER_MS = exports.MAX_OBSERVATION_SHORT_STRING_LENGTH = exports.MAX_CONTEXT_DEPTH = exports.MAX_CONTEXT_BYTES = exports.MAX_VALIDATION_SUGGESTIONS_BYTES = exports.MAX_VALIDATION_ISSUES_BYTES = exports.MAX_VALIDATION_SUGGESTION_ITEM_BYTES = exports.MAX_VALIDATION_ISSUE_ITEM_BYTES = exports.MAX_OUTPUT_NOTES_MARKDOWN_BYTES = exports.MAX_DECISION_TRACE_TOTAL_BYTES = exports.MAX_DECISION_TRACE_ENTRY_SUMMARY_BYTES = exports.MAX_DECISION_TRACE_ENTRIES = exports.MAX_BLOCKER_SUGGESTED_FIX_BYTES = exports.MAX_BLOCKER_MESSAGE_BYTES = exports.MAX_BLOCKERS = void 0;
+exports.AUTONOMY_MODE = exports.ADVANCE_INTENT = exports.MANIFEST_KIND = exports.EDGE_CAUSE = exports.ADVANCE_OUTCOME = exports.ENGINE_STATE = exports.EDGE_KIND = exports.PAYLOAD_KIND = exports.OUTPUT_CHANNEL = exports.EVENT_KIND = exports.DELIMITER_SAFE_ID_PATTERN = exports.SHA256_DIGEST_PATTERN = exports.MAX_RESUME_PREVIEW_BYTES = exports.RECOVERY_BUDGET_BYTES = exports.TRUNCATION_MARKER = exports.DEFAULT_RETRY_AFTER_MS = exports.SESSION_LOCK_RETRY_AFTER_MS = exports.MAX_OBSERVATION_SHORT_STRING_LENGTH = exports.MAX_CONTEXT_DEPTH = exports.MAX_CONTEXT_BYTES = exports.MAX_VALIDATION_SUGGESTIONS_BYTES = exports.MAX_VALIDATION_ISSUES_BYTES = exports.MAX_VALIDATION_SUGGESTION_ITEM_BYTES = exports.MAX_VALIDATION_ISSUE_ITEM_BYTES = exports.MAX_OUTPUT_NOTES_MARKDOWN_BYTES = exports.MAX_DECISION_TRACE_TOTAL_BYTES = exports.MAX_DECISION_TRACE_ENTRY_SUMMARY_BYTES = exports.MAX_DECISION_TRACE_ENTRIES = exports.MAX_BLOCKER_SUGGESTED_FIX_BYTES = exports.MAX_BLOCKER_MESSAGE_BYTES = exports.MAX_BLOCKERS = void 0;
 exports.MAX_BLOCKERS = 10;
 exports.MAX_BLOCKER_MESSAGE_BYTES = 512;
 exports.MAX_BLOCKER_SUGGESTED_FIX_BYTES = 1024;
@@ -18,7 +18,8 @@ exports.MAX_OBSERVATION_SHORT_STRING_LENGTH = 80;
 exports.SESSION_LOCK_RETRY_AFTER_MS = 1000;
 exports.DEFAULT_RETRY_AFTER_MS = 1000;
 exports.TRUNCATION_MARKER = '\n\n[TRUNCATED]';
-exports.RECOVERY_BUDGET_BYTES = 12288;
+exports.RECOVERY_BUDGET_BYTES = 24 * 1024;
+exports.MAX_RESUME_PREVIEW_BYTES = 2 * 1024;
 exports.SHA256_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
 exports.DELIMITER_SAFE_ID_PATTERN = /^[a-z0-9_-]+$/;
 exports.EVENT_KIND = {

package/dist/v2/durable-core/domain/prompt-renderer.js

@@ -15,11 +15,13 @@ const index_js_2 = require("../schemas/artifacts/index.js");
 const run_context_js_1 = require("../../projections/run-context.js");
 const condition_evaluator_js_1 = require("../../../utils/condition-evaluator.js");
 const context_template_resolver_js_1 = require("./context-template-resolver.js");
-function buildNonTipSections(args) {
-    const sections = [];
+const retrieval_contract_js_1 = require("./retrieval-contract.js");
+function buildNonTipSegments(args) {
+    const segments = [];
     const childSummary = (0, recap_recovery_js_1.buildChildSummary)({ nodeId: args.nodeId, dag: args.run });
-    if (childSummary) {
-        sections.push(`### Branch Summary\n${childSummary}`);
+    const childSummarySegment = (0, retrieval_contract_js_1.createBranchSummarySegment)(childSummary);
+    if (childSummarySegment) {
+        segments.push(childSummarySegment);
     }
     if (args.run.preferredTipNodeId && args.run.preferredTipNodeId !== String(args.nodeId)) {
         const downstreamRes = (0, recap_recovery_js_1.collectDownstreamRecap)({
@@ -29,12 +31,15 @@ function buildNonTipSections(args) {
             outputs: args.outputs,
         });
         if (downstreamRes.isOk() && downstreamRes.value.length > 0) {
-            sections.push(`### Downstream Recap (Preferred Branch)\n${downstreamRes.value.join('\n\n')}`);
+            const downstreamSegment = (0, retrieval_contract_js_1.createDownstreamRecapSegment)(downstreamRes.value.join('\n\n'));
+            if (downstreamSegment) {
+                segments.push(downstreamSegment);
+            }
         }
     }
-    return sections;
+    return segments;
 }
-function buildAncestrySections(args) {
+function buildAncestrySegments(args) {
     const ancestryRes = (0, recap_recovery_js_1.collectAncestryRecap)({
         nodeId: args.nodeId,
         dag: args.run,
@@ -42,11 +47,12 @@ function buildAncestrySections(args) {
         includeCurrentNode: false,
     });
     if (ancestryRes.isOk() && ancestryRes.value.length > 0) {
-        return [`### Ancestry Recap\n${ancestryRes.value.join('\n\n')}`];
+        const ancestrySegment = (0, retrieval_contract_js_1.createAncestryRecapSegment)(ancestryRes.value.join('\n\n'));
+        return ancestrySegment ? [ancestrySegment] : [];
     }
     return [];
 }
-function buildFunctionDefsSections(args) {
+function buildFunctionDefsSegments(args) {
     const funcsRes = (0, function_definition_expander_js_1.expandFunctionDefinitions)({
         workflow: args.workflow,
         stepId: args.stepId,
@@ -55,7 +61,8 @@ function buildFunctionDefsSections(args) {
     });
     if (funcsRes.isOk() && funcsRes.value.length > 0) {
         const formatted = funcsRes.value.map(function_definition_expander_js_1.formatFunctionDef).join('\n\n');
-        return [`### Function Definitions\n\`\`\`\n${formatted}\n\`\`\``];
+        const functionDefinitionsSegment = (0, retrieval_contract_js_1.createFunctionDefinitionsSegment)(`\`\`\`\n${formatted}\n\`\`\``);
+        return functionDefinitionsSegment ? [functionDefinitionsSegment] : [];
     }
     return [];
 }
@@ -65,12 +72,12 @@ function hasPriorNotesInRun(args) {
         e.data.outputChannel === constants_js_1.OUTPUT_CHANNEL.RECAP &&
         e.data.payload.payloadKind === constants_js_1.PAYLOAD_KIND.NOTES);
 }
-function buildRecoverySections(args) {
+function buildRecoverySegments(args) {
     const isTip = args.run.tipNodeIds.includes(String(args.nodeId));
     return [
-        ...(isTip ? [] : buildNonTipSections({ nodeId: args.nodeId, run: args.run, outputs: args.outputs })),
-        ...buildAncestrySections({ nodeId: args.nodeId, run: args.run, outputs: args.outputs }),
-        ...buildFunctionDefsSections({
+        ...(isTip ? [] : buildNonTipSegments({ nodeId: args.nodeId, run: args.run, outputs: args.outputs })),
+        ...buildAncestrySegments({ nodeId: args.nodeId, run: args.run, outputs: args.outputs }),
+        ...buildFunctionDefsSegments({
             workflow: args.workflow,
             stepId: args.stepId,
             loopPath: args.loopPath,
@@ -78,52 +85,6 @@ function buildRecoverySections(args) {
         }),
     ];
 }
-function trimToUtf8Boundary(bytes) {
-    const n = bytes.length;
-    if (n === 0)
-        return bytes;
-    let cont = 0;
-    for (let i = n - 1; i >= 0 && i >= n - 4; i--) {
-        const b = bytes[i];
-        if ((b & 192) === 128) {
-            cont++;
-        }
-        else {
-            break;
-        }
-    }
-    if (cont === 0)
-        return bytes;
-    const leadByteIndex = n - cont - 1;
-    if (leadByteIndex < 0) {
-        return new Uint8Array(0);
-    }
-    const leadByte = bytes[leadByteIndex];
-    const expectedLen = (leadByte & 128) === 0 ? 1 :
-        (leadByte & 224) === 192 ? 2 :
-            (leadByte & 240) === 224 ? 3 :
-                (leadByte & 248) === 240 ? 4 :
-                    0;
-    const actualLen = cont + 1;
-    if (expectedLen === 0 || expectedLen !== actualLen) {
-        return bytes.subarray(0, leadByteIndex);
-    }
-    return bytes;
-}
-function applyPromptBudget(combinedPrompt) {
-    const encoder = new TextEncoder();
-    const promptBytes = encoder.encode(combinedPrompt);
-    if (promptBytes.length <= constants_js_1.RECOVERY_BUDGET_BYTES) {
-        return combinedPrompt;
-    }
-    const markerText = constants_js_1.TRUNCATION_MARKER;
-    const omissionNote = `\nOmitted recovery content due to budget constraints.`;
-    const suffixBytes = encoder.encode(markerText + omissionNote);
-    const maxContentBytes = constants_js_1.RECOVERY_BUDGET_BYTES - suffixBytes.length;
-    const truncatedBytes = trimToUtf8Boundary(promptBytes.subarray(0, maxContentBytes));
-    const decoder = new TextDecoder('utf-8');
-    return decoder.decode(truncatedBytes) + markerText + omissionNote;
-}
 function resolveParentLoopStep(workflow, stepId) {
     for (const step of workflow.definition.steps) {
         if ((0, workflow_js_1.isLoopStepDefinition)(step) && Array.isArray(step.body)) {
@@ -352,9 +313,8 @@ function renderPendingPrompt(args) {
         });
     }
     const { run, outputs } = projectionsRes.value;
-    const sections = buildRecoverySections({
+    const segments = buildRecoverySegments({
         nodeId: args.nodeId,
-        dag: run,
         run,
         outputs,
         workflow: args.workflow,
@@ -362,12 +322,14 @@ function renderPendingPrompt(args) {
         loopPath: args.loopPath,
         functionReferences,
     });
-    if (sections.length === 0) {
+    if (segments.length === 0) {
         return (0, neverthrow_1.ok)({ stepId: args.stepId, title: baseTitle, prompt: enhancedPrompt, agentRole, requireConfirmation });
     }
     const recoveryHeader = cleanResponseFormat ? 'Your previous work:' : '## Recovery Context';
-    const recoveryText = `${recoveryHeader}\n\n${sections.join('\n\n')}`;
-    const combinedPrompt = `${enhancedPrompt}\n\n${recoveryText}`;
-    const finalPrompt = applyPromptBudget(combinedPrompt);
+    const recoveryText = (0, retrieval_contract_js_1.renderBudgetedRehydrateRecovery)({
+        header: recoveryHeader,
+        segments,
+    }).text;
+    const finalPrompt = `${enhancedPrompt}\n\n${recoveryText}`;
     return (0, neverthrow_1.ok)({ stepId: args.stepId, title: baseTitle, prompt: finalPrompt, agentRole, requireConfirmation });
 }

package/dist/v2/durable-core/domain/retrieval-contract.d.ts

@@ -0,0 +1,105 @@
+export type RetrievalPackSurface = 'rehydrate';
+export type ResumePreviewSurface = 'resume_preview';
+export type RetrievalPackTier = 'structural_context' | 'durable_recap' | 'reference_material';
+export type ResumePreviewTier = 'identity_context' | 'durable_recap';
+export interface RetrievalPackTierDefinition {
+    readonly tier: RetrievalPackTier;
+    readonly purpose: string;
+    readonly priority: number;
+    readonly retention: 'core' | 'tail';
+}
+export interface ResumePreviewTierDefinition {
+    readonly tier: ResumePreviewTier;
+    readonly purpose: string;
+    readonly priority: number;
+    readonly maxBytes: number;
+}
+export interface RetrievalPackTruncationPolicy {
+    readonly mode: 'drop_lower_tiers_then_global_utf8_trim';
+    readonly budgetScope: 'shared_recovery_prompt';
+    readonly antiReconstructionRule: 'select_order_and_compress_explicit_facts_only';
+}
+export interface RetrievalPackContract {
+    readonly surface: RetrievalPackSurface;
+    readonly tiers: readonly RetrievalPackTierDefinition[];
+    readonly truncation: RetrievalPackTruncationPolicy;
+}
+export interface ResumePreviewContract {
+    readonly surface: ResumePreviewSurface;
+    readonly tiers: readonly ResumePreviewTierDefinition[];
+    readonly budgetBytes: number;
+}
+export interface BranchSummarySegment {
+    readonly kind: 'branch_summary';
+    readonly tier: 'structural_context';
+    readonly source: 'deterministic_structure';
+    readonly title: 'Branch Summary';
+    readonly body: string;
+}
+export interface DownstreamRecapSegment {
+    readonly kind: 'downstream_recap';
+    readonly tier: 'structural_context';
+    readonly source: 'explicit_durable_fact';
+    readonly title: 'Downstream Recap (Preferred Branch)';
+    readonly body: string;
+}
+export interface AncestryRecapSegment {
+    readonly kind: 'ancestry_recap';
+    readonly tier: 'durable_recap';
+    readonly source: 'explicit_durable_fact';
+    readonly title: 'Ancestry Recap';
+    readonly body: string;
+}
+export interface FunctionDefinitionsSegment {
+    readonly kind: 'function_definitions';
+    readonly tier: 'reference_material';
+    readonly source: 'workflow_definition';
+    readonly title: 'Function Definitions';
+    readonly body: string;
+}
+export type RetrievalPackSegment = BranchSummarySegment | DownstreamRecapSegment | AncestryRecapSegment | FunctionDefinitionsSegment;
+export interface RetrievalPackRenderResult {
+    readonly text: string;
+    readonly includedTiers: readonly RetrievalPackTier[];
+    readonly omittedTierCount: number;
+    readonly truncatedWithinTier: boolean;
+}
+export interface SessionTitlePreviewSegment {
+    readonly kind: 'session_title_preview';
+    readonly tier: 'identity_context';
+    readonly source: 'persisted_context';
+    readonly body: string;
+}
+export interface RecapPreviewSegment {
+    readonly kind: 'recap_preview';
+    readonly tier: 'durable_recap';
+    readonly source: 'explicit_durable_fact';
+    readonly body: string;
+}
+export type ResumePreviewSegment = SessionTitlePreviewSegment | RecapPreviewSegment;
+export type ResumePreviewText = string & {
+    readonly __brand: 'ResumePreviewText';
+};
+export interface ResumePreviewRenderResult {
+    readonly text: ResumePreviewText;
+    readonly includedTiers: readonly ResumePreviewTier[];
+}
+export declare const REHYDRATE_RETRIEVAL_CONTRACT: RetrievalPackContract;
+export declare const RESUME_PREVIEW_CONTRACT: ResumePreviewContract;
+export declare function createBranchSummarySegment(body: string): BranchSummarySegment | null;
+export declare function createDownstreamRecapSegment(body: string): DownstreamRecapSegment | null;
+export declare function createAncestryRecapSegment(body: string): AncestryRecapSegment | null;
+export declare function createFunctionDefinitionsSegment(body: string): FunctionDefinitionsSegment | null;
+export declare function createSessionTitlePreviewSegment(body: string): SessionTitlePreviewSegment | null;
+export declare function createRecapPreviewSegment(body: string): RecapPreviewSegment | null;
+export declare function compareRetrievalPackSegments(a: RetrievalPackSegment, b: RetrievalPackSegment): number;
+export declare function orderRetrievalPackSegments(segments: readonly RetrievalPackSegment[]): readonly RetrievalPackSegment[];
+export declare function renderRetrievalPackSections(segments: readonly RetrievalPackSegment[]): readonly string[];
+export declare function renderBudgetedResumePreview(args: {
+    readonly segments: readonly ResumePreviewSegment[];
+    readonly focusTerms?: readonly string[];
+}): ResumePreviewRenderResult;
+export declare function renderBudgetedRehydrateRecovery(args: {
+    readonly header: string;
+    readonly segments: readonly RetrievalPackSegment[];
+}): RetrievalPackRenderResult;

package/dist/v2/durable-core/domain/retrieval-contract.js

@@ -0,0 +1,310 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESUME_PREVIEW_CONTRACT = exports.REHYDRATE_RETRIEVAL_CONTRACT = void 0;
+exports.createBranchSummarySegment = createBranchSummarySegment;
+exports.createDownstreamRecapSegment = createDownstreamRecapSegment;
+exports.createAncestryRecapSegment = createAncestryRecapSegment;
+exports.createFunctionDefinitionsSegment = createFunctionDefinitionsSegment;
+exports.createSessionTitlePreviewSegment = createSessionTitlePreviewSegment;
+exports.createRecapPreviewSegment = createRecapPreviewSegment;
+exports.compareRetrievalPackSegments = compareRetrievalPackSegments;
+exports.orderRetrievalPackSegments = orderRetrievalPackSegments;
+exports.renderRetrievalPackSections = renderRetrievalPackSections;
+exports.renderBudgetedResumePreview = renderBudgetedResumePreview;
+exports.renderBudgetedRehydrateRecovery = renderBudgetedRehydrateRecovery;
+const constants_js_1 = require("../constants.js");
+const REHYDRATE_TIER_DEFINITIONS = [
+    {
+        tier: 'structural_context',
+        purpose: 'Orient the agent to branch shape and preferred continuation path.',
+        priority: 0,
+        retention: 'core',
+    },
+    {
+        tier: 'durable_recap',
+        purpose: 'Surface durable notes captured from explicit recap outputs.',
+        priority: 1,
+        retention: 'core',
+    },
+    {
+        tier: 'reference_material',
+        purpose: 'Surface authored workflow definitions referenced by the current step.',
+        priority: 2,
+        retention: 'tail',
+    },
+];
+exports.REHYDRATE_RETRIEVAL_CONTRACT = {
+    surface: 'rehydrate',
+    tiers: REHYDRATE_TIER_DEFINITIONS,
+    truncation: {
+        mode: 'drop_lower_tiers_then_global_utf8_trim',
+        budgetScope: 'shared_recovery_prompt',
+        antiReconstructionRule: 'select_order_and_compress_explicit_facts_only',
+    },
+};
+const RESUME_PREVIEW_TIER_DEFINITIONS = [
+    {
+        tier: 'identity_context',
+        purpose: 'Surface the best concise identity hint for the session.',
+        priority: 0,
+        maxBytes: 320,
+    },
+    {
+        tier: 'durable_recap',
+        purpose: 'Surface durable recap text, focused around the user query when possible.',
+        priority: 1,
+        maxBytes: 1600,
+    },
+];
+exports.RESUME_PREVIEW_CONTRACT = {
+    surface: 'resume_preview',
+    tiers: RESUME_PREVIEW_TIER_DEFINITIONS,
+    budgetBytes: constants_js_1.MAX_RESUME_PREVIEW_BYTES,
+};
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8');
+function getTierPriority(tier) {
+    return exports.REHYDRATE_RETRIEVAL_CONTRACT.tiers.find((candidate) => candidate.tier === tier)?.priority ?? Number.MAX_SAFE_INTEGER;
+}
+function getTierRetention(tier) {
+    return exports.REHYDRATE_RETRIEVAL_CONTRACT.tiers.find((candidate) => candidate.tier === tier)?.retention ?? 'tail';
+}
+function getResumePreviewTierPriority(tier) {
+    return exports.RESUME_PREVIEW_CONTRACT.tiers.find((candidate) => candidate.tier === tier)?.priority ?? Number.MAX_SAFE_INTEGER;
+}
+function getResumePreviewTierMaxBytes(tier) {
+    return exports.RESUME_PREVIEW_CONTRACT.tiers.find((candidate) => candidate.tier === tier)?.maxBytes ?? exports.RESUME_PREVIEW_CONTRACT.budgetBytes;
+}
+function compareAscii(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function trimToUtf8Boundary(bytes) {
+    const n = bytes.length;
+    if (n === 0)
+        return bytes;
+    let cont = 0;
+    for (let i = n - 1; i >= 0 && i >= n - 4; i--) {
+        const b = bytes[i];
+        if ((b & 192) === 128) {
+            cont++;
+        }
+        else {
+            break;
+        }
+    }
+    if (cont === 0)
+        return bytes;
+    const leadByteIndex = n - cont - 1;
+    if (leadByteIndex < 0) {
+        return new Uint8Array(0);
+    }
+    const leadByte = bytes[leadByteIndex];
+    const expectedLen = (leadByte & 128) === 0 ? 1 :
+        (leadByte & 224) === 192 ? 2 :
+            (leadByte & 240) === 224 ? 3 :
+                (leadByte & 248) === 240 ? 4 :
+                    0;
+    const actualLen = cont + 1;
+    if (expectedLen === 0 || expectedLen !== actualLen) {
+        return bytes.subarray(0, leadByteIndex);
+    }
+    return bytes;
+}
+function truncateUtf8(text, maxBytes) {
+    const bytes = encoder.encode(text);
+    if (bytes.length <= maxBytes) {
+        return text;
+    }
+    return decoder.decode(trimToUtf8Boundary(bytes.subarray(0, Math.max(0, maxBytes))));
+}
+function buildOmissionSuffix(omittedTierCount) {
+    const omissionLine = omittedTierCount > 0
+        ? `\nOmitted ${omittedTierCount} lower-priority tier${omittedTierCount === 1 ? '' : 's'} due to budget constraints.`
+        : '\nOmitted recovery content due to budget constraints.';
+    return `${constants_js_1.TRUNCATION_MARKER}${omissionLine}`;
+}
+function trimFinalRecoveryText(text, omittedTierCount) {
+    const suffix = buildOmissionSuffix(omittedTierCount);
+    const maxContentBytes = constants_js_1.RECOVERY_BUDGET_BYTES - encoder.encode(suffix).length;
+    const truncated = truncateUtf8(text, maxContentBytes);
+    return truncated + suffix;
+}
+function normalizePreviewFocusTerms(focusTerms) {
+    return [...new Set(focusTerms.map((term) => term.trim().toLowerCase()).filter((term) => term.length >= 3))];
+}
+function findFocusIndex(text, focusTerms) {
+    if (focusTerms.length === 0)
+        return -1;
+    const lower = text.toLowerCase();
+    return focusTerms.reduce((bestIndex, term) => {
+        const idx = lower.indexOf(term);
+        if (idx === -1)
+            return bestIndex;
+        if (bestIndex === -1)
+            return idx;
+        return Math.min(bestIndex, idx);
+    }, -1);
+}
+function excerptAroundFocus(text, maxBytes, focusTerms) {
+    const focusIndex = findFocusIndex(text, focusTerms);
+    if (focusIndex === -1) {
+        const truncated = truncateUtf8(text, maxBytes);
+        return truncated.length < text.length ? `${truncated}...` : truncated;
+    }
+    const contextChars = Math.max(80, Math.floor(maxBytes / 4));
+    const start = Math.max(0, focusIndex - contextChars);
+    const end = Math.min(text.length, focusIndex + contextChars * 2);
+    const slice = text.slice(start, end).trim();
+    const prefix = start > 0 ? '...' : '';
+    const suffix = end < text.length ? '...' : '';
+    const excerpt = `${prefix}${slice}${suffix}`;
+    return truncateUtf8(excerpt, maxBytes);
+}
+function createBranchSummarySegment(body) {
+    const trimmed = body.trim();
+    return trimmed.length === 0
+        ? null
+        : {
+            kind: 'branch_summary',
+            tier: 'structural_context',
+            source: 'deterministic_structure',
+            title: 'Branch Summary',
+            body: trimmed,
+        };
+}
+function createDownstreamRecapSegment(body) {
+    const trimmed = body.trim();
+    return trimmed.length === 0
+        ? null
+        : {
+            kind: 'downstream_recap',
+            tier: 'structural_context',
+            source: 'explicit_durable_fact',
+            title: 'Downstream Recap (Preferred Branch)',
+            body: trimmed,
+        };
+}
+function createAncestryRecapSegment(body) {
+    const trimmed = body.trim();
+    return trimmed.length === 0
+        ? null
+        : {
+            kind: 'ancestry_recap',
+            tier: 'durable_recap',
+            source: 'explicit_durable_fact',
+            title: 'Ancestry Recap',
+            body: trimmed,
+        };
+}
+function createFunctionDefinitionsSegment(body) {
+    const trimmed = body.trim();
+    return trimmed.length === 0
+        ? null
+        : {
+            kind: 'function_definitions',
+            tier: 'reference_material',
+            source: 'workflow_definition',
+            title: 'Function Definitions',
+            body: trimmed,
+        };
+}
+function createSessionTitlePreviewSegment(body) {
+    const trimmed = body.trim();
+    return trimmed.length === 0
+        ? null
+        : {
+            kind: 'session_title_preview',
+            tier: 'identity_context',
+            source: 'persisted_context',
+            body: trimmed,
+        };
+}
+function createRecapPreviewSegment(body) {
+    const trimmed = body.trim();
+    return trimmed.length === 0
+        ? null
+        : {
+            kind: 'recap_preview',
+            tier: 'durable_recap',
+            source: 'explicit_durable_fact',
+            body: trimmed,
+        };
+}
+function compareRetrievalPackSegments(a, b) {
+    const tierDiff = getTierPriority(a.tier) - getTierPriority(b.tier);
+    if (tierDiff !== 0)
+        return tierDiff;
+    const titleDiff = compareAscii(a.title, b.title);
+    if (titleDiff !== 0)
+        return titleDiff;
+    return compareAscii(a.body, b.body);
+}
+function orderRetrievalPackSegments(segments) {
+    return [...segments].sort(compareRetrievalPackSegments);
+}
+function renderRetrievalPackSections(segments) {
+    return orderRetrievalPackSegments(segments).map((segment) => `### ${segment.title}\n${segment.body}`);
+}
+function compareResumePreviewSegments(a, b) {
+    const tierDiff = getResumePreviewTierPriority(a.tier) - getResumePreviewTierPriority(b.tier);
+    if (tierDiff !== 0)
+        return tierDiff;
+    return compareAscii(a.body, b.body);
+}
+function renderBudgetedResumePreview(args) {
+    const ordered = [...args.segments].sort(compareResumePreviewSegments);
+    if (ordered.length === 0) {
+        return { text: '', includedTiers: [] };
+    }
+    const focusTerms = normalizePreviewFocusTerms(args.focusTerms ?? []);
+    const tierTexts = ordered.map((segment) => {
+        const maxBytes = getResumePreviewTierMaxBytes(segment.tier);
+        return {
+            tier: segment.tier,
+            text: excerptAroundFocus(segment.body, maxBytes, focusTerms),
+        };
+    });
+    const joined = tierTexts.map((entry) => entry.text).filter((text) => text.length > 0).join('\n\n');
+    const finalText = truncateUtf8(joined, exports.RESUME_PREVIEW_CONTRACT.budgetBytes);
+    const includedTiers = [...new Set(tierTexts.filter((entry) => entry.text.length > 0).map((entry) => entry.tier))];
+    return { text: finalText, includedTiers };
+}
+function renderBudgetedRehydrateRecovery(args) {
+    const ordered = orderRetrievalPackSegments(args.segments);
+    if (ordered.length === 0) {
+        return { text: '', includedTiers: [], omittedTierCount: 0, truncatedWithinTier: false };
+    }
+    const tiersInOrder = exports.REHYDRATE_RETRIEVAL_CONTRACT.tiers.map((tier) => tier.tier);
+    const sectionsByTier = new Map(tiersInOrder.map((tier) => [tier, ordered.filter((segment) => segment.tier === tier).map((segment) => `### ${segment.title}\n${segment.body}`)]));
+    const renderFromTiers = (tiers) => {
+        const sections = tiers.flatMap((tier) => sectionsByTier.get(tier) ?? []);
+        return sections.length === 0 ? '' : `${args.header}\n\n${sections.join('\n\n')}`;
+    };
+    const initiallyIncludedTiers = tiersInOrder.filter((tier) => (sectionsByTier.get(tier) ?? []).length > 0);
+    let includedTiers = initiallyIncludedTiers;
+    let recoveryText = renderFromTiers(includedTiers);
+    while (encoder.encode(recoveryText).length > constants_js_1.RECOVERY_BUDGET_BYTES) {
+        const droppableTierIndex = [...includedTiers]
+            .reverse()
+            .findIndex((tier) => getTierRetention(tier) === 'tail');
+        if (droppableTierIndex === -1) {
+            break;
+        }
+        const actualIndex = includedTiers.length - 1 - droppableTierIndex;
+        includedTiers = includedTiers.filter((_, index) => index !== actualIndex);
+        recoveryText = renderFromTiers(includedTiers);
+    }
+    const omittedTierCount = initiallyIncludedTiers.length - includedTiers.length;
+    const needsSuffix = omittedTierCount > 0 || encoder.encode(recoveryText).length > constants_js_1.RECOVERY_BUDGET_BYTES || includedTiers.length === 0;
+    const finalText = recoveryText.length === 0
+        ? trimFinalRecoveryText(args.header, initiallyIncludedTiers.length)
+        : !needsSuffix
+            ? recoveryText
+            : trimFinalRecoveryText(recoveryText, omittedTierCount);
+    return {
+        text: finalText,
+        includedTiers,
+        omittedTierCount,
+        truncatedWithinTier: encoder.encode(recoveryText).length > constants_js_1.RECOVERY_BUDGET_BYTES || includedTiers.length === 0,
+    };
+}

package/dist/v2/projections/resume-ranking.d.ts

@@ -1,4 +1,5 @@
 import type { SessionId, WorkflowHash, WorkflowId } from '../durable-core/ids/index.js';
+export { MAX_RESUME_PREVIEW_BYTES } from '../durable-core/constants.js';
 export type RecapSnippet = string & {
     readonly __brand: 'RecapSnippet';
 };

package/dist/v2/projections/resume-ranking.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_RESUME_CANDIDATES = void 0;
+exports.MAX_RESUME_CANDIDATES = exports.MAX_RESUME_PREVIEW_BYTES = void 0;
 exports.asRecapSnippet = asRecapSnippet;
 exports.normalizeToTokens = normalizeToTokens;
 exports.allQueryTokensMatch = allQueryTokensMatch;
@@ -11,7 +11,10 @@ exports.computeQueryRelevanceScore = computeQueryRelevanceScore;
 exports.assignTier = assignTier;
 exports.rankResumeCandidates = rankResumeCandidates;
 const constants_js_1 = require("../durable-core/constants.js");
-const MAX_SNIPPET_BYTES = 1024;
+const retrieval_contract_js_1 = require("../durable-core/domain/retrieval-contract.js");
+var constants_js_2 = require("../durable-core/constants.js");
+Object.defineProperty(exports, "MAX_RESUME_PREVIEW_BYTES", { enumerable: true, get: function () { return constants_js_2.MAX_RESUME_PREVIEW_BYTES; } });
+const MAX_SNIPPET_BYTES = constants_js_1.MAX_RESUME_PREVIEW_BYTES;
 function asRecapSnippet(raw) {
     const stripped = raw.endsWith(constants_js_1.TRUNCATION_MARKER)
         ? raw.slice(0, -constants_js_1.TRUNCATION_MARKER.length)
@@ -145,29 +148,14 @@ function collectMatchReasons(summary, query, tier) {
     return reasons;
 }
 function buildPreviewSnippet(summary, query) {
-    const previewSource = buildSearchableSessionText(summary);
-    if (!previewSource)
+    const segments = [
+        summary.sessionTitle ? (0, retrieval_contract_js_1.createSessionTitlePreviewSegment)(summary.sessionTitle) : null,
+        summary.recapSnippet ? (0, retrieval_contract_js_1.createRecapPreviewSegment)(summary.recapSnippet) : null,
+    ].filter((segment) => segment !== null);
+    if (segments.length === 0)
         return '';
-    const queryTokens = query.freeTextQuery ? [...normalizeToTokens(query.freeTextQuery)] : [];
-    if (queryTokens.length === 0)
-        return summary.recapSnippet ?? previewSource;
-    const lower = previewSource.toLowerCase();
-    let bestIndex = -1;
-    for (const token of queryTokens) {
-        if (token.length < 3)
-            continue;
-        const idx = lower.indexOf(token);
-        if (idx !== -1 && (bestIndex === -1 || idx < bestIndex))
-            bestIndex = idx;
-    }
-    if (bestIndex === -1)
-        return summary.recapSnippet ?? previewSource;
-    const start = Math.max(0, bestIndex - 100);
-    const end = Math.min(previewSource.length, bestIndex + 180);
-    const slice = previewSource.slice(start, end).trim();
-    const prefix = start > 0 ? '...' : '';
-    const suffix = end < previewSource.length ? '...' : '';
-    return `${prefix}${slice}${suffix}`;
+    const focusTerms = query.freeTextQuery ? [...normalizeToTokens(query.freeTextQuery)] : [];
+    return (0, retrieval_contract_js_1.renderBudgetedResumePreview)({ segments, focusTerms }).text;
 }
 function deriveConfidence(tier, reasons) {
     if (tier.kind === 'matched_exact_id' || tier.kind === 'matched_notes')

package/package.json

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

package/workflows/mr-review-workflow.agentic.v2.json

@@ -19,19 +19,22 @@
     "DEFAULT BEHAVIOR: self-execute with tools. Only ask for missing external artifacts, permissions, or business context you cannot resolve yourself.",
     "V2 DURABILITY: use output.notesMarkdown and explicit `continue_workflow` context keys as durable workflow state. Do NOT rely on the review document as required workflow memory.",
     "ARTIFACT STRATEGY: `reviewDocPath` is an optional human-facing artifact only. Create or update it only when it materially improves handoff or readability. Workflow truth lives in notes and explicit context fields.",
+    "NOTES QUALITY: notes should work for both a human reader and a future agent resuming later. For important phases, make clear what was learned, what was decided, what remains uncertain, and what should happen next.",
     "OWNERSHIP & DELEGATION: the main agent owns truth, synthesis, severity calibration, recommendation, and final handoff. Delegate only bounded reviewer or validation work through the WorkRail Executor.",
     "SUBAGENT SYNTHESIS: treat reviewer-family and validator output as evidence, not conclusions. State your current hypothesis before delegation, then say what was confirmed, what was new, what you reject, and what changed your mind.",
     "PARALLELISM: parallelize independent cognition; serialize canonical synthesis, coverage-ledger updates, recommendation decisions, and document writes.",
     "REVIEW MODEL: first build shared understanding, then freeze a neutral fact packet, then let reviewer families challenge it in parallel, then reconcile contradictions explicitly.",
     "COVERAGE LEDGER: explicitly track review domains as `checked`, `uncertain`, `not_applicable`, `contradicted`, or `needs_followup`. Do not finalize with unresolved material gaps unless you name them clearly.",
     "TRIGGERS: WorkRail can only react to explicit fields. Use structural fields such as `contextUnknownCount`, `criticalSurfaceTouched`, `coverageUncertainCount`, `contradictionCount`, `falsePositiveRiskCount`, `blindSpotCount`, and `needsSimulation`.",
+    "BOUNDARY DISCIPLINE: attempt to determine the real review target and the likely ancestor-relative review surface. If that confidence remains weak, continue with downgraded confidence and disclose the limitation clearly instead of pretending certainty.",
+    "SOURCE DISCOVERY: opportunistically recover PR context, ticket/docs context, and repo/user policy context from the strongest available sources. Missing sources should usually lower confidence and be disclosed, not block the workflow.",
     "BOUNDARY: do not post comments, approve, reject, or merge unless the user explicitly asks. Produce findings, recommendation, and handoff material only."
   ],
   "steps": [
     {
       "id": "phase-0-understand-and-classify",
-      "title": "Phase 0: Understand & Classify",
-      "prompt": "Build understanding and classify the review in one pass.\n\nStep 1 — Early exit / minimum inputs:\nBefore exploring, verify that the review target is real and inspectable. If the diff, changed files, or equivalent review material are completely absent and cannot be inferred with tools, ask for the minimum missing artifact and stop. Do NOT ask questions you can resolve with tools.\n\nStep 2 — Explore:\nUse tools to build the minimum complete understanding needed to review accurately. Read independent files in parallel when possible.\n\nGather:\n- MR title and purpose, if discoverable\n- ticket or acceptance-criteria context when available\n- changed files overview and changed-file count\n- module roots, call chain highlights, public contracts, impacted consumers, and repo patterns that matter\n- explicit unknowns, likely blind spots, and whether author intent remains unclear\n- whether any critical surface is touched\n\nStep 3 — Classify after exploration:\nSet:\n- `reviewMode`: QUICK / STANDARD / THOROUGH\n- `riskLevel`: Low / Medium / High\n- `maxParallelism`: 0 / 3 / 5\n- `criticalSurfaceTouched`: true / false\n- `needsSimulation`: true / false\n\nDecision guidance:\n- QUICK: very small, isolated, low-risk changes with little ambiguity\n- STANDARD: typical feature or bug-fix reviews with moderate ambiguity or moderate risk\n- THOROUGH: critical surfaces, architectural novelty, high risk, broad change sets, or strong need for independent reviewer perspectives\n\nStep 4 — Optional deeper context:\nIf `reviewMode` is STANDARD or THOROUGH and understanding still feels incomplete, and delegation is available, spawn TWO WorkRail Executors SIMULTANEOUSLY running `routine-context-gathering` with focus=COMPLETENESS and focus=DEPTH. Synthesize both outputs before finishing this step.\n\nStep 5 — Human-facing artifact:\nChoose `reviewDocPath` only if a live artifact will materially improve human readability. Default suggestion: `mr-review.md` at the project root. This artifact is optional and never canonical workflow state.\n\nSet these keys in the next `continue_workflow` call's `context` object:\n- `mrTitle`\n- `mrPurpose`\n- `ticketContext`\n- `focusAreas`\n- `changedFileCount`\n- `criticalSurfaceTouched`\n- `reviewMode`\n- `riskLevel`\n- `maxParallelism`\n- `reviewDocPath`\n- `contextSummary`\n- `candidateFiles`\n- `moduleRoots`\n- `contextUnknownCount`\n- `coverageGapCount`\n- `authorIntentUnclear`\n- `needsSimulation`\n- `openQuestions`\n\nRules:\n- answer your own questions with tools whenever possible\n- only keep true human-decision questions in `openQuestions`\n- keep `openQuestions` bounded to the minimum necessary\n- if the review target is missing entirely, ask only for that missing artifact\n- classify AFTER exploring, not before",
+      "title": "Phase 0: Locate, Bound, Enrich & Classify",
+      "prompt": "Build the review foundation in one pass.\n\nStep 1 — Early exit / minimum inputs:\nBefore exploring, verify that the review target is real and inspectable. If the diff, changed files, or equivalent review material are completely absent and cannot be inferred with tools, ask for the minimum missing artifact and stop. Do NOT ask questions you can resolve with tools.\n\nStep 2 — Locate and bound the review target:\nAttempt to determine the strongest available review target and boundary.\n\nAttempt to establish:\n- `reviewTargetKind` from the strongest available source such as PR/MR, branch, patch, diff, or local working tree changes\n- `reviewTargetSource` describing where the target came from\n- likely PR/MR identity when available (`prUrl`, `prNumber`)\n- likely base / ancestor reference (`baseCandidate`, `mergeBaseRef`) when available\n- whether the branch may include inherited or out-of-scope changes\n- `boundaryConfidence`: High / Medium / Low\n\nDo not over-prescribe your own investigation path. Use the strongest available evidence and record uncertainty honestly.\n\nStep 3 — Enrich with context:\nRecover the strongest available intent and policy context from whatever sources are actually available.\n\nAttempt to recover:\n- MR title and purpose\n- ticket / issue / acceptance context (`ticketRefs`, `ticketContext`)\n- supporting docs / specs / rollout context (`supportingDocsFound`)\n- repo or user policy/convention context when it is likely to affect review judgment (`policySourcesFound`)\n- `contextConfidence`: High / Medium / Low\n\nStep 4 — Review-surface hygiene:\nClassify the visible change into a minimal review surface.\n\nSet:\n- `coreReviewSurface`\n- `likelyNoiseOrMechanicalChurn`\n- `likelyInheritedOrOutOfScopeChanges`\n- `reviewSurfaceSummary`\n- `reviewScopeWarnings`\n\nThe goal is not a giant ledger. The goal is to avoid treating every visible changed file as equally worthy of deep review by default.\n\nStep 5 — Classify the review:\nAfter exploration, classify the work.\n\nSet:\n- `reviewMode`: QUICK / STANDARD / THOROUGH\n- `riskLevel`: Low / Medium / High\n- `shapeProfile`: choose the best primary label from `isolated_change`, `crosscutting_change`, `mechanically_noisy_change`, or `ambiguous_boundary`\n- `changeTypeProfile`: choose the best primary label from `general_code_change`, `api_contract_change`, `data_model_or_migration`, `security_sensitive`, or `test_only`\n- `maxParallelism`: 0 / 3 / 5\n- `criticalSurfaceTouched`: true / false\n- `needsSimulation`: true / false\n- `needsBoundaryFollowup`: true / false\n- `needsContextFollowup`: true / false\n- `needsReviewerBundle`: true / false\n\nDecision guidance:\n- QUICK: very small, isolated, low-risk changes with little ambiguity\n- STANDARD: typical feature or bug-fix reviews with moderate ambiguity or moderate risk\n- THOROUGH: critical surfaces, architectural novelty, high risk, broad change sets, or strong need for independent reviewer perspectives\n\nMinimal routing guidance:\n- if `boundaryConfidence = Low`, bias toward boundary/context follow-up before strong recommendation confidence\n- if `changeTypeProfile = api_contract_change`, bias toward contract/consumer/backward-compatibility scrutiny\n- if `changeTypeProfile = data_model_or_migration`, bias toward rollout / compatibility / simulation scrutiny\n- if `changeTypeProfile = security_sensitive`, bias toward adversarial/runtime-risk scrutiny and lower tolerance for weak evidence\n- if `changeTypeProfile = test_only`, bias toward stronger false-positive suppression\n- if `shapeProfile = mechanically_noisy_change`, bias toward stronger noise filtering and lower appetite for style-only findings\n\nStep 6 — Optional deeper context:\nIf `reviewMode` is STANDARD or THOROUGH and context remains incomplete, and delegation is available, spawn TWO WorkRail Executors SIMULTANEOUSLY running `routine-context-gathering` with focus=COMPLETENESS and focus=DEPTH. Synthesize both outputs before finishing this step.\n\nStep 7 — Human-facing artifact:\nChoose `reviewDocPath` only if a live artifact will materially improve human readability. Default suggestion: `mr-review.md` at the project root. This artifact is optional and never canonical workflow state.\n\nFallback behavior:\n- if PR/MR is not found but a branch/diff is inspectable, continue with downgraded context confidence and disclose missing PR context later\n- if the branch is inspectable but merge-base / ancestor remains ambiguous, continue with downgraded boundary confidence, set `needsBoundaryFollowup = true`, and disclose the uncertainty later\n- if ticket or supporting docs are missing, continue with downgraded context confidence and avoid overclaiming intent-sensitive findings\n- if only a patch/diff is available, continue if it is inspectable, but keep lower confidence on intent/boundary-dependent conclusions\n- if the review target itself is missing, ask only for that missing artifact and stop\n\nSet these keys in the next `continue_workflow` call's `context` object:\n- `reviewTargetKind`\n- `reviewTargetSource`\n- `prUrl`\n- `prNumber`\n- `baseCandidate`\n- `mergeBaseRef`\n- `boundaryConfidence`\n- `contextConfidence`\n- `mrTitle`\n- `mrPurpose`\n- `ticketRefs`\n- `ticketContext`\n- `supportingDocsFound`\n- `policySourcesFound`\n- `accessibleContextSources`\n- `missingContextSources`\n- `focusAreas`\n- `changedFileCount`\n- `criticalSurfaceTouched`\n- `reviewMode`\n- `riskLevel`\n- `shapeProfile`\n- `changeTypeProfile`\n- `maxParallelism`\n- `reviewDocPath`\n- `contextSummary`\n- `candidateFiles`\n- `moduleRoots`\n- `contextUnknownCount`\n- `coverageGapCount`\n- `authorIntentUnclear`\n- `needsSimulation`\n- `needsBoundaryFollowup`\n- `needsContextFollowup`\n- `needsReviewerBundle`\n- `coreReviewSurface`\n- `likelyNoiseOrMechanicalChurn`\n- `likelyInheritedOrOutOfScopeChanges`\n- `reviewSurfaceSummary`\n- `reviewScopeWarnings`\n- `openQuestions`\n\nRules:\n- answer your own questions with tools whenever possible\n- only keep true human-decision questions in `openQuestions`\n- keep `openQuestions` bounded to the minimum necessary\n- classify AFTER exploring, not before\n- before leaving this phase, either establish the likely review boundary or explicitly record why you could not",
       "requireConfirmation": {
         "or": [
           { "var": "reviewMode", "equals": "THOROUGH" },
@@ -58,12 +61,13 @@
           "Keep `recommendationHypothesis` as a secondary hypothesis to challenge, not a frame to defend."
         ],
         "procedure": [
-          "Create a neutral `reviewFactPacket` containing: MR purpose and expected behavior change, changed files and module roots, key contracts / invariants / affected consumers, call-chain highlights, relevant repo patterns and exemplars, tests/docs expectations, and explicit open unknowns.",
+          "Create a neutral `reviewFactPacket` containing: MR purpose and expected behavior change, review target and review-surface summary, changed files and module roots, key contracts / invariants / affected consumers, call-chain highlights, relevant repo patterns and exemplars, tests/docs expectations, discovered ticket/doc/policy context, accessible and missing context sources, and explicit open unknowns.",
           "Initialize `coverageLedger` for these domains: `correctness_logic`, `contracts_invariants`, `patterns_architecture`, `runtime_production_risk`, `tests_docs_rollout`, `security_performance`.",
           "Perform a preliminary self-review from the fact packet before choosing reviewer families.",
           "Reviewer family options: `correctness_invariants`, `patterns_architecture`, `runtime_production_risk`, `test_docs_rollout`, `false_positive_skeptic`, `missed_issue_hunter`.",
           "Selection guidance: QUICK = no bundle by default unless ambiguity still feels material; STANDARD = 3 families by default; THOROUGH = 5 families by default.",
           "Always include `correctness_invariants` unless clearly not applicable. Include `test_docs_rollout` in STANDARD and THOROUGH unless clearly not applicable. Include `runtime_production_risk` when `criticalSurfaceTouched = true` or `needsSimulation = true`. Include `missed_issue_hunter` in THOROUGH. Include `false_positive_skeptic` when Major/Critical findings seem plausible or severity inflation risk is non-trivial.",
+          "Routing guidance: for `api_contract_change`, bias toward contract / consumer / backward-compatibility scrutiny; for `data_model_or_migration`, bias toward rollout / compatibility / simulation scrutiny; for `security_sensitive`, bias toward runtime-risk scrutiny and lower tolerance for weak evidence; for `test_only`, bias toward stronger false-positive suppression; for `mechanically_noisy_change`, bias toward stronger noise filtering and lower appetite for style-only findings.",
           "Set `coverageUncertainCount` as the number of coverage domains not yet safely closed: `uncertain` + `contradicted` + `needs_followup`.",
           "Initialize `contradictionCount`, `blindSpotCount`, and `falsePositiveRiskCount` to `0` if no reviewer-family bundle will run."
         ],
@@ -191,8 +195,9 @@
           "Before delegating, state: what is your current recommendation, where are you least confident, and what finding would most likely change your mind now?",
           "Mode-adaptive validation: QUICK = self-validate and optionally spawn ONE WorkRail Executor running `routine-hypothesis-challenge` if a serious uncertainty remains; STANDARD = if validation is required and delegation is available, spawn TWO WorkRail Executors SIMULTANEOUSLY running `routine-hypothesis-challenge` and either `routine-execution-simulation` or `routine-plan-analysis`; THOROUGH = if validation is required and delegation is available, spawn THREE WorkRail Executors SIMULTANEOUSLY running `routine-hypothesis-challenge`, `routine-execution-simulation` when needed, and `routine-plan-analysis`.",
           "After receiving validator output, explicitly synthesize what was confirmed, what was new, what appears weak, and whether your recommendation changed.",
+          "Perform a compact confidence assessment using these dimensions: `boundaryConfidence`, `intentConfidence`, `evidenceConfidence`, `coverageConfidence`, and `consensusConfidence`. Rate each as High / Medium / Low, explain each in one sentence, and then derive final recommendation confidence with these rules: if boundary is Low, final confidence is Low; else if evidence is Low, final confidence is Low; else if 2 or more dimensions are Medium, final confidence is Medium; else if all key dimensions are High, final confidence is High. Unresolved disagreement can only lower confidence, never raise it.",
           "Compute `docCompletenessConcernCount` by counting one concern for each material packaging gap: missing rationale for any Critical or Major finding, missing ready-to-post MR comment for any Critical or Major finding, recommendation mismatch with canonical findings, still-uncertain / contradicted / needs-followup coverage domains not summarized clearly, or any missing required final section needed for actionability.",
-          "Set these keys in the next `continue_workflow` call's `context` object: `validatorConsensusLevel`, `validationSummary`, `recommendationConfidenceBand`, `docCompletenessConcernCount`."
+          "Set these keys in the next `continue_workflow` call's `context` object: `intentConfidence`, `evidenceConfidence`, `coverageConfidence`, `consensusConfidence`, `confidenceAssessmentSummary`, `validatorConsensusLevel`, `validationSummary`, `recommendationConfidenceBand`, `docCompletenessConcernCount`."
         ],
         "verify": [
           "If 2+ validators still raise serious concerns, confidence is downgraded and synthesis is reopened.",
@@ -210,7 +215,7 @@
     {
       "id": "phase-6-final-handoff",
       "title": "Phase 6: Final Handoff",
-      "prompt": "Provide the final MR review handoff.\n\nInclude:\n- MR title and purpose\n- review mode used\n- final recommendation and confidence band\n- counts of Critical / Major / Minor / Nit findings\n- top findings with rationale\n- strongest remaining areas of uncertainty, if any\n- summary of the coverage ledger, especially any still-uncertain domains\n- ready-to-post MR comments summary\n- any validation outcomes a human reviewer should see\n- path to the full human-facing review artifact (`reviewDocPath`) only if one was created\n\nRules:\n- the final recommendation assists a human reviewer; it does not replace them\n- if `reviewDocPath` exists, treat it as a human-facing companion artifact only\n- do not post comments, approve, reject, or merge unless the user explicitly asks",
+      "prompt": "Provide the final MR review handoff.\n\nInclude:\n- MR title and purpose\n- review mode used\n- final recommendation and confidence band\n- confidence assessment summary, including the most important reason confidence was capped if it was not High\n- counts of Critical / Major / Minor / Nit findings\n- top findings with rationale\n- strongest remaining areas of uncertainty, if any\n- summary of the coverage ledger, especially any still-uncertain domains\n- ready-to-post MR comments summary\n- any validation outcomes a human reviewer should see\n- review environment status:\n  - what review target/context sources were successfully used\n  - what important sources were missing or ambiguous\n  - boundary confidence and context confidence\n  - how those limits affected the review\n- path to the full human-facing review artifact (`reviewDocPath`) only if one was created\n\nRules:\n- the final recommendation assists a human reviewer; it does not replace them\n- if `reviewDocPath` exists, treat it as a human-facing companion artifact only\n- be explicit when missing PR/ticket/doc/boundary context limited confidence\n- do not post comments, approve, reject, or merge unless the user explicitly asks",
       "requireConfirmation": true
     }
   ]