Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(record): keep who decided, rejected options and code links for decisions

Erene08a0c8523ee
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 61ab437..7d26045 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- Decision detail in the record and the map: nodes take `decidedBy` (`user`, `agent` or `agreed`), `alternatives` (options considered and rejected, with the reason), `commits` and `files`; decision cards show their reason and a short line such as "agreed · 1 commit · 2 options rejected", and the drill-down panel lists the rejected options, the commits and files, who decided, and when the node was recorded and last changed. The `/codelineage:lineage` skill asks the agent to fill them in.
- Map shows where the work left off: `session write` now stamps each node it adds or changes (`touchedAt`, set by the CLI and never taken from agent input), and the map opens the branches down to the nodes the last write of the latest session added or changed, marks each "left off here" and frames that session.
- Claude Code plugin skeleton: the `codelineage` npm package is also the plugin (`.claude-plugin/plugin.json`, bundled `dist/cli.js`), and the repository root carries a `codelineage` marketplace that installs it from npm.
diff --git a/packages/cli/skills/lineage/SKILL.md b/packages/cli/skills/lineage/SKILL.md
index c498512..1bac54a 100644
--- a/packages/cli/skills/lineage/SKILL.md
+++ b/packages/cli/skills/lineage/SKILL.md
@@ -43,7 +43,20 @@ Build one JSON object:
that was made, with the reason in `why`) or `question` (an open question).
- `parent`: the id of the topic the node belongs to, or `null` for a
top-level topic.
- - `title`: up to about ten words. `summary` and `why`: one or two sentences.
+ - `title`: up to about ten words. `summary` and `why`: one or two sentences
+ each; enough that someone returning days later understands it without the
+ conversation.
+ - For a `decision`, also send when known:
+ - `decidedBy`: `"user"` (the user asked for it or picked it), `"agent"`
+ (you decided on your own) or `"agreed"` (you proposed it and the user
+ approved).
+ - `alternatives`: options that were considered and not taken, each as
+ `{ "option": "…", "why": "…" }` with the reason it was rejected, including
+ an approach that was tried and then reverted.
+ - For any node, when the work reached the code:
+ - `commits`: short hashes of the commits that carry it out.
+ - `files`: the main files it touched, relative to the project (a few, not
+ every file).
## Organize the nodes by topic, not by time
diff --git a/packages/cli/src/schema/merge.ts b/packages/cli/src/schema/merge.ts
index a0a452f..1da8dcf 100644
--- a/packages/cli/src/schema/merge.ts
+++ b/packages/cli/src/schema/merge.ts
@@ -59,11 +59,22 @@ export function mergeSession(
return { session: merged, warnings };
}
-const NODE_FIELDS = ["parent", "kind", "title", "summary", "why", "at"] as const;
+const NODE_FIELDS = [
+ "parent",
+ "kind",
+ "title",
+ "summary",
+ "why",
+ "at",
+ "decidedBy",
+ "alternatives",
+ "commits",
+ "files",
+] as const;
/** A resent node that changed nothing keeps its touch time. */
function sameNode(a: LineageNode, b: LineageNode): boolean {
- return NODE_FIELDS.every((field) => a[field] === b[field]);
+ return NODE_FIELDS.every((field) => JSON.stringify(a[field]) === JSON.stringify(b[field]));
}
/** Re-roots nodes whose parent is missing or that sit on a cycle. Mutates in place. */
diff --git a/packages/cli/src/schema/session.ts b/packages/cli/src/schema/session.ts
index 095c110..21ff9df 100644
--- a/packages/cli/src/schema/session.ts
+++ b/packages/cli/src/schema/session.ts
@@ -6,6 +6,15 @@ export const SESSION_SCHEMA = 1;
export const NodeKind = z.enum(["phase", "step", "decision", "question"]);
export type NodeKind = z.infer<typeof NodeKind>;
+/** Who made a decision: the user, the agent alone, or the user approving the agent's proposal. */
+export const DecidedBy = z.enum(["user", "agent", "agreed"]);
+
+/** An option that was considered and not taken, with the reason. */
+export const Alternative = z.object({
+ option: z.string().min(1).max(200),
+ why: z.string().max(500).default(""),
+});
+
export const LineageNode = z.object({
id: Slug,
parent: Slug.nullable().default(null),
@@ -14,6 +23,16 @@ export const LineageNode = z.object({
summary: z.string().max(2000).optional(),
why: z.string().max(2000).optional(),
at: IsoDate.optional(),
+ decidedBy: DecidedBy.optional(),
+ /** Options considered and rejected, mostly for decisions. */
+ alternatives: z.array(Alternative).max(10).optional(),
+ /** Commits that carry this work out, as short or full hashes. */
+ commits: z
+ .array(z.string().regex(/^[0-9a-f]{7,40}$/, "a commit hash"))
+ .max(20)
+ .optional(),
+ /** Files this work touched, relative to the project. */
+ files: z.array(z.string().min(1).max(300)).max(30).optional(),
/** When `session write` first added this node; set by the CLI, never by the agent. */
addedAt: IsoDate.optional(),
/** When `session write` last added or changed this node; set by the CLI, never by the agent. */
diff --git a/packages/cli/src/view/lineage.ts b/packages/cli/src/view/lineage.ts
index d71d3e4..ffab802 100644
--- a/packages/cli/src/view/lineage.ts
+++ b/packages/cli/src/view/lineage.ts
@@ -44,6 +44,10 @@ export function buildNodeTree(nodes: LineageNode[]): ViewNode[] {
...(node.summary === undefined ? {} : { summary: node.summary }),
...(node.why === undefined ? {} : { why: node.why }),
...(node.at === undefined ? {} : { at: node.at }),
+ ...(node.decidedBy === undefined ? {} : { decidedBy: node.decidedBy }),
+ ...(node.alternatives?.length ? { alternatives: node.alternatives } : {}),
+ ...(node.commits?.length ? { commits: node.commits } : {}),
+ ...(node.files?.length ? { files: node.files } : {}),
...(node.addedAt === undefined ? {} : { addedAt: node.addedAt }),
...(node.touchedAt === undefined ? {} : { touchedAt: node.touchedAt }),
children,
diff --git a/packages/cli/src/view/model.ts b/packages/cli/src/view/model.ts
index ad8d152..f36bea9 100644
--- a/packages/cli/src/view/model.ts
+++ b/packages/cli/src/view/model.ts
@@ -20,6 +20,10 @@ export interface ViewNode {
summary?: string;
why?: string;
at?: string;
+ decidedBy?: "user" | "agent" | "agreed";
+ alternatives?: { option: string; why: string }[];
+ commits?: string[];
+ files?: string[];
/** When the node was first added. */
addedAt?: string;
/** When the node was last added or changed; marks where the work left off. */
diff --git a/packages/cli/test/build.test.ts b/packages/cli/test/build.test.ts
index 5e8b84c..e441cf6 100644
--- a/packages/cli/test/build.test.ts
+++ b/packages/cli/test/build.test.ts
@@ -49,6 +49,20 @@ function session(over: Partial<Session> & { sessionId: string }): Session {
}
describe("buildNodeTree", () => {
+ it("carries decision detail into the view and drops empty lists", () => {
+ const [d] = buildNodeTree([
+ node("d", "decision", "D", null, {
+ decidedBy: "user",
+ alternatives: [{ option: "x", why: "y" }],
+ commits: ["abc1234"],
+ files: [],
+ }),
+ ]);
+ expect(d).toMatchObject({ decidedBy: "user", commits: ["abc1234"] });
+ expect(d?.alternatives).toHaveLength(1);
+ expect(d).not.toHaveProperty("files");
+ });
+
it("orders siblings by when their thread began, keeping unstamped ones first and in order", () => {
const t = (h: number) => `2026-10-23T${String(h).padStart(2, "0")}:00:00.000Z`;
const tree = buildNodeTree([
diff --git a/packages/cli/test/schema.test.ts b/packages/cli/test/schema.test.ts
index b40043a..7f1c51b 100644
--- a/packages/cli/test/schema.test.ts
+++ b/packages/cli/test/schema.test.ts
@@ -97,6 +97,32 @@ describe("parseVersioned", () => {
});
describe("mergeSession", () => {
+ it("keeps decision detail and re-stamps only when it changes", () => {
+ const node = {
+ id: "d",
+ kind: "decision",
+ title: "D",
+ decidedBy: "agreed",
+ alternatives: [{ option: "drag to resize", why: "user wanted auto size" }],
+ commits: ["322259a"],
+ files: ["packages/template/src/cardHeight.ts"],
+ };
+ const first = mergeSession(undefined, input({ sessionId: "s1", nodes: [node] }), T0).session;
+ expect(first.nodes[0]).toMatchObject({ decidedBy: "agreed", commits: ["322259a"] });
+ expect(
+ mergeSession(first, input({ sessionId: "s1", nodes: [node] }), T1).session.nodes[0]
+ ?.touchedAt,
+ ).toBe(T0);
+ const more = { ...node, commits: ["322259a", "61d2873"] };
+ expect(
+ mergeSession(first, input({ sessionId: "s1", nodes: [more] }), T1).session.nodes[0]
+ ?.touchedAt,
+ ).toBe(T1);
+ expect(() =>
+ input({ sessionId: "s1", nodes: [{ ...node, commits: ["not-a-hash"] }] }),
+ ).toThrow();
+ });
+
it("stamps nodes when they are added or changed, never from agent input", () => {
const node = { id: "a", kind: "step", title: "A", touchedAt: "2000-01-01T00:00:00.000Z" };
const first = mergeSession(undefined, input({ sessionId: "s1", nodes: [node] }), T0).session;
diff --git a/packages/template/src/Graph.tsx b/packages/template/src/Graph.tsx
index 0417b58..30a0bbb 100644
--- a/packages/template/src/Graph.tsx
+++ b/packages/template/src/Graph.tsx
@@ -23,7 +23,7 @@ import {
useState,
} from "react";
import type { LineageViewModel } from "../../cli/src/view/model.js";
-import { formatDate, formatTime, itemsInside, kindLabel } from "./format.js";
+import { cardMeta, cardText, formatDate, formatTime, itemsInside, kindLabel } from "./format.js";
import { useFullscreen } from "./fullscreen.js";
import {
defaultExpanded,
@@ -149,9 +149,10 @@ function LineageBox({ id, data }: NodeProps<LineageFlowNode>) {
<p className="lineage-count">{itemsInside(data.count)}</p>
) : data.at ? (
<time dateTime={data.at}>{formatTime(data.at)}</time>
- ) : data.summary ? (
- <p title={data.summary}>{data.summary}</p>
+ ) : cardText(data) ? (
+ <p>{cardText(data)}</p>
) : null}
+ {cardMeta(data) ? <p className="card-meta">{cardMeta(data)}</p> : null}
</div>
);
}
diff --git a/packages/template/src/Outline.tsx b/packages/template/src/Outline.tsx
index 6a01ff2..72e9ce5 100644
--- a/packages/template/src/Outline.tsx
+++ b/packages/template/src/Outline.tsx
@@ -1,7 +1,14 @@
import { useEffect, useMemo, useState } from "react";
import type { LineageViewModel, ViewNode, ViewSession } from "../../cli/src/view/model.js";
import { kindLabel } from "./format.js";
-import { countNodes, epochId, nodeId, sessionId, UNASSIGNED_EPOCH_ID } from "./graph.js";
+import {
+ countNodes,
+ epochId,
+ nodeId,
+ sessionId,
+ toNodeDetail,
+ UNASSIGNED_EPOCH_ID,
+} from "./graph.js";
import type { Selection } from "./SidePanel.js";
/**
@@ -135,14 +142,7 @@ function NodeRows({
expand: [epoch, sessionKey],
selection: {
type: "node",
- node: {
- kind: node.kind,
- title: node.title,
- ...(node.summary === undefined ? {} : { summary: node.summary }),
- ...(node.why === undefined ? {} : { why: node.why }),
- ...(node.at === undefined ? {} : { at: node.at }),
- sessionId: rawSessionId,
- },
+ node: toNodeDetail(node, rawSessionId),
},
})
}
diff --git a/packages/template/src/SidePanel.tsx b/packages/template/src/SidePanel.tsx
index 3c7997f..ee48315 100644
--- a/packages/template/src/SidePanel.tsx
+++ b/packages/template/src/SidePanel.tsx
@@ -2,10 +2,7 @@ import { useEffect, useRef, useState } from "react";
import type { LineageViewModel, ViewSession } from "../../cli/src/view/model.js";
import { resumeCommand } from "../../cli/src/view/resume.js";
import { formatTime, kindLabel } from "./format.js";
-import type { LineageData } from "./graph.js";
-
-/** What the drill-down shows of a node; the expand state stays in the graph. */
-export type NodeDetail = Omit<LineageData, "count" | "expanded" | "hasChildren" | "isLast">;
+import type { NodeDetail } from "./graph.js";
/** What the drill-down shows: a graph node or a whole session. */
export type Selection = { type: "node"; node: NodeDetail } | { type: "session"; sessionId: string };
@@ -130,6 +127,12 @@ function SessionSummary({ model, session }: { model: LineageViewModel; session:
);
}
+const DECIDED_LABEL = {
+ user: "You",
+ agent: "The agent, on its own",
+ agreed: "You, approving the agent's proposal",
+} as const;
+
function NodeDetails({ model, node }: { model: LineageViewModel; node: NodeDetail }) {
const session = findSession(model, node.sessionId);
return (
@@ -146,8 +149,46 @@ function NodeDetails({ model, node }: { model: LineageViewModel; node: NodeDetai
<p>{node.why}</p>
</section>
) : null}
+ {node.alternatives?.length ? (
+ <section>
+ <h3>Considered and rejected</h3>
+ <ul className="drilldown-list">
+ {node.alternatives.map((alt) => (
+ <li key={alt.option}>
+ <strong>{alt.option}</strong>
+ {alt.why ? <> — {alt.why}</> : null}
+ </li>
+ ))}
+ </ul>
+ </section>
+ ) : null}
+ {node.commits?.length || node.files?.length ? (
+ <section>
+ <h3>In the code</h3>
+ {node.commits?.length ? (
+ <p className="drilldown-code">
+ {node.commits.map((commit) => (
+ <code key={commit}>{commit}</code>
+ ))}
+ </p>
+ ) : null}
+ {node.files?.length ? (
+ <ul className="drilldown-list">
+ {node.files.map((file) => (
+ <li key={file}>
+ <code>{file}</code>
+ </li>
+ ))}
+ </ul>
+ ) : null}
+ </section>
+ ) : null}
<dl className="drilldown-meta">
- <Field label="Recorded">{formatTime(node.at ?? null)}</Field>
+ {node.decidedBy ? <Field label="Decided by">{DECIDED_LABEL[node.decidedBy]}</Field> : null}
+ <Field label="Recorded">{formatTime(node.at ?? node.addedAt ?? null)}</Field>
+ {node.touchedAt && node.touchedAt !== node.addedAt ? (
+ <Field label="Last changed">{formatTime(node.touchedAt)}</Field>
+ ) : null}
<Field label="Session">
{session ? (
<>
diff --git a/packages/template/src/cardHeight.ts b/packages/template/src/cardHeight.ts
index 49a089c..7901ec9 100644
--- a/packages/template/src/cardHeight.ts
+++ b/packages/template/src/cardHeight.ts
@@ -10,6 +10,7 @@ const FONT_FAMILY = 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-s
const TITLE_FONT = `700 13px ${FONT_FAMILY}`;
const BODY_FONT = `400 11px ${FONT_FAMILY}`;
const KIND_FONT = `400 10px ${FONT_FAMILY}`;
+const META_FONT = `400 10px ${FONT_FAMILY}`;
const TITLE_LINE = 17;
const BODY_LINE = 15;
/** Padding, borders and the gap above the body line. */
@@ -81,6 +82,8 @@ export interface CardText {
/** The line under the title: a summary, a time or an "N items inside" count. */
body?: string;
hasToggle: boolean;
+ /** A small line at the bottom: who decided, commits, rejected options. */
+ meta?: string;
}
export function cardHeight(
@@ -94,5 +97,7 @@ export function cardHeight(
const head = Math.max(HEAD_MIN, titleLines * TITLE_LINE);
const bodyLines = card.body ? countLines(card.body, width - INSET, BODY_FONT, measure) : 0;
const body = bodyLines > 0 ? BODY_GAP + bodyLines * BODY_LINE : 0;
- return Math.ceil(CHROME + head + body + SLACK);
+ const metaLines = card.meta ? countLines(card.meta, width - INSET, META_FONT, measure) : 0;
+ const meta = metaLines > 0 ? BODY_GAP + metaLines * BODY_LINE : 0;
+ return Math.ceil(CHROME + head + body + meta + SLACK);
}
diff --git a/packages/template/src/format.ts b/packages/template/src/format.ts
index b1afdcf..b7a545f 100644
--- a/packages/template/src/format.ts
+++ b/packages/template/src/format.ts
@@ -23,3 +23,29 @@ export function kindLabel(kind: string): string {
export function itemsInside(count: number): string {
return `${count} item${count === 1 ? "" : "s"} inside`;
}
+
+const DECIDED_BY = { user: "you decided", agent: "agent decided", agreed: "agreed" } as const;
+
+/** Who decided, and what more the drill-down holds; empty when there is nothing to say. */
+export function cardMeta(node: {
+ decidedBy?: keyof typeof DECIDED_BY | undefined;
+ commits?: string[] | undefined;
+ alternatives?: unknown[] | undefined;
+}): string {
+ const parts: string[] = [];
+ if (node.decidedBy) parts.push(DECIDED_BY[node.decidedBy]);
+ const commits = node.commits?.length ?? 0;
+ if (commits > 0) parts.push(`${commits} commit${commits === 1 ? "" : "s"}`);
+ const rejected = node.alternatives?.length ?? 0;
+ if (rejected > 0) parts.push(`${rejected} option${rejected === 1 ? "" : "s"} rejected`);
+ return parts.join(" · ");
+}
+
+/** A card's second line: for decisions the reason, otherwise the summary. */
+export function cardText(node: {
+ kind: string;
+ summary?: string | undefined;
+ why?: string | undefined;
+}) {
+ return node.kind === "decision" && node.why ? node.why : node.summary;
+}
diff --git a/packages/template/src/graph.ts b/packages/template/src/graph.ts
index bcffb01..c25d8a2 100644
--- a/packages/template/src/graph.ts
+++ b/packages/template/src/graph.ts
@@ -6,7 +6,7 @@ import ELK, {
} from "elkjs/lib/elk.bundled.js";
import type { LineageViewModel, ViewNode, ViewSession } from "../../cli/src/view/model.js";
import { cardHeight } from "./cardHeight.js";
-import { formatTime, itemsInside, kindLabel } from "./format.js";
+import { cardMeta, cardText, formatTime, itemsInside, kindLabel } from "./format.js";
/**
* Builds the nested React Flow graph (epoch → session → node) and lays it out
@@ -56,19 +56,34 @@ export type SessionData = {
hasChildren: boolean;
};
-export type LineageData = {
+/** Everything the drill-down panel shows about a node. */
+export type NodeDetail = {
kind: ViewNode["kind"];
title: string;
summary?: string;
why?: string;
at?: string;
+ decidedBy?: ViewNode["decidedBy"];
+ alternatives?: ViewNode["alternatives"];
+ commits?: string[];
+ files?: string[];
+ addedAt?: string;
+ touchedAt?: string;
/** Owning session, so the drill-down panel can show and resume it. */
sessionId: string;
+};
+
+export function toNodeDetail(node: ViewNode, sessionId: string): NodeDetail {
+ const { id: _id, children: _children, ...detail } = node;
+ return { ...detail, sessionId };
+}
+
+export type LineageData = NodeDetail & {
/** Nodes nested below this one, at any depth. */
count: number;
expanded: boolean;
hasChildren: boolean;
- /** The most recently added or changed node: where the work left off. */
+ /** One of the nodes the last write added or changed: where the work left off. */
isLast: boolean;
};
@@ -225,7 +240,8 @@ function nodeHeight(node: ViewNode, open: boolean): number {
? itemsInside(countNodes(node.children))
: node.at
? formatTime(node.at)
- : node.summary;
+ : cardText(node);
+ const meta = cardMeta(node);
return Math.max(
NODE_HEIGHT,
cardHeight(
@@ -234,6 +250,7 @@ function nodeHeight(node: ViewNode, open: boolean): number {
title: node.title,
hasToggle: hasChildren,
...(body ? { body } : {}),
+ ...(meta ? { meta } : {}),
},
NODE_WIDTH,
),
@@ -499,12 +516,7 @@ function collectFlowNodes(
connectable: false,
selectable: false,
data: {
- kind: node.kind,
- title: node.title,
- ...(node.summary === undefined ? {} : { summary: node.summary }),
- ...(node.why === undefined ? {} : { why: node.why }),
- ...(node.at === undefined ? {} : { at: node.at }),
- sessionId,
+ ...toNodeDetail(node, sessionId),
count: countNodes(node.children),
expanded: open,
hasChildren: node.children.length > 0,
diff --git a/packages/template/src/styles.css b/packages/template/src/styles.css
index dae4166..101f311 100644
--- a/packages/template/src/styles.css
+++ b/packages/template/src/styles.css
@@ -471,6 +471,12 @@ body:has(.map-shell.is-expanded) {
line-height: 14px;
}
+.lineage-box p.card-meta {
+ font-size: 10px;
+ color: var(--accent);
+ opacity: 0.85;
+}
+
.lineage-box p.lineage-count {
color: var(--accent);
}
@@ -581,6 +587,21 @@ body:has(.map-shell.is-expanded) {
overflow-wrap: anywhere;
}
+.drilldown-list {
+ margin: 4px 0 0;
+ padding-left: 18px;
+}
+
+.drilldown-list li + li {
+ margin-top: 4px;
+}
+
+.drilldown-code {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 6px;
+}
+
.drilldown-meta {
display: grid;
gap: 8px;
diff --git a/packages/template/test/cardHeight.test.ts b/packages/template/test/cardHeight.test.ts
index 8e4e0fa..e14819b 100644
--- a/packages/template/test/cardHeight.test.ts
+++ b/packages/template/test/cardHeight.test.ts
@@ -35,6 +35,12 @@ describe("cardHeight", () => {
);
});
+ it("adds room for the meta line", () => {
+ expect(cardHeight({ ...card, meta: "agreed · 1 commit" }, 240, fixed)).toBeGreaterThan(
+ cardHeight(card, 240, fixed),
+ );
+ });
+
it("falls back to an estimate without a canvas", () => {
expect(cardHeight(card, 240)).toBeGreaterThan(30);
});
diff --git a/packages/template/test/format.test.ts b/packages/template/test/format.test.ts
index 3a5bb00..02331ab 100644
--- a/packages/template/test/format.test.ts
+++ b/packages/template/test/format.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { formatDate, formatTime, kindLabel } from "../src/format.js";
+import { cardMeta, cardText, formatDate, formatTime, kindLabel } from "../src/format.js";
describe("format", () => {
it("shows a placeholder for a missing time and an unparseable value as-is", () => {
@@ -26,3 +26,21 @@ describe("kindLabel", () => {
expect(kindLabel("decision")).toBe("decision");
});
});
+
+describe("card text", () => {
+ it("shows a decision's reason and other kinds' summary", () => {
+ expect(cardText({ kind: "decision", summary: "s", why: "w" })).toBe("w");
+ expect(cardText({ kind: "decision", summary: "s" })).toBe("s");
+ expect(cardText({ kind: "step", summary: "s", why: "w" })).toBe("s");
+ });
+
+ it("sums up who decided, commits and rejected options", () => {
+ expect(cardMeta({})).toBe("");
+ expect(cardMeta({ decidedBy: "agreed", commits: ["a"], alternatives: [1, 2] })).toBe(
+ "agreed · 1 commit · 2 options rejected",
+ );
+ expect(cardMeta({ decidedBy: "user", commits: ["a", "b"], alternatives: [1] })).toBe(
+ "you decided · 2 commits · 1 option rejected",
+ );
+ });
+});