@xaccefy/pi-casefile 0.6.2 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaccefy/pi-casefile",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Offensive security case tracker for Pi Agent — bug bounties, CTFs, security audits",
   "keywords": [
     "pi-package",
@@ -35,6 +35,7 @@
     "src/ledger.ts",
     "src/workflow.ts",
     "src/poc-runner.ts",
+    "src/scratchpad.ts",
     "src/sqlite-compat/index.ts",
     "skills",
     "README.md",

package/src/index.ts

@@ -1,13 +1,12 @@
 /**
  * Casefile — offensive security case tracker for Pi.
  *
- * Tools: CaseAdd, CaseUpdate, PromoteFinding, CaseGet, CaseList, CaseSearch, CaseLink, CaseUnlink, CaseReport
+ * Tools: CaseAdd, CaseUpdate, PromoteFinding, CaseGet, CaseList, CaseSearch, CaseLink, CaseUnlink, CaseReport, ScratchpadInit, ScratchpadResume, ScratchpadCheckpoint, ScratchpadWrite, ScratchpadRead, ScratchpadPhaseDone, ScratchpadClear
  * Command: /casefile — interactive dashboard
  * Event: before_agent_start — injects cyber workflow (+ active case list) once per user prompt
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
@@ -46,6 +45,17 @@ import {
   writeCaseReport,
 } from "./ledger.ts";
 import { type PocRun, runPoc } from "./poc-runner.ts";
+import {
+  type ScratchpadPhase,
+  type ScratchpadResume,
+  scratchpad_checkpoint,
+  scratchpad_clear,
+  scratchpad_init,
+  scratchpad_phase_done,
+  scratchpad_read,
+  scratchpad_resume,
+  scratchpad_write,
+} from "./scratchpad.ts";
 import { STATIC_CYBER_WORKFLOW } from "./workflow.ts";
 
 // ── Schemas ───────────────────────────────────────────────────────────
@@ -111,6 +121,11 @@ const PromoteSchema = Type.Object(
     poc_path: Type.String({
       description: "Absolute path to the PoC script on disk",
     }),
+    verification_marker: Type.String({
+      minLength: 1,
+      description:
+        "A unique string the PoC must print to stdout to prove exploitation actually occurred. The gate checks the PoC output contains this marker — exit code 0 alone is NOT sufficient. The marker should be specific to the finding (e.g. 'VULN_CONFIRMED_<case-id>') and only printed after the PoC has verified the exploit worked (e.g. after extracting data, receiving a callback, seeing the payload reflected). This prevents fluke exit 0 and mocked PoCs from passing the gate.",
+    }),
     disconfirmation_path: Type.Optional(
       Type.String({
         description:
@@ -216,6 +231,95 @@ const ReportSchema = Type.Object(
   { additionalProperties: false },
 );
 
+// ── Tool: Scratchpad ─────────────────────────────────────────────────
+//
+// The scratchpad is the pipeline's crash-recoverable artifact store.
+// The casefile owns state transitions; the scratchpad owns artifacts
+// (recon maps, trace outputs, verification logs). Resume re-reads
+// artifacts; it does not re-run completed phases (idempotent).
+
+const SCRATCHPAD_PHASES = [
+  "recon",
+  "hunt",
+  "gapfil",
+  "trace",
+  "skeptic",
+  "validate",
+  "chain",
+  "patch",
+  "report",
+] as const;
+
+const ScratchpadPhaseSchema = Type.String({
+  enum: [...SCRATCHPAD_PHASES],
+  description:
+    "Pipeline phase: recon | hunt | gapfil | trace | skeptic | validate | chain | patch | report",
+});
+
+const ScratchpadInitSchema = Type.Object(
+  {
+    run_id: Type.String({ description: "Unique run identifier for this pipeline run" }),
+  },
+  { additionalProperties: false },
+);
+
+const ScratchpadResumeSchema = Type.Object(
+  {
+    run_id: Type.String({ description: "Run identifier to resume" }),
+  },
+  { additionalProperties: false },
+);
+
+const ScratchpadCheckpointSchema = Type.Object(
+  {
+    run_id: Type.String({ description: "Run identifier" }),
+    phase: ScratchpadPhaseSchema,
+    ids: Type.Optional(
+      Type.Array(Type.String(), {
+        description: "Key IDs produced by this phase (case IDs, finding IDs)",
+      }),
+    ),
+    summary: Type.Optional(Type.String({ description: "One-line summary of phase completion" })),
+  },
+  { additionalProperties: false },
+);
+
+const ScratchpadWriteSchema = Type.Object(
+  {
+    run_id: Type.String({ description: "Run identifier" }),
+    phase: ScratchpadPhaseSchema,
+    artifact_name: Type.String({
+      description: "Artifact filename (sanitized; path traversal is blocked)",
+    }),
+    content: Type.String({ description: "Artifact content to write" }),
+  },
+  { additionalProperties: false },
+);
+
+const ScratchpadReadSchema = Type.Object(
+  {
+    run_id: Type.String({ description: "Run identifier" }),
+    phase: ScratchpadPhaseSchema,
+    artifact_name: Type.String({ description: "Artifact filename to read" }),
+  },
+  { additionalProperties: false },
+);
+
+const ScratchpadPhaseDoneSchema = Type.Object(
+  {
+    run_id: Type.String({ description: "Run identifier" }),
+    phase: ScratchpadPhaseSchema,
+  },
+  { additionalProperties: false },
+);
+
+const ScratchpadClearSchema = Type.Object(
+  {
+    run_id: Type.String({ description: "Run identifier to clear (deletes that run only)" }),
+  },
+  { additionalProperties: false },
+);
+
 interface Theme {
   fg(color: string, text: string): string;
   bold(text: string): string;
@@ -322,9 +426,7 @@ class CasefileDashboard {
 
     if (this.records.length === 0) {
       lines.push("");
-      lines.push(
-        `  ${th.fg("dim", "No active security cases. Ask the agent to CaseAdd findings!")}`,
-      );
+      lines.push(`  ${th.fg("dim", "No security cases yet. Ask the agent to CaseAdd findings!")}`);
     } else {
       lines.push("");
       for (const r of this.records) {
@@ -427,11 +529,7 @@ export const XP_MODE_ENV = "PI_XP_MODE";
 export type XpMode = "on" | "off";
 
 export function getXpModeStatePath(): string {
-  try {
-    return join(dirname(getCasefilePath()), "xp-mode");
-  } catch {
-    return join(homedir(), ".pi", "xp-mode");
-  }
+  return join(dirname(getCasefilePath()), "xp-mode");
 }
 
 export function readXpMode(
@@ -631,13 +729,14 @@ export default function casefileExtension(pi: ExtensionAPI) {
     name: "PromoteFinding",
     label: "Promote Finding",
     description:
-      "Run an on-disk PoC script (Docker sandbox or local) and, on exit 0, promote an investigating case to confirmed. Optionally run a disconfirmation script that must exit non-0 (finding survived the attempt to disprove).",
+      "Run an on-disk PoC script (Docker sandbox or local) and, on exit 0 + verification marker present in output, promote an investigating case to confirmed. The verification_marker proves the exploit actually worked — exit code 0 alone is NOT sufficient. Optionally run a disconfirmation script that must exit non-0 (finding survived the attempt to disprove).",
     promptSnippet: "Run a PoC and promote an investigating case to confirmed",
     promptGuidelines: [
       "Use PromoteFinding when an investigating case has a concrete PoC script on disk and you are ready to prove it.",
       "The case must already have status='investigating' and non-empty poc, evidence, impact, severity, target, and disconfirmation fields.",
       "By default, the PoC runs in `docker run --rm --network none`. Use local:true to run on the host (e.g. for network-dependent bugs).",
-      "Only exit code 0 promotes the case to confirmed.",
+      "Promotion requires BOTH exit code 0 AND the verification_marker appearing in the PoC output. The marker is a string you choose (e.g. 'VULN_CONFIRMED_<case-id>') that the PoC prints ONLY after it has verified the exploit worked — after extracting data, receiving a callback, seeing the payload reflected, etc. Do NOT print the marker unconditionally or before the exploit check.",
+      "The marker check prevents fluke exit 0 (script crashed before real logic) and mocked PoCs (script ran but didn't actually exploit the target) from passing the gate.",
       "Optionally provide disconfirmation_path to a script that tries to disprove the finding. If the disconfirmation script exits 0, the finding is considered disproven and promotion is blocked.",
       "Do not use CaseUpdate to set status='confirmed' directly — it is rejected. Always use PromoteFinding.",
     ],
@@ -648,6 +747,26 @@ export default function casefileExtension(pi: ExtensionAPI) {
       // 30s (plus first-time image pull), so fail cheap when the case can't
       // advance anyway (missing, wrong status, missing required fields).
       assertPromotable(params.id as string);
+
+      // Reject empty/whitespace markers BEFORE any PoC run — it's a param
+      // error, so fail cheap instead of burning a (up to 30s) sandboxed run.
+      const marker = (params.verification_marker as string | undefined)?.trim();
+      if (!marker) {
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                "verification_marker is empty or whitespace. " +
+                "A non-empty marker printed only AFTER the PoC confirms exploitation is required — " +
+                "exit code 0 alone is not sufficient. Case remains investigating.",
+            },
+          ],
+          isError: true,
+          details: { record: getCaseById(params.id as string) },
+        };
+      }
+
       const run = runPoc(params.poc_path as string, params.local !== true);
 
       // Fail closed without throwing: non-zero PoC must leave the case investigating.
@@ -665,6 +784,28 @@ export default function casefileExtension(pi: ExtensionAPI) {
         };
       }
 
+      // Verification marker check: exit code 0 alone is NOT sufficient.
+      // The PoC must print the verification_marker to stdout, proving the
+      // exploit actually worked — not just that the script ran. This blocks
+      // fluke exit 0 (crash before real logic) and mocked PoCs that don't
+      // actually exploit the target.
+      if (!(run.output ?? "").includes(marker)) {
+        const record = getCaseById(params.id as string);
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `PoC exited 0 but the verification marker "${marker}" was NOT found in the output.\n` +
+                `This means the script ran but did not prove exploitation. The marker must be printed only AFTER the PoC verifies the exploit worked (data extracted, callback received, payload reflected, etc.).\n` +
+                `Do not print the marker unconditionally — print it only when the exploit is confirmed.\n\nOutput:\n${run.output}`,
+            },
+          ],
+          isError: true,
+          details: { record, run, markerMissing: true },
+        };
+      }
+
       // Run disconfirmation script if provided — must exit NON-0 (finding survived the attempt to disprove).
       let disconfirmationRun: PocRun | undefined;
       if (params.disconfirmation_path) {
@@ -1012,7 +1153,7 @@ export default function casefileExtension(pi: ExtensionAPI) {
     name: "CaseReport",
     label: "Write Case Report",
     description:
-      "Generate a markdown report from a confirmed or reported case under the project report directory. Hypothesis/investigating/blocked/killed cases are rejected — promote to confirmed first.",
+      "Generate a markdown report from a confirmed or reported case under the casefile report directory (next to the casefile DB). Hypothesis/investigating/blocked/killed cases are rejected — promote to confirmed first.",
     promptSnippet: "Generate a bounty-style markdown report from a case",
     promptGuidelines: [
       "Use CaseReport only for confirmed or already reported cases. Keep hypotheses and investigating cases in the ledger until proof is captured.",
@@ -1066,6 +1207,362 @@ export default function casefileExtension(pi: ExtensionAPI) {
     },
   });
 
+  // ── Tool: ScratchpadInit ──
+
+  pi.registerTool({
+    name: "ScratchpadInit",
+    label: "Init Scratchpad",
+    description:
+      "Initialize a crash-recoverable artifact store for a pipeline run. Creates the directory structure and an initial state.json checkpoint. Idempotent — safe to call on resume without --fresh; returns the existing checkpoint if the run already exists.",
+    promptSnippet: "Initialize the pipeline artifact store for a run",
+    promptGuidelines: [
+      "Call ScratchpadInit once at the start of a pipeline run (or on resume before ScratchpadResume).",
+      "The run_id is arbitrary but should be unique per pipeline run — typically <target>-<timestamp>.",
+      "On resume, ScratchpadInit returns the existing checkpoint without wiping it; pair with ScratchpadResume to skip completed phases.",
+    ],
+    parameters: ScratchpadInitSchema,
+
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      const cp = scratchpad_init(params.run_id as string);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Scratchpad initialized for run ${cp.run_id}.\nCompleted phases: ${cp.completed_phases.length ? cp.completed_phases.join(", ") : "none"}`,
+          },
+        ],
+        details: { checkpoint: cp },
+      };
+    },
+
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("ScratchpadInit ")) +
+          theme.fg("dim", (args.run_id as string) ?? ""),
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, _opts, theme) {
+      const cp = (result.details as { checkpoint: { run_id: string } } | undefined)?.checkpoint;
+      return new Text(`${theme.fg("success", "✓ ")}ScratchpadInit ${cp?.run_id ?? ""}`, 0, 0);
+    },
+  });
+
+  // ── Tool: ScratchpadResume ──
+
+  pi.registerTool({
+    name: "ScratchpadResume",
+    label: "Resume Scratchpad",
+    description:
+      "Read the checkpoint and artifact listing for a pipeline run to decide where to resume. Returns the next phase to run (or null if done) and which phases already completed. Returns null if the run does not exist.",
+    promptSnippet: "Check pipeline resume state — which phases are done",
+    promptGuidelines: [
+      "Call ScratchpadResume at pipeline start to determine where to resume. If it returns a checkpoint, skip completed phases (check ScratchpadPhaseDone before each dispatch) and continue from next_phase.",
+      "If ScratchpadResume returns null, the run has no checkpoint — call ScratchpadInit to start fresh.",
+      "Use ScratchpadPhaseDone before dispatching each stage to avoid re-running completed phases (idempotent resume).",
+    ],
+    parameters: ScratchpadResumeSchema,
+
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      const resume = scratchpad_resume(params.run_id as string);
+      if (!resume) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No scratchpad found for run ${params.run_id}. Call ScratchpadInit to start a new run.`,
+            },
+          ],
+          details: { resume: null },
+        };
+      }
+      const cp = resume.checkpoint;
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `Resume run ${cp.run_id}:\n` +
+              `Completed phases: ${cp.completed_phases.length ? cp.completed_phases.join(", ") : "none"}\n` +
+              `Next phase: ${resume.next_phase ?? "none (run is done)"}`,
+          },
+        ],
+        details: { resume },
+      };
+    },
+
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("ScratchpadResume ")) +
+          theme.fg("dim", (args.run_id as string) ?? ""),
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, _opts, theme) {
+      const resume = (result.details as { resume: ScratchpadResume | null } | undefined)?.resume;
+      if (!resume) return new Text(theme.fg("warning", "↷ ScratchpadResume — no run found"), 0, 0);
+      return new Text(
+        theme.fg("success", "✓ ") +
+          `ScratchpadResume ${resume.checkpoint.run_id} → next: ${resume.next_phase ?? "done"}`,
+        0,
+        0,
+      );
+    },
+  });
+
+  // ── Tool: ScratchpadCheckpoint ──
+
+  pi.registerTool({
+    name: "ScratchpadCheckpoint",
+    label: "Checkpoint Phase",
+    description:
+      "Mark a pipeline phase as complete in the scratchpad state.json. Records the completion timestamp, key IDs, and an optional summary. Idempotent — re-checkpointing a phase overwrites its summary/IDs without duplicating the completed_phases entry.",
+    promptSnippet: "Record a pipeline phase as complete",
+    promptGuidelines: [
+      "Call ScratchpadCheckpoint after every phase completes: ScratchpadCheckpoint(run_id, phase, { ids, summary }).",
+      "ids are the key case/finding IDs the phase produced — used by resume to reconstruct state.",
+      "Keep completed_phases in pipeline order; the checkpoint sorts automatically.",
+    ],
+    parameters: ScratchpadCheckpointSchema,
+
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      const cp = scratchpad_checkpoint(params.run_id as string, params.phase as ScratchpadPhase, {
+        ids: params.ids as string[] | undefined,
+        summary: params.summary as string | undefined,
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `Phase ${params.phase} checkpointed for run ${cp.run_id}.\n` +
+              `Completed phases: ${cp.completed_phases.join(", ")}`,
+          },
+        ],
+        details: { checkpoint: cp },
+      };
+    },
+
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("ScratchpadCheckpoint ")) +
+          theme.fg("dim", `${args.run_id ?? ""} ${args.phase ?? ""}`),
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, _opts, theme) {
+      const cp = (
+        result.details as { checkpoint: { run_id: string; completed_phases: string[] } } | undefined
+      )?.checkpoint;
+      return new Text(
+        theme.fg("success", "✓ ") +
+          `ScratchpadCheckpoint ${cp?.run_id ?? ""} — ${cp?.completed_phases.length ?? 0} phases done`,
+        0,
+        0,
+      );
+    },
+  });
+
+  // ── Tool: ScratchpadWrite ──
+
+  pi.registerTool({
+    name: "ScratchpadWrite",
+    label: "Write Artifact",
+    description:
+      "Write an intermediate artifact (recon map, trace output, verification log) to a phase's subdirectory in the scratchpad. Overwrites if the name exists. Artifact names are sanitized — path traversal is blocked.",
+    promptSnippet: "Save a pipeline artifact to the scratchpad",
+    promptGuidelines: [
+      "Agents write artifacts to the scratchpad, not to each other's output files (prevents an echo chamber).",
+      "The casefile owns state transitions; the scratchpad owns artifacts. Use ScratchpadWrite for bulky intermediate outputs, not CaseUpdate.",
+    ],
+    parameters: ScratchpadWriteSchema,
+
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      const path = scratchpad_write(
+        params.run_id as string,
+        params.phase as ScratchpadPhase,
+        params.artifact_name as string,
+        params.content as string,
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Artifact written: ${params.artifact_name} → ${path}`,
+          },
+        ],
+        details: { path, artifact_name: params.artifact_name },
+      };
+    },
+
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("ScratchpadWrite ")) +
+          theme.fg("dim", `${args.run_id ?? ""}/${args.phase ?? ""}/${args.artifact_name ?? ""}`),
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, _opts, theme) {
+      const name = (result.details as { artifact_name?: string } | undefined)?.artifact_name;
+      return new Text(theme.fg("success", `✓ ScratchpadWrite ${name ?? ""}`), 0, 0);
+    },
+  });
+
+  // ── Tool: ScratchpadRead ──
+
+  pi.registerTool({
+    name: "ScratchpadRead",
+    label: "Read Artifact",
+    description:
+      "Read an artifact from a phase's subdirectory in the scratchpad. Returns null if the artifact is missing. Use to resume a phase from a prior run's intermediate output.",
+    promptSnippet: "Read a pipeline artifact from the scratchpad",
+    promptGuidelines: [
+      "On resume, ScratchpadRead retrieves a prior phase's intermediate output so the next phase can proceed without re-running it.",
+      "Returns null for missing artifacts — treat as 'not yet produced' rather than an error.",
+    ],
+    parameters: ScratchpadReadSchema,
+
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      const content = scratchpad_read(
+        params.run_id as string,
+        params.phase as ScratchpadPhase,
+        params.artifact_name as string,
+      );
+      if (content === null) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Artifact not found: ${params.artifact_name} in ${params.phase}/`,
+            },
+          ],
+          details: { artifact_name: params.artifact_name, found: false },
+        };
+      }
+      return {
+        content: [{ type: "text", text: content }],
+        details: { artifact_name: params.artifact_name, found: true, length: content.length },
+      };
+    },
+
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("ScratchpadRead ")) +
+          theme.fg("dim", `${args.run_id ?? ""}/${args.phase ?? ""}/${args.artifact_name ?? ""}`),
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, _opts, theme) {
+      const found = (result.details as { found?: boolean } | undefined)?.found;
+      return new Text(
+        found
+          ? theme.fg("success", "✓ ScratchpadRead")
+          : theme.fg("warning", "↷ ScratchpadRead — not found"),
+        0,
+        0,
+      );
+    },
+  });
+
+  // ── Tool: ScratchpadPhaseDone ──
+
+  pi.registerTool({
+    name: "ScratchpadPhaseDone",
+    label: "Phase Done?",
+    description:
+      "Check whether a phase has already been checkpointed in the scratchpad — for idempotent re-run. Returns true if the phase is complete; skip re-dispatching it on resume.",
+    promptSnippet: "Check if a pipeline phase is already complete",
+    promptGuidelines: [
+      "Call ScratchpadPhaseDone before dispatching each stage to avoid re-running completed phases on resume.",
+      "A completed phase with a checkpoint is a no-op on re-run — skip it and continue to the next incomplete phase.",
+    ],
+    parameters: ScratchpadPhaseDoneSchema,
+
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      const done = scratchpad_phase_done(params.run_id as string, params.phase as ScratchpadPhase);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Phase ${params.phase} for run ${params.run_id}: ${done ? "DONE (skip on resume)" : "not done"}`,
+          },
+        ],
+        details: { phase: params.phase, done },
+      };
+    },
+
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("ScratchpadPhaseDone ")) +
+          theme.fg("dim", `${args.run_id ?? ""} ${args.phase ?? ""}`),
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, _opts, theme) {
+      const done = (result.details as { done?: boolean } | undefined)?.done;
+      return new Text(
+        done
+          ? theme.fg("success", "✓ ScratchpadPhaseDone — done")
+          : theme.fg("warning", "↷ ScratchpadPhaseDone — not done"),
+        0,
+        0,
+      );
+    },
+  });
+
+  // ── Tool: ScratchpadClear ──
+
+  pi.registerTool({
+    name: "ScratchpadClear",
+    label: "Clear Run",
+    description:
+      "Clear a single pipeline run's scratchpad directory. Used by --fresh for one run. Does not touch other runs. The run must be re-initialized with ScratchpadInit afterward.",
+    promptSnippet: "Clear one pipeline run's artifacts",
+    promptGuidelines: [
+      "Use ScratchpadClear to force a fresh start for a single run (--fresh). It deletes that run's directory only.",
+      "After clearing, call ScratchpadInit to recreate the directory structure before writing artifacts.",
+    ],
+    parameters: ScratchpadClearSchema,
+
+    async execute(_id, params, _signal, _onUpdate, _ctx) {
+      scratchpad_clear(params.run_id as string);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Scratchpad cleared for run ${params.run_id}. Call ScratchpadInit to start a new run.`,
+          },
+        ],
+        details: { run_id: params.run_id, cleared: true },
+      };
+    },
+
+    renderCall(args, theme) {
+      return new Text(
+        theme.fg("toolTitle", theme.bold("ScratchpadClear ")) +
+          theme.fg("dim", (args.run_id as string) ?? ""),
+        0,
+        0,
+      );
+    },
+
+    renderResult(_result, _opts, theme) {
+      return new Text(theme.fg("success", "✓ ScratchpadClear"), 0, 0);
+    },
+  });
+
   // ── Command: /casefile ──
 
   pi.registerCommand("casefile", {

package/src/ledger.ts

@@ -12,7 +12,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite-compat/index.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -226,8 +226,14 @@ function stableShortId(input: string): string {
 }
 
 function detectWorkspaceRoot(): string {
-  const envs = ["CASEFILE_WORKSPACE_ROOT", "PI_WORKSPACE_ROOT", "GITHUB_WORKSPACE", "PWD"];
-  for (const e of envs) if (process.env[e]) return resolve(process.env[e]!);
+  // PWD is deliberately excluded: it is shell-set, can be stale or forged in
+  // spawned processes, and disagree with the real cwd. Explicit overrides only,
+  // then walk up from the actual cwd.
+  const envs = ["CASEFILE_WORKSPACE_ROOT", "PI_WORKSPACE_ROOT", "GITHUB_WORKSPACE"];
+  for (const e of envs) {
+    const v = process.env[e]?.trim();
+    if (v) return resolve(v);
+  }
 
   let curr = resolve(process.cwd());
   for (let i = 0; i < 20; i++) {
@@ -241,7 +247,10 @@ function detectWorkspaceRoot(): string {
 
 export function getCasefilePath(): string {
   if (ledgerPathOverride) return ledgerPathOverride;
-  if (process.env.PI_CASEFILE_PATH) return resolve(process.env.PI_CASEFILE_PATH.trim());
+  // Trim BEFORE the truthiness check: a whitespace-only value must not
+  // "pass" and resolve to the process cwd ("" resolves to cwd).
+  const envPath = process.env.PI_CASEFILE_PATH?.trim();
+  if (envPath) return resolve(envPath);
   return join(detectWorkspaceRoot(), ".pi", "casefile.db");
 }
 
@@ -622,19 +631,17 @@ function findDuplicateCaseInDb(
   const endpoint = normalizeMatchText(candidate.endpoint);
   const bugClass = normalizeMatchText(candidate.bugClass);
 
-  // Pre-filter by normalized title in SQL so we don't load the whole ledger into
-  // JS just to find a duplicate. normalizeMatchText lowercases + collapses
-  // whitespace, so we match against lower(title) with the same normalization.
-  // The full title/target/endpoint/bugClass match still runs in JS below to catch
-  // whitespace/case differences the SQL LIKE can't express exactly.
-  const sqlTitle = `%${title}%`;
+  // No SQL pre-filter: candidate rows are compared in JS against
+  // normalizeMatchText (lowercase + whitespace-collapse). SQLite's lower() is
+  // ASCII-only and LIKE can't collapse whitespace, so any SQL pre-filter would
+  // silently drop rows the JS comparator would call duplicates (e.g. stored
+  // "SQL  Injection" vs candidate "SQL Injection", or non-ASCII case variants).
+  // Case ledgers are small (hundreds of rows); a full non-killed scan is cheap.
   const rows = excludeId
     ? (db
-        .prepare("SELECT * FROM cases WHERE status != 'killed' AND id != ? AND lower(title) LIKE ?")
-        .all(excludeId, sqlTitle) as any[])
-    : (db
-        .prepare("SELECT * FROM cases WHERE status != 'killed' AND lower(title) LIKE ?")
-        .all(sqlTitle) as any[]);
+        .prepare("SELECT * FROM cases WHERE status != 'killed' AND id != ?")
+        .all(excludeId) as any[])
+    : (db.prepare("SELECT * FROM cases WHERE status != 'killed'").all() as any[]);
 
   for (const row of rows) {
     if (
@@ -922,7 +929,7 @@ export function promoteFindingResult(
   }
 
   const newEvidence =
-    (current.evidence ? current.evidence + "\n\n" : "") +
+    (current.evidence ? `${current.evidence}\n\n` : "") +
     `### PoC Execution Capture (${verification.ranAt})\n` +
     `- **Exit Code:** ${verification.exitCode}\n` +
     `- **Sandbox:** ${verification.sandbox ? "yes" : "no"}\n` +
@@ -1171,7 +1178,7 @@ function mapRowsWithLinks(db: DatabaseSync, rows: any[]): CaseRecord[] {
   const linkMap = new Map<string, { id: string; kind: string }[]>();
   for (const l of links) {
     if (!linkMap.has(l.source_id)) linkMap.set(l.source_id, []);
-    linkMap.get(l.source_id)!.push({ id: l.target_id, kind: l.kind });
+    linkMap.get(l.source_id)?.push({ id: l.target_id, kind: l.kind });
   }
   return rows.map((row) => mapRow(row, linkMap.get(row.id) ?? []));
 }
@@ -1323,14 +1330,14 @@ export function writeCaseReport(id: string): { path: string; record: CaseRecord
     current.pocVerified
       ? mdSection(
           "PoC Verification Log",
-          `### PoC Run Verification\n- **Timestamp:** ${current.pocVerified.ranAt}\n- **Path:** \`${current.pocVerified.path}\`\n- **Sandbox:** ${current.pocVerified.sandbox ? "yes" : "no"}\n- **Exit Code:** ${current.pocVerified.exitCode}\n\n#### Output\n\`\`\`\n${current.pocVerified.output ?? ""}\n\`\`\``,
+          `### PoC Run Verification\n- **Timestamp:** ${current.pocVerified.ranAt}\n- **Script:** \`${basename(current.pocVerified.path)}\`\n- **Sandbox:** ${current.pocVerified.sandbox ? "yes" : "no"}\n- **Exit Code:** ${current.pocVerified.exitCode}\n\n#### Output\n\`\`\`\n${current.pocVerified.output ?? ""}\n\`\`\``,
         )
       : undefined,
     mdSection("Disconfirmation Attempt", current.disconfirmation),
     current.disconfirmationVerified
       ? mdSection(
           "Disconfirmation Verification Log",
-          `### Disconfirmation Run Verification\n- **Timestamp:** ${current.disconfirmationVerified.ranAt}\n- **Path:** \`${current.disconfirmationVerified.path}\`\n- **Sandbox:** ${current.disconfirmationVerified.sandbox ? "yes" : "no"}\n- **Exit Code:** ${current.disconfirmationVerified.exitCode} (non-zero = finding survived the attempt to disprove)\n\n#### Output\n\`\`\`\n${current.disconfirmationVerified.output ?? ""}\n\`\`\``,
+          `### Disconfirmation Run Verification\n- **Timestamp:** ${current.disconfirmationVerified.ranAt}\n- **Script:** \`${basename(current.disconfirmationVerified.path)}\`\n- **Sandbox:** ${current.disconfirmationVerified.sandbox ? "yes" : "no"}\n- **Exit Code:** ${current.disconfirmationVerified.exitCode} (non-zero = finding survived the attempt to disprove)\n\n#### Output\n\`\`\`\n${current.disconfirmationVerified.output ?? ""}\n\`\`\``,
         )
       : undefined,
     mdSection("Impact", current.impact),

package/src/scratchpad.ts

@@ -0,0 +1,339 @@
+/**
+ * Scratchpad — intermediate artifact store for pipeline runs.
+ *
+ * The casefile owns state transitions; the scratchpad owns artifacts.
+ * Agents write their outputs here (recon maps, trace outputs, verification
+ * logs) instead of stuffing everything into casefile text fields or relying
+ * on each other's output streams (which creates an echo chamber).
+ *
+ * Directory layout per pipeline run:
+ *   {project_root}/.scratchpad/{run_id}/
+ *     recon/      — fingerprints, tech detection, surface maps
+ *     trace/      — per-finding reachability traces
+ *     verify/     — PoC logs, run outputs
+ *     state.json  — checkpoint file with phase completion + key IDs
+ *
+ * Resume re-reads scratchpad artifacts; it does not re-run completed phases
+ * (idempotent). The `.scratchpad/` directory is preserved between runs;
+ * `--fresh` clears it via scratchpad_clear().
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export type ScratchpadPhase =
+  | "recon"
+  | "hunt"
+  | "gapfil"
+  | "trace"
+  | "skeptic"
+  | "validate"
+  | "chain"
+  | "patch"
+  | "report";
+
+export interface ScratchpadCheckpoint {
+  run_id: string;
+  project_root: string;
+  created_at: string;
+  last_updated: string;
+  /** Ordered list of phases that have completed (in pipeline order). */
+  completed_phases: ScratchpadPhase[];
+  /** ISO timestamp of the last phase completion. */
+  last_phase_at: string | null;
+  /** Key IDs produced by each phase — case IDs, finding IDs, etc. */
+  phase_ids: Record<ScratchpadPhase, string[]>;
+  /** Free-form summary per phase, set by checkpoint(). */
+  phase_summaries: Record<ScratchpadPhase, string>;
+}
+
+export interface ScratchpadResume {
+  checkpoint: ScratchpadCheckpoint;
+  /** The next phase to run (or null if the run is done). */
+  next_phase: ScratchpadPhase | null;
+  /** Artifact references per phase: { trace: ["finding-abc.json", ...], ... } */
+  artifacts: Record<string, string[]>;
+}
+
+// ── Constants ────────────────────────────────────────────────────────
+
+const PHASE_ORDER: ScratchpadPhase[] = [
+  "recon",
+  "hunt",
+  "gapfil",
+  "trace",
+  "skeptic",
+  "validate",
+  "chain",
+  "patch",
+  "report",
+];
+
+const PHASE_DIRS: Record<ScratchpadPhase, string> = {
+  recon: "recon",
+  hunt: "hunt",
+  gapfil: "gapfil",
+  trace: "trace",
+  skeptic: "skeptic",
+  validate: "verify",
+  chain: "chain",
+  patch: "patch",
+  report: "report",
+};
+
+const SCRATCHPAD_DIR = ".scratchpad";
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+let scratchpadRootOverride: string | undefined;
+
+/**
+ * Detect the workspace root by walking up for a .git dir or package.json,
+ * matching the ledger's detectWorkspaceRoot() heuristic.
+ */
+function detectWorkspaceRoot(): string {
+  if (scratchpadRootOverride) return scratchpadRootOverride;
+
+  // PWD is deliberately excluded (shell-set, can be stale/forged); explicit
+  // overrides only, then walk up from the real cwd.
+  const envs = ["XPI_SCRATCHPAD_ROOT", "PI_WORKSPACE_ROOT", "GITHUB_WORKSPACE"];
+  for (const e of envs) {
+    const v = process.env[e];
+    if (v) return resolve(v);
+  }
+
+  let curr = resolve(process.cwd());
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(join(curr, ".git")) || existsSync(join(curr, "package.json"))) return curr;
+    const parent = dirname(curr);
+    if (parent === curr) break;
+    curr = parent;
+  }
+  return resolve(process.cwd());
+}
+
+/** Override the scratchpad root (for testing). Pass undefined to reset. */
+export function setScratchpadRoot(path: string | undefined): void {
+  scratchpadRootOverride = path ? resolve(path) : undefined;
+}
+
+/** The top-level scratchpad directory for a given project root. */
+export function getScratchpadRoot(projectRoot?: string): string {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  return join(root, SCRATCHPAD_DIR);
+}
+
+/**
+ * Sanitize a run_id into a single safe directory name. Unlike artifact names,
+ * run_ids arrive from the agent and were never sanitized — `..`/`/` would let
+ * join() escape .scratchpad, turning ScratchpadClear("..") into a recursive
+ * delete of the project root. Same allowlist as artifact names, plus rejection
+ * of dot-only results (.", "..", or a sanitized empty string).
+ */
+function sanitizeRunId(runId: string): string {
+  const safe = runId.replace(/[^a-zA-Z0-9._-]/g, "_");
+  if (!safe || /^\.*$/.test(safe)) {
+    throw new Error(`Invalid run_id: "${runId}" — nothing left after sanitization`);
+  }
+  return safe;
+}
+
+/** The directory for a specific run. */
+export function getRunDir(runId: string, projectRoot?: string): string {
+  return join(getScratchpadRoot(projectRoot), sanitizeRunId(runId));
+}
+
+/** The state.json path for a run. */
+export function getStatePath(runId: string, projectRoot?: string): string {
+  return join(getRunDir(runId, projectRoot), "state.json");
+}
+
+function emptyCheckpoint(runId: string, projectRoot: string): ScratchpadCheckpoint {
+  const now = new Date().toISOString();
+  return {
+    run_id: runId,
+    project_root: projectRoot,
+    created_at: now,
+    last_updated: now,
+    last_phase_at: null,
+    completed_phases: [],
+    phase_ids: {} as Record<ScratchpadPhase, string[]>,
+    phase_summaries: {} as Record<ScratchpadPhase, string>,
+  };
+}
+
+function ensureRunDirs(runDir: string): void {
+  if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
+  for (const phase of PHASE_ORDER) {
+    const dir = join(runDir, PHASE_DIRS[phase]);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readCheckpointRaw(runId: string, projectRoot?: string): ScratchpadCheckpoint | null {
+  const statePath = getStatePath(runId, projectRoot);
+  if (!existsSync(statePath)) return null;
+  try {
+    const raw = readFileSync(statePath, "utf8");
+    const cp = JSON.parse(raw) as ScratchpadCheckpoint;
+    // Backfill maps for phases not yet checkpointed (defensive).
+    if (!cp.phase_ids) cp.phase_ids = {} as Record<ScratchpadPhase, string[]>;
+    if (!cp.phase_summaries) cp.phase_summaries = {} as Record<ScratchpadPhase, string>;
+    return cp;
+  } catch {
+    return null;
+  }
+}
+
+function writeCheckpointRaw(cp: ScratchpadCheckpoint, projectRoot?: string): void {
+  cp.last_updated = new Date().toISOString();
+  const statePath = getStatePath(cp.run_id, projectRoot);
+  ensureRunDirs(getRunDir(cp.run_id, projectRoot));
+  writeFileSync(statePath, JSON.stringify(cp, null, 2), "utf8");
+}
+
+// ── Public API ───────────────────────────────────────────────────────
+
+/**
+ * Initialize a new scratchpad run. Creates the directory structure and writes
+ * an initial state.json. If the run already exists, returns the existing
+ * checkpoint (idempotent — safe to call on resume without --fresh).
+ */
+export function scratchpad_init(runId: string, projectRoot?: string): ScratchpadCheckpoint {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  const runDir = getRunDir(runId, root);
+  ensureRunDirs(runDir);
+
+  const existing = readCheckpointRaw(runId, root);
+  if (existing) return existing;
+
+  const cp = emptyCheckpoint(runId, root);
+  writeCheckpointRaw(cp, root);
+  return cp;
+}
+
+/**
+ * Write an artifact to a phase's subdirectory. Overwrites if the name exists.
+ * Returns the full path to the written artifact.
+ */
+export function scratchpad_write(
+  runId: string,
+  phase: ScratchpadPhase,
+  artifactName: string,
+  content: string,
+  projectRoot?: string,
+): string {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  const runDir = getRunDir(runId, root);
+  ensureRunDirs(runDir);
+
+  // Sanitize artifact name: no path traversal.
+  const safeName = artifactName.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const dir = join(runDir, PHASE_DIRS[phase]);
+  const filePath = join(dir, safeName);
+  writeFileSync(filePath, content, "utf8");
+  return filePath;
+}
+
+/**
+ * Read an artifact. Returns null if missing.
+ */
+export function scratchpad_read(
+  runId: string,
+  phase: ScratchpadPhase,
+  artifactName: string,
+  projectRoot?: string,
+): string | null {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  const safeName = artifactName.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const filePath = join(getRunDir(runId, root), PHASE_DIRS[phase], safeName);
+  if (!existsSync(filePath)) return null;
+  return readFileSync(filePath, "utf8");
+}
+
+/**
+ * List all artifacts written for a phase.
+ */
+export function scratchpad_list(
+  runId: string,
+  phase: ScratchpadPhase,
+  projectRoot?: string,
+): string[] {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  const dir = join(getRunDir(runId, root), PHASE_DIRS[phase]);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f !== "state.json");
+}
+
+/**
+ * Mark a phase as complete. Records the completion timestamp, key IDs, and an
+ * optional summary in state.json. Idempotent: re-checkpointing a phase
+ * overwrites its previous summary/IDs but does not duplicate the entry in
+ * completed_phases.
+ */
+export function scratchpad_checkpoint(
+  runId: string,
+  phase: ScratchpadPhase,
+  data: { ids?: string[]; summary?: string },
+  projectRoot?: string,
+): ScratchpadCheckpoint {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  const cp = readCheckpointRaw(runId, root) ?? scratchpad_init(runId, root);
+
+  if (!cp.completed_phases.includes(phase)) {
+    cp.completed_phases.push(phase);
+    // Keep completed_phases in pipeline order for predictable resume.
+    cp.completed_phases.sort((a, b) => PHASE_ORDER.indexOf(a) - PHASE_ORDER.indexOf(b));
+  }
+  cp.last_phase_at = new Date().toISOString();
+  if (data.ids) cp.phase_ids[phase] = data.ids;
+  if (data.summary) cp.phase_summaries[phase] = data.summary;
+
+  writeCheckpointRaw(cp, root);
+  return cp;
+}
+
+/**
+ * Read the checkpoint + all artifact references for resume.
+ * Returns null if the run doesn't exist.
+ */
+export function scratchpad_resume(runId: string, projectRoot?: string): ScratchpadResume | null {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  const cp = readCheckpointRaw(runId, root);
+  if (!cp) return null;
+
+  // Find the next phase: the first phase in order not in completed_phases.
+  const next = PHASE_ORDER.find((p) => !cp.completed_phases.includes(p)) ?? null;
+
+  // Gather artifact listing per completed phase.
+  const artifacts: Record<string, string[]> = {};
+  for (const phase of cp.completed_phases) {
+    artifacts[phase] = scratchpad_list(runId, phase, root);
+  }
+
+  return { checkpoint: cp, next_phase: next, artifacts };
+}
+
+/**
+ * Check whether a phase has already been checkpointed (for idempotent re-run).
+ */
+export function scratchpad_phase_done(
+  runId: string,
+  phase: ScratchpadPhase,
+  projectRoot?: string,
+): boolean {
+  const cp = readCheckpointRaw(runId, projectRoot);
+  return cp?.completed_phases.includes(phase) ?? false;
+}
+
+/**
+ * Clear a specific run's scratchpad directory. Used by `--fresh` for a single
+ * run. Does not touch other runs.
+ */
+export function scratchpad_clear(runId: string, projectRoot?: string): void {
+  const root = projectRoot ?? detectWorkspaceRoot();
+  const runDir = getRunDir(runId, root);
+  if (existsSync(runDir)) rmSync(runDir, { recursive: true, force: true });
+}

package/src/workflow.ts

@@ -17,6 +17,16 @@ Think like a real external attacker, not a code reviewer. Technical bugs are che
 
 Every lead starts HYPOTHESIS. Nothing reaches CONFIRMED without a proven attacker path and demonstrated impact against a real production target or faithful replica.
 
+## Tool Reference
+
+**Casefile (state tracking):** CaseAdd, CaseUpdate, CaseGet, CaseList, CaseSearch, CaseLink, CaseUnlink, CaseReport, PromoteFinding
+
+**Scratchpad (pipeline artifacts):** ScratchpadInit, ScratchpadResume, ScratchpadCheckpoint, ScratchpadWrite, ScratchpadRead, ScratchpadPhaseDone, ScratchpadClear
+
+**Web lookup (research):** web_search, web_fetch, exploit_search, context7, deepwiki, http_request
+
+**Subagent dispatch:** \`subagent({agent: "auditor"|"tracer"|"skeptic"|"exploit"|"chain", task: "..."})\` — use this to dispatch specialist agents. Do NOT do the specialist work yourself.
+
 ## Case Lifecycle (State Machine)
 
 \`\`\`
@@ -47,7 +57,7 @@ RECON -> HYPOTHESIS --+
 | Advance To | Required Case Fields | Must Exist on Disk |
 |-----------|---------------------|--------------------|
 | HYPOTHESIS -> INVESTIGATING | evidence (observations or initial findings), confidence | Notes on what was observed |
-| INVESTIGATING -> **CONFIRMED** | evidence, poc (steps/script), **impact (see below for content requirements)**, severity, **target (host/repo/scope this affects)**, **disconfirmation (your documented attempt to disprove the finding)** | PoC script + run.log exit 0. Optionally, disconfirmation script run.log exit non-0 (finding survived the attempt to disprove). |
+| INVESTIGATING -> **CONFIRMED** | evidence, poc (steps/script), **impact (see below for content requirements)**, severity, **target (host/repo/scope this affects)**, **disconfirmation (your documented attempt to disprove the finding)** | PoC script + exit 0 + **verification_marker present in output** (proves the exploit actually worked, not just that the script ran). Optionally, disconfirmation script run.log exit non-0 (finding survived the attempt to disprove). |
 | Any -> KILLED | assumptions (why it died) | --- |
 | CONFIRMED -> REPORTED | Only after CaseReport(id) succeeds | Report file |
 
@@ -109,22 +119,20 @@ Before promoting to CONFIRMED, the following must be fully answered and document
 
 If you cannot name a concrete attacker who gains something they should not have -> do **not** confirm. Stay INVESTIGATING or KILL with documented reason.
 
-### 1. Disconfirmation Attempt (mandatory field before CONFIRMED)
+### 1. Disconfirmation (mandatory before CONFIRMED)
 
-Before promoting, you must actively attempt to disprove your own finding.
-This is not a formality --- the attempt is documented in the \`disconfirmation\`
-field and verified by the optional \`disconfirmation_path\` in PromoteFinding.
+Before promoting to CONFIRMED, the finding must survive an attempt to disprove it. There are two tiers, gated on the auditor's \`confidence\` (severity doesn't exist yet — the exploit agent assigns it only after the PoC runs):
+
+**\`confidence: high\` → skeptic subagent (MANDATORY):** You MUST dispatch a skeptic subagent via \`subagent({agent: "skeptic", task: "..."})\` BEFORE the exploit agent runs. The skeptic independently re-reads the source (or re-probes live), verifies the finding is in scope per the program's scope instruction, and tries to disprove it. The skeptic's \`disconfirmation_attempt\` is written into the case's \`disconfirmation\` field — it satisfies this gate and is stronger than self-disconfirmation because a separate agent produced it. If the skeptic says DISPROVEN, the finding is killed directly — no tie-breaker. Do NOT skip this step. Do NOT self-disconfirm high-confidence findings.
+
+**Below confidence high → self-disconfirmation:** You must actively attempt to disprove your own finding. Document the attempt in the \`disconfirmation\` field. This is not a formality.
 
 **What a disconfirmation attempt looks like:**
 
-- Reproduce the finding under different conditions (different auth, different
-  config, different network position). If it fails, you disproved the scope.
-- Check if the behavior is intentional by testing against documentation or
-  by trying to get the same result on a known-baseline endpoint.
-- Attempt to trigger protections (WAF, CSP, CSRF, rate limits) that would
-  block the path in production.
-- Try to prove the root cause is wrong: can the same behavior be triggered
-  without the attacker-controlled input you identified?
+- Reproduce the finding under different conditions (different auth, different config, different network position). If it fails, you disproved the scope.
+- Check if the behavior is intentional by testing against documentation or by trying to get the same result on a known-baseline endpoint.
+- Attempt to trigger protections (WAF, CSP, CSRF, rate limits) that would block the path in production.
+- Try to prove the root cause is wrong: can the same behavior be triggered without the attacker-controlled input you identified?
 
 **Document the attempt in \`disconfirmation\` field.** Must include:
 1. What you tried to do to disprove the finding
@@ -133,19 +141,12 @@ field and verified by the optional \`disconfirmation_path\` in PromoteFinding.
 4. Why you believe the disconfirmation attempt was valid
 
 **Strong disconfirmation that passes the gate:**
-"Attempted to read /api/users/123 as user B after confirming user A owns
-record 123. The endpoint returned 403 for user B, confirming the IDOR
-protection works as expected. However, when we modified the request to
-include the X-Override-User header seen in admin traffic, the endpoint
-returned user A's data. The protection is bypassed via the admin header."
+"Attempted to read /api/users/123 as user B after confirming user A owns record 123. The endpoint returned 403 for user B, confirming the IDOR protection works as expected. However, when we modified the request to include the X-Override-User header seen in admin traffic, the endpoint returned user A's data. The protection is bypassed via the admin header."
 
 **Weak disconfirmation:**
 "Tried to disprove. Could not."
 
-If the disconfirmation script (disconfirmation_path) exits 0, the finding
-is considered disproven and promotion is blocked. If you cannot write a
-meaningful disconfirmation script, you may not understand the finding well
-enough to promote it.
+If the disconfirmation script (\`disconfirmation_path\` in PromoteFinding) exits 0, the finding is considered disproven and promotion is blocked. If you cannot write a meaningful disconfirmation script, you may not understand the finding well enough to promote it.
 
 ### 2. Production Path Verification (must be in impact field)
 
@@ -164,7 +165,7 @@ The **impact** field for CONFIRMED must explicitly answer:
 
 You must name the **specific target host/repo** in the target field. If the finding only works on a dev instance with non-default config, document that honestly and consider whether it's KILL-worthy.
 
-### 2. KILL at Validate stage
+### 3. KILL at Validate stage
 
 Documented intended behavior
 - Self-XSS / self-DoS only (attacker harms only their own session)
@@ -175,11 +176,11 @@ Documented intended behavior
 - PoC proves a code path exists but not that any victim asset is affected
 - Protections in production block the path and are not bypassed
 
-### 3. Evidence-First Doctrine
+### 4. Evidence-First Doctrine
 
 Every claim must be traceable to observed/reproduced behavior, source code, or documented platform behavior. If evidence is insufficient: state uncertainty and propose the next experiment. Never assume success where verification is incomplete.
 
-### 4. Impact Gate
+### 5. Impact Gate
 
 Prove at least **one** real attacker-facing violation against a production-viable target:
 
@@ -194,7 +195,16 @@ Impact text must answer: *who is hurt, what is lost, how the attacker reaches it
 
 If impact is theoretical, needs a second unproven bug, or is not yet reachable from the attacker's position -> stay INVESTIGATING (chain it) or KILL.
 
-### 5. Adversarial Self-Review
+**Severity is derived from PROVEN impact, not guessed.** Do not set severity until the PoC has exited 0 and the output demonstrates the impact. Map severity to what the PoC output actually shows:
+- **critical** = RCE, account takeover, or direct fund theft — proven in PoC output
+- **high** = sensitive data read/write, privilege escalation, SSRF to internal services — proven in PoC output
+- **medium** = limited data exposure, XSS on sensitive page, IDOR on non-critical resources — proven in PoC output
+- **low** = info leak, open redirect, self-only impact with a victim path — proven but minimal harm
+- **info** = best-practice gap, no demonstrated impact
+
+"Could lead to" / "may allow" / "theoretically" = NOT proven. Drop to the level the PoC output actually demonstrates. Under-claiming is safe; over-claiming gets the finding rejected at triage.
+
+### 6. Adversarial Self-Review
 
 1. Why this might NOT be a vulnerability.
 2. Alternative explanations for the observation.
@@ -202,7 +212,7 @@ If impact is theoretical, needs a second unproven bug, or is not yet reachable f
 4. What blocks a real attacker in production today and whether each is bypassed.
 5. Would a program triage reject this as informative/N/A?
 
-### 6. Root Cause -> Boundary -> Impact
+### 7. Root Cause -> Boundary -> Impact
 
 \`\`\`
 Entry (attacker-controlled) -> Code path -> Trust boundary crossed -> Victim impact