litclaude-ai 0.3.7 → 0.3.9

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

@@ -1,7 +1,7 @@
 {
   "name": "litclaude",
   "description": "Claude Code-native workflow plugin.",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "author": {
     "name": "LitClaude contributors"
   },
@@ -11,12 +11,12 @@
   "keywords": ["claude-code", "hooks", "skills", "agents", "lsp", "workflow"],
   "skills": "./skills",
   "agents": [
+    "./agents/prometheus-planner.md",
     "./agents/boulder-executor.md",
-    "./agents/librarian-researcher.md",
     "./agents/oracle-verifier.md",
-    "./agents/prometheus-planner.md",
     "./agents/qa-runner.md",
-    "./agents/quality-reviewer.md"
+    "./agents/quality-reviewer.md",
+    "./agents/librarian-researcher.md"
   ],
   "mcpServers": "./.mcp.json",
   "lspServers": "./.lsp.json",

package/plugins/litclaude/agents/boulder-executor.md

@@ -8,5 +8,8 @@ skills:
   - programming
 ---
 
-Execute only the assigned plan checkbox. Write the failing test first, make the
-smallest change, run verification, capture evidence, and report cleanup.
+Execute only the assigned approved plan checkbox. Do not redesign, rescope, or
+replace the approved plan unless evidence proves a blocker or stale state. Write
+the failing test first, make the smallest change, run verification, capture
+real-surface evidence, and report cleanup. Your DoneClaim must name changed
+files, exact tests, real-surface evidence, risks, and cleanup receipt.

package/plugins/litclaude/agents/prometheus-planner.md

@@ -10,4 +10,6 @@ skills:
 
 You are Prometheus, the planning agent. Explore first, ask only preference
 questions, and write plans with concrete acceptance criteria and QA scenarios.
-Do not implement product changes.
+This is a planning-only role: must not implement product changes, do not run
+mutating commands, and do not start execution. After approval, hand off through
+`/start-work` or `/litclaude:start-work`.

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

@@ -43,35 +43,139 @@ const writeContext = (additionalContext, systemMessage) => {
   );
 };
 
