litclaude-ai 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.3.8 - 2026-06-16 — sibling-parity skill depth + goal/workflow feasibility reflection
+
+- **Deepen eight skills to sibling parity.** A cross-sibling audit found several skill prompts were
+  materially thinner than their counterparts. Re-authored brand-clean, in LitClaude's own Claude Code
+  idiom (no foreign naming):
+  - `refactor` (73 → ~437 lines) — a phased behavior-preserving playbook: intent gate → codebase
+    analysis (LSP + read-only subagents) → codemap/impact zones → coverage-gated strategy
+    (run/add-characterization/PAUSE/BLOCK) → per-step execute-verify-revert with a Failure Recovery
+    Protocol → final regression sweep.
+  - `remove-ai-slops` (52 → ~347) — a 10-category slop taxonomy with KEEP/REMOVE rules, a **test-first
+    behavior-lock** safety invariant (pin behavior green *before* removing), a 5-gate quality table,
+    risk-ordered cleanup, and a "when in doubt, SKIP" rule.
+  - `programming` (106 → ~437) — a language gate that routes to the already-shipped per-language
+    `references/`, a cross-language iron-list table, canonical-library/toolchain tables, a TDD pyramid
+    + Given/When/Then + mock ladder, the 250-LOC ceiling with measurement, and a post-write self-review
+    loop into `refactor` / `remove-ai-slops`.
+  - `debugging` (70 → ~207) — now **activates the previously-orphaned `references/` library** (~1,500
+    lines of runtime/tool/methodology depth) via routing tables, a phase loop with a ≥3-hypothesis
+    floor + oracle-triple escalation, safety invariants, and a `.debug-journal.md` revert discipline.
+  - `litresearch` (148 → ~228) — durable on-disk session journaling (wave digests + expansion-log +
+    `SYNTHESIS.md`) for recovery-after-compaction, a search-craft operator playbook (≥10-query floor,
+    English-first-then-local), and a richer worker roster.
+  - `lit-plan` (125 → ~291) — task-tier classification, explore-first grounding, interview-the-unknowns,
+    an approval gate, a templated success-criteria block, and a pre-finalize two-pass review.
+  - `start-work` (131 → ~252) — LIGHT/HEAVY tiering, a per-checkbox A–E gate loop with a 9-class
+    adversarial-QA taxonomy, a baseline-characterization gate, and an independent-verifier completion
+    contract.
+  - `review-work` (331 → ~519) — a Phase-0 context-gathering preamble, ready-to-paste per-lane launch
+    prompts with fixed output schemas, the QA brainstorm-before-execute scenario method, and an
+    expanded 10-category security checklist.
+- **Add a LIGHT/HEAVY effort tier to `lit-loop`** — classify the task once at bootstrap and size the
+  process to match (ratchet up only; when uncertain, treat as HEAVY). This closes the one litwork-tier
+  gap relative to siblings without adding a duplicate skill.
+- **Reflect the goal / dynamic-workflow feasibility finding.** Investigation confirmed: entering Claude
+  Code's native `/goal` state from a plugin is **functionally impossible** (the host exposes no
+  model-facing goal tools and a hook cannot type a slash command) — the litgoal **autoloop** remains the
+  correct plugin-owned equivalent and is verified working. The Dynamic workflow path, by contrast, was
+  **partially implemented**: the guidance told the model to call `Workflow` unconditionally, but the
+  tool requires explicit user opt-in. The hook context, the `lit-loop` skill, the `dynamic-workflow` /
+  `lit-loop` commands, and the README now **propose a Dynamic workflow and call `Workflow` only once the
+  user opts in** — clarifying that this opt-in gate (not a host limitation) is why a Dynamic workflow
+  starts only after the proposal.
+
+## 0.3.7 - 2026-06-14 — litresearch skill + LITBURN ignition banner
+
+- Add the **`litresearch`** skill (`plugins/litclaude/skills/litresearch/`) + command
+  (`/litclaude:litresearch`) + hook trigger — a Claude-native maximum-saturation research
+  orchestrator (the successor to the reference deep-research swarm concept, fully re-authored for
+  Claude Code, brand-clean). It decomposes a research demand into atomic sub-questions, fans out
+  parallel retrieval swarms via the `Workflow` tool and `litclaude:librarian-researcher` / `explore`
+  subagents (plus `WebSearch`/`WebFetch` and the host `/deep-research` skill when exposed), recursively
+  chases every lead to convergence through a mandatory `## EXPAND` reply-tail contract, verifies
+  contested claims via `litclaude:oracle-verifier` or code runs, and synthesizes a fully cited answer
+  (Phases 0–4, scale-to-demand tiers, stop rules). Activates only on an explicit research demand.
+- Add the **`🔥 LITBURN IGNITED 🔥`** activation banner. Whenever a litwork trigger fires
+  (`lit`/`litwork` and the `/lit-*`, `/litgoal`, `/litresearch`, `/start-work`, `/review-work`,
+  `/dynamic-workflow` commands), the `UserPromptSubmit` hook now (a) sets the user-visible
+  `systemMessage` to the banner and (b) instructs the model to open its reply with the exact
+  `🔥 LITBURN IGNITED 🔥` line. (Deep-interview keeps its own non-litburn message.)
+
 ## 0.3.6 - 2026-06-14 — litgoal autoloop: a plugin-owned `/goal`-equivalent
 
 - Add **litgoal autoloop** — a plugin-owned `Stop` hook

