@leftoff/cli 0.9.18-beta.5 → 0.9.18-beta.6

package/mod/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "leftoff",
-  "version": "0.9.18-beta.5",
+  "version": "0.9.18-beta.6",
   "description": "Leftoff (formerly Checkpoints): WTF was I working on? Tracks every Claude Code session on this machine, writes a 3-line checkpoint when one goes quiet, and adds /cp (checkpoint now), /cp-name and a /leftoff pane. Talks to the local Leftoff daemon on 127.0.0.1:7429 and falls back to writing markdown in ~/checkpoints.",
   "author": {
     "name": "One Silly App"

package/mod/hooks/core.js

@@ -506,6 +506,10 @@ export function renderCheckpointMd(cp) {
   // Informative / long checkpoints (v0.4.6): sections below the three lines.
   // Older readers only pick up the **Label:** lines, so they still work.
   const bullet = (x) => '- ' + oneLine(x).replace(/^\*+/, '')
+  // 2026-11-03 decision memory: the decisions this checkpoint saw, first of the
+  // sections, so an older reader (no section open yet) skips the heading and its lines.
+  const decided = cleanDecided(cp.decided)
+  if (decided.length) { lines.push('', '### ' + DECIDED_TITLE); for (const d of decided) lines.push(renderDecidedLine(d)) }
   for (const k of SECTION_ORDER) {
     const v = cp[k]
     if (k === 'recap') { if (v) lines.push('', '### ' + SECTION_TITLES[k], oneLine(v).replace(/^\*+/, '')); continue }
@@ -1389,6 +1393,12 @@ const CHECKPOINT_BASE = [
   'If the session is blocked on the human (a question, a permission, a decision), start Next with "YOU:".',
   'Describe only what the transcript shows; the lines above it (repo, branch, title, what was asked, previous checkpoint) are background and may be out of date.',
 ]
+// 2026-11-03 decision memory: only when the transcript shows one, quoted, never invented.
+const DECIDED_SECTION = [
+  'Only if the transcript shows a decision (a choice between real alternatives that the developer made or approved, a plan they approved, a correction they gave such as "no, do X instead", or a trade-off the agent chose and said so), add after those lines a "Decided:" heading and one "- " line per decision, at most 4:',
+  '- <what was decided, in the words the transcript uses> · why: <the reason given, one line> · over: <alternative>; <alternative> · from: <asked | plan | correction | agent>',
+  'A task done, a file edited or a routine step is not a decision. Never invent a choice or a reason the transcript does not show. When unsure, or when there is none, leave the Decided heading out entirely. Skip decisions listed as already recorded.',
+]
 const INFORMATIVE_SECTIONS = [
   'Then these sections, each a heading line followed by "- " bullets (write "- none" when there is nothing; never invent):',
   'Decisions:',
@@ -1409,9 +1419,9 @@ const LONG_SECTIONS = [
   '3. <the step after that>',
 ]
 export const CHECKPOINT_SYSTEMS = {
-  short: [...CHECKPOINT_BASE, 'Write only those five lines.', 'Optionally a 6th line "Title: <max 6 words>" if asked for a title.', 'No preamble. No markdown. Under 90 words total.'].join('\n'),
-  informative: [...CHECKPOINT_BASE, ...INFORMATIVE_SECTIONS, 'Optionally a final line "Title: <max 6 words>" if asked for a title.', 'No preamble. No other markdown. Under 280 words total.'].join('\n'),
-  long: [...CHECKPOINT_BASE, ...INFORMATIVE_SECTIONS, ...LONG_SECTIONS, 'Optionally a final line "Title: <max 6 words>" if asked for a title.', 'No preamble. No other markdown. Under 630 words total.'].join('\n'),
+  short: [...CHECKPOINT_BASE, ...DECIDED_SECTION, 'Write only those five lines (and Decided, when there is one).', 'Optionally a 6th line "Title: <max 6 words>" if asked for a title.', 'No preamble. No markdown. Under 90 words total.'].join('\n'),
+  informative: [...CHECKPOINT_BASE, ...DECIDED_SECTION, ...INFORMATIVE_SECTIONS, 'Optionally a final line "Title: <max 6 words>" if asked for a title.', 'No preamble. No other markdown. Under 280 words total.'].join('\n'),
+  long: [...CHECKPOINT_BASE, ...DECIDED_SECTION, ...INFORMATIVE_SECTIONS, ...LONG_SECTIONS, 'Optionally a final line "Title: <max 6 words>" if asked for a title.', 'No preamble. No other markdown. Under 630 words total.'].join('\n'),
 }
 // The short prompt, as before v0.4.6 (kept under its old name for anything importing it).
 export const CHECKPOINT_SYSTEM = CHECKPOINT_SYSTEMS.short
@@ -1463,12 +1473,153 @@ export function buildCheckpointPrompt({ session, previous, messages, cfg = DEFAU
   head.push('Previous checkpoint: ' + prev, 'Files touched since then: ' + (files.length ? files.join(', ') : 'none'))
   if (Array.isArray(uncommitted)) head.push('Uncommitted files now: ' + (uncommitted.length ? uncommitted.slice(0, 12).join(', ') + (uncommitted.length > 12 ? ' and ' + (uncommitted.length - 12) + ' more' : '') : 'none (everything is committed)'))
   if (userNote) head.push('Note from the developer: ' + userNote)
+  // 2026-11-03: already read from its questions and plans, no model needed; redacted like the prompt, since they're saved
+  const red = (t) => redact(String(t || ''), (cfg.redact && cfg.redact.patterns) || [])
+  const found = decisionsFromMessages(messages).map((d) => ({ ...d, text: red(d.text), why: red(d.why), alternatives: d.alternatives.map(red) }))
+  if (found.length) head.push('Decisions already recorded from the session\'s questions and plans (don\'t repeat them): ' + found.map((d) => '“' + clip(d.text, 120) + '”').join('; '))
   if (session.needsInput) head.push('State: the session is waiting on the developer (' + (session.lastNotification || 'a prompt') + ').')
   if (wantTitle) head.push('Also write the line: Title: <max 6 words>.')
   const slice = transcriptSlice(messages, { maxInputChars, cwd })
   const patterns = (cfg.redact && cfg.redact.patterns) || []
   const prompt = redact(head.join('\n') + '\nTranscript (oldest→newest, trimmed):\n' + (slice || '(empty)'), patterns)
-  return { system: CHECKPOINT_SYSTEMS[len], prompt, filesTouched: files, inputChars: prompt.length, length: len, maxTokens: SUMMARY_LENGTHS[len].maxTokens }
+  return { system: CHECKPOINT_SYSTEMS[len], prompt, filesTouched: files, inputChars: prompt.length, length: len, maxTokens: SUMMARY_LENGTHS[len].maxTokens, found }
+}
+
+// ---------------------------------------------------------------- decisions (2026-11-03)
+//
+// A decision is a choice between real alternatives that someone made or
+// approved in a session: a question you answered from its options, a plan you
+// approved, a correction you gave, or a trade-off the agent chose and said so.
+// Not a task done or a file edited. A checkpoint with none is normal.
+// In a checkpoint each is one line under "### Decided":
+//   - <what was decided> · why: <one line> · over: <alt>; <alt> · from: asked
+// Both "·" and "|" separate the labelled parts (a model may write either).
+export const DECIDED_TITLE = 'Decided'
+export const DECIDED_MAX = 8
+export const DECISION_SOURCES = ['asked', 'plan', 'correction', 'agent']
+const DEC_PART = /\s+[·|]\s+(why|over|instead of|alternatives|from|source)\s*:\s*/i
+
+export function parseDecidedLine(line) {
+  let t = String(line == null ? '' : line).replace(/^\s*(?:[-*•]|\d+[.)])\s+/, '').replace(/\*\*/g, '').trim()
+  if (!t || NONE_RE.test(t)) return null
+  const d = { text: '', why: '', alternatives: [], source: 'agent' }
+  const m0 = t.match(/^\[(asked|plan|correction|agent)\]\s*/i) // "[asked] …" also reads
+  if (m0) { d.source = m0[1].toLowerCase(); t = t.slice(m0[0].length) }
+  const parts = t.split(DEC_PART)
+  d.text = parts[0].trim()
+  for (let i = 1; i + 1 < parts.length; i += 2) {
+    const k = parts[i].toLowerCase(), v = parts[i + 1].trim()
+    if (k === 'why') d.why = v
+    else if (k === 'from' || k === 'source') { const src = v.toLowerCase().replace(/[^a-z]/g, ''); if (DECISION_SOURCES.includes(src)) d.source = src }
+    else d.alternatives = v.split(/\s*;\s*/).map((x) => x.trim()).filter((x) => x && !NONE_RE.test(x))
+  }
+  return cleanDecided([d])[0] || null
+}
+
+export function renderDecidedLine(d) {
+  const safe = (x) => oneLine(x).replace(/\s+[·|]\s+/g, ' - ')
+  return '- ' + safe(d.text) + (d.why ? ' · why: ' + safe(d.why) : '') + (d.alternatives && d.alternatives.length ? ' · over: ' + d.alternatives.map((a) => safe(a).replace(/;/g, ',')).join('; ') : '') + ' · from: ' + (d.source || 'agent')
+}
+
+// Any list -> [{ text, why, alternatives, source }], one line each, deduplicated by text.
+export function cleanDecided(list) {
+  const out = [], seen = new Set()
+  for (const x of Array.isArray(list) ? list : []) {
+    if (!x || typeof x !== 'object') continue
+    const text = clip(oneLine(x.text).replace(/^["“]|["”]$/g, ''), 240)
+    if (!text || NONE_RE.test(text)) continue
+    const k = decisionNorm(text)
+    if (seen.has(k)) continue
+    seen.add(k)
+    const alternatives = (Array.isArray(x.alternatives) ? x.alternatives : []).map((a) => clip(oneLine(a), 120)).filter(Boolean).slice(0, 6)
+    out.push({ text, why: clip(oneLine(x.why), 240), alternatives, source: DECISION_SOURCES.includes(x.source) ? x.source : 'agent' })
+    if (out.length >= DECIDED_MAX) break
+  }
+  return out
+}
+export const decisionNorm = (t) => String(t || '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim()
+
+// A decision's key in a repo's log: the same decision from the same session is
+// the same entry wherever it was read (the mod or the daemon). 12 hex characters.
+export function decisionKey(sessionId, text) {
+  const str = String(sessionId || '') + '\n' + decisionNorm(text)
+  let h1 = 0x811c9dc5, h2 = 0x01000193 ^ 0x5bd1e995
+  for (let i = 0; i < str.length; i++) {
+    const c = str.charCodeAt(i)
+    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0
+    h2 = Math.imul(h2 ^ c, 0x5bd1e995) >>> 0
+    h2 = (h2 ^ (h2 >>> 15)) >>> 0
+  }
+  return (h1.toString(16).padStart(8, '0') + h2.toString(16).padStart(8, '0')).slice(0, 12)
+}
+
+// "User has answered your questions: "Q"="A", "Q2"="B". You can now continue…" -> { Q: A }
+function questionAnswers(text, questions) {
+  const out = {}
+  const t = String(text || '')
+  for (let i = 0; i < questions.length; i++) {
+    const q = questions[i]
+    const at = t.indexOf('"' + q + '"="')
+    if (at < 0) continue
+    const from = at + q.length + 4
+    let end = -1
+    for (let j = i + 1; j < questions.length && end < 0; j++) { const n = t.indexOf('", "' + questions[j] + '"="', from); if (n >= 0) end = n }
+    if (end < 0) { const m = t.slice(from).search(/"(?:\.\s|\.?$|,\s*"[^"]*"=")/); end = m >= 0 ? from + m : t.length }
+    out[q] = t.slice(from, end).trim()
+  }
+  return out
+}
+
+const PLAN_OK = /(?:approved your plan|user has approved|plan (?:was )?approved)/i
+function planHeadline(plan) {
+  const lines = String(plan || '').replace(/\r\n?/g, '\n').split('\n').map((l) => l.trim()).filter(Boolean)
+  const h = lines.find((l) => /^#{1,3}\s+\S/.test(l)) || lines[0] || ''
+  return h.replace(/^#{1,6}\s+/, '').replace(/^(?:plan|implementation plan)\s*[:\-–—]\s*/i, '').replace(/\*\*/g, '').trim()
+}
+
+// The decisions a transcript states outright, with no model: a question you
+// answered from its options (AskUserQuestion, the board's Needs you), its other
+// options as the alternatives; a plan you approved (ExitPlanMode). Messages are
+// src/transcript.js's shape, which is also $.session.messages()'s.
+export function decisionsFromMessages(messages) {
+  const out = []
+  for (const m of messages || []) {
+    if (!m || m.role !== 'assistant') continue
+    for (const u of m.toolUses || []) {
+      const name = u && (u.tool || u.name)
+      if (!u || u.isError || !u.input) continue
+      if (name === 'AskUserQuestion' && Array.isArray(u.input.questions) && u.text) {
+        const qs = u.input.questions.filter((q) => q && q.question && Array.isArray(q.options) && q.options.length >= 2)
+        const ans = questionAnswers(u.text, qs.map((q) => String(q.question)))
+        for (const q of qs) {
+          const a = ans[q.question]
+          if (!a) continue
+          const labels = q.options.map((o) => String((o && o.label) || o || '').trim()).filter(Boolean)
+          const picked = labels.filter((l) => a === l || a.split(/\s*,\s*/).includes(l))
+          const chosen = picked.length ? picked.join(', ') : a
+          const opt = q.options.find((o) => o && o.label === picked[0])
+          out.push({
+            text: clip(String(q.header ? q.header + ': ' : '') + chosen.replace(/\s*\(Recommended\)\s*/i, ''), 240),
+            why: opt && opt.description ? opt.description : '',
+            alternatives: labels.filter((l) => !picked.includes(l)).map((l) => l.replace(/\s*\(Recommended\)\s*/i, '')),
+            source: 'asked',
+          })
+        }
+      }
+      if (name === 'ExitPlanMode' && u.text && PLAN_OK.test(u.text)) {
+        const head = planHeadline(u.input.plan)
+        if (head) out.push({ text: clip('Plan approved: ' + head, 240), why: '', alternatives: [], source: 'plan' })
+      }
+    }
+  }
+  return cleanDecided(out)
+}
+
+// The checkpoint's decisions: what the transcript states outright first, then the model's.
+// earlier: decisions already in this session's previous checkpoints (by text), left out.
+export function mergeDecided(found, fromModel, { earlier = [] } = {}) {
+  const seen = new Set((earlier || []).map((d) => decisionNorm(d && d.text)))
+  return cleanDecided([...(found || []), ...(fromModel || [])]).filter((d) => !seen.has(decisionNorm(d.text)))
 }
 
 // The extra sections of an informative / long checkpoint, by the heading a
@@ -1480,11 +1631,12 @@ const SECTION_KEYS = {
   'didn\'t work': 'didntWork', 'didnt work': 'didntWork', 'did not work': 'didntWork', 'what didn\'t work': 'didntWork', 'what didnt work': 'didntWork', 'tried': 'didntWork',
   'recap': 'recap',
   'next steps': 'nextSteps', 'next 3 steps': 'nextSteps',
+  'decided': 'decided', // 2026-11-03 decision memory
 }
 export const SECTION_TITLES = { decisions: 'Key decisions', questions: 'Open questions', files: 'Files touched', didntWork: 'What didn\'t work', recap: 'Recap', nextSteps: 'Next steps' }
 const SECTION_ORDER = ['decisions', 'questions', 'files', 'didntWork', 'recap', 'nextSteps']
 const NONE_RE = /^(none|n\/a|nothing|-|—|none yet|no(ne)? (open )?questions?)\.?$/i
-const LIMITS = { decisions: 6, questions: 5, files: 10, didntWork: 5, nextSteps: 5 }
+const LIMITS = { decided: DECIDED_MAX, decisions: 6, questions: 5, files: 10, didntWork: 5, nextSteps: 5 }
 
 // "src/a.js — retry loop" / "`src/a.js`: why" -> { path, why }
 export function parseFileNote(text) {
@@ -1495,7 +1647,7 @@ export function parseFileNote(text) {
   return p ? { path: p[1], why: '' } : { path: '', why: t }
 }
 
-function emptyExtras() { return { decisions: [], questions: [], files: [], didntWork: [], recap: '', nextSteps: [] } }
+function emptyExtras() { return { decided: [], decisions: [], questions: [], files: [], didntWork: [], recap: '', nextSteps: [] } }
 export function hasExtras(cp) {
   return !!cp && (['decisions', 'questions', 'files', 'didntWork', 'nextSteps'].some((k) => Array.isArray(cp[k]) && cp[k].length) || !!cp.recap)
 }
@@ -1510,6 +1662,7 @@ function parseSections(lines) {
     if (!v || NONE_RE.test(v)) return
     if (k === 'recap') { ex.recap = ex.recap ? ex.recap + ' ' + v : v; return }
     if (k === 'files') { const f = parseFileNote(v); if (f.path || f.why) ex.files.push(f); return }
+    if (k === 'decided') { const d = parseDecidedLine(v); if (d) ex.decided.push(d); return }
     ex[k].push(v)
   }
   for (const raw of lines) {
@@ -1528,6 +1681,7 @@ function parseSections(lines) {
     if (item) push(cur, item[1])
     else if (cur === 'recap') push(cur, line)
     else if (/^(doing|stopped at|next|title|open question|note|resume)\s*:/i.test(h)) cur = null
+    else if (cur === 'decided') continue // a decision is one bullet line; loose prose under the heading is not one
     else push(cur, line)
   }
   for (const k of Object.keys(LIMITS)) ex[k] = ex[k].slice(0, LIMITS[k])
@@ -1707,6 +1861,8 @@ export function heuristicCheckpoint(messages, session = {}, { length = 'short',
   else if (lastError) next = 'Look at the last error and decide whether to retry or change approach.'
   else if (lastEdit >= 0 && lastCommit < lastEdit) next = 'Commit, or keep going.'
   const base = { doing, stoppedAt, next, title: null, openQuestion: null, parseOk: true }
+  const found = decisionsFromMessages(ms_) // 2026-11-03: only what the transcript states outright; the heuristic guesses none
+  if (found.length) base.decided = found
   const len = normalizeLength(length)
   if (len === 'short') return base
   const ex = emptyExtras()
@@ -1733,7 +1889,7 @@ export function heuristicCheckpoint(messages, session = {}, { length = 'short',
     ].filter(Boolean).join(' ')
     ex.nextSteps = next ? [next] : []
   }
-  return { ...base, ...ex }
+  return { ...base, ...ex, decided: base.decided || [] }
 }
 
 // Fallback title: {repo}@{branch} · {first 6 words of the first prompt}

package/mod/hooks/register.js

@@ -14,7 +14,7 @@
 // each event is registered once per matcher.
 import {
   DEFAULT_CONFIG, DEFAULT_PORT, mergeConfig, resolveMachine, applyEvent, checkpointDue, buildCheckpointPrompt,
-  parseCheckpointReply, retryCheckpointPrompt, betterSalvage, heuristicCheckpoint, isEmptyCheckpoint, NOTHING_TO_CHECKPOINT, renderCheckpointMd, checkpointId, checkpointFileName,
+  parseCheckpointReply, retryCheckpointPrompt, mergeDecided, betterSalvage, heuristicCheckpoint, isEmptyCheckpoint, NOTHING_TO_CHECKPOINT, renderCheckpointMd, checkpointId, checkpointFileName,
   sessionFolderName, id8, clip, toIso, resumeCommand, repoName,
   shortId, formatTabTitle, parseTabTitle, tabRenameWaits, detectTerminal, parseProcLine, trailingQuestion,
   parseCheckpointArgs, SUMMARY_LENGTHS, parseBulletList, parseCatchupArgs,
@@ -32,7 +32,7 @@ const START_SKIP_GRACE_MS = 15000 // the same for SessionStart (a cold start can
 const PERM_GRACE_MS = 1500 // how long a permission prompt tool.check saw waits for classic.PermissionRequest before the mod reports it
 
 // Module state. $.state is not used: the pane redraws with $.ui.invalidate.
-const MOD_VERSION = '0.9.18-beta.5' // keep in step with .claude-plugin/plugin.json
+const MOD_VERSION = '0.9.18-beta.6' // keep in step with .claude-plugin/plugin.json
 
 const st = {
   internal: false,
@@ -477,6 +477,20 @@ async function unlockOwnParkLocks($, cwd) {
   } catch {}
 }
 
+// ------------------------------------------------------------ decisions (2026-11-03)
+
+// The daemon's short read of this repo's accepted decisions (id + one line each, capped), or null:
+// nothing for Leftoff's own runs or a board-run headless session, when the daemon doesn't answer quickly,
+// or when the repo has none.
+const DECISIONS_TIMEOUT_MS = 800
+async function decisionContext($, e) {
+  if (st.internal || await isHeadless($)) return null
+  const q = '?session=' + encodeURIComponent(e.session_id || st.sessionId || '') + (e.cwd ? '&cwd=' + encodeURIComponent(e.cwd) : '')
+  const r = await api($, 'GET', '/v1/decisions/context' + q, undefined, DECISIONS_TIMEOUT_MS)
+  const t = r && r.ok && r.json && typeof r.json.context === 'string' ? r.json.context.trim() : ''
+  return t ? t.slice(0, 2000) : null
+}
+
 // ------------------------------------------------------------ lists (v0.5.1)
 
 // This session's saved lists, when they changed since Claude last heard
@@ -841,6 +855,7 @@ async function makeCheckpoint($, trigger, userNote, length, opts = {}) {
       doing: parsed.doing, stoppedAt: parsed.stoppedAt, next: parsed.next, openQuestion: parsed.openQuestion || null,
       userNote: userNote || null, filesTouched: ctx.filesTouched, turnsSinceLast: record.turnsSinceCheckpoint || 0,
       parseOk: parsed.parseOk, ...(parsed.format === 'markdown' ? { format: 'markdown' } : {}), generator, length: ctx.length,
+      decided: mergeDecided(ctx.found, generator && generator.by === 'heuristic' ? [] : parsed.decided, { earlier: st.lastCheckpoint && st.lastCheckpoint.decided }), // 2026-11-03 decision memory
       decisions: parsed.decisions || [], questions: parsed.questions || [], files: parsed.files || [],
       didntWork: parsed.didntWork || [], recap: parsed.recap || '', nextSteps: parsed.nextSteps || [],
     }
@@ -1172,6 +1187,14 @@ export function register(on, options) {
         const name = own && !own.id ? own.name : (own && own.name) || st.daemonTitle || null
         await applyTabTitle($, name, { force: !!parentSessionId, current: e.session_title || null })
       }
+      // 2026-11-03 decision memory: the repo's accepted decisions go to Claude as this event's context.
+      // Added to what the hooks below (yours included) answer, never in place of it.
+      const ctx = await decisionContext($, e)
+      if (ctx) {
+        const res = await next(e)
+        const r = res && typeof res === 'object' ? res : {}
+        return { ...r, additionalContext: [...(Array.isArray(r.additionalContext) ? r.additionalContext : []), ctx] }
+      }
     }
     return next(e)
   })

package/mod/skills/walkthrough/SKILL.md

@@ -11,10 +11,12 @@ How to walk through a change:
 
 1. Order the steps the way the change makes sense to read: the core idea first, then what follows from it. Not file order.
 2. Each step gets a short title and one or two sentences of why: the request it answers, the bug it fixes, or the trade-off you chose and the alternative you didn't take.
-3. Mark what matters. A step that changes behaviour is Core; a small follow-on (config, docs, a helper, a rename) is Supporting. Tests that only follow along, imports and formatting are mechanical and need no story.
+3. Mark what matters. A step that changes behaviour is Core; a small follow-on (config, docs, a helper, a rename) is Supporting. Tests that only follow along (updated to match the change), imports and formatting are mechanical and need no story.
+   - A test that doesn't really test anything is never mechanical and never safe to skip. That is a test that asserts nothing meaningful or asserts a tautology, mocks the very thing under test, snapshots its own output, had an assertion loosened or deleted to make it pass, or was skipped or disabled. Put it in a step and give it a look callout at its line saying why.
 4. Point out what deserves a second look, at the exact line: something risky or subtle (look), a guess the code makes (assumption), or behaviour no test covers (untested). Be honest about the parts you were unsure of.
-5. Never paste code. Point at it.
+5. Cite the decisions behind a step. When Leftoff lists the repo's accepted decisions (D-7f3a: …), a step may name the ones it follows or changes ("decisions": ["D-7f3a"]), using only ids from that list. A step that reverses or departs from an accepted decision gets a look callout at its line naming the decision and how it departs.
+6. Never paste code. Point at it.
 
-When Leftoff asks (the request lists hunks H1…Hn and a JSON shape): reply with that JSON object only, no prose and no code fences. Every ref is a hunk id from the list ("H3", "H3:new 14-19", "H3:old 7"); never invent ids or line numbers; put every hunk in a step or in mechanical. You may read files with Read, Grep and Glob to check details; change nothing.
+When Leftoff asks (the request lists hunks H1…Hn and a JSON shape): reply with that JSON object only, no prose and no code fences. Every ref is a hunk id from the list ("H3", "H3:new 14-19", "H3:old 7"); never invent ids or line numbers; put every hunk in a step or in mechanical. A step's "decisions" are ids from the decisions listed, never made up. You may read files with Read, Grep and Glob to check details; change nothing.
 
 When the developer asks in the terminal: give the same walkthrough as a short numbered list (title, why, file:line for each step, then what to look at closely).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leftoff/cli",
-  "version": "0.9.18-beta.5",
+  "version": "0.9.18-beta.6",
   "description": "Leftoff: WTF was I working on? Tracks every Claude Code session, writes a 3-line checkpoint when one goes quiet, and gives you a daily digest and a board, on your Mac and (optionally) your phone.",
   "keywords": [
     "claude",

package/ui/app.css

@@ -5433,3 +5433,62 @@ code .file-ref-off { font-size: inherit; }
   .hf-acts { justify-content: stretch; }
   .hf-acts .btn { flex: 1 1 auto; }
 }
+
+/* 2026-11-03 decision memory */
+.dec-list { list-style: none; margin: 0; padding: 0 0 6px; display: grid; gap: 10px; }
+.dec-row { font-size: 13.5px; line-height: 1.45; color: var(--text); }
+.dec-id { font: 600 12px/1 ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--text2); }
+.dec-why, .dec-alt, .dec-src { font-size: 12.5px; color: var(--text2); margin-top: 2px; }
+.dec-src { color: var(--muted, var(--text2)); }
+.dec-st { margin-left: 6px; font-size: 12px; color: var(--text2); white-space: nowrap; }
+.dec-open { display: inline-flex; align-items: center; min-height: 44px; font-size: 13px; }
+
+.dec-page .dec-head h1 { margin: 4px 0 2px; }
+.dec-tl { list-style: none; margin: 8px 0 0; padding: 0; display: grid; gap: 0; }
+.dec-item { position: relative; padding: 12px 0 12px 18px; border-left: 2px solid var(--line); margin-left: 6px; }
+.dec-item::before { content: ''; position: absolute; left: -6px; top: 17px; width: 10px; height: 10px; border-radius: 50%; background: var(--bg); border: 2px solid var(--text2); box-sizing: border-box; }
+.dec-item.dec-accepted::before { background: var(--text2); }
+.dec-item.dec-superseded, .dec-item.dec-rejected { opacity: .78; }
+.dec-item.dec-superseded::before { border-color: var(--line-strong, var(--line)); }
+.dec-item.dec-rejected .dec-text { text-decoration: line-through; text-decoration-thickness: 1px; }
+.dec-h { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 10px; font-size: 12.5px; color: var(--text2); }
+.dec-date { font-variant-numeric: tabular-nums; }
+.dec-repo { padding: 1px 6px; border: 1px solid var(--line); border-radius: 999px; font-size: 11.5px; }
+.dec-item .dec-st { margin-left: 0; }
+.dec-item .dec-text { font-size: 15px; line-height: 1.45; margin-top: 4px; color: var(--text); overflow-wrap: anywhere; }
+.dec-meta { font-size: 12.5px; color: var(--text2); margin-top: 4px; }
+.dec-chains { display: flex; flex-wrap: wrap; gap: 4px 12px; margin-top: 4px; font-size: 12.5px; color: var(--text2); }
+.dec-chip { font: 600 12px/1 ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--text); background: transparent; border: 1px solid var(--line); border-radius: 6px; padding: 4px 6px; min-height: 24px; cursor: pointer; position: relative; }
+.dec-chip::after { content: ''; position: absolute; inset: -10px -4px; }
+.dec-chip:hover { border-color: var(--text2); }
+.dec-sug { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 10px; margin-top: 8px; padding: 8px 10px; border: 1px dashed var(--line); border-radius: 8px; font-size: 13px; }
+.dec-acts { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 8px; }
+.dec-acts .btn, .dec-acts .linkish { min-height: 44px; }
+.dec-acts-quiet { margin-top: 0; }
+.dec-ctl { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin: 4px 0 4px; }
+.dec-ctl .sask-opt, .dec-ctl .btn, .dec-store-opts .sask-opt { min-height: 44px; }
+.dec-store-h { font-weight: 600; margin-bottom: 6px; }
+.dec-store-opts { display: inline-flex; flex-wrap: wrap; gap: 6px; }
+.dec-store p { margin: 8px 0 0; max-width: 62ch; }
+.dec-edit { display: grid; gap: 8px; margin-top: 8px; max-width: 640px; }
+.dec-edit label { display: grid; gap: 4px; font-size: 12.5px; color: var(--text2); }
+.dec-in { font: inherit; font-size: 15px; padding: 10px 12px; border: 1px solid var(--line); border-radius: 8px; background: var(--bg); color: var(--text); min-height: 44px; box-sizing: border-box; width: 100%; }
+@media (pointer: coarse) { .dec-in { font-size: 16px; } }
+.dec-in:focus-visible { outline: 2px solid var(--accent, var(--text2)); outline-offset: 1px; }
+.dec-flash { background: color-mix(in srgb, var(--text2) 10%, transparent); transition: background .6s; }
+@media (prefers-reduced-motion: reduce) { .dec-flash { transition: none; } }
+.dec-proj p { margin: 4px 0 10px; }
+
+.wt-decs { display: flex; flex-wrap: wrap; gap: 6px; margin: 6px 0 2px; }
+.wt-dec { display: inline-flex; align-items: center; gap: 6px; max-width: 100%; min-height: 32px; padding: 4px 8px; font-weight: 400; }
+@media (pointer: coarse) { .wt-dec { min-height: 44px; } }
+.wt-dec .wt-dec-id { font-weight: 600; }
+.wt-dec .wt-dec-t { font: 12.5px/1.3 var(--sans, system-ui, sans-serif); color: var(--text2); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 42ch; }
+.wt-dec-gone { border-style: dashed; }
+.wt-dec-w { font: 12px/1 var(--sans, system-ui, sans-serif); color: var(--text2); }
+.dec-chainview { margin-top: 4px; }
+
+.dv-isdec .dv-dl { display: none !important; }
+.dec-ctl .sask-opt { border: 1px solid var(--line); border-radius: 8px; padding: 0 12px; background: transparent; color: var(--text2); cursor: pointer; }
+.dec-ctl .sask-opt[aria-pressed="true"] { color: var(--text); border-color: var(--line-strong, var(--text2)); }
+@media (min-width: 700px) { .dv-isdec .dv-sheet { max-width: 760px; height: auto; max-height: 80vh; margin-left: auto; margin-right: auto; } }

package/ui/app.js

@@ -74,6 +74,7 @@ import { loginBannersHtml, loginSig, dismissedKeys as loginDismissed, dismissLog
 import { isDone, stillWorking, canMarkDone, DONE_CONFIRM, DONE_TIP, UNDONE_TIP, doneChipHtml } from './done.js' // 0.9.15 Done
 import { mountTerminal, escInTerminal } from './term.js' // 0.9.15 the embedded terminal
 import { termTipFor } from './term-host.js' // 0.9.15 a terminal for another Mac's session
+import { decidedListHtml, decisionScope, decisionsPageHtml, projectDecisionsHtml, decisionItemHtml, decisionsHref } from './decisions.js' // 2026-11-03 decision memory
 import { recapLineHtml, beforeClearHtml } from './recap-line.js' // 0.9.15 Claude Code's recap; before /clear
 import { Presence, cardRows, awayWords } from './away.js' // 0.9.15 a card shows more the longer you've been away
 import { backLine, backLineHtml, BACK_PREFIX, BACK_AWAY_MS } from './back-line.js' // 0.9.15 the recap above the Live composer
@@ -2940,6 +2941,8 @@ function sessionPageHtml(s, { spv = null, live: liveV = null, lists = null } = {
   // 2026-10-29 a calmer panel: only the newest checkpoint (Stopped + Next, the rest behind More); older ones fold
   side += '<section class="fs-sec fs-cps" id="fsCps"><h2>Checkpoints <span class="count">' + cps.length + '</span></h2>'
   side += !cps.length && !wrRow ? '<div class="empty">No checkpoints yet.</div>' : '<div class="timeline">' + wrRow + (cps.length ? cpLatestHtml(cps[0], s.agent ? null : s.id, paths) : '') + '</div>'
+  if (cps.length && Array.isArray(cps[0].decided) && cps[0].decided.length) noteSessionDecisions(s)
+  if (cps.length && Array.isArray(cps[0].decided) && cps[0].decided.length) side += foldHtml({ key: 'cp-decided', title: 'Decided', count: cps[0].decided.length, open: sideFolds.open('cp-decided'), cls: 'fs-fold-in', body: decidedListHtml(cps[0].decided, { esc, log: decisionsUi.bySession[s.id] || null, repoId: s.decisionRepo || null }) }, { esc }) // 2026-11-03 decision memory
   if (cps.length > 1) side += foldHtml({ key: 'cps-earlier', title: 'Earlier checkpoints', count: cps.length - 1, open: sideFolds.open('cps-earlier'), cls: 'fs-fold-in', body: '<div class="timeline">' + cpTimeline(cps.slice(1), null, null, paths) + '</div>' }, { esc })
   const doubted = s.checkpoints.filter((cp) => cp.doubt && cp.doubt !== 'empty') // 0.9.0: written with another session's branch: kept, folded away
   if (doubted.length) side += '<details class="tl-doubt"><summary>' + doubted.length + ' checkpoint' + (doubted.length === 1 ? '' : 's') + ' set aside: written with another session’s branch</summary><div class="timeline">' + cpTimeline(doubted, null) + '</div></details>'
@@ -4443,6 +4446,131 @@ function cpHeadLine(cp) {
   return '<div class="tl-head"><span class="t">' + esc(clock(cp.createdAt)) + '</span><span class="trig">' + esc(cp.trigger) + '</span><span>' + esc(ago(cp.createdAt)) + '</span>' +
     (cp.generator && cp.generator.by ? '<span>· ' + esc(cpByText(cp.generator)) + cpByHintHtml(cp.generator) + '</span>' : '') + '</div>'
 }
+// 2026-11-03 decision memory: the log's word on a session's decisions (by text), once its repo's log is loaded
+const decisionsUi = { bySession: {}, scope: null, view: null, all: false, editing: null, project: null, loadedRepo: {} }
+// The session panel's Decided list reads the log's word on each one (once per repo per visit, quietly)
+function noteSessionDecisions(s) {
+  const repo = s && s.decisionRepo
+  if (!repo || decisionsUi.loadedRepo[repo]) return
+  decisionsUi.loadedRepo[repo] = true
+  api('GET', '/v1/decisions?repo=' + encodeURIComponent(repo), undefined, { timeoutMs: 8000 }).then((v) => {
+    const norm = (t) => String(t || '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim()
+    const by = {}
+    for (const d of v.decisions || []) if (d.sessionId === s.id) { by[norm(d.text)] = d; if (d.original) by[norm(d.original.text)] = d }
+    decisionsUi.bySession[s.id] = by
+    const box = document.querySelector('[data-fold="cp-decided"] .fs-fold-b')
+    const cp = (s.checkpoints || []).filter((c) => !c.doubt).sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))[0]
+    if (box && cp && cp.decided) box.innerHTML = decidedListHtml(cp.decided, { esc, log: by, repoId: repo })
+  }).catch(() => { decisionsUi.loadedRepo[repo] = false })
+}
+// ---- the decision log page (#/decisions/<repo id> or #/decisions/project:<id>)
+async function viewDecisions(arg) {
+  const raw = decodeURIComponent(arg || '')
+  if (decisionsUi.scope !== raw) { decisionsUi.scope = raw; decisionsUi.view = null; decisionsUi.editing = null }
+  decisionsUi.view = await api('GET', '/v1/decisions?' + decisionScope(raw).api)
+  const want = state.route && state.route.params && state.route.params.get('d')
+  if (want && (decisionsUi.view.decisions || []).some((d) => d.id === want && (d.status === 'superseded' || d.status === 'rejected'))) decisionsUi.all = true
+  paintDecisions()
+  if (want) { const el = document.getElementById('dec-' + want); if (el) { el.scrollIntoView({ block: 'center' }); el.classList.add('dec-flash'); setTimeout(() => el.classList.remove('dec-flash'), 1600) } }
+}
+function paintDecisions() {
+  if (!decisionsUi.view || !state.route || state.route.name !== 'decisions') return
+  $app.innerHTML = decisionsPageHtml(decisionsUi.view, { all: decisionsUi.all, editing: decisionsUi.editing, may: state.mayAnswer !== false, trusted: state.viewerLocal !== false || !!(state.health && state.health.answering && state.health.answering.remoteAllowed) }, { esc })
+  if (decisionsUi.editing) { const i = $app.querySelector('.dec-edit .dec-in'); if (i) i.focus({ preventScroll: true }) }
+}
+async function decisionAction(repo, ref, action, body = {}) {
+  try {
+    await api('POST', '/v1/decisions/action', { repo, ref, action, ...body })
+    decisionsUi.loadedRepo = {}
+    if (state.route && state.route.name === 'decisions') await viewDecisions(decisionsUi.scope)
+    else if (state.route && state.route.name === 'project') loadProjectDecisions(qaUi.token, true)
+  } catch (e) { toast(e.message || String(e)) }
+}
+document.addEventListener('click', async (ev) => {
+  const btn = ev.target.closest && ev.target.closest('[data-action^="dec-"]')
+  if (!btn || btn.tagName === 'FORM') return
+  const a = btn.dataset.action
+  if (a === 'dec-act') return decisionAction(btn.dataset.repo, btn.dataset.id, btn.dataset.act, btn.dataset.act === 'accept' ? {} : {})
+  if (a === 'dec-link') return decisionAction(btn.dataset.repo, btn.dataset.id, 'link', { supersedes: [btn.dataset.to] })
+  if (a === 'dec-edit') { decisionsUi.editing = btn.dataset.id; return paintDecisions() }
+  if (a === 'dec-cancel') { decisionsUi.editing = null; return paintDecisions() }
+  if (a === 'dec-all') { decisionsUi.all = !decisionsUi.all; return paintDecisions() }
+  if (a === 'dec-copy') { const md = decisionsUi.view && decisionsUi.view.markdown; if (md && await clipWrite(md)) toast('Copied as Markdown'); else if (md) prompt('Copy this:', md); return }
+  if (a === 'dec-show') {
+    const el = document.getElementById('dec-' + btn.dataset.id)
+    if (el) { el.scrollIntoView({ block: 'center', behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth' }); el.classList.add('dec-flash'); setTimeout(() => el.classList.remove('dec-flash'), 1600); return }
+    if (btn.dataset.repo) { location.hash = '#/decisions/' + btn.dataset.repo + '?d=' + encodeURIComponent(btn.dataset.id) }
+    return
+  }
+  if (a === 'dec-store') {
+    const on = btn.dataset.on === 'true'
+    try {
+      await api('POST', '/v1/projects/' + encodeURIComponent(btn.dataset.project) + '/decision-log', { inRepo: on })
+      toast(on ? 'Accepted decisions now go into each repo’s docs/DECISIONS.md' : 'The decision log stays in Leftoff; repo files are left as they are')
+      if (state.route && state.route.name === 'decisions') await viewDecisions(decisionsUi.scope)
+      else loadProjectDecisions(qaUi.token, true)
+    } catch (e) { toast(e.message || String(e)) }
+  }
+})
+// A walkthrough step's decision chip: the decision and its chain, in the viewer (centered; a bottom sheet on a phone)
+document.addEventListener('click', (ev) => {
+  const b = ev.target.closest && ev.target.closest('[data-action="wt-dec"]')
+  if (!b) return
+  ev.preventDefault()
+  const s = wtSession(wtUi.sid)
+  openDecisionViewer(b.dataset.repo || (s && s.decisionRepo) || '', b.dataset.id, b)
+})
+async function openDecisionViewer(repo, id, from) {
+  if (!repo || !id) return
+  let v
+  try { v = await api('GET', '/v1/decisions?repo=' + encodeURIComponent(repo), undefined, { timeoutMs: 8000 }) } catch (e) { toast(e.message || String(e)); return }
+  const list = v.decisions || [], byId = new Map(list.map((d) => [d.id, d]))
+  const d = byId.get(id)
+  const el = docViewerEl()
+  el.querySelector('.dv-title').textContent = 'Decision ' + id
+  el.querySelector('.dv-dl').hidden = true
+  el.querySelector('.dv-ref').innerHTML = ''; el.querySelector('.dv-ptitle').textContent = ''
+  el.querySelector('.dv-sub').textContent = d ? (d.repoLabel || '') : 'Not in the log any more'
+  // the chain: what it replaced (oldest first), the decision, what replaced it
+  const chain = []
+  if (d) {
+    const back = []; let cur = d, guard = 0
+    while (cur && cur.supersedes && cur.supersedes.length && guard++ < 20) { const o = byId.get(cur.supersedes[0]); if (!o || back.includes(o)) break; back.unshift(o); cur = o }
+    chain.push(...back, d)
+    cur = d; guard = 0
+    while (cur && cur.supersededBy && guard++ < 20) { const n = byId.get(cur.supersededBy); if (!n || chain.includes(n)) break; chain.push(n); cur = n }
+  }
+  el.querySelector('.dv-body').innerHTML = (chain.length ? '<ol class="dec-tl dec-chainview">' + chain.map((x) => decisionItemHtml(x, { esc, byId, may: false })).join('') + '</ol>' : '<p class="faint">This decision isn’t in the repo’s log.</p>') +
+    '<p><a class="linkish dec-open" href="' + esc(decisionsHref(repo)) + '?d=' + encodeURIComponent(id) + '">Open the decision log →</a></p>'
+  el.classList.remove('dv-isref'); el.classList.add('dv-isdec')
+  refUi.from = from || null
+  el.hidden = false
+  document.documentElement.classList.add('dv-open')
+  const x = el.querySelector('.dv-x'); if (x) x.focus({ preventScroll: true })
+}
+document.addEventListener('submit', (ev) => {
+  const f = ev.target.closest && ev.target.closest('form[data-action="dec-save"]')
+  if (!f) return
+  ev.preventDefault()
+  const text = f.querySelector('[name="text"]').value, why = f.querySelector('[name="why"]').value
+  decisionsUi.editing = null
+  decisionAction(f.dataset.repo, f.dataset.id, 'edit', { text, why })
+})
+// The project page's Decisions section
+async function loadProjectDecisions(token, force = false) {
+  if (!token) return
+  try {
+    const v = await api('GET', '/v1/decisions?project=' + encodeURIComponent(token), undefined, { timeoutMs: 8000 })
+    decisionsUi.project = { token, v }
+    paintProjectDecisions()
+  } catch { decisionsUi.project = null }
+}
+function paintProjectDecisions() {
+  const box = document.getElementById('projDecisionsBox')
+  const pd = decisionsUi.project
+  if (!box || !pd || pd.token !== qaUi.token) return
+  box.innerHTML = projectDecisionsHtml(pd.v, { esc, may: state.mayAnswer !== false, scopeArg: 'project:' + ((pd.v.scope && pd.v.scope.id) || pd.token) })
+}
 // 2026-10-29 The panel's newest checkpoint: Stopped + Next; Goal, Doing, the extra sections,
 // your note and the files behind More (open or closed as you last left it on this device).
 function cpLatestHtml(cp, wtSid, paths) {
@@ -6646,6 +6774,7 @@ async function render() {
     else if (r.name === 'search') await viewSearch(r.q || '')
     else if (r.name === 'new') await viewNewSession()
     else if (r.name === 'project' && r.arg) await viewProject(r.arg)
+    else if (r.name === 'decisions' && r.arg) await viewDecisions(location.hash.replace(/^#\/decisions\//, '').split('?')[0])
     else if (r.name === 'ask' && r.arg) await viewAsk(r.arg, r.params.get('m'))
     else if (r.name === 'setup') await viewSetup()
     else if (r.name === 'tour') { location.replace('#/'); startTour({ api }); return }
@@ -6680,6 +6809,7 @@ async function viewProject(token) {
   const [page] = await Promise.all([api('GET', '/v1/project-page?scope=' + encodeURIComponent(token)), loadProjects()]) // 0.9.12: the projects, for the title's scope menu
   qaUi.page = page
   paintProject()
+  if (page && page.scope && page.scope.kind === 'project') loadProjectDecisions(token)
   if (fresh) window.scrollTo(0, 0)
   const r = state.route || {}
   if (sAskUi.carry && sAskUi.carry.token === token) { // 0.9.11: "Whole project" from a session's Ask carries the question here
@@ -6699,6 +6829,11 @@ function paintProject() {
   const kf = fa && fa.id === 'askIn' ? { a: fa.selectionStart, b: fa.selectionEnd } : null
   $app.innerHTML = out.html
   fillAsk($app, out.keys)
+  if (p.scope && p.scope.kind === 'project') { // 2026-11-03 decision memory: the project's log and where it's kept
+    const at = document.getElementById('projAsks')
+    if (at && !document.getElementById('projDecisionsBox')) { const box = document.createElement('div'); box.id = 'projDecisionsBox'; at.after(box) }
+    paintProjectDecisions()
+  }
   const ta = document.getElementById('askIn')
   if (ta) { ta.value = state.drafts['ask:' + ((p.scope || {}).key || '')] || ''; fitComposer(ta); if (kf && !ta.disabled) { ta.focus({ preventScroll: true }); try { ta.setSelectionRange(kf.a, kf.b) } catch {} } }
 }
@@ -9538,7 +9673,7 @@ function docViewerEl() {
   document.body.appendChild(el)
   return el
 }
-function closeDoc() { closeActionMenu(); endDocPrint(); const el = document.getElementById('docViewer'); if (el) { el.hidden = true; el.querySelector('.dv-body').innerHTML = ''; const back = el.classList.contains('dv-isref') ? refUi.from : null; el.classList.remove('dv-isref'); refUi.sid = null; refUi.from = null; refUi.r = null; if (back && back.isConnected) back.focus({ preventScroll: true }) } docUi.r = null; document.documentElement.classList.remove('dv-open') }
+function closeDoc() { closeActionMenu(); endDocPrint(); const el = document.getElementById('docViewer'); if (el) { el.hidden = true; el.classList.remove('dv-isdec'); el.querySelector('.dv-body').innerHTML = ''; const back = el.classList.contains('dv-isref') ? refUi.from : null; el.classList.remove('dv-isref'); refUi.sid = null; refUi.from = null; refUi.r = null; if (back && back.isConnected) back.focus({ preventScroll: true }) } docUi.r = null; document.documentElement.classList.remove('dv-open') }
 document.addEventListener('keydown', (ev) => { if (ev.key === 'Escape' && !escInTerminal(ev) && document.getElementById('docViewer') && !document.getElementById('docViewer').hidden) closeDoc() })
 async function openDoc(sessionId, { path, plan } = {}) {
   if (!sessionId || (!path && !plan)) return