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

10
packages/core/src/__tests__/db-migrate.test.ts
View File

@@ -715,7 +715,7 @@ describe("schema migration", () => {
const row = db.prepare("SELECT deletedAt FROM tasks WHERE id = 'FN-legacy'").get() as { deletedAt: string | null };
expect(row.deletedAt).toBeNull();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
db.close();
});
@@ -748,7 +748,7 @@ describe("schema migration", () => {
{ id: "WS-001", mode: "prompt", gateMode: "advisory" },
{ id: "WS-002", mode: "script", gateMode: "advisory" },
]);
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
db.close();
});
@@ -798,7 +798,7 @@ describe("schema migration", () => {
reviewerContextRetryCount: 0,
reviewerFallbackRetryCount: 0,
});
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
db.close();
});
@@ -827,7 +827,7 @@ describe("schema migration", () => {
const columns = db.prepare("PRAGMA table_info(milestones)").all() as Array<{ name: string }>;
expect(columns.map((column) => column.name)).toContain("acceptanceCriteria");
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
db.close();
});
@@ -862,7 +862,7 @@ describe("schema migration", () => {
{ id: "WS-002", mode: "script", enabled: 1, gateMode: "advisory" },
{ id: "WS-003", mode: "prompt", enabled: 0, gateMode: "advisory" },
]);
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
db.close();
});

34
packages/core/src/__tests__/db.test.ts
View File

