@exaudeus/workrail 3.13.0 → 3.15.0

package/workflows/relocation-workflow-us.json

@@ -1,8 +1,8 @@
 {
   "id": "relocation-workflow-us",
-  "name": "US Relocation Decision Workflow (Evidence-Driven • AreaSpec • Ranked Dossier)",
+  "name": "US Relocation Decision Workflow (Evidence-Driven \u2022 AreaSpec \u2022 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.",
+  "description": "Use this to evaluate US cities or regions for a potential relocation. Discovers your preferences, generates candidate areas, screens them, and produces a ranked dossier with evidence.",
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"
@@ -20,14 +20,14 @@
   ],
   "metaGuidance": [
     "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.",
+    "V2 DURABILITY: use output.notesMarkdown and explicit context variables as the durable record. RELOCATION_DOSSIER.md and profile docs are human-facing artifacts \u2014 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.",
+    "SCREENING CAPS: first-pass screening must stay fast \u2014 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": [
@@ -37,18 +37,18 @@
       "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.",
+          "Do not start researching candidates yet \u2014 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).",
+          "Step 1 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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": [
@@ -67,17 +67,17 @@
       "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.",
+          "Every policy must be explicit \u2014 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).",
+          "Step 1 \u2014 Missing data policy. Ask the user to choose one: (a) neutral \u2014 Unknown scores 0.5; (b) penalize \u2014 Unknown scores 0.25; (c) followup_required \u2014 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 \u2014 Intake completeness check. Confirm you have enough context to set dealbreakers and weights. If not, note missingInputs and resolve before proceeding.",
+          "Step 3 \u2014 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 \u2014 Shortlist range. Propose defaults and ask the user to confirm or adjust: shortlistMin (default 8), shortlistMax (default 12).",
+          "Step 5 \u2014 Screening caps. Propose defaults and ask the user to confirm or adjust: screeningTopCriteriaCount (default 3 \u2014 screen dealbreakers + top N weighted criteria only), screeningMaxClaimsPerCandidate (default 3), screeningTimeboxMinutesPerCandidate (default 5), screeningBatchSize (default 10).",
+          "Step 6 \u2014 Discovery caps. Propose defaults and ask the user to confirm or adjust: perSourceCandidateCap (default 8 \u2014 cap per curated-list source to avoid editorial bias).",
+          "Step 7 \u2014 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": [
@@ -99,10 +99,10 @@
           "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.",
+          "Step 1 \u2014 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 \u2014 generate the pool from actual data, not from memory alone.",
+          "Step 2 \u2014 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 \u2014 include a mix of obvious and non-obvious candidates. Include at least minCandidatePool candidates total.",
+          "Step 3 \u2014 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 \u2014 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": [
@@ -136,7 +136,7 @@
     {
       "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).",
+      "prompt": "Run a lightweight baseline pass on all Pass or Maybe candidates from screenResults.\n\nScope \u2014 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 \u2014 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
     },
     {
@@ -145,17 +145,26 @@
       "promptFragments": [
         {
           "id": "no-red-flags",
-          "when": { "var": "redFlagCount", "equals": 0 },
+          "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."
         },
         {
           "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)."
+          "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 \u2014 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 \u2014 ask the user how to weight it and which existing weights decrease so the `weights` array still sums to 100; (c) fyi \u2014 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 }
+      "requireConfirmation": {
+        "var": "redFlagCount",
+        "gt": 0
+      }
     },
     {
       "id": "phase-5-shortlist",
@@ -207,16 +216,16 @@
         "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.",
+          "Unknowns must be disclosed in the ranking narrative \u2014 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.",
+          "Step 1 \u2014 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 \u2014 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 \u2192 0.5; penalize policy \u2192 0.25; followup_required policy \u2192 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 \u2014 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 \u2014 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 \u2014 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": [

package/workflows/routines/tension-driven-design.json

@@ -41,7 +41,7 @@
     {
       "id": "step-generate-candidates",
       "title": "Step 3: Generate Candidates from Tensions",
-      "prompt": "Generate design candidates that resolve the identified tensions differently.\n\nMANDATORY candidates:\n1. The simplest possible change that satisfies acceptance criteria. If the problem doesn't need an architectural solution, say so.\n2. Follow the existing repo pattern — adapt what the codebase already does for similar problems. Don't invent when you can adapt.\n\nAdditional candidates (1-2 more):\n- Each must resolve the identified tensions DIFFERENTLY, not just vary surface details\n- Each must be grounded in a real constraint or tradeoff, not an abstract perspective label\n- Consider philosophy conflicts: if the stated philosophy disagrees with repo patterns, one candidate could follow the stated philosophy and another could follow the established pattern\n\nFor each candidate, produce:\n- One-sentence summary of the approach\n- Which tensions it resolves and which it accepts\n- Boundary solved at, and why that boundary is the best fit\n- The specific failure mode you'd watch for\n- How it relates to existing repo patterns (follows / adapts / departs)\n- What you gain and what you give up\n- Impact surface beyond the immediate task\n- Scope judgment: too narrow / best-fit / too broad, with concrete evidence\n- Which philosophy principles it honors and which it conflicts with (by name)\n\nRules:\n- candidates must be genuinely different in shape, not just wording\n- if all candidates converge on the same approach, that's signal — note it honestly rather than manufacturing fake diversity\n- broader scope requires concrete evidence\n- cite specific files or patterns when they materially shape a candidate",
+      "prompt": "Generate design candidates that resolve the identified tensions differently.\n\nMANDATORY candidates:\n1. The simplest possible change that satisfies acceptance criteria. If the problem doesn't need an architectural solution, say so.\n2. Follow the existing repo pattern — adapt what the codebase already does for similar problems. Don't invent when you can adapt.\n\nAdditional candidates (1-2 more):\n- Each must resolve the identified tensions DIFFERENTLY, not just vary surface details\n- Each must be grounded in a real constraint or tradeoff, not an abstract perspective label\n- Consider philosophy conflicts: if the stated philosophy disagrees with repo patterns, one candidate could follow the stated philosophy and another could follow the established pattern\n\nFor each candidate, produce:\n- One-sentence summary of the approach\n- Which tensions it resolves and which it accepts\n- Boundary solved at, and why that boundary is the best fit\n- The specific failure mode you'd watch for\n- How it relates to existing repo patterns (follows / adapts / departs)\n- What you gain and what you give up\n- Impact surface beyond the immediate task\n- Scope judgment: too narrow / best-fit / too broad, with concrete evidence\n- Which philosophy principles it honors and which it conflicts with (by name)\n\nRules:\n- candidates must be genuinely different in shape, not just wording\n- if all candidates converge on the same approach, that's signal — note it honestly rather than manufacturing fake diversity\n- broader scope requires concrete evidence\n- cite specific files or patterns when they materially shape a candidate\n- specify each candidate at the level of concrete shape, not concept labels: 'tags' is not a candidate specification; 'per-workflow multi-labels drawn from a closed 9-value enum' is. If you find yourself using a concept label (tags, categories, events, hooks), you have not yet specified the candidate — name the data structure, the vocabulary or value set it uses, who maintains it, and how it is queried",
       "agentRole": "You are generating genuinely diverse design candidates grounded in real tensions.",
       "requireConfirmation": false
     },

package/workflows/scoped-documentation-workflow.json

@@ -2,7 +2,7 @@
   "id": "scoped-documentation-workflow",
   "name": "Scoped Documentation Workflow",
   "version": "2.0.0",
-  "description": "Create documentation for a SINGLE, BOUNDED subject with strict scope enforcement. Perfect for: one class/component, one integration point, one mechanism, one architecture decision. Prevents documentation sprawl through continuous boundary validation.",
+  "description": "Use this to create documentation for a single, bounded subject \u2014 one class, one integration point, one mechanism, or one architecture decision. Enforces strict scope discipline to prevent documentation sprawl.",
   "clarificationPrompts": [
     "What specifically do you want to document? (feature, component, library, mechanism, interaction, architecture, process, etc.)",
     "Who will read this documentation? (team members, external users, new developers, architects, etc.)",
@@ -16,18 +16,18 @@
     "Agent can read files, analyze code, and write documentation"
   ],
   "metaGuidance": [
-    "SCOPE IS LAW: Define a boundary and defend it. REFERENCE out-of-scope items (one sentence + link). Never EXPLAIN them. One violation leads to more — protect the boundary.",
-    "REFERENCE vs EXPLAIN: Good — 'This uses CacheManager (see Cache Docs) to store results.' Bad — 'CacheManager works by maintaining an LRU cache that...' Never explain out-of-scope internals.",
-    "TEMPTATION LOGGING: Every time you almost explain an out-of-scope item, log it: 'Almost explained [X] but stopped — out of scope.' Zero logs on a complex subject is a red flag.",
-    "NOTES-FIRST DURABILITY: use output.notesMarkdown as the primary durable record. ANALYSIS.md, OUTLINE.md, SCOPE_CONTRACT.md are optional human-facing artifacts — not required workflow memory.",
-    "RUBRIC OVER VIBES: Score concrete dimensions with evidence sentences. Derive your next action from the rubric result — not from a gut feeling about whether things seem okay.",
+    "SCOPE IS LAW: Define a boundary and defend it. REFERENCE out-of-scope items (one sentence + link). Never EXPLAIN them. One violation leads to more \u2014 protect the boundary.",
+    "REFERENCE vs EXPLAIN: Good \u2014 'This uses CacheManager (see Cache Docs) to store results.' Bad \u2014 'CacheManager works by maintaining an LRU cache that...' Never explain out-of-scope internals.",
+    "TEMPTATION LOGGING: Every time you almost explain an out-of-scope item, log it: 'Almost explained [X] but stopped \u2014 out of scope.' Zero logs on a complex subject is a red flag.",
+    "NOTES-FIRST DURABILITY: use output.notesMarkdown as the primary durable record. ANALYSIS.md, OUTLINE.md, SCOPE_CONTRACT.md are optional human-facing artifacts \u2014 not required workflow memory.",
+    "RUBRIC OVER VIBES: Score concrete dimensions with evidence sentences. Derive your next action from the rubric result \u2014 not from a gut feeling about whether things seem okay.",
     "DEFAULT BEHAVIOR: self-execute with tools. Only ask the user for approvals at explicit checkpoints or for external knowledge you genuinely cannot determine yourself."
   ],
   "steps": [
     {
       "id": "phase-0-reconnaissance-and-scope",
       "title": "Phase 0: Reconnaissance & Scope Definition",
-      "prompt": "I want to create focused documentation for: \"[user's request]\"\n\n**How I work:** I handle most decisions autonomously and stop only for critical choices like scope approval. You can adjust anytime: say 'check with me more often' to add phase checkpoints, or 'just finish it' to minimize stops.\n\n**Step 1 — Reconnaissance (2-3 minutes):**\n\nExplore the subject quickly to understand the landscape before proposing scope:\n\n- Locate the subject (files, system definitions, process docs)\n- Identify primary interfaces and entry points\n- Map immediate dependencies (one level deep)\n- Check for existing documentation to avoid duplication\n- Note related components and assess complexity (simple/moderate/complex)\n\nReconnaissance findings:\n- **Primary Subject:** [what was requested]\n- **Type:** [code/system/concept/process/interaction]\n- **Located at:** [file paths, system names, or description]\n- **Related Components:** [list with brief descriptions]\n- **Dependencies:** [key dependencies identified]\n- **Existing Docs:** [found/not found]\n- **Complexity:** [Simple/Moderate/Complex]\n\n**Step 2 — Scope Proposal:**\n\nBased on reconnaissance, propose a scope contract:\n\n**Subject:** [One clear sentence describing what you're documenting]\n\n**IN SCOPE** (will be explained in detail):\n- [Specific component/feature/mechanism and its core behaviors]\n- [Common use cases and usage patterns]\n- [Integration points and interfaces]\n- [Important edge cases and design decisions]\n\n**OUT OF SCOPE** (will be referenced only, not explained):\n- [Dependency X] internals — referenced as prerequisite\n- [Related feature Y] — link to separate docs\n- [Historical context] — unless specifically needed\n\n**BOUNDARY CONDITIONS** (where in-scope meets out-of-scope):\n- [Interface with System A]: document our side, reference their docs\n- [Integration with Component B]: document the contract, not their internals\n\n**Target Audience:** [who will read this]\n**Success Criteria:** Reader can [specific outcome]\n**Estimated Length:** ~[N] words\n\n**Does this scope look right?** Reply with approval or adjustments. If no response, I'll interpret as approval and proceed.\n\nAfter approval: I'll proceed with autonomous analysis, checking back only for critical questions or validation issues.",
+      "prompt": "I want to create focused documentation for: \"[user's request]\"\n\n**How I work:** I handle most decisions autonomously and stop only for critical choices like scope approval. You can adjust anytime: say 'check with me more often' to add phase checkpoints, or 'just finish it' to minimize stops.\n\n**Step 1 \u2014 Reconnaissance (2-3 minutes):**\n\nExplore the subject quickly to understand the landscape before proposing scope:\n\n- Locate the subject (files, system definitions, process docs)\n- Identify primary interfaces and entry points\n- Map immediate dependencies (one level deep)\n- Check for existing documentation to avoid duplication\n- Note related components and assess complexity (simple/moderate/complex)\n\nReconnaissance findings:\n- **Primary Subject:** [what was requested]\n- **Type:** [code/system/concept/process/interaction]\n- **Located at:** [file paths, system names, or description]\n- **Related Components:** [list with brief descriptions]\n- **Dependencies:** [key dependencies identified]\n- **Existing Docs:** [found/not found]\n- **Complexity:** [Simple/Moderate/Complex]\n\n**Step 2 \u2014 Scope Proposal:**\n\nBased on reconnaissance, propose a scope contract:\n\n**Subject:** [One clear sentence describing what you're documenting]\n\n**IN SCOPE** (will be explained in detail):\n- [Specific component/feature/mechanism and its core behaviors]\n- [Common use cases and usage patterns]\n- [Integration points and interfaces]\n- [Important edge cases and design decisions]\n\n**OUT OF SCOPE** (will be referenced only, not explained):\n- [Dependency X] internals \u2014 referenced as prerequisite\n- [Related feature Y] \u2014 link to separate docs\n- [Historical context] \u2014 unless specifically needed\n\n**BOUNDARY CONDITIONS** (where in-scope meets out-of-scope):\n- [Interface with System A]: document our side, reference their docs\n- [Integration with Component B]: document the contract, not their internals\n\n**Target Audience:** [who will read this]\n**Success Criteria:** Reader can [specific outcome]\n**Estimated Length:** ~[N] words\n\n**Does this scope look right?** Reply with approval or adjustments. If no response, I'll interpret as approval and proceed.\n\nAfter approval: I'll proceed with autonomous analysis, checking back only for critical questions or validation issues.",
       "requireConfirmation": true,
       "validationCriteria": [
         {
@@ -54,14 +54,14 @@
       "promptBlocks": {
         "goal": "Analyze the subject thoroughly within the approved scope boundary and score evidence quality before proceeding.",
         "constraints": [
-          "Enforce scope during analysis: read and trace only in-scope files and behaviors. When you encounter an out-of-scope item, log it and move on — do not analyze it.",
+          "Enforce scope during analysis: read and trace only in-scope files and behaviors. When you encounter an out-of-scope item, log it and move on \u2014 do not analyze it.",
           "Notes-first: record analysis findings in notesMarkdown, not in ANALYSIS.md as a required artifact.",
-          "Derive the proceed/gather-more decision from the evidence rubric — not from a gut feeling."
+          "Derive the proceed/gather-more decision from the evidence rubric \u2014 not from a gut feeling."
         ],
         "procedure": [
           "Investigation approach: (1) Map interfaces and public API surface (in-scope only). (2) Trace key execution flows and behaviors. (3) Identify important mechanisms and patterns. (4) Extract 5+ representative examples from code or usage. (5) Document integration points at the interface/contract level only. (6) Note design decisions and tradeoffs.",
-          "Boundary enforcement (continuous) — when you encounter something outside scope: REFERENCE IT ('This integrates with [System X] via [interface]'), LINK TO DOCS ('For [System X] details, see [link]'), DO NOT EXPLAIN IT, DO NOT ANALYZE IT, LOG THE TEMPTATION ('Almost analyzed [X] but stopped — out of scope').",
-          "Evidence rubric — score all 4 dimensions before deciding to proceed. Score each dimension 0, 1, or 2 and write one evidence sentence for each.",
+          "Boundary enforcement (continuous) \u2014 when you encounter something outside scope: REFERENCE IT ('This integrates with [System X] via [interface]'), LINK TO DOCS ('For [System X] details, see [link]'), DO NOT EXPLAIN IT, DO NOT ANALYZE IT, LOG THE TEMPTATION ('Almost analyzed [X] but stopped \u2014 out of scope').",
+          "Evidence rubric \u2014 score all 4 dimensions before deciding to proceed. Score each dimension 0, 1, or 2 and write one evidence sentence for each.",
           "subjectBoundaryClarity: 0=boundary confirmed and clear, 1=likely correct but one area uncertain, 2=boundary still ambiguous",
           "behaviorCoverage: 0=all key behaviors identified with examples, 1=most behaviors covered with minor gaps, 2=significant behavior gaps remain",
           "examplesCollected: 0=5+ concrete examples extracted from subject, 1=2-4 examples found, 2=fewer than 2 verifiable examples",
@@ -70,7 +70,7 @@
           "If you find a critical scope issue (the subject is actually two distinct subjects, or a required dependency cannot be referenced without explaining it), surface this to the user before proceeding."
         ],
         "outputRequired": {
-          "analysisFindings": "Subject overview, core behaviors/components, integration points, examples (5+), design decisions — recorded in notesMarkdown",
+          "analysisFindings": "Subject overview, core behaviors/components, integration points, examples (5+), design decisions \u2014 recorded in notesMarkdown",
           "scopeBoundaryLog": "Every temptation stopped: what was encountered and why it was left out",
           "evidenceRubricScores": "All 4 dimensions scored with evidence sentences, plus gate decision (proceed or gather more with specifics)"
         },
@@ -90,18 +90,18 @@
         "goal": "Design the documentation structure and create a detailed outline that maps directly to the Phase 1 analysis findings.",
         "constraints": [
           "Every section must map to an in-scope item from Phase 1 analysis.",
-          "Out-of-scope items belong only in a 'Related Documentation' section — as references, never explanations.",
-          "Pull all content points from Phase 1 findings — do not invent new content that wasn't in the analysis.",
+          "Out-of-scope items belong only in a 'Related Documentation' section \u2014 as references, never explanations.",
+          "Pull all content points from Phase 1 findings \u2014 do not invent new content that wasn't in the analysis.",
           "Notes-first: record the outline in notesMarkdown, not only in OUTLINE.md."
         ],
         "procedure": [
-          "Step 1 — Choose structure type based on subject: Code subject: Overview → How It Works → Usage Guide → Reference → Edge Cases → Related Docs. System/concept: Overview → Components → Interactions → Integration → Examples → Related Docs. Process/workflow: Overview → Steps → Decision Points → Examples → Troubleshooting → Related Docs. Adjust sections based on what analysis actually found.",
-          "Step 2 — Create detailed outline. For each section, specify: content points sourced from Phase 1 analysis (with evidence references), examples to include (from Phase 1 examples), approximate word count target, whether this section documents in-scope items or references out-of-scope ones.",
-          "Step 3 — Scope compliance check on the outline. Review every section and confirm: Does it map to an in-scope item? Does it require explaining any out-of-scope dependency? Can the content be written entirely from Phase 1 findings?",
+          "Step 1 \u2014 Choose structure type based on subject: Code subject: Overview \u2192 How It Works \u2192 Usage Guide \u2192 Reference \u2192 Edge Cases \u2192 Related Docs. System/concept: Overview \u2192 Components \u2192 Interactions \u2192 Integration \u2192 Examples \u2192 Related Docs. Process/workflow: Overview \u2192 Steps \u2192 Decision Points \u2192 Examples \u2192 Troubleshooting \u2192 Related Docs. Adjust sections based on what analysis actually found.",
+          "Step 2 \u2014 Create detailed outline. For each section, specify: content points sourced from Phase 1 analysis (with evidence references), examples to include (from Phase 1 examples), approximate word count target, whether this section documents in-scope items or references out-of-scope ones.",
+          "Step 3 \u2014 Scope compliance check on the outline. Review every section and confirm: Does it map to an in-scope item? Does it require explaining any out-of-scope dependency? Can the content be written entirely from Phase 1 findings?",
           "If any section requires explaining an out-of-scope item: convert it to a reference, remove it, or surface a scope re-negotiation to the user. If any section cannot be written from Phase 1 findings: flag what additional analysis is needed and return to Phase 1."
         ],
         "outputRequired": {
-          "documentationStructure": "Section titles, word count targets, and content-source mapping — recorded in notesMarkdown",
+          "documentationStructure": "Section titles, word count targets, and content-source mapping \u2014 recorded in notesMarkdown",
           "scopeComplianceConfirmation": "All sections confirmed to map to in-scope items",
           "totalEstimatedWordCount": "Total word count estimate",
           "analysisGaps": "Any gaps requiring return to Phase 1 (if none, state none)"
@@ -109,7 +109,7 @@
         "verify": [
           "Every section maps to an in-scope item from Phase 1 analysis",
           "Out-of-scope items only appear in 'Related Documentation' section",
-          "All examples sourced from Phase 1 — none invented",
+          "All examples sourced from Phase 1 \u2014 none invented",
           "Outline recorded in notesMarkdown"
         ]
       },
@@ -121,16 +121,16 @@
       "promptBlocks": {
         "goal": "Write the documentation section by section, enforcing scope boundaries continuously and logging all boundary decisions.",
         "constraints": [
-          "Content must come from Phase 1 analysis and Phase 2 outline — do not introduce new claims or examples that weren't in the analysis.",
+          "Content must come from Phase 1 analysis and Phase 2 outline \u2014 do not introduce new claims or examples that weren't in the analysis.",
           "After every paragraph: check scope compliance. Am I explaining something in scope or referencing something out of scope?",
           "Mark boundaries clearly in the text so readers know what's in vs out.",
           "Notes-first: the documentation file is the primary artifact; ANALYSIS.md or OUTLINE.md sidecar files are optional."
         ],
         "procedure": [
-          "Writing approach — section by section. For each section from the Phase 2 outline: (1) Draft content from outline and Phase 1 findings. (2) Add examples from analysis (complete, not fragments). (3) Check scope compliance inline. (4) Write boundary markers for out-of-scope references. (5) Log any temptation to explain an out-of-scope item.",
-          "Scope boundary wording — use these patterns. Good (reference only): 'This uses the CacheManager (see Cache Documentation) to store results.' Good: 'For authentication details, see Auth Service Documentation.' Bad (explaining out-of-scope): 'The CacheManager works by maintaining an in-memory LRU cache that...'",
-          "After writing all sections — final scope audit. Read through the complete draft and count: lines documenting in-scope items (vast majority), lines referencing out-of-scope items (minimal), lines explaining out-of-scope items (must be zero). Fix any violations before advancing to Phase 4.",
-          "If you discover a critical inaccuracy (a claim you cannot verify from analysis), flag it for user confirmation in Phase 4 — don't silently remove it.",
+          "Writing approach \u2014 section by section. For each section from the Phase 2 outline: (1) Draft content from outline and Phase 1 findings. (2) Add examples from analysis (complete, not fragments). (3) Check scope compliance inline. (4) Write boundary markers for out-of-scope references. (5) Log any temptation to explain an out-of-scope item.",
+          "Scope boundary wording \u2014 use these patterns. Good (reference only): 'This uses the CacheManager (see Cache Documentation) to store results.' Good: 'For authentication details, see Auth Service Documentation.' Bad (explaining out-of-scope): 'The CacheManager works by maintaining an in-memory LRU cache that...'",
+          "After writing all sections \u2014 final scope audit. Read through the complete draft and count: lines documenting in-scope items (vast majority), lines referencing out-of-scope items (minimal), lines explaining out-of-scope items (must be zero). Fix any violations before advancing to Phase 4.",
+          "If you discover a critical inaccuracy (a claim you cannot verify from analysis), flag it for user confirmation in Phase 4 \u2014 don't silently remove it.",
           "Write the documentation to a file. Suggested filename: [SUBJECT]_Documentation.md or similar. Record the path in mainDocumentationFile."
         ],
         "outputRequired": {
@@ -151,7 +151,7 @@
     {
       "id": "phase-4-validation-and-delivery",
       "title": "Phase 4: Adversarial Validation & Delivery",
-      "prompt": "Now be the harshest critic before delivering.\n\n**VALIDATION RUBRIC — score all 4 dimensions with evidence:**\n\n**1. Scope Compliance**\n- PASS: zero unexplained out-of-scope items in the documentation\n- PARTIAL: minor violations found and fixed autonomously\n- FAIL: violations found that cannot be fixed without user input\n- Evidence: [sentence + violation count]\n- Action: FAIL triggers user input; PARTIAL acceptable with disclosure\n\n**2. Completeness**\n- PASS: all in-scope items from the scope contract are documented\n- PARTIAL: minor gaps (non-critical items missing)\n- FAIL: significant in-scope items missing\n- Evidence: [sentence + gap count]\n- Action: FAIL triggers autonomous content addition then re-validate; PARTIAL acceptable with disclosure\n\n**3. Accuracy**\n- PASS: all technical claims verifiable from Phase 1 analysis\n- PARTIAL: minor uncertainties clearly marked in documentation\n- FAIL: key claims uncertain — external confirmation required\n- Evidence: [sentence + uncertain claim count]\n- Action: FAIL triggers user checkpoint with specific questions; PARTIAL acceptable with disclosure\n\n**4. Clarity**\n- PASS: target audience can achieve the success criteria using this documentation\n- PARTIAL: some sections need clearer wording\n- FAIL: significant clarity gaps preventing successful use\n- Evidence: [sentence]\n- Action: FAIL triggers autonomous rewrite then re-validate; PARTIAL acceptable with disclosure\n\n---\n\n**Gate rules:**\n- scopeCompliance and completeness must both reach PASS for delivery\n- accuracy FAIL triggers user checkpoint — list specific questions below\n- clarity FAIL triggers autonomous rewrite\n- accuracy PARTIAL and clarity PARTIAL proceed with disclosure\n\n**If all gates pass or are acceptable for delivery:**\n\nCreate SCOPE_MAP.md:\n```\n# Scope Map: [Subject]\n\n## Documented Here (In Scope)\n- [Item]: [brief description] — see [Section]\n\n## Referenced Only (Out of Scope)\n- [Item]: [brief description] — [link if available]\n\n## Integration Points\n- [Where this connects to other systems / interface contracts]\n\n## Related Documentation\n- [Links with descriptions]\n```\n\nOptionally create MAINTENANCE_NOTES.md with: when to update this documentation, which sections to review for accuracy, scope boundary reminders (what stays referenced-only).\n\n**DELIVERY SUMMARY:**\n\n- Main documentation: [path] (~[N] words)\n- Scope map: SCOPE_MAP.md\n- Validation results: scopeCompliance=[X], completeness=[X], accuracy=[X], clarity=[X]\n- Scope discipline: [N] temptations stopped, 0 violations in final delivery\n- Audience: [target audience]\n- Success criteria: Reader can [outcome]\n\n---\n\n**IF accuracy FAIL — user checkpoint required:**\n\nBefore I can deliver, I need your input on accuracy:\n\n[List specific technical claims that need confirmation, with context for each]\n\nOnce you confirm, I'll finalize and deliver.",
+      "prompt": "Now be the harshest critic before delivering.\n\n**VALIDATION RUBRIC \u2014 score all 4 dimensions with evidence:**\n\n**1. Scope Compliance**\n- PASS: zero unexplained out-of-scope items in the documentation\n- PARTIAL: minor violations found and fixed autonomously\n- FAIL: violations found that cannot be fixed without user input\n- Evidence: [sentence + violation count]\n- Action: FAIL triggers user input; PARTIAL acceptable with disclosure\n\n**2. Completeness**\n- PASS: all in-scope items from the scope contract are documented\n- PARTIAL: minor gaps (non-critical items missing)\n- FAIL: significant in-scope items missing\n- Evidence: [sentence + gap count]\n- Action: FAIL triggers autonomous content addition then re-validate; PARTIAL acceptable with disclosure\n\n**3. Accuracy**\n- PASS: all technical claims verifiable from Phase 1 analysis\n- PARTIAL: minor uncertainties clearly marked in documentation\n- FAIL: key claims uncertain \u2014 external confirmation required\n- Evidence: [sentence + uncertain claim count]\n- Action: FAIL triggers user checkpoint with specific questions; PARTIAL acceptable with disclosure\n\n**4. Clarity**\n- PASS: target audience can achieve the success criteria using this documentation\n- PARTIAL: some sections need clearer wording\n- FAIL: significant clarity gaps preventing successful use\n- Evidence: [sentence]\n- Action: FAIL triggers autonomous rewrite then re-validate; PARTIAL acceptable with disclosure\n\n---\n\n**Gate rules:**\n- scopeCompliance and completeness must both reach PASS for delivery\n- accuracy FAIL triggers user checkpoint \u2014 list specific questions below\n- clarity FAIL triggers autonomous rewrite\n- accuracy PARTIAL and clarity PARTIAL proceed with disclosure\n\n**If all gates pass or are acceptable for delivery:**\n\nCreate SCOPE_MAP.md:\n```\n# Scope Map: [Subject]\n\n## Documented Here (In Scope)\n- [Item]: [brief description] \u2014 see [Section]\n\n## Referenced Only (Out of Scope)\n- [Item]: [brief description] \u2014 [link if available]\n\n## Integration Points\n- [Where this connects to other systems / interface contracts]\n\n## Related Documentation\n- [Links with descriptions]\n```\n\nOptionally create MAINTENANCE_NOTES.md with: when to update this documentation, which sections to review for accuracy, scope boundary reminders (what stays referenced-only).\n\n**DELIVERY SUMMARY:**\n\n- Main documentation: [path] (~[N] words)\n- Scope map: SCOPE_MAP.md\n- Validation results: scopeCompliance=[X], completeness=[X], accuracy=[X], clarity=[X]\n- Scope discipline: [N] temptations stopped, 0 violations in final delivery\n- Audience: [target audience]\n- Success criteria: Reader can [outcome]\n\n---\n\n**IF accuracy FAIL \u2014 user checkpoint required:**\n\nBefore I can deliver, I need your input on accuracy:\n\n[List specific technical claims that need confirmation, with context for each]\n\nOnce you confirm, I'll finalize and deliver.",
       "requireConfirmation": true,
       "validationCriteria": [
         {

package/workflows/test-artifact-loop-control.json

@@ -59,8 +59,7 @@
       "assessmentConsequences": [
         {
           "when": {
-            "dimensionId": "confidence",
-            "equalsLevel": "low"
+            "anyEqualsLevel": "low"
           },
           "effect": {
             "kind": "require_followup",