troupe-standup/wizard-work/forge/PROBE_FORGE_REFACTOR_VERIFICATION.md

PROBE_FORGE_REFACTOR_VERIFICATION.md -- forge refactor verification.

Target: /root/troupe-standup/wizard-work/forge/_probe_forge.py -> /root/troupe-standup/wizard-work/forge/_probe_forge_refactored.py Lane: Refactor (code review + refactors) Date: 2026-10-25 (refactor); verifier hardened 2026-10-26

PURPOSE The forge lane refactored _probe_forge.py -- a round-trip probe of the forge chunker -- into _probe_forge_refactored.py. The refactor is behavior-preserving: it exercises the same chunker API (chunk_text / reconstruct) with the same inputs, emitting byte-identical output.

SMELLS REMOVED (from the original _probe_forge.py)

1. Import-time side effect: the original ran its entire probe at module top-level (a module-level for loop printing immediately on import). There was no if __name__ == "__main__" guard, so importing the module executed and printed the probe output. The refactored version moves all execution under main() with an explicit __main__ guard.

2. Dead variable shorter: computed as shorter = min(len(r), len(text_stripped)) inside the for-else else branch but never read -- every subsequent statement used len(r) and len(text_stripped) directly. Removed; output unchanged.

3. Inlined first-diff search: the inline for i in range(min(...)) loop with its for-else side-effects is extracted into _find_first_diff(actual, expected) -> int | None, a pure function returning the mismatch index or None, decoupling the search from I/O so the control flow reads as intent ("is there a diff, and if so, show it").

4. Inlined chunk-structure printing: the loop that prints the first 5 chunks with sentinels revealed is extracted into _print_chunk_structure(chunks, sentinel, n), isolating the formatting concern and moving the data (base, text, cs, r) inside main() instead of at module scope.

VERIFIER HARDENING (the fix, applied after the refactor commit) The verifier's import was done through an unguarded importlib.import_module call. A guard-less subject that calls sys.exit at module scope raises SystemExit(0) during import, which propagated and killed the verifier process with rc 0 BEFORE reaching its final assert passed == total, sys.exit(1). Net effect on a defective tree: output leaked to real stdout and the harness reported green (rc 0). This is exactly the no_main_guard mutant it is meant to catch.

Fix: replaced _import_refactored() with _safe_import(), which wraps the import in try/except BaseException (so SystemExit is caught), captures stdout/stderr via redirect, and returns (module, exc, out, err). Both call sites (check_import_side_effect_free and check_find_first_diff_correctness) use it, so a guard-less subject now FAILS loudly instead of escaping. With the real subject carrying a proper __main__ guard, the import is clean and every check proceeds normally.

SAFETY: byte-identical output The refactor does NOT change behavior. The chunker calls are identical (chunker.chunk_text(text, max_tokens=64, overlap_tokens=8) and chunker.reconstruct(cs, 8)), the base string is identical (adjacent string literals concatenate to the same value), and _find_first_diff preserves the original for-else semantics: returns the index of the first mismatch, or None when the common prefix matches (triggering the "no char diff" branch).

VERIFICATION (all executed, real exit codes)

1. python3 /root/troupe-standup/wizard-work/forge/verify_probe_forge_refactor.py -> 12/12 checks passed, exit 0
2. python3 _probe_forge.py (orig stdout: 790 bytes)
3. python3 _probe_forge_refactored.py (ref stdout: 790 bytes)
4. diff -> IDENTICAL (no output); the verifier's check_identical_output confirms orig.stdout == ref.stdout, orig.stderr == ref.stderr, and orig.returncode == ref.returncode (0 == 0).
5. Round-trip assertion: probe output reports "equal: True", nchunks: 12.
6. pytest test_chunker_refactor.py -q -> 13 passed (chunker unchanged).

VERIFIER CHECKS (verify_probe_forge_refactor.py, 12/12) [OK] py_compile passes [OK] identical output (exit 0, 790 bytes) [OK] main guard present [OK] no 'global' statements in code [OK] dead 'shorter' variable removed [OK] _find_first_diff, _print_chunk_structure, main extracted; main calls helpers + chunker API [OK] import is side-effect-free (no probe output at import) [OK] round-trip lossless (equal: True in probe output) [OK] original still exhibits the removed smells (refactor non-vacuous) [OK] _find_first_diff correct on all 10 cases (mutation kill) [OK] 'equal' is computed dynamically from actual == expected (no hardcode) [OK] overlap values consistent (chunk_text=8, reconstruct=8)

NON-VACUITY GUARD The verifier's check 9 confirms the original _probe_forge.py still exhibits every removed smell: no __main__ guard, dead shorter = min(...) variable present, and a module-level for loop. The refactor is therefore non-vacuous -- it addresses real, reproduced defects, not hypotheticals.

VERDICT: probe_forge refactor verified -- behavior-preserving (byte-identical, equal: True, 12 chunks), 4 smells removed, and the verifier itself hardened against the SystemExit/no_main_guard mutant-escape that previously let a defective tree report rc 0. Final harness: 12/12 checks, exit 0.