-const workflowTriggers = [
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)deep-interview(?=$|[^\w-])/u, command: "/litclaude:deep-interview", skill: "Skill(deep-interview)", discipline: "deep-interview" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)dynamic-workflow(?=$|[^\w-])/u, command: "/litclaude:dynamic-workflow", skill: "Skill(lit-loop)", discipline: "dynamic-workflow" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)lit-plan(?=$|[^\w-])/u, command: "/litclaude:lit-plan", skill: "Skill(lit-plan)", discipline: "lit-plan" },
-  { pattern: /(?:^|\s)(?:\$|\/(?:litclaude:)?)lit-loop(?=$|[^\w-])/u, command: "/litclaude:lit-loop", skill: "Skill(lit-loop)", discipline: "lit-loop" },
-  { 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 },
+const plainWordBoundary = /^[A-Za-z0-9]$/u;
+const compoundWordBoundary = /^[A-Za-z0-9_-]$/u;
+
+const triggerByToken = {
+  "deep-interview": { command: "/litclaude:deep-interview", skill: "Skill(deep-interview)", discipline: "deep-interview" },
+  "dynamic-workflow": { command: "/litclaude:dynamic-workflow", skill: "Skill(lit-loop)", discipline: "dynamic-workflow" },
+  "lit-plan": { command: "/litclaude:lit-plan", skill: "Skill(lit-plan)", discipline: "lit-plan" },
+  "lit-loop": { command: "/litclaude:lit-loop", skill: "Skill(lit-loop)", discipline: "lit-loop" },
+  "start-work": { command: "/litclaude:start-work", skill: "Skill(start-work)", discipline: "start-work" },
+  "review-work": { command: "/litclaude:review-work", skill: "Skill(review-work)", discipline: "review-work" },
+  litgoal: { command: "/litclaude:litgoal", skill: "Skill(litgoal)", discipline: "litgoal" },
+  litresearch: { command: "/litclaude:litresearch", skill: "Skill(litresearch)", discipline: "litresearch" },
+};
+
+const modeContracts = {
+  "lit-loop": "Mode contract: lit-loop is a durable, evidence-driven execution loop. Define checkable success criteria before coding, use RED->GREEN tests, pair tests with real-surface evidence, checkpoint progress, and stop only when verified done or BLOCKED.",
+  "lit-plan": "Mode contract: lit-plan is planning-only. Do not edit files, run mutating commands, call start-work tooling, or implement. Explore read-only, produce an approval-gated plan, then tell the user to run `/start-work` or `/litclaude:start-work` for execution.",
+  "start-work": "Mode contract: start-work is execution-only for an approved plan. Natural-language activation cannot switch Claude Code agents, so this hook must hand off safely instead of pretending execution started.",
+  "review-work": "Mode contract: review-work runs a five-lane review: goal/constraints, real-surface QA, code quality, security, and docs/package/context readiness. PASS requires evidence from every applicable lane.",
+  litresearch: "Mode contract: litresearch uses sourced evidence, separates verified facts from hypotheses, cites the search/runtime surface used, and reports residual uncertainty.",
+  litgoal: "Mode contract: litgoal binds one outcome-shaped objective plus checkable criteria, each with scenario, real surface, and observable evidence.",
+  "deep-interview": "Mode contract: deep-interview clarifies vague requirements before planning or implementation, without inventing acceptance criteria.",
+  "dynamic-workflow": "Mode contract: dynamic-workflow is opt-in orchestration for broad, risky, parallel, or long-running work; propose it first and only call Workflow after user opt-in or existing session permission.",
+};
+
+const withoutCode = (text) => text.replace(/```[\s\S]*?```/gu, " ").replace(/`[^`]*`/gu, " ");
+const rawTriggerText = (text) => withoutCode(text).toLowerCase();
+const normalizedTriggerText = (text) => rawTriggerText(text).replace(/[_-]+/gu, " ");
+
+const isPlainWordBoundary = (value) => value === undefined || !plainWordBoundary.test(value);
+const isCompoundWordBoundary = (value) => value === undefined || !compoundWordBoundary.test(value);
+
+const containsPlainWord = (text, word) => {
+  for (let index = 0; index < text.length; index += 1) {
+    if (!text.startsWith(word, index)) continue;
+    const previous = index === 0 ? undefined : text[index - 1];
+    const next = text[index + word.length];
+    if (isPlainWordBoundary(previous) && isPlainWordBoundary(next)) return true;
+  }
+  return false;
+};
+
+const containsCompoundBoundedWord = (text, word) => {
+  for (let index = 0; index < text.length; index += 1) {
+    if (!text.startsWith(word, index)) continue;
+    const previous = index === 0 ? undefined : text[index - 1];
+    const next = text[index + word.length];
+    if (isCompoundWordBoundary(previous) && isCompoundWordBoundary(next)) return true;
+  }
+  return false;
+};
+
+const slashCommandMentions = [
+  "/deep-interview",
+  "/dynamic-workflow",
+  "/goal",
+  "/lit-loop",
+  "/lit-plan",
+  "/litclaude:deep-interview",
+  "/litclaude:dynamic-workflow",
+  "/litclaude:lit-loop",
+  "/litclaude:lit-plan",
+  "/litclaude:litgoal",
+  "/litclaude:litresearch",
+  "/litclaude:review-work",
+  "/litclaude:start-work",
+  "/litgoal",
+  "/litresearch",
+  "/review-work",
+  "/start-work",
 ];
 
-const findWorkflowTrigger = (prompt) => workflowTriggers.find((trigger) => trigger.pattern.test(prompt));
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+
+const slashCommandMentionPattern = new RegExp(
+  `(^|\\s)(?:${slashCommandMentions.map(escapeRegExp).join("|")})(?=$|[\\s.,;:!?)}\\]])`,
+  "u",
+);
+
+const containsSlashCommandMention = (text) => slashCommandMentionPattern.test(text);
+
+const findDollarCommandTrigger = (raw) => {
+  const match = /(?:^|\s)\$(deep-interview|dynamic-workflow|lit-plan|lit-loop|start-work|review-work|litgoal|litresearch)(?=$|[^\w-])/u.exec(raw);
+  if (!match) return undefined;
+  return { ...triggerByToken[match[1]], source: "dollar-command" };
+};
+
+const hasLitTrigger = (raw) => containsCompoundBoundedWord(raw, "lit") || containsCompoundBoundedWord(raw, "litwork");
+
+const findNaturalLitTrigger = (prompt) => {
+  const raw = rawTriggerText(prompt);
+  if (containsSlashCommandMention(raw)) return undefined;
+  if (!hasLitTrigger(raw)) return undefined;
+
+  const normalized = normalizedTriggerText(prompt);
+  if (containsPlainWord(normalized, "review")) return { ...triggerByToken["review-work"], source: "natural-language" };
+  if (containsPlainWord(normalized, "start") && containsPlainWord(normalized, "work")) {
+    return { ...triggerByToken["start-work"], source: "natural-language", safetyBlock: true };
+  }
+  if (containsPlainWord(normalized, "research")) return { ...triggerByToken.litresearch, source: "natural-language" };
+  if (containsPlainWord(normalized, "goal")) return { ...triggerByToken.litgoal, source: "natural-language" };
+  if (containsPlainWord(normalized, "plan")) return { ...triggerByToken["lit-plan"], source: "natural-language" };
+  return { ...triggerByToken["lit-loop"], source: "natural-language", softConfirm: true };
+};
+
+const findWorkflowTrigger = (prompt) => {
+  const raw = rawTriggerText(prompt);
+  const dollarTrigger = findDollarCommandTrigger(raw);
+  if (dollarTrigger) return dollarTrigger;
+  if (containsSlashCommandMention(raw)) return undefined;
+  return findNaturalLitTrigger(prompt);
+};
 
 const isDiagnosticLiteralPrompt = (prompt) =>
   /\bdiagnostic\b/iu.test(prompt)
   && /do not inspect or modify files/iu.test(prompt)
   && /reply with exactly one line/iu.test(prompt);
 
-const litworkContext = ({ command, skill, discipline, softConfirm }) => [
+const litworkContext = ({ command, skill, discipline, softConfirm, safetyBlock, source }) => [
+  ...(safetyBlock
+    ? ["BLOCKED: Natural-language start-work activation cannot switch the active Claude Code agent. Run `/start-work` (or `/litclaude:start-work`) with the approved plan so Claude Code can use the correct execution surface; do not continue implementation from this prompt hook."]
+    : []),
   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.`,
