Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
feat(view): open the map layer by layer, with topics as columns
Eren61d2873d35d9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 82bc269..4e6eba7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,8 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- `codelineage session write --consume`: deletes the `--file` input once the record is saved and keeps it when the write fails. `gitPolicy=commit` now also ignores `.codelineage/inbox/`.### Changed+- Map opens like layers of an onion: sessions run down the page in time order, and inside the latest session only its top-level topics show, side by side as columns with an "N items inside" count; an opened topic lists its items down its column, nested ones indented, and any node with children expands and collapses on click (selecting a nested item in the outline opens every layer above it). Phases are labelled "topic", and collapsed session boxes are wide enough for their titles.+- `/codelineage:lineage` skill: organizes nodes by topic instead of by time (topics and sub-topics at any depth, time order kept inside each), reuses existing topics and moves misplaced nodes by resending them with the right `parent`.- The npm package and the plugin manifest now take their version from `VERSION` (the one `./release` bumps): `npm run build` and `npm pack` copy it through `scripts/sync-version.mjs`, and a test fails while they differ. Both move from 0.1.0 to 0.4.0, so the first release continues at 0.5.0.-- Map: inside a session the nodes now read top to bottom, as an indented outline (phases in order along a left spine, their steps, decisions and questions indented below), so the map grows downwards instead of sideways.- Map: the graph now spans the full window width and nearly its full height (the header and status card stay at a readable width), and a "Full screen" button expands it over the whole window, entering browser full screen when allowed; Esc or the button closes it.- `commander`, `zod` and `@inquirer/prompts` moved to `devDependencies`: they are bundled into `dist/cli.js`, so installing the package pulls in no runtime dependencies.diff --git a/packages/cli/skills/lineage/SKILL.md b/packages/cli/skills/lineage/SKILL.mdindex 3ca846d..c498512 100644--- a/packages/cli/skills/lineage/SKILL.md+++ b/packages/cli/skills/lineage/SKILL.md@@ -36,15 +36,31 @@ Build one JSON object:- `pending`: `{ "text": "…", "needsUser": true }` for anything waiting on theuser, and `needsUser: false` for work that is simply not done yet.- `next`: the next concrete step.-- `nodes`: only new nodes, or existing ones whose title, summary or reason- changed. Nodes you leave out are kept, and so are fields you leave out.+- `nodes`: only new nodes, or existing ones whose title, summary, reason or+ parent changed. Nodes you leave out are kept, and so are fields you leave out.- `id`: a short, stable slug. Reuse an existing id to change that node.- - `kind`: `phase` (a stretch of work), `step` (a concrete action within a- phase), `decision` (a choice that was made, with the reason in `why`) or- `question` (an open question).- - `parent`: the id of the phase the node belongs to, or `null` for a phase.+ - `kind`: `phase` (a topic), `step` (a concrete action), `decision` (a choice+ 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.+## Organize the nodes by topic, not by time++The map opens like layers of an onion: first the session's top-level topics,+then a click reveals what is inside each one. Order within a layer is the order+in which things were added, so time is kept inside every topic.++- A topic (`phase`) names what the work is about, such as "Permissions" or "Map+ layout", never when it happened ("First part", "Open decisions").+- Put each new step, decision or question under the topic it belongs to. Open+ a sub-topic (a `phase` whose parent is a topic) once a topic holds several+ distinct threads; nest as deep as the work needs.+- Reuse an existing topic before creating a new one. If an earlier node sits+ under the wrong topic, send it again (with its `kind` and `title`) and the+ right `parent`.+- Keep the top level short: a handful of topics per session.+Write titles and text in the conversation's language when `language` is `"auto"`,and in that language otherwise. JSON keys stay in English.diff --git a/packages/template/src/Graph.tsx b/packages/template/src/Graph.tsxindex 901da57..8aa567a 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 } from "./format.js";+import { formatDate, formatTime, kindLabel } from "./format.js";import { useFullscreen } from "./fullscreen.js";import {defaultExpanded,@@ -34,9 +34,8 @@ import {type SessionFlowNode,TREE_LEFT,TREE_OUT,- TREE_TOP,} from "./graph.js";-import { Outline, type OutlineTarget } from "./Outline.js";+import { Outline, type OutlineTarget, outlinePath } from "./Outline.js";import { DrillDown, type Selection } from "./SidePanel.js";/** Toggle callback reaches the group headers without threading props through React Flow. */@@ -67,17 +66,10 @@ function GroupToggle({);}-/** Spine handles for the top-to-bottom outline inside a session (see placeSessionNodes). */+/** Spine handles for the outline inside a topic column (see placeSessionNodes). */function TreeHandles() {return (<>- <Handle- id={TREE_TOP}- type="target"- position={Position.Top}- className="flow-handle tree-handle"- isConnectable={false}- /><Handleid={TREE_LEFT}type="target"@@ -142,15 +134,20 @@ function SessionNode({ id, data }: NodeProps<SessionFlowNode>) {);}-function LineageBox({ data }: NodeProps<LineageFlowNode>) {+function LineageBox({ id, data }: NodeProps<LineageFlowNode>) {return (<div className={`lineage-box kind-${data.kind}`}><TreeHandles /><div className="lineage-head">- <span className={`kind kind-${data.kind}`}>{data.kind}</span>+ {data.hasChildren ? <GroupToggle id={id} data={data} /> : null}+ <span className={`kind kind-${data.kind}`}>{kindLabel(data.kind)}</span><strong title={data.title}>{data.title}</strong></div>- {data.at ? (+ {data.hasChildren && !data.expanded ? (+ <p className="lineage-count">+ {data.count} item{data.count === 1 ? "" : "s"} inside+ </p>+ ) : data.at ? (<time dateTime={data.at}>{formatTime(data.at)}</time>) : data.summary ? (<p title={data.summary}>{data.summary}</p>@@ -282,10 +279,12 @@ function Flow({ model }: { model: LineageViewModel }) {*/const selectFromOutline = useCallback((target: OutlineTarget) => {- const needsLayout = target.expand.some((id) => !expanded.has(id));+ // Open every layer above the target, including topics it is nested in.+ const reveal = [...target.expand, ...(outlinePath(model, target.focusId) ?? []).slice(0, -1)];+ const needsLayout = reveal.some((id) => !expanded.has(id));setExpanded((previous) => {const next = new Set(previous);- for (const id of target.expand) next.add(id);+ for (const id of reveal) next.add(id);return next;});setSelection(target.selection);@@ -298,7 +297,7 @@ function Flow({ model }: { model: LineageViewModel }) {scheduleFocus(target.focusId);}},- [expanded, scheduleFocus],+ [expanded, model, scheduleFocus],);let content: ReactNode;diff --git a/packages/template/src/Outline.tsx b/packages/template/src/Outline.tsxindex 6cf4243..6a01ff2 100644--- a/packages/template/src/Outline.tsx+++ b/packages/template/src/Outline.tsx@@ -1,5 +1,6 @@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 type { Selection } from "./SidePanel.js";@@ -146,7 +147,7 @@ function NodeRows({})}>- <span className={`kind kind-${node.kind}`}>{node.kind}</span>+ <span className={`kind kind-${node.kind}`}>{kindLabel(node.kind)}</span><span className="label">{node.title}</span></button></div>diff --git a/packages/template/src/SidePanel.tsx b/packages/template/src/SidePanel.tsxindex 154dce7..431613e 100644--- a/packages/template/src/SidePanel.tsx+++ b/packages/template/src/SidePanel.tsx@@ -1,13 +1,14 @@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 } from "./format.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">;+/** What the drill-down shows: a graph node or a whole session. */-export type Selection =- | { type: "node"; node: LineageData }- | { type: "session"; sessionId: string };+export type Selection = { type: "node"; node: NodeDetail } | { type: "session"; sessionId: string };function findSession(model: LineageViewModel, sessionId: string): ViewSession | undefined {for (const epoch of model.epochs) {@@ -129,7 +130,7 @@ function SessionSummary({ model, session }: { model: LineageViewModel; session:);}-function NodeDetails({ model, node }: { model: LineageViewModel; node: LineageData }) {+function NodeDetails({ model, node }: { model: LineageViewModel; node: NodeDetail }) {const session = findSession(model, node.sessionId);return (<>@@ -231,7 +232,7 @@ export function DrillDown({<aside className="drilldown" role="dialog" aria-label="Node details"><header className="drilldown-head"><div>- <span className={`kind kind-${node.kind}`}>{node.kind}</span>+ <span className={`kind kind-${node.kind}`}>{kindLabel(node.kind)}</span><h2>{node.title}</h2></div><button type="button" className="drilldown-close" aria-label="Close" onClick={onClose}>diff --git a/packages/template/src/format.ts b/packages/template/src/format.tsindex 4b55c13..5df0639 100644--- a/packages/template/src/format.ts+++ b/packages/template/src/format.ts@@ -13,3 +13,8 @@ export function formatDate(iso: string | null): string {? iso: date.toLocaleDateString(undefined, { month: "short", day: "numeric" });}++/** Phases are shown as topics: the map groups a session by what the work is about. */+export function kindLabel(kind: string): string {+ return kind === "phase" ? "topic" : kind;+}diff --git a/packages/template/src/graph.ts b/packages/template/src/graph.tsindex 0cbb1d2..d3b193e 100644--- a/packages/template/src/graph.ts+++ b/packages/template/src/graph.ts@@ -23,13 +23,15 @@ const GROUP_HEADER = 44;const ROOT_PADDING = 48;-/** Inside a session nodes read top to bottom: phases in order, their items indented below. */+/** Inside a topic column nodes read top to bottom, nested items indented below their topic. */const INDENT = 32;const ROW_GAP = 16;+const COLUMN_GAP = 24;+/** Wide enough that a collapsed session shows a readable title. */+const SESSION_WIDTH = 380;-/** Handle ids on lineage cards: the spine leaves at the bottom left, enters at the top left or the left side. */+/** Handle ids on lineage cards: the spine leaves at the bottom left and enters at the left side. */export const TREE_OUT = "tree-out";-export const TREE_TOP = "tree-top";export const TREE_LEFT = "tree-left";export type EpochData = {@@ -57,6 +59,10 @@ export type LineageData = {at?: string;/** Owning session, so the drill-down panel can show and resume it. */sessionId: string;+ /** Nodes nested below this one, at any depth. */+ count: number;+ expanded: boolean;+ hasChildren: boolean;};export type EpochFlowNode = FlowNode<EpochData, "epoch">;@@ -106,7 +112,10 @@ function groupOptions() {};}-/** The map opens on the most recently updated session, with its epoch expanded. */+/**+ * The map opens on the most recently updated session, with its epoch expanded,+ * showing only that session's top-level topics; deeper layers open on click.+ */export function defaultExpanded(model: LineageViewModel): Set<string> {const candidates: { session: ViewSession; group: string }[] = [];for (const epoch of model.epochs) {@@ -171,39 +180,46 @@ function treeEdge(source: string, target: string, targetHandle: string): FlowEdg}/**- * Places a session's nodes as an indented, top-to-bottom outline: one row per node- * in recorded order. Phases are chained along the left spine and each item hangs- * off its parent's spine, so the map grows downwards, never sideways.+ * Places a session's nodes: top-level topics side by side as columns (they run in+ * parallel, so their order matters little), and inside each column an indented,+ * top-to-bottom outline of what the topic holds, in recorded order. Time runs+ * down the map across sessions; topics run across.*/-export function placeSessionNodes(nodes: ViewNode[], sessionGroup: string): Placement {+export function placeSessionNodes(+ nodes: ViewNode[],+ sessionGroup: string,+ isOpen: (id: string) => boolean = () => true,+): Placement {const boxes = new Map<string, Sized>();const edges: FlowEdge[] = [];- let row = 0;- let maxDepth = 0;- const visit = (list: ViewNode[], parent: string | null, depth: number): void => {- let previous: string | null = null;- for (const node of list) {+ const top = GROUP_HEADER + 8;+ let columnX = GROUP_PADDING;+ let maxRows = 0;+ for (const root of nodes) {+ let row = 0;+ let columnWidth = NODE_WIDTH;+ const visit = (node: ViewNode, parent: string | null, depth: number): void => {const id = nodeId(sessionGroup, node.id);boxes.set(id, {- x: GROUP_PADDING + depth * INDENT,- y: GROUP_HEADER + 8 + row * (NODE_HEIGHT + ROW_GAP),+ x: columnX + depth * INDENT,+ y: top + row * (NODE_HEIGHT + ROW_GAP),width: NODE_WIDTH,height: NODE_HEIGHT,});row += 1;- maxDepth = Math.max(maxDepth, depth);+ columnWidth = Math.max(columnWidth, depth * INDENT + NODE_WIDTH);if (parent !== null) edges.push(treeEdge(parent, id, TREE_LEFT));- else if (previous !== null) edges.push(treeEdge(previous, id, TREE_TOP));- previous = id;- visit(node.children, id, depth + 1);- }- };- visit(nodes, null, 0);+ if (isOpen(id)) for (const child of node.children) visit(child, id, depth + 1);+ };+ visit(root, null, 0);+ maxRows = Math.max(maxRows, row);+ columnX += columnWidth + COLUMN_GAP;+ }return {boxes,edges,- width: GROUP_PADDING * 2 + maxDepth * INDENT + NODE_WIDTH,- height: GROUP_HEADER + 8 + row * (NODE_HEIGHT + ROW_GAP) - ROW_GAP + GROUP_PADDING,+ width: Math.max(columnX - COLUMN_GAP, GROUP_PADDING) + GROUP_PADDING,+ height: top + maxRows * (NODE_HEIGHT + ROW_GAP) - ROW_GAP + GROUP_PADDING,};}@@ -217,12 +233,12 @@ function buildSession(const id = sessionId(session.sessionId);meta.set(id, parentId);const showChildren = expanded.has(id) && session.nodes.length > 0;- if (!showChildren) return { id, width: GROUP_WIDTH, height: GROUP_HEIGHT };+ if (!showChildren) return { id, width: SESSION_WIDTH, height: GROUP_HEIGHT };// ELK sizes the session box; its contents are placed by hand.- const placement = placeSessionNodes(session.nodes, id);+ const placement = placeSessionNodes(session.nodes, id, (nodeKey) => expanded.has(nodeKey));placements.set(id, placement);- return { id, width: Math.max(GROUP_WIDTH, placement.width), height: placement.height };+ return { id, width: Math.max(SESSION_WIDTH, placement.width), height: placement.height };}function buildEpoch(@@ -371,7 +387,7 @@ export async function layoutGraph(},});if (!sessionExpanded) continue;- collectFlowNodes(session.nodes, id, session.sessionId, nodes, sizes);+ collectFlowNodes(session.nodes, id, session.sessionId, nodes, sizes, expanded);}}@@ -384,9 +400,11 @@ function collectFlowNodes(sessionId: string,out: GraphNode[],sizes: Map<string, Sized>,+ expanded: ReadonlySet<string>,): void {for (const node of nodes) {const id = nodeId(parent, node.id);+ const open = expanded.has(id);const size = sizes.get(id) ?? { x: 0, y: 0, width: NODE_WIDTH, height: NODE_HEIGHT };out.push({id,@@ -406,8 +424,11 @@ function collectFlowNodes(...(node.why === undefined ? {} : { why: node.why }),...(node.at === undefined ? {} : { at: node.at }),sessionId,+ count: countNodes(node.children),+ expanded: open,+ hasChildren: node.children.length > 0,},});- collectFlowNodes(node.children, parent, sessionId, out, sizes);+ if (open) collectFlowNodes(node.children, parent, sessionId, out, sizes, expanded);}}diff --git a/packages/template/src/styles.css b/packages/template/src/styles.cssindex adff39b..a49e664 100644--- a/packages/template/src/styles.css+++ b/packages/template/src/styles.css@@ -455,6 +455,10 @@ body:has(.map-shell.is-expanded) {text-overflow: ellipsis;}+.lineage-box p.lineage-count {+ color: var(--accent);+}+.lineage-box time {display: block;margin-top: 1px;diff --git a/packages/template/test/format.test.ts b/packages/template/test/format.test.tsindex d219fcf..3a5bb00 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 } from "../src/format.js";+import { formatDate, formatTime, kindLabel } from "../src/format.js";describe("format", () => {it("shows a placeholder for a missing time and an unparseable value as-is", () => {@@ -19,3 +19,10 @@ describe("format", () => {expect(formatDate(iso)).not.toContain(":");});});++describe("kindLabel", () => {+ it("shows phases as topics and keeps the other kinds", () => {+ expect(kindLabel("phase")).toBe("topic");+ expect(kindLabel("decision")).toBe("decision");+ });+});diff --git a/packages/template/test/graph.test.ts b/packages/template/test/graph.test.tsindex 7873cd5..d46f201 100644--- a/packages/template/test/graph.test.ts+++ b/packages/template/test/graph.test.ts@@ -1,6 +1,6 @@import { describe, expect, it } from "vitest";import type { ViewNode } from "../../cli/src/view/model.js";-import { placeSessionNodes, TREE_LEFT, TREE_TOP } from "../src/graph.js";+import { placeSessionNodes, TREE_LEFT } from "../src/graph.js";function node(id: string, children: ViewNode[] = []): ViewNode {return { id, kind: "phase", title: id, children };@@ -11,27 +11,39 @@ describe("placeSessionNodes", () => {const { boxes, edges, width, height } = placeSessionNodes(tree, "s");const box = (id: string) => boxes.get(`node:s:${id}`);- it("puts every node on its own row in recorded order", () => {- const order = ["a", "a1", "a2", "a2x", "b", "b1"].map((id) => box(id)?.y ?? -1);- expect(order).toEqual([...order].sort((x, y) => x - y));- expect(new Set(order).size).toBe(order.length);+ it("puts top-level topics side by side in one row", () => {+ expect(box("a")?.y).toBe(box("b")?.y);+ expect(box("b")?.x).toBeGreaterThan((box("a2x")?.x ?? 0) + (box("a2x")?.width ?? 0));});- it("indents children under their parent and keeps phases in one column", () => {- expect(box("a")?.x).toBe(box("b")?.x);+ it("lists a topic's items below it in recorded order, indented by depth", () => {+ const column = ["a", "a1", "a2", "a2x"].map((id) => box(id)?.y ?? -1);+ expect(column).toEqual([...column].sort((x, y) => x - y));+ expect(new Set(column).size).toBe(column.length);expect(box("a1")?.x).toBeGreaterThan(box("a")?.x ?? 0);expect(box("a2x")?.x).toBeGreaterThan(box("a2")?.x ?? 0);- expect(width).toBeGreaterThanOrEqual((box("a2x")?.x ?? 0) + (box("a2x")?.width ?? 0));- expect(height).toBeGreaterThan((box("b1")?.y ?? 0) + (box("b1")?.height ?? 0));+ expect(width).toBeGreaterThan((box("b1")?.x ?? 0) + (box("b1")?.width ?? 0));+ expect(height).toBeGreaterThan((box("a2x")?.y ?? 0) + (box("a2x")?.height ?? 0));});- it("chains phases along the spine and hangs items off their parent", () => {+ it("hangs items off their parent and never links parallel topics", () => {const link = (from: string, to: string) =>edges.find((e) => e.source === `node:s:${from}` && e.target === `node:s:${to}`);- expect(link("a", "b")?.targetHandle).toBe(TREE_TOP);expect(link("a", "a1")?.targetHandle).toBe(TREE_LEFT);expect(link("a2", "a2x")?.targetHandle).toBe(TREE_LEFT);- expect(link("a1", "a2")).toBeUndefined();- expect(edges).toHaveLength(5);+ expect(link("a", "b")).toBeUndefined();+ expect(edges).toHaveLength(4);+ });++ it("hides the children of a closed topic and narrows its column", () => {+ const closed = placeSessionNodes(tree, "s", (id) => id !== "node:s:a");+ expect(closed.boxes.has("node:s:a1")).toBe(false);+ expect(closed.boxes.has("node:s:b1")).toBe(true);+ expect(closed.boxes.get("node:s:b")?.x).toBeLessThan(box("b")?.x ?? 0);+ expect(closed.edges.map((e) => e.target)).toEqual(["node:s:b1"]);+ });++ it("gives an empty session a minimal box", () => {+ expect(placeSessionNodes([], "s").boxes.size).toBe(0);});});