log_change
Record code changes with session, model, files affected, description, and reason to maintain a persistent change ledger for cross-session coherence.
Instructions
Log a code change to the persistent change ledger. Models MUST call this after modifying files. Enables cross-session coherence.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | ||
| model | Yes | ||
| filesAffected | Yes | ||
| description | Yes | ||
| reason | Yes | ||
| tags | No | ||
| conductorTrack | No | ||
| conductorTask | No |
Implementation Reference
- src/managers/LedgerManager.ts:33-52 (handler)Core handler function that creates a LedgerEntry with context (branch, SHA from git), generates a unique ID, and appends it to the ledger file via FileSystemAccess.
async function logChange(input: LogChangeInput): Promise<LedgerEntry> { const context = await git.getBranchContext(repoDir); const entry: LedgerEntry = { id: `chg_${randomUUID().replace(/-/g, '').slice(0, 12)}`, timestamp: new Date().toISOString(), branch: context.branch, sha: context.sha, sessionId: input.sessionId, model: input.model, filesAffected: input.filesAffected, description: input.description, reason: input.reason, tags: input.tags ?? [], conductorTrack: input.conductorTrack, conductorTask: input.conductorTask, }; await fs.appendLedgerEntry(ledgerPath, entry); return entry; } - src/tools/ledger.tool.ts:5-14 (schema)Zod schema for the log_change tool input: sessionId, model, filesAffected, description, reason, and optional tags/conductorTrack/conductorTask.
export const LogChangeSchema = z.object({ sessionId: z.string().min(1), model: z.string().min(1), filesAffected: z.array(z.string()).min(1), description: z.string().min(1), reason: z.string().min(1), tags: z.array(z.string()).optional(), conductorTrack: z.string().optional(), conductorTask: z.string().optional(), }); - src/tools/ledger.tool.ts:29-34 (registration)Registers the 'log_change' tool on the MCP server with its description, schema, and the async callback that delegates to manager.logChange().
server.tool('log_change', 'Log a code change to the persistent change ledger. Models MUST call this after modifying files. Enables cross-session coherence.', LogChangeSchema.shape, async (args) => { const entry = await manager.logChange(args); return { content: [{ type: 'text' as const, text: JSON.stringify(entry, null, 2) }], }; }); - src/managers/LedgerManager.ts:5-14 (helper)TypeScript interface defining the LogChangeInput type used by the logChange handler.
export interface LogChangeInput { sessionId: string; model: string; filesAffected: string[]; description: string; reason: string; tags?: string[]; conductorTrack?: string; conductorTask?: string; } - src/access/FileSystemAccess.ts:44-47 (helper)Low-level helper that serializes a LedgerEntry as JSON and writes it as a new line (append) to the ledger file.
async function appendLedgerEntry(ledgerPath: string, entry: LedgerEntry): Promise<void> { const line = JSON.stringify(entry) + '\n'; await writeFile(ledgerPath, line, { flag: 'a', encoding: 'utf8' }); }