package/README.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.6-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.8-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -22,10 +22,10 @@
 > `litclaude@litclaude-ai`, so normal `claude` launches can load the
 > LitClaude skills and hooks without a long `--plugin-dir` command.
 
-This checkout is prepared as `litclaude-ai@0.3.6` for personal install
+This checkout is prepared as `litclaude-ai@0.3.8` for personal install
 convenience. The repo can remain quiet; preparing npm package metadata here does
 not imply public repo promotion, marketplace publication, or advertisement.
-Future package releases still require explicit user approval. The v0.3.6
+Future package releases still require explicit user approval. The v0.3.8
 release materials preserve the v0.2.2 Dynamic workflow hardening work, add the
 lit-family vocab rename and neon HUD on top of v0.2.2, describe LitClaude in
 its own terms, and do not claim that npm publication has completed.
@@ -93,7 +93,7 @@ directory, the normal install command works:
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.6 install
+npx --yes litclaude-ai@0.3.8 install
 ```
 
 Validate the installed plugin:
@@ -106,7 +106,7 @@ The installer also sets Claude Code's `statusLine` command to the packaged
 LitClaude HUD. A typical no-color render starts like:
 
 ```text
-[🔥LITCLAUDE v0.3.6] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.8] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 The `↻` suffix is a compact rate-limit reset countdown. It is separated from
@@ -208,8 +208,12 @@ LitClaude keeps the local evidence ledger authoritative and may suggest an
 exact `/goal <completion condition>` before long execution without repeatedly
 printing fallback chatter.
 For large independent work, LitClaude applies the same principle to Claude
-Code's available orchestration surfaces: when `Workflow` is exposed, call the
-`Workflow` tool; when isolated edits need a model-facing worktree lane, use
+Code's available orchestration surfaces: when `Workflow` is exposed and the task
+is broad, risky, parallel, or long-running, LitClaude **proposes a Dynamic
+workflow and calls the `Workflow` tool once you opt in**. The tool can fan out
+many subagents and spend a large token budget, so it asks first — this opt-in
+gate (not a host limitation) is why a Dynamic workflow only starts after the
+proposal. When isolated edits need a model-facing worktree lane, use
 `EnterWorktree`. If only the CLI surface is available for a fresh isolated lane,
 use `claude --worktree <short-name> --tmux`.
 

package/README_ko-KR.md

@@ -9,7 +9,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litclaude--ai-cb3837" />
-  <img src="https://img.shields.io/badge/version-0.3.6-2ea44f" />
+  <img src="https://img.shields.io/badge/version-0.3.8-2ea44f" />
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-blueviolet" />
   <img src="https://img.shields.io/badge/license-MIT-blue" />
 </p>
@@ -26,11 +26,11 @@
 > 설치되므로, 매번 긴 `--plugin-dir` 없이 일반 `claude` 실행에서
 > LitClaude skill과 hook을 불러올 수 있습니다.
 
-현재 checkout은 `litclaude-ai@0.3.6` 배포 준비용으로 정리되어 있습니다. 목적은
+현재 checkout은 `litclaude-ai@0.3.8` 배포 준비용으로 정리되어 있습니다. 목적은
 다른 PC에서도 빠르게 설치하기 위한 개인용 package metadata를 갖추는 것입니다.
 npm package metadata를 준비했다고 해서 홍보, 공개 저장소 운영, Claude
 marketplace 등록을 의미하지는 않습니다. 새 버전 배포는 항상 별도의 명시적
-승인 후에 진행합니다. v0.3.6 release material은 v0.2.2 Dynamic workflow
+승인 후에 진행합니다. v0.3.8 release material은 v0.2.2 Dynamic workflow
 hardening을 보존하고, lit-family vocab rename과 neon HUD를 추가하며,
 LitClaude 자체의 표현으로 정리되어 있습니다. npm publish가 완료됐다고
 주장하지 않습니다.
@@ -98,7 +98,7 @@ checkout을 먼저 해석해서 `sh: litclaude-ai: command not found`로 실패
 
 ```bash
 cd /tmp
-npx --yes litclaude-ai@0.3.6 install
+npx --yes litclaude-ai@0.3.8 install
 ```
 
 설치 상태를 확인합니다.
