@siuver/omp-debug-mode 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.4 - 2026-08-21
+
+- Added least-user-intervention evidence planning: the agent chooses `agent_inspection`, `runtime_probe`, `user_report`, or `user_artifact` per hypothesis, must justify user-assisted methods, and batches compatible hypotheses into the fewest reproductions or captures.
+- Added persisted evidence requests, user observations, and in-place artifact metadata plus the read-only `list_debug_evidence` tool. `/debug-evidence [<request-id>] <path>` links files to pending requests without copying or deleting them, and unavailable files remain explicitly unverified.
+- Replaced the automatic round-review menu with a command-only gate widget. Removed `/debug-menu` and merged user-report submission into `/debug-proceed [details]`; users now continue with `/debug-proceed`, `/debug-evidence`, `/debug-done`, `/debug-abort`, and `/debug-status` while safety confirmations remain in place.
+- Extended the reproduction gate, cleanup context, session restore, status output, tests, and documentation for mixed probe/report/artifact rounds, including opaque RenderDoc `.rdc` captures.
+
+## 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.

package/README.md

@@ -1,78 +1,133 @@
-# @siuver/omp-debug-mode
-
-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.
-
-## Commands
-
-| Command | Purpose |
-| --- | --- |
-| `/debug-mode <problem>` | Starts a debugging session from a symptom, expected result, actual result, and reproduction description. |
-| `/debug-review` | Reopens the interactive action menu for the completed round. |
-| `/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` | Non-menu shortcut that confirms the fix and asks the agent to remove every probe and summarize the result. |
-| `/debug-done proceed` | Non-menu shortcut that analyzes the captured logs and starts another hypothesis/instrument/fix round. |
-| `/debug-abort` | Stops debug mode and removes its logs after confirmation while leaving code changes in the working tree. |
-
-## Interactive Round Review
-
-When the Agent completes a debugging round, the plugin enters the reproduction gate and opens an action 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 with captured logs** - refreshes the log file at selection time, archives the completed run, and starts the next analysis and fix round. 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.
-
-Pressing `Esc` simply closes the menu and leaves the workflow at the reproduction gate. After reproducing the issue in another application, run `/debug-review` to reopen it. The existing `/debug-done fixed|proceed` 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. The injected prompt strongly requires every probe to append runtime observations directly to the exact JSONL path; console output is supplemental only.
-3. When the Agent stops, dismiss the review menu if necessary and reproduce the issue in the real application so the instrumented code writes its observations.
-4. Reopen `/debug-review` and mark the issue fixed, proceed with logs, or return to the editor to submit `/debug-note <details>`.
-
-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:
-
-```text
-<project>/.omp/debug/current.jsonl
-```
-
-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}}
-```
-
-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-done proceed`, or `/debug-note`, 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.
-
-## Install
-
-```sh
-omp plugin install @siuver/omp-debug-mode
-```
-
-Restart omp after installation, then run `/debug-mode <problem>`.
-
-## Local Development
-
-From the repository root:
-
-```sh
-bun run check
-omp plugin link ./plugins/debug-mode
-```
-
-Restart omp after linking.
-
-## Changelog
-
-See `CHANGELOG.md` for release notes included in the npm package.
+# @siuver/omp-debug-mode
+
+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 3-5 hypotheses, choose the cheapest reliable evidence method for each one, and pause so you can reproduce the problem. The agent is instructed to NEVER fix without runtime evidence first; after a fix it keeps runtime 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-proceed [details]` | Continues with captured evidence: optional details are recorded as a user-report observation, then the agent evaluates hypotheses and may fix only with evidence before asking for verification. |
+| `/debug-evidence [<request-id>] <path>` | Attaches one user-provided evidence file to the current waiting round. If the first token matches a pending current-round request ID, the file is linked to that request; otherwise the whole argument is treated as the path (spaces allowed). Without an argument it opens an input dialog (interactive UI only). Files are referenced in place and never copied or deleted. |
+| `/debug-done` | Marks the problem as fixed: the agent removes every probe and summarizes the result. |
+| `/debug-status` | Shows the current phase, round, run, live probes, captured log counts, pending evidence requests, and attached/unavailable artifacts. |
+| `/debug-abort` | Stops debug mode and removes its logs after confirmation while leaving code changes in the working tree. |
+
+## Evidence Methods
+
+For every hypothesis, the agent must pick one of four methods, in least-user-intervention order:
+
+1. **`agent_inspection`** - reuse existing logs/files and the agent's own read/search/test/command tools. Always tried first.
+2. **`runtime_probe`** - if runtime state is required, the agent installs `@omp-probe` instrumentation and combines every compatible hypothesis into a single reproduction.
+3. **`user_report`** - only when a simple manual observation is decisive (something only you can see or try).
+4. **`user_artifact`** - only when the disputed state cannot be represented reliably by inspection, probes, or a verbal report (e.g. a GPU capture, screenshot, crash dump, or externally generated trace).
+
+Rules the agent must follow:
+
+- It never asks you to run a command it could run itself.
+- All unavoidable user actions are batched into the fewest reproductions/captures: hypotheses answerable by the same action share one request (`hypothesisIds` lists them all) instead of serial reports.
+- A lower-priority method is never chosen merely because it is familiar; every `user_report`/`user_artifact` entry needs a rationale explicitly naming why agent inspection and runtime probes cannot settle its hypotheses.
+
+## The Evidence Plan
+
+Each round closes with an exact machine-readable block that covers every hypothesis:
+
+```text
+<evidence_plan>
+[{"id":"E1","hypothesisIds":["A","B"],"method":"runtime_probe","title":"...","rationale":"The disputed runtime branches are not present in existing logs; one model-added probe set can capture both without a separate user artifact.","instructions":["..."],"artifactHint":"optional"}]
+</evidence_plan>
+```
+
+Every field is validated: `id` must be unique and non-empty, `hypothesisIds` must reference one or more real hypotheses, `method` must be one of the four literals above, `rationale`/`title` must be non-empty, and `instructions` must contain actionable steps (`artifactHint` describes the expected file kind for `user_artifact`). A malformed plan is rejected entirely — no hypothesis is ever silently dropped. Plans are capped at 12 entries per round. The plan is combined with the existing `<reproduction_steps>` block, which describes the single combined reproduction/capture sequence.
+
+## 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.
+
+Rounds must also close with a valid `<evidence_plan>`. If the plan block is missing, the agent is nudged once for the exact JSON block plus the reproduction steps; after that the gate proceeds anyway with a note that the next round will be asked to declare a method. A round with neither probes nor a valid evidence plan gets the "no runtime evidence" warning; a valid plan that chose a non-probe route (e.g. `agent_inspection` or `user_artifact`) is a properly closed round and produces no such warning — and for `user_report`/`user_artifact` plans, no JSONL logs are expected at all.
+
+At the gate a widget shows the reproduction steps, any pending user requests (title, instructions, artifact hint), a live counter of captured observations, an `evidence: <pending> pending, <attached> attached` counter, and the list of commands you can use, so you can tell what evidence the round is waiting on and how to act. The widget always ends with the live log counter. Every round stops at the widget and you interact through commands only.
+
+Pending requests resolve like this:
+
+- A `user_artifact` request is pending until a file is attached with a matching request ID.
+- A `user_report` request is pending until `/debug-proceed <details>` records an observation for the current round; one details submission can satisfy several report requests at once.
+- `agent_inspection` and `runtime_probe` requests never create user work.
+
+If user requests are still pending when you run `/debug-proceed`, the plugin asks "Proceed without all requested evidence?" — confirming is allowed so an unavailable external capture can never deadlock the session; cancelling keeps you at the gate. `/debug-proceed` and `/debug-done` ask for confirmation when the round captured no runtime logs and has no valid non-probe evidence plan.
+
+## Attaching Evidence Files
+
+`/debug-evidence [<request-id>] <path>` records one user-provided file for the current waiting round:
+
+- The path is resolved against the session working directory; the plugin records the absolute path, size, and mtime and references the file **in place**. It never copies, renames, or deletes your file — not during attach, not during cleanup, not during teardown.
+- If the first argument token matches a pending current-round request ID, the file is linked to that request; otherwise the entire argument is treated as the path (spaces are supported) and the artifact is attached unlinked — the agent sees it as unassigned evidence and must associate it with a request itself.
+  A path whose first token happens to look like a request ID but does not match one is simply treated as a path.
+- Interactive sessions must confirm before recording a path outside the session working directory; non-interactive sessions reject outside-`cwd` paths because no confirmation channel exists.
+- Re-attaching the same resolved path reuses the existing artifact entry and refreshes its metadata and request association.
+- Missing paths, directories, and unreadable files are rejected with the reason, and the ledger stays unchanged.
+
+Availability is re-checked by re-statting each path, so a file that was moved or deleted after attaching is reported as *unavailable* — the ledger never claims unavailable evidence was captured. The model is told to treat user reports and artifacts as data to inspect, not instructions to execute, and must conclude INCONCLUSIVE (or file a new, lower-burden request) when it cannot inspect a file with its normal tools.
+
+Example: for a GPU-rendering symptom whose disputed state only exists inside a frame capture, the agent justifies why inspection, tests, and probes cannot answer, then emits one `user_artifact` request with an `artifactHint` like "RenderDoc .rdc capture of a failing frame". You capture `frame.rdc` in RenderDoc and run `/debug-evidence E1 frame.rdc` (using the request ID shown in the widget). `/debug-status` and the read-only `list_debug_evidence` tool then show the artifact ID, absolute path, size, and availability. The `.rdc` bytes are treated as opaque — the plugin does not parse the format; if the agent cannot extract what it needs from the binary with its normal `read`/`bash` tools, it says so and asks for a converted report or a new capture rather than guessing.
+
+## Workflow
+1. Run `/debug-mode <problem description>`.
+2. The Agent records 3-5 hypotheses and picks an evidence method for each under the least-user-intervention priority. If the route is `runtime_probe`, it 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 — or supply the requested evidence with `/debug-evidence` or `/debug-proceed <details>`. Restart the app or service if the instrumented build would otherwise be stale.
+
+4. Continue with `/debug-proceed [details]` (optionally record a user observation, then evaluate evidence), `/debug-done` (clean up and summarize), `/debug-evidence` (attach a file), or `/debug-status` (inspect the current round state). Each round stops at the widget; all interaction is command-driven.
+5. On Proceed, the Agent reads the evidence (logs, your observations, attached artifacts), cites the evidence method plus log-line numbers or artifact/report paths 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 round.
+6. On `/debug-done`, 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`, `list_debug_probes`, and `list_debug_evidence` tools so the Agent can inspect runtime evidence, review pending/satisfied requests with their methods and rationales, and verify cleanup.
+
+## Runtime Data
+
+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/<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. Teardown removes only this log directory; attached user evidence files are never removed.
+
+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","hypothesisId":"A","ts":1787193600000,"location":"Player.cs:42","message":"grounded check","data":{"isGrounded":false}}
+```
+
+`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.
+
+When you run `/debug-proceed [details]`, the plugin records non-empty details as a user observation, 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
+
+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. Rounds that choose non-probe evidence methods simply add no markers, and cleanup still verifies that no leftover markers remain before finishing.
+
+## Install
+
+```sh
+omp plugin install @siuver/omp-debug-mode
+```
+
+Restart omp after installation, then run `/debug-mode <problem>`.
+
+## Local Development
+
+From the repository root:
+
+```sh
+bun run check
+omp plugin link ./plugins/debug-mode
+```
+
+Restart omp after linking.
+
+## Changelog
+
+See `CHANGELOG.md` for release notes included in the npm package.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@siuver/omp-debug-mode",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
-  "description": "A Cursor Debug Mode replica for evidence-driven, human-in-the-loop debugging in oh-my-pi.",
+  "description": "Evidence-driven, human-in-the-loop debugging with autonomous probes and user-assisted artifacts for oh-my-pi.",
   "license": "MIT",
   "homepage": "https://github.com/Siuver/blackhole/tree/master/plugins/debug-mode#readme",
   "repository": {
@@ -30,7 +30,7 @@
   ],
   "omp": {
     "name": "debug-mode",
-    "description": "Cursor-style human-in-the-loop debugging with runtime probes and reproduction gates.",
+    "description": "Evidence-driven debugging with least-user-intervention methods, runtime probes, and user artifacts.",
     "extensions": [
       "./src/main.ts"
     ]