@arik_shemesh/yoman 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arik Shemesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# yoman
+
+Local-first CLI that generates engineering log entries (`DEVELOPMENT_LOG.md`) from git history + your own stated intent, via the Gemini API.
+
+## Why
+
+Every existing "AI changelog" tool infers narrative from the diff alone - which means it hallucinates rationale. A diff shows *what* changed, never *why*. yoman fixes this by capturing your reasoning verbatim at milestone time, the one piece of information that was never in the diff to begin with. The diff is only used as supporting evidence.
+
+## Install
+
+From npm:
+
+```
+npm install -g @arik_shemesh/yoman
+```
+
+Or from source:
+
+```
+git clone https://github.com/ArikShemesh/yoman.git
+cd yoman
+npm install
+```
+
+Create a `.env` file next to `cli.js` with your Gemini API key:
+
+```
+GEMINI_API_KEY=your-key-here
+```
+
+`.env` is gitignored - never committed.
+
+## Global command
+
+Run once inside the cloned yoman folder:
+
+```
+npm link
+```
+
+This puts a `yoman` command on your PATH, so every command below is just `yoman`, `yoman init`, `yoman status`, etc.
+
+## Updating
+
+```
+cd /path/to/yoman
+git pull
+npm install   # only if dependencies changed
+```
+
+Nothing else: `npm link` is a symlink to the clone, so pulled code is live everywhere immediately. New config defaults reach existing repos automatically - a `.yoman/config.json` without a newly added key just gets that key's default; add the key to the file only to override it. Installed hooks keep working untouched (they only call `yoman nag`; all logic lives in the clone).
+
+## Usage
+
+Run these from inside the git repo you want to journal (not from the yoman folder itself, unless you're journaling yoman's own history):
+
+```
+yoman init
+```
+
+Creates `.yoman/config.json` and `.yoman/state.json` in the current repo, and `DEVELOPMENT_LOG.md` if it doesn't exist yet. Safe to re-run - refuses to overwrite and prints the current state instead.
+
+```
+yoman
+```
+
+The main command. Run it after finishing a milestone (one commit or several):
+
+1. Shows the commits since the last journal entry.
+2. Asks you to pick a title (derived from commit messages) or type your own.
+3. Asks **why** you made the change - free text, mandatory. Under ~15 words, it asks once more for more context, then accepts whatever you give it.
+4. Sends your stated intent + the commit messages + a secret-filtered diff to Gemini, and prepends a new entry to `DEVELOPMENT_LOG.md` (newest entry first).
+
+If the API call fails (bad model name, rate limit, network), your title/why/commit-range is saved to `.yoman/pending.json` - nothing is lost. Fix whatever broke and run:
+
+```
+yoman retry
+```
+
+This flushes everything queued in `.yoman/pending.json`.
+
+## Nag hook
+
+Forgetting to journal is the default failure mode. Install a reminder per repo:
+
+```
+yoman hook
+```
+
+This adds a `post-commit` hook that prints one line once you have `nagThreshold` (default 5) unjournaled commits - and stays silent otherwise. It never blocks or breaks a commit: any yoman error is swallowed. If your repo manages hooks via `core.hooksPath` (husky etc.), yoman refuses to touch the managed directory and prints the line to add manually.
+
+`yoman status` shows where you stand any time: model, unjournaled commits, pending queue.
+
+## What gets sent to the LLM, and what doesn't
+
+- Sent: commit subjects, a filtered diff, your stated intent, the entry date (the day the milestone was recorded).
+- Never sent: anything matching `.env`, `.env.*`, `*.pem`, `*.key`, `*credentials*`, `*secret*`, lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`), the `.yoman/` directory, or the log file itself.
+- The prompt explicitly instructs the model that your stated intent is the *only* source of truth for motivation - the diff is evidence of *what* changed, never *why*. If no rationale was stated, the entry says "Rationale not recorded" instead of guessing.
+- The "Stated intent" line in every log entry is your verbatim text, assembled by the code - never something the model is trusted to reproduce or paraphrase.
+
+## Config
+
+`.yoman/config.json` (created by `init`, per-repo):
+
+```json
+{
+  "model": "gemini-flash-latest",
+  "logFile": "DEVELOPMENT_LOG.md",
+  "minWhyWords": 15,
+  "diffCharLimit": 20000,
+  "nagThreshold": 5
+}
+```
+
+Edit freely - e.g. swap `model` if Gemini retires/renames one (this happens; the tool maps 404s to a clear "update your config" message instead of a stack trace).
+
+`.yoman/state.json` tracks `lastSha` - the last commit journaled. Commit both `.yoman/` and your log file to your repo so state travels with it.
+
+## Not yet included
+
+Deliberately deferred:
+
+- No npm registry publish (global command is via `npm link` only)
+- No other LLM providers (Gemini only)
+- No log splitting or cross-entry narrative continuity
+
+## Project layout
+
+```
+cli.js              entry point, command dispatch (init / run / retry / status / hook)
+src/
+  config.js          .yoman/config.json load/validate + .env key
+  state.js            .yoman/state.json (lastSha) read/write
+  git.js               commit list, filtered diff, secret-path exclusion
+  titles.js            local (non-AI) title candidates from commit subjects
+  prompt.js            hallucination-guarded prompt construction
+  llm.js               Gemini API call + friendly error mapping
+  log.js                prepend entry to DEVELOPMENT_LOG.md with SHA-range anchor
+  pending.js            save-before-call queue (.yoman/pending.json)
+```

package/cli.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+async function cmdInit() {
+  const fs = require('fs');
+  const path = require('path');
+  const config = require('./src/config');
+  const state = require('./src/state');
+  const git = require('./src/git');
+
+  const cwd = process.cwd();
+
+  if (config.isInitialized(cwd)) {
+    const existingConfig = JSON.parse(fs.readFileSync(config.configPath(cwd), 'utf8'));
+    const existingState = state.loadState(cwd);
+    console.log('yoman already initialized in this directory.');
+    console.log(`  config: ${JSON.stringify(existingConfig)}`);
+    console.log(`  state:  ${JSON.stringify(existingState)}`);
+    return;
+  }
+
+  const head = git.currentHead(cwd);
+  config.writeConfig(config.DEFAULT_CONFIG, cwd);
+  state.writeState({ lastSha: head }, cwd);
+
+  const logFile = path.join(cwd, config.DEFAULT_CONFIG.logFile);
+  if (!fs.existsSync(logFile)) {
+    fs.writeFileSync(logFile, '# Development Log\n');
+  }
+
+  console.log('yoman initialized.');
+  console.log(`  config: ${config.configPath(cwd)}`);
+  console.log(`  state:  lastSha=${head}`);
+  console.log(`  log:    ${logFile}`);
+}
+
+// Shared by run (fresh milestone) and retry/auto-flush (queued milestone):
+// builds the filtered diff, calls the LLM, prepends the log entry, and
+// advances state.lastSha to the item's range end (plan step 9 applies to
+// both call sites).
+async function processPendingItem(item, cfg, cwd) {
+  const git = require('./src/git');
+  const prompt = require('./src/prompt');
+  const llm = require('./src/llm');
+  const log = require('./src/log');
+  const state = require('./src/state');
+
+  const { from, to } = item.shaRange;
+  const commitLines = git.commitOneliners(from, to, cwd);
+  const { diff, truncated } = git.filteredDiff(from, to, cfg.diffCharLimit, cwd, cfg.logFile);
+  // Entry date = the day the human recorded the milestone, not the day a
+  // queued item finally flushed (may differ after a failed run + later retry).
+  const isoDate = item.timestamp.slice(0, 10);
+
+  const llmPrompt = prompt.buildPrompt({
+    date: isoDate,
+    title: item.title,
+    why: item.why,
+    commitLines,
+    diff,
+    truncated,
+  });
+
+  const modelBody = await llm.generateEntry({ model: cfg.model, prompt: llmPrompt });
+
+  log.prependEntry(
+    {
+      logFile: cfg.logFile,
+      fromSha: from,
+      toSha: to,
+      isoDate,
+      title: item.title,
+      why: item.why,
+      modelBody,
+    },
+    cwd
+  );
+
+  state.writeState({ lastSha: to }, cwd);
+}
+
+// Flush the pending queue: journal each queued item, dropping items whose
+// range was already journaled (item.to is an ancestor of current lastSha).
+// Stale items happen when a run covering the same commits succeeded after
+// the item was queued; processing them would duplicate log entries and
+// regress state.lastSha.
+async function flushPending(cfg, cwd) {
+  const pending = require('./src/pending');
+  const git = require('./src/git');
+  const state = require('./src/state');
+
+  const items = pending.loadPending(cwd);
+  const result = { total: items.length, recovered: 0, dropped: 0, failed: 0 };
+
+  for (const item of items) {
+    const st = state.loadState(cwd);
+    if (git.isAncestor(item.shaRange.to, st.lastSha, cwd)) {
+      pending.removePending(item.timestamp, cwd);
+      result.dropped++;
+      console.log(`dropped stale pending entry (commits already journaled): ${item.title}`);
+      continue;
+    }
+    try {
+      await processPendingItem(item, cfg, cwd);
+      pending.removePending(item.timestamp, cwd);
+      result.recovered++;
+      console.log(`recovered: ${item.title}`);
+    } catch (err) {
+      result.failed++;
+      console.error(`yoman: still failing for "${item.title}": ${err.message}`);
+    }
+  }
+
+  return result;
+}
+
+async function cmdRun() {
+  const { select, input } = require('@inquirer/prompts');
+  const config = require('./src/config');
+  const state = require('./src/state');
+  const git = require('./src/git');
+  const titles = require('./src/titles');
+  const pending = require('./src/pending');
+
+  const cwd = process.cwd();
+  const cfg = config.loadConfig(cwd);
+  config.requireApiKey();
+
+  // Flush leftovers from failed runs BEFORE computing the new range.
+  // Otherwise the new range overlaps the queued one and the same commits
+  // get journaled twice with state.lastSha regressing afterward.
+  if (pending.loadPending(cwd).length > 0) {
+    console.log('pending entries from a failed run found - recovering them first...');
+    const flush = await flushPending(cfg, cwd);
+    if (flush.failed > 0) {
+      console.error(
+        'yoman: pending entries are still failing - a new run now would journal the same commits twice.'
+      );
+      console.error('fix the problem above (model name / quota / network), then run `yoman retry`.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const st = state.loadState(cwd);
+  const head = git.currentHead(cwd);
+
+  const count = git.commitCount(st.lastSha, head, cwd);
+  if (count === 0) {
+    console.log('nothing to journal (no commits since last entry).');
+    return;
+  }
+
+  const oneliners = git.commitOneliners(st.lastSha, head, cwd);
+  console.log(`${count} commit(s) since last entry:`);
+  for (const line of oneliners.slice(0, 20)) console.log(`  ${line}`);
+  if (oneliners.length > 20) console.log(`  +${oneliners.length - 20} more`);
+
+  const subjects = git.commitSubjects(st.lastSha, head, cwd);
+  const OTHER = '__other__';
+  const choices = [
+    ...titles.deriveTitles(subjects).map((t) => ({ name: t, value: t })),
+    { name: 'Other (type manually)', value: OTHER },
+  ];
+  let title = await select({ message: 'Title for this entry:', choices });
+  if (title === OTHER) {
+    title = await input({
+      message: 'Enter a title:',
+      validate: (v) => v.trim().length > 0 || 'title is required',
+    });
+  }
+
+  const askWhy = (message) =>
+    input({ message, validate: (v) => v.trim().length > 0 || 'why is required' });
+
+  let why = await askWhy('Why did you make this change? (context, mandatory):');
+  const wordCount = (s) => s.trim().split(/\s+/).filter(Boolean).length;
+  if (wordCount(why) < cfg.minWhyWords) {
+    console.log(
+      `That's pretty thin (aim for ${cfg.minWhyWords}+ words - more context makes a better entry). One more try:`
+    );
+    why = await askWhy('Why did you make this change?:');
+  }
+
+  const item = {
+    title,
+    why,
+    shaRange: { from: st.lastSha, to: head },
+    timestamp: new Date().toISOString(),
+  };
+  pending.addPending(item, cwd);
+
+  try {
+    await processPendingItem(item, cfg, cwd);
+    pending.removePending(item.timestamp, cwd);
+    console.log(`entry added to ${cfg.logFile}.`);
+  } catch (err) {
+    console.error(`yoman: ${err.message}`);
+    console.error('your input is saved - run `yoman retry` later.');
+    process.exitCode = 1;
+  }
+}
+
+async function cmdRetry() {
+  const config = require('./src/config');
+  const pending = require('./src/pending');
+  const cwd = process.cwd();
+  const cfg = config.loadConfig(cwd);
+  config.requireApiKey();
+
+  if (pending.loadPending(cwd).length === 0) {
+    console.log('nothing pending.');
+    return;
+  }
+
+  const result = await flushPending(cfg, cwd);
+  console.log(
+    `${result.recovered}/${result.total} recovered, ${result.dropped} dropped as stale, ${result.failed} still pending.`
+  );
+  if (result.failed > 0) process.exitCode = 1;
+}
+
+async function cmdStatus() {
+  const config = require('./src/config');
+  const state = require('./src/state');
+  const git = require('./src/git');
+  const pending = require('./src/pending');
+
+  const cwd = process.cwd();
+  const cfg = config.loadConfig(cwd);
+  const st = state.loadState(cwd);
+  const head = git.currentHead(cwd);
+  const count = git.commitCount(st.lastSha, head, cwd);
+  const pendingCount = pending.loadPending(cwd).length;
+
+  console.log(`model:              ${cfg.model}`);
+  console.log(`log file:           ${cfg.logFile}`);
+  console.log(`nag threshold:      ${cfg.nagThreshold}`);
+  console.log(`last journaled sha: ${st.lastSha.slice(0, 7)}`);
+  console.log(
+    `pending queue:      ${pendingCount === 0 ? 'none' : `${pendingCount} item(s) - run \`yoman retry\``}`
+  );
+  if (count === 0) {
+    console.log('commits since last entry: none');
+    return;
+  }
+  console.log(`commits since last entry: ${count}`);
+  const oneliners = git.commitOneliners(st.lastSha, head, cwd);
+  for (const line of oneliners.slice(0, 5)) console.log(`  ${line}`);
+  if (oneliners.length > 5) console.log(`  +${oneliners.length - 5} more`);
+}
+
+// Called from the post-commit hook. Must NEVER break or pollute a commit:
+// prints nothing below threshold, prints nothing on ANY error, always exits 0.
+async function cmdNag() {
+  try {
+    const config = require('./src/config');
+    const state = require('./src/state');
+    const git = require('./src/git');
+
+    const cwd = process.cwd();
+    const cfg = config.loadConfig(cwd);
+    const st = state.loadState(cwd);
+    const head = git.currentHead(cwd);
+    const count = git.commitCount(st.lastSha, head, cwd);
+    if (count >= cfg.nagThreshold) {
+      console.log(`yoman: ${count} commits unjournaled - consider a milestone entry`);
+    }
+  } catch (err) {
+    // silent by contract
+  }
+}
+
+async function cmdHook() {
+  const fs = require('fs');
+  const path = require('path');
+  const { execFileSync } = require('child_process');
+  const cwd = process.cwd();
+
+  const MARKER = '# yoman-nag';
+  const CALL_LINE = 'yoman nag 2>/dev/null || true';
+
+  let hooksPath = '';
+  try {
+    hooksPath = execFileSync('git', ['config', 'core.hooksPath'], { cwd, encoding: 'utf8' }).trim();
+  } catch (err) {
+    // exit 1 = unset; we manage .git/hooks ourselves
+  }
+
+  if (hooksPath) {
+    console.log(`core.hooksPath is set (${hooksPath}) - another tool manages hooks in this repo.`);
+    console.log('yoman will not modify a managed hooks directory.');
+    console.log('Add these two lines to that post-commit hook yourself:');
+    console.log(`  ${MARKER}`);
+    console.log(`  ${CALL_LINE}`);
+    return;
+  }
+
+  const gitDir = execFileSync('git', ['rev-parse', '--git-dir'], { cwd, encoding: 'utf8' }).trim();
+  const hookFile = path.resolve(cwd, gitDir, 'hooks', 'post-commit');
+
+  if (fs.existsSync(hookFile)) {
+    const content = fs.readFileSync(hookFile, 'utf8');
+    if (content.includes(MARKER)) {
+      console.log('yoman nag hook already installed.');
+      return;
+    }
+    const updated = content.replace(/\n*$/, '\n') + `\n${MARKER}\n${CALL_LINE}\n`;
+    fs.writeFileSync(hookFile, updated);
+    console.log(`appended yoman nag to existing post-commit hook: ${hookFile}`);
+  } else {
+    fs.mkdirSync(path.dirname(hookFile), { recursive: true });
+    fs.writeFileSync(hookFile, `#!/bin/sh\n\n${MARKER}\n${CALL_LINE}\n`);
+    console.log(`created post-commit hook: ${hookFile}`);
+  }
+
+  try {
+    fs.chmodSync(hookFile, 0o755);
+  } catch (err) {
+    // best-effort; git-bash on Windows executes hooks regardless
+  }
+}
+
+async function main() {
+  const [, , sub] = process.argv;
+
+  if (sub === 'init') return cmdInit();
+  if (sub === 'retry') return cmdRetry();
+  if (sub === 'status') return cmdStatus();
+  if (sub === 'nag') return cmdNag();
+  if (sub === 'hook') return cmdHook();
+  if (sub && sub !== 'run') {
+    console.error(`yoman: unknown command "${sub}"`);
+    process.exitCode = 1;
+    return;
+  }
+  return cmdRun();
+}
+
+main().catch((err) => {
+  console.error(`yoman: ${err.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@arik_shemesh/yoman",
+  "version": "0.2.0",
+  "description": "Local-first CLI that generates engineering log entries from git history + human-provided intent, via Gemini API.",
+  "main": "cli.js",
+  "bin": {
+    "yoman": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArikShemesh/yoman.git"
+  },
+  "scripts": {
+    "start": "node cli.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@google/genai": "^1.0.0",
+    "@inquirer/prompts": "^7.0.0",
+    "dotenv": "^16.4.5"
+  }
+}

package/src/config.js

@@ -0,0 +1,45 @@
+const fs = require('fs');
+const path = require('path');
+
+require('dotenv').config({ path: path.join(__dirname, '..', '.env') });
+
+const YOMAN_DIR = '.yoman';
+const CONFIG_FILE = 'config.json';
+
+const DEFAULT_CONFIG = {
+  model: 'gemini-flash-latest',
+  logFile: 'DEVELOPMENT_LOG.md',
+  minWhyWords: 15,
+  diffCharLimit: 20000,
+  nagThreshold: 5,
+};
+
+function configPath(cwd = process.cwd()) {
+  return path.join(cwd, YOMAN_DIR, CONFIG_FILE);
+}
+
+function isInitialized(cwd = process.cwd()) {
+  return fs.existsSync(configPath(cwd));
+}
+
+function loadConfig(cwd = process.cwd()) {
+  if (!isInitialized(cwd)) {
+    throw new Error('not initialized in this directory. Run `yoman init` first.');
+  }
+  const raw = fs.readFileSync(configPath(cwd), 'utf8');
+  return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+}
+
+function requireApiKey() {
+  if (!process.env.GEMINI_API_KEY) {
+    throw new Error('GEMINI_API_KEY not set. Add it to the .env file next to cli.js.');
+  }
+}
+
+function writeConfig(config, cwd = process.cwd()) {
+  const file = configPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+}
+
+module.exports = { DEFAULT_CONFIG, configPath, isInitialized, loadConfig, writeConfig, requireApiKey };

package/src/git.js

@@ -0,0 +1,72 @@
+const { execFileSync } = require('child_process');
+
+const EXCLUDED_PATTERNS = [
+  '.env',
+  '.env.*',
+  '*.pem',
+  '*.key',
+  '*credentials*',
+  '*secret*',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  '.yoman/**',
+];
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 1024 * 1024 * 50 });
+}
+
+function currentHead(cwd = process.cwd()) {
+  return git(['rev-parse', 'HEAD'], cwd).trim();
+}
+
+// true if maybeAncestor is an ancestor of sha (or the same commit)
+function isAncestor(maybeAncestor, sha, cwd = process.cwd()) {
+  try {
+    git(['merge-base', '--is-ancestor', maybeAncestor, sha], cwd);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+function commitCount(fromSha, toSha, cwd = process.cwd()) {
+  const out = git(['rev-list', `${fromSha}..${toSha}`], cwd).trim();
+  return out ? out.split('\n').length : 0;
+}
+
+function commitSubjects(fromSha, toSha, cwd = process.cwd()) {
+  const out = git(['log', '--format=%s', `${fromSha}..${toSha}`], cwd).trim();
+  return out ? out.split('\n') : [];
+}
+
+function commitOneliners(fromSha, toSha, cwd = process.cwd()) {
+  const out = git(['log', '--format=%h %s', `${fromSha}..${toSha}`], cwd).trim();
+  return out ? out.split('\n') : [];
+}
+
+function filteredDiff(fromSha, toSha, charLimit, cwd = process.cwd(), logFile) {
+  const patterns = logFile ? [...EXCLUDED_PATTERNS, logFile] : EXCLUDED_PATTERNS;
+  const excludeArgs = patterns.map((p) => `:(exclude)${p}`);
+  const raw = git(['diff', fromSha, toSha, '--', '.', ...excludeArgs], cwd);
+  if (raw.length <= charLimit) {
+    return { diff: raw, truncated: false };
+  }
+  const truncated = raw.slice(0, charLimit);
+  const lastHunk = truncated.lastIndexOf('\ndiff --git ');
+  const cut = lastHunk > 0 ? truncated.slice(0, lastHunk) : truncated;
+  return {
+    diff: `${cut}\n\n[... diff truncated at ${charLimit} chars ...]\n`,
+    truncated: true,
+  };
+}
+
+module.exports = {
+  currentHead,
+  isAncestor,
+  commitCount,
+  commitSubjects,
+  commitOneliners,
+  filteredDiff,
+};

package/src/llm.js

@@ -0,0 +1,21 @@
+const { GoogleGenAI } = require('@google/genai');
+
+async function generateEntry({ model, prompt }) {
+  const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
+  try {
+    const response = await ai.models.generateContent({ model, contents: prompt });
+    return response.text;
+  } catch (err) {
+    if (err.status === 404) {
+      throw new Error(
+        `model "${model}" not found or not available for this key. Update "model" in .yoman/config.json. (${err.message})`
+      );
+    }
+    if (err.status === 429) {
+      throw new Error(`rate limited / quota exceeded for model "${model}". (${err.message})`);
+    }
+    throw new Error(`Gemini API call failed: ${err.message}`);
+  }
+}
+
+module.exports = { generateEntry };

package/src/log.js

@@ -0,0 +1,28 @@
+const fs = require('fs');
+const path = require('path');
+
+function prependEntry(
+  { logFile, fromSha, toSha, isoDate, title, why, modelBody },
+  cwd = process.cwd()
+) {
+  const file = path.isAbsolute(logFile) ? logFile : path.join(cwd, logFile);
+  const anchor = `<!-- yoman: ${fromSha}..${toSha} | ${isoDate} -->`;
+  const entryMarkdown = `## ${isoDate} - ${title}\n**Stated intent:** ${why}\n\n${modelBody.trim()}`;
+  const block = `${anchor}\n${entryMarkdown.trim()}\n`;
+
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const headerMatch = existing.match(/^(#[^\n]*\n)/);
+
+  let updated;
+  if (headerMatch) {
+    const header = headerMatch[1];
+    const rest = existing.slice(header.length).replace(/^\n+/, '');
+    updated = `${header}\n${block}\n${rest}`;
+  } else {
+    updated = `${block}\n${existing}`;
+  }
+
+  fs.writeFileSync(file, updated);
+}
+
+module.exports = { prependEntry };

package/src/pending.js

@@ -0,0 +1,43 @@
+const fs = require('fs');
+const path = require('path');
+
+const YOMAN_DIR = '.yoman';
+const PENDING_FILE = 'pending.json';
+
+function pendingPath(cwd = process.cwd()) {
+  return path.join(cwd, YOMAN_DIR, PENDING_FILE);
+}
+
+function loadPending(cwd = process.cwd()) {
+  const file = pendingPath(cwd);
+  if (!fs.existsSync(file)) return [];
+  const raw = fs.readFileSync(file, 'utf8').trim();
+  return raw ? JSON.parse(raw) : [];
+}
+
+function writePending(items, cwd = process.cwd()) {
+  const file = pendingPath(cwd);
+  if (items.length === 0) {
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+    return;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(items, null, 2) + '\n');
+}
+
+// item: { title, why, shaRange: { from, to }, timestamp }
+function addPending(item, cwd = process.cwd()) {
+  const items = loadPending(cwd);
+  items.push(item);
+  writePending(items, cwd);
+  return item;
+}
+
+function removePending(timestamp, cwd = process.cwd()) {
+  const items = loadPending(cwd);
+  const remaining = items.filter((item) => item.timestamp !== timestamp);
+  writePending(remaining, cwd);
+  return remaining;
+}
+
+module.exports = { pendingPath, loadPending, writePending, addPending, removePending };

package/src/prompt.js

@@ -0,0 +1,43 @@
+const EXAMPLE_ENTRY = `**Summary:** Added a pending.json queue that saves the user's input before the API call, so a failed call doesn't lose it. Added \`yoman retry\` to flush the queue.
+
+**Key technical decisions:** Save-before-call ordering - the write happens before the network request, not after a catch block, so a crash mid-request still leaves the data on disk.
+
+**Impact:** API failures no longer lose the user's context; retry is a manual re-run away.`;
+
+// The heading and "Stated intent" line are assembled deterministically by
+// the caller (see log.js), never generated by the model - the model only
+// ever sees the why as evidence, so it can't paraphrase or drop it.
+function buildPrompt({ date, title, why, commitLines, diff, truncated }) {
+  return `You are a professional engineering log writer.
+
+HARD RULES:
+- The human context below is the ONLY source of truth for intent and motivation.
+- The diff and commit messages are evidence of WHAT changed only.
+- Never invent motivations, alternatives, or reasoning not stated in the context.
+- If rationale for a change is not stated, write "Rationale not recorded."
+- The entry date is ${date}. Do not infer or invent any other date.
+
+EXAMPLE OF A GOOD RESPONSE BODY (format reference only, not this task's content):
+${EXAMPLE_ENTRY}
+
+INPUTS:
+Entry date: ${date}
+Title: ${title}
+Stated intent (context only - do not repeat it verbatim, the caller already displays it separately): ${why}
+
+Commit messages in range:
+${commitLines.join('\n')}
+
+Diff (evidence only, filtered for secrets${truncated ? ', truncated' : ''}):
+${diff}
+
+OUTPUT FORMAT (return only markdown, nothing else, no code fences, no heading, no "Stated intent" line):
+**Summary:** ...
+
+**Key technical decisions:** ...
+
+**Impact:** ...
+`;
+}
+
+module.exports = { buildPrompt };

package/src/state.js

@@ -0,0 +1,25 @@
+const fs = require('fs');
+const path = require('path');
+
+const YOMAN_DIR = '.yoman';
+const STATE_FILE = 'state.json';
+
+function statePath(cwd = process.cwd()) {
+  return path.join(cwd, YOMAN_DIR, STATE_FILE);
+}
+
+function loadState(cwd = process.cwd()) {
+  const file = statePath(cwd);
+  if (!fs.existsSync(file)) {
+    throw new Error('not initialized in this directory. Run `yoman init` first.');
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function writeState(state, cwd = process.cwd()) {
+  const file = statePath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+}
+
+module.exports = { statePath, loadState, writeState };

package/src/titles.js

@@ -0,0 +1,25 @@
+function clean(subject) {
+  return subject.trim().replace(/\s+/g, ' ');
+}
+
+// Local heuristic (no API call): most-recent subject, oldest subject, and a
+// count summary, deduplicated. Good enough to seed a menu, not meant to be smart.
+function deriveTitles(commitSubjects) {
+  const subjects = commitSubjects.map(clean).filter(Boolean);
+  if (subjects.length === 0) return [];
+
+  const options = [];
+  const add = (title) => {
+    if (title && !options.includes(title)) options.push(title);
+  };
+
+  add(subjects[0]);
+  if (subjects.length > 1) {
+    add(subjects[subjects.length - 1]);
+    add(`${subjects.length} changes: ${subjects[0]}`);
+  }
+
+  return options.slice(0, 3);
+}
+
+module.exports = { deriveTitles };