v6 Rule Location Map — Phase 2a Lockstep Companion (#836)¶

Status: DRAFT — blocks Phase 2a per docs/specs/conversation-v6-feature.md §4 + §8.5. Companion to: docs/specs/conversation-v6-feature.md (parent spec). Reviewer: Dr. Shrikanth Naidu (clinical-safety wording gate — Phase 2a). CI consumers: tests/test_lockstep_consistency.py (NEW), tests/test_v5_rule_verbatim_preservation.py (NEW).

0. Purpose¶

The v6 restructure breaks conversation_v4.yaml (a monolithic ~260-line prompt) and the six phase_contexts/v2/*.yaml files into a new layout (base/conversation_v6.yaml + stages.yaml + knowledge/*.yaml). Every rule that survives the move must land somewhere — or be explicitly declared "intentionally removed" with a citation to the v6 spec. This document is the exhaustive line-level map the CI lockstep gate reads.

If a rule disappears between v5 (current production = v4 + phase_contexts/v2) and v6 without being declared here, CI fails.

This doc is read by: 1. tests/test_lockstep_consistency.py — walks every row, asserts the rule text exists at the declared v6 destination. 2. tests/test_v5_rule_verbatim_preservation.py — asserts every verbatim: Y phrase appears unchanged in conversation_v6.yaml. 3. Dr. Naidu — reviews the "Open clinical questions" section before Phase 2a merges.

1. Conventions¶

Rule ID format¶

v4.<SECTION>.<NNN> for rules sourced from config/prompts/base/conversation_v4.yaml. v4mso.<NNN> for rules sourced from the mso_offer_addendum: block at the bottom of conversation_v4.yaml. phase.<phase_name>.<NNN> for rules sourced from config/prompts/phase_contexts/v2/<phase_name>.yaml.

Where <SECTION> is one of: - ROLE — Role + collect-before-matching framing - VOICE — Voice & emotional intelligence block - NAME — Using the patient's name - NEVER — Forbidden patterns + forbidden phrases marker - CONT — Conversational continuity - EMO — Emotional context handling - PROJ — Never project emotions - NONSENSE — Nonsensical/test input handling - ABROAD — Never assume "abroad" - FIRST — First-message shape - APPROACH — Approach + batching - THINK — Before-responding silent reasoning - FORMAT — Formatting (markdown discipline) - SAFETY — Safety (strict) - FACTS — Process facts (evaluation/matching/post-select/privacy/cost/timeline/fallback) - EXAMPLES — Few-shot examples - JSON — JSON output schema + forced prefill - REMEMBER — Final remember block

<NNN> is a zero-padded sequential index inside that section, starting from 001. IDs are STABLE — once allocated, never re-numbered. New rules added in Phase 2a or later get the next-available ID in their section; intentionally removed rules keep their ID with v6_destination_file:line_range = "REMOVED".

v6 section anchor format¶

The v6_section_anchor column is a stable string of the form # ANCHOR-<NAME> that the CI gate greps for inside conversation_v6.yaml or stages.yaml. Implementers MUST include these anchors as YAML comments in the destination file — they are the lockstep gate's primary lookup mechanism.

Verbatim vs semantic¶

• verbatim: Y — the exact wording (case-insensitive, whitespace-normalized) must appear in the v6 destination. Used for clinically-safety-critical phrases that cannot be paraphrased.
• verbatim: N — only the semantic intent must be preserved. Implementers may modernize phrasing during the v6 port. The lockstep gate checks for anchor presence + minimum content overlap; it does not enforce exact wording.

v6 destination shorthand¶

• conversation_v6.yaml:N-M — line range inside the new base prompt.
• stages.yaml:<stage>.<key>[<idx>] — pointer into a stage profile (e.g., stages.yaml:intake.guidance or stages.yaml:records_collection.do_not[0]). Note: per the v6 spec the equivalent of the v2 phase intake.yaml lands across two stages (procedure_identification for first-contact and records_collection/follow-ups). The destination column resolves this per-rule.
• knowledge/<file>.yaml:<key> — pointer into a knowledge addendum.
• REMOVED — rule is intentionally dropped (see §4).

2. Rule extraction — full table¶

Rows are grouped by source section for readability; the lockstep gate reads the whole table.

2.1 conversation_v4.yaml ROLE block (lines 22-32)¶

2.2 conversation_v4.yaml VOICE block (lines 34-41)¶

2.3 conversation_v4.yaml NAME block (lines 43-49)¶

2.4 conversation_v4.yaml NEVER + FORBIDDEN block (lines 51-54)¶

2.5 conversation_v4.yaml CONT block (lines 56-60)¶

2.6 conversation_v4.yaml EMO block (lines 62-68)¶

2.7 conversation_v4.yaml PROJ block (line 72)¶

2.8 conversation_v4.yaml NONSENSE block (line 74)¶

2.9 conversation_v4.yaml ABROAD block (line 76)¶

2.10 conversation_v4.yaml FIRST block (lines 78-85)¶

2.11 conversation_v4.yaml APPROACH block (line 87)¶

2.12 conversation_v4.yaml THINK block (lines 89-93)¶

2.13 conversation_v4.yaml FORMAT block (lines 95-103)¶

2.14 conversation_v4.yaml SAFETY block (lines 105-112) — CLINICAL-SAFETY-CRITICAL¶

2.15 conversation_v4.yaml FACTS block (lines 114-152)¶

2.16 conversation_v4.yaml placeholders + EXAMPLES (lines 154-183)¶

2.17 conversation_v4.yaml JSON block (lines 185-188)¶

2.18 conversation_v4.yaml REMEMBER block (lines 190-194)¶

2.19 conversation_v4.yaml MSO offer addendum (lines 206-260)¶

2.20 phase_contexts/v2/intake.yaml (lines 6-26)¶

2.21 phase_contexts/v2/records_first.yaml (lines 6-26)¶

2.22 phase_contexts/v2/identify_procedure.yaml (lines 6-30)¶

2.23 phase_contexts/v2/document_review.yaml (lines 6-26)¶

2.24 phase_contexts/v2/general.yaml (lines 6-13)¶

2.25 phase_contexts/v2/recovery_checkin.yaml (lines 6-119)¶

2.26 phase_contexts/v2/recovery_offer.yaml (lines 6-119)¶

2.27 v5 rule absorption rows (from v5 spec §2 — already enumerated in v6 spec §4)¶

These rules were introduced in v5 (which never shipped as a standalone file — its rules are being absorbed directly into v6). They are tracked here so the lockstep gate can confirm they landed and were not lost in the v5→v6 fold.

3. Verbatim phrase registry¶

The CI gate tests/test_v5_rule_verbatim_preservation.py greps for the following phrases in the assembled (post-loader) prompt string. Each MUST appear unchanged. Whitespace and case are normalized; punctuation is preserved.

3.1 Clinical-safety NEVER phrases (from v5 §2.1 and v4 SAFETY/HOTFIX)¶

1. different from what your doctor told you
2. this is not [diagnosis]
3. the diagnosis is wrong
4. I'm seeing findings that contradict
5. don't worry (must appear inside a NEVER context)
6. everything will be fine (must appear inside a NEVER context)
7. we don't handle that (must appear inside a NEVER context — from #837 scope-rejection ban)
8. this is outside our scope (must appear inside a NEVER context — from #837)
9. Curaway isn't set up for (must appear inside a NEVER context — from #837)
10. you should (must appear inside a NEVER context — from #837 treatment-recommendation ban)
11. the right next step is (must appear inside a NEVER context — from #837)
12. what you need is (must appear inside a NEVER context — from #837)

3.2 Clinical-safety ALWAYS / template phrases¶

1. I want to make sure these have been factored in
2. could you check with the oncologist whether
3. Surfacing factual findings IS allowed
4. The report I'm reading lists the patient as X — is this for someone other than yourself?
5. Your doctor is best positioned for that clinical decision.
6. Let me flag this with our care team so we can connect you with the right specialist.
7. Providers typically request
8. I have added these findings to your health record.
9. Microalbuminuria detected — providers will review kidney markers before surgery
10. HbA1c in the prediabetes range — important for surgical planning

3.3 Document-review WRONG/RIGHT example pairs (verbatim, both halves required)¶

1. WRONG: Microalbuminuria suggests early kidney changes
2. WRONG: Your glucose control is borderline
3. RIGHT: Microalbuminuria detected — providers will review kidney markers before surgery
4. RIGHT: HbA1c in the prediabetes range — important for surgical planning

3.4 Emotional verbatim words list (v5 Rule 2.7)¶

The following 7 words must appear as a literal list inside a v6 voice-rules section anchored by # V5-RULE-2.7-EMOTIONAL-VERBATIM:

1. exhausted
2. scared
3. desperate
4. overwhelmed
5. frustrated
6. worried
7. tired

3.5 Patronizing-filler ban list (from recovery_checkin.yaml + recovery_offer.yaml)¶

1. I hear you
2. I understand
3. I'm here for you
4. completely natural to feel

These must appear as a literal banned-phrase list in a v6 voice-rules section AND in stages.yaml:recovery_offer.do_not / stages.yaml:recovery_followup.do_not.

3.6 Extractor-coupled state machine literals (recovery_offer state)¶

These literals are extractor-coupled — the extractor switches on them. Verbatim required.

1. recovery_intent = "opted_in"
2. recovery_intent = "declined"
3. recovery_intent = "uncertain"
4. pain_level_high
5. Keyword list (exact tokens): bleeding, fever, swelling, emergency, infection, pus, dizzy, fainting, chest pain

3.7 #837 hot-fix paragraphs (asserted byte-identical by tests/test_hotfix_837_absorption.py)¶

1. v4.SAFETY.006 — treatment-recommendation ban paragraph (entire bullet from conversation_v4.yaml:111).
2. v4.SAFETY.007 — scope-rejection ban paragraph (entire bullet from conversation_v4.yaml:112).

Both must appear in conversation_v6.yaml HARD BANS section, byte-identical to conversation_v4.yaml. Lockstep target: v4 + v6_base.

4. Intentionally removed rules¶

The following v4/v5 rules are explicitly DROPPED in v6. The CI gate accepts these as legitimate gaps when it walks the rule table.

No clinical-safety rule is intentionally removed. Any such removal would require Dr. Naidu sign-off and a new row in this section with a citation.

5. CI gate algorithm — tests/test_lockstep_consistency.py¶

The Phase 2a CI gate reads this document and verifies every rule landed where it was promised. Pseudocode:

# tests/test_lockstep_consistency.py
#
# Reads docs/specs/v6-rule-location-map.md, parses each table row, asserts
# (a) the rule text exists at the declared v6 destination, anchored by the
# v6_section_anchor comment, and (b) verbatim rows survive normalized-text
# equality.

import hashlib
import re
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parent.parent
RULE_MAP = REPO_ROOT / "docs/specs/v6-rule-location-map.md"
V6_BASE = REPO_ROOT / "config/prompts/base/conversation_v6.yaml"
V6_STAGES = REPO_ROOT / "config/prompts/v6/stages.yaml"
V6_KNOWLEDGE_DIR = REPO_ROOT / "config/prompts/v6/knowledge"
V4_BASE = REPO_ROOT / "config/prompts/base/conversation_v4.yaml"


def normalize(text: str) -> str:
    """Lowercase, collapse whitespace, drop trailing punctuation."""
    text = text.lower()
    text = re.sub(r"\s+", " ", text).strip()
    return text


def semantic_hash(text: str) -> str:
    """v6 spec §8.5: lowercase → strip whitespace → drop punctuation → sort sentences → SHA-256."""
    text = text.lower()
    text = re.sub(r"[^\w\s.]", "", text)
    sentences = sorted(s.strip() for s in text.split(".") if s.strip())
    joined = " ".join(sentences)
    return hashlib.sha256(joined.encode()).hexdigest()


def parse_rule_table(md_path: Path) -> list[dict]:
    """Walk the markdown tables in §2, return a list of rule dicts."""
    # Implementation: regex over | rule_id | source | verbatim | dest | anchor | notes |
    # Skip header rows and section sub-headings.
    # ...


def load_v6_destination(dest: str) -> str:
    """Resolve a v6_destination_file:line_range pointer to a text blob."""
    # Supports:
    #   "conversation_v6.yaml" (full file)
    #   "stages.yaml:<stage>.<key>" (specific stage key)
    #   "stages.yaml:<stage>.<key>[<idx>]" (specific list element)
    #   "knowledge/<file>.yaml:<key>"
    #   "REMOVED" → returns sentinel that the row is in §4
    # ...


def test_every_rule_has_a_home():
    rules = parse_rule_table(RULE_MAP)
    removed_ids = parse_removed_section(RULE_MAP)  # §4

    for rule in rules:
        rid = rule["rule_id"]
        dest = rule["v6_destination"]
        anchor = rule["v6_section_anchor"]

        if dest == "REMOVED":
            assert rid in removed_ids, (
                f"{rid}: marked REMOVED in §2 but not declared in §4 "
                f"intentionally-removed section."
            )
            continue

        target_text = load_v6_destination(dest)

        # (a) the anchor comment must exist in the target file.
        assert anchor in target_text, (
            f"{rid}: v6 destination {dest} is missing required anchor "
            f"comment '{anchor}'. Add the anchor as a YAML comment so the "
            f"lockstep gate can locate this rule."
        )

        # (b) verbatim rows must produce the same normalized text as the source.
        if rule["verbatim"] == "Y":
            source_text = load_v4_or_phase_source(rule["source_file_line"])
            assert normalize(source_text) in normalize(target_text), (
                f"{rid}: verbatim rule did not survive the migration. "
                f"Source: {rule['source_file_line']}. Destination: {dest}. "
                f"Expected normalized text: {normalize(source_text)[:80]}..."
            )


def test_v4_v6_base_lockstep_pairs():
    """For every rule with lockstep_required: ['v4', 'v6_base'], compute
    semantic_hash on both targets; must match unless semantic_diff_allowed=true."""
    pairs = parse_lockstep_pairs(RULE_MAP)  # rows where both v4 and v6_base exist

    for pair in pairs:
        if pair.get("semantic_diff_allowed") is True:
            continue  # explicit waiver — skip hash check.

        v4_text = load_v4_destination(pair["v4_location"])
        v6_text = load_v6_destination(pair["v6_base_location"])

        h4 = semantic_hash(v4_text)
        h6 = semantic_hash(v6_text)

        assert h4 == h6, (
            f"{pair['rule_id']}: v4 and v6_base wording diverged "
            f"(hash mismatch). If divergence is intentional, set "
            f"semantic_diff_allowed: true in the rule row with a justification."
        )


def test_no_orphan_rules_in_destinations():
    """Reverse direction: walk the v6 files for any rule anchor that isn't
    referenced from this document. Catches rules that were added in Phase 2a+
    without registering here — those are scope-creep and must be added to
    this map."""
    declared_anchors = {r["v6_section_anchor"] for r in parse_rule_table(RULE_MAP)}
    found_anchors = grep_anchors_in_v6_tree(V6_BASE, V6_STAGES, V6_KNOWLEDGE_DIR)

    orphans = found_anchors - declared_anchors
    assert not orphans, (
        f"Found {len(orphans)} v6 anchors not declared in the rule map: "
        f"{sorted(orphans)[:5]}... Either register them in §2 or remove them."
    )


def test_intentionally_removed_have_citations():
    """Every row in §4 must include a citation column. The CI gate refuses
    to accept a 'removed' row without a justification."""
    for row in parse_removed_section(RULE_MAP):
        assert row["citation"], f"{row['rule_id']}: removed without citation."

Companion test — tests/test_v5_rule_verbatim_preservation.py consumes §3 directly:

# Reads §3 of v6-rule-location-map.md, walks each numbered phrase,
# greps the assembled (post-loader) prompt string for an exact match.

def test_verbatim_phrases_survive_loader_assembly():
    phrases = parse_verbatim_registry(RULE_MAP)  # numbered list from §3
    assembled = load_prompt_via_loader(prompt_key="conversation", version="v6")
    normalized_assembled = normalize(assembled)

    missing = []
    for phrase in phrases:
        if normalize(phrase) not in normalized_assembled:
            missing.append(phrase)

    assert not missing, (
        f"v5 verbatim-phrase preservation failed. Missing from v6 "
        f"post-loader output: {missing}. These are clinical-safety phrases "
        f"that v6 spec §4 declares MUST survive the migration."
    )

Determinism + speed: both tests are pure-file IO + regex; no LLM calls; run in <2 seconds. They run on every PR touching config/prompts/base/conversation_v6.yaml, config/prompts/v6/**, or this document.

Failure mode: a single missing rule fails the PR with an actionable message telling the implementer exactly where the rule should have landed.

6. Open questions for clinical review¶

These rows make material wording changes that Dr. Naidu must review during the Phase 2a window. Each is a candidate for an explicit verbatim: Y row if the clinical advisor wants to lock the wording, OR an explicit "intentionally removed" with citation if the rule is being dropped.

• OQ.01 — phase_complete → stage_complete rename. The token literal changes. Criteria (rule v4.JSON.003) are preserved. Question: does Dr. Naidu want the criteria wording strengthened during this rename (e.g., "meds confirmed" → "meds confirmed OR explicitly declined")?
• OQ.02 — document_review phase has no 1:1 stage in v6. The v6 spec lists 10 stages; document review folds into records_collection guidance. Question: is this the right home, or should we add a document_review sub-state under records_collection? The CI gate currently routes phase.document_review.* rows to stages.yaml:records_collection.guidance. Dr. Naidu sign-off needed before Phase 2a.
• OQ.03 — general.yaml maps onto support stage. The v6 spec describes support as a fallback "I don't know what stage" safety net. The current v2 general.yaml is an active "keep building the picture" guidance set. Question: is mapping general → support semantically correct, or should general's active-conversation guidance land in every stage's shared guidance preamble instead?
• OQ.04 — Medication→condition inference list (v4.APPROACH.002). "metformin=diabetes, lisinopril=hypertension, CPAP=sleep apnea" — these are clinical claims embedded in the prompt. Question: should this list move to knowledge/medication_lookup.yaml (out of base prompt) so Dr. Naidu can review the full inference table without re-reading the system prompt? Out of Phase 2a scope; flagged for Phase 5 (knowledge addendum design).
• OQ.05 — MSO mso_offer_addendum: → knowledge/mso_second_opinion.yaml move. Per v6 spec §10 open question 6, the existing mso_patient_offer_enabled flag + tenant resolution must carry forward. Question: does Dr. Naidu want any of the MSO voice-constraint phrasing (v4mso.005) strengthened during the move, or strict semantic preservation?
• OQ.06 — Recovery-checkin response shape uses 5-lines-max (phase.recovery_checkin.008) but recovery_offer.yaml also uses 5-lines-max (phase.recovery_offer.003). Both land in different v6 stages. Question: is "5 lines" the right cap for both, or should the recovery_followup stage have a different cap (e.g., 3 lines for terse milestone check-ins)?
• OQ.07 — Caregiver / helper consent gate (phase.intake.005). "Block progression until confirmed" is a hard cadence claim. Question: confirm the v6 stages.yaml location enforces this as a do_not: [advance_until_helper_consent] predicate, not just guidance prose.
• OQ.08 — Escalation keyword list (phase.recovery_checkin.016). "bleeding, fever, swelling, emergency, infection, pus, dizzy, fainting, chest pain" — extractor-coupled. Question: is this list complete, or should we add post-op-specific keywords (e.g., "shortness of breath", "calf pain", "vomiting blood") in Phase 2a? Adding keywords requires updating the extractor in lockstep.

7. Counts (auto-updated as rows are added)¶

• Total rule rows in §2: 199
• v4 ROLE: 5
• v4 VOICE: 7
• v4 NAME: 6
• v4 NEVER/FORBIDDEN: 3
• v4 CONT: 4
• v4 EMO: 7
• v4 PROJ: 3
• v4 NONSENSE: 2
• v4 ABROAD: 2
• v4 FIRST: 6
• v4 APPROACH: 2
• v4 THINK: 5
• v4 FORMAT: 8
• v4 SAFETY: 7
• v4 FACTS: 8
• v4 EXAMPLES/placeholders: 9
• v4 JSON: 3
• v4 REMEMBER: 5
• v4 MSO addendum: 7
• phase.intake: 14
• phase.records_first: 10
• phase.identify_procedure: 7
• phase.document_review: 14
• phase.general: 5
• phase.recovery_checkin: 23
• phase.recovery_offer: 20
• v5 absorption rows: 7
• Verbatim-required rows: 112 (rows marked verbatim: Y in §2 tables)
• Intentionally-removed rows (§4): 5
• Verbatim phrase registry entries (§3): 44
• Open clinical questions (§6): 8

If §2 grows or shrinks during Phase 2a review, the counts here MUST be updated in the same PR — tests/test_lockstep_consistency.py:test_counts_match_rows cross-checks.

8. Maintenance contract¶

• This file is append-only for rule rows. Removing a row requires either (a) moving the rule to §4 with citation, or (b) declaring the rule was renamed and updating the rule_id map in a stable-id ledger (none today — file an issue if needed).
• Anchor strings (# V5-RULE-2.1-DOC-TRUST-FRAMING etc.) are immutable — once a rule has an anchor, that anchor stays for the life of the rule. Renaming an anchor breaks the lockstep gate.
• During Phase 2a porting, implementers update only v6_destination_file:line_range when the actual destination line numbers settle. Anchor strings and rule IDs stay frozen.
• Dr. Naidu sign-off (per v6 spec §6 Phase 2a gate) is required on §3 verbatim registry + §6 open questions before this doc moves out of DRAFT.

End of v6 Rule Location Map.