@siuver/omp-debug-mode 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.3 - 2026-08-20
+
+- Aligned the injected methodology with Cursor Debug Mode: 3-5 hypotheses, instrument all of them, never fix without runtime logs, keep probes during the fix, and verify with a second reproduce. Round 1 is instrument-only.
+- The methodology now actually reaches the model: the context filter keeps the newest `debug-mode-context` instead of stripping the injection, and the start prompt names the absolute log file and forbids console-only probes such as Unity `Debug.Log`. Cleanup turns get a cleanup-specific contract.
+- The reproduction gate opens on the agent's `<reproduction_steps>` block. A clarifying question no longer strands you at the gate; an instrumented round that forgets the block is asked once to finish it, then gated anyway. The gate widget counts observations live while you reproduce.
+- The Mark as fixed / Proceed / Add reproduction details / Abort menu opens automatically at the gate. `/debug-menu` reopens it; `/debug-proceed` continues with captured logs; `/debug-done` marks the problem fixed.
+- Probe ledger and log reads are grounded in disk: markers are resolved against the session cwd, removal edits no longer re-register themselves, unreadable files are reported instead of assumed clean, and `get_debug_logs` defaults to the newest run that captured observations.
+- Probe logs live under a per-session directory. `.omp/debug/` is added once to `.git/info/exclude`. Status, proceed, and `get_debug_logs` summarize hits by `hypothesisId`.
+
+## 0.1.2 - 2026-08-20
+
+- Added an interactive round-review menu with Mark as fixed, Proceed, Add reproduction details, and Abort actions.
+- Added `/debug-review` to reopen the menu and `/debug-note <details>` to return to the editor, add user evidence, and continue the workflow.
+- Kept `/debug-done fixed|proceed` as compatible shortcuts and added interactive confirmation for zero-log completion, zero-log progression, and abort.
+
 ## 0.1.1 - 2026-08-20
 
 - Replaced the localhost HTTP collector with direct JSONL file appends from instrumented runtime code.

package/README.md

@@ -2,45 +2,73 @@
 
 A Cursor Debug Mode replica for oh-my-pi. It recreates Cursor's evidence-driven, human-in-the-loop debugging workflow for OMP; it is an independent implementation and is not affiliated with Cursor.
 
-The plugin makes the agent form hypotheses, add temporary runtime probes, attempt a fix, and then pause while you reproduce the problem outside the agent loop. Your result either starts another evidence-driven round or triggers probe cleanup and a final summary.
+The plugin makes the agent form 3-5 hypotheses, add temporary runtime probes that test all of them, and pause so you can reproduce the problem. The agent is instructed to NEVER fix without runtime evidence first; after a fix it keeps those probes in place for a verification reproduce. Your result either starts another evidence-driven round or triggers probe cleanup and a final summary.
 
 ## Commands
 
 | Command | Purpose |
 | --- | --- |
 | `/debug-mode <problem>` | Starts a debugging session from a symptom, expected result, actual result, and reproduction description. |
+| `/debug-menu` | Opens the interactive action menu after a round reaches the reproduction gate. |
+| `/debug-proceed` | Continues with captured logs: the agent evaluates hypotheses and may fix only with log proof, then asks for a verification reproduce. |
+| `/debug-done` | Marks the problem as fixed: the agent removes every probe and summarizes the result. |
+| `/debug-note <details>` | Adds reproduction details from the editor and starts the next evidence-driven round. |
 | `/debug-status` | Shows the current phase, round, run, live probes, and captured log counts. |
-| `/debug-done fixed` | Confirms the fix and asks the agent to remove every probe and summarize the root cause and final change. |
-| `/debug-done proceed` | Reports that the issue remains, asks the agent to analyze the captured logs, and starts another hypothesis/instrument/fix round. |
-| `/debug-abort` | Stops debug mode and removes its logs while leaving code changes in the working tree. |
+| `/debug-abort` | Stops debug mode and removes its logs after confirmation while leaving code changes in the working tree. |
+
+## The Reproduction Gate
+
+A round ends at the gate when the Agent emits a `<reproduction_steps>` block, not merely when it stops talking. So a clarifying question mid-round leaves you talking to the Agent normally, while an instrumented round that forgot its steps is asked once to finish properly and is then gated anyway so the workflow cannot stall. If a round reaches the gate without adding any probes, the plugin warns you that it cannot produce runtime evidence.
+
+At the gate a widget shows the reproduction steps and a live counter of captured observations that updates while you reproduce the problem outside omp, so you can tell whether the instrumented path actually ran before you decide anything.
+
+## Interactive Round Review
+
+When a round reaches the reproduction gate, the plugin opens the action menu (titled with the log and probe counts your decision depends on). Reproduce in the real application first if you still need evidence, then pick an action. Dismiss the menu to keep waiting; `/debug-menu` reopens it. `/debug-proceed` and `/debug-done` skip the menu.
+
+- **Mark as fixed** - asks the Agent to clean up probes and summarize the root cause and fix. If the round captured no runtime logs, the plugin asks for confirmation first.
+- **Proceed** - refreshes the log file at selection time, archives the completed run, and starts log analysis. The Agent evaluates each hypothesis as CONFIRMED / REJECTED / INCONCLUSIVE, may apply a fix only with 100% confidence while keeping probes, and then asks you to reproduce again. If no runtime observations exist, the plugin asks for confirmation before proceeding.
+- **Add reproduction details** - closes the menu and pre-fills the editor with `/debug-note ` so you can add symptoms, environment details, or reproduction results before continuing.
+- **Abort debug mode** - asks for confirmation, removes debug logs, and keeps applied code changes.
+
+The existing `/debug-proceed` and `/debug-done` commands remain available for non-interactive and shortcut use.
 
 ## Workflow
 
 1. Run `/debug-mode <problem description>`.
