feat(FN-5321): add evidence gap detector for external integration manifests

Implements external integration validation (FN-5321) with a manifest validator scaffold, worktrunk manifest wiring, and an evidence gap detector that runs during spec validation and triage; the reviewer also gates on external integration readiness. Includes tests for manifest, evidence gap, and tria

Fusion-Task-Id: FN-5321

packages/engine/src/__tests__/external-integration-manifest.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { validateExternalIntegrationManifest } from "../external-integrations/manifest.js";
+
+describe("validateExternalIntegrationManifest", () => {
+  it("accepts a valid upstream-verified manifest", () => {
+    const result = validateExternalIntegrationManifest({
+      id: "worktrunk",
+      binaryName: "wt",
+      upstreamRepo: "max-sixty/worktrunk",
+      docsUrl: "https://worktrunk.dev/",
+      source: "upstream-verified",
+      version: "0.4.2",
+      verifiedAt: "2026-05-20T00:00:00.000Z",
+      assets: {
+        "linux-x64": {
+          url: "https://github.com/max-sixty/worktrunk/releases/download/v0.4.2/wt-linux-x64.tar.gz",
+          sha256: "a".repeat(64),
+        },
+      },
+    });
+
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("rejects pending manifests with non-empty assets", () => {
+    const result = validateExternalIntegrationManifest({
+      id: "worktrunk",
+      binaryName: "wt",
+      upstreamRepo: "max-sixty/worktrunk",
+      docsUrl: "https://worktrunk.dev/",
+      source: "upstream-pending-verification",
+      version: null,
+      verifiedAt: null,
+      assets: { linux: { url: "https://github.com/max-sixty/worktrunk/releases/download/v0.4.2/x", sha256: "a".repeat(64) } },
+    });
+
+    expect(result).toMatchObject({ ok: false });
+    if (result.ok) throw new Error("expected validation failure");
+    expect(result.missingFields).toContain("assets:must-be-empty-when-pending");
+  });
+
+  it("rejects upstream-verified manifests with empty sha256", () => {
+    const result = validateExternalIntegrationManifest({
+      id: "worktrunk",
+      binaryName: "wt",
+      upstreamRepo: "max-sixty/worktrunk",
+      docsUrl: "https://worktrunk.dev/",
+      source: "upstream-verified",
+      version: "0.4.2",
+      verifiedAt: "2026-05-20T00:00:00.000Z",
+      assets: {
+        linux: {
+          url: "https://github.com/max-sixty/worktrunk/releases/download/v0.4.2/wt-linux-x64.tar.gz",
+          sha256: "",
+        },
+      },
+    });
+
+    expect(result).toMatchObject({ ok: false });
+    if (result.ok) throw new Error("expected validation failure");
+    expect(result.missingFields).toContain("assets.linux.sha256");
+  });
+
+  it("rejects malformed upstreamRepo values", () => {
+    const result = validateExternalIntegrationManifest({
+      id: "cloudflared",
+      binaryName: "cloudflared",
+      upstreamRepo: "cloudflared",
+      docsUrl: "https://developers.cloudflare.com/",
+      source: "upstream-pending-verification",
+      version: null,
+      verifiedAt: null,
+      assets: {},
+    });
+
+    expect(result).toMatchObject({ ok: false });
+    if (result.ok) throw new Error("expected validation failure");
+    expect(result.missingFields).toContain("upstreamRepo");
+  });
+
+  it("rejects asset URLs outside upstream repo and docs host", () => {
+    const result = validateExternalIntegrationManifest({
+      id: "worktrunk",
+      binaryName: "wt",
+      upstreamRepo: "max-sixty/worktrunk",
+      docsUrl: "https://worktrunk.dev/",
+      source: "upstream-verified",
+      version: "0.4.2",
+      verifiedAt: "2026-05-20T00:00:00.000Z",
+      assets: {
+        linux: {
+          url: "https://example.com/download/wt-linux-x64.tar.gz",
+          sha256: "a".repeat(64),
+        },
+      },
+    });
+
+    expect(result).toMatchObject({ ok: false });
+    if (result.ok) throw new Error("expected validation failure");
+    expect(result.missingFields).toContain("assets.linux.url");
+  });
+
+  it("rejects missing required identifiers", () => {
+    const result = validateExternalIntegrationManifest({
+      source: "upstream-pending-verification",
+      version: null,
+      verifiedAt: null,
+      assets: {},
+    });
+
+    expect(result).toMatchObject({ ok: false });
+    if (result.ok) throw new Error("expected validation failure");
+    expect(result.missingFields).toEqual(expect.arrayContaining(["id", "binaryName", "docsUrl"]));
+  });
+
+  it.each([null, undefined, 42, "bad", true])("never throws for garbage input: %p", (input) => {
+    expect(() => validateExternalIntegrationManifest(input)).not.toThrow();
+    const result = validateExternalIntegrationManifest(input);
+    expect(result.ok).toBe(false);
+  });
+});

packages/engine/src/__tests__/external-integrations-registry.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import {
+  KNOWN_EXTERNAL_INTEGRATIONS,
+  validateExternalIntegrationManifest,
+} from "../external-integrations/index.js";
+
+describe("KNOWN_EXTERNAL_INTEGRATIONS contract", () => {
+  it("validates every registry entry", () => {
+    for (const entry of KNOWN_EXTERNAL_INTEGRATIONS) {
+      const result = validateExternalIntegrationManifest(entry);
+      expect(result).toEqual({ ok: true });
+      expect(entry.binaryName).toMatch(/^[a-z][a-z0-9-]{0,31}$/);
+
+      for (const asset of Object.values(entry.assets)) {
+        expect(asset.url).not.toMatch(/github\.com\/([^/]+)\/\1\//);
+        expect(asset.sha256).not.toBe("");
+        expect(asset.sha256).not.toBe("unverified");
+      }
+
+      if (entry.source === "upstream-verified") {
+        for (const asset of Object.values(entry.assets)) {
+          expect(asset.url.includes(entry.upstreamRepo)).toBe(true);
+        }
+      }
+    }
+  });
+
+  it("pins worktrunk to canonical upstream metadata", () => {
+    const worktrunk = KNOWN_EXTERNAL_INTEGRATIONS.find((entry) => entry.id === "worktrunk");
+    expect(worktrunk).toBeDefined();
+    expect(worktrunk?.binaryName).toBe("wt");
+    expect(worktrunk?.upstreamRepo).toBe("max-sixty/worktrunk");
+    expect(worktrunk?.source).toBe("upstream-pending-verification");
+  });
+});

packages/engine/src/__tests__/spec-validation-external-integration-evidence.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { detectExternalIntegrationEvidenceGaps } from "../spec-validation/external-integration-evidence.js";
+
+describe("detectExternalIntegrationEvidenceGaps", () => {
+  it("returns empty findings when prompt has no external integration signals", () => {
+    const prompt = `# Task\n## Mission\nRefactor retry budget counters in scheduler.\n## Steps\n- Update store logic.`;
+    expect(detectExternalIntegrationEvidenceGaps({ promptContent: prompt })).toEqual([]);
+  });
+
+  it("flags FN-5320 style hallucination signals", () => {
+    const fabricatedRepo = ["worktrunk", "worktrunk"].join("/");
+    const prompt = `## Mission\nAdd external integration for worktrunk install flow.\n\n## Steps\n- Install and probe \`worktrunk\` binary.\n- Download from https://github.com/${fabricatedRepo}/releases/latest/download/worktrunk.tar.gz`;
+
+    const findings = detectExternalIntegrationEvidenceGaps({ promptContent: prompt });
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0]?.missing).toEqual(
+      expect.arrayContaining(["canonical-upstream-repo-url", "checksum-or-source-of-truth-evidence"]),
+    );
+  });
+
+  it("accepts a canonical worktrunk evidence set", () => {
+    const prompt = `## Mission\nHarden external binary integration.\n\n## Context to Read First\n- https://github.com/max-sixty/worktrunk\n- https://worktrunk.dev/\n- WORKTRUNK_PINNED_RELEASE\n\n## Steps\n- Probe and run \`wt\` from PATH.\n- Reference releases at https://github.com/max-sixty/worktrunk/releases/latest/download/wt-linux-x64.tar.gz\n- Keep source as upstream-pending-verification until checksums are pinned.`;
+
+    expect(detectExternalIntegrationEvidenceGaps({ promptContent: prompt })).toEqual([]);
+  });
+
+  it("treats duplicate-segment github URLs as missing canonical evidence", () => {
+    const duplicateRepo = ["foo", "foo"].join("/");
+    const prompt = `## Mission\nExternal tool install.\n## Steps\n- download release from https://github.com/${duplicateRepo}/releases/latest/download/foo.tgz\n- run and probe \`foo\``;
+
+    const findings = detectExternalIntegrationEvidenceGaps({ promptContent: prompt });
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings[0]?.missing).toContain("canonical-upstream-repo-url");
+  });
+});

