@exaudeus/workrail 3.9.1 → 3.10.0

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.1",
+  "version": "3.10.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {

package/spec/workflow.schema.json

@@ -20,7 +20,7 @@
     },
     "description": {
       "type": "string",
-      "description": "What this workflow accomplishes",
+      "description": "What this workflow accomplishes. Prefer clear user-facing language for bundled/user-facing workflows; schema does not enforce prose style.",
       "minLength": 1,
       "maxLength": 512
     },
@@ -42,7 +42,7 @@
     },
     "clarificationPrompts": {
       "type": "array",
-      "description": "Questions to ask upfront to resolve ambiguities",
+      "description": "Questions to ask upfront to resolve ambiguities. Prefer direct, user-grounded wording over abstract framework narration.",
       "items": {
         "type": "string",
         "minLength": 1,
@@ -67,7 +67,7 @@
     },
     "metaGuidance": {
       "type": "array",
-      "description": "Persistent behavioral rules surfaced on start and resume. Not repeated on every step advance. For external document pointers, use 'references' instead.",
+      "description": "Persistent behavioral rules surfaced on start and resume. Not repeated on every step advance. Use this to define quality bars and anti-failure guidance without rigidly scripting every thought. For external document pointers, use 'references' instead.",
       "items": {
         "type": "string",
         "minLength": 1,
@@ -127,7 +127,7 @@
     },
     "features": {
       "type": "array",
-      "description": "Compiler features to apply to this workflow (e.g. wr.features.memory_context). Features inject content into promptBlocks at compile time.",
+      "description": "Compiler features to apply to this workflow (e.g. wr.features.memory_context). Features inject content into promptBlocks at compile time and work best when the workflow uses structured promptBlocks instead of relying entirely on raw prompt prose.",
       "items": {
         "type": "string",
         "minLength": 1,
@@ -137,7 +137,7 @@
     },
     "extensionPoints": {
       "type": "array",
-      "description": "Bounded cognitive slots that users can customize via .workrail/bindings.json. Each slot is referenced in step prompts via {{wr.bindings.slotId}} and resolved at compile time.",
+      "description": "Bounded cognitive slots that users can customize via .workrail/bindings.json. Each slot is referenced in step prompts via {{wr.bindings.slotId}} and resolved at compile time. Use extension points for bounded cognitive units, not for core orchestration or final synthesis ownership.",
       "items": {
         "$ref": "#/$defs/extensionPoint"
       },
@@ -163,7 +163,7 @@
   "$defs": {
     "extensionPoint": {
       "type": "object",
-      "description": "A bounded cognitive slot that can be customized via .workrail/bindings.json",
+      "description": "A bounded cognitive slot that can be customized via .workrail/bindings.json. Good uses include candidate generation, review, and validation passes; poor uses include replacing the parent workflow's core orchestration contract.",
       "properties": {
         "slotId": {
           "type": "string",
@@ -283,7 +283,7 @@
       "properties": {
         "id": { "$ref": "#/$defs/stepId", "description": "Unique identifier for the step" },
         "title": { "type": "string", "minLength": 1, "maxLength": 128 },
-        "prompt": { "type": "string", "minLength": 1, "maxLength": 8192 },
+        "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Traditional single-string prompt. Use when structure is simple; prefer promptBlocks when you need stronger quality bars without over-scripting cognition." },
         "promptBlocks": { "$ref": "#/$defs/promptBlocks" },
         "agentRole": { "type": "string", "minLength": 10, "maxLength": 1024 },
         "guidance": { "type": "array", "items": { "type": "string" } },

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
     }
   ]