root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
gsxdsm
2026-05-29 08:25:38 -07:00
parent 23e0593cb1
commit 71e2aec5b7
24 changed files with 817 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/cli/src/__tests__/bin.test.ts
View File

@@ -59,6 +59,7 @@ const commandMocks = vi.hoisted(() => ({
runGoalsList: vi.fn(),
runGoalsCreate: vi.fn(),
runGoalsArchive: vi.fn(),
runGoalsCitations: vi.fn(),
runProjectList: vi.fn(),
runProjectAdd: vi.fn(),
@@ -177,6 +178,7 @@ vi.mock("../commands/goals.js", () => ({
runGoalsList: commandMocks.runGoalsList,
runGoalsCreate: commandMocks.runGoalsCreate,
runGoalsArchive: commandMocks.runGoalsArchive,
runGoalsCitations: commandMocks.runGoalsCitations,
}));
vi.mock("../commands/project.js", () => ({

82
packages/cli/src/__tests__/goals-citations-cli.test.ts Normal file
View File

@@ -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.");
});
});

19
packages/cli/src/bin.ts
View File

@@ -127,7 +127,7 @@ async function loadCommandHandlers() {
const { runBackupCreate, runBackupList, runBackupRestore, runBackupCleanup } = await import("./commands/backup.js");
const { runMemoryBackupCreate, runMemoryBackupList, runMemoryBackupRestore } = await import("./commands/memory-backup.js");
const { runMissionCreate, runMissionList, runMissionShow, runMissionDelete, runMissionActivateSlice } = await import("./commands/mission.js");
const { runGoalsList, runGoalsCreate, runGoalsArchive } = await import("./commands/goals.js");
const { runGoalsList, runGoalsCreate, runGoalsArchive, runGoalsCitations } = await import("./commands/goals.js");
const { runProjectList, runProjectAdd, runProjectRemove, runProjectShow, runProjectInfo, runProjectSetDefault, runProjectDetect } = await import("./commands/project.js");
const { runNodeList, runNodeConnect, runNodeDisconnect, runNodeShow, runNodeHealth, runMeshStatus } = await import("./commands/node.js");
const { runInit } = await import("./commands/init.js");
@@ -196,6 +196,7 @@ async function loadCommandHandlers() {
runGoalsList,
runGoalsCreate,
runGoalsArchive,
runGoalsCitations,
runProjectList,
runProjectAdd,
runProjectRemove,
@@ -316,6 +317,7 @@ PR:
fn goals list [--status STATE] List goals (default: active)
fn goals create [title] [desc] Create a new goal
fn goals archive <id> Archive a goal
fn goals citations [flags] List recorded goal-ID citations across agent logs and task documents (Slice 2 success signal)
fn project list | ls [--json] List all registered projects
fn project add [name] [path] [opts] Register a new project
fn project remove | rm <name> [--force]
@@ -603,6 +605,7 @@ async function main() {
runGoalsList,
runGoalsCreate,
runGoalsArchive,
runGoalsCitations,
runProjectList,
runProjectAdd,
runProjectRemove,
@@ -1367,9 +1370,21 @@ async function main() {
await runGoalsArchive(id, projectName);
break;
}
case "citations": {
const goalId = getFlagValue(args, "--goal");
const agentId = getFlagValue(args, "--agent");
const surface = getFlagValue(args, "--surface") as "agent_log" | "task_document" | undefined;
const since = getFlagValue(args, "--since");
const until = getFlagValue(args, "--until");
const limitValue = getFlagValue(args, "--limit");
const limit = limitValue ? Number(limitValue) : undefined;
const json = args.includes("--json");
await runGoalsCitations(projectName, { goalId, agentId, surface, since, until, limit, json });
break;
}
default:
console.error(`Unknown subcommand: goals ${subcommand || ""}`);
console.log("Try: fn goals list | create | archive");
console.log("Try: fn goals list | create | archive | citations");
process.exit(1);
}
break;

43
packages/cli/src/commands/goals.ts
View File

@@ -1,4 +1,5 @@
import { createInterface } from "node:readline/promises";
import type { GoalCitationSurface } from "@fusion/core";
import { getStore } from "../project-resolver.js";
type GoalStatusFilter = "active" | "archived" | "all";
@@ -7,6 +8,16 @@ interface RunGoalsListOptions {
status?: GoalStatusFilter;
}
interface RunGoalsCitationsOptions {
goalId?: string;
agentId?: string;
surface?: GoalCitationSurface;
since?: string;
until?: string;
limit?: number;
json?: boolean;
}
const ACTIVE_SOFT_WARNING_THRESHOLD = 3;
const ACTIVE_HARD_LIMIT = 5;
@@ -115,6 +126,38 @@ export async function runGoalsCreate(
}
}
export async function runGoalsCitations(
projectName: string | undefined,
opts: RunGoalsCitationsOptions,
): Promise<void> {
const store = await getStore({ project: projectName });
const rows = store.listGoalCitations({
goalId: opts.goalId,
agentId: opts.agentId,
surface: opts.surface,
startTime: opts.since,
endTime: opts.until,
limit: opts.limit ?? 50,
});
if (opts.json) {
console.log(JSON.stringify(rows, null, 2));
return;
}
if (rows.length === 0) {
console.log("No goal citations match the filter.");
return;
}
for (const row of rows) {
console.log(`${row.timestamp} ${row.goalId} ${row.agentId} ${row.surface} ${row.sourceRef}`);
console.log(` ${row.snippet}`);
}
console.log(`\n${rows.length} citation(s).`);
}
export async function runGoalsArchive(idArg: string | undefined, projectName?: string): Promise<void> {
if (!idArg) {
console.error("Usage: fn goals archive <id>");