+  modeContracts[discipline],
+  `Activation source: ${source ?? "legacy"}. Slash commands and slash-command mentions are handled by Claude Code's native command surface and do not activate this prompt hook. Code spans, code fences, substrings, and compound tokens are ignored. Secret-bearing prompt material is never persisted raw; record only redacted summaries and evidence paths in durable state.`,
   "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.",

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/lit-plan.md

@@ -6,6 +6,11 @@ argument-hint: '<planning brief>'
 Use the `lit-plan` skill for the user's current planning brief or command
 arguments.
 
+This command is planning-only. Do not implement, edit files for product
+changes, run mutating commands, or call start-work tooling from the planning
+surface. End with an approval gate and instruct the user to run `/start-work` or
+`/litclaude:start-work` after approval.
+
 The plan must include Claude Code-native bootstrap steps:
 
 - If model-facing goal tools are exposed, use `get_goal`, `create_goal`, and

package/plugins/litclaude/commands/litgoal.md

@@ -6,6 +6,10 @@ argument-hint: '<goal operation>'
 Use the `litgoal` skill for the user's current goal operation or command
 arguments.
 
+Shape the goal as one outcome-focused objective plus checkable criteria. Each
+criterion needs a scenario, a real surface, and observable evidence before it is
+complete.
+
 Prefer the package CLI for durable local state:
 `litclaude-ai litgoal create-goals`, `status`, `criteria`,
 `record-evidence`, `checkpoint`, `steer`, and `record-review-blockers`.

package/plugins/litclaude/commands/litresearch.md

@@ -6,6 +6,9 @@ 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.
+Separate sourced evidence from hypotheses, verify contested claims before
+synthesis, and report residual uncertainty rather than collapsing unknowns into
+facts.
 
 Before fanning out, bootstrap Claude Code-native research state:
 

package/plugins/litclaude/commands/review-work.md

@@ -7,7 +7,7 @@ Use the `review-work` skill for the user's current scope or command arguments.
 
 Run the 5-lane review contract: goal and constraint verification
 (goal/constraint), hands-on QA execution, code quality review, security review,
-and local-first context mining.
+and docs/package/context readiness through local-first context mining.
 Aggregate findings into a PASS, FAIL, or NEEDS-CONTEXT verdict, and cite the
 evidence used for every lane.
 Manual-QA channels must leave artifacts, cleanup receipt paths, and bounded

package/plugins/litclaude/commands/start-work.md

@@ -6,6 +6,11 @@ argument-hint: '<plan-file>'
 Use the `start-work` skill for the user's current plan file or command
 arguments.
 
+This command is the Claude Code-native execution transition for an approved
+plan. If a user reached start-work through natural language (`lit start work`),
+do not pretend the hook switched modes; require this slash command or the
+namespaced `/litclaude:start-work` equivalent before execution.
+
 Before the first checkbox, bootstrap Claude Code-native workflow state:
 
 - Use `get_goal` and `create_goal` only if model-facing goal tools are exposed.

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

@@ -21,6 +21,10 @@ success criteria before editing. Keep decisions, evidence, cleanup receipts,
 and remaining work in a durable notepad, plan, or ledger when the task spans
 multiple steps.
 
+This is a durable, evidence-driven execution loop. tests are necessary but not
+sufficient: every done claim needs the matching real Claude Code/package/user
+surface artifact, not just a green suite.
+
 ## Bootstrap
 
 Before implementation:
@@ -37,6 +41,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 +72,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`.