@exaudeus/workrail 0.14.0 → 0.16.0

package/dist/manifest.json

@@ -550,8 +550,8 @@
       "bytes": 1748
     },
     "mcp/handlers/workflow.js": {
-      "sha256": "99ff7aac9705ef540cc5681515cf2aa9650d886761f7ae69f829ff87ac772756",
-      "bytes": 8246
+      "sha256": "7ebd383922c6f238c35c376c8a0aa87b0969a80bb4e7c48e704a8480fd974bb4",
+      "bytes": 8254
     },
     "mcp/index.d.ts": {
       "sha256": "525b4247cf90ba3af66769462bcfaab5dbf38ee8c49d2a9ceec1e4b38e33511b",
@@ -574,8 +574,8 @@
       "bytes": 168
     },
     "mcp/server.js": {
-      "sha256": "41c61033d821f9794cada0bb40058fa220fa11175897326ae597df422a1fcd0b",
-      "bytes": 13552
+      "sha256": "cf128711a6d74bb604653431c9e3bac4fac9fed94bd4da8326438e86809501e3",
+      "bytes": 13866
     },
     "mcp/tool-description-provider.d.ts": {
       "sha256": "1d46abc3112e11b68e57197e846f5708293ec9b2281fa71a9124ee2aad71e41b",
@@ -590,8 +590,8 @@
       "bytes": 132
     },
     "mcp/tool-descriptions.js": {
-      "sha256": "06a6eff077301d66a90b6240fbebae166ddfdcd3aa9177d5cfb48d6e0a31698c",
-      "bytes": 7792
+      "sha256": "c8150119782dadd286e8430e9377b0b727891c414be2396e314423713939d6eb",
+      "bytes": 7980
     },
     "mcp/tool-factory.d.ts": {
       "sha256": "0fe3c6b863b2d7aef0c3d659ff54f3a9ee8a0a3c2005b6565d2f8ad517bc7211",
@@ -602,12 +602,12 @@
       "bytes": 479
     },
     "mcp/tools.d.ts": {
-      "sha256": "f11991cdc3cdbd2912c38252541818adaca8a99c08cc7c1aaa37636ae112cfd6",
-      "bytes": 5952
+      "sha256": "8474e810cae37197d5968be4c3dfb9751ba2b09fe8a7f39e0e7dcc414af4bdb5",
+      "bytes": 5976
     },
     "mcp/tools.js": {
-      "sha256": "34522d0b078477627fe068130d3b0a5d4d8cc9fc90599a583d979080d632f544",
-      "bytes": 7688
+      "sha256": "0af59932b32bad5ebc9cbc925279d325350c91b43085561d0d218035250b641a",
+      "bytes": 8020
     },
     "mcp/types.d.ts": {
       "sha256": "4ab4a4af1eeedf9ba9bcdc70476a5adcc24ce05b3d7d715d70979052b1eb7246",
@@ -638,8 +638,8 @@
       "bytes": 2579
     },
     "mcp/v2/tools.js": {
-      "sha256": "9e934ea8a5f83bffc68d343970292267b207f67d72a5aa824348967e53777820",
-      "bytes": 2333
+      "sha256": "4b0d5d1c019d3f747b0f4211a606d1aba4944f9e570ae9fecc6831987a6cc16f",
+      "bytes": 2537
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",
@@ -649,6 +649,54 @@
       "sha256": "0134fd92e1b160f1b57230d9f8a471044858af43484206f911619cf7159e3f0d",
       "bytes": 834
     },