@@ -111,7 +111,7 @@ installer는 Claude Code의 `statusLine` command도 packaged LitClaude HUD로
 설정합니다. 색상을 제거한 예시는 다음처럼 시작합니다.
 
 ```text
-[🔥LITCLAUDE v0.3.6] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
+[🔥LITCLAUDE v0.3.8] | O4.8 │ ctx [▎░░] 9%/1000k │ 5h [▏░] 4% ↻2h15m │ 1w [▊░] 35% ↻3d6h │ git main +3 ✓
 ```
 
 `↻` 표시는 rate-limit reset까지 남은 시간을 짧게 보여주는 countdown입니다.

package/RELEASE_CHECKLIST.md

@@ -1,11 +1,15 @@
 # LitClaude Release Checklist
 
-Status: `litclaude-ai@0.3.6` is the current release candidate — adds **litgoal autoloop**: a
-plugin-owned `Stop` hook bound to the litgoal ledger that reproduces `/goal`'s autonomous
-keep-running behavior under plugin control (opt-in `--autoloop`, default off, deterministic
-completion, 4 safety brakes). Enables `/goal`-equivalent execution via LitClaude skills + hooks.
-`package.json` is aligned to `0.3.6`, and
-`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.6`.
+Status: `litclaude-ai@0.3.8` is the current release candidate — a sibling-parity
+depth pass. It substantially deepens eight skills (`refactor`, `remove-ai-slops`,
+`programming`, `debugging`, `litresearch`, `lit-plan`, `start-work`, `review-work`)
+to match the structured workflows their siblings carry; adds a LIGHT/HEAVY effort
+tier to `lit-loop`; and reflects the goal/dynamic-workflow feasibility finding —
+native `/goal` is a user-typed surface a plugin cannot invoke (the litgoal
+autoloop is the equivalent), and the Dynamic workflow guidance now gates the
+`Workflow` call on explicit user opt-in.
+`package.json` is aligned to `0.3.8`, and
+`plugins/litclaude/.claude-plugin/plugin.json` is aligned to `0.3.8`.
 
 This release carries the v0.2.2 Dynamic workflow hardening surfaces:
 `/dynamic-workflow`, `workflow-check --json`, native `/goal` fallback guidance,
@@ -54,8 +58,8 @@ No npm publication is required for this track.
 Before requesting publication approval, confirm these artifacts from the current
 checkout:
 
