@exaudeus/workrail 3.11.2 → 3.13.0

package/workflows/relocation-workflow-us.json

@@ -1,415 +1,123 @@
 {
   "id": "relocation-workflow-us",
-  "name": "Relocation Decision Workflow (US v1 — AreaSpec • Custom Areas • Dossier • Evidence • Ranking)",
-  "version": "0.2.0",
-  "description": "A bias-resistant, evidence-driven relocation workflow for the United States. Helps users discover what they care about, generate a broad candidate pool (including optional custom areas), screen it with strict caps, deep-dive shortlisted areas, and produce a master dossier plus per-location profile docs with a transparent, explainable weighted ranking.",
+  "name": "US Relocation Decision Workflow (Evidence-Driven • AreaSpec • Ranked Dossier)",
+  "version": "1.0.0",
+  "description": "An evidence-driven relocation workflow for the United States. Discovers preferences, generates a broad candidate pool with anti-anchoring discipline, screens with strict caps, deep-dives a shortlist, and produces a ranked dossier with per-location profiles and an explainable weighted ranking.",
+  "recommendedPreferences": {
+    "recommendedAutonomy": "guided",
+    "recommendedRiskPolicy": "conservative"
+  },
   "preconditions": [
     "User is considering relocation within the United States (v1 scope).",
     "Agent can research the web and/or use user-provided sources.",
-    "Agent can write files to maintain a durable paper trail (or paste canonical artifacts if file writing is unavailable)."
+    "Agent can write files to maintain a durable paper trail, or paste canonical content in chat if file writing is unavailable."
   ],
   "clarificationPrompts": [
-    "Are you relocating within the US only (this v1 workflow), or do you want an international-capable version?",
     "What is your expected timeline to move (0-3 months, 3-12 months, 12+ months)?",
-    "What is your household situation (single, couple, family with kids, multi-generational, etc.) and which constraints matter most?",
-    "Do you need to consider a specific job market / visa / employer location constraint (even within the US)?",
+    "What is your household situation (single, couple, family with kids, multi-generational) and which constraints matter most?",
+    "Do you need to consider a specific job market or employer location constraint?",
     "What is your rough budget range (housing, total monthly burn) and are you buying or renting?"
   ],
   "metaGuidance": [
-    "MISSION: Help the user pick where to move by systematically discovering preferences, researching candidates, and producing an evidence-backed, explainable ranking.",
-    "ANTI-ANCHORING: Do not deep-dive a single favorite city early. Generate a broad pool first, then screen, then shortlist, then deep dive.",
-    "PAPER TRAIL: Maintain a master dossier and per-location profile docs. Every key claim must be sourced and graded (High/Medium/Low).",
-    "DATA VARIANCE: If a metric is unavailable or inconsistent, record it as Unknown and apply the explicit missing-data policy (never silently assume).",
-    "BOUNDARIES (CRITICAL): Prevent boundary drift by representing every candidate as an AreaSpec (what exactly the 'area' is). Never switch boundaries mid-run without logging it.",
-    "CUSTOM AREAS: v1 supports custom areas via a single custom boundary mode: radius (center + radiusMiles). More precise custom modes can be added later.",
-    "SCREENING MUST SCALE: First-pass screening must be intentionally thin (dealbreakers + top criteria only) with strict time/source/claim caps. Deep dives are where detail lives.",
-    "BRANCHING: Keep this workflow generic via lightweight modules (kids/schools, commute, transit, climate risk, etc.) rather than rigid personas.",
-    "OUTPUT SHAPE: One master dossier + one profile doc per shortlisted candidate. Keep formatting consistent to enable side-by-side comparison.",
-    "QUALITY GATES: Require user confirmation at criteria lock-in, shortlist selection, and final ranking."
-  ],
-  "functionDefinitions": [
-    {
-      "name": "writeOrPasteArtifact",
-      "definition": "When a step requires a durable artifact, attempt to write/update the file(s). If file writing is unavailable, output the full pasteable content in chat and treat that as canonical."
-    },
-    {
-      "name": "captureCheckpoint",
-      "definition": "Append a 'Machine State Checkpoint' entry to `RELOCATION_DOSSIER.md` that is BOTH human-meaningful and machine-resumable.\n\nRequired fields:\n- timestamp (ISO)\n- lastCompletedStepId\n- missingDataPolicy\n- weights summary (top 3 criteria + weights)\n- candidatePoolCount, nonObviousCandidateCount, shortlistCount\n- unresolved unknowns summary (1–3 bullets)\n\nDeterministic resume payload (non-optional):\n- Paste the raw `response.state` object from the latest `workflow_next` call\n- Paste the raw `response.next.stepInstanceId` object from the latest `workflow_next` call\n\nRules:\n- Keep the last 3 checkpoints only (delete older)\n- Do not stringify the JSON objects (paste as objects)\n- If you cannot write the file: paste the full updated section in chat and treat it as canonical."
-    },
-    {
-      "name": "trackClaim",
-      "definition": "For each important statement about a location (cost, taxes, schools, crime, climate, job market, etc.), record: claim, source (URL or citation), retrievedAt (date), and confidenceGrade (High/Medium/Low). If unsure, grade Low."
-    },
-    {
-      "name": "areaSpec",
-      "definition": "Represent the exact boundary of a candidate deterministically using an AreaSpec.\n\nAreaSpec fields (v1):\n- areaId: stable slug for the run (derive from candidateType + displayName + stateCodes; keep consistent)\n- displayName: human-friendly\n- candidateType: metro|city|county|custom\n- region: freeform (e.g., \"New England\", \"Mid-Atlantic\", \"Southeast\")\n- stateCodes: string[] (required)\n\nBoundary definition (by candidateType):\n- metro: { metroName: string, states: string[], definitionSource: string }\n- city: { cityName: string, stateCode: string }\n- county: { countyName: string, stateCode: string, fips?: string }\n- custom (v1 mode): { mode: \"radius\", center: { place: string, stateCode: string }, radiusMiles: number }\n\nRule: No candidate may enter candidatePool without an AreaSpec."
-    },
-    {
-      "name": "normalizeCandidate",
-      "definition": "Represent each candidate consistently using: { areaId, name, region, candidateType (metro/city/county/custom), areaSpec, whyIncluded, dealbreakersPassed, unknowns, notes }.\n\n- name should match areaSpec.displayName\n- areaId must be stable (do not change mid-run)\n- unknowns is a short list of unresolved questions (strings)"
-    },
-    {
-      "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 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",
-      "definition": "Explicitly choose how Unknown affects scoring: neutral, penalize, or followup_required. Apply consistently across all candidates and explain the choice in the dossier."
-    },
-    {
-      "name": "antiAnchoringGate",
-      "definition": "Do not proceed to deep dives unless candidatePoolCount >= minCandidatePool AND nonObviousCandidateCount >= minNonObviousCandidates. If not met, expand the pool first."
-    }
+    "DEFAULT BEHAVIOR: self-execute with tools. Ask the user only for true preferences, real confirmations, and any external context you cannot find yourself.",
+    "V2 DURABILITY: use output.notesMarkdown and explicit context variables as the durable record. RELOCATION_DOSSIER.md and profile docs are human-facing artifacts — they are NOT required workflow memory and are never read back for routing.",
+    "ANTI-ANCHORING: generate a broad pool first; screen second; deep-dive only the shortlist. Do not deep-dive a single favorite area early.",
+    "AREA BOUNDARIES: every candidate must have an AreaSpec before entering the pool. Use areaId = <candidateType>-<slug(displayName)>-<sortedStateCodes> (e.g. metro-raleigh-durham-nc). Never switch a candidate's boundary mid-run without logging it.",
+    "CLAIMS LEDGER: every key claim about a location must include source (URL or citation), retrievedAt (date), and confidenceGrade (High/Medium/Low). If a claim cannot be sourced, grade it Low.",
+    "MISSING DATA: when a data point is unavailable, record it as Unknown and apply the chosen missingDataPolicy consistently. Never silently assume a value for an Unknown.",
+    "ARTIFACTS: try to write files (RELOCATION_DOSSIER.md, relocation-profiles/<slug>.md). If file writing is unavailable, paste full canonical content in chat and treat that as the record.",
+    "MODULES: activate only sections relevant to activeModules. Do not include placeholder sections for inactive modules.",
+    "SCREENING CAPS: first-pass screening must stay fast — dealbreakers plus top weighted criteria only, strict claim and time caps. Deep research belongs in Phase 6 deep dives.",
+    "NON-OBVIOUS CANDIDATES: non-obvious = not in userTopOfMind AND not in top-100 US metros. If you cannot map a candidate to the top-100 list deterministically, mark obviousness Unknown and do not count it toward non-obvious requirements."
   ],
   "steps": [
     {
-      "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   - 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": [
-        {
-          "type": "contains",
-          "value": "activeModules",
-          "message": "Must set activeModules"
-        },
-        {
-          "type": "contains",
-          "value": "candidateType",
-          "message": "Must set candidateType"
-        },
-        {
-          "type": "contains",
-          "value": "customAreaMode",
-          "message": "Must set customAreaMode"
-        },
-        {
-          "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
-    },
-    {
-      "id": "phase-0b-area-model-and-boundary-rules",
-      "title": "Phase 0b: Area Model & Boundary Rules (Prevent Boundary Drift)",
-      "prompt": "Lock in how candidates are defined so research and scoring are comparable.\n\n1) Define and record the AreaSpec model (use the `areaSpec()` definition).\n2) Confirm custom boundary mode (v1): `customAreaMode = radius`.\n3) Define deterministic Area ID rules (record in dossier):\n   - areaId = <candidateType>-<slug(displayName)>-<sortedStateCodes>\n   - Example: metro-raleigh-durham-nc\n4) Define boundary resolution rules:\n   - For metro: explicitly treat as the metro area (not just the city). Record the metro definition source.\n   - For city/county: record state code, and FIPS if found.\n   - For custom radius: record center + radiusMiles; do not silently expand.\n\nUpdate `RELOCATION_DOSSIER.md`:\n- Boundary & Definitions (AreaSpec rules + areaId rules)\n- Aggregation & Comparability Policy (v1):\n  - Prefer narrative + explicit Unknowns over false precision\n  - For custom areas, allow proxy/aggregate only if clearly labeled; otherwise Unknown\n\n**Set context variables (required):**\n- areaIdRule: <string>\n\nOutput (in chat):\n- areaIdRule\n- Confirmation request: proceed with these boundary rules?",
-      "agentRole": "You are a boundary discipline enforcer. Make area definitions explicit and stable.",
-      "validationCriteria": [
-        { "type": "contains", "value": "areaIdRule", "message": "Must set areaIdRule" },
-        { "type": "regex", "pattern": "customAreaMode:\\s*radius", "message": "customAreaMode must be radius for v1" }
-      ],
-      "requireConfirmation": true
-    },
-    {
-      "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\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:",
-          "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"
-        }
-      ],
-      "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 (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": [
-        {
-          "type": "contains",
-          "value": "calibrationTop3",
-          "message": "Must output calibrationTop3"
-        },
-        {
-          "type": "contains",
-          "value": "calibrationBottom3",
-          "message": "Must output calibrationBottom3"
-        },
-        {
-          "type": "contains",
-          "value": "weightsDeltaSummary",
-          "message": "Must output weightsDeltaSummary"
-        },
-        {
-          "type": "contains",
-          "value": "derivedSignals",
-          "message": "Must output derivedSignals"
-        },
-        {
-          "type": "contains",
-          "value": "weights:",
-          "message": "Must output updated weights array"
-        }
-      ],
+      "id": "phase-1-scope-and-preferences",
+      "title": "Phase 1: Scope, Modules & Calibrated Preferences",
+      "promptBlocks": {
+        "goal": "Establish the scope and structure for this relocation search, then discover calibrated preferences and a stable weight model before any research begins.",
+        "constraints": [
+          "Do not start researching candidates yet — preferences and boundary rules must be locked first.",
+          "Activate only modules the user actually needs; do not load everything by default.",
+          "If the user is unsure about weights, offer the MaxDiff helper before finalizing."
+        ],
+        "procedure": [
+          "Step 1 — Confirm scope and initialize artifacts. Confirm this is a US-only v1 relocation search. Ask for userTopOfMind (0-10 areas the user already has in mind; empty is fine). Initialize RELOCATION_DOSSIER.md with sections: User Context & Modules, Boundary & Definitions, Preferences (Draft), Constraints & Dealbreakers, Missing Data Policy, Sources Strategy, Candidate Pool, Screened Candidates, Screening Claims Ledger, Baseline Flags (Not Scored), Red Flag Gate Decisions (append-only), Shortlist, Profiles Index, Comparison & Ranking, Decision Log (append-only). Create the relocation-profiles/ directory.",
+          "Step 2 — Capture user context. Ask about and record: timelineToMove (0-3 months / 3-12 months / 12+ months), householdProfile (single / couple / family with kids / multi-generational), housingPlan (rent/buy/either and budget range), workConstraints (remote/hybrid/onsite; time zones allowed), geoExclusions (states or regions to exclude).",
+          "Step 3 — Select modules. Present the module list and activate all that apply: kids/schools, commute, transit, climate-risk, healthcare-access, career-job-market, outdoors, nightlife-arts, safety, taxes, diversity-community, disability-accessibility, amenities-errands, air-quality, noise, internet-infra. Record as activeModules.",
+          "Step 4 — Lock boundary rules. Set candidateType (default: metro; options: city, county, custom). Record the AreaSpec model: areaId = <candidateType>-<slug(displayName)>-<sortedStateCodes>. For metro candidates, record the definition source and treat the full metro area as the boundary (not just the city). For custom areas (v1), use radius mode: center (place + stateCode) + radiusMiles. Update RELOCATION_DOSSIER.md Boundary & Definitions section.",
+          "Step 5 — Elicit preferences. Ask about: hard constraints (must-have geography, climate, budget, job, family, health), anti-goals (explicit non-goals), dealbreakers. Draft 6-10 weighted criteria across active modules; weights must sum to 100. If the user is unsure, start with equal-weight draft and offer MaxDiff.",
+          "Step 6 — Optional MaxDiff weight derivation. Ask: 'Do you want help deriving weights using Most/Least comparisons?' If yes: build deterministic rotation sets (N<=7: 3 sets of 4; N>=8: 4 sets of 5). For each set ask which criterion is MOST important and which is LEAST. Derive weights: raw[c] = mostCount[c] - leastCount[c]; shifted[c] = raw[c] - min(raw) + 1; weight[c] = round(shifted[c] / sum(shifted) * 100); adjust largest weight so sum = exactly 100. Allow one small tweak pass (up to 2 weights adjusted, then re-normalize).",
+          "Step 7 — Calibration deck. Generate 8-12 diverse US location archetypes (dense transit metro, college town, mountain small city, coastal mid-size, sunbelt suburb, rust-belt revival city, DC-adjacent, etc.). For each: 2-3 sentences on lifestyle and tradeoffs, who it fits, who it frustrates. Ask the user to rank top 3 and bottom 3 and name 1-2 surprises. Update weights and constraints if calibration reveals new signal. Record derivedSignals (densityLeaning, climateLeaning, regionLeaning).",
+          "Capture these context variables: activeModules, candidateType, userTopOfMind, timelineToMove, householdProfile, housingPlan, workConstraints, geoExclusions, dealbreakers, weights (array of {criterion, weight}), weightsCount, derivedSignals."
+        ],
+        "verify": [
+          "weights sum to exactly 100",
+          "activeModules is non-empty",
+          "candidateType is set",
+          "dealbreakers are explicit (not empty)",
+          "calibration deck has been shown and user has responded"
+        ]
+      },
       "requireConfirmation": true
     },
     {
       "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) 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)",
-          "message": "missingDataPolicy must be one of neutral|penalize|followup_required"
-        },
-        {
-          "type": "contains",
-          "value": "minCandidatePool",
-          "message": "Must set minCandidatePool"
-        },
-        {
-          "type": "contains",
-          "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",
-          "message": "Must set shortlistMin"
-        },
-        {
-          "type": "contains",
-          "value": "shortlistMax",
-          "message": "Must set shortlistMax"
-        },
-        {
-          "type": "contains",
-          "value": "screeningTopCriteriaCount",
-          "message": "Must set screeningTopCriteriaCount"
-        },
-        {
-          "type": "contains",
-          "value": "screeningMaxClaimsPerCandidate",
-          "message": "Must set screeningMaxClaimsPerCandidate"
-        },
-        {
-          "type": "contains",
-          "value": "screeningTimeboxMinutesPerCandidate",
-          "message": "Must set screeningTimeboxMinutesPerCandidate"
-        },
-        {
-          "type": "contains",
-          "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",
-          "message": "Must confirm shortlistMin <= shortlistMax"
-        }
-      ],
+      "title": "Phase 2: Decision Policies & Gate Parameters",
+      "promptBlocks": {
+        "goal": "Lock the decision mechanics and gate parameters before any candidate research begins. These policies govern how ambiguity, missing data, and diversity requirements are handled throughout the workflow.",
+        "constraints": [
+          "Every policy must be explicit — no implicit defaults allowed past this gate.",
+          "The user must confirm these settings before Phase 3 begins."
+        ],
+        "procedure": [
+          "Step 1 — Missing data policy. Ask the user to choose one: (a) neutral — Unknown scores 0.5; (b) penalize — Unknown scores 0.25; (c) followup_required — Unknown scores 0.5 AND candidates with Unknown on any criterion with weight >= 15 are ineligible for the top 3. Record as missingDataPolicy.",
+          "Step 2 — Intake completeness check. Confirm you have enough context to set dealbreakers and weights. If not, note missingInputs and resolve before proceeding.",
+          "Step 3 — Anti-anchoring gate parameters. Propose defaults and ask the user to confirm or adjust: minCandidatePool (default 20), minNonObviousCandidates (default 6), minCoverageRegions (default 3), minCoverageClimateBands (default 2).",
+          "Step 4 — Shortlist range. Propose defaults and ask the user to confirm or adjust: shortlistMin (default 8), shortlistMax (default 12).",
+          "Step 5 — Screening caps. Propose defaults and ask the user to confirm or adjust: screeningTopCriteriaCount (default 3 — screen dealbreakers + top N weighted criteria only), screeningMaxClaimsPerCandidate (default 3), screeningTimeboxMinutesPerCandidate (default 5), screeningBatchSize (default 10).",
+          "Step 6 — Discovery caps. Propose defaults and ask the user to confirm or adjust: perSourceCandidateCap (default 8 — cap per curated-list source to avoid editorial bias).",
+          "Step 7 — Baseline flags caps. Propose defaults and ask the user to confirm or adjust: baselineMaxFlagsPerCandidate (default 2), baselineMaxSourcesPerFlag (default 1), baselineTimeboxMinutesPerCandidate (default 2).",
+          "Update RELOCATION_DOSSIER.md with all policies and caps. Capture all values as context variables: missingDataPolicy, minCandidatePool, minNonObviousCandidates, minCoverageRegions, minCoverageClimateBands, shortlistMin, shortlistMax, screeningTopCriteriaCount, screeningMaxClaimsPerCandidate, screeningTimeboxMinutesPerCandidate, screeningBatchSize, perSourceCandidateCap, baselineMaxFlagsPerCandidate, baselineMaxSourcesPerFlag, baselineTimeboxMinutesPerCandidate."
+        ],
+        "verify": [
+          "missingDataPolicy is one of: neutral, penalize, followup_required",
+          "shortlistMin <= shortlistMax",
+          "all gate parameters are explicit numbers"
+        ]
+      },
       "requireConfirmation": true
     },
     {
-      "id": "phase-2b-checkpoint",
-      "title": "Phase 2b: Checkpoint (Resumability)",
-      "prompt": "Run captureCheckpoint() and append a Machine State Checkpoint entry to `RELOCATION_DOSSIER.md`.\n\nRequired:\n- record lastCompletedStepId = phase-2-policy-and-gates\n- include the raw `response.state` and `response.next.stepInstanceId` objects from the latest `workflow_next` call",
-      "agentRole": "You are maintaining resumability. Capture enough state to resume deterministically.",
-      "requireConfirmation": false
-    },
-    {
-      "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  - 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": [
-        {
-          "type": "contains",
-          "value": "candidatePool",
-          "message": "Must set candidatePool"
-        },
-        {
-          "type": "contains",
-          "value": "candidatePoolCount",
-          "message": "Must set candidatePoolCount"
-        },
-        {
-          "type": "contains",
-          "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",
-          "message": "Must record nonObviousDefinitionUsed"
-        }
-      ],
-      "requireConfirmation": false
-    },
-    {
-      "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- 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": [
-        {
-          "type": "regex",
-          "pattern": "antiAnchoringGate:\\s*(pass|fail)",
-          "message": "Must output antiAnchoringGate: pass|fail"
-        }
-      ],
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-3c-build-screening-batches",
-      "title": "Phase 3c: Build Screening Batches (Chunking)",
-      "prompt": "Prepare chunked screening to avoid excessively large loop iteration limits.\n\nGoal: build `screeningBatches` from `candidatePool` using `screeningBatchSize`.\n\nRules:\n- Preserve candidate order from `candidatePool`.\n- Each batch has at most `screeningBatchSize` candidates.\n- Each batch must be represented deterministically as:\n  - { batchId, startIndex, endIndexExclusive, candidates }\n  - where candidates is the list of normalized candidates (or their names/areaIds), in order.\n\n**Set context variables (required):**\n- screeningBatches: array\n- screeningBatchesCount: number\n\nUpdate `RELOCATION_DOSSIER.md`:\n- Add a short note under \"Screened Candidates\" explaining batching (batch size + number of batches).\n\n**Required output format (exact keys):**\n- screeningBatchSize: <number>\n- screeningBatchesCount: <number>\n- screeningBatches: <present>\n\nThen proceed to Phase 4.",
-      "agentRole": "You are preparing chunked execution. Keep the screening loop bounded and resumable.",
-      "validationCriteria": [
-        { "type": "contains", "value": "screeningBatches:", "message": "Must output screeningBatches" },
-        { "type": "contains", "value": "screeningBatchesCount", "message": "Must output screeningBatchesCount" },
-        { "type": "contains", "value": "screeningBatchSize", "message": "Must output screeningBatchSize" }
-      ],
+      "id": "phase-3-breadth-and-gate",
+      "title": "Phase 3: Breadth Search, Anti-Anchoring Gate & Screening Batches",
+      "promptBlocks": {
+        "goal": "Generate a broad, diverse candidate pool that satisfies the anti-anchoring gate, then build the screening batches for Phase 4.",
+        "constraints": [
+          "Every candidate must have an AreaSpec before entering the pool.",
+          "Cap contributions from any single curated-list source to perSourceCandidateCap to avoid editorial bias.",
+          "Do not proceed to screening until the anti-anchoring gate passes."
+        ],
+        "procedure": [
+          "Step 1 — Sources strategy. Before generating candidates, document the sources strategy in RELOCATION_DOSSIER.md: Housing (Zillow + alternative), Taxes (state revenue sites), Climate normals (NOAA), Climate risk (FEMA flood maps), Employment (BLS / state labor stats), Transit/commute (local agencies), Air quality (AirNow/EPA), Noise (airport contour maps), Internet (FCC broadband map). Include only sources for active modules. Use this sources strategy as your research guide throughout candidate generation — generate the pool from actual data, not from memory alone.",
+          "Step 2 — Generate candidates. Use the weight model and dealbreakers as the filter. For each candidate: assign a stable areaId, record the full AreaSpec (candidateType, displayName, stateCodes, and boundary definition), record why included, tag with candidateFacets (region, climateBand, sizeTier, taxRegime, airportAccess, outdoorsBiome as applicable). Fill coverage gaps deliberately — include a mix of obvious and non-obvious candidates. Include at least minCandidatePool candidates total.",
+          "Step 3 — Anti-anchoring gate. Check: candidatePoolCount >= minCandidatePool, qualifyingNonObviousCandidateCount >= minNonObviousCandidates, coverageRegionsCount >= minCoverageRegions, coverageClimateBandsCount >= minCoverageClimateBands. A 'qualifying non-obvious' candidate is non-obvious AND plausibly passes dealbreakers. Record the top-100 list source used for non-obvious classification. If the gate fails, expand the pool by filling coverage gaps (prefer non-obvious candidates). Repeat until the gate passes.",
+          "Step 4 — Build screening batches. Divide candidatePool into batches of screeningBatchSize, preserving order. Each batch: { batchId, startIndex, endIndexExclusive, candidates }. Record screeningBatches and screeningBatchesCount.",
+          "Update RELOCATION_DOSSIER.md: Candidate Pool table (name, candidateType, region, why included, early risks/unknowns). Capture context variables: candidatePool, candidatePoolCount, nonObviousCandidateCount, qualifyingNonObviousCandidateCount, coverageRegionsCount, coverageClimateBandsCount, screeningBatches, screeningBatchesCount, discoverySourcesUsed, nonObviousDefinitionUsed."
+        ],
+        "verify": [
+          "anti-anchoring gate passed",
+          "every candidate has an AreaSpec",
+          "screeningBatches is non-empty",
+          "discoverySourcesUsed is recorded"
+        ]
+      },
       "requireConfirmation": false
     },
     {
       "id": "phase-4-screening-loop",
       "type": "loop",
-      "title": "Phase 4: First-Pass Screening (Fast, High-Signal)",
+      "title": "Phase 4: First-Pass Screening",
       "loop": {
         "type": "forEach",
         "items": "screeningBatches",
@@ -419,188 +127,106 @@
       },
       "body": [
         {
-          "id": "phase-4a-screen-batch",
+          "id": "phase-4-screen-batch",
           "title": "Screen Batch {{batchIndex}}",
-          "prompt": "Perform a fast, high-signal screening pass for the current batch.\n\nBatch format (from Phase 3c):\n- batch: { batchId, startIndex, endIndexExclusive, candidates }\n\n**Non-negotiable caps (from Phase 2):**\n- For EACH candidate in batch.candidates:\n  - Screen only: dealbreakers + top `screeningTopCriteriaCount` weighted criteria\n  - Max `screeningMaxClaimsPerCandidate` claims recorded for this candidate in screening\n  - Prefer 1 source per claim (screeningMaxSourcesPerClaim); otherwise mark Unknown\n  - Stay within `screeningTimeboxMinutesPerCandidate` minutes PER candidate\n\nInstructions:\n1) Iterate through `batch.candidates` sequentially (do not skip).\n2) For each candidate, produce a `screenResult` (Pass/Fail/Maybe) and update:\n   - `RELOCATION_DOSSIER.md` Screened Candidates table\n   - `RELOCATION_DOSSIER.md` Screening Claims Ledger (capped)\n   - `screenResults` context map\n3) After the batch completes, write a short batch summary into the dossier (one paragraph):\n   - batchId, screened count, pass/fail/maybe counts, any repeated unknown categories\n\nMaintain `screenResults` in context as a map:\n- screenResults: { [candidateName: string]: \"Pass\"|\"Fail\"|\"Maybe\" }\n\n**Required output format (exact keys):**\n- batchId: <string>\n- batchScreenedCount: <number>\n- batchPassCount: <number>\n- batchFailCount: <number>\n- batchMaybeCount: <number>",
-          "agentRole": "You are doing triage-level screening in batches to keep the workflow scalable and resumable.",
-          "validationCriteria": [
-            {
-              "type": "contains",
-              "value": "batchId",
-              "message": "Must output batchId"
-            },
-            {
-              "type": "contains",
-              "value": "batchScreenedCount",
-              "message": "Must output batchScreenedCount"
-            },
-            {
-              "type": "contains",
-              "value": "batchPassCount",
-              "message": "Must output batchPassCount"
-            },
-            {
-              "type": "contains",
-              "value": "batchFailCount",
-              "message": "Must output batchFailCount"
-            },
-            {
-              "type": "contains",
-              "value": "batchMaybeCount",
-              "message": "Must output batchMaybeCount"
-            }
-          ],
-          "requireConfirmation": false
+          "prompt": "Screen the current batch with a fast, high-signal pass.\n\nBatch: { batchId, startIndex, endIndexExclusive, candidates }\n\nFor each candidate in batch.candidates (do not skip):\n- Screen only: dealbreakers + top screeningTopCriteriaCount weighted criteria\n- Record at most screeningMaxClaimsPerCandidate claims per candidate in the Screening Claims Ledger\n- Prefer 1 source per claim; mark Unknown if unavailable\n- Stay within screeningTimeboxMinutesPerCandidate per candidate\n- Assign a screenResult: Pass, Fail, or Maybe\n\nAfter all candidates in the batch:\n- Update RELOCATION_DOSSIER.md Screened Candidates table (add each result)\n- Append batch summary to Screening Claims Ledger (batchId, screened count, pass/fail/maybe counts, repeated unknown categories)\n- Update screenResults context map: { [candidateName]: 'Pass' | 'Fail' | 'Maybe' }"
         }
       ]
     },
     {
-      "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" }
-      ],
+      "id": "phase-4-baseline-flags",
+      "title": "Phase 4b: Baseline Due Diligence (Not Scored)",
+      "prompt": "Run a lightweight baseline pass on all Pass or Maybe candidates from screenResults.\n\nScope — check only:\n- Climate risk (high-level: flood zone, wildfire, extreme heat)\n- Safety and crime (high-level: neighborhood-level variance)\n- Schools and healthcare access — only if kids/schools or healthcare-access modules are active\n\nCaps (apply strictly):\n- At most baselineMaxFlagsPerCandidate flags per candidate\n- At most baselineMaxSourcesPerFlag sources per flag\n- At most baselineTimeboxMinutesPerCandidate minutes per candidate\n\nFor each Pass/Maybe candidate, produce 0 to baselineMaxFlagsPerCandidate baseline flags. Each flag: category (climate/safety/schools/healthcare/policy/other), severity (yellow/orange/red), one-sentence summary, source, retrievedAt, confidenceGrade. A red flag has severity = red.\n\nDo NOT compute or modify any scores here. Do NOT silently turn flags into dealbreakers or weights. If evidence is unclear, record Unknown.\n\nUpdate RELOCATION_DOSSIER.md: add Baseline Flags (Not Scored) section with per-candidate table.\n\nCapture context variables: baselineFlags ({ [candidateKey]: { flags: array, unknowns: string[] } }), redFlagCandidates (string[]), redFlagCount (number).",
       "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": [
+      "id": "phase-4-red-flag-gate",
+      "title": "Phase 4c: Red Flag Gate",
+      "promptFragments": [
         {
-          "type": "regex",
-          "pattern": "redFlagDecision:\\s*(promote_to_dealbreakers|add_weighted_criterion|fyi)",
-          "message": "Must set redFlagDecision"
+          "id": "no-red-flags",
+          "when": { "var": "redFlagCount", "equals": 0 },
+          "text": "No red flags were detected. Record redFlagDecision = 'fyi' and redFlagDecisionNotes = 'No red flags detected in baseline due diligence.' Proceed to Phase 5."
         },
         {
-          "type": "contains",
-          "value": "redFlagDecisionNotes",
-          "message": "Must set redFlagDecisionNotes"
+          "id": "has-red-flags",
+          "when": { "var": "redFlagCount", "gt": 0 },
+          "text": "Red flags were found. Summarize each: candidate name, category, one-line summary, source. Ask the user to choose exactly one action: (a) promote_to_dealbreakers — update the `dealbreakers` context variable AND the RELOCATION_DOSSIER.md Constraints section with the new/updated dealbreakers, then re-check screenResults for affected candidates; (b) add_weighted_criterion — ask the user how to weight it and which existing weights decrease so the `weights` array still sums to 100; (c) fyi — record the decision and move on. Record redFlagDecision and redFlagDecisionNotes. Append to RELOCATION_DOSSIER.md Red Flag Gate Decisions (append-only)."
         }
       ],
+      "prompt": "Handle baseline red flags before selecting the shortlist.",
       "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- 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": [
-        {
-          "type": "contains",
-          "value": "shortlist",
-          "message": "Must set shortlist"
-        },
-        {
-          "type": "contains",
-          "value": "shortlistCount",
-          "message": "Must set shortlistCount"
-        },
-        {
-          "type": "contains",
-          "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",
-          "message": "Must confirm shortlistMin <= shortlistCount <= shortlistMax"
-        }
-      ],
+      "id": "phase-5-shortlist",
+      "title": "Phase 5: Shortlist Selection",
+      "promptBlocks": {
+        "goal": "Select a diverse, curated shortlist of candidates for deep dives.",
+        "constraints": [
+          "Shortlist must be within shortlistMin to shortlistMax candidates.",
+          "Must include at least 3 candidates outside userTopOfMind (if provided).",
+          "Baseline flags do not affect scores, but the shortlist rationale must call out any red/orange flags for shortlisted candidates."
+        ],
+        "procedure": [
+          "Review screenResults: all Pass and Maybe candidates are eligible. If too many pass, prefer diversity across archetypes, regions, and climate bands over ranking by screening signal.",
+          "For each shortlisted candidate, write a short rationale: why included, any notable red/orange baseline flags, what makes it distinct.",
+          "Update RELOCATION_DOSSIER.md: Shortlist section (rationale per candidate), Profiles Index (planned profile file paths).",
+          "Capture context variables: shortlist (normalized candidates array), shortlistCount, shortlistNonTopOfMindCount, shortlistNonObviousCount, shortlistRedFlagCount."
+        ],
+        "verify": [
+          "shortlistCount is between shortlistMin and shortlistMax",
+          "shortlistNonTopOfMindCount >= 3 (or all shortlisted candidates if userTopOfMind is empty)",
+          "every shortlisted candidate has a rationale"
+        ]
+      },
       "requireConfirmation": true
     },
     {
-      "id": "phase-4c-checkpoint",
-      "title": "Phase 4c: Checkpoint (After Shortlist Confirmation)",
-      "prompt": "Run captureCheckpoint() and append a Machine State Checkpoint entry to `RELOCATION_DOSSIER.md`.\n\nRequired:\n- record lastCompletedStepId = phase-4b-select-shortlist\n- include the raw `response.state` and `response.next.stepInstanceId` objects from the latest `workflow_next` call",
-      "agentRole": "You are maintaining resumability. Capture enough state to resume deterministically.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-5-profile-deep-dive-loop",
+      "id": "phase-6-deep-dive-loop",
       "type": "loop",
-      "title": "Phase 5: Deep Dives (Per-Candidate Profiles)",
+      "title": "Phase 6: Deep Dives (Per-Candidate Profiles)",
       "loop": {
         "type": "forEach",
         "items": "shortlist",
         "itemVar": "shortCandidate",
         "indexVar": "shortIndex",
-        "maxIterations": 50
+        "maxIterations": 20
       },
       "body": [
         {
-          "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- 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": [
-            {
-              "type": "contains",
-              "value": "## Claims & Sources",
-              "message": "Profile must include '## Claims & Sources'"
-            },
-            {
-              "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
+          "id": "phase-6-write-profile",
+          "title": "Profile: {{shortCandidate.name}}",
+          "prompt": "Create or update the per-candidate profile at relocation-profiles/<candidate-slug>.md.\n\nStart with the boundary:\n- CandidateType and AreaSpec (exact boundary)\n\nModule-driven rule: include a section only if its module is active in activeModules. Omit sections for inactive modules entirely (no placeholders).\n\nProfile structure:\n- Summary (who it fits / who it doesn't)\n- Housing (rent/buy ranges, inventory, 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 [kids/schools module]\n- Commute/transit [commute, transit modules]\n- Healthcare access [healthcare-access module]\n- Climate & climate risk [climate-risk module]\n- Job market [career-job-market module]\n- Lifestyle [outdoors, nightlife-arts, diversity-community modules]\n- Amenities & errands [amenities-errands module]\n- Air quality [air-quality module]\n- Noise [noise module]\n- Internet & infrastructure [internet-infra module]\n- Pros / Cons (evidence-backed)\n\nRequired sections (always include):\n## Baseline Flags (Not Scored)\nCopy baseline flags from Phase 4b for this candidate. If absent or stale, do a quick refresh within active modules (stay within caps). State explicitly: 'These baseline flags do not affect scoring unless the user chooses to promote them.'\n\n## Unknowns & Follow-ups\nList unresolved questions. Apply missingDataPolicy to any Unknowns that will affect scoring.\n\n## Claims & Sources\nEvery key claim: { claim, source (URL or citation), retrievedAt, confidenceGrade (High/Medium/Low) }. For proxy/aggregate claims (especially custom areas), label them as such.\n\nAlso add a short entry for this candidate in RELOCATION_DOSSIER.md (1 paragraph, link to profile, key differentiators)."
         }
       ]
     },
     {
-      "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\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": [
-        {
-          "type": "contains",
-          "value": "ranking:",
-          "message": "Must output ranking list"
-        },
-        {
-          "type": "contains",
-          "value": "reweightUsed",
-          "message": "Must output reweightUsed"
-        }
-      ],
+      "id": "phase-7-rank-and-next-steps",
+      "title": "Phase 7: Comparison, Ranking & Next Steps",
+      "promptBlocks": {
+        "goal": "Produce the final comparison matrix, explainable ranking, and a practical next-steps plan.",
+        "constraints": [
+          "The score formula must be applied consistently to every candidate.",
+          "Unknowns must be disclosed in the ranking narrative — never presented as if they were evidence-backed.",
+          "Baseline flags (not scored) are shown separately and do not change totalScore.",
+          "One re-weight pass is allowed if the user says the ranking direction is wrong."
+        ],
+        "procedure": [
+          "Step 1 — Comparison matrix. Build a table in RELOCATION_DOSSIER.md: rows = shortlisted candidates, columns = weighted criteria. Mark Unknowns explicitly. Add a separate appendix table for baseline flags (Not Scored): red/orange flags per candidate.",
+          "Step 2 — Score each candidate. For each criterion, assign a normalized subscore: Strong fit = 1.0, Mixed/conditional = 0.5, Weak fit = 0.0. For Unknowns: neutral policy → 0.5; penalize policy → 0.25; followup_required policy → 0.5 and flag candidate ineligible for top 3 if Unknown on any criterion with weight >= 15. Compute totalScore = sum(weight_i * subscore_i) for each candidate.",
+          "Step 3 — Ranking narrative. For each candidate write: 'Ranks #k because it wins on X and Y, loses on Z. Biggest tradeoff: ...' Make sure all Unknown subscores are called out explicitly in the narrative.",
+          "Step 4 — Re-weight gate. Ask the user: 'Does this ranking direction feel correct?' If not, allow one re-weight (user adjusts any number of criteria weights; must still sum to 100; re-run scoring). Record reweightUsed (true/false). Update Decision Log with any weight changes and rationale.",
+          "Step 5 — Next steps. Produce: suggested visit plan for top 2-4 candidates (what to validate in person), open questions per candidate (from Unknowns sections), pivot triggers (what evidence would change the ranking), optional neighborhood-level follow-ups if enough evidence exists. Update RELOCATION_DOSSIER.md with Next Steps and Pivot Triggers.",
+          "Capture context variables: ranking ([{name, totalScore, rank}]), unknownsImpactSummary, reweightUsed."
+        ],
+        "verify": [
+          "every shortlisted candidate appears in the ranking",
+          "all Unknown subscores are disclosed in the narrative",
+          "reweightUsed is set",
+          "next steps are specific to each top candidate"
+        ]
+      },
       "requireConfirmation": true
-    },
-    {
-      "id": "phase-6b-checkpoint",
-      "title": "Phase 6b: Checkpoint (After Ranking)",
-      "prompt": "Run captureCheckpoint() and append a Machine State Checkpoint entry to `RELOCATION_DOSSIER.md`.\n\nRequired:\n- record lastCompletedStepId = phase-6-compare-and-rank\n- include the raw `response.state` and `response.next.stepInstanceId` objects from the latest `workflow_next` call",
-      "agentRole": "You are maintaining resumability. Capture enough state to resume deterministically.",
-      "requireConfirmation": false
-    },
-    {
-      "id": "phase-7-next-steps",
-      "title": "Phase 7: Next Steps (Validation in the Real World)",
-      "prompt": "Create a practical next-steps plan.\n\nInclude:\n- Suggested visit plan for top 2–4 candidates (what to validate in person)\n- Open questions per candidate (from Unknowns)\n- What would change your mind (pivot triggers)\n- Optional: recommended neighborhoods to investigate further (if you have enough evidence; otherwise mark Unknown)\n\nUpdate `RELOCATION_DOSSIER.md` with Next Steps and Pivot Triggers.\n\nOutput: concise next-steps checklist.",
-      "agentRole": "You are a pragmatic planner. Translate analysis into actionable validation steps.",
-      "requireConfirmation": false
     }
   ]
 }