@@ -330,7 +330,7 @@ describe("Database", () => {
});
it("seeds schema version", () => {
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
});
it("includes tokenUsageCacheWriteTokens on freshly initialized tasks table", () => {
@@ -373,7 +373,7 @@ describe("Database", () => {
it("is idempotent - calling init() twice does not fail", () => {
expect(() => db.init()).not.toThrow();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
});
it("does not overwrite existing config on re-init", () => {
// Update the config
@@ -1443,7 +1443,7 @@ describe("schema migrations", () => {
db.init();
// Verify version bumped to 29 (includes v1→v2 through v26→v29)
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
// Verify new columns exist and existing data is intact
const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
@@ -1468,11 +1468,11 @@ describe("schema migrations", () => {
const db = new Database(fusionDir);
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
// Re-init should not fail
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
db.close();
});
@@ -1507,7 +1507,7 @@ describe("schema migrations", () => {
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
expect(cols.map((col) => col.name)).toContain("priority");
@@ -1548,7 +1548,7 @@ describe("schema migrations", () => {
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
const colNames = cols.map((col) => col.name);
@@ -1620,7 +1620,7 @@ describe("schema migrations", () => {
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
const colNames = cols.map((col) => col.name);
@@ -1860,7 +1860,7 @@ describe("schema migrations", () => {
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
const cols = db.prepare("PRAGMA table_info(chat_messages)").all() as Array<{ name: string }>;
expect(cols.map((col) => col.name)).toContain("attachments");
@@ -1934,7 +1934,7 @@ describe("schema migrations", () => {
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = 'agentRatings'").all() as Array<{ name: string }>;
expect(tables).toEqual([{ name: "agentRatings" }]);
@@ -1958,7 +1958,7 @@ describe("schema migrations", () => {
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = 'mission_events'").all() as Array<{ name: string }>;
expect(tables).toEqual([{ name: "mission_events" }]);
@@ -2062,7 +2062,7 @@ describe("schema migrations", () => {
db.init();
// Verify version bumped to 29
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
// Verify new columns exist and existing data is intact
const cols = db.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
@@ -2281,7 +2281,7 @@ describe("schema migrations", () => {
localDb.init();
expect(localDb.getSchemaVersion()).toBe(92);
expect(localDb.getSchemaVersion()).toBe(93);
const columns = localDb.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
expect(columns.map((column) => column.name)).toContain("tokenUsageCacheWriteTokens");
@@ -2592,7 +2592,7 @@ describe("createDatabase factory", () => {
const db = createDatabase(fusionDir);
db.init();
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
expect(db.getLastModified()).toBeGreaterThan(0);
db.close();
@@ -2746,7 +2746,7 @@ describe("migration v77 task token budget columns", () => {
migrated = new Database(fusion);
migrated.init();
expect(migrated.getSchemaVersion()).toBe(92);
expect(migrated.getSchemaVersion()).toBe(93);
const rows = migrated.prepare("PRAGMA table_info(tasks)").all() as Array<{ name: string }>;
const names = new Set(rows.map((row) => row.name));
expect(names.has("tokenBudgetSoftAlertedAt")).toBe(true);
@@ -2792,7 +2792,7 @@ describe("migration v67 drops orphan project auth tables", () => {
migrated = new Database(fusion);
migrated.init();
expect(migrated.getSchemaVersion()).toBe(92);
expect(migrated.getSchemaVersion()).toBe(93);
const tables = migrated
.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'project_auth_%'")
.all() as Array<{ name: string }>;
@@ -2819,7 +2819,7 @@ describe("migration v67 drops orphan project auth tables", () => {
try {
fresh.init();
expect(fresh.getSchemaVersion()).toBe(92);
expect(fresh.getSchemaVersion()).toBe(93);
const tables = fresh
.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'project_auth_%'")
.all() as Array<{ name: string }>;

56
packages/core/src/__tests__/goal-citation-extractor.test.ts Normal file
View File

@@ -0,0 +1,56 @@
import { describe, expect, it } from "vitest";
import {
buildSnippet,
extractGoalCitations,
GOAL_CITATION_SNIPPET_MAX,
} from "../goal-citation-extractor.js";
describe("goal-citation-extractor", () => {
it("extracts simple fixture goal IDs", () => {
const matches = extractGoalCitations("prioritizing per G-FAKE001 today");
expect(matches).toHaveLength(1);
expect(matches[0]?.goalId).toBe("G-FAKE001");
});
it("extracts realistic generated goal IDs", () => {
expect(extractGoalCitations("working against G-MABC-0001-XYZW now")[0]?.goalId).toBe(
"G-MABC-0001-XYZW",
);
});
it("rejects false positives", () => {
expect(extractGoalCitations("FN-5663 g-lowercase GG-NOPE prefixG-X")).toEqual([]);
});
it("deduplicates duplicate IDs and keeps first index", () => {
const text = "G-FAKE001 then later G-FAKE001 again";
const matches = extractGoalCitations(text);
expect(matches).toHaveLength(1);
expect(matches[0]).toEqual({ goalId: "G-FAKE001", index: text.indexOf("G-FAKE001") });
});
it("returns empty for empty/undefined/non-string", () => {
expect(extractGoalCitations("")).toEqual([]);
expect(extractGoalCitations(undefined as unknown as string)).toEqual([]);
expect(extractGoalCitations(42 as unknown as string)).toEqual([]);
});
it("buildSnippet caps length and collapses whitespace", () => {
const text = `before\n\nG-FAKE001\n\nafter`;
const snippet = buildSnippet(text, text.indexOf("G-FAKE001"));
expect(snippet.length).toBeLessThanOrEqual(GOAL_CITATION_SNIPPET_MAX);
expect(snippet).toContain("G-FAKE001");
expect(snippet).toBe("before G-FAKE001 after");
});
it("buildSnippet handles left/right/short-text edges", () => {
const leftText = "G-LEFT text";
expect(buildSnippet(leftText, 0, 8)).toContain("G-LEFT");
const rightText = "prefix text ending G-RIGHT";
expect(buildSnippet(rightText, rightText.indexOf("G-RIGHT"), 12)).toContain("G-RIGHT");
const shortText = "tiny G-SHORT";
expect(buildSnippet(shortText, shortText.indexOf("G-SHORT"), 200)).toBe("tiny G-SHORT");
});
});

175
packages/core/src/__tests__/goal-citations-store.test.ts Normal file
View File

@@ -0,0 +1,175 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import * as extractor from "../goal-citation-extractor.js";
import { createTaskStoreTestHarness } from "./store-test-helpers.js";
describe("goal citations store integration", () => {
const harness = createTaskStoreTestHarness();
beforeEach(async () => {
await harness.beforeEach();
});
afterEach(async () => {
vi.restoreAllMocks();
await harness.afterEach();
});
it("records agent_log citations for goal IDs", async () => {
const store = harness.store();
const task = await store.createTask({ title: "Task", description: "desc" });
await store.appendAgentLog(task.id, "working on G-FAKE001 now", "text", undefined, "executor");
(store as any).flushAgentLogBuffer();
const rows = store.listGoalCitations({ goalId: "G-FAKE001" });
expect(rows).toHaveLength(1);
expect(rows[0]).toMatchObject({
goalId: "G-FAKE001",
agentId: "executor",
taskId: task.id,
surface: "agent_log",
});
expect(rows[0]?.sourceRef).toMatch(/^agentLog:/);
});
it("does not record citations for near-miss log text", async () => {
const store = harness.store();
const task = await store.createTask({ title: "Task", description: "desc" });
await store.appendAgentLog(task.id, "text with FN-9999 only", "text", undefined, "executor");
(store as any).flushAgentLogBuffer();
expect(store.listGoalCitations()).toHaveLength(0);
});
it("records task_document citations and sourceRef shape", async () => {
const store = harness.store();
const task = await store.createTask({ title: "Task", description: "desc" });
await store.upsertTaskDocument(task.id, {
key: "notes",
content: "check G-ALPHA and G-BETA now",
author: "agent",
});
const rows = store.listGoalCitations({ surface: "task_document" });
expect(rows).toHaveLength(2);
expect(rows.every((row) => row.sourceRef.startsWith(`document:${task.id}:notes:rev1`))).toBe(true);
});
it("records citations from appendAgentLogBatch seam", async () => {
const store = harness.store();
const task = await store.createTask({ title: "Task", description: "desc" });
await store.appendAgentLogBatch([
{ taskId: task.id, text: "tracking G-BATCH001", type: "text", agent: "executor" },
]);
const rows = store.listGoalCitations({ goalId: "G-BATCH001" });
expect(rows).toHaveLength(1);
expect(rows[0]).toMatchObject({ surface: "agent_log", agentId: "executor", taskId: task.id });
});
it("deduplicates goal citations per goalId+surface+sourceRef", () => {
const store = harness.store();
const inserted = store.recordGoalCitations([
{
goalId: "G-DUP",
agentId: "agent-1",
taskId: "FN-1",
surface: "task_document",
sourceRef: "document:FN-1:plan:rev3",
snippet: "mentions G-DUP",
},
{
goalId: "G-DUP",
agentId: "agent-1",
taskId: "FN-1",
surface: "task_document",
sourceRef: "document:FN-1:plan:rev3",
snippet: "mentions G-DUP",
},
]);
expect(inserted).toHaveLength(1);
expect(store.listGoalCitations({ goalId: "G-DUP" })).toHaveLength(1);
});
it("re-upserting same citation source is deduped", async () => {
const store = harness.store();
const task = await store.createTask({ title: "Task", description: "desc" });
await store.upsertTaskDocument(task.id, {
key: "plan",
content: "first G-SAME",
author: "agent",
});
const firstRows = store.listGoalCitations({ goalId: "G-SAME" });
expect(firstRows).toHaveLength(1);
const insertedAgain = store.recordGoalCitations([
{
goalId: "G-SAME",
agentId: "agent",
taskId: task.id,
surface: "task_document",
sourceRef: `document:${task.id}:plan:rev1`,
snippet: "G-SAME",
},
]);
expect(insertedAgain).toHaveLength(0);
});
it("filters by goal and time window in descending timestamp order", () => {
const store = harness.store();
store.recordGoalCitations([
{
goalId: "G-WIN",
agentId: "agent-1",
surface: "agent_log",
sourceRef: "agentLog:1",
snippet: "G-WIN older",
timestamp: "2026-01-01T00:00:00.000Z",
},
{
goalId: "G-WIN",
agentId: "agent-1",
surface: "agent_log",
sourceRef: "agentLog:2",
snippet: "G-WIN newer",
timestamp: "2026-01-02T00:00:00.000Z",
},
{
goalId: "G-OTHER",
agentId: "agent-1",
surface: "agent_log",
sourceRef: "agentLog:3",
snippet: "other",
timestamp: "2026-01-02T00:00:00.000Z",
},
]);
const rows = store.listGoalCitations({
goalId: "G-WIN",
startTime: "2026-01-01T12:00:00.000Z",
endTime: "2026-01-03T00:00:00.000Z",
});
expect(rows).toHaveLength(1);
expect(rows[0]?.sourceRef).toBe("agentLog:2");
});
it("does not throw when citation scan fails during appendAgentLog", async () => {
const store = harness.store();
const task = await store.createTask({ title: "Task", description: "desc" });
vi.spyOn(extractor, "extractGoalCitations").mockImplementation(() => {
throw new Error("boom");
});
await expect(store.appendAgentLog(task.id, "G-FAKE001", "text", undefined, "executor")).resolves.toBeUndefined();
expect(() => (store as any).flushAgentLogBuffer()).not.toThrow();
const logs = await store.getAgentLogs(task.id);
expect(logs).toHaveLength(1);
});
});

2
packages/core/src/__tests__/goals-schema.test.ts
View File

@@ -91,6 +91,6 @@ describe("goals schema", () => {
});
it("reports schema version 92", () => {
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
});
});

10
packages/core/src/__tests__/insight-store.test.ts
View File

@@ -1000,7 +1000,7 @@ describe("Migration: pre-33 DB upgrade", () => {
// Step 1: Create a fresh database at v33 (runs all migrations up to 33)
const db1 = createDatabase(legacyDir);
db1.init();
expect(db1.getSchemaVersion()).toBe(92);
expect(db1.getSchemaVersion()).toBe(93);
db1.close();
// Step 2: Manually downgrade to version 32 and drop insight tables
@@ -1035,7 +1035,7 @@ describe("Migration: pre-33 DB upgrade", () => {
expect(tableNamesBefore).not.toContain("project_insight_runs");
// Now run init — this triggers the v32→v33 migration
db3.init();
expect(db3.getSchemaVersion()).toBe(92);
expect(db3.getSchemaVersion()).toBe(93);
// Step 4: Verify insight tables exist after migration
const tablesAfter = db3.prepare(
@@ -1066,12 +1066,12 @@ describe("Migration: pre-33 DB upgrade", () => {
try {
const db1 = createDatabase(testDir);
db1.init();
expect(db1.getSchemaVersion()).toBe(92);
expect(db1.getSchemaVersion()).toBe(93);
db1.close();
const db2 = createDatabase(testDir);
expect(() => db2.init()).not.toThrow();
expect(db2.getSchemaVersion()).toBe(92);
expect(db2.getSchemaVersion()).toBe(93);
db2.close();
} finally {
rmSync(testDir, { recursive: true, force: true });
@@ -1085,7 +1085,7 @@ describe("Migration: pre-33 DB upgrade", () => {
// Step 1: Create a fresh DB and run migrations
const db1 = createDatabase(compatDir);
db1.init();
expect(db1.getSchemaVersion()).toBe(92);
expect(db1.getSchemaVersion()).toBe(93);
// Step 2: Strip lifecycle and cancelledAt columns by recreating the
// table without them. This simulates a DB that was created before the

2
packages/core/src/__tests__/mission-store.test.ts
View File

@@ -2886,7 +2886,7 @@ describe("MissionStore", () => {
describe("Loop State & Validator Run Schema (v31)", () => {
it("schema version is 40 after migration", () => {
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
});
it("mission_features table has loop state columns", () => {

2
packages/core/src/__tests__/run-audit.test.ts
View File

@@ -584,7 +584,7 @@ describe("Run Audit", () => {
});
it("schema version is bumped to 40", () => {
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
});
});
});

6
packages/core/src/__tests__/secrets-schema.test.ts
View File

@@ -42,7 +42,7 @@ describe("secrets schema migrations", () => {
const version = db
.prepare("SELECT value FROM __meta WHERE key = 'schemaVersion'")
.get() as { value: string };
expect(version.value).toBe("92");
expect(version.value).toBe("93");
} finally {
db.close();
rmSync(dir, { recursive: true, force: true });
@@ -105,7 +105,7 @@ describe("secrets schema migrations", () => {
const version = db
.prepare("SELECT value FROM __meta WHERE key = 'schemaVersion'")
.get() as { value: string };
expect(version.value).toBe("92");
expect(version.value).toBe("93");
} finally {
db.close();
rmSync(dir, { recursive: true, force: true });
@@ -155,7 +155,7 @@ describe("secrets schema migrations", () => {
.prepare("SELECT value FROM __meta WHERE key = 'schemaVersion'")
.get() as { value: string };
expect(projectVersion.value).toBe("92");
expect(projectVersion.value).toBe("93");
expect(centralVersion.value).toBe("13");
} finally {
projectDb.close();

2
packages/core/src/__tests__/store-merge-queue.test.ts
View File

@@ -60,7 +60,7 @@ describe("TaskStore merge queue", () => {
expect.arrayContaining(["idx_mergeQueue_lease_ready", "idx_mergeQueue_leaseExpiresAt"]),
);
expect(store.getDatabase().getSchemaVersion()).toBe(92);
expect(store.getDatabase().getSchemaVersion()).toBe(93);
});
it("migrates a legacy v88 database and preserves task rows", async () => {

2
packages/core/src/__tests__/task-documents.test.ts
View File

@@ -51,7 +51,7 @@ describe("TaskStore task documents", () => {
expect(tableNames.has("task_documents")).toBe(true);
expect(tableNames.has("task_document_revisions")).toBe(true);
expect(db.getSchemaVersion()).toBe(92);
expect(db.getSchemaVersion()).toBe(93);
const index = db
.prepare(