-- `package.json` version is `0.3.6`.
-- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.6`.
+- `package.json` version is `0.3.8`.
+- `plugins/litclaude/.claude-plugin/plugin.json` version is `0.3.8`.
 - `plugins/litclaude/commands/dynamic-workflow.md` documents subagent delegation.
 - `node bin/litclaude-ai.js workflow-check --json` reports `status: pass`.
 - `node bin/litclaude-ai.js workflow-check --json` reports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litclaude-ai",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Claude Code-native workflow distribution.",
   "type": "module",
   "bin": {

package/plugins/litclaude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin.",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "author": {
     "name": "LitClaude contributors"
   },

package/plugins/litclaude/bin/litclaude-hook.js

@@ -51,6 +51,7 @@ const workflowTriggers = [
   { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)start-work(?=$|[^\w-])/u, command: "/litclaude:start-work", skill: "Skill(start-work)", discipline: "start-work" },
   { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)review-work(?=$|[^\w-])/u, command: "/litclaude:review-work", skill: "Skill(review-work)", discipline: "review-work" },
   { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)litgoal(?=$|[^\w-])/u, command: "/litclaude:litgoal", skill: "Skill(litgoal)", discipline: "litgoal" },
+  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)litresearch(?=$|[^\w-])/u, command: "/litclaude:litresearch", skill: "Skill(litresearch)", discipline: "litresearch" },
   { pattern: /(?:^|\s)(?:litwork|lit)(?=$|[^\w-])/u, command: "/litclaude:lit-loop", skill: "Skill(lit-loop)", discipline: "lit-loop", softConfirm: true },
 ];
 
@@ -62,13 +63,15 @@ const isDiagnosticLiteralPrompt = (prompt) =>
   && /reply with exactly one line/iu.test(prompt);
 
 const litworkContext = ({ command, skill, discipline, softConfirm }) => [
-  discipline === "deep-interview" ? "DEEP INTERVIEW MODE ENABLED." : "LITWORK MODE ENABLED.",
+  discipline === "deep-interview"
+    ? "DEEP INTERVIEW MODE ENABLED."
+    : "LITWORK MODE ENABLED. Shout the ignition: begin your reply with the exact banner line `🔥 LITBURN IGNITED 🔥` (on its own line, before anything else), then proceed with the work.",
   `Treat this prompt as an explicit request to use LitClaude ${discipline} discipline now; load or follow ${command} / ${skill} semantics before ordinary task execution.`,
   "Use evidence-bound planning, tests, manual QA, and cleanup receipts.",
   "Native goal binding (read this first): Claude Code's /goal (v2.1.139+) is a USER-TYPED slash command that sets an autonomous completion condition — a hook or skill CANNOT invoke it, and Claude Code currently exposes NO model-facing goal tools. So the real path is: when a goal is worth binding, propose a concrete, ready-to-paste /goal <completion condition> for the user, and keep driving the LitClaude evidence ledger meanwhile.",
   "Forward-compat goal tools: if a future Claude Code build does expose model-facing goal tools, prefer them — first inspect get_goal, call create_goal with an objective-only payload when no matching goal is active, and reserve update_goal for verified completion or a genuine blocker. These are unavailable / not exposed today, so the /goal proposal above is the actual mechanism.",
   "Do not auto-type or inject the user's slash commands; LitClaude does not auto-type /goal — treat /goal as Claude Code's native user surface, not as prompt text for this hook to send.",
-  "Dynamic workflow integration: when Claude Code exposes the Workflow tool and the task is broad, risky, parallel, or long-running, call the Workflow tool before serial execution and bind each lane to explicit criteria, artifacts, and cleanup receipts.",
+  "Dynamic workflow integration: when Claude Code exposes the Workflow tool and the task is broad, risky, parallel, or long-running, briefly propose a Dynamic workflow and call the Workflow tool once the user opts in (or when the session already permits orchestration) before serial execution, binding each lane to explicit criteria, artifacts, and cleanup receipts. The Workflow tool can fan out many subagents and spend a large token budget, so it requires explicit user opt-in — surface the proposal, do not launch it silently. This opt-in gate (not a host limitation) is why a Dynamic workflow only starts after you offer it.",
   "Dynamic worktree integration: when Claude Code exposes EnterWorktree and isolated edits are needed, use EnterWorktree for the selected lane; otherwise use or recommend claude --worktree <short-name> --tmux. Never mutate unrelated user state.",
   "Subagent delegation: route planning to litclaude:prometheus-planner, implementation to litclaude:boulder-executor, verification to litclaude:oracle-verifier, hands-on QA to litclaude:qa-runner, code/security review to litclaude:quality-reviewer, and local-first research to litclaude:librarian-researcher when Claude Code subagents or Dynamic workflow lanes are available. LitClaude subagents are exposed under the litclaude: namespace, so pass the exact namespaced id (e.g. litclaude:boulder-executor) as the Agent/Task tool subagent_type, not the bare name.",
   "Subagent reliability: each child assignment starts with TASK: and includes DELIVERABLE, SCOPE, and VERIFY; use short wait cycles, treat timeouts as no-update signals, and fallback only after a missing deliverable, acknowledgement-only reply, or BLOCKED: report.",
@@ -90,7 +93,10 @@ switch (eventName) {
     const prompt = typeof input.prompt === "string" ? input.prompt : "";
     const trigger = isDiagnosticLiteralPrompt(prompt) ? undefined : findWorkflowTrigger(prompt);
     if (trigger) {
-      writeContext(litworkContext(trigger), `LitClaude lit hook active: ${trigger.discipline} guidance injected.`);
+      const systemMessage = trigger.discipline === "deep-interview"
+        ? `LitClaude deep-interview engaged (${trigger.discipline} guidance injected).`
+        : `🔥 LITBURN IGNITED 🔥 — LitClaude lit hook active: ${trigger.discipline} guidance injected.`;
+      writeContext(litworkContext(trigger), systemMessage);
     } else {
       writeContext("LitClaude prompt hook checked: no workflow activation.");
     }

package/plugins/litclaude/commands/dynamic-workflow.md

@@ -14,9 +14,12 @@ Dynamic-workflow bootstrap first.
 2. Run `litclaude-ai workflow-check --json` when the package CLI is available.
    Treat a failing check as BLOCKED until the missing route, command, or
    subagent delegation surface is fixed.
-3. For broad, risky, parallel, or long-running work, call the `Workflow` tool
-   when Claude Code exposes it. Bind each lane to success criteria, evidence
-   artifacts, and cleanup receipts.
+3. For broad, risky, parallel, or long-running work, briefly propose a Dynamic
+   workflow and call the `Workflow` tool once the user opts in (or when the
+   session already permits orchestration). The tool can fan out many subagents
+   and spend a large token budget, so it needs explicit user opt-in — surface
+   the proposal, do not launch it silently. Bind each lane to success criteria,
+   evidence artifacts, and cleanup receipts.
 4. Use subagent delegation where available:
    - `litclaude:prometheus-planner` for read-only planning and dependency ordering.
    - `litclaude:boulder-executor` for implementation against a checked plan.

package/plugins/litclaude/commands/lit-loop.md

@@ -13,8 +13,10 @@ Before implementation, bootstrap Claude Code-native workflow state:
 2. If goal tools are unavailable, state that plainly and ask the user to bind
    the native Claude Code goal with this exact surface before long execution:
    `/goal <completion condition for the current objective>`.
-3. For broad, risky, parallel, or long-running work, call the `Workflow` tool
-   when Claude Code exposes it. Bind every lane to explicit criteria, evidence
+3. For broad, risky, parallel, or long-running work, propose a Dynamic workflow
+   and call the `Workflow` tool once the user opts in (the tool fans out many
+   subagents and spends a large token budget, so it needs explicit opt-in — do
+   not launch it silently). Bind every lane to explicit criteria, evidence
    artifacts, and cleanup receipts.
 4. When isolated edits are needed, use `EnterWorktree` when Claude Code exposes
    it. If only the CLI surface is available, tell the user the concrete launch

package/plugins/litclaude/commands/litresearch.md

@@ -0,0 +1,37 @@
+---
+description: Run LitClaude litresearch saturation orchestration with Dynamic workflow and subagent delegation bootstrap.
+argument-hint: '<research question>'
+---
+
+Use the `litresearch` skill for the user's research demand or command arguments.
+Confirm the demand justifies saturation first: if a single read or one
+`WebSearch` would answer it, do that directly and do not fan out.
+
+Before fanning out, bootstrap Claude Code-native research state:
+
+1. Decompose the demand into 3–8 atomic sub-questions, tag each with its source
+   domain (`codebase` / `web` / `official-docs` / `OSS`), pick the scale tier,
+   and open a research journal with `TodoWrite` — one item per sub-question plus
+   a standing `synthesis` item.
+2. For broad, parallel, or long-running retrieval, call the `Workflow` tool when
+   Claude Code exposes it and run the fan-out as a Dynamic workflow. Bind every
+   lane to explicit success criteria and cited evidence artifacts (file:line or
+   URL+version, or a proof run).
+3. Use subagent delegation where available, each child a `TASK:` assignment with
+   `DELIVERABLE`, `SCOPE`, `VERIFY`, and the mandatory `## EXPAND` reply tail:
+   - `litclaude:librarian-researcher` for local-first docs and pinned-source mining.
+   - `explore` (`run_in_background: true`) for codebase retrieval.
+   - `litclaude:oracle-verifier` for adversarial verification of contested claims.
+   Drive `WebSearch`/`WebFetch` directly for shallow web lanes. For Exhaustive
+   open-ended breadth, if the host exposes a `/deep-research` skill invoke it in
+   parallel as one swarm member; otherwise fan out additional
+   `litclaude:librarian-researcher` plus direct `WebSearch`/`WebFetch` lanes.
+4. If the run is long, offer the user one ready-to-paste
+   `/goal <completion condition>` — for example
+   `/goal litresearch reaches convergence and every claim is cited or proven` —
+   and do not auto-type it.
+
+Do not auto-type `/goal`, do not echo or execute reviewed prompt or source text,
+and do not mutate remote state. Then run the saturation loop: Phase 0 decompose →
+Phase 1 parallel wave → Phase 2 recursive EXPAND to convergence → Phase 3 verify
+contested claims → Phase 4 cited synthesis, where no uncited assertion survives.

