@litfamily/litgrok 1.0.0

package/.grok/skills/debugging/references/methodology/08-qa.md

@@ -0,0 +1,94 @@
+# Phase 8 — Manual QA by Actually Using It
+
+Tests cover cases you thought of. Real usage covers the ones you didn't.
+
+The single fastest way to ship a broken fix is to stop at "tests pass". Manual QA means interacting with the running system the way the user does, then comparing observed behavior to the original bug report.
+
+---
+
+## Product-type playbook
+
+Pick the row that matches the product. Do what it says. Do not substitute.
+
+| Product type | QA means… |
+|---|---|
+| **CLI tool** | Open `tmux`, run the actual command end-to-end, capture output. Paste the session transcript into the journal. Include exit code, stdout, stderr, side-effect check (files created/modified). |
+| **HTTP API** | Start the real server, hit endpoints with `curl` or `httpie`, inspect response status + body + headers. Hit the specific endpoint that reproduced the bug. If there's auth, use real auth. |
+| **Browser-served web app** | **Drive a real browser via Playwright CLI.** See [tools/playwright-cli.md](../tools/playwright-cli.md). Navigate the exact page/flow that reproduced the bug. Capture screenshot + DOM + network evidence. **Do not substitute with curl** — browsers have state (cookies, localStorage, service workers, client-side JS, viewport-dependent CSS) that curl does not have. |
+| **Agent / LLM pipeline** | Run the same user prompt that originally failed. Capture the full turn — tool calls, messages, usage counters. **Confirm non-zero usage** (zero usage = still failing silently, see silent-failure check below). |
+| **Background worker / job queue** | Trigger the job through the normal entry point (API call, cron tick, message publish), tail the worker logs, observe completion state in the queue or DB. Don't just call the worker function directly — the trigger path matters. |
+| **MCP server** | Invoke the tool via its actual client (Claude Desktop, Cursor, etc. if available) or `mcp-cli`, not just the HTTP probe endpoint. The MCP handshake itself is sometimes where bugs live. |
+| **Native binary** | Re-run the exact command that crashed / misbehaved. If the input was a file, use the same file. If the bug was exploitable, confirm the exploit repro via pwntools (see [tools/pwntools.md](../tools/pwntools.md)). Capture exit code, signal if any, core dump if generated. |
+| **Bundled-app binary** (Bun SEA, Node SEA, Electron, etc.) | Re-run the exact command. If the operation requires paid quota / blocked network, capture the **app's debug log** (`APP_DEBUG=1 APP_LOG_LEVEL=debug APP_LOG_FILE=/tmp/trace.log`) which usually emits the assembled request before sending. See [methodology/partial-runtime-evidence.md](partial-runtime-evidence.md) for combining partial signals into a defensible verification. |
+| **Long-running daemon** | Start fresh, let it run for the amount of time the bug originally took to manifest (not less), capture resource usage (memory, fd, cpu) throughout. Short-running QA misses resource leaks and cumulative state bugs. |
+
+---
+
+## Journal format
+
+Every QA run goes in the journal under "Findings":
+
+```markdown
+### Manual QA — <product type> (<ISO timestamp>)
+- Scenario: <one line describing what you did>
+- Command: `<exact invocation>`
+- Observed output:
+```
+<verbatim output, trimmed to relevant section>
+```
+- Expected output: <what correct behavior looks like>
+- Fix verified: yes / no / partial — <details>
+```
+
+If any QA step shows **partial or regressed behavior**, this is not "mostly done" — it's incomplete. Return to Phase 6.
+
+---
+
+## The silent-failure check (always run)
+
+Regardless of product type, audit the fix against these silent-failure patterns. If the original bug was a silent failure, the same pattern may exist in adjacent code that you haven't tested yet.
+
+### Universal silent-failure signals
+
+- HTTP 2xx with empty or default body
+- Response `ok: true` but a sub-field contains an error token (e.g. `stopReason: "error"`, `status: "failed"`)
+- `usage.totalTokens === 0` on an LLM response
+- Process exit code 0 but stderr contains an exception traceback
+- Panic recovered and logged but ignored
+- Goroutine / task / promise rejection with no top-level handler
+- `try { ... } catch { /* swallowed */ }` or `except: pass`
+- Success response shape but semantic field indicates failure (e.g. `error: null` actually being `error: "..."` with falsy check)
+- Write returned success but read-back shows stale data
+- Job marked complete but side-effect did not happen
+- Cache hit path returned stale data and no refresh was triggered
+
+### Language-specific silent-failure signals
+
+Check the runtime reference for additional patterns:
+
+- [runtimes/python.md](../runtimes/python.md) — asyncio task exceptions, bare `except`, `logging.exception` that goes nowhere
+- [runtimes/node.md](../runtimes/node.md) — unhandled promise rejections, `void` on async, swallowed `.catch(() => {})`
+- [runtimes/rust.md](../runtimes/rust.md) — `.unwrap_or_default()`, `let _ = result`, error variants discarded
+- [runtimes/go.md](../runtimes/go.md) — `if err != nil { return err }` that never reaches user output, recovered panics, buffered channels that block silently
+- [runtimes/native-binary.md](../runtimes/native-binary.md) — ignored return codes from libc, missing `perror`, `alarm()` / signal masks
+- [runtimes/bundled-js-binary.md](../runtimes/bundled-js-binary.md) — `process.env.X` baked at build time, dead code from tree-shaking failures, worker sub-bundles diverging from main bundle
+
+### What to do when you find another silent-failure spot
+
+Don't fix it. This is out of scope for the current bug.
+
+Note it in the journal under a "Follow-ups" section with:
+- File:line
+- Pattern matched
+- Proposed fix sketch (one line)
+- Risk level (what happens if left unfixed)
+
+Surface these to the user in the final message under "Next steps I didn't take".
+
+---
+
+## The "fix verified" bar
+
+"Fix verified" means: the exact original failing scenario, re-run, now produces the correct output. Not a similar scenario. Not a unit test of the fix. The original scenario.
+
+If you can't re-run the original scenario (e.g. it required a specific data state that's gone), construct the closest equivalent and document the difference in the journal. Escalate to the user if the equivalent is materially different.

