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(shape): add Sequence, Interface and Example tools and a dry run
Eren14b824455273
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ba70d1e..4450f6f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).## [Unreleased]+### Added+- Three more Shape tools: **Sequence** (a Mermaid sequence diagram for work handed between a hook, a queue, a server or a background job), **Interface** (one row per command, flag, exported function, config key or schema field that changed) and **Example** (one concrete run with real values). A new or changed command always gets an example.+- `cogit shape --commit <sha> --dry-run` prints the Shape a commit would get without saving or queueing anything.++### Changed+- The Shape writer gives at most three tools, the ones that say the most, and a flowchart stays under 10 nodes.## [0.25.1] - 2026-10-31### Addeddiff --git a/README.md b/README.mdindex 15d1cbf..6fc1ee0 100644--- a/README.md+++ b/README.md@@ -23,7 +23,8 @@ Claude Code today.- **Commits point back to their reason**: a `Thought:` trailer on each commit;`cogit show <sha>`, `cogit blame` and `cogit why` follow it back.- **Intent, Shape, Code**: a message that landed commits shows why it happened, a small- picture of what the change does (plain steps or a diagram), and the diff, in one place.+ picture of what the change does (a diagram, a before/after or interface table, an example+ or plain steps), and the diff, in one place.- **Pull request descriptions with the decisions**: `cogit pr` writes the goal, thedecisions and the rejected options, never the raw chat.- **Teams share the record through git**: after a pull, your teammates' sessions are on thediff --git a/docs/guide/map.md b/docs/guide/map.mdindex fcbab9d..9210624 100644--- a/docs/guide/map.md+++ b/docs/guide/map.md@@ -86,9 +86,18 @@ A message that landed commits has three layers, in that order:- **Intent** — the record: the decision, the reason you gave, who decided, and the optionsthat were rejected. It is read as recorded, never rewritten here.-- **Shape** — a small representation of what the change *does*: numbered plain-language- steps naming the functions and files, or a Mermaid diagram of the new path between them.- The recorder writes it, not you; the map draws the diagram in the page, offline included.+- **Shape** — a small representation of what the change *does*, in up to three of these:+ - a **Flowchart** of a path through the code, or a **Sequence** diagram when work is handed+ between a hook, a queue, a server or a background job;+ - a **Before / After** table for a fix or any change you can see, and an **Interface**+ table for a command, flag, exported function, config key or schema field that changed;+ - an **Example**, one concrete run with real values (every new command gets one);+ - **Steps**, numbered plain-language steps naming the functions and files.++ The recorder writes it, not you, and a tiny change or a pure refactor gets none. The+ diagrams are drawn when the map is opened with `cogit open`; a map opened from the file+ shows their source. `cogit shape --commit <sha> --dry-run` prints the Shape a commit would+ get without saving it.- **Code** — the message's commits and their diffs, the same patches the panel opens.The message details show a short preview and an **Open** button. Open shows the three layersdiff --git a/docs/schema/session-input.json b/docs/schema/session-input.jsonindex b4b4e86..4cb2429 100644--- a/docs/schema/session-input.json+++ b/docs/schema/session-input.json@@ -264,7 +264,10 @@"enum": ["pseudo","mermaid",- "table"+ "table",+ "sequence",+ "interface",+ "example"]},"text": {diff --git a/packages/cli/skills/record/SKILL.md b/packages/cli/skills/record/SKILL.mdindex fa5a9f1..1154b84 100644--- a/packages/cli/skills/record/SKILL.md+++ b/packages/cli/skills/record/SKILL.md@@ -88,19 +88,24 @@ message's node, with the node's commit hashes:"shape": { "tools": [{ "kind": "pseudo", "text": "1. ...\n2. ..." }], "commits": ["abc1234"] }```-Three tools:+Tools (at most three, the ones that say the most; never two that tell the same thing):-- `mermaid`: a Mermaid `flowchart TD` (or `LR`) of the new path between files or functions,- at most 15 nodes. Quote labels that hold spaces or punctuation.+- `mermaid`: a Mermaid `flowchart TD` (or `LR`) of a path through code, at most 10 nodes.+ Quote labels that hold spaces or punctuation.+- `sequence`: a Mermaid `sequenceDiagram` when work is handed between actors over time (a hook+ starting a job, a client and a server, a queue drained later), at most 6 participants.- `table`: Before / After, one `case | before | after` line per case (at most 8), for achange someone can see: a fix, a new default, a rule that now says yes or no.+- `interface`: one `item | before | after` line per command, flag, exported function, config+ key or stored schema field that changed, only what is reached from outside the module;+ `—` for nothing.+- `example`: one concrete case with real values, each result on its own line after `→`. A new+ or changed command or flag always gets one that runs it.- `pseudo`: numbered plain-language steps of the new logic, naming the functions and files.-A change across two or more files gets the diagram and the steps; a visible behaviour change-also gets the table; order them diagram, table, steps. `{ "tools": [] }` means nothing worth-showing. Skip messages whose-commits are only release/version bumps, lockfiles or CHANGELOG, or change fewer than 5 lines-in total. Write it in the conversation's language; the CLI validates each output and keeps an+Tables have no header row. Order them diagram, tables, example, steps. `{ "tools": [] }`+means nothing worth showing. Skip messages whose commits are only release/version bumps,+lockfiles or CHANGELOG, or change fewer than 5 lines in total. Write it in the conversation's language; the CLI validates each output and keeps aninvalid diagram as text.## Branch summarydiff --git a/packages/cli/src/commands/shape.ts b/packages/cli/src/commands/shape.tsindex 926adce..906e27b 100644--- a/packages/cli/src/commands/shape.ts+++ b/packages/cli/src/commands/shape.ts@@ -15,6 +15,7 @@ import {type ShapeCommitInfo,shapePrompt,shapeWanted,+ validateShapeTools,} from "../shape.js";import { dequeueShape, enqueueShape } from "../shape-queue.js";import { LockBusyError, withLock } from "../store/lock.js";@@ -65,6 +66,8 @@ export function nextShapeNode(nodes: readonly LineageNode[]): LineageNode | undeexport interface ShapeOptions {/** Shape the message this commit's `Thought:` trailer names (the post-commit path). */commit?: string | undefined;+ /** With `commit`: print the Shape the side model writes, without saving it. */+ dryRun?: boolean | undefined;}export async function shapeMessage(@@ -79,6 +82,11 @@ export async function shapeMessage(if (!project.ok) throw new CliError(project.error);const config = await loadConfig(io.env);+ if (opts.dryRun === true) {+ if (opts.commit === undefined) throw new CliError("--dry-run needs --commit <sha>");+ await previewCommit(root, opts.commit, config, io);+ return;+ }if (!config.shapes) {io.out("shapes are off");return;@@ -157,6 +165,33 @@ async function shapeCommit(root: string, ref: string, config: Config, io: Io): P});}+/**+ * `--dry-run`: the Shape one commit would get, printed and not saved. The+ * message the trailer names lends its Intent when it is recorded; otherwise+ * the commit's subject stands in for it. Nothing is queued or written.+ */+async function previewCommit(root: string, ref: string, config: Config, io: Io): Promise<void> {+ const gitRoot = await findGitRoot(root);+ const commit = gitRoot === undefined ? undefined : await resolveCommit(gitRoot, ref);+ if (gitRoot === undefined || commit === undefined) throw new CliError(`no commit ${ref}`);+ const thought = await readCommitThought(root, commit, io.env);+ const sessions = await loadAllSessions(root, () => {});+ const recorded = sessions+ .flatMap((session) => session.nodes)+ .find((node) => node.kind === "message" && node.id === thought);+ const subject = (await readCommitSubjects(gitRoot, [commit])).get(commit) ?? commit.slice(0, 7);+ const node: LineageNode = {+ ...(recorded ?? {+ id: thought ?? "h000000000000",+ kind: "message",+ title: subject,+ parent: null,+ }),+ commits: [commit],+ };+ await shapeNode(root, gitRoot, undefined, node, config, io);+}+/*** The manual path: the newest message that wants a Shape. A message the skip* rules turn down (a release commit, a two-line fix) is passed over, so it@@ -177,11 +212,14 @@ async function runShape(root: string, sessionId: string, config: Config, io: Io)}}-/** Writes one message's Shape; false when the skip rules turned it down. */+/**+ * Writes one message's Shape; false when the skip rules turned it down. With+ * no session it prints the validated tools as JSON instead (`--dry-run`).+ */async function shapeNode(root: string,gitRoot: string,- sessionId: string,+ sessionId: string | undefined,node: LineageNode,config: Config,io: Io,@@ -220,6 +258,10 @@ async function shapeNode(});const stdout = await runClaude(prompt, config.sideModel, io.env);const answer = parseShapeAnswer(resultText(stdout)) ?? { tools: [], commits: [] };+ if (sessionId === undefined) {+ io.out(JSON.stringify({ tools: validateShapeTools(answer.tools) }, null, 2));+ return true;+ }const payload = {sessionId,nodes: [diff --git a/packages/cli/src/program.ts b/packages/cli/src/program.tsindex 9379316..6679bc1 100644--- a/packages/cli/src/program.ts+++ b/packages/cli/src/program.ts@@ -422,14 +422,22 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =.helpGroup("Agent:").argument("[session-id]", "session id; defaults to the session in .cogit/HEAD").option("--commit <sha>", "shape the message this commit's Thought trailer names")+ .option("--dry-run", "with --commit: print the Shape instead of saving it").option("-C, --dir <dir>", "project directory", ".").addHelpText("after",examples("cogit shape", "cogit shape 9c32ab18", "cogit shape --commit HEAD"),).action(- run(async (sessionId: string | undefined, opts: { dir: string; commit?: string }) =>- shapeMessage(opts.dir, sessionId, makeIo(false), { commit: opts.commit }),+ run(+ async (+ sessionId: string | undefined,+ opts: { dir: string; commit?: string; dryRun?: boolean },+ ) =>+ shapeMessage(opts.dir, sessionId, makeIo(false), {+ commit: opts.commit,+ dryRun: opts.dryRun,+ }),),);diff --git a/packages/cli/src/schema/session.ts b/packages/cli/src/schema/session.tsindex 1236288..315ee2e 100644--- a/packages/cli/src/schema/session.ts+++ b/packages/cli/src/schema/session.ts@@ -34,7 +34,7 @@ export const MESSAGE_ID = /^m[1-9][0-9]*$/;* How a Shape shows what a change does (Story 13.6). The registry in `shape.ts`* says when each tool fits and validates its output.*/-export const ShapeKind = z.enum(["pseudo", "mermaid", "table"]);+export const ShapeKind = z.enum(["pseudo", "mermaid", "table", "sequence", "interface", "example"]);export type ShapeKind = z.infer<typeof ShapeKind>;/**diff --git a/packages/cli/src/shape.ts b/packages/cli/src/shape.tsindex 1efc967..9586776 100644--- a/packages/cli/src/shape.ts+++ b/packages/cli/src/shape.ts@@ -26,7 +26,7 @@ export interface ShapeToolSpec {}/** Number of nodes a Mermaid flowchart may carry. */-export const MERMAID_MAX_NODES = 15;+export const MERMAID_MAX_NODES = 10;const MERMAID_KEYWORDS = new Set(["flowchart",@@ -67,6 +67,9 @@ export function mermaidNodeCount(text: string): number {return ids.size;}+/** Participants a sequence diagram may carry. */+export const SEQUENCE_MAX_ACTORS = 6;+export const SHAPE_TOOLS: readonly ShapeToolSpec[] = [{kind: "pseudo",@@ -100,7 +103,7 @@ export const SHAPE_TOOLS: readonly ShapeToolSpec[] = [},{kind: "mermaid",- name: "Diagram",+ name: "Flowchart",when:`The change is a flow between files or functions (a request path, a queue, a state ` +`machine). A Mermaid flowchart of at most ${MERMAID_MAX_NODES} nodes.`,@@ -114,8 +117,69 @@ export const SHAPE_TOOLS: readonly ShapeToolSpec[] = [return mermaidNodeCount(source) <= MERMAID_MAX_NODES;},},+ {+ kind: "sequence",+ name: "Sequence",+ when:+ "The change is a flow over time between actors that hand work to each other: a hook " ++ "starting a background job, a client and a server, a queue drained later. Prefer it to a " ++ `flowchart when the order of the calls is the point. A Mermaid sequenceDiagram of at most ${SEQUENCE_MAX_ACTORS} participants.`,+ output:+ '{"kind": "sequence", "text": "sequenceDiagram\\n participant Git\\n Git->>CLI: post-commit"}',+ validate(text) {+ const source = text.trim();+ if (!/^sequenceDiagram\b/.test(source)) return false;+ if (/<script/i.test(source)) return false;+ if (!/-{1,2}>>?|-[x)]/.test(source)) return false;+ if (source.split("\n").length > 40) return false;+ return sequenceActors(source) <= SEQUENCE_MAX_ACTORS;+ },+ },+ {+ kind: "interface",+ name: "Interface",+ when:+ "The change adds, removes or changes something other code or people call: a CLI command " ++ "or flag, an exported function's signature, a config key, a schema field, an HTTP route. " ++ 'One row per item: the item, what it was, what it is now; "—" for nothing.',+ output:+ '{"kind": "interface", "text": "cogit shape --commit <sha> | — | shapes the message the commit\'s trailer names"}',+ validate(text) {+ const rows = tableRows(text);+ return rows !== undefined && rows.length >= 1 && rows.length <= TABLE_MAX_ROWS;+ },+ },+ {+ kind: "example",+ name: "Example",+ when:+ "The behaviour is easiest to grasp from one concrete case: a command and what it prints, " ++ "an input and the output, a situation and what now happens. Real values from the diff, " ++ 'each step on its own line, "→" before each result.',+ output:+ '{"kind": "example", "text": "git commit (message not recorded yet)\\n→ queued ba654e8 until h72a65f6220b4 is recorded"}',+ validate(text) {+ const lines = text.split("\n").filter((line) => line.trim() !== "");+ return lines.length >= 2 && lines.length <= 12 && text.includes("→") && text.length <= 1500;+ },+ },];+/** The participants of a sequence diagram: declared ones plus every message end. */+export function sequenceActors(text: string): number {+ const actors = new Set<string>();+ for (const line of text.split("\n")) {+ const declared = /^\s*(?:participant|actor)\s+([^\s:]+)/.exec(line);+ if (declared?.[1]) actors.add(declared[1]);+ const message = /^\s*([^\s:-][^:]*?)\s*-{1,2}(?:>>|>|x|\))[+-]?\s*([^:]+?)\s*:/.exec(line);+ if (message?.[1] && message[2]) {+ actors.add(message[1]);+ actors.add(message[2]);+ }+ }+ return actors.size;+}+/** Rows a Before / After table may carry. */export const TABLE_MAX_ROWS = 8;@@ -253,12 +317,16 @@ export function shapePrompt(opts: {toolCatalogue(),"","Rules:",- "- When the change touches two or more files, give a diagram of the path and the steps; a single-file change takes the one tool that fits.",- "- When the change alters behaviour someone can see (a fix, a new default, a rule), add a Before / After table; a pure refactor takes none.",- "- A table has no header row (the map adds Case / Before / After); every line is one case.",- "- Order the tools diagram, table, steps; at most three. Return none when the change is a small fix not worth a picture.",+ "- Give at most three tools, the ones that say the most about this change; never two that tell the same thing.",+ "- A diagram for a change across two or more files: a sequence diagram when work is handed between actors over time, a flowchart for a path through code.",+ "- A Before / After table when behaviour someone can see changes (a fix, a new default, a rule). A pure refactor takes none.",+ "- An Interface table only for what is reached from outside the changed module: a CLI command or flag, an exported function or type other packages use, a config key, a stored schema field, an HTTP route. Never an internal helper, a component prop or a view-model field.",+ "- A new or changed command or flag always gets an example that runs it and shows what it prints, with real values from the diff. Otherwise an example only when one concrete case shows the change faster than steps.",+ "- Steps only when the logic itself is the point and no other tool says it.",+ "- Tables have no header row (the map adds one); every line is one row of three cells split by |.",+ "- Order the tools: diagram, tables, example, steps. Return none when the change is a small fix not worth a picture.",`- Name real functions, files and modules from the diff. Never invent a path.`,- `- The Mermaid source must start with "flowchart TD" (or LR) and stay under ${MERMAID_MAX_NODES} nodes; quote labels that hold spaces or punctuation.`,+ `- A flowchart starts with "flowchart TD" (or LR) and stays under ${MERMAID_MAX_NODES} nodes; quote labels that hold spaces or punctuation. A sequence diagram starts with "sequenceDiagram", names at most ${SEQUENCE_MAX_ACTORS} participants with short ids, and puts no semicolons or # in message text.`,"- Describe what the code does now, not the steps of the conversation.",`- Write the text in ${writing}; JSON keys stay English. Never write secrets, credentials or personal data.`,"",diff --git a/packages/cli/src/view/shape.ts b/packages/cli/src/view/shape.tsindex 693d4dc..d5d4ed2 100644--- a/packages/cli/src/view/shape.ts+++ b/packages/cli/src/view/shape.ts@@ -21,16 +21,16 @@ export function shapeState(shape: ViewShape | undefined, enabled: boolean): Shap}/**- * The panel preview: the first lines of the steps, or else of the Before /- * After table as `case: before → after`. A diagram alone has no text preview.+ * The panel preview: the first lines of the steps, else of the example, else+ * of a table as `case: before → after`. A diagram alone has no text preview.*/export function shapePreview(shape: ViewShape | undefined, lines = 3): string | undefined {const text = (kind: string) => shape?.tools.find((tool) => tool.kind === kind)?.text;- const pseudo = text("pseudo");- const table = text("table");+ const plain = text("pseudo") ?? text("example");+ const table = text("table") ?? text("interface");const kept =- pseudo !== undefined- ? pseudo.split("\n").map((line) => line.trim())+ plain !== undefined+ ? plain.split("\n").map((line) => line.trim()): (table?.split("\n") ?? []).map((line) => {const cells = line.split("|").map((cell) => cell.trim());return cells.length === 3 ? `${cells[0]}: ${cells[1]} → ${cells[2]}` : line.trim();diff --git a/packages/cli/test/shape-commit.test.ts b/packages/cli/test/shape-commit.test.tsindex 63f1c53..3ff41c6 100644--- a/packages/cli/test/shape-commit.test.ts+++ b/packages/cli/test/shape-commit.test.ts@@ -206,4 +206,27 @@ process.stdin.on("end", () => {await withLock(projectPaths(root).lock("shape-s1"), () => shapeMessage(root, "s1", io));expect(io.lines).toEqual(["a shape for s1 is already being written"]);});++ it("prints a dry run without saving or queueing, for a recorded message or a bare commit", async () => {+ const sha = await commit("a.txt", 12, THOUGHT);+ const claudeEnv = await fakeClaude();+ const bare = fakeIo(claudeEnv);+ await shapeMessage(root, undefined, bare, { commit: sha, dryRun: true });+ expect(JSON.parse(bare.lines.join("\n")).tools[0]).toMatchObject({+ kind: "pseudo",+ valid: true,+ });+ expect(await queuedShapes(root)).toEqual([]);++ await writeRecord([{ id: THOUGHT, kind: "message", title: "Work", parent: null }]);+ await shapeMessage(root, undefined, fakeIo(claudeEnv), { commit: "HEAD", dryRun: true });+ expect(await shapeOf(THOUGHT)).toBeUndefined();++ await expect(shapeMessage(root, undefined, fakeIo(env), { dryRun: true })).rejects.toThrow(+ "--dry-run needs --commit",+ );+ await expect(+ shapeMessage(root, undefined, fakeIo(env), { commit: "nope", dryRun: true }),+ ).rejects.toThrow("no commit nope");+ });});diff --git a/packages/cli/test/shape.test.ts b/packages/cli/test/shape.test.tsindex ee5a3b1..60eebfa 100644--- a/packages/cli/test/shape.test.ts+++ b/packages/cli/test/shape.test.ts@@ -10,6 +10,7 @@ import {mermaidNodeCount,parseShapeAnswer,SHAPE_DIFF_LIMIT,+ sequenceActors,shapePrompt,shapeWanted,stampShape,@@ -70,6 +71,43 @@ describe("the Shape tool catalogue", () => {expect(validateShapeTools([{ kind: "mermaid", text: labelled }])[0]?.valid).toBe(true);});+ it("accepts a small sequence diagram and rejects a crowded or empty one", () => {+ const ok = [+ "sequenceDiagram",+ " participant G as Git",+ " G->>CLI: post-commit",+ " CLI-->>Queue: enqueue",+ " Queue->>Model: shape when recorded",+ ].join("\n");+ expect(sequenceActors(ok)).toBe(4);+ expect(validateShapeTools([{ kind: "sequence", text: ok }])[0]?.valid).toBe(true);+ const crowded = [+ "sequenceDiagram",+ ...Array.from({ length: 7 }, (_, i) => ` A${i}->>A${i + 1}: go`),+ ];+ for (const bad of [+ "flowchart TD\n A --> B",+ "sequenceDiagram\n participant A",+ crowded.join("\n"),+ "sequenceDiagram\n A->>B: hi\n<script>x</script>",+ ]) {+ expect(validateShapeTools([{ kind: "sequence", text: bad }])[0]?.valid).toBe(false);+ }+ });++ it("accepts an Interface table and a concrete example", () => {+ const iface =+ "cogit shape --commit <sha> | — | shapes the commit's message\nShape.tools.kind | enum | any string";+ expect(validateShapeTools([{ kind: "interface", text: iface }])[0]?.valid).toBe(true);+ expect(validateShapeTools([{ kind: "interface", text: "a | b" }])[0]?.valid).toBe(false);+ const example =+ "git commit (message not recorded)\n→ queued ba654e8 until h72a65f6220b4 is recorded";+ expect(validateShapeTools([{ kind: "example", text: example }])[0]?.valid).toBe(true);+ for (const bad of ["one line → only", "two lines\nwith no arrow", `${"x\n".repeat(13)}→`]) {+ expect(validateShapeTools([{ kind: "example", text: bad }])[0]?.valid).toBe(false);+ }+ });+it("accepts a Before / After table and rejects rows without three cells", () => {const ok ="Commit before record | no Shape | queued, then shaped\nSkipped message | blocks the rest | passed over";@@ -101,6 +139,12 @@ describe("the Shape tool catalogue", () => {expect(shapePreview(tools([{ kind: "mermaid", text: "flowchart TD\nA --> B" }])),).toBeUndefined();+ expect(shapePreview(tools([{ kind: "example", text: "run it\n→ done" }]))).toBe(+ "run it\n→ done",+ );+ expect(shapePreview(tools([{ kind: "interface", text: "--commit | — | new flag" }]))).toBe(+ "--commit: — → new flag",+ );expect(tableRows("a | b | c\n\nd | e | f")).toEqual([["a", "b", "c"],["d", "e", "f"],@@ -115,16 +159,22 @@ describe("the Shape tool catalogue", () => {diffTruncated: false,language: "auto",});- expect(prompt).toContain("two or more files, give a diagram of the path and the steps");- expect(prompt).toContain("add a Before / After table");+ expect(prompt).toContain("A diagram for a change across two or more files");+ expect(prompt).toContain("A Before / After table when behaviour someone can see changes");+ expect(prompt).toContain("A new or changed command or flag always gets an example");+ expect(prompt).toContain("Never an internal helper");expect(prompt).toContain('"table" (Before / After)');+ expect(prompt).toContain('"sequence" (Sequence)');+ expect(prompt).toContain('"interface" (Interface)');+ expect(prompt).toContain('"example" (Example)');+ expect(prompt).toContain("a sequence diagram when work is handed between actors");});it("names both tools and says when to use each", () => {const catalogue = toolCatalogue();expect(catalogue).toContain('"pseudo"');expect(catalogue).toContain('"mermaid"');- expect(catalogue).toContain("15 nodes");+ expect(catalogue).toContain("10 nodes");expect(catalogue).toContain('{"kind": "pseudo"');expect(catalogue).toContain('{"kind": "mermaid"');});diff --git a/packages/template/src/ShapeModal.tsx b/packages/template/src/ShapeModal.tsxindex d3e110e..e99c990 100644--- a/packages/template/src/ShapeModal.tsx+++ b/packages/template/src/ShapeModal.tsx@@ -102,19 +102,39 @@ function IntentLayer({ node }: { node: ShapeNode }) {/** How a tool's output is named when it is shown as plain text. */const TEXT_CAPTION: Record<string, string> = {pseudo: "Steps",- mermaid: "Diagram source (not drawn)",+ example: "Example",+ mermaid: "Flowchart source (not drawn)",+ sequence: "Sequence source (not drawn)",table: "Before / After (as written)",+ interface: "Interface (as written)",};-/** A Before / After table: one row per case. */-function BeforeAfter({ rows }: { rows: readonly (readonly [string, string, string])[] }) {+/** Tools Mermaid draws. */+const DIAGRAM_KINDS = new Set(["mermaid", "sequence"]);++/** The header of each table tool; the writer sends only the rows. */+const TABLE_COLUMNS: Record<string, readonly [string, string, string]> = {+ table: ["Case", "Before", "After"],+ interface: ["Item", "Before", "After"],+};++/** A three-column table: Before / After or Interface, one row per case or item. */+function ShapeTable({+ columns,+ rows,+}: {+ columns: readonly [string, string, string];+ rows: readonly (readonly [string, string, string])[];+}) {return (<table className="shape-table"><thead><tr>- <th scope="col">Case</th>- <th scope="col">Before</th>- <th scope="col">After</th>+ {columns.map((column) => (+ <th key={column} scope="col">+ {column}+ </th>+ ))}</tr></thead><tbody>@@ -154,20 +174,20 @@ function ShapeLayer({<div className="shape-tools">{node.shape?.tools.map((tool, index) => {const key = `${tool.kind}-${index}`;- if (tool.kind === "mermaid" && tool.valid !== false)+ if (DIAGRAM_KINDS.has(tool.kind) && tool.valid !== false)return (<figure key={key} className="shape-figure">{renderMermaid(tool.text)}- <figcaption>Diagram</figcaption>+ <figcaption>{tool.kind === "sequence" ? "Sequence" : "Flowchart"}</figcaption></figure>);- const rows =- tool.kind === "table" && tool.valid !== false ? tableRows(tool.text) : undefined;- if (rows !== undefined)+ const columns = TABLE_COLUMNS[tool.kind];+ const rows = columns && tool.valid !== false ? tableRows(tool.text) : undefined;+ if (columns && rows !== undefined)return (<figure key={key} className="shape-figure">- <BeforeAfter rows={rows} />- <figcaption>Before / After</figcaption>+ <ShapeTable columns={columns} rows={rows} />+ <figcaption>{tool.kind === "interface" ? "Interface" : "Before / After"}</figcaption></figure>);return (@@ -330,7 +350,9 @@ export function ShapeSection({const [open, setOpen] = useState(false);const state = shapeState(node.shape, enabled);const preview = shapePreview(node.shape);- const diagram = node.shape?.tools.find((tool) => tool.kind === "mermaid" && tool.valid !== false);+ const diagram = node.shape?.tools.find(+ (tool) => DIAGRAM_KINDS.has(tool.kind) && tool.valid !== false,+ );return (<section className="shape-section"><h3>Intent, Shape and Code</h3>diff --git a/packages/template/test/shape-modal.test.tsx b/packages/template/test/shape-modal.test.tsxindex 260a4c5..b62e013 100644--- a/packages/template/test/shape-modal.test.tsx+++ b/packages/template/test/shape-modal.test.tsx@@ -81,7 +81,7 @@ describe("Intent, Shape and Code", () => {commits: [],},});- expect(invalid).toContain("Diagram source (not drawn)");+ expect(invalid).toContain("Flowchart source (not drawn)");});it("lays out a Before / After table and shows an unknown tool as text", () => {@@ -105,6 +105,24 @@ describe("Intent, Shape and Code", () => {expect(html).toContain("<figcaption>timeline</figcaption>");});+ it("draws a sequence, lays out an Interface table and shows an example", () => {+ const html = render("shape", {+ shape: {+ tools: [+ { kind: "sequence", text: "sequenceDiagram\n A->>B: go", valid: true },+ { kind: "interface", text: "--commit <sha> | — | new flag", valid: true },+ { kind: "example", text: "git commit\n→ queued", valid: true },+ ],+ commits: [],+ },+ });+ expect(html).toContain("<figcaption>Sequence</figcaption>");+ expect(html).toContain('<th scope="col">Item</th>');+ expect(html).toContain("<figcaption>Interface</figcaption>");+ expect(html).toContain("<figcaption>Example</figcaption>");+ expect(html).toContain("→ queued");+ });+it("shows a table the registry refused as written", () => {const html = render("shape", {shape: { tools: [{ kind: "table", text: "only | two", valid: false }], commits: [] },