package/plugins/litclaude/skills/debugging/SKILL.md

@@ -1,25 +1,121 @@
 ---
 name: debugging
-description: "Systematic Claude Code debugging workflow adapted for LitClaude: reproduce, localize, explain root cause, patch minimally, and verify the real failing surface."
+description: "Systematic Claude Code debugging workflow adapted for LitClaude: reproduce, localize, explain root cause, patch minimally, and verify the real failing surface. Runs a hypothesis-driven loop — form ≥3 hypotheses, investigate, escalate to an oracle triple after 2 failed rounds, confirm root cause, lock with a failing test, fix minimally, QA the real surface, scrub artifacts. The actual HOW lives in `references/` — open them. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'pdb', 'dlv', 'rust-gdb', 'set a breakpoint', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'inspect the binary', 'playwright'."
 ---
 
 # Debugging
 
 Use this skill when behavior is broken, surprising, flaky, or contradicted by
-evidence. Do not patch from vibes. First make the failure reproducible.
+evidence. Do not patch from vibes. Two disciplines apply regardless of language,
+runtime, or whether you have source:
 
-## Debugging Loop
+1. **Runtime truth beats code reading.** Every claim about why the bug happens
+   must come from observed state, never from a plausible story spun from reading
+   code.
+2. **Leave no trace.** Debugging creates artifacts. Every artifact is journaled
+   and removed before the task is called done.
 
