solidity-argus 0.5.7 → 0.5.9

package/AGENTS.md

@@ -12,7 +12,7 @@ CLI: `argus doctor`, `argus init`, `argus install`.
 
 **Role**: Primary security audit orchestrator
 **Description**: Argus Panoptes, the All-Seeing Guardian. Coordinates full Solidity security audits by dispatching Sentinel (analysis), Pythia (research), Scribe (reporting), and Themis (validation). Follows a rigorous 7-step methodology: Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, and Reporting.
-**Model**: anthropic/claude-opus-4-6
+**Model**: anthropic/claude-opus-4-7
 **Tools**: 14 orchestrator-accessible argus_* tools (argus_slither_analyze, argus_analyze_contract, argus_check_patterns, argus_proxy_detection, argus_solodit_search, argus_forge_test, argus_gas_analysis, argus_forge_fuzz, argus_forge_coverage, argus_skill_load, argus_generate_report, argus_record_finding, argus_read_findings, argus_sync_knowledge). `argus_persist_deduped` is reserved for Scribe.
 
 ## sentinel
@@ -39,6 +39,6 @@ CLI: `argus doctor`, `argus init`, `argus install`.
 ## themis
 
 **Role**: Audit quality gate
-**Description**: Independent cross-validation agent running on GPT-5.4 (different LLM provider for reasoning diversity). Validates pipeline integrity: compares raw findings against Scribe's deduped output and the final report. Performs second-opinion research via Solodit and vulnerability skill checklists. Returns a structured verdict to Argus who makes the final decision. Dispatched by Argus after Scribe completes.
-**Model**: openai/gpt-5.4
+**Description**: Independent cross-validation agent running on GPT-5.5 (different LLM provider for reasoning diversity). Validates pipeline integrity: compares raw findings against Scribe's deduped output and the final report. Performs second-opinion research via Solodit and vulnerability skill checklists. Returns a structured verdict to Argus who makes the final decision. Dispatched by Argus after Scribe completes.
+**Model**: openai/gpt-5.5
 **Tools**: argus_read_findings, argus_solodit_search, argus_check_patterns, argus_skill_load, skill

package/README.md

@@ -65,11 +65,11 @@ Argus will automatically:
 
 | Agent | Role | Model |
 |-------|------|-------|
-| `@argus` | Orchestrator — coordinates the full audit | claude-opus-4-6 |
+| `@argus` | Orchestrator — coordinates the full audit | claude-opus-4-7 |
 | `@sentinel` | Static analysis & testing specialist | claude-sonnet-4-6 |
 | `@pythia` | Vulnerability researcher | claude-sonnet-4-6 |
 | `@scribe` | Audit report writer | claude-sonnet-4-6 |
-| `@themis` | Independent audit quality gate | gpt-5.4 |
+| `@themis` | Independent audit quality gate | gpt-5.5 |
 
 ### @argus — The Orchestrator
 Argus Panoptes is the lead auditor. It follows a 7-step methodology (Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, Reporting) and delegates to Sentinel, Pythia, Scribe, and Themis as needed.
