State Program Debugger - Claude Re-Review Packet

Date: 2026-07-10
Review: second pass after initial NO-GO

Review Objective

Perform an adversarial second review of the revised State Program Debugger contract. Return two separate verdicts:

1. DESIGN GO or DESIGN NO-GO: is the document specific and trustworthy enough to implement without inventing evidence, ownership, or stepping semantics?
2. IMPLEMENTATION GO or IMPLEMENTATION NO-GO: does the current prototype and hydrator conform to that contract?

The expected implementation verdict is allowed to remain NO-GO while work is pending. Do not turn a design approval into a production approval. Do not edit files during the review.

Files to Read

Read these in order:

1. docs/design/2026-07-10-state-program-debugger-evidence-design.md
2. docs/design/2026-07-10-state-program-debugger-implementation-plan.md
3. web/state-program-debugger-mockup.html
4. tests/web/test_state_program_debugger_mockup.py
5. docs/superpowers/specs/2026-07-09-state-audio-timeline-hydration.md
6. riff/postcall/state_audio_timeline.py
7. riff/state_manager.py, especially _SlotReadTracker, evaluate_guard, transition verdicts, slot writes, and transition commit
8. riff/state_trace_writer.py
9. riff/phone/telnyx_transport.py, especially initial-slot setup
10. flows/property_management.yaml, especially menu_announce, menu_full_announce, menu, and existing-request states

Initial Review Findings

The first review returned NO-GO with four blockers:

• R1: menu_full_announce absorbed caller and resolver evidence from the following menu visit.
• R2: the entry/current/exit table and legal-exit table lacked explicit hydration joins.
• R3: the access column claimed reads and ignored values without a named evidence source.
• R4: Step Into used an unspecified mix of recorded and synthesized micro-events.

The first review also recommended a real failing-call fixture, an always-visible conversation lane, identity-prefill verification, and semantic UI tests.

Claimed Contract Resolutions

Verify these claims rather than accepting them at face value.

R1 - Frame Ownership

The revised contract defines one frame per state visit, sequence and explicit identity attribution rules, an unattributed conflict lane, and a concrete property-menu boundary example. It states that Status and _route=existing_request belong to menu, not menu_full_announce.

Review questions:

• Do the rules handle re-entry and same-state loops?
• Are outgoing edge writes represented once while appearing in source Exit and target Entry?
• Can an event be silently assigned to the wrong visit?

R2 - Hydration

The revised contract maps:

• visit boundaries to lifecycle and transition events;
• variable snapshots to a new seeded baseline plus a fold of slot_write;
• legal exits to compiled transition metadata;
• guard outcomes to guard_evaluated and transition_verdict;
• the winner to the final verdict plus exit/commit agreement;
• audio, tools, and caller evidence to session and section-6 artifacts.

It also names the current identity gap: initial slots are applied with self._session_ctx.slots.update(initial_slots) after session_started, so a new instrumented session_slots_seeded baseline is required. It rejects slot_filled as a substitute and requires dictionary/direct-mutation coverage plus a fold-integrity gate.

Review questions:

• Is the baseline-plus-write fold deterministic for the initial and later visits?
• Are privacy/redaction and unavailable exact values represented honestly?
• Can duplicate-target edges be joined without ambiguity?
• Does the contract clearly separate existing telemetry from required new instrumentation?

R3 - Access Evidence

The initial review said no slot-read telemetry existed. Verify riff/state_manager.py: guard evaluation already emits guard_evaluated.slots_read via _SlotReadTracker. The revised contract uses that only for guard read (recorded), uses referenced (static) for declared flow/template references, marks other runtime reads unavailable, and removes the word ignored.

Review questions:

• Are the labels precise enough to prevent guard-read coverage from being mistaken for whole-state read coverage?
• Does any remaining access claim lack a source?

R4 - Canonical Events

The revised contract defines a stable event envelope, recorded/derived/simulated vocabularies, source references, deterministic ordering, nullable timestamps, and derived placement. It removes fabricated audio_progress as a Step Into event and defines audio progress as an independent WAV playhead.