-2. The agent investigates, records hypotheses, inserts minimal probes marked with `@omp-probe <id>`, and attempts a fix. Each probe appends its runtime observation directly to the exact JSONL file provided in the injected prompt.
-3. When the agent stops, reproduce the issue in the real application so the instrumented code writes its observations.
-4. Run `/debug-done fixed` if the issue is resolved, or `/debug-done proceed` to make the agent read the completed run's JSONL file, analyze the evidence, and continue.
-5. On success, the agent removes all probes, verifies the probe ledger is empty, and summarizes the root cause and fix.
+2. The Agent records 3-5 hypotheses and inserts minimal probes marked with `@omp-probe <id>` inside `#region agent log` blocks. Round 1 does not apply a product fix. The start prompt and a per-turn `debug-mode-context` message name the exact JSONL path and require every probe to append to it, including `hypothesisId`; console output (including Unity `Debug.Log`) is supplemental only. The context filter keeps the newest of those messages so the model sees the contract instead of dropping it.
+3. When the Agent reaches the gate, follow the `<reproduction_steps>` in the real application so the instrumented code writes its observations, watching the widget counter climb. Restart the app or service if the instrumented build would otherwise be stale.
+4. Choose **Proceed**, **Mark as fixed**, or return to the editor to submit `/debug-note <details>` from the action menu (or `/debug-menu` if you dismissed it). `/debug-proceed` and `/debug-done` skip the menu.
+5. On Proceed, the Agent reads the captured logs, cites evidence for each hypothesis, and only then may apply a fix. Probes stay in place. Reproduce again to verify. If verification fails, rejected-hypothesis code changes are reverted before the next instrumented round.
+6. On Mark as fixed, the Agent removes every probe and summarizes the root cause and fix in 1-2 lines.
 
-The extension also provides the read-only `get_debug_logs` and `list_debug_probes` tools so the agent can inspect runtime evidence and verify cleanup.
+The extension also provides the read-only `get_debug_logs` and `list_debug_probes` tools so the Agent can inspect runtime evidence and verify cleanup.
 
 ## Runtime Data
 
-At the start of each round, the plugin creates an absolute log path:
+At the start of each round, the plugin creates an absolute log path under a directory owned by the current session:
 
 ```text
-<project>/.omp/debug/current.jsonl
+<project>/.omp/debug/<session-id>/current.jsonl
 ```
 
+The session segment keeps concurrent omp sessions from truncating or deleting each other's evidence, since every round truncates `current.jsonl` and teardown removes the directory. The plugin also adds `.omp/debug/` to the repository's local `.git/info/exclude` once, so probe logs never appear in `git status`; that file is not committed, so your `.gitignore` is left alone.
+
 That exact stable path is injected into the Agent prompt. The prompt requires every runtime probe to use the target environment's native file append API and write one compact JSON object plus a newline using this schema:
 
 ```json
-{"probe":"player-state","ts":1787193600000,"data":{"isGrounded":false}}
+{"probe":"player-state","hypothesisId":"A","ts":1787193600000,"location":"Player.cs:42","message":"grounded check","data":{"isGrounded":false}}
 ```
 
-Probes append directly to `current.jsonl`; they must not overwrite it, and they should flush and close the file promptly rather than retaining an exclusive handle. The stable filename means probes retained across rounds continue writing to the correct place without being rewritten just to change a path. The mechanism does not use HTTP, localhost, sockets, or any other network transport, so environments such as the Unity Editor can use their normal filesystem APIs. The target process still needs permission to access the displayed absolute path.
+`get_debug_logs`, the proceed prompt, and `/debug-status` summarize each run by `hypothesisId`, so you can see which hypotheses produced evidence before reading a single raw line. A hypothesis with no entries was not exercised, which is not the same as being rejected.
+
+If the log file contains zero entries, treat that as instrumentation or execution-path evidence. Check the build, path permissions, code path, and file append errors; do not ask the user to copy Unity Console output. Use `/debug-note` for reproduction details, not manual console transcription.
+
+When you proceed from the review menu, `/debug-proceed`, or `/debug-note`, the plugin archives the completed file as `<run-id>.jsonl` and creates an empty `current.jsonl` for the next reproduction. Because the active run is truncated at the start of every round, `get_debug_logs` defaults to the newest run that actually captured observations and names the run it read; `previous=true` forces the last completed run. `/debug-status` shows the current absolute file path and the per-run log counts.
+
+## Probe Ledger
 
-When you run `/debug-done proceed`, the plugin archives the completed file as `<run-id>.jsonl`, creates an empty `current.jsonl` for the next reproduction, and makes the Agent analyze the archived evidence through `get_debug_logs`. `/debug-status` shows the current absolute file path and log count.
+The plugin tracks every `@omp-probe <id>` marker the Agent writes, resolving each file against the session working directory. Before each round and on every `list_debug_probes` call it rescans those files so the ledger matches the code on disk: markers the Agent has since deleted drop out, and a file that exists but cannot be read is reported as *unverified* rather than assumed clean. That way a failed read can never make teardown claim the probes are gone while they are still in your source.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siuver/omp-debug-mode",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "A Cursor Debug Mode replica for evidence-driven, human-in-the-loop debugging in oh-my-pi.",
   "license": "MIT",