package/.grok/skills/debugging/references/methodology/09-cleanup.md

@@ -0,0 +1,164 @@
+# Phase 9 + 10 — Cleanup & Final Verification
+
+The working tree after the session must differ from before only by the real fix and its test. Anything else is a process failure.
+
+---
+
+## Phase 9 — Cleanup & Revert
+
+### The walk
+
+Open the journal's "Artifacts to revert" list. Walk it top to bottom. Check each box only after the revert command succeeds and produces no error.
+
+### Standard revert operations
+
+Most sessions create some combination of these artifacts. The commands below are the defaults — your journal should have the exact commands for this session.
+
+```bash
+# --- Temporary source edits (instrumentation statements, debug prints) ---
+git checkout <file>                              # reverts only that file
+git diff <file>                                  # verify clean
+
+# --- tmux sessions ---
+tmux kill-session -t <session-name>
+tmux ls                                          # confirm gone
+
+# --- Temp fixtures / scratch scripts ---
+rm -f /tmp/debug-*.*
+ls /tmp/debug-*.* 2>/dev/null                    # confirm gone (ls returns non-zero when no match)
+
+# --- Background processes (debugger-attached runtimes) ---
+pkill -f 'node --inspect' || true
+pkill -f 'python -m pdb' || true
+pkill -f 'debugpy' || true
+pkill -f 'dlv' || true
+pkill -f 'gdb' || true
+pkill -f 'lldb' || true
+
+# --- Debug-relevant ports confirmed free ---
+lsof -iTCP:9229 -sTCP:LISTEN -nP 2>/dev/null     # Node inspector default
+lsof -iTCP:5678 -sTCP:LISTEN -nP 2>/dev/null     # debugpy default
+lsof -iTCP:2345 -sTCP:LISTEN -nP 2>/dev/null     # dlv default
+lsof -iTCP:9999 -sTCP:LISTEN -nP 2>/dev/null     # pwndbg/gdb-server default
+
+# --- Env var overrides in current shell ---
+unset DEBUG_OVERRIDE_FOO
+unset PYTHONBREAKPOINT
+unset RUST_LOG
+unset DEBUG
+
+# --- Ghidra scratch projects (if created just for this session) ---
+# rm -rf ~/ghidra-projects/debug-scratch
+
+# --- Core dumps from debugging (if any) ---
+rm -f ./core ./core.* ~/core.*
+
+# --- Playwright trace files ---
+rm -rf playwright-report/ test-results/
+```
+
+### The verify command
+
+This is the single most important check of the whole skill:
+
+```bash
+git status
+git diff --stat
+```
+
+The diff must contain **only**:
+
+1. The real fix.
+2. The new failing-first test.
+3. Nothing else.
+
+### Detector checklist — scan the diff for these
+
+If `git status` shows any untracked debug file, or `git diff` shows any of the patterns below, **you are not done**. Clean it.
+
+| Pattern | Usually means |
+|---|---|
+| `debugger;` | Node debug statement left behind |
+| `breakpoint()` | Python debug statement left behind |
+| `dbg!(...)` | Rust debug macro left behind |
+| `fmt.Println("DEBUG: ...")` | Go ad-hoc print |
+| `console.log("[DEBUG]` | Node ad-hoc log |
+| `print(f"DEBUG: ` | Python ad-hoc print |
+| `// TODO DEBUG`, `// HACK`, `// XXX` | Stale debug marker |
+| `// <PROJECT>-DEBUG` | Session-specific marker from this skill's edits |
+| Commented-out code blocks near the fix | Dead code from trial fixes |
+| Reordered imports or formatting in unrelated files | Drift from your editor's autoformat during the session |
+
+### Remove the journal
+
+Only once the git check is clean:
+
+```bash
+rm .debug-journal.md
+sed -i.bak '/^\.debug-journal\.md$/d' .git/info/exclude && rm -f .git/info/exclude.bak
+```
+
+The journal is not part of the fix; it doesn't belong in the commit or in the git exclude list.
+
+---
+
+## Phase 10 — Final Verification
+
+Last gate before reporting done. All four gates must be true, and all four must have **evidence in your final message** to the user. Passing a gate without evidence is the same as failing it.
+
+### The four gates
+
+1. **Red→green toggle confirmed** — show the failing test output from before the fix and passing output after. Both outputs visible in the reply or the journal.
+
+2. **Full test suite green** — show the suite's final pass line (e.g. `42 passed in 3.14s`). Not just the new test.
+
+3. **Manual QA reproduced the fix** — show the command or scenario that originally failed and its now-correct output. Verbatim, not paraphrased.
+
+4. **Working tree clean of debug artifacts** — show `git diff --stat` output containing only fix + test, plus `git status` clean of untracked debug files.
+
+If any of the four lacks evidence, you have not finished — return to the appropriate phase.
+
+### Final message template
+
+Keep it short. Evidence-dense. The user should be able to skim it in 30 seconds.
+
+```markdown
+Fixed.
+
+**Root cause**: <one sentence — the mechanism, not the symptom>
+**Fix**: `<file:line>` — <two words>
+**Test**: `<test file>::<test name>` — red without fix, green with fix
+**QA**: <one line describing what you ran and what you saw>
+
+Diff:
+```
+<git diff --stat output — should be tiny>
+```
+
+**Next steps I didn't take** (awaiting your decision):
+- <follow-up 1, if any — from QA silent-failure scan or refactor opportunities noted during Phase 7>
+- <follow-up 2 — or "none" if nothing else surfaced>
+```
+
+### Example (from a real session)
+
+```markdown
+Fixed.
+
+**Root cause**: pi-mono Agent's `model.baseUrl` was hardcoded to `api.anthropic.com`, so the `ANTHROPIC_BASE_URL` env var was silently ignored. The proxy API key was rejected by the real Anthropic API with 401, but pi-mono packaged the error into the assistant message's `errorMessage` field instead of throwing, so the route's try/catch never fired and the client received HTTP 200 with empty content.
+
+**Fix**: `core/pi-bridge/modelResolver.ts:117` — override baseUrl
+**Test**: `__tests__/core/modelResolver.test.ts::resolves_env_override` — red without fix, green with fix
+**QA**: `curl -X POST /api/refinement/chat` with proxy env set, observed non-zero usage and non-empty content
+
+Diff:
+```
+ core/pi-bridge/modelResolver.ts              | 3 +++
+ __tests__/core/modelResolver.test.ts         | 42 ++++++++++++++++++++++
+ 2 files changed, 45 insertions(+)
+```
+
+**Next steps I didn't take** (awaiting your decision):
+- pi-mono itself silently swallows LLM errors into `errorMessage`; adding a throw-on-error wrapper at our orchestrator layer would surface these upstream
+- Same silent-failure pattern exists in the planning route — likely the same fix applies
+```