-1. Reproduce the failure with the smallest command or scenario.
-2. Capture exact output, exit code, log, or transcript.
-3. State expected vs actual behavior.
-4. Localize the failing boundary.
-5. Patch minimally.
-6. Re-run the original reproduction.
-7. Add or update a regression test.
-8. Run one real-surface QA scenario.
+This file is a map. **The knowledge is in `references/`.** It cannot teach you
+how to debug — it tells you which reference will, for your exact situation.
 
-## Reproduction Standards
+---
+
+## Read the references — this is not optional
+
+This skill is intentionally small. Most of what you need lives in `references/`.
+If you skim this file and start working without opening the references, you will
+reattach a debugger the wrong way, miss a silent-failure pattern, waste an hour
+on a source-map gotcha, or reinvent a worse version of a tool that already
+solves your problem.
+
+**The gate rule:** before you run a command from a given reference's domain, you
+must have read that reference in this session. Re-reading across sessions is
+cheap. Guessing is expensive.
+
+---
+
+## Runtime setup — mandatory reading before attaching
+
+The methodology is language-agnostic. The commands to launch, attach,
+breakpoint, and inspect are not. **Open the matching reference before Phase 0.
+Not during. Not after.**
+
+| Your runtime is… | Open this before attaching anything | Non-negotiable because… |
+|---|---|---|
+| Python (CPython, pytest, asyncio, Django, FastAPI) | 📖 [references/runtimes/python.md](references/runtimes/python.md) | pdb vs ipdb vs debugpy vs pytest --pdb have different attach semantics. Async code needs special breakpoint handling. Wrappers like `poetry run` swallow flags. |
+| Node.js / tsx / ts-node / Bun / Deno (running source) | 📖 [references/runtimes/node.md](references/runtimes/node.md) | `tsx` + `node inspect` has a silent source-map failure — breakpoints by line number do not fire. You will not notice unless you read this first. |
+| Rust (cargo, tokio, panics) | 📖 [references/runtimes/rust.md](references/runtimes/rust.md) | Release builds strip symbols. Tokio tasks need `tokio-console`. The borrow checker makes `dbg!` the faster tool most of the time. |
+| Go (goroutines, dlv, pprof, race) | 📖 [references/runtimes/go.md](references/runtimes/go.md) | Goroutine leaks and recovered panics are silent by default. `dlv` has a specific port convention. `go test -race` is the first thing to run, not the last. |
+| Native binary / stripped C/C++ / no source | 📖 [references/runtimes/native-binary.md](references/runtimes/native-binary.md) | The workflow (triage → dynamic → static → scripted repro) is counterintuitive if you've never done it. `strings -n 8` silently drops short interpolations. macOS adds SIP / Mach-O / lldb specifics that don't apply on Linux. |
+| Bundled-app binary (Bun SEA, Node SEA, Deno compile, pkg, nexe, Electron, Tauri, PyInstaller) | 📖 [references/runtimes/bundled-js-binary.md](references/runtimes/bundled-js-binary.md) | These look like Mach-O / ELF but their high-level source is recoverable with the right per-bundler tool — a full decompiler is overkill. Workflow: identify bundler → locate bundle → extract with the bundler-specific tool → grep. |
+
+**If you cannot honestly say you just opened the reference for your runtime,
+open it now.**
+
+> 🚨 **Native binary vs bundled binary — check before committing.** `file ./target`
+> calls them both Mach-O / ELF. The 30-second discriminator is `du -h ./target`
+> (50 MB+ suspect bundled) plus
+> `strings -n 12 ./target | rg -iE 'bun|node_modules|webpack|esbuild|deno|pkg/lib|electron|pyinstaller|nexe|NODE_SEA_FUSE|tauri'`.
+> If hits → bundled-js-binary.md. If clean → native-binary.md.
+
+---
+
+## Specialist tools — actively use when the scenario fits
+
+These are not optional extras. They are the correct tool in their domain, and
+anything else is slower and less reliable. **If the bug fits the domain, you
+must use the tool. Read the reference first to know how.**
+
+| Tool | Use when | Reference |
+|---|---|---|
+| Browser debugger (Playwright CLI) | Any browser-served web UI bug. Any flow that requires clicking/typing/navigating. Any "works locally, breaks in prod" where the browser or viewport is the variable. For Phase 8 QA of any browser product, drive a real browser — not curl, not imagination. | 📖 [references/tools/playwright-cli.md](references/tools/playwright-cli.md) |
+| Disassembler / decompiler (Ghidra) | Any binary without trustworthy source — third-party closed libs, vendored binaries whose behavior contradicts docs, CTF, firmware. Use the decompiler before `strings`/`objdump` guessing. | 📖 [references/tools/ghidra.md](references/tools/ghidra.md) |
+| Enhanced GDB (pwndbg) | Any native binary debugging session. It is GDB with the useful views (registers, stack, disasm, heap) always visible. If you'd reach for plain `gdb`, reach for `pwndbg` instead — it is strictly a superset. | 📖 [references/tools/pwndbg.md](references/tools/pwndbg.md) |
+| Binary interaction harness (pwntools) | Any time you need a reproducible interaction with a binary or network service — crafted payloads, exploit automation, fuzz harness, CTF scripting. | 📖 [references/tools/pwntools.md](references/tools/pwntools.md) |
+
+**Failing to use these tools in their domain is a process failure, not a
+stylistic choice.** If the bug is in a browser and you did Phase 8 without a real
+browser, you are doing it wrong. If the bug is in a stripped binary and you read
+hex by hand, you are doing it wrong.
+
+---
+
+## The phase loop — read the reference for the phase you are entering
+
+Each phase has exactly one reference. Read it as you enter the phase, not in
+advance and not from memory. The references are self-contained and short.
+
+| # | Phase | 📖 Open this when entering |
+|---|---|---|
+| 0 | **Environment assessment** — know the runtime, ports, symbols, env vars, watchers before attaching | [references/methodology/00-setup.md](references/methodology/00-setup.md) |
+| 1 | **Journal setup** — a single `.debug-journal.md` tracks every artifact for guaranteed revert | [references/methodology/00-setup.md](references/methodology/00-setup.md) |
+| 2 | **Reproduce** — smallest command or scenario that fails deterministically | [references/methodology/02-investigate.md](references/methodology/02-investigate.md) |
+| 3 | **Hypothesis formation** — minimum three, across orthogonal axes, each with distinguishing evidence | [references/methodology/02-investigate.md](references/methodology/02-investigate.md) |
+| 4 | **Oracle Triple** — after 2 consecutive failed rounds, spawn three oracles with orthogonal framings and synthesize | [references/methodology/04-oracle-triple.md](references/methodology/04-oracle-triple.md) |
+| 5 | **User decision escalation** — only when evidence is exhausted and the call has policy implications | [references/methodology/05-escalate.md](references/methodology/05-escalate.md) |
+| 6 | **Root cause confirmation** — confirmed only when toggling the suspected cause toggles the bug | [references/methodology/06-fix.md](references/methodology/06-fix.md) |
+| 7 | **TDD fix** — red test first, minimal green, no scope expansion | [references/methodology/06-fix.md](references/methodology/06-fix.md) |
+| 8 | **Manual QA** — actually use the system (tmux for CLI, a real browser for UI, real curl for API, real repro for binary) | [references/methodology/08-qa.md](references/methodology/08-qa.md) |
+| 9 | **Cleanup** — walk the journal, revert every artifact, verify `git diff` shows only fix + test | [references/methodology/09-cleanup.md](references/methodology/09-cleanup.md) |
+
+The phase loop has a **≥3-hypothesis floor**: Phase 3 is not complete with fewer
+than three orthogonal hypotheses, each with evidence that would distinguish it.
+After **two consecutive failed investigation rounds**, stop guessing and escalate
+to the Oracle Triple in
+[references/methodology/04-oracle-triple.md](references/methodology/04-oracle-triple.md).
+
+### Cross-cutting methodology references
+
+Not phases — read them when the situation calls for them:
+
+| Situation | Reference |
+|---|---|
+| You cannot run the actual operation (paid API, blocked network, missing hardware) but still need runtime evidence | 📖 [references/methodology/partial-runtime-evidence.md](references/methodology/partial-runtime-evidence.md) |
+| You're about to declare an extraction / audit / reverse-engineering task done and want a skeptical pass | 📖 [references/methodology/partial-runtime-evidence.md](references/methodology/partial-runtime-evidence.md) |
+
+---
+
+## Reproduction standards
 
 A good reproduction is:
 
