@arik_shemesh/yoman 0.2.0 → 0.3.0

package/README.md

@@ -1,10 +1,65 @@
 # yoman
 
-Local-first CLI that generates engineering log entries (`DEVELOPMENT_LOG.md`) from git history + your own stated intent, via the Gemini API.
+[![npm](https://img.shields.io/npm/v/@arik_shemesh/yoman)](https://www.npmjs.com/package/@arik_shemesh/yoman)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## Why
+**A development log your team will actually trust, because the "why" comes from you, not a guess.**
 
-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.
+Every "AI changelog" tool reads a diff and invents a reason for it. That reason is always a hallucination - a diff shows *what* changed, never *why*. yoman flips the pipeline: it asks you for your reasoning at the moment the milestone happens, captures it verbatim, and only then lets the model use the diff as supporting evidence to write up the rest.
+
+Local-first CLI. Your repo, your `DEVELOPMENT_LOG.md`, the Gemini API doing the write-up - nothing else in the loop.
+
+## See it work
+
+This is a real, unedited entry from this project's own log, generated by running `yoman` after a milestone:
+
+> **2026-07-19 - Flush pending queue before new runs; add README and CLAUDE.md**
+>
+> **Stated intent:** Asked what happens if a failed run is followed by plain yoman instead of retry, and found a real duplicate-entry and state-regression bug. Chose flush-first over post-run auto-flush so overlapping ranges can never form, plus a stale-item guard as cheap insurance.
+>
+> **Summary:** Implemented a flush-first mechanism in the main command flow that processes any queued items in `pending.json` before a new run is calculated. Added a stale-item check using a new git ancestry utility to drop queued entries that have already been journaled...
+
+The first paragraph is what the human typed. Everything after it is the model, working only from that intent plus the diff. Full entry in [DEVELOPMENT_LOG.md](DEVELOPMENT_LOG.md).
+
+## How
+
+1. `yoman` shows you the commits since your last journal entry.
+2. You pick a title, then type **why** - free text, mandatory, no skipping.
+3. Your intent gets saved to disk *before* any network call, so a failed API request never loses what you typed.
+4. Gemini receives your stated intent + commit messages + a secret-filtered diff, and is explicitly told your intent is the only source of motivation - the diff is evidence of *what* changed only.
+5. You review the generated entry before it's written: accept, regenerate with a steering note, or abort.
+
+## Quickstart
+
+```
+npm install -g @arik_shemesh/yoman
+```
+
+Add your Gemini key next to the install (`.env`, gitignored):
+
+```
+GEMINI_API_KEY=your-key-here
+```
+
+Inside the repo you want to journal:
+
+```
+yoman init   # sets up .yoman/ + DEVELOPMENT_LOG.md
+yoman        # journal commits since the last entry
+```
+
+See [Install](#install) below for installing from source with `npm link`.
+
+## Table of contents
+
+- [Install](#install)
+- [Updating](#updating)
+- [Usage](#usage)
+- [Nag hook](#nag-hook)
+- [What gets sent to the LLM, and what doesn't](#what-gets-sent-to-the-llm-and-what-doesnt)
+- [Config](#config)
+- [Not yet included](#not-yet-included)
+- [Project layout](#project-layout)
 
 ## Install
 
@@ -30,7 +85,7 @@ GEMINI_API_KEY=your-key-here
 
 `.env` is gitignored - never committed.
 
-## Global command
+### Global command
 
 Run once inside the cloned yoman folder:
 
@@ -79,6 +134,24 @@ yoman retry
 
 This flushes everything queued in `.yoman/pending.json`.
 
+Before anything is written, yoman shows the generated entry and asks: accept, regenerate (optionally with a steering note like "shorter" or "focus on the refactor"), or abort. Abort keeps your input queued for `yoman retry`. Set `"preview": false` in `.yoman/config.json` to skip the preview and write immediately.
+
+Got a weak entry into the log anyway? Fix the newest one:
+
+```
+yoman amend
+```
+
+Keep or replace the title and the stated intent, regenerate, review, accept - same SHA range, same date, older entries untouched.
+
+Rebased or amended commits after journaling? `yoman` and `yoman status` will refuse with a clear message instead of guessing; run:
+
+```
+yoman reset
+```
+
+to re-anchor the journal state at the current HEAD (confirms first; skipped commits stay unjournaled).
+
 ## Nag hook
 
 Forgetting to journal is the default failure mode. Install a reminder per repo:
@@ -108,7 +181,8 @@ This adds a `post-commit` hook that prints one line once you have `nagThreshold`
   "logFile": "DEVELOPMENT_LOG.md",
   "minWhyWords": 15,
   "diffCharLimit": 20000,
-  "nagThreshold": 5
+  "nagThreshold": 5,
+  "preview": true
 }
 ```
 
@@ -127,7 +201,7 @@ Deliberately deferred:
 ## Project layout
 
 ```
-cli.js              entry point, command dispatch (init / run / retry / status / hook)
+cli.js              entry point, command dispatch (init / run / retry / status / hook / amend / reset)
 src/
   config.js          .yoman/config.json load/validate + .env key
   state.js            .yoman/state.json (lastSha) read/write
@@ -137,4 +211,7 @@ src/
   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)
+  review.js             entry preview loop (accept / regenerate / abort)
+  amend.js              regenerate the latest entry (same range, same date)
+  ask.js                shared why prompt with thin-context re-ask
 ```

package/cli.js

@@ -32,6 +32,18 @@ async function cmdInit() {
   console.log(`  log:    ${logFile}`);
 }
 
+// Rebase/amend can leave state.lastSha pointing at a commit that no longer
+// exists on this branch; every range computation would then crash or lie.
+function checkHistoryGuard(st, cwd) {
+  const git = require('./src/git');
+  if (git.shaExists(st.lastSha, cwd) && git.isAncestor(st.lastSha, git.currentHead(cwd), cwd)) {
+    return;
+  }
+  throw new Error(
+    'journal state points at a commit not in this branch\'s history (rebase or amend?). Run `yoman reset` to re-anchor at the current HEAD.'
+  );
+}
+
 // 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
@@ -50,31 +62,39 @@ async function processPendingItem(item, cfg, cwd) {
   // 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,
+  const generateBlock = async (steeringNote) => {
+    const llmPrompt = prompt.buildPrompt({
+      date: isoDate,
+      title: item.title,
+      why: item.why,
+      commitLines,
+      diff,
+      truncated,
+      steeringNote,
+    });
+    const modelBody = await llm.generateEntry({ model: cfg.model, prompt: llmPrompt });
+    return log.buildEntryBlock({
       fromSha: from,
       toSha: to,
       isoDate,
       title: item.title,
       why: item.why,
       modelBody,
-    },
-    cwd
-  );
+    });
+  };
 
+  let block = await generateBlock(null);
+
+  if (cfg.preview) {
+    const review = require('./src/review');
+    const result = await review.reviewLoop({ entryBlock: block, regenerate: generateBlock });
+    if (result.action === 'abort') return { aborted: true };
+    block = result.entryBlock;
+  }
+
+  log.prependEntry({ logFile: cfg.logFile, block }, cwd);
   state.writeState({ lastSha: to }, cwd);
+  return { aborted: false };
 }
 
 // Flush the pending queue: journal each queued item, dropping items whose
@@ -88,7 +108,7 @@ async function flushPending(cfg, cwd) {
   const state = require('./src/state');
 
   const items = pending.loadPending(cwd);
-  const result = { total: items.length, recovered: 0, dropped: 0, failed: 0 };
+  const result = { total: items.length, recovered: 0, dropped: 0, aborted: 0, failed: 0 };
 
   for (const item of items) {
     const st = state.loadState(cwd);
@@ -99,7 +119,12 @@ async function flushPending(cfg, cwd) {
       continue;
     }
     try {
-      await processPendingItem(item, cfg, cwd);
+      const { aborted } = await processPendingItem(item, cfg, cwd);
+      if (aborted) {
+        result.aborted++;
+        console.log(`kept in pending (aborted at preview): ${item.title}`);
+        continue;
+      }
       pending.removePending(item.timestamp, cwd);
       result.recovered++;
       console.log(`recovered: ${item.title}`);
@@ -130,17 +155,18 @@ async function cmdRun() {
   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) {
+    if (flush.failed > 0 || flush.aborted > 0) {
       console.error(
-        'yoman: pending entries are still failing - a new run now would journal the same commits twice.'
+        'yoman: pending entries remain - a new run now would journal the same commits twice.'
       );
-      console.error('fix the problem above (model name / quota / network), then run `yoman retry`.');
+      console.error('fix the problem (or accept the previews), then run `yoman retry`.');
       process.exitCode = 1;
       return;
     }
   }
 
   const st = state.loadState(cwd);
+  checkHistoryGuard(st, cwd);
   const head = git.currentHead(cwd);
 
   const count = git.commitCount(st.lastSha, head, cwd);
@@ -168,17 +194,8 @@ async function cmdRun() {
     });
   }
 
-  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 { askWhy } = require('./src/ask');
+  const why = await askWhy(cfg.minWhyWords);
 
   const item = {
     title,
@@ -189,7 +206,11 @@ async function cmdRun() {
   pending.addPending(item, cwd);
 
   try {
-    await processPendingItem(item, cfg, cwd);
+    const { aborted } = await processPendingItem(item, cfg, cwd);
+    if (aborted) {
+      console.log('kept in pending - run `yoman retry` when ready.');
+      return;
+    }
     pending.removePending(item.timestamp, cwd);
     console.log(`entry added to ${cfg.logFile}.`);
   } catch (err) {
@@ -213,7 +234,7 @@ async function cmdRetry() {
 
   const result = await flushPending(cfg, cwd);
   console.log(
-    `${result.recovered}/${result.total} recovered, ${result.dropped} dropped as stale, ${result.failed} still pending.`
+    `${result.recovered}/${result.total} recovered, ${result.dropped} dropped as stale, ${result.aborted} aborted, ${result.failed} still pending.`
   );
   if (result.failed > 0) process.exitCode = 1;
 }
@@ -227,6 +248,7 @@ async function cmdStatus() {
   const cwd = process.cwd();
   const cfg = config.loadConfig(cwd);
   const st = state.loadState(cwd);
+  checkHistoryGuard(st, cwd);
   const head = git.currentHead(cwd);
   const count = git.commitCount(st.lastSha, head, cwd);
   const pendingCount = pending.loadPending(cwd).length;
@@ -269,6 +291,38 @@ async function cmdNag() {
   }
 }
 
+async function cmdReset() {
+  const { confirm } = require('@inquirer/prompts');
+  const config = require('./src/config');
+  const state = require('./src/state');
+  const git = require('./src/git');
+
+  const cwd = process.cwd();
+  config.loadConfig(cwd);
+  const st = state.loadState(cwd);
+  const head = git.currentHead(cwd);
+
+  if (st.lastSha === head) {
+    console.log('journal state already at HEAD - nothing to reset.');
+    return;
+  }
+
+  const oldDesc = git.shaExists(st.lastSha, cwd)
+    ? st.lastSha.slice(0, 7)
+    : `${st.lastSha.slice(0, 7)} (no longer exists)`;
+  console.log(`re-anchor journal state: ${oldDesc} -> ${head.slice(0, 7)}`);
+  const ok = await confirm({
+    message: 'Commits between these points will never be journaled automatically. Continue?',
+    default: false,
+  });
+  if (!ok) {
+    console.log('no changes.');
+    return;
+  }
+  state.writeState({ lastSha: head }, cwd);
+  console.log(`journal state re-anchored at ${head.slice(0, 7)}.`);
+}
+
 async function cmdHook() {
   const fs = require('fs');
   const path = require('path');
@@ -327,6 +381,8 @@ async function main() {
   if (sub === 'status') return cmdStatus();
   if (sub === 'nag') return cmdNag();
   if (sub === 'hook') return cmdHook();
+  if (sub === 'reset') return cmdReset();
+  if (sub === 'amend') return require('./src/amend').runAmend();
   if (sub && sub !== 'run') {
     console.error(`yoman: unknown command "${sub}"`);
     process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arik_shemesh/yoman",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first CLI that generates engineering log entries from git history + human-provided intent, via Gemini API.",
   "main": "cli.js",
   "bin": {
@@ -17,7 +17,8 @@
     "url": "git+https://github.com/ArikShemesh/yoman.git"
   },
   "scripts": {
-    "start": "node cli.js"
+    "start": "node cli.js",
+    "test": "node test/smoke.js"
   },
   "license": "MIT",
   "dependencies": {

package/src/amend.js

@@ -0,0 +1,87 @@
+const { select, input } = require('@inquirer/prompts');
+
+// Amend the LATEST log entry only: same SHA range, same anchor, same date -
+// rewording a milestone does not change when it happened. State untouched.
+async function runAmend() {
+  const config = require('./config');
+  const state = require('./state');
+  const git = require('./git');
+  const log = require('./log');
+  const prompt = require('./prompt');
+  const llm = require('./llm');
+  const review = require('./review');
+  const { askWhy } = require('./ask');
+
+  const cwd = process.cwd();
+  const cfg = config.loadConfig(cwd);
+  config.requireApiKey();
+  state.loadState(cwd);
+
+  const latest = log.readLatestEntry(cfg.logFile, cwd);
+  if (!latest) {
+    throw new Error(`nothing to amend (no anchored entries in ${cfg.logFile}).`);
+  }
+
+  console.log(`amending latest entry: "${latest.title}" (${latest.fromSha.slice(0, 7)}..${latest.toSha.slice(0, 7)}, ${latest.isoDate})`);
+
+  const titleChoice = await select({
+    message: 'Title:',
+    choices: [
+      { name: `Keep: "${latest.title}"`, value: 'keep' },
+      { name: 'Enter new title', value: 'new' },
+    ],
+  });
+  const title =
+    titleChoice === 'keep'
+      ? latest.title
+      : await input({
+          message: 'New title:',
+          validate: (v) => v.trim().length > 0 || 'title is required',
+        });
+
+  const whyChoice = await select({
+    message: 'Stated intent (why):',
+    choices: [
+      { name: 'Keep current', value: 'keep' },
+      { name: 'Enter new why', value: 'new' },
+    ],
+  });
+  const why = whyChoice === 'keep' ? latest.why : await askWhy(cfg.minWhyWords);
+
+  const commitLines = git.commitOneliners(latest.fromSha, latest.toSha, cwd);
+  const { diff, truncated } = git.filteredDiff(latest.fromSha, latest.toSha, cfg.diffCharLimit, cwd, cfg.logFile);
+
+  const generateBlock = async (steeringNote) => {
+    const llmPrompt = prompt.buildPrompt({
+      date: latest.isoDate,
+      title,
+      why,
+      commitLines,
+      diff,
+      truncated,
+      steeringNote,
+    });
+    const modelBody = await llm.generateEntry({ model: cfg.model, prompt: llmPrompt });
+    return log.buildEntryBlock({
+      fromSha: latest.fromSha,
+      toSha: latest.toSha,
+      isoDate: latest.isoDate,
+      title,
+      why,
+      modelBody,
+    });
+  };
+
+  const first = await generateBlock(null);
+  // Amend always previews - reviewing IS the point of the command.
+  const result = await review.reviewLoop({ entryBlock: first, regenerate: generateBlock });
+  if (result.action === 'abort') {
+    console.log('amend cancelled - log unchanged.');
+    return;
+  }
+
+  log.replaceLatestEntry({ logFile: cfg.logFile, newBlock: result.entryBlock }, cwd);
+  console.log(`latest entry amended in ${cfg.logFile}.`);
+}
+
+module.exports = { runAmend };

package/src/ask.js

@@ -0,0 +1,18 @@
+const { input } = require('@inquirer/prompts');
+
+async function askWhy(minWhyWords) {
+  const ask = (message) =>
+    input({ message, validate: (v) => v.trim().length > 0 || 'why is required' });
+
+  let why = await ask('Why did you make this change? (context, mandatory):');
+  const wordCount = why.trim().split(/\s+/).filter(Boolean).length;
+  if (wordCount < minWhyWords) {
+    console.log(
+      `That's pretty thin (aim for ${minWhyWords}+ words - more context makes a better entry). One more try:`
+    );
+    why = await ask('Why did you make this change?:');
+  }
+  return why;
+}
+
+module.exports = { askWhy };

package/src/config.js

@@ -12,6 +12,7 @@ const DEFAULT_CONFIG = {
   minWhyWords: 15,
   diffCharLimit: 20000,
   nagThreshold: 5,
+  preview: true,
 };
 
 function configPath(cwd = process.cwd()) {

package/src/git.js

@@ -1,4 +1,5 @@
 const { execFileSync } = require('child_process');
+const path = require('path');
 
 const EXCLUDED_PATTERNS = [
   '.env',
@@ -14,13 +15,28 @@ const EXCLUDED_PATTERNS = [
 ];
 
 function git(args, cwd) {
-  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 1024 * 1024 * 50 });
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024 * 50,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
 }
 
 function currentHead(cwd = process.cwd()) {
   return git(['rev-parse', 'HEAD'], cwd).trim();
 }
 
+// true if sha resolves to a commit in this repo
+function shaExists(sha, cwd = process.cwd()) {
+  try {
+    git(['cat-file', '-e', `${sha}^{commit}`], cwd);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
 // true if maybeAncestor is an ancestor of sha (or the same commit)
 function isAncestor(maybeAncestor, sha, cwd = process.cwd()) {
   try {
@@ -46,8 +62,20 @@ function commitOneliners(fromSha, toSha, cwd = process.cwd()) {
   return out ? out.split('\n') : [];
 }
 
+// git's pathspec exclude requires a path inside the repo tree. logFile can
+// be configured as an absolute path outside the repo (e.g. an Obsidian
+// vault) - resolve it and only add the exclude when it actually lands
+// inside cwd; a path outside the repo can never appear in the diff anyway.
+function logFileExcludePattern(logFile, cwd) {
+  if (!logFile) return null;
+  const rel = path.isAbsolute(logFile) ? path.relative(cwd, logFile) : logFile;
+  if (path.isAbsolute(rel) || rel.startsWith('..')) return null;
+  return rel;
+}
+
 function filteredDiff(fromSha, toSha, charLimit, cwd = process.cwd(), logFile) {
-  const patterns = logFile ? [...EXCLUDED_PATTERNS, logFile] : EXCLUDED_PATTERNS;
+  const logExclude = logFileExcludePattern(logFile, cwd);
+  const patterns = logExclude ? [...EXCLUDED_PATTERNS, logExclude] : EXCLUDED_PATTERNS;
   const excludeArgs = patterns.map((p) => `:(exclude)${p}`);
   const raw = git(['diff', fromSha, toSha, '--', '.', ...excludeArgs], cwd);
   if (raw.length <= charLimit) {
@@ -65,6 +93,7 @@ function filteredDiff(fromSha, toSha, charLimit, cwd = process.cwd(), logFile) {
 module.exports = {
   currentHead,
   isAncestor,
+  shaExists,
   commitCount,
   commitSubjects,
   commitOneliners,

package/src/llm.js

@@ -1,11 +1,39 @@
 const { GoogleGenAI } = require('@google/genai');
 
+const REQUEST_TIMEOUT_MS = 60000;
+
+const SPINNER_FRAMES = ['|', '/', '-', '\\'];
+
+function startSpinner(label) {
+  if (!process.stdout.isTTY) return null;
+  let i = 0;
+  process.stdout.write(`${label} `);
+  return setInterval(() => {
+    process.stdout.write(`\r${label} ${SPINNER_FRAMES[(i = (i + 1) % SPINNER_FRAMES.length)]}`);
+  }, 100);
+}
+
+function stopSpinner(timer) {
+  if (!timer) return;
+  clearInterval(timer);
+  process.stdout.write('\r' + ' '.repeat(40) + '\r');
+}
+
 async function generateEntry({ model, prompt }) {
-  const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
+  const ai = new GoogleGenAI({
+    apiKey: process.env.GEMINI_API_KEY,
+    httpOptions: { timeout: REQUEST_TIMEOUT_MS },
+  });
+  const spinner = startSpinner('yoman: waiting for Gemini...');
   try {
     const response = await ai.models.generateContent({ model, contents: prompt });
     return response.text;
   } catch (err) {
+    if (err.name === 'AbortError') {
+      throw new Error(
+        `Gemini request timed out after ${REQUEST_TIMEOUT_MS / 1000}s - no response. Check your connection and retry.`
+      );
+    }
     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})`
@@ -15,6 +43,8 @@ async function generateEntry({ model, prompt }) {
       throw new Error(`rate limited / quota exceeded for model "${model}". (${err.message})`);
     }
     throw new Error(`Gemini API call failed: ${err.message}`);
+  } finally {
+    stopSpinner(spinner);
   }
 }
 

package/src/log.js

@@ -1,15 +1,33 @@
 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_LINE_RE = /^<!-- yoman: ([^.\s]+)\.\.(\S+) \| (\d{4}-\d{2}-\d{2}) -->$/;
+// Heading separator: entries written today use " - "; v0.1 entries used an
+// em-dash. Parse both, write only "-".
+const HEADING_RE = /^## (\d{4}-\d{2}-\d{2}) [-—] (.*)$/;
+const INTENT_RE = /^\*\*Stated intent:\*\* (.*)$/;
+
+function resolveLogFile(logFile, cwd) {
+  return path.isAbsolute(logFile) ? logFile : path.join(cwd, logFile);
+}
+
+function buildEntryBlock({ fromSha, toSha, isoDate, title, why, modelBody }) {
   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`;
+  return `${anchor}\n## ${isoDate} - ${title}\n**Stated intent:** ${why}\n\n${modelBody.trim()}\n`;
+}
 
+// Locate the topmost anchored block: [start, end) character offsets.
+function findLatestBlock(content) {
+  const start = content.search(/^<!-- yoman: /m);
+  if (start === -1) return null;
+  const afterAnchorLine = content.indexOf('\n', start) + 1;
+  const nextRel = content.slice(afterAnchorLine).search(/^<!-- yoman: /m);
+  const end = nextRel === -1 ? content.length : afterAnchorLine + nextRel;
+  return { start, end };
+}
+
+function prependEntry({ logFile, block }, cwd = process.cwd()) {
+  const file = resolveLogFile(logFile, cwd);
   const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
   const headerMatch = existing.match(/^(#[^\n]*\n)/);
 
@@ -22,7 +40,56 @@ function prependEntry(
     updated = `${block}\n${existing}`;
   }
 
+  fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, updated);
 }
 
-module.exports = { prependEntry };
+function readLatestEntry(logFile, cwd = process.cwd()) {
+  const file = resolveLogFile(logFile, cwd);
+  if (!fs.existsSync(file)) return null;
+  const content = fs.readFileSync(file, 'utf8');
+  const loc = findLatestBlock(content);
+  if (!loc) return null;
+
+  const raw = content.slice(loc.start, loc.end);
+  const lines = raw.split('\n');
+  const anchorMatch = lines[0].match(ANCHOR_LINE_RE);
+  if (!anchorMatch) return null;
+
+  let title = null;
+  let isoDate = anchorMatch[3];
+  let why = null;
+  let bodyStart = -1;
+  for (let i = 1; i < lines.length; i++) {
+    const heading = lines[i].match(HEADING_RE);
+    if (heading && title === null) {
+      isoDate = heading[1];
+      title = heading[2];
+      continue;
+    }
+    const intent = lines[i].match(INTENT_RE);
+    if (intent && why === null) {
+      why = intent[1];
+      bodyStart = i + 1;
+      break;
+    }
+  }
+  if (title === null || why === null) return null;
+
+  const body = lines.slice(bodyStart).join('\n').replace(/^\n+/, '').replace(/\n+$/, '\n');
+  return { fromSha: anchorMatch[1], toSha: anchorMatch[2], isoDate, title, why, body, raw };
+}
+
+function replaceLatestEntry({ logFile, newBlock }, cwd = process.cwd()) {
+  const file = resolveLogFile(logFile, cwd);
+  const content = fs.readFileSync(file, 'utf8');
+  const loc = findLatestBlock(content);
+  if (!loc) {
+    throw new Error(`no anchored entry found in ${logFile}`);
+  }
+  const withNewline = newBlock.endsWith('\n') ? newBlock : `${newBlock}\n`;
+  const sep = loc.end < content.length ? '\n' : '';
+  fs.writeFileSync(file, content.slice(0, loc.start) + withNewline + sep + content.slice(loc.end));
+}
+
+module.exports = { buildEntryBlock, prependEntry, readLatestEntry, replaceLatestEntry };

package/src/prompt.js

@@ -7,7 +7,7 @@ const EXAMPLE_ENTRY = `**Summary:** Added a pending.json queue that saves the us
 // 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 }) {
+function buildPrompt({ date, title, why, commitLines, diff, truncated, steeringNote }) {
   return `You are a professional engineering log writer.
 
 HARD RULES:
@@ -31,6 +31,7 @@ ${commitLines.join('\n')}
 Diff (evidence only, filtered for secrets${truncated ? ', truncated' : ''}):
 ${diff}
 
+${steeringNote ? `Reviewer note (style/emphasis guidance only, not new facts): ${steeringNote}\n` : ''}
 OUTPUT FORMAT (return only markdown, nothing else, no code fences, no heading, no "Stated intent" line):
 **Summary:** ...
 

package/src/review.js

@@ -0,0 +1,32 @@
+const { select, input } = require('@inquirer/prompts');
+
+// UI-only preview loop. Knows nothing about git, state, or pending - takes
+// a ready-to-write entry block and a regenerate callback, returns a decision.
+async function reviewLoop({ entryBlock, regenerate }) {
+  let current = entryBlock;
+  for (;;) {
+    console.log(`\n--- entry preview ${'-'.repeat(42)}`);
+    console.log(current.trim());
+    console.log('-'.repeat(60));
+    let action;
+    try {
+      action = await select({
+        message: 'Write this entry to the log?',
+        choices: [
+          { name: 'Accept - write it', value: 'accept' },
+          { name: 'Regenerate', value: 'regen' },
+          { name: 'Abort - keep in pending', value: 'abort' },
+        ],
+      });
+    } catch (err) {
+      if (err.name === 'ExitPromptError') return { action: 'abort', entryBlock: current };
+      throw err;
+    }
+    if (action !== 'regen') return { action, entryBlock: current };
+    const note = await input({ message: 'Steering note (optional, Enter to skip):' });
+    console.log('regenerating...');
+    current = await regenerate(note.trim() || null);
+  }
+}
+
+module.exports = { reviewLoop };