packages/engine/src/__tests__/triage-review-spec-external-integration.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { TaskStore, TaskDetail, Settings } from "@fusion/core";
+import { TriageProcessor } from "../triage.js";
+
+const { mockReviewStep } = vi.hoisted(() => ({ mockReviewStep: vi.fn() }));
+
+vi.mock("../reviewer.js", () => ({ reviewStep: mockReviewStep }));
+
+vi.mock("@fusion/core", async (importOriginal) => {
+  const { createEngineCoreMock } = await import("../test/mockCore.js");
+  return createEngineCoreMock(() => importOriginal<typeof import("@fusion/core")>(), {
+    resolveAgentPrompt: vi.fn().mockReturnValue(null),
+  });
+});
+
+function createMockStore(overrides: Partial<TaskStore> = {}): TaskStore {
+  return {
+    getTask: vi.fn(),
+    listTasks: vi.fn().mockResolvedValue([]),
+    createTask: vi.fn(),
+    moveTask: vi.fn(),
+    updateTask: vi.fn().mockResolvedValue(undefined),
+    deleteTask: vi.fn(),
+    mergeTask: vi.fn(),
+    getSettings: vi.fn().mockResolvedValue({
+      maxConcurrent: 2,
+      maxWorktrees: 4,
+      pollIntervalMs: 10000,
+      groupOverlappingFiles: false,
+      autoMerge: true,
+    } as Settings),
+    updateSettings: vi.fn(),
+    logEntry: vi.fn().mockResolvedValue(undefined),
+    appendAgentLog: vi.fn().mockResolvedValue(undefined),
+    getAgentLogs: vi.fn().mockResolvedValue([]),
+    addSteeringComment: vi.fn(),
+    parseDependenciesFromPrompt: vi.fn().mockResolvedValue([]),
+    parseStepsFromPrompt: vi.fn().mockResolvedValue([]),
+    parseFileScopeFromPrompt: vi.fn().mockResolvedValue([]),
+    on: vi.fn(),
+    emit: vi.fn(),
+    ...overrides,
+  } as unknown as TaskStore;
+}
+
+const mockTaskDetail: TaskDetail = {
+  id: "FN-5321",
+  description: "Test task",
+  column: "triage",
+  dependencies: [],
+  steps: [],
+  currentStep: 0,
+  log: [],
+  createdAt: "2026-01-01T00:00:00.000Z",
+  updatedAt: "2026-01-01T00:00:00.000Z",
+  prompt: "# Task\n",
+  attachments: [],
+  comments: [],
+};
+
+describe("triage fn_review_spec external integration evidence", () => {
+  it("short-circuits to REVISE when evidence is incomplete", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "fusion-triage-ext-evidence-"));
+    try {
+      const taskId = "FN-5321";
+      const promptPath = `.fusion/tasks/${taskId}/PROMPT.md`;
+      await mkdir(join(rootDir, ".fusion", "tasks", taskId), { recursive: true });
+      const fabricatedRepo = ["worktrunk", "worktrunk"].join("/");
+      await writeFile(
+        join(rootDir, promptPath),
+        `## Mission\nAdd third-party external binary integration.\n## Steps\n- install and probe \`worktrunk\` from release URL https://github.com/${fabricatedRepo}/releases/latest/download/worktrunk.tar.gz\n`,
+      );
+
+      const store = createMockStore({ getTask: vi.fn().mockResolvedValue({ ...mockTaskDetail, id: taskId }) });
+      const processor = new TriageProcessor(store, rootDir);
+      const verdictRef = { current: null as any };
+      const tool = (processor as any).createReviewSpecTool(
+        taskId,
+        promptPath,
+        { current: null },
+        { current: null },
+        verdictRef,
+        { current: "" },
+        {},
+        false,
+      );
+
+      const result = await tool.execute({});
+      expect(String(result.content[0]?.text)).toContain("REVISE");
+      expect(String(result.content[0]?.text)).toContain("External-integration evidence gaps");
+      expect(verdictRef.current).toBe("REVISE");
+      expect(mockReviewStep).not.toHaveBeenCalled();
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  it("calls reviewer when evidence is complete", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "fusion-triage-ext-evidence-ok-"));
+    try {
+      const taskId = "FN-5321";
+      const promptPath = `.fusion/tasks/${taskId}/PROMPT.md`;
+      await mkdir(join(rootDir, ".fusion", "tasks", taskId), { recursive: true });
+      await writeFile(
+        join(rootDir, promptPath),
+        "## Mission\nAdd third-party external integration.\n## Context to Read First\n- https://github.com/max-sixty/worktrunk\n- https://worktrunk.dev/\n- WORKTRUNK_PINNED_RELEASE\n## Steps\n- probe and run `wt`\n- release URL: https://github.com/max-sixty/worktrunk/releases/latest/download/wt-linux-x64.tar.gz\n- source: upstream-pending-verification\n",
+      );
+
+      mockReviewStep.mockResolvedValueOnce({ verdict: "APPROVE", summary: "ok", review: "" });
+      const store = createMockStore({ getTask: vi.fn().mockResolvedValue({ ...mockTaskDetail, id: taskId }) });
+      const processor = new TriageProcessor(store, rootDir);
+      const verdictRef = { current: null as any };
+      const tool = (processor as any).createReviewSpecTool(
+        taskId,
+        promptPath,
+        { current: null },
+        { current: null },
+        verdictRef,
+        { current: "" },
+        {},
+        false,
+      );
+
+      const result = await tool.execute({});
+      expect(result.content[0]?.text).toBe("APPROVE");
+      expect(verdictRef.current).toBe("APPROVE");
+      expect(mockReviewStep).toHaveBeenCalledTimes(1);
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+});