@@ -284,11 +284,11 @@ Create `.argus/solidity-argus.jsonc` in your project root. `.opencode/solidity-a
 ```jsonc
 {
   "agents": {
-    "argus": { "model": "anthropic/claude-opus-4-6" },
+    "argus": { "model": "anthropic/claude-opus-4-7" },
     "sentinel": { "model": "anthropic/claude-sonnet-4-6" },
     "pythia": { "model": "anthropic/claude-sonnet-4-6" },
     "scribe": { "model": "anthropic/claude-sonnet-4-6" },
-    "themis": { "model": "openai/gpt-5.4" }
+    "themis": { "model": "openai/gpt-5.5" }
   },
 
   "tools": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 5 specialized agents, 15 tools (14 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",

package/src/agents/argus-prompt.ts

@@ -229,7 +229,7 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
   - **Constraint**: Only invoke Scribe after all analysis and testing are complete.
 
 ### **@themis** (The Quality Gate)
-- **Role**: Independent audit validation using a different LLM provider (GPT-5.4).
+- **Role**: Independent audit validation using a different LLM provider (GPT-5.5).
 - **Tools**: \`argus_read_findings\`, \`argus_solodit_search\`, \`argus_check_patterns\`, \`argus_skill_load\`
 - **Delegation Examples**:
   \`\`\`
@@ -255,7 +255,7 @@ When building the final report or synthesizing findings:
 2. **Secondary source**: Tool transcript text (use only when durable evidence is unavailable or incomplete).
 3. **Never** synthesize findings from ephemeral background transcript retrieval alone if durable state evidence exists.
 4. **Manual-finding durability**: If Argus, Sentinel, or Pythia identifies a finding outside analyzer tool payloads, they must call \
-   \`argus_record_finding\` before proceeding. The JSON payload MUST include \`impact\`, \`recommendation\`, and (for Critical/High) \`proofOfConcept\` fields.
+   \`argus_record_finding\` before proceeding. The JSON payload should include \`impact\`, \`recommendation\`, and \`proofOfConcept\` fields whenever they are known. Missing enrichment is recorded with warnings rather than rejected, but Scribe must enrich final Critical/High findings before reporting.
 5. **Report parity rule**: Scribe must not include findings in \`report_input\` unless they are event-backed (recorded via tools/events).
 
 **Bounded background fan-out**: For deep audits, limit concurrent high-context background delegations to max 2 at a time. Split larger workloads into sequential waves. This prevents retrieval blind spots from simultaneous long-running tasks.
@@ -365,7 +365,7 @@ Your subagents have access to these specialized tools. Know when to delegate eac
   "proofOfConcept": "Steps to reproduce or reference to PoC test"
 }
 \`\`\`
-  - **CRITICAL**: For Critical and High findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. The quality gate will flag findings missing these fields. Preferred field names: \`check\`, \`file\`, \`lines\`. The aliases \`title\`/\`name\` → \`check\` and \`location\` → \`file\` are accepted but canonical names are preferred. Instruct Sentinel and Pythia accordingly when delegating.
+  - **CRITICAL**: For Critical and High final report findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. For any finding with \`source: "slither"\`, preserve the finding even when enrichment is not ready, but add these three fields before final Scribe persistence whenever possible. \`argus_record_finding\` warns on incomplete Slither enrichment instead of dropping the finding. Preferred field names: \`check\`, \`file\`, \`lines\`. The aliases \`title\`/\`name\` → \`check\` and \`location\` → \`file\` are accepted but canonical names are preferred. Instruct Sentinel and Pythia accordingly when delegating.
 
 - **\`argus_sync_knowledge\`**:
   - **Use**: Maintenance.
@@ -527,7 +527,7 @@ Scope: {list of audited files}
 
 STEPS:
 1. Call argus_read_findings with run_id above to load all findings
-2. Deduplicate: group findings by vulnerability class + code location, merge into single entries
+2. Deduplicate: group findings by vulnerability class + code location, merge into single entries. Include \`observation_ids\` on every deduped finding so each raw finding maps to exactly one report entry.
 3. Enrich: for each Critical/High finding, write specific impact and recommendation
 4. Call argus_persist_deduped with run_id and your deduped findings array — this writes the source-of-truth JSON to disk
 5. Call argus_generate_report with run_id, project_name, and scope — the tool reads deduped findings from disk
@@ -538,7 +538,7 @@ Overall risk assessment: {your assessment}
 
 Scribe will:
 1. Read raw findings (may contain duplicates from different tools)
-2. Semantically deduplicate (e.g., merge reentrancy-eth + reentrancy-cei-violation at same location)
+2. Semantically deduplicate (e.g., merge reentrancy-eth + reentrancy-cei-violation at same location) while preserving \`observation_ids\` lineage for every raw finding
 3. Enrich Critical/High findings with specific impact and recommendation text
 4. Persist deduped findings to disk via \`argus_persist_deduped\` (source-of-truth JSON)
 5. Call \`argus_generate_report\` with \`run_id\` — the tool reads from disk and renders markdown

package/src/agents/pythia-prompt.ts

@@ -103,11 +103,12 @@ You have two primary tools. Master them.
   "lines": [startLine, endLine],
   "source": "manual",
   "impact": "Specific impact based on the historical precedent (e.g., 'Total vault drain via flash loan, similar to $X loss in Protocol Y')",
-  "recommendation": "Specific mitigation from the precedent audit report"
+  "recommendation": "Specific mitigation from the precedent audit report",
+  "proofOfConcept": "Steps to reproduce, exploit sketch, or reference to the historical exploit/audit evidence"
 }
 \`\`\`
 
-**CRITICAL**: For Critical and High findings, \`impact\` and \`recommendation\` are MANDATORY. The quality gate will flag findings missing these fields. Use your Solodit research to write specific, precedent-backed impact and recommendation text — not generic placeholders.
+**CRITICAL**: For Critical and High final report findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. \`argus_record_finding\` preserves incomplete findings with warnings rather than dropping them, but Scribe must enrich them before final reporting. Use your Solodit research to write specific, precedent-backed impact, recommendation, and proof-of-concept text — not generic placeholders.
 
 **Interpretation**:
 - A finding is not report-ready until it has been recorded through this tool.

package/src/agents/scribe-prompt.ts

@@ -53,6 +53,7 @@ Argus provides you with a \`run_id\`. Your job: read findings, deduplicate, enri
    - Add "**Detected by:**" listing all tools/checks that flagged it
    - Example: reentrancy-eth + reentrancy-cei-violation + reentrancy-eth-withdraw-state-after-call at VulnerableVault.sol:18-23 → ONE finding
    - **PRESERVATION RULE**: Every raw finding MUST map to exactly one deduped finding. Only merge findings that are genuinely the SAME vulnerability at the SAME location. Different vulnerability classes (e.g., default-visibility vs dos-revert) are SEPARATE findings even if both are Informational. NEVER drop findings during deduplication.
+   - **LINEAGE RULE**: Every deduped finding MUST include \`observation_ids\` containing each raw finding's \`observation_id\`, plus \`observation_count\`, \`sources\`, and \`reported_by_agents\` when available. This lets \`argus_generate_report\` prove raw-to-deduped parity instead of emitting a "Finding parity not verifiable" warning.
 
 3. **Enrich** (MANDATORY for Critical/High):
    - Write specific \`impact\` (concrete consequence, not "could be exploited")
@@ -61,7 +62,7 @@ Argus provides you with a \`run_id\`. Your job: read findings, deduplicate, enri
 
 4. **Persist deduped findings**: Call \`argus_persist_deduped\` with:
    - \`run_id\`: the run ID from Argus
-   - \`deduped_findings\`: JSON array of your deduped and enriched findings
+   - \`deduped_findings\`: JSON array of your deduped and enriched findings, including \`observation_ids\` lineage for every merged raw observation
 
    This writes the source-of-truth JSON to disk at \`.argus/runs/{run_id}/deduped-findings.json\`.
 

package/src/agents/sentinel-prompt.ts

@@ -151,7 +151,7 @@ You have access to a specific set of tools. Use them effectively.
 }
 \`\`\`
 
-**CRITICAL**: For Critical and High findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. The quality gate will flag findings missing these fields. Do not use generic placeholders — be specific to the vulnerability.
+**CRITICAL**: For Critical and High findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. For any finding with \`source: "slither"\`, preserve the finding even when enrichment is not ready, but add these three fields before final Scribe persistence whenever possible. \`argus_record_finding\` warns on incomplete Slither enrichment instead of dropping the finding. Do not use generic placeholders — be specific to the vulnerability.
 
 **Interpretation**:
 - Recording is mandatory before handing findings to Argus for final synthesis.

package/src/agents/themis-prompt.ts

@@ -5,7 +5,7 @@ export const THEMIS_PROMPT = `You are **Themis**, the Quality Gate of Argus Pano
 You are the final validation and review agent in the audit pipeline. You do not run the full audit from scratch and you do not write the final report. You verify that the pipeline output is complete, consistent, and defensible.
 
 Model context:
-- You run on **OpenAI GPT-5.4-pro**.
+- You run on **OpenAI GPT-5.5**.
 - This is intentionally a different provider than the other Argus agents (Claude) to increase reasoning diversity for final quality checks.
 
 Your core responsibilities are:

package/src/cli/commands/doctor.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs"
-import { basename, dirname, extname, join } from "node:path"
+import { homedir } from "node:os"
+import { basename, dirname, extname, join, resolve } from "node:path"
 import { loadArgusConfig } from "../../config/loader"
 import type { ArgusConfig } from "../../config/types"
 import { createLogger } from "../../shared/logger"
@@ -12,6 +13,8 @@ import {
 } from "../../skills/argus-skill-resolver"
 import { parseFrontmatter, validateSkillFrontmatter } from "../../skills/skill-schema"
 import { detectViaIr } from "../../tools/slither-tool"
+import { DEFAULT_SOLODIT_PORT } from "../../tools/solodit-search-tool"
+import { checkSoloditHealth } from "../../utils/solodit-health"
 import { cliOutput } from "../cli-output"
 import type { CliCommand } from "../types"
 
@@ -133,6 +136,143 @@ export function buildSkillHealthReport(
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Install-drift detection
+//
+// OpenCode's plugin resolver walks up the filesystem looking up `node_modules`
+// directories. A stale copy of solidity-argus hoisted to a higher-precedence
+// location (typically `~/.cache/opencode/node_modules/solidity-argus`) will
+// SHADOW the canonical install under `~/.cache/opencode/packages/...`. The
+// shadowing install is loaded silently, leading to confusing failures like
+// `undefined is not an object (evaluating 'result.toLowerCase')` on every MCP
+// call (older versions lacked defensive guards in `tool.execute.after`).
+//
+// This check enumerates known install locations and flags drift.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ArgusInstallSource =
+  | "current"
+  | "hoisted-cache"
+  | "package-cache"
+  | "user-config"
+  | "project-local"
+
+export type ArgusInstall = {
+  source: ArgusInstallSource
+  path: string
+  version: string | null
+}
+
+export type InstallDriftReport = {
+  current: ArgusInstall | null
+  installs: ArgusInstall[]
+  errors: string[]
+  warnings: string[]
+}
+
+function readPackageVersion(packageRoot: string): string | null {
+  try {
+    const raw = readFileSync(join(packageRoot, "package.json"), "utf8")
+    const parsed = JSON.parse(raw) as { version?: unknown }
+    return typeof parsed.version === "string" ? parsed.version : null
+  } catch {
+    return null
+  }
+}
+
+function getCurrentArgusInstall(): ArgusInstall | null {
+  // doctor.ts lives at <packageRoot>/src/cli/commands/doctor.ts
+  const packageRoot = resolve(import.meta.dir, "../../..")
+  if (!existsSync(join(packageRoot, "package.json"))) return null
+  const version = readPackageVersion(packageRoot)
+  return { source: "current", path: packageRoot, version }
+}
+
+export function enumerateArgusInstallCandidates(
+  cwd: string,
+  home: string,
+): Array<{ source: ArgusInstallSource; path: string }> {
+  return [
+    {
+      source: "hoisted-cache",
+      path: join(home, ".cache", "opencode", "node_modules", "solidity-argus"),
+    },
+    {
+      source: "package-cache",
+      path: join(
+        home,
+        ".cache",
+        "opencode",
+        "packages",
+        "solidity-argus@latest",
+        "node_modules",
+        "solidity-argus",
+      ),
+    },
+    {
+      source: "user-config",
+      path: join(home, ".config", "opencode", "node_modules", "solidity-argus"),
+    },
+    {
+      source: "project-local",
+      path: join(cwd, "node_modules", "solidity-argus"),
+    },
+  ]
+}
+
+function findArgusInstalls(cwd: string, home: string): ArgusInstall[] {
+  const installs: ArgusInstall[] = []
+  for (const { source, path } of enumerateArgusInstallCandidates(cwd, home)) {
+    if (existsSync(path)) {
+      installs.push({ source, path, version: readPackageVersion(path) })
+    }
+  }
+  return installs
+}
+
+export function detectInstallDrift(
+  current: ArgusInstall | null,
+  installs: ArgusInstall[],
+): { errors: string[]; warnings: string[] } {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  const hoisted = installs.find((i) => i.source === "hoisted-cache")
+  const pkgCache = installs.find((i) => i.source === "package-cache")
+
+  // Highest-confidence error: hoisted cache shadows the canonical cache with a
+  // DIFFERENT version. OpenCode will load the wrong one.
+  if (hoisted && pkgCache && hoisted.version !== pkgCache.version) {
+    errors.push(
+      `Stale install shadowing canonical version:\n` +
+        `    ${hoisted.path} (v${hoisted.version ?? "unknown"})\n` +
+        `    shadows ${pkgCache.path} (v${pkgCache.version ?? "unknown"}).\n` +
+        `    OpenCode will load v${hoisted.version ?? "unknown"} instead of v${pkgCache.version ?? "unknown"}.\n` +
+        `    Fix: rm -rf "${hoisted.path}"`,
+    )
+    return { errors, warnings }
+  }
+
+  // Lower-confidence: hoisted install drifts from the version the doctor CLI
+  // is itself running as (typical when the user upgraded via bunx/opencode).
+  if (hoisted && current?.version && hoisted.version && hoisted.version !== current.version) {
+    warnings.push(
+      `Possible stale install (drift from running version):\n` +
+        `    ${hoisted.path} (v${hoisted.version}) differs from current (v${current.version}).\n` +
+        `    Fix: rm -rf "${hoisted.path}"`,
+    )
+  }
+
+  return { errors, warnings }
+}
+
+export function buildInstallDriftReport(cwd: string, home: string): InstallDriftReport {
+  const current = getCurrentArgusInstall()
+  const installs = findArgusInstalls(cwd, home)
+  const { errors, warnings } = detectInstallDrift(current, installs)
+  return { current, installs, errors, warnings }
+}
+
 const NON_SKILL_FILENAMES = new Set(["README.md", "INVENTORY.md", "CHANGELOG.md", "LICENSE.md"])
 
 function scanMarkdownFiles(dir: string, maxDepth = 8): string[] {
@@ -237,6 +377,22 @@ export const doctorCommand: CliCommand = {
       cliOutput.log(`${YELLOW}⚠${RESET} Project: no Solidity project detected`)
     }
 
+    const driftReport = buildInstallDriftReport(cwd, homedir())
+    if (driftReport.errors.length === 0 && driftReport.warnings.length === 0) {
+      const versionStr = driftReport.current?.version
+        ? ` (current: v${driftReport.current.version})`
+        : ""
+      cliOutput.log(`${GREEN}✓${RESET} Install drift: none detected${versionStr}`)
+    } else {
+      for (const err of driftReport.errors) {
+        cliOutput.log(`${RED}✗${RESET} Install drift: ${err}`)
+        hasFailure = true
+      }
+      for (const warn of driftReport.warnings) {
+        cliOutput.log(`${YELLOW}⚠${RESET} Install drift: ${warn}`)
+      }
+    }
+
     if (projectType === "foundry" && detectViaIr(cwd)) {
       cliOutput.log(
         `${YELLOW}⚠${RESET} via_ir: enabled in foundry.toml — Slither will use flatten fallback`,
@@ -305,21 +461,13 @@ export const doctorCommand: CliCommand = {
 
     const soloditEnabled = config?.solodit?.enabled !== false
     if (soloditEnabled) {
-      try {
-        const response = await fetch(
-          "https://solodit.cyfrin.io/api/trpc/findings.get?batch=1&input=" +
-            encodeURIComponent(JSON.stringify({ 0: "[]" })),
-          {
-            signal: AbortSignal.timeout(5000),
-          },
-        )
-        if (response.ok) {
-          cliOutput.log(`${GREEN}✓${RESET} Solodit API: reachable`)
-        } else {
-          cliOutput.log(`${YELLOW}⚠${RESET} Solodit API: returned ${response.status}`)
-        }
-      } catch {
-        cliOutput.log(`${YELLOW}⚠${RESET} Solodit API: unreachable`)
+      const port = config?.solodit?.port ?? DEFAULT_SOLODIT_PORT
+      const status = await checkSoloditHealth(port, true)
+      if (status.reachable) {
+        cliOutput.log(`${GREEN}✓${RESET} Solodit MCP: reachable on port ${port}`)
+      } else {
+        const suffix = status.error ? ` (${status.error})` : ""
+        cliOutput.log(`${YELLOW}⚠${RESET} Solodit MCP: unreachable on port ${port}${suffix}`)
       }
     } else {
       cliOutput.log(`${YELLOW}⚠${RESET} Solodit: disabled in config`)

package/src/cli/commands/install.ts

@@ -64,7 +64,8 @@ function addPluginToConfig(configPath: string): { added: boolean; ok: boolean }
 
 export const installCommand: CliCommand = {
   name: "install",
-  description: "Register solidity-argus in your OpenCode config (use --global for ~/.config/opencode)",
+  description:
+    "Register solidity-argus in your OpenCode config (use --global for ~/.config/opencode)",
   async execute(args: string[]): Promise<number> {
     const isGlobal = args.includes("--global") || args.includes("-g")
     const local = localConfigPath()
@@ -85,7 +86,9 @@ export const installCommand: CliCommand = {
       `  Installing globally would write to ${global} and load solidity-argus in EVERY OpenCode session.`,
     )
     cliOutput.warn(`  To install globally on purpose, re-run with: argus install --global`)
-    cliOutput.warn(`  To install for this project, first create an opencode.json in this directory.`)
+    cliOutput.warn(
+      `  To install for this project, first create an opencode.json in this directory.`,
+    )
 
     const proceed = await confirm("Install globally anyway?", false)
     if (!proceed) {

package/src/constants/defaults.ts

@@ -1,9 +1,9 @@
 export const DEFAULT_MODELS = {
-  argus: "anthropic/claude-opus-4-6",
+  argus: "anthropic/claude-opus-4-7",
   sentinel: "anthropic/claude-sonnet-4-6",
   pythia: "anthropic/claude-sonnet-4-6",
   scribe: "anthropic/claude-sonnet-4-6",
-  themis: "openai/gpt-5.4",
+  themis: "openai/gpt-5.5",
 } as const
 
 export const DEFAULT_STEPS = 50 as const

package/src/create-hooks.ts

@@ -14,7 +14,6 @@ import {
   releaseEventSink,
 } from "./features/persistent-state/event-sink"
 import {
-  materializeFindings,
   materializeFindingsForRun,
   materializeReportInput,
 } from "./features/persistent-state/findings-materializer"

package/src/features/persistent-state/findings-materializer.ts

@@ -12,10 +12,7 @@ import type { CanonicalFinding, CanonicalToolExecution, ReportInput } from "../.
 import { SCHEMA_VERSION } from "../../state/schemas"
 import { readEvents } from "./event-sink"
 
-export type MaterializeFindingsTrigger =
-  | "session.idle"
-  | "session.deleted"
-  | "tool.execute.after"
+export type MaterializeFindingsTrigger = "session.idle" | "session.deleted" | "tool.execute.after"
 
 export interface MaterializeFindingsForRunOptions {
   failFast?: boolean

package/src/features/persistent-state/run-finalizer.ts

@@ -83,6 +83,54 @@ function asRecord(value: unknown): Record<string, unknown> | null {
   return null
 }
 
+function isGenerateReportCompletion(event: AuditEvent): boolean {
+  if (event.type !== "tool.completed") return false
+  const payload = asRecord(event.payload)
+  if (!payload) return false
+  return payload.tool === "argus_generate_report" || payload.name === "argus_generate_report"
+}
+
+async function collectReportCompletenessErrors(events: AuditEvent[]): Promise<string[]> {
+  const errors: string[] = []
+  const reportEvents = events.filter(isGenerateReportCompletion)
+
+  for (const event of reportEvents) {
+    const payload = asRecord(event.payload)
+    const filePath = payload?.filePath
+    if (typeof filePath !== "string" || filePath.length === 0) continue
+
+    try {
+      const report = await Bun.file(filePath).text()
+      if (report.includes("## ⚠ Completeness Warning")) {
+        errors.push("generated report contains Completeness Warning")
+      }
+    } catch {
+      // Missing report files are handled by report-generation/tool-tracking gates.
+    }
+  }
+
+  return errors
+}
+
+function collectReportQualityGateErrors(events: AuditEvent[]): string[] {
+  const errors: string[] = []
+  const reportEvents = events.filter(isGenerateReportCompletion)
+
+  for (const event of reportEvents) {
+    const payload = asRecord(event.payload)
+    const qualityGates = asRecord(payload?.qualityGates)
+    if (qualityGates?.passed !== false) continue
+
+    const violations = Array.isArray(qualityGates.violations)
+      ? qualityGates.violations.filter((entry): entry is string => typeof entry === "string")
+      : []
+    const details = violations.length > 0 ? `: ${violations.join("; ")}` : ""
+    errors.push(`generated report failed quality gates${details}`)
+  }
+
+  return errors
+}
+
 function collectParentChildIntegrityErrors(events: AuditEvent[]): string[] {
   const errors: string[] = []
   const parentByChild = new Map<string, string>()
@@ -257,17 +305,25 @@ export async function finalizeRun(
   const hasEventsAfterExistingFinalization =
     existingResult !== null && existingResult.finalizedIndex < events.length - 1
   if (existingResult?.invariantsPassed && !hasEventsAfterExistingFinalization) {
-    return {
-      success: existingResult.success,
-      invariantsPassed: existingResult.invariantsPassed,
-      errors: existingResult.errors,
-      warnings: existingResult.warnings,
-      runId: existingResult.runId,
-      timestamp: existingResult.timestamp,
+    const reportErrors = [
+      ...(await collectReportCompletenessErrors(events)),
+      ...collectReportQualityGateErrors(events),
+    ]
+    if (reportErrors.length === 0) {
+      return {
+        success: existingResult.success,
+        invariantsPassed: existingResult.invariantsPassed,
+        errors: existingResult.errors,
+        warnings: existingResult.warnings,
+        runId: existingResult.runId,
+        timestamp: existingResult.timestamp,
+      }
     }
   }
 
   const { errors, warnings } = collectInvariantErrors(events)
+  errors.push(...(await collectReportCompletenessErrors(events)))
+  errors.push(...collectReportQualityGateErrors(events))
   const invariantsPassed = errors.length === 0
   const sessionId = events.at(-1)?.session_id ?? ""
 

package/src/hooks/config-handler.ts

@@ -185,7 +185,7 @@ export function createConfigHandler(
         mode: "subagent",
         model: argusConfig.agents?.themis?.model ?? DEFAULT_MODELS.themis,
         steps: argusConfig.agents?.themis?.steps ?? DEFAULT_STEPS,
-        description: "Audit quality gate — independent cross-validation (GPT-5.4)",
+        description: "Audit quality gate — independent cross-validation (GPT-5.5)",
         prompt: THEMIS_PROMPT,
         permission: {
           argus_read_findings: "allow",

package/src/state/adapters.ts

@@ -62,6 +62,13 @@ const KNOWN_INPUT_FIELDS = new Set([
   "observationId",
   "observationFingerprint",
   "issueFingerprint",
+  "observation_ids",
+  "observationIds",
+  "observation_count",
+  "observationCount",
+  "reported_by_agents",
+  "reportedByAgents",
+  "sources",
   "elements",
   "location",
 ])
@@ -157,6 +164,20 @@ function pushValidationDiagnostics(errors: ValidationError[]): Diagnostic[] {
   }))
 }
 
+function normalizeStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const strings = value.filter(
+    (item): item is string => typeof item === "string" && item.length > 0,
+  )
+  return strings.length > 0
+    ? Array.from(new Set(strings)).sort((a, b) => a.localeCompare(b))
+    : undefined
+}
+
+function normalizePositiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined
+}
+
 export function normalizeToCanonicalFinding(
   raw: Finding | Record<string, unknown>,
   runId: string,
@@ -288,6 +309,16 @@ export function normalizeToCanonicalFinding(
       observationId,
     })
 
+  const observationIds =
+    normalizeStringArray(input.observation_ids) ?? normalizeStringArray(input.observationIds)
+  const reportedByAgents =
+    normalizeStringArray(input.reported_by_agents) ?? normalizeStringArray(input.reportedByAgents)
+  const sources = normalizeStringArray(input.sources)
+  const observationCount =
+    normalizePositiveInteger(input.observation_count) ??
+    normalizePositiveInteger(input.observationCount) ??
+    observationIds?.length
+
   const canonical: CanonicalFinding = {
     id: observationId,
     check,
@@ -302,6 +333,10 @@ export function normalizeToCanonicalFinding(
     issue_fingerprint: issueFingerprint,
     observation_fingerprint: observationFingerprint,
     observation_id: observationId,
+    observation_ids: observationIds,
+    observation_count: observationCount,
+    reported_by_agents: reportedByAgents,
+    sources,
     impact: typeof input.impact === "string" && input.impact.length > 0 ? input.impact : undefined,
     recommendation:
       typeof input.recommendation === "string" && input.recommendation.length > 0

package/src/tools/persist-deduped-tool.ts

@@ -85,7 +85,7 @@ export const persistDedupedTool = tool({
     deduped_findings: tool.schema
       .string()
       .describe(
-        "Serialized JSON array of deduplicated and enriched findings. Each finding should have: check, severity, confidence, description, file, lines, source, impact, recommendation.",
+        "Serialized JSON array of deduplicated and enriched findings. Each finding should have: check, severity, confidence, description, file, lines, source, impact, recommendation, proofOfConcept, and observation_ids lineage proving which raw findings were merged.",
       ),
   },
   async execute(args, context) {

package/src/tools/record-finding-tool.ts

@@ -28,6 +28,8 @@ type RecordFindingResponse = {
   }>
   schema_version: string
   note: string
+  enrichment_warnings?: string[]
+  enrichment_hint?: string
 }
 
 type ParseResult = { ok: true; data: Record<string, unknown>[] } | { ok: false; error: string }
@@ -79,6 +81,16 @@ function errorResponse(error: string): string {
   })
 }
 
+function collectMissingEnrichmentFields(
+  finding: ReturnType<typeof normalizeToCanonicalFinding>["data"],
+): string[] {
+  const missing: string[] = []
+  if (!isNonEmptyString(finding.impact)) missing.push("impact")
+  if (!isNonEmptyString(finding.recommendation)) missing.push("recommendation")
+  if (!isNonEmptyString(finding.proofOfConcept)) missing.push("proofOfConcept")
+  return missing
+}
+
 export async function executeRecordFinding(
   args: RecordFindingArgs,
   context: ToolContext,
@@ -160,16 +172,21 @@ export async function executeRecordFinding(
     return errorResponse(`Failed to record finding(s): ${errors.join("; ")}`)
   }
 
-  // Warn when Critical/High findings are missing enrichment fields
+  // Warn when report-quality enrichment is missing without dropping findings.
   const enrichmentWarnings: string[] = []
   const HIGH_SEVERITIES = new Set(["Critical", "High"])
   for (const f of findings) {
-    if (!HIGH_SEVERITIES.has(f.severity)) continue
-    const missing: string[] = []
-    if (!f.impact) missing.push("impact")
-    if (!f.recommendation) missing.push("recommendation")
-    if (!f.proofOfConcept) missing.push("proofOfConcept")
+    const missing = collectMissingEnrichmentFields(f)
     if (missing.length > 0) {
+      if (f.source === "slither") {
+        enrichmentWarnings.push(
+          `[${f.severity}] Slither finding ${f.check} in ${f.file} is missing: ${missing.join(", ")}. The finding was recorded, but Scribe must enrich it before final reporting.`,
+        )
+        continue
+      }
+
+      if (!HIGH_SEVERITIES.has(f.severity)) continue
+
       enrichmentWarnings.push(
         `[${f.severity}] ${f.check} in ${f.file} is missing: ${missing.join(", ")}. Quality gate will flag this.`,
       )
@@ -199,7 +216,7 @@ export async function executeRecordFinding(
       ? {
           enrichment_warnings: enrichmentWarnings,
           enrichment_hint:
-            "Critical and High findings MUST include impact, recommendation, and proofOfConcept fields. Re-submit with these fields to pass the quality gate.",
+            "Critical and High findings MUST include impact, recommendation, and proofOfConcept fields. Slither findings should include all three fields before Scribe persists deduped findings; incomplete Slither records are preserved but will be flagged by report quality gates if not enriched downstream.",
         }
       : {}),
   }
@@ -215,13 +232,13 @@ export const recordFindingTool = tool({
       .string()
       .optional()
       .describe(
-        'Serialized JSON object for a single finding. Required fields: check (string, e.g. "reentrancy-eth"), severity (Critical|High|Medium|Low|Informational), confidence (High|Medium|Low), description (string), file (relative path, e.g. "src/Vault.sol"), lines ([startLine, endLine] tuple), source ("manual"). Optional: impact, recommendation, proofOfConcept (mandatory for Critical/High).',
+        'Serialized JSON object for a single finding. Required fields: check (string, e.g. "reentrancy-eth"), severity (Critical|High|Medium|Low|Informational), confidence (High|Medium|Low), description (string), file (relative path, e.g. "src/Vault.sol"), lines ([startLine, endLine] tuple), source ("manual"|"slither"|"pattern"|"scvd"|"solodit"|"fuzz"). Optional: impact, recommendation, proofOfConcept (mandatory for Critical/High final report findings; strongly recommended for Slither-source findings before Scribe persistence).',
       ),
     findings: tool.schema
       .string()
       .optional()
       .describe(
-        "Serialized JSON array of finding objects. Each object requires the same fields as the finding parameter: check, severity, confidence, description, file, lines, source. Aliases title/name → check and location → file are accepted but canonical names are preferred.",
+        "Serialized JSON array of finding objects. Each object requires the same fields as the finding parameter: check, severity, confidence, description, file, lines, source. impact, recommendation, and proofOfConcept are mandatory for Critical/High final report findings and strongly recommended for Slither-source findings before Scribe persistence. Aliases title/name → check and location → file are accepted but canonical names are preferred.",
       ),
   },
   async execute(args, context) {

package/src/tools/report-generator-tool.ts

@@ -627,9 +627,7 @@ function parseReportInputPayload(
             dedupedArtifact.findings,
             effectiveRunId,
             projectDir,
-            typeof dedupedArtifact.deduped_by === "string"
-              ? dedupedArtifact.deduped_by
-              : "scribe",
+            typeof dedupedArtifact.deduped_by === "string" ? dedupedArtifact.deduped_by : "scribe",
           )
           const merged: Record<string, unknown> = {
             ...baseInput,
@@ -658,10 +656,7 @@ function parseReportInputPayload(
           ) {
             merged.schema_version = SCHEMA_VERSION
           }
-          if (
-            typeof merged.projectDir !== "string" ||
-            (merged.projectDir as string).length === 0
-          ) {
+          if (typeof merged.projectDir !== "string" || (merged.projectDir as string).length === 0) {
             merged.projectDir = projectDir
           }
           if (!Array.isArray(merged.scope)) {
@@ -858,6 +853,38 @@ function sortFindingsDeterministically(findings: Finding[]): Finding[] {
   return [...findings].sort(compareFindingsDeterministically)
 }
 
+function hasDedupLineage(findings: Finding[]): boolean {
+  return findings.some((finding) => {
+    const observationIds = (finding as { observation_ids?: unknown }).observation_ids
+    return Array.isArray(observationIds) && observationIds.length > 0
+  })
+}
+
+function observationIdsForFinding(finding: Finding): string[] {
+  const observationIds = (finding as { observation_ids?: unknown }).observation_ids
+  if (Array.isArray(observationIds)) {
+    return observationIds.filter((id): id is string => typeof id === "string" && id.length > 0)
+  }
+  return typeof finding.observation_id === "string" && finding.observation_id.length > 0
+    ? [finding.observation_id]
+    : []
+}
+
+function compareObservationLineage(
+  eventFindings: Finding[],
+  reportFindings: Finding[],
+): { missing: string[]; extra: string[]; matches: boolean } {
+  const expected = new Set(eventFindings.flatMap(observationIdsForFinding))
+  const actual = new Set(reportFindings.flatMap(observationIdsForFinding))
+  const missing = Array.from(expected)
+    .filter((id) => !actual.has(id))
+    .sort((a, b) => a.localeCompare(b))
+  const extra = Array.from(actual)
+    .filter((id) => !expected.has(id))
+    .sort((a, b) => a.localeCompare(b))
+  return { missing, extra, matches: missing.length === 0 && extra.length === 0 }
+}
+
 export function validateReportQuality(
   findings: Finding[],
   policy: QualityGatePolicy,
@@ -1154,7 +1181,7 @@ export async function executeReportGeneration(
   deps: ReportGenerationDependencies = {},
 ): Promise<ReportGenerationResult> {
   const includeExecutiveSummary = args.include_executive_summary ?? true
-  const threshold = args.severity_threshold ?? "low"
+  const threshold = args.severity_threshold ?? "informational"
   const qualityGatePolicy = args.quality_gate_policy ?? "warn"
   const toolCoveragePolicy = args.tool_coverage_policy ?? "enforce"
   const expectedRunId = resolveExpectedRunId(args, context, deps)
@@ -1230,7 +1257,26 @@ export async function executeReportGeneration(
 
     const eventFindings = dedupeFindingsForFinalOutput(projectFindings(events))
     const inputFindings = dedupeFindingsForFinalOutput(reportInput.findings)
-    const parity = compareIssueFingerprintSets(eventFindings, inputFindings)
+    const hasLineage = hasDedupLineage(reportInput.findings)
+    const shouldCheckParity = eventFindings.length === inputFindings.length || hasLineage
+    const parity = shouldCheckParity
+      ? hasLineage
+        ? compareObservationLineage(projectFindings(events), reportInput.findings)
+        : compareIssueFingerprintSets(eventFindings, inputFindings)
+      : { missing: [], extra: [], matches: true }
+
+    if (!shouldCheckParity) {
+      const unverifiableSummary = `event_findings=${eventFindings.length}, report_findings=${inputFindings.length}`
+      if (preflightPolicy === "strict-fail") {
+        throw new Error(
+          `Preflight failed (strict-fail): finding parity not verifiable (${unverifiableSummary}; missing observation_ids)`,
+        )
+      }
+
+      warningBullets.push(
+        `- Finding parity not verifiable: ${unverifiableSummary}; deduped findings must include observation_ids to prove merged observations were preserved`,
+      )
+    }
 
     if (!parity.matches) {
       const mismatchSummary = `missing=${parity.missing.length}, extra=${parity.extra.length}`
@@ -1241,11 +1287,12 @@ export async function executeReportGeneration(
       }
 
       warningBullets.push(`- Finding parity mismatch: ${mismatchSummary}`)
+      const parityLabel = hasLineage ? "observation IDs" : "issue fingerprints"
       if (parity.missing.length > 0) {
-        warningBullets.push(`- Missing issue fingerprints: ${parity.missing.join(", ")}`)
+        warningBullets.push(`- Missing ${parityLabel}: ${parity.missing.join(", ")}`)
       }
       if (parity.extra.length > 0) {
-        warningBullets.push(`- Extra issue fingerprints: ${parity.extra.join(", ")}`)
+        warningBullets.push(`- Extra ${parityLabel}: ${parity.extra.join(", ")}`)
       }
     }
   } catch (err) {