@xaccefy/pi-casefile 0.5.7 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaccefy/pi-casefile",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "Offensive security case tracker for Pi Agent — bug bounties, CTFs, security audits",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -35,6 +35,7 @@ import {
   linkCasesResult,
   PRIORITY_VALUES,
   promoteFindingResult,
+  readActiveCases,
   readCasefile,
   SEARCH_FIELD_VALUES,
   SEVERITY_VALUES,
@@ -44,7 +45,7 @@ import {
   updateCaseResult,
   writeCaseReport,
 } from "./ledger.ts";
-import { runPoc } from "./poc-runner.ts";
+import { type PocRun, runPoc } from "./poc-runner.ts";
 import { STATIC_CYBER_WORKFLOW } from "./workflow.ts";
 
 // ── Schemas ───────────────────────────────────────────────────────────
@@ -110,6 +111,12 @@ const PromoteSchema = Type.Object(
     poc_path: Type.String({
       description: "Absolute path to the PoC script on disk",
     }),
+    disconfirmation_path: Type.Optional(
+      Type.String({
+        description:
+          "Absolute path to a disconfirmation script that tries to disprove the finding; must exit non-zero (failure to disprove)",
+      }),
+    ),
     local: Type.Optional(Type.Boolean({ description: "Run locally instead of in Docker sandbox" })),
   },
   { additionalProperties: false },
@@ -405,7 +412,8 @@ function buildCaseListContext(records: CaseRecord[]): string {
 /** Always includes cyber workflow; attaches case list when active cases exist. */
 function buildAgentInjection(active: CaseRecord[]): string {
   const caseList = buildCaseListContext(active);
-  return caseList ? `${caseList}\n\n${STATIC_CYBER_WORKFLOW}` : STATIC_CYBER_WORKFLOW;
+  // Workflow FIRST for prominence, then case list as reference data.
+  return caseList ? `${STATIC_CYBER_WORKFLOW}\n\n${caseList}` : STATIC_CYBER_WORKFLOW;
 }
 
 // ── XP (offensive / exploit) mode toggle ─────────────────────────────
@@ -623,13 +631,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.",
+      "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).",
     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, and severity fields.",
+      "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.",
+      "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.",
     ],
     parameters: PromoteSchema,
@@ -656,13 +665,46 @@ export default function casefileExtension(pi: ExtensionAPI) {
         };
       }
 
-      const result = promoteFindingResult(params.id as string, {
-        path: run.path,
-        exitCode: run.exitCode,
-        ranAt: run.ranAt,
-        output: run.output,
-        sandbox: run.sandbox,
-      });
+      // Run disconfirmation script if provided — must exit NON-0 (finding survived the attempt to disprove).
+      let disconfirmationRun: PocRun | undefined;
+      if (params.disconfirmation_path) {
+        disconfirmationRun = runPoc(params.disconfirmation_path as string, params.local !== true);
+        if (disconfirmationRun.exitCode === 0) {
+          const record = getCaseById(params.id as string);
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `Disconfirmation script exited 0 (finding was disproven). ` +
+                  `Case remains investigating.\nOutput:\n${disconfirmationRun.output}`,
+              },
+            ],
+            isError: true,
+            details: { record, run, disconfirmationRun },
+          };
+        }
+      }
+
+      const result = promoteFindingResult(
+        params.id as string,
+        {
+          path: run.path,
+          exitCode: run.exitCode,
+          ranAt: run.ranAt,
+          output: run.output,
+          sandbox: run.sandbox,
+        },
+        disconfirmationRun
+          ? {
+              path: disconfirmationRun.path,
+              exitCode: disconfirmationRun.exitCode,
+              ranAt: disconfirmationRun.ranAt,
+              output: disconfirmationRun.output,
+              sandbox: disconfirmationRun.sandbox,
+            }
+          : undefined,
+      );
       const record = result.record;
       return {
         content: [
@@ -969,7 +1011,8 @@ export default function casefileExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: "CaseReport",
     label: "Write Case Report",
-    description: "Generate a markdown report from a case under the project report directory.",
+    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.",
     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.",
@@ -1057,30 +1100,29 @@ export default function casefileExtension(pi: ExtensionAPI) {
     }
   });
 
-  // ── Event: Inject context into system prompt ──
+  // ── Event: Inject cyber workflow into system prompt ──
   // XP (offensive) mode is OFF by default so normal dev work stays quiet.
-  // Only when enabled do we inject the cyber workflow (and case list) each
-  // prompt. This keeps the agent focused during everyday development while
-  // still allowing the full attacker discipline to be switched on for
-  // offensive/audit/bounty sessions.
+  // Only when enabled do we inject the cyber workflow (and case list) into
+  // the system prompt each turn. Injecting into event.systemPrompt (not as a
+  // conversation message) makes the attacker mindset immediate and avoids
+  // session bloat from repeated message entries.
 