Review questions:

• Can forward and reverse replay derive the same view every time?
• Are derived events clearly distinct from recorded facts?
• Are any event kinds still too vague to implement?

Programmatic AI Use

The revised contract says the UI, local CLI, and authenticated local API share one deterministic projection and simulation engine. It defines recorded navigation, isolated state simulation, a state-under-test capsule, pattern matrices, structured commands/results, determinism hashes, LLM/audio limits, side-effect controls, and independent immutable engine/flow execution targets. Recorded reproduction requires the recorded Python engine revision as well as the recorded flow; candidate regression names both candidate revisions. Missing historical code makes reproduction unavailable rather than silently selecting today's engine.

Review questions:

• Can an AI inspect and step a recorded state without executing production behavior?
• Can it fork any state, vary entry values or input fixtures, run the exact selected engine and flow revisions, and compare exits without touching external systems?
• Does a state capsule contain enough versioned evidence to avoid reading today's mutable flow by accident?
• Does recorded reproduction require historical Python/runtime identity rather than treating a pinned YAML flow as the whole program?
• Can the reviewer distinguish recorded reproduction, full candidate regression, and a controlled one-layer-at-a-time comparison?
• Can a failing pattern become a deterministic regression test?

Required State Program

incoming edge
-> entry boundary and immutable entry variables
-> state goal
-> ordered canonical micro-events
-> current variables at the cursor
-> all legal exits and guard verdicts
-> outgoing edge writes and clears
-> immutable recorded exit variables
-> transition commit
-> next state's entry boundary

Required Evidence Spine

Each visit has six summary beats, each with evidence status, provenance class, human explanation, and source references:

1. Intended
2. Generated
3. Sent
4. Heard
5. Caller said
6. Decided

Recorded, derived, simulated, redacted, disproven, and unavailable must remain distinguishable without relying only on color.

Design GO Criteria

Return DESIGN GO only if:

1. Visit boundaries and event ownership are deterministic, including re-entry.
2. Entry, cursor, and recorded exit values have explicit sources and cannot be confused.
3. Baseline or mutation gaps become incomplete evidence, never guessed values.
4. Every legal edge, duplicate targets, verdicts, winner, sets, and clears have stable joins.
5. Access labels do not overstate runtime read coverage.
6. Forward and reverse stepping use a canonical, stable event sequence.
7. Recorded, derived, unavailable, redacted, and simulated evidence are not confusable.
8. Caller-input provenance explains Gemini, Whisper, DTMF/control, and the acted-on source.
9. The artifact schema can hydrate the UI without changing the conceptual model.
10. The implementation sequence and acceptance gates are sufficient to detect the original four defects.
11. UI, CLI, and API clients share one deterministic engine, and an AI can run bounded state-pattern experiments without production side effects.
12. Every executing command pins independent immutable engine and flow revisions; unavailable historical code cannot fall back to current code.
13. The implementation packets are bounded and specific enough that a lower-capability model can execute WP0-WP6 without making architectural, privacy, or production-side-effect decisions.

Otherwise return DESIGN NO-GO with the minimum blocking changes.

Implementation GO Criteria

Return IMPLEMENTATION GO only if the current code, mock, and tests actually meet the design gates. Hardcoded representative values, browser-speech proof, the announce/menu frame leak, missing baseline telemetry, or substring-only tests are sufficient reasons for IMPLEMENTATION NO-GO.

Required Response Format

1. Preserve-worthy strengths.
2. Design blockers, ordered by severity.
3. Implementation conformance gaps, ordered by severity.
4. Review of each initial blocker R1-R4: resolved, partial, or unresolved.
5. Design scorecard against the thirteen GO criteria.
6. Final DESIGN GO|NO-GO and IMPLEMENTATION GO|NO-GO on separate lines.
7. Minimum next actions.

Suggested Command

cd ~/src/riff
claude --safe-mode -p --model fable --effort max \
  "Read docs/design/2026-07-10-state-program-debugger-claude-review.md and perform the review exactly as requested. Do not edit files."