@exaudeus/workrail 0.11.0 → 0.13.0

package/workflows/design-thinking-workflow-autonomous.agentic.json

@@ -110,7 +110,7 @@
       "id": "phase-3-ideation-loop",
       "type": "loop",
       "title": "Phase 3: Ideation (4 Rounds)",
-      "loop": { "type": "for", "count": 4, "maxIterations": 4, "iterationVar": "ideationRound" },
+      "loop": { "type": "for", "count": 4, "maxIterations": 5, "iterationVar": "ideationRound" },
       "body": [
         {
           "id": "ideation-round-1",

package/workflows/design-thinking-workflow.json

@@ -92,7 +92,7 @@
       "loop": {
         "type": "for",
         "count": 4,
-        "maxIterations": 4,
+        "maxIterations": 5,
         "iterationVar": "ideationRound"
       },
       "body": [

package/workflows/relocation-workflow-us.json

@@ -0,0 +1,430 @@
+{
+  "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.",
+  "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)."
+  ],
+  "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 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 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."
+    },
+    {
+      "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."
+    }
+  ],
+  "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\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.",
+      "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)"
+        }
+      ],
+      "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\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).",
+      "agentRole": "You are a facilitator eliciting preferences through tradeoffs and constraints.",
+      "validationCriteria": [
+        {
+          "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-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.",
+      "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": "weights:",
+          "message": "Must output updated weights array"
+        }
+      ],
+      "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) 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.",
+      "agentRole": "You are a decision systems designer. Make ambiguity explicit and policy-driven.",
+      "validationCriteria": [
+        {
+          "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": "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": "regex",
+          "pattern": "shortlistRangeCheck:\\s*ok",
+          "message": "Must confirm shortlistMin <= shortlistMax"
+        }
+      ],
+      "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\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>",
+      "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": "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- 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.",
+      "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" }
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-4-screening-loop",
+      "type": "loop",
+      "title": "Phase 4: First-Pass Screening (Fast, High-Signal)",
+      "loop": {
+        "type": "forEach",
+        "items": "screeningBatches",
+        "itemVar": "batch",
+        "indexVar": "batchIndex",
+        "maxIterations": 30
+      },
+      "body": [
+        {
+          "id": "phase-4a-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
+        }
+      ]
+    },
+    {
+      "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.",
+      "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": "regex",
+          "pattern": "shortlistRangeCheck:\\s*ok",
+          "message": "Must confirm shortlistMin <= shortlistCount <= shortlistMax"
+        }
+      ],
+      "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",
+      "type": "loop",
+      "title": "Phase 5: Deep Dives (Per-Candidate Profiles)",
+      "loop": {
+        "type": "forEach",
+        "items": "shortlist",
+        "itemVar": "shortCandidate",
+        "indexVar": "shortIndex",
+        "maxIterations": 50
+      },
+      "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- 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.",
+          "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'"
+            }
+          ],
+          "requireConfirmation": false
+        }
+      ]
+    },
+    {
+      "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.",
+      "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"
+        }
+      ],
+      "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
+    }
+  ]
+}

package/dist/v2/durable-core/tokens/base64url.d.ts

@@ -1,7 +0,0 @@
-import type { Result } from 'neverthrow';
-export type Base64UrlError = {
-    readonly code: 'BASE64URL_INVALID';
-    readonly message: string;
-};
-export declare function encodeBase64Url(bytes: Uint8Array): string;
-export declare function decodeBase64Url(input: string): Result<Uint8Array, Base64UrlError>;

package/dist/v2/durable-core/tokens/base64url.js

@@ -1,16 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.encodeBase64Url = encodeBase64Url;
-exports.decodeBase64Url = decodeBase64Url;
-const neverthrow_1 = require("neverthrow");
-function encodeBase64Url(bytes) {
-    return Buffer.from(bytes).toString('base64url');
-}
-function decodeBase64Url(input) {
-    try {
-        return (0, neverthrow_1.ok)(new Uint8Array(Buffer.from(input, 'base64url')));
-    }
-    catch {
-        return (0, neverthrow_1.err)({ code: 'BASE64URL_INVALID', message: 'Invalid base64url string' });
-    }
-}