-  pi.on("before_agent_start", async () => {
+  pi.on("before_agent_start", async (event) => {
     if (readXpMode() === "off") return;
 
     let active: CaseRecord[] = [];
     try {
-      const records = readCasefile();
-      active = records.filter((r) => r.status !== "killed" && r.status !== "reported");
+      active = readActiveCases();
     } catch {
       // No database yet — still inject workflow.
     }
 
+    const injection = buildAgentInjection(active);
+
+    // Inject workflow FIRST (before skills) so the attacker mindset is
+    // prominent, not buried at the end of a long system prompt.
     return {
-      message: {
-        customType: "casefile_summary",
-        content: buildAgentInjection(active),
-        display: false,
-      },
+      systemPrompt: `${injection}\n\n${event.systemPrompt ?? ""}`,
     };
   });
 

package/src/ledger.ts

@@ -101,6 +101,8 @@ export type CaseRecord = {
   tags?: string[];
   /** Explicit assumptions or unknowns to avoid overstating exploitability. */
   assumptions?: string[];
+  /** Agent's documented attempt to disprove the finding (required before CONFIRMED). */
+  disconfirmation?: string;
   /** Verification of an on-disk PoC run (set only by promoteFindingResult). */
   pocVerified?: {
     path: string;
@@ -109,6 +111,14 @@ export type CaseRecord = {
     output?: string;
     sandbox: boolean;
   };
+  /** Verification of a disconfirmation run (set only by promoteFindingResult). */
+  disconfirmationVerified?: {
+    path: string;
+    exitCode: number;
+    ranAt: string;
+    output?: string;
+    sandbox: boolean;
+  };
   /** ISO timestamp when CaseReport first wrote the markdown report. */
   reportedAt?: string;
   /** Path to the generated markdown report (set only by writeCaseReport). */
@@ -140,11 +150,14 @@ export type CaseInput = {
   blockers?: string[];
   tags?: string[];
   assumptions?: string[];
+  /** Agent's documented attempt to disprove the finding (required before CONFIRMED). */
+  disconfirmation?: string;
 };
 
 type NormalizedCaseInput = Partial<CaseInput> & {
   linkedCaseIds?: string[];
   pocVerified?: CaseRecord["pocVerified"];
+  disconfirmationVerified?: CaseRecord["disconfirmationVerified"];
   reportedAt?: string;
   reportPath?: string;
 };
@@ -285,6 +298,8 @@ function getDb(): DatabaseSync {
       tags_json TEXT, -- JSON string array
       assumptions_json TEXT, -- JSON string array
       poc_verified_json TEXT, -- JSON object
+      disconfirmation TEXT,
+      disconfirmation_verified_json TEXT, -- JSON object
       reported_at TEXT,
       report_path TEXT,
       created_at TEXT NOT NULL,
@@ -309,6 +324,15 @@ function getDb(): DatabaseSync {
     db.exec("ALTER TABLE case_links ADD COLUMN kind TEXT NOT NULL DEFAULT 'related'");
   }
 
+  // Idempotent migration for new columns on existing databases
+  const caseCols = db.prepare("PRAGMA table_info(cases)").all() as { name: string }[];
+  if (!caseCols.some((c) => c.name === "disconfirmation")) {
+    db.exec("ALTER TABLE cases ADD COLUMN disconfirmation TEXT");
+  }
+  if (!caseCols.some((c) => c.name === "disconfirmation_verified_json")) {
+    db.exec("ALTER TABLE cases ADD COLUMN disconfirmation_verified_json TEXT");
+  }
+
   // Indexes
   db.exec(`CREATE INDEX IF NOT EXISTS idx_cases_status ON cases(status)`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_cases_target ON cases(target)`);
@@ -361,7 +385,9 @@ function mapRow(row: any, linkedCases: { id: string; kind: string }[] = []): Cas
     blockers: safeParseArray(row.blockers_json),
     tags: safeParseArray(row.tags_json),
     assumptions: safeParseArray(row.assumptions_json),
+    disconfirmation: row.disconfirmation || undefined,
     pocVerified: safeParseObject(row.poc_verified_json),
+    disconfirmationVerified: safeParseObject(row.disconfirmation_verified_json),
     reportedAt: row.reported_at || undefined,
     reportPath: row.report_path || undefined,
     linkedCases,
@@ -393,6 +419,19 @@ export function readCasefile(): CaseRecord[] {
   return rows.map((row: any) => mapRow(row, linkMap.get(row.id) ?? []));
 }
 
+/**
+ * Read only non-terminal cases (hypothesis, investigating, confirmed, blocked).
+ * Used for per-prompt context injection so we never load killed/reported rows
+ * (which grow without bound over a long engagement) into memory each turn.
+ */
+export function readActiveCases(): CaseRecord[] {
+  const db = getDb();
+  const rows = db
+    .prepare("SELECT * FROM cases WHERE status NOT IN ('killed', 'reported')")
+    .all() as any[];
+  return mapRowsWithLinks(db, rows);
+}
+
 export function getCaseById(id: string): CaseRecord | undefined {
   const db = getDb();
   const stmt = db.prepare("SELECT * FROM cases WHERE id = ?");
@@ -416,9 +455,13 @@ function validateCase(record: CaseRecord): void {
   // CONFIRMED when it has evidence, a PoC, demonstrated impact, and a severity.
   if (
     record.status === "confirmed" &&
-    (!record.evidence || !record.poc || !record.impact || !record.severity)
+    (!record.evidence ||
+      !record.poc ||
+      !record.impact ||
+      !record.severity ||
+      !record.disconfirmation)
   ) {
-    throw new Error("Confirmed cases require evidence, poc, impact, and severity");
+    throw new Error("Confirmed cases require evidence, poc, impact, severity, and disconfirmation");
   }
   if (record.status === "blocked" && (record.blockers ?? []).length === 0) {
     throw new Error("Blocked cases require at least one blocker");
@@ -553,6 +596,11 @@ function buildRecord(input: NormalizedCaseInput, existing?: CaseRecord): CaseRec
     tags: normalizeList(input.tags ?? existing?.tags),
     assumptions: normalizeList(input.assumptions ?? existing?.assumptions),
     pocVerified: input.pocVerified ?? existing?.pocVerified,
+    disconfirmation:
+      input.disconfirmation !== undefined
+        ? normalizeText(input.disconfirmation)
+        : existing?.disconfirmation,
+    disconfirmationVerified: input.disconfirmationVerified ?? existing?.disconfirmationVerified,
     reportedAt: input.reportedAt ?? existing?.reportedAt,
     reportPath: input.reportPath ?? existing?.reportPath,
     linkedCases: existing?.linkedCases ?? [],
@@ -574,12 +622,19 @@ function findDuplicateCaseInDb(
   const endpoint = normalizeMatchText(candidate.endpoint);
   const bugClass = normalizeMatchText(candidate.bugClass);
 
-  // Query non-killed cases, then match normalized title/scope in JS.
+  // 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}%`;
   const rows = excludeId
     ? (db
-        .prepare("SELECT * FROM cases WHERE status != 'killed' AND id != ?")
-        .all(excludeId) as any[])
-    : (db.prepare("SELECT * FROM cases WHERE status != 'killed'").all() as any[]);
+        .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[]);
 
   for (const row of rows) {
     if (
@@ -610,11 +665,13 @@ function upsertCase(db: DatabaseSync, record: CaseRecord) {
       id, title, status, confidence, severity, priority, target, endpoint, bugClass,
       summary, evidence, impact, nextStep, poc, remediation,
       references_json, blockers_json, tags_json, assumptions_json, poc_verified_json,
+      disconfirmation, disconfirmation_verified_json,
       reported_at, report_path, created_at, updated_at
     ) VALUES (
       ?, ?, ?, ?, ?, ?, ?, ?, ?,
       ?, ?, ?, ?, ?, ?,
       ?, ?, ?, ?, ?,
+      ?, ?,
       ?, ?, ?, ?
     )
     ON CONFLICT(id) DO UPDATE SET
@@ -637,6 +694,8 @@ function upsertCase(db: DatabaseSync, record: CaseRecord) {
       tags_json = excluded.tags_json,
       assumptions_json = excluded.assumptions_json,
       poc_verified_json = excluded.poc_verified_json,
+      disconfirmation = excluded.disconfirmation,
+      disconfirmation_verified_json = excluded.disconfirmation_verified_json,
       reported_at = excluded.reported_at,
       report_path = excluded.report_path,
       created_at = excluded.created_at,
@@ -664,6 +723,8 @@ function upsertCase(db: DatabaseSync, record: CaseRecord) {
     JSON.stringify(record.tags),
     JSON.stringify(record.assumptions),
     record.pocVerified ? JSON.stringify(record.pocVerified) : null,
+    record.disconfirmation || null,
+    record.disconfirmationVerified ? JSON.stringify(record.disconfirmationVerified) : null,
     record.reportedAt || null,
     record.reportPath || null,
     record.createdAt,
@@ -719,6 +780,7 @@ export function updateCaseResult(id: string, update: CaseUpdate): CaseUpdateResu
     "nextStep",
     "poc",
     "remediation",
+    "disconfirmation",
   ] as const;
   const optionalPatch: Record<string, unknown> = {};
   for (const field of optionalFields) {
@@ -746,16 +808,38 @@ export function updateCaseResult(id: string, update: CaseUpdate): CaseUpdateResu
     validateTransition(current.status, next.status, update, current);
   }
 
-  // Demoting off confirmed invalidates prior PoC verification — re-promote required.
+  // Demoting off confirmed invalidates prior PoC + disconfirmation verification —
+  // re-promote required. Both verification artifacts must be re-earned together.
   if (current.status === "confirmed" && next.status === "investigating") {
-    next = { ...next, pocVerified: undefined };
+    next = { ...next, pocVerified: undefined, disconfirmationVerified: undefined };
   }
 
   validateCase(next);
 
-  // Check material equality (we ignore links since links are mutated via CaseLink)
+  // Check material equality (we ignore links since links are mutated via CaseLink).
+  // Keys are sorted before stringify because mapRow (DB read) and buildRecord
+  // (write) emit CaseRecord keys in different orders — a plain JSON.stringify({...r})
+  // would report false "changed" on no-op updates whenever a field is undefined on
+  // one side and absent on the other. Sorting makes the comparison order-independent.
+  // Do NOT simplify back to JSON.stringify({...r}) — it reintroduces the bug.
   const norm = (r: CaseRecord) =>
-    JSON.stringify({ ...r, updatedAt: "", createdAt: "", linkedCaseIds: [], linkedCases: [] });
+    JSON.stringify(
+      Object.keys(r)
+        .sort()
+        .reduce<Record<string, unknown>>((acc, k) => {
+          if (
+            k === "updatedAt" ||
+            k === "createdAt" ||
+            k === "linkedCaseIds" ||
+            k === "linkedCases"
+          ) {
+            acc[k] = "";
+          } else {
+            acc[k] = (r as Record<string, unknown>)[k];
+          }
+          return acc;
+        }, {}),
+    );
   if (norm(current) === norm(next)) {
     const reason =
       update.status && update.status === current.status
@@ -777,7 +861,7 @@ export function updateCaseResult(id: string, update: CaseUpdate): CaseUpdateResu
   return { record: next, changed: true };
 }
 
-type PocVerification = {
+export type PocVerification = {
   path: string;
   exitCode: number;
   ranAt: string;
@@ -811,10 +895,24 @@ export function assertPromotable(id: string): CaseRecord {
   if (!current.severity) {
     throw new Error("CONFIRMED requires severity; set severity on the case first");
   }
+  if (!current.target) {
+    throw new Error(
+      "CONFIRMED requires target (what host/repo/scope this affects); set target on the case first",
+    );
+  }
+  if (!current.disconfirmation) {
+    throw new Error(
+      "CONFIRMED requires disconfirmation (your attempt to disprove the finding); set disconfirmation on the case first",
+    );
+  }
   return current;
 }
 
-export function promoteFindingResult(id: string, verification: PocVerification): CaseUpdateResult {
+export function promoteFindingResult(
+  id: string,
+  verification: PocVerification,
+  disconfirmationVerification?: PocVerification,
+): CaseUpdateResult {
   const db = getDb();
   const current = assertPromotable(id);
   if (verification.exitCode !== 0) {
@@ -830,14 +928,16 @@ export function promoteFindingResult(id: string, verification: PocVerification):
     `- **Sandbox:** ${verification.sandbox ? "yes" : "no"}\n` +
     `#### Execution Output\n\`\`\`\n${verification.output ?? ""}\n\`\`\``;
 
-  const next = buildRecord(
-    {
-      status: "confirmed",
-      pocVerified: verification,
-      evidence: newEvidence,
-    },
-    current,
-  );
+  const update: NormalizedCaseInput = {
+    status: "confirmed",
+    pocVerified: verification,
+    evidence: newEvidence,
+  };
+  if (disconfirmationVerification) {
+    update.disconfirmationVerified = disconfirmationVerification;
+  }
+
+  const next = buildRecord(update, current);
   validateCase(next);
 
   upsertCase(db, next);
@@ -1226,6 +1326,13 @@ export function writeCaseReport(id: string): { path: string; record: CaseRecord
           `### 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\`\`\``,
         )
       : 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\`\`\``,
+        )
+      : undefined,
     mdSection("Impact", current.impact),
     mdSection("Remediation", current.remediation),
     mdSection("Assumptions and Uncertainty", assumptions),
@@ -1243,6 +1350,11 @@ export function writeCaseReport(id: string): { path: string; record: CaseRecord
     updatedAt: new Date().toISOString(),
   };
 
+  // Enforce the same field invariants as every other write path. writeCaseReport
+  // never changes status (confirmed stays confirmed; the caller flips to reported
+  // via CaseUpdate, which runs validateTransition), but it does set reportPath —
+  // validateCase ensures the resulting record is internally consistent.
+  validateCase(next);
   upsertCase(db, next);
   return { path: reportPath, record: next };
 }

package/src/poc-runner.ts

@@ -421,15 +421,20 @@ function runLocal(pocPath: string, language: PocLanguage): PocRun {
     throw new Error("Language config has no run command");
   }
 
-  // The run template is `<interpreter> <file>`. Preserve multi-arg run commands for
-  // normal paths, but keep a space-containing PoC path as a single argument (no shell
-  // is used, so args are passed verbatim).
-  const command = renderCommand(language.run, pocPath, false);
-  const trimmed = command.trim();
-  const firstSpace = trimmed.indexOf(" ");
-  const interpreter = firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace);
-  const rest = firstSpace === -1 ? "" : trimmed.slice(firstSpace + 1);
-  const args = pocPath.includes(" ") ? (rest ? [rest] : []) : rest ? rest.split(" ") : [];
+  // The run template is `<interpreter> [flags...] {{file}}`. Split the static
+  // template on whitespace FIRST (the template is trusted config, not user input),
+  // then render placeholders within each token. Passing the tokens to spawnSync
+  // with NO shell keeps a space-containing PoC path as one arg and keeps extra
+  // flags (e.g. `node --experimental-vm-modules {{file}}`) as separate args.
+  // Splitting after rendering would re-split a space-containing path.
+  const tokens = language.run.trim().split(/\s+/).filter(Boolean);
+  const interpreter = tokens.shift() ?? language.run.trim();
+  const args = tokens.map((tok) =>
+    tok
+      .replace(/{{file}}/g, pocPath)
+      .replace(/{{bin}}/g, join(dirname(pocPath), "poc"))
+      .replace(/{{class}}/g, basename(pocPath).replace(/\.[^.]+$/i, "")),
+  );
 
   const result = spawnSync(interpreter, args, {
     encoding: "utf8",

package/src/workflow.ts

@@ -1,187 +1,233 @@
 /**
  * Cyber workflow injected into agent context when XP mode is ON.
- * Extracted into its own file to keep index.ts readable.
+ *
+ * Skills (pipeline, web-pentest) already cover tool usage and methodology.
+ * This file adds the unique attacker discipline: state machine with
+ * preconditions, attacker model, impact validation, adversarial review,
+ * kill checklist, and report-readiness criteria.
+ *
+ * The case lifecycle (HYPOTHESIS -> INVESTIGATING -> CONFIRMED -> REPORTED)
+ * maps to the pipeline's discovery stages. This file explains the gate
+ * discipline applied at each transition.
  */
 export const STATIC_CYBER_WORKFLOW = `
 # Cyber Workflow (Attacker-Oriented)
 
 Think like a real external attacker, not a code reviewer. Technical bugs are cheap; **reachable attacker impact** is what matters for bounty-valid findings.
 
-Every lead starts HYPOTHESIS. Nothing reaches CONFIRMED without:
-1. a working PoC on disk,
-2. a proven attacker path (who can trigger it, from where),
-3. demonstrated C/I/A impact (not theoretical).
+Every lead starts HYPOTHESIS. Nothing reaches CONFIRMED without a proven attacker path and demonstrated impact against a real production target or faithful replica.
 
-Prefer killing a cute-but-unusable bug over reporting noise. Every confirmed finding must survive skeptical review by another experienced security researcher **and** a program triage engineer.
-
-## State Machine (CaseAdd → CaseUpdate → CaseReport)
+## Case Lifecycle (State Machine)
 
 \`\`\`
-HYPOTHESIS ──→ INVESTIGATING ──→ CONFIRMED ──→ REPORTED
-    │               │                │
-    └──→ KILLED ←───┘                │
-                     CONFIRMED ←─ KILL if any gate fails
+                     +--- KILLED (dead end, documented why)
+                     |
+RECON -> HYPOTHESIS --+
+                       |
+                       +--> INVESTIGATING --> CONFIRMED --> REPORTED
+                                |   ^                 |
+                                |   |  chain/primitive |
+                                |   +-----------------+
+                                |
+                                +--> KILLED (insufficient impact, duplicate, etc.)
 \`\`\`
 
-### Preconditions Per State (MANDATORY)
+### Phase -> State map
+
+| Phase | Case State | What happens |
+|-------|-----------|-------------|
+| RECON | (none yet) | Map attack surface, fingerprint, search CVEs. When something interesting appears -> HYPOTHESIS. |
+| HUNT | HYPOTHESIS | Document the lead. Impact not required yet. If it's a clear intended-behavior or artifact -> KILLED. Otherwise -> INVESTIGATING. |
+| CHAIN | INVESTIGATING | Test the hypothesis, chain primitives, build PoC. Explore combinations (open redirect + SSRF, leak + other endpoint, etc.). |
+| VALIDATE | CONFIRMED | Prove impact against production target, adversarial review, root-cause trace. Survive the gates below, or fall back to INVESTIGATING / KILLED. |
+| REPORT | REPORTED | Write up, report-readiness gate, submit. |
+
+### Preconditions Per State Transition (MANDATORY)
 
 | Advance To | Required Case Fields | Must Exist on Disk |
 |-----------|---------------------|--------------------|
-| INVESTIGATING | \`evidence\` (source→sink + **attacker reachability**), \`confidence\` | Path trace in notes |
-| **CONFIRMED** | \`evidence\`, **\`poc\`**, \`impact\` (attacker-real), \`severity\`, **\`impact_proof\`** | **PoC script + run.log exit 0 + proof of impact** |
-| KILLED | \`assumptions\` (why it died: no path / no impact / not applicable) | — |
-| REPORTED | Only after \`CaseReport(id)\` succeeds | Report file |
+| 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). |
+| Any -> KILLED | assumptions (why it died) | --- |
+| CONFIRMED -> REPORTED | Only after CaseReport(id) succeeds | Report file |
+
+**Rule: If a required field is empty, you cannot advance.** The fields are the gates.
+
+### When to advance vs kill vs stay
+
+Staying in HYPOTHESIS or INVESTIGATING is **fine** --- it means you're still working. Do not force a transition.
 
-**Rule: If a required field is empty, you cannot advance.** \`CaseUpdate({status:"confirmed", poc:""})\` is invalid. The fields are the gates.
+- **HYPOTHESIS -> KILLED only when**: it's documented intended behavior, duplicate, artifact/noise, or you proved no attack path exists after testing.
+- **HYPOTHESIS -> INVESTIGATING**: you have something real and are actively testing. Source-sink not required yet.
+- **INVESTIGATING -> KILLED**: you proved insufficient impact, environmental issue, unreliable exploit, or duplicate after investigation.
+- **INVESTIGATING -> CONFIRMED**: strict gates below must pass.
 
 ---
 
-## 0. Attacker Model (Read First)
+## At HYPOTHESIS (just found something)
+
+Document what you know without worrying about impact proof:
+
+1. **What happened?** (behavior, error, timing, leak)
+2. **Where?** (endpoint, parameter, component, line)
+3. **Who can reach it?** (unauth, any user, admin only)
+4. **What you don't know yet** -> next experiments
+
+**Do not kill a hypothesis just because impact is unclear.** Impact may come from chaining.
+
+**Kill a hypothesis only when:**
+- It's clearly documented/intended behavior (after checking docs)
+- It's a duplicate
+- It's a test artifact, cache noise, browser quirk
+- You tested and proved no attack path exists (not "I can't see one")
+
+---
 
-Before escalating any finding, answer in evidence:
+## At INVESTIGATING (chaining primitives)
+
+Many findings start as primitives: open redirect, limited SSRF, info leak of non-sensitive data, reflected XSS on non-sensitive page, CSRF on public-only action.
+
+For each primitive, ask:
+1. **What can this combine with?** (SSRF + internal service, open redirect + OAuth callback, leak + other endpoint)
+2. **Does the primitive cross a trust boundary?** Can an unauth user trigger it? Can a low-priv user reach an admin endpoint?
+3. **What's the worst-case chain expressed in C/I/A?**
+
+Record chains via CaseLink. Keep the primitive as INVESTIGATING while you explore. Only KILL if you prove no chain exists after testing.
+
+---
+
+## At VALIDATE (before advancing to CONFIRMED)
+
+Before promoting to CONFIRMED, the following must be fully answered and documented in the case fields (evidence + impact). Incomplete answers = stay INVESTIGATING.
+
+### 0. Attacker Model (must be in evidence or impact field)
 
 1. **Who is the attacker?** (unauth internet, low-priv user, tenant peer, SSRF pivot, etc.)
 2. **What can they already do without the bug?** (baseline privileges)
 3. **What extra power does the bug grant beyond that baseline?**
-4. **Is the path realistic in production?** (auth, CSRF, WAF, network, feature flags, admin-only)
+4. **Is the path realistic in production?** (auth, CSRF, WAF, network, feature flags, admin-only required?)
 
-If you cannot name a concrete attacker who gains something they should not have → do **not** confirm. Keep as hypothesis/investigating, or kill as \`insufficient_impact\` / \`environmental_issue\`.
+If you cannot name a concrete attacker who gains something they should not have -> do **not** confirm. Stay INVESTIGATING or KILL with documented reason.
 
-**Non-applicable / weak-impact defaults (KILL or do not promote):**
-- Self-XSS / self-DoS only (attacker harms only their own session/account)
-- Requires admin/root/already-trusted role that already has the same power
-- Local-only, offline, or impossible deployment assumptions
-- Spec-compliant / documented intentional behavior
-- Needs physical access, victim to paste payload into their own console, or other social-engineering-only steps with no trust-boundary break
-- "Interesting" logic quirks with **no confidentiality, integrity, availability, or financial effect**
-- PoC proves a code path exists but **not** that a real victim asset is affected
+### 1. Disconfirmation Attempt (mandatory field before CONFIRMED)
 
-Technical validity ≠ bounty validity. A true bug with no attacker-usable impact is still a kill for confirmed/report.
+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.
 
----
+**What a disconfirmation attempt looks like:**
 
-## 1. Evidence-First Doctrine
-Evidence overrides intuition. Never present speculation as fact. Every security claim must be traceable to:
-- Observed behavior (logs, responses, error traces)
-- Reproduced behavior (exact steps, scripts)
-- Source code / protocol analysis
-- Documented platform behavior
-If evidence is insufficient: state uncertainty, propose the next experiment, do not escalate. Never assume success where verification is incomplete.
+- 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
+2. How you did it (conditions, inputs, target)
+3. What result you got (if it failed to disprove, that's the expected outcome)
+4. Why you believe the disconfirmation attempt was valid
 
-## 2. Impact Gate (Mandatory Before CONFIRMED)
+**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."
 
-Prove at least **one** real attacker-facing violation:
+**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.
+
+### 2. Production Path Verification (must be in impact field)
+
+The **impact** field for CONFIRMED must explicitly answer:
+
+1. **Target environment:** Which host/repo/instance was this tested against? (prod, staging, dev, local?)
+2. **Production protections:** What protections exist in production that could block this path? (WAF, CSRF tokens, CORS, CSP, rate limiting, network segmentation, auth, feature flags, admin-only access)
+3. **Bypass verification:** For each protection, have you confirmed it is bypassed or absent?
+4. **Target comparison:** If tested against dev/staging/local, what differs in production that could affect exploitability? Have you verified the path still works in the production configuration?
+
+**Weak impact that fails this gate:**
+- "Attacker can read files" without specifying which target and whether protections block it
+- "This works on localhost" without verifying production differences
+- "The code path exists" without proving a real victim asset is reachable
+- "Could be dangerous" or "may lead to RCE" without a concrete production path
+
+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
+
+Documented intended behavior
+- Self-XSS / self-DoS only (attacker harms only their own session)
+- Requires admin/root role that already has the same power
+- Local-only, offline, or impossible deployment assumptions
+- Needs physical access, social engineering with no trust-boundary break
+- No C/I/A/financial effect for anyone but the attacker
+- 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
+
+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
+
+Prove at least **one** real attacker-facing violation against a production-viable target:
 
 | Category | Required proof |
 |----------|----------------|
-| **Confidentiality** | Attacker reads data they must not see (other users/tenants/secrets) |
+| **Confidentiality** | Attacker reads data they must not see |
 | **Integrity** | Attacker changes data/state they must not control |
-| **Availability** | Attacker degrades service for **others** (not only self) |
+| **Availability** | Attacker degrades service for **others** |
 | **Financial / authz** | Direct money, privilege, or account takeover path |
 
-Impact text must answer: *who is hurt, what is lost, how the attacker reaches it.*  
-Vague impact like "could be dangerous" or "may lead to RCE" without a path is not impact_proof.
+Impact text must answer: *who is hurt, what is lost, how the attacker reaches it from production.*
 
-If impact is only theoretical, needs a second unproven bug, or is not yet capable from the attacker's seat → stay INVESTIGATING (chain it) or KILL \`insufficient_impact\`. Do **not** confirm "valid but non-applicable" findings.
+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
 
-## 3. Adversarial Self-Review (Mandatory Before CONFIRMED)
-Argue against yourself:
-1. Why this might NOT be a vulnerability (intended, sandbox, misconfig, already authorized).
+1. Why this might NOT be a vulnerability.
 2. Alternative explanations for the observation.
 3. Why each alternative was rejected **with evidence**.
-4. What blocks a real attacker today (auth, CSRF, network, role checks) and whether each is bypassed.
-5. Would a program triage say "informative / N/A" because impact is self-only or privileged-only?
+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?
 
----
-
-## 4. False Positive / Non-Applicable Kill Checklist
-KILL immediately when any apply:
-- Matches documented/spec behavior (\`intended_behavior\`)
-- Browser quirk, test artifact, or cache noise
-- Framework/middleware/WAF blocks the path and is not bypassed (\`framework_protection\`)
-- Requires privileges the attacker already has or cannot obtain (\`environmental_issue\`)
-- No C/I/A/financial effect for anyone but the attacker themselves (\`insufficient_impact\`)
-- Exploit unreliable / not reproducible twice (\`exploit_unreliable\`)
-- Duplicate of an existing case (\`duplicate\`)
+### 6. Root Cause -> Boundary -> Impact
 
----
-
-## 5. Root Cause → Boundary → Impact (Not Behavior → Hype)
-Trace:
 \`\`\`
-Entry (attacker-controlled) ──→ Reachable code path ──→ Trust boundary crossed ──→ Victim impact
+Entry (attacker-controlled) -> Code path -> Trust boundary crossed -> Victim impact
 \`\`\`
-- Minimum: reproduce successfully at least twice or via two independent methods.
-- Record: **Observed Facts**, **Assumptions**, **Unknowns**, **Experiments Remaining**.
-- If the bug is only a **primitive** (e.g. open redirect, limited SSRF, info leak of non-sensitive data), either chain to high impact or keep severity honest — do not inflate.
-
----
 
-## 6. Duplicate Check
-Before CaseAdd:
-- Is this new?
-- Same root cause as an open case?
-- Multiple endpoints, one bug?
-Continue the existing case ID when scope matches.
+Reproduce at least twice or via two methods.
 
 ---
 
-## 7. Report-Readiness Gate
-Before REPORTED:
+## At REPORT (before advancing to REPORTED)
+
 - Another researcher can reproduce deterministically
-- Steps are complete and production-realistic
-- Impact is justified without inflation (would the vendor agree?)
-- Root cause and fix guidance are concrete
-- Attacker model + victim impact are explicit in the write-up
+- Steps realistic in production
+- Impact justified without inflation (would the vendor agree?)
+- Root cause + fix guidance are concrete
+- Attacker model + victim impact + target explicit
 
 ---
 
-## 8. Permanent KILLED Cataloging
-Keep killed reasons explicit in assumptions/blockers:
-- \`intended_behavior\`
-- \`duplicate\`
-- \`framework_protection\`
-- \`exploit_unreliable\`
-- \`insufficient_impact\`
-- \`environmental_issue\`
-- \`not_applicable\` (true bug / interesting behavior, no realistic attacker value)
-Documenting kills prevents re-opening dead ends.
+## KILLED cataloging
 
----
+When a case is definitively dead (not "I don't know yet"), record the reason:
+- intended_behavior / duplicate / framework_protection
+- exploit_unreliable / insufficient_impact / environmental_issue
+- not_applicable (true bug / interesting behavior, no realistic attacker value)
 
-## 9. Tool Ecosystem (USE PROACTIVELY)
-
-You have offensive tools beyond casefile. Use them — do not rely on memory or guesswork.
-
-| Tool | When to use | Do NOT skip it when... |
-|------|------------|------------------------|
-| **ExploitSearch** | Before writing any PoC. Search for known techniques, bypasses, and attack primitives relevant to the target stack/vuln class. | ...you are investigating a hypothesis or building a PoC. Ground your approach in real write-ups, not memory. |
-| **web_search** | To find CVEs, advisories, prior bug reports, documentation, or any live information about the target. | ...you need to check if a vulnerability is known, find version-specific issues, or research a technology. |
-| **web_fetch** | To read full page content from a URL you already have (advisory, write-up, target page). | ...you have a specific URL to inspect. |
-| **context7** | To look up current library/framework API docs and behavior. | ...you need to understand how a framework feature works (auth, parsing, routing). |
-| **deepwiki** | To ask questions about a public GitHub repository's architecture and internals. | ...the target is an open-source project and you need to understand its design. |
-| **codebase-memory-mcp** | To index a codebase and trace source-to-sink paths. index_repository, get_architecture, search_graph, trace_path. | ...you have access to the target source code and need structural reachability analysis. |
-
-**pdtm CLI tools** (run via bash; each takes auth/flags differently — read the flags, do not guess):
-- subfinder -d host (-silent, -t threads) — passive subdomain enum from API sources; no target auth. Pipe to httpx, not straight to nuclei.
-- httpx -u <url> / -l hosts.txt (-t threads, -td tech-detect, -mc match-status, -H "Name: Value") — fast probe of authed endpoints; supports Header/Cookie/Bearer.
-- ffuf -u <url> -w wordlist (-t threads, -rate, -H "..." -b "c=v", -mc/-fs filters) — authed fuzzing / content discovery.
-- whatweb <url> (-a aggression 1-4, -t threads, --cookie) — tech fingerprint; positional URL, no -u.
-- naabu -host <ip> / -l (-p ports, -rate, -c top-ports) — port scan; hosts, not web-auth.
-- katana -u <url> / -list (-d depth, -jc js-crawl, -H "...") — crawl.
-- nuclei -l hosts.txt / -u <url> (-tags, -severity, -type http, -silent; -c threads -bs host-batch -rl rate-limit -timeout 5 -retries 0): FAST when filtered, slow only if naive.
-  - Do not run all 9000+ templates. Filter: -tags cve,exposure,rce -severity critical,high -type http -t http/misconfiguration/.
-  - Pre-filter targets: subfinder -> httpx -mc 200,403 -> nuclei (cuts ~80% of work).
-  - Tune: -c 100-200 -bs 50-100 -rl 300 (avoid Cloudflare tarpit) -timeout 5 -retries 0 -mhe 10.
-  - Many hosts: -scan-strategy host-spray (v3). Few hosts many templates: template-spray.
-
-**Default behavior when XP mode is ON:**
-1. Start recon with ExploitSearch + web_search before diving into code.
-2. Use context7/deepwiki to understand framework internals before claiming a vuln.
-3. Use codebase-memory-mcp (if available) to prove reachability structurally.
-4. Log everything to casefile (CaseAdd/CaseUpdate). Do not skip the ledger.
+Documenting kills prevents re-opening dead ends. Cases with unresolved unknowns should stay INVESTIGATING, not killed.
 `.trim();