@cogit/cli 0.31.0 → 0.31.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cogit",
   "displayName": "cogit",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Git remembers what changed. cogit remembers why.",
   "author": {
     "name": "Eren Sertkaya"

package/README.md

@@ -8,11 +8,47 @@ Git remembers what changed. cogit remembers why.
 
 cogit records every message you send to an AI coding agent as a *thought commit*: what you
 asked, what came of it, and the message it answered. Your code commits point back to the
-thought behind them, so `git log` tells you what changed and cogit tells you why. It works with
-Claude Code today.
+thought behind them, so `cogit why` takes any line of code back to the reason it exists. It works
+with Claude Code today.
 
-It runs as a Claude Code plugin and hooks in at SessionStart, Stop and SessionEnd, so the
-record is written while you work, not reconstructed from the diff afterwards.
+Agent memory helps your agent remember. cogit helps you understand.
+
+It runs as a Claude Code plugin and works through Claude Code hooks, so the record is written
+while you work, not reconstructed from the diff afterwards.
+
+**[Click through a saved map](https://erensrtky.github.io/cogit/demo/)**: no install, no server.
+It's the page `cogit open` writes, built from sample data and read-only.
+
+## Why
+
+I started by copying code out of ChatGPT, then moved to browser tools, editor extensions and now
+terminal agents. Each step moved the code further from me, and I kept feeling something was
+slipping away. When you write code yourself, it sinks in bit by bit: you know why that table
+exists and why you wrote that class. When an agent writes it, that feeling goes away.
+
+The information isn't really gone. It sits in your messages, the agent's replies and your commits,
+just in separate places. cogit ties them together, so you can always walk back and see why
+something was done. It helps most when you juggle projects: I run 5-10 agents at once across 2-3
+of them, and a few minutes later I can lose track of what I did where.
+
+<img src="docs/images/why-abstraction.png" alt="A conceptual chart from machine code to software factories: abstraction keeps rising, while how much of the why you can still trace falls sharply once AI starts writing code. cogit keeps what falls away.">
+
+It's bigger than one person's memory: a reviewer sees what changed, not why.
+[More, with research and sources](docs/guide/why.md).
+
+cogit isn't:
+
+- **Agent memory** (OpenViking, Mem0): that helps your agent recall what you talked about.
+- **A token saver** (RTK, Headroom): that sends the model less.
+- **A code map** (graphify): that shows how a codebase fits together.
+- **An orchestrator** (Herdr, Conductor): that runs many agents at once.
+- **A planning framework** (BMAD, Spec Kit): that decides what to build next.
+- **An AI review bot** (CodeRabbit, Greptile): that comments on whether a diff looks right.
+
+It answers the one question they leave open: why is this code the way it is? I use several of
+them alongside it.
+
+## See it
 
 <img src="docs/images/map.png" alt="The map: sessions as a git graph, each with its messages, branches, commit chips and a left off here marker">
 
@@ -26,18 +62,14 @@ what the change does, and the diff.*
 
 <img src="docs/images/tasks.png" alt="The Tasks panel: suggested items with Accept and Dismiss, open items with Done, and a Done section">
 
-*Tasks — what your sessions left undone, drafted when a session closes. You accept, dismiss or
-close each one.*
+*Tasks — work that came up in a session and didn't get finished, caught when the session closes.
+You accept, dismiss or close each one.*
 
 <img src="docs/images/files.png" alt="The Files view: a changed file opened, listing the messages that touched it with each message's reason and the option it rejected">
 
 *A changed file opens its history: every message that touched it, and the reason behind each —
 including the option that was rejected.*
 
-**[Click through a saved map](https://erensrtky.github.io/cogit/demo/)** — no install, no server:
-the same page `cogit open` writes, built from sample data. Read-only, so the Tasks buttons are
-inert.
-
 ## What it does
 
 - **Every message becomes a thought commit**: the question, the outcome, the decisions with
@@ -50,25 +82,21 @@ inert.
 - **Intent, Shape, Code**: a message that landed commits shows why it happened, a small
   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.
-- **Tasks**: when a session ends, a small model drafts a few user-level items from what it
-  left undone; you accept, dismiss or close them (`cogit captures`, and on the map).
+- **Tasks**: when a session ends, a small model catches the work that came up and didn't get
+  finished as a few user-level items; you accept, dismiss or close them (`cogit captures`, and
+  on the map).
 - **Pull request descriptions with the decisions**: `cogit pr` writes the goal, the
   decisions and the rejected options, never the raw chat.
 - **Teams share the record through git**: after a pull, your teammates' sessions are on the
   map too, with who ran them and what changed most.
-- **The agent remembers**: a new session starts where the last one left off, and before
-  editing a file the agent hears what was already tried and rejected there.
 - **Cheap by default**: a small side model records in the background; in our sessions it
   cost about 1–2% of a session's tokens.
-- **Private by default**: no server, no account. The raw conversation stays on your machine
-  and keys are redacted.
-
-## Why
-
-AI coding agents made writing code faster and moved the bottleneck to review: in a study of
-718 firms, they opened 23% more pull requests while review time rose 49% and finished work did
-not measurably grow. A reviewer sees what changed, not why; the why stays in a chat nobody else
-reads. cogit keeps it next to the code. [More, with sources](docs/guide/why.md).
+- **No server, no account**: it runs on your machine. Your chats are not committed. The record
+  (titles, decisions and reasons) is, so it travels with your branch; `cogit init` lets you keep
+  it local instead. Key and token patterns are redacted.
+- **The agent gets the context too**: a new session starts where the last one left off, and
+  before editing a file the agent hears what was already tried and rejected there. It works
+  alongside memory tools; it doesn't replace them.
 
 ## Install
 

package/dist/{chunk-XMQKZVCS.js → chunk-DJFQNOZT.js}

@@ -21206,7 +21206,7 @@ async function migrateProject(root) {
     const next = renameGitignoreLines(text);
     if (next !== text) await atomicWrite(gitignore, next).catch(() => void 0);
   }
-  const { installGitHooks: installGitHooks2 } = await import("./git-hooks-SGXDRKNY.js");
+  const { installGitHooks: installGitHooks2 } = await import("./git-hooks-KQ3BN2VC.js");
   await installGitHooks2(dir).catch(() => void 0);
   return true;
 }
@@ -23793,6 +23793,9 @@ function isStoredTurn(value) {
   const turn = value;
   return typeof turn.uuid === "string" && turn.uuid !== "" && typeof turn.at === "string" && typeof turn.text === "string" && Array.isArray(turn.replies) && turn.replies.every((reply) => typeof reply === "string") && turn.tools !== null && typeof turn.tools === "object";
 }
+function answerSize(turn) {
+  return turn.replies.reduce((sum, reply) => sum + reply.length, 0) + JSON.stringify(turn.tools).length;
+}
 async function readConversationStore(root, sessionId) {
   let text;
   try {
@@ -23819,16 +23822,28 @@ async function readConversationStore(root, sessionId) {
       order.push(value.uuid);
       continue;
     }
-    if (prev.hash === void 0 && value.hash !== void 0) byUuid.set(value.uuid, value);
+    const fuller = answerSize(value) > answerSize(prev) ? value : prev;
+    const hash2 = prev.hash ?? value.hash;
+    byUuid.set(value.uuid, {
+      ...prev,
+      ...hash2 === void 0 ? {} : { hash: hash2 },
+      replies: fuller.replies,
+      tools: fuller.tools
+    });
   }
   return order.map((uuid3) => byUuid.get(uuid3));
 }
 async function appendConversationTurns(root, sessionId, turns) {
-  const known = new Set((await readConversationStore(root, sessionId)).map((turn) => turn.uuid));
+  const stored = new Map(
+    (await readConversationStore(root, sessionId)).map((turn) => [turn.uuid, turn])
+  );
+  const seen = /* @__PURE__ */ new Set();
   const fresh = [];
   for (const turn of turns) {
-    if (turn.uuid === void 0 || known.has(turn.uuid)) continue;
-    known.add(turn.uuid);
+    if (turn.uuid === void 0 || seen.has(turn.uuid)) continue;
+    seen.add(turn.uuid);
+    const held = stored.get(turn.uuid);
+    if (held && answerSize(turn) <= answerSize(held)) continue;
     fresh.push({
       uuid: turn.uuid,
       ...turn.hash === void 0 ? {} : { hash: turn.hash },
@@ -23839,13 +23854,17 @@ async function appendConversationTurns(root, sessionId, turns) {
     });
   }
   if (fresh.length === 0) return 0;
-  const { value } = redactDeep(fresh);
+  const value = redactDeep(fresh).value.filter((turn) => {
+    const held = stored.get(turn.uuid);
+    return !held || answerSize(turn) > answerSize(held);
+  });
+  if (value.length === 0) return 0;
   const chunk = `${value.map((turn) => JSON.stringify(turn)).join("\n")}
 `;
   const file2 = projectPaths(root).conversation(sessionId);
   await mkdir4(dirname6(file2), { recursive: true });
   await appendFile(file2, gzipSync(Buffer.from(chunk, "utf8")));
-  return fresh.length;
+  return value.length;
 }
 async function appendConversationHashes(root, sessionId, hashes) {
   if (hashes.size === 0) return 0;
@@ -24517,9 +24536,8 @@ function embedViewModel(template, model) {
   if (!template.includes(EMPTY_DATA_ELEMENT)) {
     throw new Error(`the template has no empty <script id="${DATA_ELEMENT_ID}"> element`);
   }
-  const data = `<script id="${DATA_ELEMENT_ID}" type="application/json">${escapeForScript(
-    JSON.stringify(model)
-  )}</script>`;
+  const json2 = JSON.stringify(model, null, 1).replace(/\n +/g, "\n");
+  const data = `<script id="${DATA_ELEMENT_ID}" type="application/json">${escapeForScript(json2)}</script>`;
   return template.replace(EMPTY_DATA_ELEMENT, () => data);
 }
 
@@ -25578,7 +25596,7 @@ async function onSessionEnd(ctx) {
 // package.json
 var package_default = {
   name: "@cogit/cli",
-  version: "0.31.0",
+  version: "0.31.1",
   description: "Git remembers what changed. cogit remembers why.",
   license: "MIT",
   keywords: [

package/dist/cli.js

@@ -121,7 +121,7 @@ import {
   versionNotice,
   why,
   withLock
-} from "./chunk-XMQKZVCS.js";
+} from "./chunk-DJFQNOZT.js";
 
 // node_modules/commander/lib/error.js
 var CommanderError = class extends Error {
@@ -4194,8 +4194,7 @@ async function readTranscriptViews(sessions, transcripts, root, io) {
     const file = transcripts.get(session.sessionId);
     const recordsMessages = session.nodes.some((node) => node.kind === "message");
     const roots = [session.worktree?.path, root].filter((r) => Boolean(r));
-    const stored = await readConversationStore(root, session.sessionId);
-    const storedByUuid = new Map(stored.map((turn) => [turn.uuid, turn]));
+    let stored = await readConversationStore(root, session.sessionId);
     let transcript = null;
     if (file) {
       try {
@@ -4209,21 +4208,18 @@ async function readTranscriptViews(sessions, transcripts, root, io) {
     }
     const fromTranscript = transcript && transcript.length > 0 ? hashTurns(session.sessionId, transcript) : null;
     if (fromTranscript) {
-      const fresh = fromTranscript.filter(
-        (turn) => turn.uuid !== void 0 && !storedByUuid.has(turn.uuid)
-      );
       const hashes = new Map(
         fromTranscript.flatMap(
           (turn) => turn.uuid === void 0 ? [] : [[turn.uuid, turn.hash]]
         )
       );
       try {
-        if (fresh.length > 0)
-          await appendConversationTurns(
-            root,
-            session.sessionId,
-            fresh.map((turn) => agent3.displayTurn(turn, roots))
-          );
+        const appended = await appendConversationTurns(
+          root,
+          session.sessionId,
+          fromTranscript.map((turn) => agent3.displayTurn(turn, roots))
+        );
+        if (appended > 0) stored = await readConversationStore(root, session.sessionId);
         await appendConversationHashes(root, session.sessionId, hashes);
       } catch (err) {
         io.warn(
@@ -4239,6 +4235,7 @@ async function readTranscriptViews(sessions, transcripts, root, io) {
       nodes: applyEvents(upgraded.nodes, events)
     };
     prepared.push(effective);
+    const storedByUuid = new Map(stored.map((turn) => [turn.uuid, turn]));
     let turns;
     if (fromTranscript) {
       turns = fromTranscript.map((turn) => {
@@ -5826,6 +5823,8 @@ function rules(language, messageSummaries, recorder) {
     "- parent: an earlier message id, or null when the message starts a new thread; never a topic or phase node.",
     "- Back to an older thread: that message is the parent and the previous one goes in links (at most 5). Unsure: use the previous message.",
     '- When the message itself made a decision (the user asked for it, picked an option or approved a proposal): decidedBy ("user" or "agreed"), the reason in why, and the options not taken in alternatives [{"option": "...", "why": "..."}].',
+    "- alternatives lists only options someone actually named in the conversation before the decision. Never infer one from the decision, never list the current state as an option, and leave the field out when none was named. Its why says what the conversation said: no durations, sizes or reasons it does not contain. An option only postponed was not rejected.",
+    '- decidedBy "agreed" needs the user approving the proposal in this message. A proposal the user has not answered is not a decision.',
     `- The agent's work belongs inside the message node that caused it, never in nodes of its own: work (short items), agentDecisions ([{"title": "...", "why": "...", "alternatives": [...]}]) only for technical choices with a reason \u2014 never for proposals or work items \u2014 commits (short hashes) and files (a few paths).`,
     "- Write a branch summary ({title, asked, outcome, open}) on the first message of a branch when the branch ends.",
     `- Never send "at"; the CLI takes each message's time from the transcript.`,

package/dist/{git-hooks-SGXDRKNY.js → git-hooks-KQ3BN2VC.js}

@@ -15,7 +15,7 @@ import {
   uninstallGitHooks,
   withHookBlock,
   withoutHookBlock
-} from "./chunk-XMQKZVCS.js";
+} from "./chunk-DJFQNOZT.js";
 export {
   BLOCK_END,
   BLOCK_START,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogit/cli",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Git remembers what changed. cogit remembers why.",
   "license": "MIT",
   "keywords": [

package/skills/record/SKILL.md

@@ -55,7 +55,11 @@ transcript is unreadable: send only `status`.
 - `summary`: what came of it, ONLY when `messageSummaries` is true; otherwise leave it out,
   like a commit with a subject and no body.
 - A decision: `decidedBy` (`"user"` or `"agreed"`), `why`, `alternatives`
-  (`{ "option", "why" }`).
+  (`{ "option", "why" }`). `alternatives` lists only options someone actually named in the
+  conversation before the decision: never one inferred from the decision, never the current
+  state, and no durations, sizes or reasons the conversation does not contain. An option only
+  postponed was not rejected. `"agreed"` needs the user approving the proposal in this message;
+  a proposal the user has not answered is not a decision.
 - Your work belongs to the message that caused it: `work`, `agentDecisions`
   (`{ "title", "why", "alternatives" }`), `commits` (short hashes), `files` (a few paths).
   Work spanning messages goes on the one it ended in; update an earlier node only to correct it.