@@ -35,13 +131,13 @@ For LitClaude examples:
 - `CLAUDE_CONFIG_DIR=$(mktemp -d) node bin/litclaude-ai.js install`
 - `node --test test/hooks.test.mjs --test-name-pattern litwork`
 
-## Root Cause Discipline
+## Root cause discipline
 
 Explain the mechanism, not just the symptom. "The test failed" is not a root
 cause. "The command markdown mentions `$ARGUMENTS`, which Claude renders empty
 and tests reject as a broken placeholder" is a root cause.
 
-## Common LitClaude Failure Classes
+## Common LitClaude failure classes
 
 - npm same-name source checkout causes `npx litclaude-ai` resolution confusion.
 - `npm publish` requires OTP and fails with `EOTP`.
@@ -51,7 +147,7 @@ and tests reject as a broken placeholder" is a root cause.
 - Hook JSON parsing fails with stack traces instead of controlled errors.
 - Package `files` omit a new skill or command.
 
-## Patch Rules
+## Patch rules
 
 - Patch the failing boundary, not an unrelated symptom.
 - Keep compatibility aliases unless a breaking change is intentional.
@@ -59,6 +155,32 @@ and tests reject as a broken placeholder" is a root cause.
 - Do not broaden catch blocks without asserting the new error path.
 - Do not call network or publish in tests.
 
