Preserve tested Verify source, authoritative READY checks, bounded bridge retries, diagnostics and failure-only reporting. Include 336-test suite and packaging assets; exclude live Mentor samples, field logs, backups and distributions.
11 KiB
CBB Bridge Execution and UNC Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Replace fragile popup/title/timestamp decisions with a confirmed dialog state machine, structured PCB COM execution bridge, authoritative post-Verify status check, and bounded UNC path handling.
Architecture: A pure Python dialog state machine decides and confirms popup transitions while a Win32 adapter performs scoped window actions. A separate PCB bridge process owns Expedition COM and emits JSONL events; the parent owns the only inactivity deadline. LibraryPathLease maps UNC shares temporarily and supplies a stable Mentor path without recursively fingerprinting the network tree.
Tech Stack: Python 3.12, pytest, pywin32, ctypes/WNet, 32-bit Mentor COM/VBScript licensing helper, PyInstaller.
Spec: docs/superpowers/specs/2026-09-20-bridge-execution-and-unc-design.md
Global Constraints
- Never inject mouse/keyboard input or switch the user's desktop.
- Never click an unknown dialog automatically.
- Never call private
VerifyReuseBlockorUnVerifyReuseBlockmutation exports. - A failed CBB is logged and skipped; it does not abort the batch.
- PASS requires a post-close
IsVerifiedReuseBlock == READYresponse. - Temporary network mappings never store credentials or remove user mappings.
Task 1: Confirmed Dialog State Machine
Files:
- Create:
src/cbb_refresh_verify/dialog_supervisor.py - Modify:
src/cbb_refresh_verify/mentor_adapter.py - Test:
tests/test_dialog_supervisor.py
Interfaces:
-
Produces:
DialogSnapshot,DialogDecision,DialogPollResult,DialogSupervisor.poll(). -
Consumes: Win32 observations supplied by an adapter; no Win32 calls in the pure state machine.
-
Step 1: Write failing tests for popup confirmation and safety
def test_click_is_not_resolved_until_dialog_disappears():
backend = FakeDialogs([license_dialog(), license_dialog(), []])
supervisor = DialogSupervisor(backend, retry_seconds=0, max_attempts=3)
assert supervisor.poll().action_sent
assert not supervisor.poll().resolved
assert supervisor.poll().resolved
def test_stuck_dialog_fails_after_bounded_retries():
backend = FakeDialogs([license_dialog()] * 4)
supervisor = DialogSupervisor(backend, retry_seconds=0, max_attempts=2)
supervisor.poll(); supervisor.poll()
assert supervisor.poll().error_code == "DIALOG_STUCK"
def test_unknown_dialog_is_recorded_but_not_clicked():
backend = FakeDialogs([[dialog(text="Unrecognized destructive prompt")]])
result = DialogSupervisor(backend).poll()
assert result.error_code == "UNKNOWN_DIALOG"
assert backend.actions == []
def test_save_error_is_fatal_even_with_ok_button():
result = DialogSupervisor(FakeDialogs([[save_error_dialog()]])).poll()
assert result.error_code == "SAVE_REUSABLE_BLOCK_FAILED"
- Step 2: Run the tests and verify RED
Run: python -m pytest -q tests/test_dialog_supervisor.py
Expected: collection/import failure because dialog_supervisor does not exist.
- Step 3: Implement the minimal state machine and Win32 adapter
Implement immutable snapshots with window/PID/control state, fatal classification before generic affirmative classification, pending-action tracking by (hwnd, signature), disappearance confirmation, finite retries, and structured error codes. Win32 enumeration callbacks append observations and explicitly return True; the adapter scopes enumeration to the private desktop and supplied process IDs.
- Step 4: Integrate compatibility wrapper and verify GREEN
Keep handle_known_dialogs() as a thin compatibility wrapper while run_verify() uses the persistent supervisor instance. Run the targeted test plus existing integration tests.
Run: python -m pytest -q tests/test_dialog_supervisor.py tests/test_integration.py
Expected: all pass.
Task 2: PCB COM Execution Bridge and Single Deadline
Files:
- Create:
src/cbb_refresh_verify/pcb_bridge.py - Modify:
src/cbb_refresh_verify/application.py - Modify:
src/cbb_refresh_verify/mentor_adapter.py - Modify:
src/cbb_refresh_verify/verify_runner.py - Test:
tests/test_pcb_bridge.py - Test:
tests/test_verify_runner.py
Interfaces:
-
Produces:
PcbBridge.run(job, emit, com_provider, save_runner)and hidden CLI--pcb-bridge <request.json>. -
Consumes: documented
MGCPCB.Application,IMGCPCBProjectIntegration, document save/close APIs, and existing 32-bit licensing helper. -
Step 1: Write failing bridge state-machine tests
def test_bridge_rejects_wrong_document_before_actions():
result = run_bridge(job(), com_provider=wrong_document_provider())
assert result["status"] == "FAIL"
assert result["error_code"] == "PCB_IDENTITY_MISMATCH"
assert no_integration_actions(result)
def test_bridge_runs_required_actions_and_requires_post_save_sync():
provider = staged_provider([required_states(), synchronized_states()])
result = run_bridge(job(), com_provider=provider, save_runner=successful_save)
assert result["status"] == "PASS"
assert provider.actions == ["ForwardAnnotate"]
def test_fatal_dialog_overrides_save_markers():
assert finalize_result(save_markers=SUCCESS_MARKERS,
fatal_dialog="SAVE_REUSABLE_BLOCK_FAILED")["status"] == "FAIL"
- Step 2: Run targeted tests and verify RED
Run: python -m pytest -q tests/test_pcb_bridge.py tests/test_verify_runner.py
Expected: missing bridge API and missing fatal-result precedence failures.
- Step 3: Move COM workflow behind the bridge protocol
Remove the exact Expedition title gate. The bridge polls COM directly, verifies document/project identity before action, emits only changed snapshots, performs one allowed Required action at a time, validates/saves/closes, and writes a structured outcome. The worker has no independent inactivity deadline.
- Step 4: Make the parent the sole deadline owner
run_verify() refreshes its deadline for new bridge events and confirmed dialog transitions. Repeated snapshots do not refresh. Timeout kills the Job Object and returns a safe per-item TIMEOUT.
- Step 5: Verify targeted tests GREEN
Run: python -m pytest -q tests/test_pcb_bridge.py tests/test_verify_runner.py tests/test_integration.py
Expected: all pass.
Task 3: Authoritative Post-Verify Decision
Files:
- Modify:
src/cbb_refresh_verify/status_bridge.py - Modify:
src/cbb_refresh_verify/verify_runner.py - Modify:
src/cbb_refresh_verify/ui/main_window.py - Test:
tests/test_status_bridge.py - Test:
tests/test_verify_runner.py - Test:
tests/test_ui.py
Interfaces:
-
Produces: correlated bridge responses containing request ID, block name, resolved LMC path, and source.
-
Consumes: existing
StatusBridgeClient/Serverand post-close CBB identity. -
Step 1: Write failing correlation and final-state tests
def test_bridge_rejects_mismatched_response_identity():
with pytest.raises(BridgeResponseError):
parse_bridge_response(response_for("OTHER"), expected_block="TARGET")
def test_save_success_with_pending_post_status_is_fail():
result = finalize_verify(execution_pass(), BridgeResult("PENDING", "IsVerifiedReuseBlock"))
assert result.status == "FAIL"
- Step 2: Verify RED, implement correlation and post-check, verify GREEN
Run RED then GREEN: python -m pytest -q tests/test_status_bridge.py tests/test_verify_runner.py tests/test_ui.py
The UI marks a row Ready only after the final bridge response is READY. A bridge error remains visible and selectable for a later retry; it is never promoted from Cert files.
Task 4: UNC Path Lease and Bounded Network Scan
Files:
- Create:
src/cbb_refresh_verify/network_path.py - Modify:
src/cbb_refresh_verify/batch_status.py - Modify:
src/cbb_refresh_verify/library_reader.py - Modify:
src/cbb_refresh_verify/ui/main_window.py - Test:
tests/test_network_path.py - Test:
tests/test_batch_status.py - Test:
tests/test_library_reader.py
Interfaces:
-
Produces:
LibraryPathLease.acquire(path),.mentor_path,.display_path,.close(). -
Consumes: injected WNet backend in tests and Windows WNet API in production.
-
Step 1: Write failing lease and no-recursion tests
def test_unc_uses_existing_mapping_without_releasing_it():
backend = FakeWNet(existing={"Y:": r"\\server\share"})
with LibraryPathLease.acquire(r"\\server\share\lib\mentor_lib.lmc", backend=backend) as lease:
assert lease.mentor_path == Path(r"Y:\lib\mentor_lib.lmc")
assert backend.cancelled == []
def test_created_mapping_is_released():
backend = FakeWNet()
lease = LibraryPathLease.acquire(r"\\server\share\lib\mentor_lib.lmc", backend=backend)
lease.close()
assert backend.cancelled == [lease.drive]
def test_fingerprint_does_not_walk_cbb_descendants(tmp_path, monkeypatch):
# A descendant scandir raises; the lightweight snapshot must still finish.
assert fingerprint_library(make_library(tmp_path)).sha256
- Step 2: Verify RED, implement lease and lightweight fingerprint, verify GREEN
Replace recursive _fingerprint_tree() with LMC metadata plus sorted top-level CBB names and top-level metadata. Pass the leased mentor_path consistently to listing, bridge status, preflight and Verify.
Run: python -m pytest -q tests/test_network_path.py tests/test_batch_status.py tests/test_library_reader.py tests/test_ui.py
Expected: all pass and no descendant traversal.
Task 5: Packaging, Regression, and Static Safety Verification
Files:
- Modify:
packaging/CbbRefreshVerify.spec - Modify:
README.md - Modify:
tools/status_bridge/README.md - Test:
tests/test_packaging.py - Test:
tests/test_packaging_status_bridge.py - Test:
tests/test_safety.py
Interfaces:
-
Consumes: all new modules and bridge entry points.
-
Produces: one updated
dist-optimized/CbbRefreshVerify-Backgroundand archive. -
Step 1: Add packaging and safety tests, verify RED
Assert the frozen app contains the status bridge, PCB bridge entry point, VBS helper and icon; assert production source has no fixed Expedition title gate and no callback whose return value is list.append().
- Step 2: Update packaging and documentation, verify GREEN
Run: python -m pytest -q
Expected: complete suite passes with zero failures.
- Step 3: Build and smoke-test without running Mentor Verify
Run: powershell -ExecutionPolicy Bypass -File packaging/Build-CbbRefreshVerify.ps1 -OutputDirectory dist-optimized
Run: dist-optimized/CbbRefreshVerify-Background/CbbRefreshVerify.exe --smoke-test
Expected: build exit 0, smoke exit 0, no Mentor/PCB process started.
- Step 4: Retain only the latest package and report limitations
Keep the latest application directory, archive, and user-supplied diagnostic archives/logs. Do not delete user evidence. Report that real Mentor validation remains a one-CBB acceptance step on the work machine.