+    "mcp/validation/index.d.ts": {
+      "sha256": "3e3f12357fd8214470d111454e4002338e5eb93329b5a3758664db51e44c12ec",
+      "bytes": 944
+    },
+    "mcp/validation/index.js": {
+      "sha256": "dccd3a2dc7e486afd27ee44f77303486f60cc840563821b97ac341f9cad6650c",
+      "bytes": 4445
+    },
+    "mcp/validation/schema-introspection.d.ts": {
+      "sha256": "7e0262e76234dd37079156027e95a30987b8949351f3e9ec0fd7b2be093a159d",
+      "bytes": 713
+    },
+    "mcp/validation/schema-introspection.js": {
+      "sha256": "850c09a3c01a5f22440ebc34236c393f3b428748210f5277258a9905cb847d71",
+      "bytes": 5293
+    },
+    "mcp/validation/string-similarity.d.ts": {
+      "sha256": "4326210a768a526336b54d4ea20a128a939d92f53e8b2a5a33da06b5372d196a",
+      "bytes": 671
+    },
+    "mcp/validation/string-similarity.js": {
+      "sha256": "fafdb80673ad56336009e562cd5dccd93486dd94fa78acbb923cdc47ba63becf",
+      "bytes": 2627
+    },
+    "mcp/validation/suggestion-config.d.ts": {
+      "sha256": "70b8395db74ec18bb1ef2309dd16516345b75839d2793bf9c5bfbd1e1d1baa0e",
+      "bytes": 388
+    },
+    "mcp/validation/suggestion-config.js": {
+      "sha256": "efda43e48812979d0ddae2abe23809b6b5a3e5b955e74ca5a67716933e468db4",
+      "bytes": 592
+    },
+    "mcp/validation/suggestion-generator.d.ts": {
+      "sha256": "491d983f4a03516fc0ba09ff40da2c859ec600f29a41093b0359ba549c7882cc",
+      "bytes": 450
+    },
+    "mcp/validation/suggestion-generator.js": {
+      "sha256": "e952a4d3cb569222cde1bd01dd9d5be887ee394ba007478bbb446fa177172859",
+      "bytes": 4075
+    },
+    "mcp/validation/suggestion-types.d.ts": {
+      "sha256": "b93ae2e42f4b24789dcbe19db31a41af9534ad0dca85635339c2a10db42e298b",
+      "bytes": 1333
+    },
+    "mcp/validation/suggestion-types.js": {
+      "sha256": "c7753960a199508a8a59f8030c4240a076857a3e5926efadc01e808f08d7ff3a",
+      "bytes": 729
+    },
     "mcp/validation/workflow-next-prevalidate.d.ts": {
       "sha256": "179058225dfb17f4be02d6105bbacdaa99f1441cfc25062b38d8283f0bf35b5a",
       "bytes": 254

package/dist/mcp/handlers/workflow.js

@@ -65,7 +65,7 @@ async function handleWorkflowGet(input, ctx) {
     try {
         const { createGetWorkflow } = await Promise.resolve().then(() => __importStar(require('../../application/use-cases/get-workflow.js')));
         const getWorkflowUseCase = createGetWorkflow(ctx.workflowService);
-        const result = await withTimeout(getWorkflowUseCase(input.id, input.mode), TIMEOUT_MS, 'workflow_get');
+        const result = await withTimeout(getWorkflowUseCase(input.workflowId, input.mode), TIMEOUT_MS, 'workflow_get');
         if (result.isErr()) {
             const mapped = (0, error_mapper_js_1.mapDomainErrorToToolError)(result.error);
             return mapped;

package/dist/mcp/server.js

@@ -42,6 +42,7 @@ const types_js_1 = require("./types.js");
 const tool_factory_js_1 = require("./tool-factory.js");
 const workflow_next_prevalidate_js_1 = require("./validation/workflow-next-prevalidate.js");
 const bounded_json_js_1 = require("./validation/bounded-json.js");
+const index_js_1 = require("./validation/index.js");
 const tools_js_1 = require("./tools.js");
 const tool_registry_js_1 = require("./v2/tool-registry.js");
 const workflow_js_1 = require("./handlers/workflow.js");
@@ -133,11 +134,14 @@ function createHandler(schema, handler) {
     return async (args, ctx) => {
         const parseResult = schema.safeParse(args);
         if (!parseResult.success) {
+            const suggestionResult = (0, index_js_1.generateSuggestions)(args, schema, index_js_1.DEFAULT_SUGGESTION_CONFIG);
+            const suggestionDetails = (0, index_js_1.formatSuggestionDetails)(suggestionResult);
             return toMcpResult((0, types_js_1.errNotRetryable)('VALIDATION_ERROR', 'Invalid input', {
                 validationErrors: parseResult.error.errors.map(e => ({
                     path: e.path.join('.'),
                     message: e.message,
                 })),
+                ...suggestionDetails,
             }));
         }
         return toMcpResult(await handler(parseResult.data, ctx));

package/dist/mcp/tool-descriptions.js

@@ -10,7 +10,11 @@ Your process:
 2. Analyze the returned descriptions to find a match for the user's goal.
 3. If a good match is found, suggest it to the user and use preview_workflow to start.
 4. If NO match is found, inform the user and then attempt to solve the task using your general abilities.`,
-        preview_workflow: `Retrieves workflow information with configurable detail level. Supports progressive disclosure to prevent "workflow spoiling" while providing necessary context for workflow selection and initiation.`,
+        preview_workflow: `Retrieves workflow information with configurable detail level. Supports progressive disclosure to prevent "workflow spoiling" while providing necessary context for workflow selection and initiation.
+
+Parameters:
+- workflowId: The unique identifier of the workflow to retrieve
+- mode (optional): 'metadata' for overview only, 'preview' (default) for first step`,
         advance_workflow: `Executes one workflow step at a time by returning the next eligible step and an updated execution state.
 
 Inputs:
@@ -75,7 +79,9 @@ By retrieving a workflow, you agree to:
 
 The workflow content is the user's will expressed as structured steps. Treat each step as a direct instruction from the user.
 
-Returns: Workflow metadata and first step. Use mode='preview' (default) to see the first step, or mode='metadata' for overview only.`,
+Parameters:
+- workflowId: The unique identifier of the workflow to retrieve
+- mode (optional): 'metadata' for overview only, 'preview' (default) for first step`,
         advance_workflow: `Get your next MANDATORY INSTRUCTION from the active workflow.
 
 The step returned is a DIRECT INSTRUCTION from the user. You MUST:

package/dist/mcp/tools.d.ts

@@ -3,13 +3,13 @@ export type { ToolAnnotations, ToolDefinition } from './tool-factory.js';
 export declare const WorkflowListInput: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 export type WorkflowListInput = z.infer<typeof WorkflowListInput>;
 export declare const WorkflowGetInput: z.ZodObject<{
-    id: z.ZodString;
+    workflowId: z.ZodString;
     mode: z.ZodDefault<z.ZodEnum<["metadata", "preview"]>>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
+    workflowId: string;
     mode: "metadata" | "preview";
 }, {
-    id: string;
+    workflowId: string;
     mode?: "metadata" | "preview" | undefined;
 }>;
 export type WorkflowGetInput = z.infer<typeof WorkflowGetInput>;

package/dist/mcp/tools.js

@@ -6,9 +6,9 @@ const state_js_1 = require("../domain/execution/state.js");
 const event_js_1 = require("../domain/execution/event.js");
 exports.WorkflowListInput = zod_1.z.object({});
 exports.WorkflowGetInput = zod_1.z.object({
-    id: zod_1.z
+    workflowId: zod_1.z
         .string()
-        .regex(/^[A-Za-z0-9_-]+$/, 'ID must contain only letters, numbers, hyphens, and underscores')
+        .regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores')
         .describe('The unique identifier of the workflow to retrieve'),
     mode: zod_1.z
         .enum(['metadata', 'preview'])
@@ -97,6 +97,7 @@ exports.WORKFLOW_TOOL_TITLES = {
 exports.CreateSessionInput = zod_1.z.object({
     workflowId: zod_1.z
         .string()
+        .regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores')
         .describe('Workflow identifier (e.g., "bug-investigation", "mr-review")'),
     sessionId: zod_1.z
         .string()
@@ -107,14 +108,14 @@ exports.CreateSessionInput = zod_1.z.object({
         .describe('Initial session data. Can include dashboard, phases, etc.'),
 });
 exports.UpdateSessionInput = zod_1.z.object({
-    workflowId: zod_1.z.string().describe('Workflow identifier'),
+    workflowId: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('Workflow identifier'),
     sessionId: zod_1.z.string().describe('Session identifier'),
     updates: zod_1.z
         .record(zod_1.z.unknown())
         .describe('Data to merge into session. Supports nested updates via dot notation.'),
 });
 exports.ReadSessionInput = zod_1.z.object({
-    workflowId: zod_1.z.string().describe('Workflow identifier'),
+    workflowId: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('Workflow identifier'),
     sessionId: zod_1.z.string().describe('Session identifier'),
     path: zod_1.z
         .string()

package/dist/mcp/v2/tools.js

@@ -4,11 +4,11 @@ exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2ContinueWorkflo
 const zod_1 = require("zod");
 exports.V2ListWorkflowsInput = zod_1.z.object({});
 exports.V2InspectWorkflowInput = zod_1.z.object({
-    workflowId: zod_1.z.string().min(1).describe('The workflow ID to inspect'),
+    workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to inspect'),
     mode: zod_1.z.enum(['metadata', 'preview']).default('preview').describe('Detail level'),
 });
 exports.V2StartWorkflowInput = zod_1.z.object({
-    workflowId: zod_1.z.string().min(1).describe('The workflow ID to start'),
+    workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to start'),
     context: zod_1.z.record(zod_1.z.unknown()).optional().describe('External context inputs (conditions, parameters). Do not include workflow progress state.'),
 });
 exports.V2ContinueWorkflowInput = zod_1.z.object({

package/dist/mcp/validation/index.d.ts

@@ -0,0 +1,7 @@
+export type { Similarity, ValidationSuggestion, UnknownKeySuggestion, MissingRequiredSuggestion, InvalidEnumSuggestion, SuggestionResult, } from './suggestion-types.js';
+export { similarity, EMPTY_SUGGESTION_RESULT, isUnknownKeySuggestion, isMissingRequiredSuggestion, isInvalidEnumSuggestion, } from './suggestion-types.js';
+export type { SuggestionConfig } from './suggestion-config.js';
+export { DEFAULT_SUGGESTION_CONFIG, MINIMAL_SUGGESTION_CONFIG } from './suggestion-config.js';
+export { levenshteinDistance, computeSimilarity, computeSimilarityIgnoreCase, findClosestMatch, findAllMatches, type ClosestMatch, } from './string-similarity.js';
+export { extractExpectedKeys, extractRequiredKeys, findUnknownKeys, findMissingRequiredKeys, generateExampleValue, generateTemplate, extractEnumValues, } from './schema-introspection.js';
+export { generateSuggestions, formatSuggestionDetails, hasSuggestions, } from './suggestion-generator.js';

package/dist/mcp/validation/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSuggestions = exports.formatSuggestionDetails = exports.generateSuggestions = exports.extractEnumValues = exports.generateTemplate = exports.generateExampleValue = exports.findMissingRequiredKeys = exports.findUnknownKeys = exports.extractRequiredKeys = exports.extractExpectedKeys = exports.findAllMatches = exports.findClosestMatch = exports.computeSimilarityIgnoreCase = exports.computeSimilarity = exports.levenshteinDistance = exports.MINIMAL_SUGGESTION_CONFIG = exports.DEFAULT_SUGGESTION_CONFIG = exports.isInvalidEnumSuggestion = exports.isMissingRequiredSuggestion = exports.isUnknownKeySuggestion = exports.EMPTY_SUGGESTION_RESULT = exports.similarity = void 0;
+var suggestion_types_js_1 = require("./suggestion-types.js");
+Object.defineProperty(exports, "similarity", { enumerable: true, get: function () { return suggestion_types_js_1.similarity; } });
+Object.defineProperty(exports, "EMPTY_SUGGESTION_RESULT", { enumerable: true, get: function () { return suggestion_types_js_1.EMPTY_SUGGESTION_RESULT; } });
+Object.defineProperty(exports, "isUnknownKeySuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isUnknownKeySuggestion; } });
+Object.defineProperty(exports, "isMissingRequiredSuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isMissingRequiredSuggestion; } });
+Object.defineProperty(exports, "isInvalidEnumSuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isInvalidEnumSuggestion; } });
+var suggestion_config_js_1 = require("./suggestion-config.js");
+Object.defineProperty(exports, "DEFAULT_SUGGESTION_CONFIG", { enumerable: true, get: function () { return suggestion_config_js_1.DEFAULT_SUGGESTION_CONFIG; } });
+Object.defineProperty(exports, "MINIMAL_SUGGESTION_CONFIG", { enumerable: true, get: function () { return suggestion_config_js_1.MINIMAL_SUGGESTION_CONFIG; } });
+var string_similarity_js_1 = require("./string-similarity.js");
+Object.defineProperty(exports, "levenshteinDistance", { enumerable: true, get: function () { return string_similarity_js_1.levenshteinDistance; } });
+Object.defineProperty(exports, "computeSimilarity", { enumerable: true, get: function () { return string_similarity_js_1.computeSimilarity; } });
+Object.defineProperty(exports, "computeSimilarityIgnoreCase", { enumerable: true, get: function () { return string_similarity_js_1.computeSimilarityIgnoreCase; } });
+Object.defineProperty(exports, "findClosestMatch", { enumerable: true, get: function () { return string_similarity_js_1.findClosestMatch; } });
+Object.defineProperty(exports, "findAllMatches", { enumerable: true, get: function () { return string_similarity_js_1.findAllMatches; } });
+var schema_introspection_js_1 = require("./schema-introspection.js");
+Object.defineProperty(exports, "extractExpectedKeys", { enumerable: true, get: function () { return schema_introspection_js_1.extractExpectedKeys; } });
+Object.defineProperty(exports, "extractRequiredKeys", { enumerable: true, get: function () { return schema_introspection_js_1.extractRequiredKeys; } });
+Object.defineProperty(exports, "findUnknownKeys", { enumerable: true, get: function () { return schema_introspection_js_1.findUnknownKeys; } });
+Object.defineProperty(exports, "findMissingRequiredKeys", { enumerable: true, get: function () { return schema_introspection_js_1.findMissingRequiredKeys; } });
+Object.defineProperty(exports, "generateExampleValue", { enumerable: true, get: function () { return schema_introspection_js_1.generateExampleValue; } });
+Object.defineProperty(exports, "generateTemplate", { enumerable: true, get: function () { return schema_introspection_js_1.generateTemplate; } });
+Object.defineProperty(exports, "extractEnumValues", { enumerable: true, get: function () { return schema_introspection_js_1.extractEnumValues; } });
+var suggestion_generator_js_1 = require("./suggestion-generator.js");
+Object.defineProperty(exports, "generateSuggestions", { enumerable: true, get: function () { return suggestion_generator_js_1.generateSuggestions; } });
+Object.defineProperty(exports, "formatSuggestionDetails", { enumerable: true, get: function () { return suggestion_generator_js_1.formatSuggestionDetails; } });
+Object.defineProperty(exports, "hasSuggestions", { enumerable: true, get: function () { return suggestion_generator_js_1.hasSuggestions; } });

package/dist/mcp/validation/schema-introspection.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare function extractExpectedKeys(schema: z.ZodType): readonly string[];
+export declare function extractRequiredKeys(schema: z.ZodType): readonly string[];
+export declare function findUnknownKeys(args: unknown, schema: z.ZodType): readonly string[];
+export declare function findMissingRequiredKeys(args: unknown, schema: z.ZodType): readonly string[];
+export declare function generateExampleValue(schema: z.ZodType, depth?: number, maxDepth?: number): unknown;
+export declare function generateTemplate(schema: z.ZodType, maxDepth?: number): Readonly<Record<string, unknown>> | null;
+export declare function extractEnumValues(schema: z.ZodType, path: string): readonly string[];

package/dist/mcp/validation/schema-introspection.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractExpectedKeys = extractExpectedKeys;
+exports.extractRequiredKeys = extractRequiredKeys;
+exports.findUnknownKeys = findUnknownKeys;
+exports.findMissingRequiredKeys = findMissingRequiredKeys;
+exports.generateExampleValue = generateExampleValue;
+exports.generateTemplate = generateTemplate;
+exports.extractEnumValues = extractEnumValues;
+const zod_1 = require("zod");
+function extractExpectedKeys(schema) {
+    if (schema instanceof zod_1.z.ZodObject) {
+        return Object.keys(schema._def.shape());
+    }
+    return [];
+}
+function extractRequiredKeys(schema) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return [];
+    }
+    const shape = schema._def.shape();
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const field = value;
+        if (!(field instanceof zod_1.z.ZodOptional) && !(field instanceof zod_1.z.ZodDefault)) {
+            required.push(key);
+        }
+    }
+    return required;
+}
+function findUnknownKeys(args, schema) {
+    if (typeof args !== 'object' || args === null) {
+        return [];
+    }
+    const expectedKeys = new Set(extractExpectedKeys(schema));
+    const providedKeys = Object.keys(args);
+    return providedKeys.filter(key => !expectedKeys.has(key));
+}
+function findMissingRequiredKeys(args, schema) {
+    if (typeof args !== 'object' || args === null) {
+        return extractRequiredKeys(schema);
+    }
+    const providedKeys = new Set(Object.keys(args));
+    const requiredKeys = extractRequiredKeys(schema);
+    return requiredKeys.filter(key => !providedKeys.has(key));
+}
+function generateExampleValue(schema, depth = 0, maxDepth = 3) {
+    if (depth > maxDepth) {
+        return '...';
+    }
+    if (schema instanceof zod_1.z.ZodDefault) {
+        return schema._def.defaultValue();
+    }
+    if (schema instanceof zod_1.z.ZodOptional) {
+        return generateExampleValue(schema._def.innerType, depth, maxDepth);
+    }
+    if (schema instanceof zod_1.z.ZodObject) {
+        const shape = schema._def.shape();
+        const result = {};
+        for (const [key, value] of Object.entries(shape)) {
+            const field = value;
+            if (field instanceof zod_1.z.ZodOptional)
+                continue;
+            result[key] = generateExampleValue(field, depth + 1, maxDepth);
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodDiscriminatedUnion) {
+        const options = schema._def.options;
+        if (options.length > 0) {
+            return generateExampleValue(options[0], depth + 1, maxDepth);
+        }
+        return {};
+    }
+    if (schema instanceof zod_1.z.ZodString) {
+        const description = schema._def.description;
+        if (description) {
+            return `<${description}>`;
+        }
+        return '<string>';
+    }
+    if (schema instanceof zod_1.z.ZodNumber) {
+        return '<number>';
+    }
+    if (schema instanceof zod_1.z.ZodBoolean) {
+        return '<boolean>';
+    }
+    if (schema instanceof zod_1.z.ZodArray) {
+        return [];
+    }
+    if (schema instanceof zod_1.z.ZodEnum) {
+        const values = schema._def.values;
+        if (values.length > 0) {
+            return values[0];
+        }
+        return '<enum>';
+    }
+    if (schema instanceof zod_1.z.ZodLiteral) {
+        return schema._def.value;
+    }
+    if (schema instanceof zod_1.z.ZodRecord) {
+        return {};
+    }
+    if (schema instanceof zod_1.z.ZodUnknown || schema instanceof zod_1.z.ZodAny) {
+        return '<any>';
+    }
+    if (schema instanceof zod_1.z.ZodEffects) {
+        return generateExampleValue(schema._def.schema, depth, maxDepth);
+    }
+    return '<unknown>';
+}
+function generateTemplate(schema, maxDepth = 3) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return null;
+    }
+    const example = generateExampleValue(schema, 0, maxDepth);
+    if (typeof example === 'object' && example !== null) {
+        return example;
+    }
+    return null;
+}
+function extractEnumValues(schema, path) {
+    const parts = path.split('.');
+    let current = schema;
+    for (const part of parts) {
+        if (current instanceof zod_1.z.ZodObject) {
+            const shape = current._def.shape();
+            const field = shape[part];
+            if (!field)
+                return [];
+            current = field;
+        }
+        else if (current instanceof zod_1.z.ZodOptional) {
+            current = current._def.innerType;
+            if (current instanceof zod_1.z.ZodObject) {
+                const shape = current._def.shape();
+                const field = shape[part];
+                if (!field)
+                    return [];
+                current = field;
+            }
+            else {
+                return [];
+            }
+        }
+        else {
+            return [];
+        }
+    }
+    if (current instanceof zod_1.z.ZodOptional || current instanceof zod_1.z.ZodDefault) {
+        current = current._def.innerType;
+    }
+    if (current instanceof zod_1.z.ZodEnum) {
+        return current._def.values;
+    }
+    if (current instanceof zod_1.z.ZodLiteral) {
+        const value = current._def.value;
+        if (typeof value === 'string') {
+            return [value];
+        }
+    }
+    return [];
+}

package/dist/mcp/validation/string-similarity.d.ts

@@ -0,0 +1,10 @@
+import { type Similarity } from './suggestion-types.js';
+export declare function levenshteinDistance(a: string, b: string): number;
+export declare function computeSimilarity(a: string, b: string): Similarity;
+export declare function computeSimilarityIgnoreCase(a: string, b: string): Similarity;
+export interface ClosestMatch {
+    readonly match: string;
+    readonly score: Similarity;
+}
+export declare function findClosestMatch(input: string, candidates: readonly string[], threshold: Similarity): ClosestMatch | null;
+export declare function findAllMatches(input: string, candidates: readonly string[], threshold: Similarity, limit: number): readonly ClosestMatch[];

package/dist/mcp/validation/string-similarity.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinDistance = levenshteinDistance;
+exports.computeSimilarity = computeSimilarity;
+exports.computeSimilarityIgnoreCase = computeSimilarityIgnoreCase;
+exports.findClosestMatch = findClosestMatch;
+exports.findAllMatches = findAllMatches;
+const suggestion_types_js_1 = require("./suggestion-types.js");
+function levenshteinDistance(a, b) {
+    if (a.length > b.length) {
+        [a, b] = [b, a];
+    }
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prevRow = new Array(m + 1);
+    let currRow = new Array(m + 1);
+    for (let i = 0; i <= m; i++) {
+        prevRow[i] = i;
+    }
+    for (let j = 1; j <= n; j++) {
+        currRow[0] = j;
+        for (let i = 1; i <= m; i++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            currRow[i] = Math.min(prevRow[i] + 1, currRow[i - 1] + 1, prevRow[i - 1] + cost);
+        }
+        [prevRow, currRow] = [currRow, prevRow];
+    }
+    return prevRow[m];
+}
+function computeSimilarity(a, b) {
+    if (a === b)
+        return (0, suggestion_types_js_1.similarity)(1);
+    if (a.length === 0 || b.length === 0)
+        return (0, suggestion_types_js_1.similarity)(0);
+    const distance = levenshteinDistance(a, b);
+    const maxLength = Math.max(a.length, b.length);
+    return (0, suggestion_types_js_1.similarity)(1 - distance / maxLength);
+}
+function computeSimilarityIgnoreCase(a, b) {
+    return computeSimilarity(a.toLowerCase(), b.toLowerCase());
+}
+function findClosestMatch(input, candidates, threshold) {
+    if (candidates.length === 0)
+        return null;
+    let bestMatch = null;
+    let bestScore = (0, suggestion_types_js_1.similarity)(0);
+    for (const candidate of candidates) {
+        const score = computeSimilarityIgnoreCase(input, candidate);
+        if (score > bestScore && score >= threshold) {
+            bestScore = score;
+            bestMatch = candidate;
+        }
+    }
+    if (bestMatch === null)
+        return null;
+    return { match: bestMatch, score: bestScore };
+}
+function findAllMatches(input, candidates, threshold, limit) {
+    const matches = [];
+    for (const candidate of candidates) {
+        const score = computeSimilarityIgnoreCase(input, candidate);
+        if (score >= threshold) {
+            matches.push({ match: candidate, score });
+        }
+    }
+    matches.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.match.localeCompare(b.match);
+    });
+    return matches.slice(0, limit);
+}

package/dist/mcp/validation/suggestion-config.d.ts

@@ -0,0 +1,9 @@
+import { type Similarity } from './suggestion-types.js';
+export interface SuggestionConfig {
+    readonly similarityThreshold: Similarity;
+    readonly maxSuggestions: number;
+    readonly includeTemplate: boolean;
+    readonly maxTemplateDepth: number;
+}
+export declare const DEFAULT_SUGGESTION_CONFIG: SuggestionConfig;
+export declare const MINIMAL_SUGGESTION_CONFIG: SuggestionConfig;

package/dist/mcp/validation/suggestion-config.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MINIMAL_SUGGESTION_CONFIG = exports.DEFAULT_SUGGESTION_CONFIG = void 0;
+const suggestion_types_js_1 = require("./suggestion-types.js");
+exports.DEFAULT_SUGGESTION_CONFIG = {
+    similarityThreshold: (0, suggestion_types_js_1.similarity)(0.6),
+    maxSuggestions: 3,
+    includeTemplate: true,
+    maxTemplateDepth: 3,
+};
+exports.MINIMAL_SUGGESTION_CONFIG = {
+    similarityThreshold: (0, suggestion_types_js_1.similarity)(0.7),
+    maxSuggestions: 1,
+    includeTemplate: false,
+    maxTemplateDepth: 1,
+};

package/dist/mcp/validation/suggestion-generator.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+import type { SuggestionConfig } from './suggestion-config.js';
+import type { SuggestionResult } from './suggestion-types.js';
+export declare function generateSuggestions(args: unknown, schema: z.ZodType, config: SuggestionConfig): SuggestionResult;
+export declare function formatSuggestionDetails(result: SuggestionResult): Record<string, unknown>;
+export declare function hasSuggestions(result: SuggestionResult): boolean;

package/dist/mcp/validation/suggestion-generator.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSuggestions = generateSuggestions;
+exports.formatSuggestionDetails = formatSuggestionDetails;
+exports.hasSuggestions = hasSuggestions;
+const zod_1 = require("zod");
+const suggestion_types_js_1 = require("./suggestion-types.js");
+const string_similarity_js_1 = require("./string-similarity.js");
+const schema_introspection_js_1 = require("./schema-introspection.js");
+function generateUnknownKeySuggestions(unknownKeys, expectedKeys, config) {
+    const suggestions = [];
+    for (const unknownKey of unknownKeys) {
+        const match = (0, string_similarity_js_1.findClosestMatch)(unknownKey, expectedKeys, config.similarityThreshold);
+        if (match) {
+            suggestions.push({
+                kind: 'unknown_key',
+                provided: unknownKey,
+                didYouMean: match.match,
+                similarity: match.score,
+            });
+        }
+    }
+    suggestions.sort((a, b) => b.similarity - a.similarity);
+    return suggestions.slice(0, config.maxSuggestions);
+}
+function generateMissingRequiredSuggestions(missingKeys, schema, config) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return [];
+    }
+    const shape = schema._def.shape();
+    const suggestions = [];
+    for (const key of missingKeys) {
+        const field = shape[key];
+        if (field) {
+            suggestions.push({
+                kind: 'missing_required',
+                param: key,
+                example: (0, schema_introspection_js_1.generateExampleValue)(field, 0, config.maxTemplateDepth),
+            });
+        }
+    }
+    suggestions.sort((a, b) => a.param.localeCompare(b.param));
+    return suggestions.slice(0, config.maxSuggestions);
+}
+function generateSuggestions(args, schema, config) {
+    const suggestions = [];
+    const expectedKeys = (0, schema_introspection_js_1.extractExpectedKeys)(schema);
+    const unknownKeys = (0, schema_introspection_js_1.findUnknownKeys)(args, schema);
+    const unknownKeySuggestions = generateUnknownKeySuggestions(unknownKeys, expectedKeys, config);
+    suggestions.push(...unknownKeySuggestions);
+    const missingKeys = (0, schema_introspection_js_1.findMissingRequiredKeys)(args, schema);
+    const missingRequiredSuggestions = generateMissingRequiredSuggestions(missingKeys, schema, config);
+    suggestions.push(...missingRequiredSuggestions);
+    if (suggestions.length === 0 && !config.includeTemplate) {
+        return suggestion_types_js_1.EMPTY_SUGGESTION_RESULT;
+    }
+    const correctTemplate = config.includeTemplate
+        ? (0, schema_introspection_js_1.generateTemplate)(schema, config.maxTemplateDepth)
+        : null;
+    return {
+        suggestions,
+        correctTemplate,
+    };
+}
+function formatSuggestionDetails(result) {
+    const details = {};
+    if (result.suggestions.length > 0) {
+        details.suggestions = result.suggestions.map(s => {
+            switch (s.kind) {
+                case 'unknown_key':
+                    return {
+                        kind: s.kind,
+                        provided: s.provided,
+                        didYouMean: s.didYouMean,
+                        similarity: Math.round(s.similarity * 100) / 100,
+                    };
+                case 'missing_required':
+                    return {
+                        kind: s.kind,
+                        param: s.param,
+                        example: s.example,
+                    };
+                case 'invalid_enum':
+                    return {
+                        kind: s.kind,
+                        path: s.path,
+                        provided: s.provided,
+                        didYouMean: s.didYouMean,
+                        allowedValues: s.allowedValues,
+                    };
+            }
+        });
+    }
+    if (result.correctTemplate !== null) {
+        details.correctTemplate = result.correctTemplate;
+    }
+    return details;
+}
+function hasSuggestions(result) {
+    return result.suggestions.length > 0 || result.correctTemplate !== null;
+}

package/dist/mcp/validation/suggestion-types.d.ts

@@ -0,0 +1,31 @@
+export type Similarity = number & {
+    readonly __brand: 'Similarity';
+};
+export declare function similarity(n: number): Similarity;
+export interface UnknownKeySuggestion {
+    readonly kind: 'unknown_key';
+    readonly provided: string;
+    readonly didYouMean: string;
+    readonly similarity: Similarity;
+}
+export interface MissingRequiredSuggestion {
+    readonly kind: 'missing_required';
+    readonly param: string;
+    readonly example: unknown;
+}
+export interface InvalidEnumSuggestion {
+    readonly kind: 'invalid_enum';
+    readonly path: string;
+    readonly provided: string;
+    readonly didYouMean: string | null;
+    readonly allowedValues: readonly string[];
+}
+export type ValidationSuggestion = UnknownKeySuggestion | MissingRequiredSuggestion | InvalidEnumSuggestion;
+export interface SuggestionResult {
+    readonly suggestions: readonly ValidationSuggestion[];
+    readonly correctTemplate: Readonly<Record<string, unknown>> | null;
+}
+export declare const EMPTY_SUGGESTION_RESULT: SuggestionResult;
+export declare function isUnknownKeySuggestion(s: ValidationSuggestion): s is UnknownKeySuggestion;
+export declare function isMissingRequiredSuggestion(s: ValidationSuggestion): s is MissingRequiredSuggestion;
+export declare function isInvalidEnumSuggestion(s: ValidationSuggestion): s is InvalidEnumSuggestion;

package/dist/mcp/validation/suggestion-types.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_SUGGESTION_RESULT = void 0;
+exports.similarity = similarity;
+exports.isUnknownKeySuggestion = isUnknownKeySuggestion;
+exports.isMissingRequiredSuggestion = isMissingRequiredSuggestion;
+exports.isInvalidEnumSuggestion = isInvalidEnumSuggestion;
+function similarity(n) {
+    return Math.max(0, Math.min(1, n));
+}
+exports.EMPTY_SUGGESTION_RESULT = {
+    suggestions: [],
+    correctTemplate: null,
+};
+function isUnknownKeySuggestion(s) {
+    return s.kind === 'unknown_key';
+}
+function isMissingRequiredSuggestion(s) {
+    return s.kind === 'missing_required';
+}
+function isInvalidEnumSuggestion(s) {
+    return s.kind === 'invalid_enum';
+}

package/package.json

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

package/workflows/relocation-workflow-us.json

@@ -50,7 +50,7 @@
     },
     {
       "name": "defineNonObvious",
-      "definition": "A candidate is 'non-obvious' if:\n- It is NOT in `userTopOfMind`, AND\n- It is NOT in the top-N most populous US metros list used for this run (N default 20).\n\nCustom/city/county candidates: if the candidate's displayName contains or is anchored to a top-N metro/city name, treat it as obvious.\n\nRecord the top-N list source and N in the dossier."
+      "definition": "A candidate is 'non-obvious' if:\n- It is NOT in `userTopOfMind`, AND\n- It is NOT in the top-N most populous US metros list used for this run (N default 100).\n\nDo NOT use substring matching (\"contains\"/\"anchored to\") to infer obviousness for city/county/custom candidates. If you cannot deterministically map a city/county/custom boundary to an MSA in the top-N list, mark obviousness as Unknown and do not count it toward non-obvious requirements.\n\nAdditionally track `qualifyingNonObviousCandidateCount`: candidates that are non-obvious AND plausibly pass dealbreakers (based on first-pass screening signal).\n\nRecord the top-N list source and N in the dossier."
     },
     {
       "name": "missingDataPolicy",
@@ -65,7 +65,7 @@
     {
       "id": "phase-0-scope-and-artifacts",
       "title": "Phase 0: Scope, Modules, and Paper-Trail Artifacts",
-      "prompt": "Establish scope, modules, and artifact structure.\n\n1) Confirm v1 scope: US-only relocation.\n2) Capture top-of-mind list (optional): ask the user for `userTopOfMind` (0–10 areas).\n3) Determine user context and activate lightweight modules (select all that apply):\n   - kids/schools\n   - commute\n   - transit\n   - climate risk\n   - healthcare access\n   - career/job market\n   - outdoors\n   - nightlife/arts\n   - safety\n   - taxes\n   - diversity/community\n   - disability accessibility\n\n4) Define primary search granularity for this run (set `candidateType`):\n   - Default: metro\n   - Optional: city, county, custom\n\n5) Custom areas (v1):\n   - Set `customAreaMode = radius`\n   - Custom AreaSpec format: center (place+stateCode) + radiusMiles\n\n6) Initialize artifacts (write-or-paste):\n   - Master dossier: `RELOCATION_DOSSIER.md`\n   - Profiles directory: `relocation-profiles/`\n   - Profile naming: `relocation-profiles/<candidate-slug>.md`\n\nIn the dossier, create these sections:\n- User Context & Modules\n- Boundary & Definitions\n- Aggregation & Comparability Policy\n- Preferences (Draft)\n- Constraints & Dealbreakers\n- Missing Data Policy\n- Sources Strategy\n- Candidate Pool (Breadth)\n- Screened Candidates\n- Screening Claims Ledger\n- Shortlist\n- Profiles Index\n- Comparison & Ranking\n- Machine State Checkpoints\n- Decision Log (append-only)\n\n**Set context variables (required):**\n- activeModules: string[]\n- candidateType: metro|city|county|custom\n- customAreaMode: radius\n- userTopOfMind: string[] (empty array allowed)\n\nOutput (in chat):\n- activeModules\n- candidateType\n- customAreaMode\n- userTopOfMind\n- Artifact paths created\n\nThen ask user to confirm modules + candidateType before proceeding.",
+      "prompt": "Establish scope, modules, and artifact structure.\n\n1) Confirm v1 scope: US-only relocation.\n2) Capture top-of-mind list (optional): ask the user for `userTopOfMind` (0–10 areas).\n3) Determine user context and activate lightweight modules (select all that apply):\n   - kids/schools\n   - commute\n   - transit\n   - climate risk\n   - healthcare access\n   - career/job market\n   - outdoors\n   - nightlife/arts\n   - safety\n   - taxes\n   - diversity/community\n   - disability accessibility\n   - amenities/errands\n   - air quality\n   - noise\n   - internet/infra\n\n4) Define primary search granularity for this run (set `candidateType`):\n   - Default: metro\n   - Optional: city, county, custom\n\n5) Custom areas (v1):\n   - Set `customAreaMode = radius`\n   - Custom AreaSpec format: center (place+stateCode) + radiusMiles\n\n6) Initialize artifacts (write-or-paste):\n   - Master dossier: `RELOCATION_DOSSIER.md`\n   - Profiles directory: `relocation-profiles/`\n   - Profile naming: `relocation-profiles/<candidate-slug>.md`\n\nIn the dossier, create these sections:\n- User Context & Modules\n- Boundary & Definitions\n- Aggregation & Comparability Policy\n- Preferences (Draft)\n- Constraints & Dealbreakers\n- Missing Data Policy\n- Sources Strategy\n- Candidate Pool (Breadth)\n- Screened Candidates\n- Screening Claims Ledger\n- Baseline Flags (Not Scored)\n- Red Flag Gate Decisions (append-only)\n- Shortlist\n- Profiles Index\n- Comparison & Ranking\n- Machine State Checkpoints\n- Decision Log (append-only)\n\n**Set context variables (required):**\n- activeModules: string[]\n- candidateType: metro|city|county|custom\n- customAreaMode: radius\n- userTopOfMind: string[] (empty array allowed)\n- timelineToMove: 0-3 months|3-12 months|12+ months\n- householdProfile: string\n- housingPlan: { mode: rent|buy|either, budgetRange?: string }\n- workConstraints: { mode: remote|hybrid|onsite, timeZonesAllowed?: string[] }\n- geoExclusions: { excludeStates?: string[], excludeRegions?: string[] }\n- diversityDimensions: string[]\n\nOutput (in chat):\n- activeModules\n- candidateType\n- customAreaMode\n- userTopOfMind\n- timelineToMove\n- householdProfile\n- housingPlan\n- workConstraints\n- geoExclusions\n- diversityDimensions\n- Artifact paths created\n\nThen ask user to confirm modules + candidateType before proceeding.",
       "agentRole": "You are a relocation workflow coordinator. Create structure first, then proceed systematically.",
       "validationCriteria": [
         {
@@ -87,6 +87,36 @@
           "type": "contains",
           "value": "userTopOfMind",
           "message": "Must set userTopOfMind (can be empty)"
+        },
+        {
+          "type": "contains",
+          "value": "timelineToMove",
+          "message": "Must set timelineToMove"
+        },
+        {
+          "type": "contains",
+          "value": "householdProfile",
+          "message": "Must set householdProfile"
+        },
+        {
+          "type": "contains",
+          "value": "housingPlan",
+          "message": "Must set housingPlan"
+        },
+        {
+          "type": "contains",
+          "value": "workConstraints",
+          "message": "Must set workConstraints"
+        },
+        {
+          "type": "contains",
+          "value": "geoExclusions",
+          "message": "Must set geoExclusions (can be empty)"
+        },
+        {
+          "type": "contains",
+          "value": "diversityDimensions",
+          "message": "Must set diversityDimensions"
         }
       ],
       "requireConfirmation": true
@@ -105,9 +135,29 @@
     {
       "id": "phase-1-preference-discovery",
       "title": "Phase 1: Preference Discovery (Draft) + Calibration Setup",
-      "prompt": "Discover what the user cares about before searching.\n\n1) Gather constraints:\n- Hard constraints (must-have): geography constraints, climate constraints, max budget, job constraints, family constraints, health constraints.\n- Anti-goals (explicit non-goals).\n- Timeline.\n\n2) Draft preferences as:\n- Dealbreakers\n- Strong preferences\n- Mild preferences\n\n3) Create an initial weight model (draft) across the activated modules:\n- Pick top 6–10 criteria.\n- Assign weights (sum to 100).\n\n**Required output format (exact keys):**\n- weights: [{ criterion: string, weight: number }]\n- weightsCount: <number>\n- weightsSumCheck: 100\n\n4) Update `RELOCATION_DOSSIER.md`:\n- Fill Preferences (Draft)\n- Fill Constraints & Dealbreakers\n- Add initial Weight Model (Draft)\n\nKeep it generic: prefer questions about tradeoffs (e.g., \"Would you trade smaller home for better walkability?\").\n\nOutput: Draft preferences + a short list of open questions (max 5).",
+      "prompt": "Discover what the user cares about before searching.\n\n1) Gather constraints:\n- Hard constraints (must-have): geography constraints, climate constraints, max budget, job constraints, family constraints, health constraints.\n- Anti-goals (explicit non-goals).\n- Timeline.\n\n2) Draft preferences as:\n- Dealbreakers\n- Strong preferences\n- Mild preferences\n\n3) Create an initial weight model (draft) across the activated modules:\n- Pick top 6–10 criteria.\n- Assign weights (sum to 100).\n\nIf the user is unsure how to pick numbers, use a temporary equal-weight draft (e.g., 8 criteria → 12,12,12,12,12,12,14,14) and proceed. A later step can help derive better weights via Most/Least comparisons.\n\n**Required output format (exact keys):**\n- dealbreakers: string[]\n- geoConstraints: { includeStates?: string[], excludeStates?: string[], includeRegions?: string[], excludeRegions?: string[], timeZonesAllowed?: string[] }\n- proximityConstraints: { near?: [{ feature: string, maxDriveMinutes?: number, maxMiles?: number }] }\n- climateConstraints: { summerHeat?: low|medium|high, humidityTolerance?: low|medium|high, winterSeverityTolerance?: low|medium|high, sunshineNeed?: low|medium|high, snowIceNoGo?: boolean }\n- urbanFormPreference: { density: dense|mixed|suburban|small-town|rural, walkabilityImportance?: low|medium|high }\n- policyCultureConstraints: { mustHave?: string[], mustAvoid?: string[] }\n- weights: [{ criterion: string, weight: number }]\n- weightsCount: <number>\n- weightsSumCheck: 100\n\n4) Update `RELOCATION_DOSSIER.md`: \n- Fill Preferences (Draft)\n- Fill Constraints & Dealbreakers\n- Add initial Weight Model (Draft)\n\nKeep it generic: prefer questions about tradeoffs (e.g., \"Would you trade smaller home for better walkability?\").\n\nOutput: Draft preferences + a short list of open questions (max 5).",
       "agentRole": "You are a facilitator eliciting preferences through tradeoffs and constraints.",
       "validationCriteria": [
+        {
+          "type": "contains",
+          "value": "dealbreakers:",
+          "message": "Must output dealbreakers"
+        },
+        {
+          "type": "contains",
+          "value": "geoConstraints:",
+          "message": "Must output geoConstraints"
+        },
+        {
+          "type": "contains",
+          "value": "climateConstraints:",
+          "message": "Must output climateConstraints"
+        },
+        {
+          "type": "contains",
+          "value": "urbanFormPreference:",
+          "message": "Must output urbanFormPreference"
+        },
         {
           "type": "contains",
           "value": "weights:",
@@ -126,10 +176,25 @@
       ],
       "requireConfirmation": false
     },
+    {
+      "id": "phase-1c-weights-maxdiff-optional",
+      "title": "Phase 1c: Weight Derivation Helper (MaxDiff, Optional)",
+      "prompt": "Optional helper to reduce weight-setting friction.\n\nAsk the user: \"Do you want help deriving weights using Most/Least comparisons? (yes/no)\"\n\nIf NO:\n- Set pairwiseUsed = false\n- Set maxDiffSetsCount = 0\n- Keep the existing weights from Phase 1\n\nIf YES:\n1) Build deterministic MaxDiff sets from the current criteria list (in the order they appear in `weights`).\n   - Let N = weightsCount\n   - If N <= 7: use 3 sets of 4 criteria\n   - If N >= 8: use 4 sets of 5 criteria\n   - Sets are rotations of the criteria list (no randomness):\n     - set0 = first K\n     - set1 = rotate left by 1, take first K\n     - set2 = rotate left by 2, take first K\n     - set3 = rotate left by 3, take first K (only if 4 sets)\n2) For each set, ask TWO questions:\n   - \"Which is MOST important to you?\"\n   - \"Which is LEAST important to you?\"\n3) Derive weights deterministically from counts:\n   - raw[c] = mostCount[c] - leastCount[c]\n   - shifted[c] = raw[c] - min(raw) + 1 (so all >= 1)\n   - weight[c] = round(shifted[c] / sum(shifted) * 100)\n   - Fix rounding drift by adjusting the largest weight to make the sum exactly 100\n   - If all raw values are equal (no signal), keep original weights and note that in weightsDeltaSummary\n4) Show the derived weights and allow ONE small tweak pass:\n   - User may adjust up to 2 weights; re-normalize to sum=100\n\nUpdate `RELOCATION_DOSSIER.md` Preferences section:\n- Record whether MaxDiff was used\n- Record the sets and user picks (Most/Least)\n- Record the final weights and 1–5 bullets explaining what changed\n\n**Required output format (exact keys):**\n- pairwiseUsed: true|false\n- maxDiffSetsCount: <number>\n- weights: [{ criterion: string, weight: number }]\n- weightsCount: <number>\n- weightsSumCheck: 100\n- weightsDeltaSummary: [1–5 bullets]",
+      "agentRole": "You are helping the user derive stable weights using bounded Most/Least comparisons.",
+      "validationCriteria": [
+        { "type": "regex", "pattern": "pairwiseUsed:\\s*(true|false)", "message": "Must output pairwiseUsed" },
+        { "type": "contains", "value": "maxDiffSetsCount", "message": "Must output maxDiffSetsCount" },
+        { "type": "contains", "value": "weights:", "message": "Must output weights array" },
+        { "type": "regex", "pattern": "weightsCount:\\s*(6|7|8|9|10)", "message": "weightsCount must be 6–10" },
+        { "type": "regex", "pattern": "weightsSumCheck:\\s*100", "message": "weightsSumCheck must be 100" },
+        { "type": "contains", "value": "weightsDeltaSummary", "message": "Must output weightsDeltaSummary" }
+      ],
+      "requireConfirmation": true
+    },
     {
       "id": "phase-1b-calibration-deck",
       "title": "Phase 1b: Preference Calibration Deck (Anti-Anchoring)",
-      "prompt": "Generate a calibration deck of 8–12 diverse US location archetypes (not specific cities yet). Examples: dense transit metro, college town, mountain small city, coastal mid-size, sunbelt suburb, rust-belt revival city, DC-adjacent, etc.\n\nFor each archetype:\n- 2–3 sentences describing lifestyle and typical tradeoffs\n- Who it fits / who it frustrates\n- What it implies about the weight model\n\nAsk user to:\n- Rank top 3 and bottom 3 archetypes\n- Name 1–2 surprises (\"I didn't expect to like...\")\n\nThen update `RELOCATION_DOSSIER.md`:\n- Add Calibration Findings (what changed in preferences)\n- Revise the Weight Model accordingly\n\n**Required output format (exact keys):**\n- calibrationTop3: [string, string, string]\n- calibrationBottom3: [string, string, string]\n- weightsDeltaSummary: [1–5 bullets]\n- weights: [{ criterion: string, weight: number }]\n\nOutput: Updated weight model and what changed because of calibration.",
+      "prompt": "Generate a calibration deck of 8–12 diverse US location archetypes (not specific cities yet). Examples: dense transit metro, college town, mountain small city, coastal mid-size, sunbelt suburb, rust-belt revival city, DC-adjacent, etc.\n\nFor each archetype:\n- 2–3 sentences describing lifestyle and typical tradeoffs\n- Who it fits / who it frustrates\n- What it implies about the weight model\n\nAsk user to:\n- Rank top 3 and bottom 3 archetypes\n- Name 1–2 surprises (\"I didn't expect to like...\")\n\nThen update `RELOCATION_DOSSIER.md`:\n- Add Calibration Findings (what changed in preferences)\n- Revise the Weight Model accordingly (weights may have been derived via MaxDiff in Phase 1c)\n\nThen revise (explicitly) any of these if calibration implies changes:\n- geoConstraints\n- climateConstraints\n- urbanFormPreference\n- proximityConstraints\n\n**Required output format (exact keys):**\n- calibrationTop3: [string, string, string]\n- calibrationBottom3: [string, string, string]\n- weightsDeltaSummary: [1–5 bullets]\n- derivedSignals: { densityLeaning: string, climateLeaning: string, regionLeaning: string, travelLeaning: string }\n- weights: [{ criterion: string, weight: number }]\n\nOutput: Updated constraints (if changed), updated weight model, and what changed because of calibration.",
       "agentRole": "You are an anti-anchoring specialist. Use diversity to reveal latent preferences.",
       "validationCriteria": [
         {
@@ -147,6 +212,11 @@
           "value": "weightsDeltaSummary",
           "message": "Must output weightsDeltaSummary"
         },
+        {
+          "type": "contains",
+          "value": "derivedSignals",
+          "message": "Must output derivedSignals"
+        },
         {
           "type": "contains",
           "value": "weights:",
@@ -158,9 +228,19 @@
     {
       "id": "phase-2-policy-and-gates",
       "title": "Phase 2: Missing-Data Policy + Gates (Lock-In)",
-      "prompt": "Lock in the decision mechanics before researching candidates.\n\n1) Choose a Missing Data Policy (must be explicit) and record it as `missingDataPolicy`:\n- neutral\n- penalize\n- followup_required\n\n2) Define anti-anchoring gate parameters:\n- minCandidatePool (default 20)\n- minNonObviousCandidates (default 6)\n\n3) Define shortlist range:\n- shortlistMin (default 8)\n- shortlistMax (default 12)\n\n4) Define screening caps (to keep Phase 4 scalable):\n- screeningTopCriteriaCount (default 3)  // screen only dealbreakers + top N weighted criteria\n- screeningMaxClaimsPerCandidate (default 3)\n- screeningMaxSourcesPerClaim (default 1)\n- screeningTimeboxMinutesPerCandidate (default 5)\n\n5) Define screening batching (to avoid huge loop iteration limits):\n- screeningBatchSize (default 10)\n\n6) Update `RELOCATION_DOSSIER.md`:\n- Missing Data Policy\n- Anti-Anchoring Gate\n- Shortlist Size Target\n- Screening Caps\n- Screening Batching\n\n**Required output format (exact keys):**\n- missingDataPolicy: neutral|penalize|followup_required\n- minCandidatePool: <number>\n- minNonObviousCandidates: <number>\n- shortlistMin: <number>\n- shortlistMax: <number>\n- screeningTopCriteriaCount: <number>\n- screeningMaxClaimsPerCandidate: <number>\n- screeningTimeboxMinutesPerCandidate: <number>\n- screeningBatchSize: <number>\n- shortlistRangeCheck: ok\n\nAsk user to confirm these policies before proceeding.",
+      "prompt": "Lock in the decision mechanics before researching candidates.\n\n1) Choose a Missing Data Policy (must be explicit) and record it as `missingDataPolicy`:\n- neutral\n- penalize\n- followup_required\n\n2) Intake completeness gate (must be explicit):\n- intakeCompletenessCheck: ok|needs_more_info\n- missingInputs: string[] (empty if ok)\n\n3) Define anti-anchoring + diversity gate parameters:\n- minCandidatePool (default 20)\n- minNonObviousCandidates (default 6)\n- minCoverageRegions (default 3)\n- minCoverageClimateBands (default 2)\n\n4) Define shortlist range:\n- shortlistMin (default 8)\n- shortlistMax (default 12)\n\n5) Define screening caps (to keep Phase 4 scalable):\n- screeningTopCriteriaCount (default 3)  // screen only dealbreakers + top N weighted criteria\n- screeningMaxClaimsPerCandidate (default 3)\n- screeningMaxSourcesPerClaim (default 1)\n- screeningTimeboxMinutesPerCandidate (default 5)\n\n6) Define screening batching (to avoid huge loop iteration limits):\n- screeningBatchSize (default 10)\n\n7) Define candidate discovery seeding cap (Phase 3 breadth search):\n- perSourceCandidateCap (default 8)\n\n8) Define baseline flags caps (Phase 4 baseline flags):\n- baselineMaxFlagsPerCandidate (default 2)\n- baselineMaxSourcesPerFlag (default 1)\n- baselineTimeboxMinutesPerCandidate (default 2)\n\n9) Update `RELOCATION_DOSSIER.md`:\n- Missing Data Policy\n- Anti-Anchoring Gate\n- Diversity Coverage Gate\n- Shortlist Size Target\n- Screening Caps\n- Screening Batching\n- Discovery Seeding Cap\n- Baseline Flags Caps\n\n**Required output format (exact keys):**\n- intakeCompletenessCheck: ok|needs_more_info\n- missingInputs: string[]\n- missingDataPolicy: neutral|penalize|followup_required\n- minCandidatePool: <number>\n- minNonObviousCandidates: <number>\n- minCoverageRegions: <number>\n- minCoverageClimateBands: <number>\n- shortlistMin: <number>\n- shortlistMax: <number>\n- screeningTopCriteriaCount: <number>\n- screeningMaxClaimsPerCandidate: <number>\n- screeningTimeboxMinutesPerCandidate: <number>\n- screeningBatchSize: <number>\n- perSourceCandidateCap: <number>\n- baselineMaxFlagsPerCandidate: <number>\n- baselineMaxSourcesPerFlag: <number>\n- baselineTimeboxMinutesPerCandidate: <number>\n- shortlistRangeCheck: ok\n\nAsk user to confirm these policies before proceeding.",
       "agentRole": "You are a decision systems designer. Make ambiguity explicit and policy-driven.",
       "validationCriteria": [
+        {
+          "type": "regex",
+          "pattern": "intakeCompletenessCheck:\\s*(ok|needs_more_info)",
+          "message": "Must set intakeCompletenessCheck: ok|needs_more_info"
+        },
+        {
+          "type": "contains",
+          "value": "missingInputs",
+          "message": "Must set missingInputs (can be empty)"
+        },
         {
           "type": "regex",
           "pattern": "missingDataPolicy:\\s*(neutral|penalize|followup_required)",
@@ -176,6 +256,16 @@
           "value": "minNonObviousCandidates",
           "message": "Must set minNonObviousCandidates"
         },
+        {
+          "type": "contains",
+          "value": "minCoverageRegions",
+          "message": "Must set minCoverageRegions"
+        },
+        {
+          "type": "contains",
+          "value": "minCoverageClimateBands",
+          "message": "Must set minCoverageClimateBands"
+        },
         {
           "type": "contains",
           "value": "shortlistMin",
@@ -206,6 +296,26 @@
           "value": "screeningBatchSize",
           "message": "Must set screeningBatchSize"
         },
+        {
+          "type": "contains",
+          "value": "perSourceCandidateCap",
+          "message": "Must set perSourceCandidateCap"
+        },
+        {
+          "type": "contains",
+          "value": "baselineMaxFlagsPerCandidate",
+          "message": "Must set baselineMaxFlagsPerCandidate"
+        },
+        {
+          "type": "contains",
+          "value": "baselineMaxSourcesPerFlag",
+          "message": "Must set baselineMaxSourcesPerFlag"
+        },
+        {
+          "type": "contains",
+          "value": "baselineTimeboxMinutesPerCandidate",
+          "message": "Must set baselineTimeboxMinutesPerCandidate"
+        },
         {
           "type": "regex",
           "pattern": "shortlistRangeCheck:\\s*ok",
@@ -224,7 +334,7 @@
     {
       "id": "phase-3-breadth-search",
       "title": "Phase 3: Breadth Search (Generate Candidate Pool)",
-      "prompt": "Generate a broad candidate pool of US areas that plausibly fit the user's constraints.\n\nBefore generating candidates, update `RELOCATION_DOSSIER.md` with a required section:\n- `## Sources Strategy`\n  - Housing: Zillow (if available) + at least one alternative\n  - Taxes: state revenue sites / reputable summaries\n  - Climate normals: NOAA\n  - Climate risk: FEMA flood maps + local/state sources where applicable\n  - Employment: BLS / state labor stats (if module active)\n  - Transit/commute: local transit agencies / reputable summaries (if module active)\n\nRules:\n- Use the Weight Model + Dealbreakers.\n- Generate at least `minCandidatePool` candidates.\n- Ensure at least `minNonObviousCandidates` candidates qualify per defineNonObvious().\n- Every candidate MUST have an AreaSpec.\n- For each candidate, use normalizeCandidate() and record why included.\n- Record the top-N populous metros list used for defineNonObvious() (N default 20) with a source.\n- Include a mix: some candidates the user likely knows + some non-obvious candidates.\n- Optional: include a small number of custom radius candidates if they are plausible and well-defined.\n\n**Set context variables (required):**\n- candidatePool: normalized candidates array\n- candidatePoolCount: number\n- nonObviousCandidateCount: number\n- nonObviousDefinitionUsed: { topN: number, source: string }\n\nUpdate `RELOCATION_DOSSIER.md`:\n- Candidate Pool (Breadth): table with candidate name, candidateType, region, why included, early risks/unknowns\n- Decision Log entry: how the pool was constructed\n\n**Required output format (exact keys):**\n- candidatePoolCount: <number>\n- nonObviousCandidateCount: <number>\n- nonObviousDefinitionUsed: <summary>",
+      "prompt": "Generate a broad candidate pool of US areas that plausibly fit the user's constraints.\n\nBefore generating candidates, update `RELOCATION_DOSSIER.md` with a required section:\n- `## Sources Strategy`\n  - Housing: Zillow (if available) + at least one alternative\n  - Taxes: state revenue sites / reputable summaries\n  - Climate normals: NOAA\n  - Climate risk: FEMA flood maps + local/state sources where applicable\n  - Employment: BLS / state labor stats (if module active)\n  - Transit/commute: local transit agencies / reputable summaries (if module active)\n  - Air quality: AirNow/EPA + local air district summaries (if module active)\n  - Noise: airport noise contour maps + municipal noise resources (if module active)\n  - Internet/infra: FCC broadband map + ISP availability (if module active)\n  - Amenities/errands: mapping services + local business directories (qualitative; if module active)\n\nRules:\n- Use the Weight Model + Dealbreakers.\n- Discovery breadth must be systematic: tag each candidate with `candidateFacets` (region, climateBand, sizeTier, taxRegime, airportAccess, outdoorsBiome as applicable) and fill obvious coverage gaps.\n- When using curated list sources for discovery, cap contributions to `perSourceCandidateCap` candidates per source to avoid editorial bias dominating.\n- Generate at least `minCandidatePool` candidates.\n- Ensure at least `minNonObviousCandidates` candidates qualify as *qualifying non-obvious* (non-obvious per defineNonObvious() AND plausibly passes dealbreakers based on first-pass screening signal).\n- Every candidate MUST have an AreaSpec.\n- For each candidate, use normalizeCandidate() and record why included.\n- Record the top-N populous metros list used for defineNonObvious() (N default 100) with a source.\n- Include a mix: some candidates the user likely knows + some non-obvious candidates.\n- Optional: include a small number of custom radius candidates if they are plausible and well-defined.\n\n**Set context variables (required):**\n- candidatePool: normalized candidates array\n- candidatePoolCount: number\n- nonObviousCandidateCount: number\n- qualifyingNonObviousCandidateCount: number\n- coverageRegionsCount: number\n- coverageClimateBandsCount: number\n- candidateFacetsSummary: { regions: string[], climateBands: string[], sizeTiers: string[] }\n- coverageMatrix: <summary>\n- coverageGaps: string[]\n- discoverySourcesUsed: { name: string, countAdded: number }[]\n- perSourceCandidateCap: number\n- nonObviousDefinitionUsed: { topN: number, source: string }\n\nUpdate `RELOCATION_DOSSIER.md`:\n- Candidate Pool (Breadth): table with candidate name, candidateType, region, why included, early risks/unknowns\n- Decision Log entry: how the pool was constructed\n\n**Required output format (exact keys):**\n- candidatePoolCount: <number>\n- nonObviousCandidateCount: <number>\n- qualifyingNonObviousCandidateCount: <number>\n- coverageRegionsCount: <number>\n- coverageClimateBandsCount: <number>\n- coverageGaps: <summary>\n- discoverySourcesUsed: <summary>\n- nonObviousDefinitionUsed: <summary>",
       "agentRole": "You are a researcher generating a diverse, constraint-respecting candidate pool.",
       "validationCriteria": [
         {
@@ -242,6 +352,26 @@
           "value": "nonObviousCandidateCount",
           "message": "Must set nonObviousCandidateCount"
         },
+        {
+          "type": "contains",
+          "value": "qualifyingNonObviousCandidateCount",
+          "message": "Must set qualifyingNonObviousCandidateCount"
+        },
+        {
+          "type": "contains",
+          "value": "coverageRegionsCount",
+          "message": "Must set coverageRegionsCount"
+        },
+        {
+          "type": "contains",
+          "value": "coverageClimateBandsCount",
+          "message": "Must set coverageClimateBandsCount"
+        },
+        {
+          "type": "contains",
+          "value": "discoverySourcesUsed",
+          "message": "Must record discoverySourcesUsed"
+        },
         {
           "type": "contains",
           "value": "nonObviousDefinitionUsed",
@@ -253,7 +383,7 @@
     {
       "id": "phase-3b-anti-anchoring-gate-check",
       "title": "Phase 3b: Anti-Anchoring Gate Check",
-      "prompt": "Run antiAnchoringGate() deterministically using these comparisons:\n- candidatePoolCount >= minCandidatePool\n- nonObviousCandidateCount >= minNonObviousCandidates\n\nIf the gate fails:\n- Expand the pool until it passes (diversify; avoid adding only obvious metros).\n- Recompute candidatePoolCount and nonObviousCandidateCount.\n\nIf the gate passes:\n- Proceed.\n\n**Required output format (exact keys):**\n- antiAnchoringGate: pass|fail\n- gateFailureReason: <string or empty>\n- poolExpansionCount: <number>\n\nUpdate `RELOCATION_DOSSIER.md` with gate status and any expansions performed.",
+      "prompt": "Run antiAnchoringGate() deterministically using these comparisons:\n- candidatePoolCount >= minCandidatePool\n- qualifyingNonObviousCandidateCount >= minNonObviousCandidates\n- coverageRegionsCount >= minCoverageRegions\n- coverageClimateBandsCount >= minCoverageClimateBands\n\nIf the gate fails:\n- Expand the pool until it passes by filling coverage gaps first (diversify; avoid adding only obvious metros).\n- Recompute candidatePoolCount, qualifyingNonObviousCandidateCount, coverageRegionsCount, and coverageClimateBandsCount.\n\nIf the gate passes:\n- Proceed.\n\n**Required output format (exact keys):**\n- antiAnchoringGate: pass|fail\n- gateFailureReason: <string or empty>\n- poolExpansionCount: <number>\n\nUpdate `RELOCATION_DOSSIER.md` with gate status and any expansions performed.",
       "agentRole": "You enforce anti-anchoring and minimum diversity requirements.",
       "validationCriteria": [
         {
@@ -324,10 +454,41 @@
         }
       ]
     },
+    {
+      "id": "phase-4aa-baseline-flags",
+      "title": "Phase 4aa: Baseline Flags (Not Scored)",
+      "prompt": "Perform a lightweight baseline due diligence pass (NOT scored) for candidates that survived screening.\n\nInput: use `screenResults` to identify candidates that are Pass or Maybe.\n\nBaseline scope (keep bounded):\n- Climate risk (high-level)\n- Safety/crime (high-level)\n- If relevant to householdProfile or activeModules: schools and healthcare access (high-level)\n\nCaps (from Phase 2):\n- baselineMaxFlagsPerCandidate\n- baselineMaxSourcesPerFlag\n- baselineTimeboxMinutesPerCandidate\n\nRules:\n- Do not compute or modify ranking scores here.\n- Do not silently turn flags into dealbreakers or weights.\n- If evidence is unclear, record Unknown and add to unknowns.\n\nFor each Pass/Maybe candidate, produce 0..baselineMaxFlagsPerCandidate baseline flags. Each flag must be tagged:\n- category: climate|safety|schools|healthcare|policy|other\n- severity: yellow|orange|red\n- summary: one sentence\n- source (URL/citation)\n- retrievedAt\n- confidenceGrade (High/Medium/Low)\n\nRed flag definition (v1): any flag with severity=red.\n\nUpdate `RELOCATION_DOSSIER.md`:\n- Add/append a Baseline Flags (Not Scored) section with a per-candidate table of flags + unknowns.\n\n**Set context variables (required):**\n- baselineFlags: { [candidateKey: string]: { flags: array, unknowns: string[] } }\n- redFlagCandidates: string[]\n- redFlagCount: number\n\n**Required output format (exact keys):**\n- redFlagCount: <number>\n- redFlagCandidates: <list>\n- baselineFlags: <present>",
+      "agentRole": "You are doing bounded baseline due diligence without affecting scoring.",
+      "validationCriteria": [
+        { "type": "contains", "value": "baselineFlags", "message": "Must set baselineFlags" },
+        { "type": "contains", "value": "redFlagCandidates", "message": "Must set redFlagCandidates" },
+        { "type": "contains", "value": "redFlagCount", "message": "Must set redFlagCount" }
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-4ab-red-flag-gate",
+      "title": "Phase 4ab: Red Flag Gate (User Decision)",
+      "prompt": "Handle baseline red flags explicitly before shortlisting.\n\nIf redFlagCount = 0:\n- Output redFlagDecision = fyi\n- Output redFlagDecisionNotes = \"No red flags detected in baseline due diligence\"\n- Proceed.\n\nIf redFlagCount > 0:\n1) Summarize each red flag (candidate + category + one-line summary + source).\n2) Ask user which one to do (pick exactly one):\n   - promote_to_dealbreakers\n   - add_weighted_criterion\n   - fyi\n\nIf promote_to_dealbreakers:\n- Update Dealbreakers in `RELOCATION_DOSSIER.md` and state the new/updated dealbreakers explicitly.\n\nIf add_weighted_criterion:\n- Ask user how it should be weighted and which existing weight(s) should decrease so weights still sum to 100.\n\nIf fyi:\n- Record decision in `RELOCATION_DOSSIER.md` Red Flag Gate Decisions (append-only).\n\n**Required output format (exact keys):**\n- redFlagDecision: promote_to_dealbreakers|add_weighted_criterion|fyi\n- redFlagDecisionNotes: <string>",
+      "agentRole": "You enforce explicit user intent for red flags (no hidden weighting).",
+      "validationCriteria": [
+        {
+          "type": "regex",
+          "pattern": "redFlagDecision:\\s*(promote_to_dealbreakers|add_weighted_criterion|fyi)",
+          "message": "Must set redFlagDecision"
+        },
+        {
+          "type": "contains",
+          "value": "redFlagDecisionNotes",
+          "message": "Must set redFlagDecisionNotes"
+        }
+      ],
+      "requireConfirmation": { "var": "redFlagCount", "gt": 0 }
+    },
     {
       "id": "phase-4b-select-shortlist",
       "title": "Phase 4b: Select Shortlist for Deep Dives",
-      "prompt": "Select a shortlist for deep dives.\n\nRules:\n- Target shortlist size: within shortlistMin..shortlistMax.\n- Must include at least 3 candidates outside the user's `userTopOfMind` list (if provided).\n- If too many Pass/Maybe, prefer diversity across archetypes.\n\n**Set context variables (required):**\n- shortlist: normalized candidates array\n- shortlistCount: number\n- shortlistNonTopOfMindCount: number\n\n**Required output format (exact keys):**\n- shortlistCount: <number>\n- shortlistNonTopOfMindCount: <number>\n- shortlistRangeCheck: ok\n\nUpdate `RELOCATION_DOSSIER.md`:\n- Shortlist section with rationale per shortlisted candidate\n- Profiles Index (planned profile files)\n\nAsk user to confirm the shortlist before deep dives.",
+      "prompt": "Select a shortlist for deep dives.\n\nRules:\n- Target shortlist size: within shortlistMin..shortlistMax.\n- Must include at least 3 candidates outside the user's `userTopOfMind` list (if provided).\n- If too many Pass/Maybe, prefer diversity across archetypes.\n- Baseline flags are NOT scored, but shortlist rationale must call out any red/orange baseline flags for shortlisted candidates (briefly).\n\n**Set context variables (required):**\n- shortlist: normalized candidates array\n- shortlistCount: number\n- shortlistNonTopOfMindCount: number\n- shortlistNonObviousCount: number\n- shortlistRedFlagCount: number\n\n**Required output format (exact keys):**\n- shortlistCount: <number>\n- shortlistNonTopOfMindCount: <number>\n- shortlistNonObviousCount: <number>\n- shortlistRedFlagCount: <number>\n- shortlistRangeCheck: ok\n\nUpdate `RELOCATION_DOSSIER.md`:\n- Shortlist section with rationale per shortlisted candidate\n- Profiles Index (planned profile files)\n\nAsk user to confirm the shortlist before deep dives.",
       "agentRole": "You are a curator optimizing for diversity, fit, and decision usefulness.",
       "validationCriteria": [
         {
@@ -345,6 +506,16 @@
           "value": "shortlistNonTopOfMindCount",
           "message": "Must set shortlistNonTopOfMindCount"
         },
+        {
+          "type": "contains",
+          "value": "shortlistNonObviousCount",
+          "message": "Must set shortlistNonObviousCount"
+        },
+        {
+          "type": "contains",
+          "value": "shortlistRedFlagCount",
+          "message": "Must set shortlistRedFlagCount"
+        },
         {
           "type": "regex",
           "pattern": "shortlistRangeCheck:\\s*ok",
@@ -375,7 +546,7 @@
         {
           "id": "phase-5a-write-profile",
           "title": "Profile Deep Dive: {{shortCandidate.name}}",
-          "prompt": "Create/update the per-candidate profile doc at `relocation-profiles/<candidate-slug>.md`.\n\nRequired: include boundary explicitly at the top:\n- CandidateType\n- AreaSpec (exact boundary)\n\nModule-driven rule (required):\n- Include a section ONLY if its module is active in `activeModules`.\n- If a module is inactive, omit the section (do not include placeholders).\n\nProfile template (must follow):\n- Summary (who it fits / who it doesn't)\n- Housing (rent/buy ranges, inventory notes, neighborhood variation)\n- Cost of living (beyond housing)\n- Taxes (income/property/sales; major gotchas)\n- Safety (high-level + neighborhood variance; avoid false precision)\n- Schools/childcare (module: kids/schools)\n- Commute/transit (modules: commute, transit)\n- Healthcare access (module: healthcare access)\n- Climate & climate risk (module: climate risk)\n- Job market (module: career/job market)\n- Lifestyle (modules: outdoors, nightlife/arts, diversity/community)\n- Pros / Cons (evidence-backed)\n\n**Required headings (non-optional):**\n- ## Unknowns & follow-ups\n- ## Claims & Sources\n\nClaims & Sources ledger requirements:\n- Every key claim uses trackClaim() fields: claim, source, retrievedAt, confidenceGrade.\n- If a claim is proxy/aggregate (especially for custom areas), label it as such.\n\nAlso update `RELOCATION_DOSSIER.md`:\n- Add a short entry for this candidate (1 paragraph) linking to the profile and summarizing differentiators.\n\nWrite-or-paste applies.",
+          "prompt": "Create/update the per-candidate profile doc at `relocation-profiles/<candidate-slug>.md`.\n\nRequired: include boundary explicitly at the top:\n- CandidateType\n- AreaSpec (exact boundary)\n\nModule-driven rule (required):\n- Include a section ONLY if its module is active in `activeModules`.\n- If a module is inactive, omit the section (do not include placeholders).\n\nProfile template (must follow):\n- Summary (who it fits / who it doesn't)\n- Housing (rent/buy ranges, inventory notes, neighborhood variation)\n- Cost of living (beyond housing)\n- Taxes (income/property/sales; major gotchas)\n- Safety (high-level + neighborhood variance; avoid false precision)\n- Schools/childcare (module: kids/schools)\n- Commute/transit (modules: commute, transit)\n- Healthcare access (module: healthcare access)\n- Climate & climate risk (module: climate risk)\n- Job market (module: career/job market)\n- Lifestyle (modules: outdoors, nightlife/arts, diversity/community)\n- Amenities & errands (module: amenities/errands)\n- Air quality (module: air quality)\n- Noise (module: noise)\n- Internet & infrastructure (module: internet/infra)\n- Pros / Cons (evidence-backed)\n\n**Required headings (non-optional):**\n- ## Baseline Flags (Not Scored)\n- ## Unknowns & follow-ups\n- ## Claims & Sources\n\nBaseline Flags (Not Scored) requirements:\n- Copy any baseline flags already discovered in Phase 4aa for this candidate (if present).\n- If absent or stale, do a quick refresh within the active modules (bounded; do not over-research).\n- Explicitly state: \"These baseline flags do not affect scoring unless the user chooses to promote them.\"\n\nClaims & Sources ledger requirements:\n- Every key claim uses trackClaim() fields: claim, source, retrievedAt, confidenceGrade.\n- If a claim is proxy/aggregate (especially for custom areas), label it as such.\n\nAlso update `RELOCATION_DOSSIER.md`: \n- Add a short entry for this candidate (1 paragraph) linking to the profile and summarizing differentiators.\n\nWrite-or-paste applies.",
           "agentRole": "You are a meticulous researcher producing consistent, evidence-backed location profiles.",
           "validationCriteria": [
             {
@@ -387,6 +558,11 @@
               "type": "contains",
               "value": "## Unknowns & follow-ups",
               "message": "Profile must include '## Unknowns & follow-ups'"
+            },
+            {
+              "type": "contains",
+              "value": "## Baseline Flags (Not Scored)",
+              "message": "Profile must include '## Baseline Flags (Not Scored)'"
             }
           ],
           "requireConfirmation": false
@@ -396,7 +572,7 @@
     {
       "id": "phase-6-compare-and-rank",
       "title": "Phase 6: Comparison & Explainable Ranking",
-      "prompt": "Produce the final comparison and ranking.\n\n1) Build a comparison matrix in `RELOCATION_DOSSIER.md`:\n- Rows: shortlisted candidates\n- Columns: the weighted criteria\n- Include Unknown markers explicitly\n\n2) Deterministic scoring model (required):\n- For each criterion, assign a normalized subscore:\n  - Strong fit = 1.0\n  - Mixed/conditional fit = 0.5\n  - Weak fit = 0.0\n  - Unknown = depends on missingDataPolicy\n- Missing data handling (must be explicit and consistent):\n  - missingDataPolicy=neutral → Unknown subscore = 0.5\n  - missingDataPolicy=penalize → Unknown subscore = 0.25\n  - missingDataPolicy=followup_required → Unknown subscore = 0.5 AND candidate is ineligible for top 3 if it has Unknown on any criterion with weight >= 15\n\nScore formula:\n- totalScore = Σ (weight_i * subscore_i)\n\n3) For each candidate, add an explainable narrative:\n- \"Ranks #k because it wins on X/Y and loses on Z. Biggest tradeoff: ...\"\n\n4) Produce final ranked list (top to bottom) with confidence notes and key caveats.\n\n5) Re-weight gate (bounded):\n- Ask user to confirm if ranking is directionally correct.\n- If not, allow ONE re-weight of `weights` and re-run scoring.\n- Output `reweightUsed: true|false`.\n\n**Required output format (exact keys):**\n- ranking: [{ name: string, totalScore: number, rank: number }]\n- unknownsImpactSummary: <string>\n- reweightUsed: true|false\n\nUpdate Decision Log with any weight changes and rationale.",
+      "prompt": "Produce the final comparison and ranking.\n\n1) Build a comparison matrix in `RELOCATION_DOSSIER.md`:\n- Rows: shortlisted candidates\n- Columns: the weighted criteria\n- Include Unknown markers explicitly\n\nAlso include a separate, clearly labeled appendix/table for baseline flags:\n- Baseline Flags (Not Scored): summarize red/orange baseline flags per candidate\n- These baseline flags do NOT change totalScore\n\n2) Deterministic scoring model (required):\n- For each criterion, assign a normalized subscore:\n  - Strong fit = 1.0\n  - Mixed/conditional fit = 0.5\n  - Weak fit = 0.0\n  - Unknown = depends on missingDataPolicy\n- Missing data handling (must be explicit and consistent):\n  - missingDataPolicy=neutral → Unknown subscore = 0.5\n  - missingDataPolicy=penalize → Unknown subscore = 0.25\n  - missingDataPolicy=followup_required → Unknown subscore = 0.5 AND candidate is ineligible for top 3 if it has Unknown on any criterion with weight >= 15\n\nScore formula:\n- totalScore = Σ (weight_i * subscore_i)\n\n3) For each candidate, add an explainable narrative:\n- \"Ranks #k because it wins on X/Y and loses on Z. Biggest tradeoff: ...\"\n\n4) Produce final ranked list (top to bottom) with confidence notes and key caveats.\n\n5) Re-weight gate (bounded):\n- Ask user to confirm if ranking is directionally correct.\n- If not, allow ONE re-weight of `weights` and re-run scoring.\n- Output `reweightUsed: true|false`.\n\n**Required output format (exact keys):**\n- ranking: [{ name: string, totalScore: number, rank: number }]\n- unknownsImpactSummary: <string>\n- reweightUsed: true|false\n\nUpdate Decision Log with any weight changes and rationale.",
       "agentRole": "You are an analyst producing an explainable, evidence-backed ranking with explicit tradeoffs.",
       "validationCriteria": [
         {