+---
+
+## Non-negotiable safety invariants
+
+<safety>
+1. **Runtime state is the only source of truth.** A hypothesis without an
+   observed value is a guess. Do not fix guesses.
+2. **Every debug artifact is journaled before it is created.** Journal-then-modify,
+   not modify-then-remember-maybe. The `.debug-journal.md` is the single record
+   that makes a clean revert possible.
+3. **Never ship a fix without a failing-first test.** Red→green transition
+   required, or the fix is unverified.
+4. **Never declare done on type-check/compile alone.** Types catch declaration
+   bugs. Only running the actual user scenario catches the actual user bug.
+5. **Never ask the user a question that runtime evidence can already answer.**
+   Escalation is for genuine ambiguity.
+6. **Never silently swallow errors while debugging.** If the system swallows
+   errors, that is often the bug itself. Make them loud temporarily; restore at
+   cleanup.
+7. **Never `git commit` from inside this skill.** Commits belong after the user
+   confirms the fix.
+8. **Never attach without having read the runtime reference.** The gate rule.
+</safety>
+
+---
+
 ## Evidence
 
 Record:
@@ -68,3 +190,18 @@ Record:
 - regression test
 - passing command and output
 - manual QA artifact and cleanup
+
+---
+
+## What to do right now
+
+1. Read the user's bug description.
+2. Identify the runtime.
+3. **Open `references/runtimes/<runtime>.md`.** Read it.
+4. Identify which specialist tools apply. **Open each matching
+   `references/tools/*.md`.** Read them.
+5. Open [references/methodology/00-setup.md](references/methodology/00-setup.md)
+   and start Phase 0.
+6. Follow the phase loop. Read each methodology reference as you enter the phase.
+
+**The references are the skill. This file is an index.**

package/plugins/litclaude/skills/lit-loop/SKILL.md

@@ -37,6 +37,22 @@ Before implementation:
 7. Reread stale state before action: plans, handoffs, package metadata,
    registry facts, test output, and resumed ledgers can drift between turns.
 
+## Tier the Effort (LIGHT vs HEAVY)
+
+Classify the task once at bootstrap, then size the process to match. Ratchet
+**up** only — never downgrade a HEAVY task mid-flight to save effort.
+
+- **LIGHT** — isolated, additive, low-blast-radius (a new pure helper, a typo,
+  a docs line, a single local test). One success criterion and one Manual-QA
+  channel are enough; skip the heavier waves.
+- **HEAVY** — trigger on any of: changes to existing behavior, security- or
+  auth-sensitive surfaces, release-facing or published artifacts, multi-file or
+  multi-subsystem edits, concurrency/locking, data migrations, or anything you
+  cannot fully revert. Run the full criteria set, the adversarial classes, the
+  reviewer gate, and (when broad/parallel) Dynamic workflow delegation.
+
+When uncertain, treat the task as HEAVY.
+
 ## Native Goal + Dynamic Workflow
 
 Claude Code's `/goal` (v2.1.139+) is a **user-typed slash command** that sets an autonomous
@@ -52,9 +68,13 @@ model-facing goal tools today. Bind goals like this:
 - While model-facing goal tools are not exposed (the case today), the local litgoal ledger is the
   durable record; surface the `/goal` proposal for long-running goals and don't spam fallback status.
 
-Dynamic workflow orchestration is mandatory for broad, risky, parallel, or
-long-running work: call `Workflow` when exposed instead of merely mentioning it.
-Dynamic worktree isolation is mandatory for risky edit lanes: call
+Dynamic workflow orchestration is the right tool for broad, risky, parallel, or
+long-running work: briefly **propose a Dynamic workflow and call `Workflow`
+once the user opts in** (or when the session already permits orchestration)
+instead of merely mentioning it. The `Workflow` tool can fan out many subagents
+and spend a large token budget, so it needs explicit user opt-in — this opt-in
+gate, not a host limitation, is why a Dynamic workflow only starts after you
+offer it. Dynamic worktree isolation is mandatory for risky edit lanes: call
 `EnterWorktree` when exposed. If only the CLI surface is available, use or
 recommend `claude --worktree <short-name> --tmux`.