Add phrase-equivalence test for marker-comment / docstring sync (PR #641 R2-B2 follow-up)

[michael-wojcik]

Background

During PR #641 Round-2 blind review (R2-B2 finding), the architect-r2 reviewer flagged that comment text and the corresponding docstring on the same helper can drift apart silently. When a reviewer-cycle finding tightens one, the other can be missed.

Concrete example from #641 Cycle-2: remove_stale_kernel_block (now strip_orphan_kernel_block) had a # SUNSET BEFORE v4.x.y marker comment in session_init.py, while sibling docstrings in test_claude_md_manager.py carried the same v4.x.y placeholder. Cycle-3 R2-M2 fixed the marker comment to v5.0.0 but missed the sibling docstrings — caught only at Cycle-4 R3-Arch-M1.

Proposal

Add a phrase-equivalence test that asserts a chosen list of helpers' marker-comment phrases stay in sync with their docstring phrases. Mechanism options:

Option A — single-source-of-truth constant

# pact-plugin/hooks/sentinels.py (new)
ORPHAN_KERNEL_BLOCK_SUNSET = "v5.0.0"

# session_init.py:
# SUNSET BEFORE {ORPHAN_KERNEL_BLOCK_SUNSET}: ...

# test_claude_md_manager.py docstring:
"""...SUNSET-BEFORE-{ORPHAN_KERNEL_BLOCK_SUNSET}..."""

Test asserts the phrase appears in both files at the expected location.

Option B — phrase-set test

# tests/test_phrase_equivalence.py
PHRASE_PAIRS = [
    {
        "name": "strip_orphan_kernel_block sunset version",
        "phrase": "v5.0.0",
        "sites": [
            ("pact-plugin/hooks/session_init.py", "SUNSET BEFORE"),
            ("pact-plugin/tests/test_claude_md_manager.py", "SUNSET-BEFORE-"),
        ],
    },
    # Add more as helpers acquire sibling docs
]

def test_phrase_equivalence():
    for pair in PHRASE_PAIRS:
        for path, prefix in pair["sites"]:
            content = Path(path).read_text()
            assert f"{prefix}{pair['phrase']}" in content, \
                f"phrase {pair['phrase']!r} missing from {path}"

Option B is lower-coupling; Option A is more rigorous (constant-driven) but requires retrofitting existing docs.

Acceptance criteria

• Test exists asserting marker-comment / docstring phrase synchronization for at least the strip_orphan_kernel_block helper.
• Test fails if either site drifts (one phrase changes, the other does not).
• Documentation note in pinned project rule about how to add new helpers to the phrase-set when applicable.

Why this matters

Surfaced as a real defect in #641 Cycle-2 → Cycle-3 → Cycle-4 progression. Each cycle caught one site of phrase drift; without the test, the fourth cycle's fresh-eye verify-only was the only catch mechanism. Codifying as a test moves the catch from review-eye-attention to CI.

Cross-references

• PR Restore session-startup ritual (#628) #641 (Restore session_init inline directives + peer_inject hook (5 functions) deleted in C4/C7 of #621 #628 implementation)
• R2-M2 fix (Cycle-3): set explicit v5.0.0 in marker comment
• R3-Arch-M1 fix (Cycle-4): swept sibling docstrings in baeb2d8