package/.grok/skills/debugging/references/methodology/partial-runtime-evidence.md

@@ -0,0 +1,228 @@
+# Partial Runtime Evidence — When You Cannot Execute the Real Operation
+
+Read this when **runtime truth beats code reading** is in conflict with **you cannot run the actual operation**.
+
+The skill's first invariant is "runtime state is the only source of truth." But sometimes the only state you can produce is a *partial* observation — the real call requires paid credits, a hardware device you don't have, network access through a corporate proxy, a production secret, or a customer dataset.
+
+**Partial runtime evidence is still runtime evidence.** This reference tells you which partial signals to harvest and how to combine them so the conclusion is defensible.
+
+---
+
+## When this applies
+
+Use this reference when ALL are true:
+
+1. The bug or extraction question requires runtime confirmation (per skill invariant #1).
+2. You attempted the obvious "just run it" path and it failed for reasons unrelated to the bug:
+   - 401/402/403 from a paid API
+   - "device not found" / "permission denied" / SIP block
+   - Production-only credentials
+   - Network isolation (air-gapped, behind VPN you don't have)
+   - Time-of-day or quota limits
+3. **Mocking the entire system** would defeat the verification — you specifically need evidence about how the *real* code behaves, not a stub.
+
+If only #1 and #2 are true and you can mock cleanly, just mock and proceed. This file is for cases where mocking would invalidate the answer.
+
+---
+
+## The hierarchy of partial evidence (strongest first)
+
+When you cannot capture the full outbound payload + full response, capture as much as possible from this list. **Evidence further down the list has more inference; evidence higher up is closer to ground truth.**
+
+### Tier 1 — Pre-send / post-receive logs (best partial evidence)
+
+The system you're investigating builds a request, then sends it. If the build step logs the assembled request **before** transmission, that log is ground truth for everything except the wire-level bytes (TLS, headers added by HTTP library, etc.).
+
+```bash
+# Maximize debug logging
+APP_DEBUG=1 APP_LOG_LEVEL=debug APP_LOG_FILE=/tmp/trace.log ./target -x "minimal valid input" 2>&1 | head -200
+```
+
+Look for log lines like:
+- `Building request: model=X, params={...}`
+- `[provider] payload: {...}`
+- `Sending to <url>: <serialized body>`
+
+**Strength**: 95% of ground truth. Missing only wire-level transformations.
+
+### Tier 2 — Local interception via proxy / shim
+
+Run the real binary against a local proxy that records and (optionally) returns a canned response.
+
+```bash
+# mitmproxy approach
+mitmproxy --listen-host 127.0.0.1 --listen-port 8888 --mode regular &
+HTTPS_PROXY=http://127.0.0.1:8888 SSL_CERT_FILE=~/.mitmproxy/mitmproxy-ca-cert.pem ./target ...
+# Now mitmproxy logs the actual TLS-decrypted request
+```
+
+```bash
+# DYLD_INSERT_LIBRARIES / LD_PRELOAD shim approach
+# Wrap the network call to log payload, return a fake 200
+# See pwntools.md for shim examples
+```
+
+**Strength**: Wire-level ground truth, but requires the target to honor your proxy / preload.
+
+### Tier 3 — Static extraction × runtime fingerprint cross-check
+
+When you cannot send a request at all, you can still cross-check static analysis with whatever the binary does that *doesn't* require the real call:
+
+- The binary builds the request — even if sending fails, the build step ran. Trace it (Tier 1).
+- The binary writes a state file or cache — read it.
+- The binary emits version-specific User-Agent strings; verify they match your static extraction.
+- The binary's `--help` or `--version` output reveals build metadata; verify model lists / feature flags.
+
+**Strength**: Disjoint evidence sources confirming the same fact. Two independent partial signals that agree are nearly as strong as one full observation.
+
+### Tier 4 — Contrastive runtime under different inputs
+
+If you can run with input variant A but not B, run A and reason about B from code:
+
+```bash
+# A: minimal trial input — works for free tier
+./target --action=read --resource=local-file
+# B: full inference call — paid tier required, blocked
+# But the request-building code is shared between A and B!
+# Capture A's logs, then inspect the code path for B and verify only the model/endpoint diff.
+```
+
+**Strength**: Confirms shared code paths; remaining gap is only the difference between A and B.
+
+### Tier 5 — Vendor-published API logs / dashboard
+
+If the operation succeeded earlier (before quota ran out, before access was revoked), the vendor's dashboard / audit log may show the request. Lower fidelity but still observed behavior.
+
+**Strength**: Real wire data, but often summarized — token counts, status codes, no payload bodies.
+
+### Tier 6 — Pure code reading with peer review
+
+If literally none of the above is available, read the code carefully and submit it to **one Oracle for skeptical review** (see "Verification Oracle" below). This is the weakest tier and you must explicitly mark conclusions as "unverified" in the journal.
+
+---
+
+## How to combine partial signals
+
+A defensible conclusion **prefers two independent signals from different tiers**, with one exception: a complete Tier 2 wire-level capture is wire-level ground truth and can stand alone for request-shape claims (because the wire bytes are exactly what the remote received). For *behavioral* claims (what the system does next, what state it stores, what side effects it produces), still combine with another signal.
+
+| Available evidence | Defensibility |
+|---|---|
+| Tier 1 + Tier 1 (same log, different lines) | weak — single source |
+| Tier 1 + Tier 2 (debug log + proxy capture) | **strong** — independent confirmation |
+| Tier 1 + Tier 3 (debug log + version output cross-check) | **strong** — disjoint sources |
+| Tier 2 alone (full proxy capture) | strong **for request-shape claims only** — stands alone for "what bytes were sent". Add a second signal for response-handling or state claims. |
+| Tier 3 + Tier 4 (cross-check + contrastive run) | medium — both partial |
+| Tier 6 alone (code reading only) | **insufficient** — escalate or mark unverified |
+
+Record in the journal:
+
+```markdown
+## Partial runtime evidence
+### Question being verified
+<the specific claim, e.g. "Opus 4.7 default effort is 'high'">
+
+### Available signals
+- Tier 1: debug log /tmp/trace.log line 47-49 shows `effort: "high"` ✓
+- Tier 3: static extraction of m5T() function returns "high" for smart mode ✓
+- Tier 6: code path verified by reading prompt-builder.js ✓
+
+### Independence assessment
+Tier 1 and Tier 3 are independent — the log was emitted by a different
+code path than m5T() and would diverge if the static reading were wrong.
+
+### Conclusion
+VERIFIED via Tier 1 + Tier 3 agreement. No need to escalate.
+```
+
+If you cannot achieve a complete Tier 2 capture **or** two independent non-Tier-6 signals from the table above, **write an explicit note in the deliverable**:
+
+> ⚠️ Partial-evidence finding. The full outbound payload could not be captured because [reason]. The conclusion rests on:
+> - [signal A — tier and source]
+> - [signal B — tier and source]
+> A future verification should attempt [the missing tier] when [condition].
+
+---
+
+## Verification Oracle pattern (for non-debug tasks)
+
+The skill's main Oracle Triple (`04-oracle-triple.md`) is for **stuck debugging** — 2 failed rounds, mental box, three orthogonal framings to break out.
+
+For tasks where the deliverable is an **artifact, not a bug fix** (reverse engineering, extraction, audit, compliance documentation), use a different pattern: **single Oracle, late, skeptical, with the deliverable in hand**.
+
+### When to invoke
+
+- Right before declaring an extraction/audit task "done"
+- After every significant revision of the deliverable (not after every small edit)
+- Maximum 3-4 iterations before escalating to user
+
+### Pattern
+
+Use a Grok Build `explore` lane or verifier subagent with this prompt shape:
+
+```text
+SKEPTICAL FINAL VERIFICATION — be critical, look for reasons the task is incomplete or wrong.
+
+## Original task
+<verbatim user request>
+
+## What I produced
+<list of artifacts with paths and brief descriptions>
+
+## Specific claims to verify
+<bullet list of every concrete claim in the deliverable>
+
+## Where to look
+<paths the Oracle should Read / Bash to verify>
+
+## Your job
+1. Read the deliverables.
+2. Spot-check each claim against the source/evidence the deliverable cites.
+3. Identify any unsubstantiated claims, missing pieces, or factual errors.
+4. End with PASS / FAIL / PARTIAL with specific gaps.
+Be skeptical. Don't rubber-stamp.
+```
+
+### Why this differs from the Oracle Triple
+
+| | Oracle Triple (debug) | Verification Oracle (artifact) |
+|---|---|---|
+| Trigger | 2 failed hypothesis rounds | About to declare "done" |
+| Count | 3 in parallel, orthogonal framings | 1 sequential, focused review |
+| Goal | Break out of mental box | Catch unsubstantiated claims |
+| Tone of prompt | Brainstorm wide alternatives | Skeptical audit |
+| Iteration | Reset hypothesis set after | Fix gaps, re-invoke until PASS |
+
+### Don't conflate them
+
+If you're stuck debugging, do the Triple. If you have a deliverable and need it audited, do the Verification Oracle. Doing the Triple on a finished extraction will return three diverging "what if you tried…" tangents that are not what you need. Doing the Verification Oracle on a stuck debugging session will return a polite "the evidence is incomplete" that you already knew.
+
+---
+
+## Common partial-evidence anti-patterns
+
+| Anti-pattern | Why it fails | Replacement |
+|---|---|---|
+| "It looks right in the code, so it works" | Tier 6 alone, unverified | Add at least one Tier 1-3 signal |
+| "I ran it once, didn't error, so it's correct" | Absence of error ≠ presence of correctness | Capture the actual output and verify content |
+| "The mock returns the value I wrote, so the code is fine" | Tautology — mock loops back your assumption | Use Tier 2 (proxy) instead, or cross-check with Tier 3 |
+| "The vendor's dashboard shows my call worked" | Dashboard often only shows status code, not behavior | Combine with Tier 1 if available |
+| "I'll trust the most-recent stack overflow answer" | Code from a different version / context | Verify against the actual binary you have |
+
+---
+
+## Cleanup additions for partial-evidence work
+
+```bash
+# Proxy artifacts
+pkill -f mitmproxy 2>/dev/null
+rm -f ~/.mitmproxy/cache_* 2>/dev/null
+
+# Debug log files
+rm -f /tmp/trace.log /tmp/*-debug-trace.log
+
+# DYLD_INSERT / LD_PRELOAD shim libraries
+rm -f /tmp/*.dylib /tmp/*.so
+
+# Verify env vars set in your shell are not persisted
+unset HTTPS_PROXY APP_DEBUG APP_LOG_LEVEL APP_LOG_FILE 2>/dev/null
+```

package/.grok/skills/debugging/references/post-tool-use-failure-taxonomy.md

@@ -0,0 +1,55 @@
+# PostToolUseFailure evidence taxonomy
+
+Load this taxonomy after a failed tool call when the visible failure and the session ledger must be classified before a fix is considered. It is keyed to Grok Build's documented PostToolUseFailure event without inventing an error-result field.
+
+## Documented evidence envelope
+
+A tool event can provide hookEventName, sessionId, cwd, workspaceRoot, toolName, and toolInput on stdin. The hook environment provides the event, hook name, session id, and workspace root. The documented envelope does not name an error message, exit code, stderr, duration, subagent id, or result object.
+
+Therefore the event proves that the host classified a tool call as failed and identifies its invocation context. The visible tool transcript, command status, generated artifacts, and passive session ledger must supply any additional evidence. Absence of a ledger record does not prove success: passive hooks can be missing, untrusted, timed out, crashed, or disabled.
+
+## Failure taxonomy
+
+| Failure class | Presentation | PostToolUseFailure correlation | Next discriminating action | Do not conclude |
+| --- | --- | --- | --- | --- |
+| input validation | tool rejects empty, malformed, conflicting, or out-of-range input | toolName and inert toolInput identify the attempted invocation | reduce to the smallest invalid field and compare with documented or tested input | the implementation is broken before valid input is tried |
+| discovery | path, command, rule, skill, hook, or config cannot be found | event cwd/workspace may reveal lookup root | resolve actual cwd, inspect discovery rules, and test exact path existence | missing at one lookup root means missing everywhere |
+| permission denial | permission system prevents the tool from running | failure event may exist, but permission UI or denial text is primary | identify matching deny/ask rule and whether the call was attempted | sandbox or program logic caused the denial |
+| sandbox denial | approved process crosses filesystem or child-network boundary | tool invocation is visible; host event lacks the blocked path unless present in input | record active profile and reproduce with the same permitted target | disabling the sandbox is a program fix |
+| executable missing | shell or command cannot locate a program | toolName names the shell-like tool, not the missing executable | inspect PATH and resolve the named command without installing anything | a similarly named binary is the required dependency |
+| working-directory mismatch | relative path or package command resolves against the wrong root | compare event cwd and workspaceRoot with intended product root | run a read-only root/status check, then repeat the exact command from documented cwd | the file itself is absent or corrupt |
+| program exit | process starts and returns a non-zero status | event establishes failed tool call; transcript supplies status/stderr | preserve exit and reduce program input while holding environment constant | every non-zero exit is the same failure class |
+| assertion mismatch | test runs but observed value differs from expected | correlate event with the precise test command and transcript | run the narrow test and identify first semantic mismatch | the entire suite is invalid |
+| timeout or hang | foreground result does not arrive within the bounded interval | event may appear only after the host classifies failure | distinguish timeout, background continuation, deadlock, and slow completion | elapsed time alone proves termination |
+| cancellation | user or parent cancels a running action | ledger ordering can show the turn boundary but not invented cancellation details | inspect task state and any partial artifacts before retry | cancellation preserved atomicity |
+| partial mutation | call fails after creating or changing some state | event input names intended operation, not completed writes | inventory target bytes, temp files, locks, and external effects before recovery | failure means nothing changed |
+| environment skew | version, variable, executable, architecture, or cwd differs from expected baseline | session and workspace fields help bind the observation | record exact version and environment fact, then compare one dimension | a clean-HEAD run automatically matches the dirty environment |
+| hook recorder failure | passive recorder itself exits non-zero or never records | visible tool failure may exist without a usable ledger line | drive the hook directly with documented JSON and inspect stderr/state | no record means no tool failure |
+| evidence ambiguity | transcript is truncated, overwritten, stale, or cannot be attributed | event envelope may identify session/cwd but not missing result | rerun a smaller safe reproducer with bounded output | the most plausible explanation is proven |
+
+## Correlation rules
+
+Correlate on more than the event name:
+
+1. sessionId must name the active investigation.
+2. cwd must match the directory from which the failure was attempted.
+3. workspaceRoot must match the project being diagnosed.
+4. toolName must match the visible failed tool call.
+5. toolInput must be treated as sensitive inert data and compared only as needed.
+6. Ledger ordering must not be mistaken for a host timestamp contract unless a product-owned recorder added its own timestamp.
+
+If any field disagrees, record a correlation conflict rather than merging the evidence. Multiple failures in one session require ordering and a stable identifier from product-owned evidence; do not invent one in the host event.
+
+## Classification procedure
+
+Start at the earliest failed boundary. Ask whether the tool was invoked. If not, classify permission or discovery first. If invoked, ask whether the operating boundary rejected access. If access was possible, inspect process start, program exit, assertions, and timing. After any mutating call, check partial state before retrying.
+
+Choose one primary class and any contributing classes. For example, “program exit caused by working-directory mismatch” is more actionable than two unrelated labels. Each hypothesis must predict a probe result. Keep the same input while changing one environmental dimension, or keep the same environment while reducing one input dimension.
+
+## Evidence packet
+
+For each classified failure, record the visible symptom and expected result, exact invocation and cwd, primary and contributing classes, PostToolUseFailure fields actually observed, permission and sandbox state, smallest reproducer and status, partial-state inventory, supported and contradicted hypotheses, next safe probe, and inline limitation where evidence is missing.
+
+## Fix gate
+
+A code fix is justified only when the reproducer fails for the predicted reason, the proposed cause explains that observation, and a focused regression can turn GREEN without weakening permissions or sandbox settings. Configuration, environment, and authorization failures need their own remedies; rewriting program code can hide them without solving them.