FN-5663: add goal-citation audit trail to agent reasoning

Record goal citation evidence so agent reasoning can be traced end-to-end.

- add core goal citation types, extraction helper, persistence schema, and store APIs for citation create/list workflows
- add CLI support and tests for goal citation flows, including command wiring and regression coverage
- update docs and add a published changeset for @runfusion/fusion describing the new audit-trail capability

Files changed:
 .changeset/fn-5663-goal-citation-audit-trail.md    |  10 +
 docs/agents.md                                     |  15 ++
 docs/cli-reference.md                              |   6 +-
 packages/cli/src/__tests__/bin.test.ts             |   2 +
 .../cli/src/__tests__/goals-citations-cli.test.ts  |  82 ++++++++
 packages/cli/src/bin.ts                            |  19 +-
 packages/cli/src/commands/goals.ts                 |  43 +++++
 packages/core/src/__tests__/db-migrate.test.ts     |  10 +-
 packages/core/src/__tests__/db.test.ts             |  34 ++--
 .../src/__tests__/goal-citation-extractor.test.ts  |  56 ++++++
 .../src/__tests__/goal-citations-store.test.ts     | 175 +++++++++++++++++
 packages/core/src/__tests__/goals-schema.test.ts   |   2 +-
 packages/core/src/__tests__/insight-store.test.ts  |  10 +-
 packages/core/src/__tests__/mission-store.test.ts  |   2 +-
 packages/core/src/__tests__/run-audit.test.ts      |   2 +-
 packages/core/src/__tests__/secrets-schema.test.ts |   6 +-
 .../core/src/__tests__/store-merge-queue.test.ts   |   2 +-
 packages/core/src/__tests__/task-documents.test.ts |   2 +-
 packages/core/src/db.ts                            |  51 ++++-
 packages/core/src/goal-citation-extractor.ts       |  56 ++++++
 packages/core/src/index.ts                         |  13 ++
 packages/core/src/store.ts                         | 210 ++++++++++++++++++++-
 packages/core/src/types.ts                         |  51 ++++-
 .../src/store/__tests__/roadmap-store.test.ts      |   4 +-
 24 files changed, 817 insertions(+), 46 deletions(-)

Fusion-Task-Id: FN-5663

Fusion-Task-Lineage: 720f2c4b-4363-464a-a76f-472ec6aca136

packages/cli/src/__tests__/goals-citations-cli.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../project-resolver.js", () => ({
+  getStore: vi.fn(),
+}));
+
+const { getStore } = await import("../project-resolver.js");
+const { runGoalsCitations } = await import("../commands/goals.js");
+
+describe("goals citations cli", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("filters by goal and since/until window", async () => {
+    const listGoalCitations = vi.fn().mockReturnValue([
+      {
+        id: 2,
+        goalId: "G-ONE",
+        agentId: "executor",
+        surface: "agent_log",
+        sourceRef: "agentLog:2",
+        snippet: "G-ONE cited",
+        timestamp: "2026-05-01T00:00:00.000Z",
+      },
+    ]);
+    vi.mocked(getStore).mockResolvedValue({ listGoalCitations } as any);
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await runGoalsCitations(undefined, {
+      goalId: "G-ONE",
+      since: "2026-05-01T00:00:00.000Z",
+      until: "2026-05-31T23:59:59.000Z",
+    });
+
+    expect(listGoalCitations).toHaveBeenCalledWith({
+      goalId: "G-ONE",
+      agentId: undefined,
+      surface: undefined,
+      startTime: "2026-05-01T00:00:00.000Z",
+      endTime: "2026-05-31T23:59:59.000Z",
+      limit: 50,
+    });
+    expect(logSpy).toHaveBeenCalledWith(
+      "2026-05-01T00:00:00.000Z  G-ONE  executor  agent_log  agentLog:2",
+    );
+  });
+
+  it("prints valid json with --json", async () => {
+    const rows = [
+      {
+        id: 1,
+        goalId: "G-JSON",
+        agentId: "agent-1",
+        surface: "task_document",
+        sourceRef: "document:FN-1:plan:rev1",
+        snippet: "G-JSON",
+        timestamp: "2026-01-01T00:00:00.000Z",
+      },
+    ];
+    vi.mocked(getStore).mockResolvedValue({ listGoalCitations: vi.fn().mockReturnValue(rows) } as any);
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await runGoalsCitations(undefined, { json: true });
+
+    const output = logSpy.mock.calls[0]?.[0];
+    expect(() => JSON.parse(String(output))).not.toThrow();
+    expect(JSON.parse(String(output))).toEqual(rows);
+  });
+
+  it("prints empty-state message when no matches", async () => {
+    vi.mocked(getStore).mockResolvedValue({ listGoalCitations: vi.fn().mockReturnValue([]) } as any);
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await runGoalsCitations(undefined, {});
+    expect(logSpy).toHaveBeenCalledWith("No goal citations match the filter.");
+  });
+});