claudenv 1.2.4 → 1.3.0

package/scaffold/global/.claude/skills/vibe-decisions/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: vibe-decisions
+description: |
+  Trigger before writing code that involves a non-trivial technical
+  choice (library, algorithm, data structure, architecture pattern,
+  sync vs async, correctness vs performance). Output a brief overview
+  with concrete trade-offs and 1-2 alternatives, then log the decision.
+  Two modes: auto-log (no pauses) inside `claudenv loop`, pause-and-ask
+  in interactive Claude Code. Also triggers on: "почему X?", "X vs Y?",
+  "/why", "/deeper", "/decisions", "alternatives?", "trade-offs?".
+  Do NOT trigger for trivial syntax, naming, or formatting choices.
+---
+
+# Vibe decisions
+
+## Mode detection (FIRST step every time)
+
+Check the system prompt for the marker `Vibe-decisions mode (loop)`.
+
+- **Marker present** → AUTO-LOG mode. Pick the approach, write the decision file, continue. NEVER pause. NEVER ask "делать так?". This is `claudenv loop` and pause violates autonomy=law.
+- **Marker absent** → INTERACTIVE mode. Output brief overview, wait for user confirmation or `/deeper`.
+
+Both modes share the same trigger criteria, file format, and slash-command behavior. Only output shape and pause behavior differ.
+
+## Trigger criteria
+
+Trigger if the decision involves:
+
+- choosing a library or framework from 2+ viable options
+- choosing an algorithm or data structure with meaningful trade-offs
+- architecture pattern (sync/async, push/pull, where state lives, monolith/services)
+- correctness vs performance vs simplicity trade-off
+- anything where reasonable engineers would disagree
+
+DO NOT trigger for:
+
+- syntax-level choices in a single language (for vs map, ternary vs if)
+- obvious choices (JSON for a config file, regex for simple pattern)
+- pure refactoring within established patterns
+- when the user typed `/just-code` in the previous turn
+
+## Step 1 — Check memory before deciding
+
+Before writing brief or auto-log, read related precedents:
+
+- `view` `/memories/decisions/` — list files; if any topic looks related, read it
+- Mention the precedent briefly: "Раньше для X выбирали Y (см. <file>)"
+
+## Step 2A — AUTO-LOG mode output (inside `claudenv loop`)
+
+Output exactly this shape in the user's language, then continue with code in the same turn:
+
+```
+**Выбрано:** <approach>
+**Почему:** <one sentence>
+**Альтернативы:** <A> — <terse trade-off>; <B> — <terse trade-off>
+**Лог:** /memories/decisions/<YYYY-MM-DD>-<topic-slug>.md (scope: <global|project>)
+```
+
+Immediately after the block, use the Write tool to create the decision file (see Step 4 for format). Then proceed with the actual code. Do NOT pause.
+
+## Step 2B — INTERACTIVE mode output (no loop)
+
+Output this shape and STOP. Wait for the user.
+
+```
+**Подход:** <approach>
+**Почему для этой задачи:** <1-2 lines, concrete to the task>
+**Минусы:** <1-2 lines, concrete to the task>
+**Альтернативы:** <A> — <one sentence>; <B> — <one sentence>
+```
+
+Then ask: "Делать так, или разобрать варианты подробнее?"
+
+DO NOT proceed with code until the user confirms OR asks for deep dive.
+
+## Step 3 — Deep dive (on `/deeper` or "расскажи подробнее")
+
+Expand the most recent decision into:
+
+1. **Концептуально** — what it is and the problem it solves (3-5 lines)
+2. **Как работает** — simplified model (5-10 lines, optionally a code sketch)
+3. **2-3 варианта реализации** — for each: code + 1-2 lines of trade-offs
+4. **Канон** — 2-4 references. First check `~/.claudenv/memories/canon/index.yaml` for a topic match. If a match exists — cite those. If not — WebSearch for authoritative sources and after the response suggest `claudenv canon add <topic> <url> --why "..."`.
+
+After deep dive, in auto-log mode update the existing decision file's `deep_dive_done: yes` field. In interactive mode wait for confirmation.
+
+## Step 4 — Write the decision file
+
+Path:
+
+- `scope: global` (default) → `~/.claudenv/memories/decisions/<YYYY-MM-DD>-<topic-slug>.md`
+- `scope: project` → `<cwd>/.claude/memories/decisions/<YYYY-MM-DD>-<topic-slug>.md`
+
+**Choose scope BEFORE writing — don't rely on hook to rewrite.** Project scope if the choice mentions project-only artifacts (module name, env var, deployment target, internal service). Otherwise global.
+
+File content:
+
+```
+---
+date: <ISO 8601 datetime with timezone>
+project: <basename of cwd, or "(none)" if no project context>
+topic: <plain-language summary of what was decided>
+chose: <approach>
+alternatives_considered: [<A>, <B>]
+reason: <one sentence why>
+deep_dive_done: <yes|no>
+sources_consulted: [<canon-id-or-url>, ...]
+scope: <global|project>
+---
+
+<optional body — caveats, follow-ups, links>
+
+__VIBE_DECISION__
+```
+
+The `__VIBE_DECISION__` marker on the last line lets the `decisions-logger` hook detect the file even if the path check fails. Always include it.
+
+## Slash-commands the skill responds to
+
+- `/why <X>` — explain X briefly without committing a decision; do NOT write a decision file
+- `/deeper` — deep dive on the most recent decision (Step 3)
+- `/decisions [N]` — execute Bash `claudenv decisions list --limit ${N:-10}` and show output
+- `/canon [<topic>]` — execute Bash `claudenv canon list <topic>` and show output
+- `/just-code` — suppress vibe-decisions on the NEXT response only; resume on the one after
+
+Trigger phrases that also count (in any language): "расскажи подробнее", "почему именно X?", "X vs Y?", "alternatives?", "trade-offs?".

package/scaffold/global/.claude/skills/vibe-decisions/deep-dive-template.md

@@ -0,0 +1,41 @@
+# Deep dive template
+
+Used by the `vibe-decisions` skill when the user requests `/deeper` or asks "расскажи подробнее", "X vs Y?", "trade-offs?".
+
+Fill each section concretely against the current task — generic prose is the failure mode here.
+
+## 1. Концептуально (3-5 строк)
+
+What this approach is and what problem it solves. Mention the canonical name and 1-2 alternatives by name (so the reader can search later). Avoid marketing language.
+
+## 2. Как работает (5-10 строк, опц. code sketch)
+
+A simplified mental model. If a 10-15 line code sketch clarifies the mechanism, include it. Otherwise prose. Mention 1-2 invariants that matter — what the approach guarantees and what it explicitly does not.
+
+## 3. Варианты реализации (2-3)
+
+For each variant:
+
+### Variant N — <name>
+
+```<lang>
+# minimal sketch, 5-15 lines
+```
+
+**Когда подходит:** <one line>
+**Когда не подходит:** <one line>
+
+## 4. Канон (2-4 ссылки)
+
+Priority: matches from `~/.claudenv/memories/canon/index.yaml` by topic. If no match, WebSearch and propose `claudenv canon add` after the response.
+
+Format each entry:
+
+- **<title>** — <author or venue> — <1 line why>
+  <url>
+
+## After deep dive
+
+In AUTO-LOG mode: update the existing decision file to set `deep_dive_done: yes` and append source URLs to `sources_consulted`.
+
+In INTERACTIVE mode: ask the user "Принимаем этот подход?" before writing/updating the decision file.

package/scaffold/global-claudenv/config.yaml

@@ -0,0 +1,16 @@
+# claudenv global config.
+# Created by `claudenv install` if missing; preserved on subsequent installs.
+
+# Default model for `claudenv loop` if --model is not passed.
+# Options: opus, sonnet, haiku
+default_model: sonnet
+
+# Auto-commit ~/.claudenv/ after each session (planned for 1.4 — currently unused).
+auto_commit: false
+
+# Memory scope default when vibe-decisions can't infer.
+# Options: global, project
+default_scope: global
+
+# INDEX.md regeneration: maximum number of recent decisions to surface.
+index_recent_limit: 5

package/scaffold/global-claudenv/memories/INDEX.md

@@ -0,0 +1,25 @@
+# claudenv memory — INDEX
+
+> Auto-generated by `claudenv hook regen-index` after each session and after each `claudenv loop` iteration. Hand-edits will be overwritten.
+> Last regenerated: <never>
+
+## Recent decisions
+
+_No decisions logged yet. Make a non-trivial technical choice in a session — the `vibe-decisions` skill will log it here._
+
+## Active preferences
+
+_No `user/preferences.md` yet. Create one at `~/.claudenv/memories/user/preferences.md` (template at `preferences.md.example`)._
+
+## Active projects
+
+_Per-project facts live in each project's `.claude/memories/project.md`. This index lists projects seen recently._
+
+---
+
+Files in this directory:
+
+- `INDEX.md` — this file
+- `decisions/` — global cross-project tech decisions
+- `canon/` — personal canon of references
+- `user/` — cross-project preferences

package/scaffold/global-claudenv/memories/canon/index.yaml

@@ -0,0 +1,21 @@
+# Личный канон. Только то что вы прочитали и сочли важным.
+# Добавляйте через: claudenv canon add <topic> <url> --why "<reason>"
+# Используется vibe-decisions skill в /deeper для подбора ссылок.
+
+# Стартовое наполнение пустое — канон растёт от реальных decision-моментов.
+# Пример (раскомментируйте и адаптируйте):
+
+# distributed_locks:
+#   - title: "How to do distributed locking"
+#     author: Martin Kleppmann
+#     url: https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html
+#     why: "обязательное чтение перед выбором Redis для locks"
+#     added: 2026-05-27
+
+# raft_consensus:
+#   - title: "In Search of an Understandable Consensus Algorithm"
+#     authors: [Ongaro, Ousterhout]
+#     venue: "USENIX ATC 2014"
+#     url: https://raft.github.io/raft.pdf
+#     why: "оригинальный paper"
+#     added: 2026-05-27

package/scaffold/global-claudenv/memories/user/preferences.md.example

@@ -0,0 +1,16 @@
+# User preferences
+
+Copy this file to `preferences.md` (in the same directory) and edit. The `vibe-decisions` skill reads it and uses it as context when suggesting approaches.
+
+Format: free-form markdown, but short lines (one preference per line) work best for cache stability.
+
+## Examples
+
+- Default branch naming: `<initials>/<short-desc>`
+- Commit style: conventional commits, lowercase subject
+- Editor: helix
+- Package manager: pnpm (Node), uv (Python), cargo (Rust)
+- TypeScript: strict + noUncheckedIndexedAccess
+- Python: type hints required, no `Any` без TODO
+- Prefer integration tests с реальной БД over heavy mocking
+- Не использовать `as` import unless prefix collision

package/src/autonomy.js

@@ -9,6 +9,7 @@ import {
   generateAuditLogHook,
   generateAliases,
   generateCIWorkflow,
+  isGlobalInstall,
 } from './hooks-gen.js';
 import { detectTechStack } from './detector.js';
 
@@ -25,10 +26,14 @@ export async function generateAutonomyConfig(profileName, projectDir, options =
   const profile = getProfile(profileName);
   const detected = options.detected || (await detectTechStack(projectDir));
 
+  // Hook commands need `claudenv` on PATH. If user installed via npm install -g
+  // we can call `claudenv` directly; otherwise fall back to `npx claudenv`.
+  const claudenvCmd = (await isGlobalInstall()) ? 'claudenv' : 'npx claudenv';
+
   const files = [
     {
       path: '.claude/settings.json',
-      content: generateSettingsJson(profile, detected),
+      content: generateSettingsJson(profile, detected, { claudenvCmd }),
     },
     {
       path: '.claude/hooks/pre-tool-use.sh',
@@ -63,6 +68,7 @@ export function printSecuritySummary(profile) {
   console.log(`\n  Security summary — ${profile.name} profile\n`);
   console.log(`  ${'─'.repeat(50)}`);
 
+  console.log(`  Default model:      ${profile.model || 'sonnet'}`);
   console.log(`  Skip permissions:   ${profile.skipPermissions ? 'YES (--dangerously-skip-permissions)' : 'No'}`);
   console.log(`  Credential policy:  ${profile.credentialPolicy}`);
 

package/src/canon.js

@@ -0,0 +1,214 @@
+/**
+ * CLI: `claudenv canon add/list/search/prune`
+ *
+ * Owns ~/.claudenv/memories/canon/index.yaml — a topic-keyed list of links.
+ * Format intentionally simple (flat YAML) so it's human-editable.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { canonIndexPath } from './memory-paths.js';
+
+/**
+ * Read the canon yaml as a JS object. Tolerant to missing or empty files.
+ *
+ * Parser is intentionally minimal — full YAML would be overkill for a flat
+ * topic → [entries] mapping and would add a dependency.
+ */
+async function readCanon() {
+  let text;
+  try {
+    text = await readFile(canonIndexPath(), 'utf-8');
+  } catch {
+    return {};
+  }
+
+  const result = {};
+  let currentTopic = null;
+  let currentEntry = null;
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (!line || line.startsWith('#')) continue;
+
+    // Topic key: `topic_name:` at column 0
+    const topicMatch = /^([a-zA-Z][a-zA-Z0-9_-]*):\s*$/.exec(line);
+    if (topicMatch) {
+      currentTopic = topicMatch[1];
+      result[currentTopic] = [];
+      currentEntry = null;
+      continue;
+    }
+
+    // List entry start: `  - key: value` or `  - key:` (multiline value)
+    const entryStartMatch = /^\s+-\s+([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/.exec(line);
+    if (entryStartMatch && currentTopic) {
+      currentEntry = {};
+      currentEntry[entryStartMatch[1]] = unquote(entryStartMatch[2]);
+      result[currentTopic].push(currentEntry);
+      continue;
+    }
+
+    // Subsequent key in same entry: `    key: value`
+    const subKeyMatch = /^\s+([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/.exec(line);
+    if (subKeyMatch && currentEntry) {
+      currentEntry[subKeyMatch[1]] = unquote(subKeyMatch[2]);
+      continue;
+    }
+  }
+
+  return result;
+}
+
+function unquote(s) {
+  const trimmed = s.trim();
+  if (!trimmed) return '';
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  // Inline arrays — pass through as raw string for now (rare in canon).
+  return trimmed;
+}
+
+/**
+ * Append an entry to the canon. Creates the topic group if absent.
+ *
+ * @param {object} opts
+ * @param {string} opts.topic - Topic slug
+ * @param {string} opts.url - Required
+ * @param {string} opts.why - Required
+ * @param {string} [opts.title]
+ * @param {string} [opts.author]
+ */
+export async function canonAdd({ topic, url, why, title, author }) {
+  if (!topic || !url || !why) {
+    throw new Error('claudenv canon add <topic> <url> --why "<reason>" required');
+  }
+
+  const canon = await readCanon();
+  if (!canon[topic]) canon[topic] = [];
+
+  const entry = {
+    ...(title ? { title } : {}),
+    ...(author ? { author } : {}),
+    url,
+    why,
+    added: new Date().toISOString().slice(0, 10),
+  };
+
+  // Skip duplicates by URL within the same topic.
+  const dup = canon[topic].find((e) => e.url === url);
+  if (dup) return { added: false, reason: 'duplicate url in same topic', entry: dup };
+
+  canon[topic].push(entry);
+  await writeCanon(canon);
+  return { added: true, topic, entry };
+}
+
+/**
+ * List all topics with their entries, or filter by one topic.
+ */
+export async function canonList(topic) {
+  const canon = await readCanon();
+  if (topic) {
+    return { [topic]: canon[topic] || [] };
+  }
+  return canon;
+}
+
+/**
+ * Substring search across title/why/url, returning matching entries grouped by topic.
+ */
+export async function canonSearch(query) {
+  if (!query) throw new Error('claudenv canon search <query> required');
+  const q = query.toLowerCase();
+  const canon = await readCanon();
+  const result = {};
+  for (const [topic, entries] of Object.entries(canon)) {
+    const hits = entries.filter((e) =>
+      [e.title, e.why, e.url, e.author].some((v) => v && v.toLowerCase().includes(q))
+    );
+    if (hits.length) result[topic] = hits;
+  }
+  return result;
+}
+
+/**
+ * Find entries whose `added` date is older than `months` months — candidates
+ * for review. Returns an array of `{topic, entry}` items.
+ */
+export async function canonPrune(months = 6) {
+  const cutoff = new Date();
+  cutoff.setMonth(cutoff.getMonth() - months);
+  const canon = await readCanon();
+  const stale = [];
+  for (const [topic, entries] of Object.entries(canon)) {
+    for (const entry of entries) {
+      if (!entry.added) {
+        stale.push({ topic, entry, reason: 'no `added` date' });
+        continue;
+      }
+      const added = new Date(entry.added);
+      if (!Number.isNaN(added.getTime()) && added < cutoff) {
+        stale.push({ topic, entry });
+      }
+    }
+  }
+  return stale;
+}
+
+/**
+ * Serialize canon back to YAML form. Comment-light, human-editable.
+ */
+async function writeCanon(canon) {
+  const lines = [];
+  lines.push('# Личный канон. Добавляйте через: claudenv canon add <topic> <url> --why "<reason>"');
+  lines.push('');
+  for (const [topic, entries] of Object.entries(canon)) {
+    lines.push(`${topic}:`);
+    for (const e of entries) {
+      const keys = Object.keys(e);
+      if (keys.length === 0) continue;
+      const [firstKey, ...rest] = keys;
+      lines.push(`  - ${firstKey}: ${quote(e[firstKey])}`);
+      for (const k of rest) {
+        lines.push(`    ${k}: ${quote(e[k])}`);
+      }
+    }
+    lines.push('');
+  }
+  await mkdir(dirname(canonIndexPath()), { recursive: true });
+  await writeFile(canonIndexPath(), lines.join('\n'), 'utf-8');
+}
+
+function quote(v) {
+  if (typeof v !== 'string') return String(v);
+  if (/[:#"\n]/.test(v)) return JSON.stringify(v);
+  return v;
+}
+
+/**
+ * Format canon for terminal output.
+ */
+export function formatCanon(canon) {
+  const topics = Object.keys(canon);
+  if (topics.length === 0) {
+    return 'Канон пуст. Добавь первые записи через `claudenv canon add <topic> <url> --why "..."`.';
+  }
+  const lines = [];
+  for (const t of topics) {
+    lines.push(`## ${t}`);
+    for (const e of canon[t] || []) {
+      const title = e.title || '(no title)';
+      const author = e.author ? ` — ${e.author}` : '';
+      lines.push(`  - ${title}${author}`);
+      lines.push(`    ${e.url}`);
+      if (e.why) lines.push(`    why: ${e.why}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd();
+}

package/src/decisions.js

@@ -0,0 +1,161 @@
+/**
+ * CLI: `claudenv decisions list/show/search/archive`
+ *
+ * Reads decision files from both global (~/.claudenv/memories/decisions/) and
+ * the current project (.claude/memories/decisions/). Files outside these two
+ * roots are not considered decisions.
+ */
+
+import { readFile, writeFile, readdir, mkdir, rename, stat } from 'node:fs/promises';
+import { join, basename, dirname } from 'node:path';
+import {
+  globalDecisionsDir,
+  projectDecisionsDir,
+  parseFrontmatter,
+} from './memory-paths.js';
+
+async function readDir(dir) {
+  try {
+    return await readdir(dir);
+  } catch {
+    return [];
+  }
+}
+
+async function loadDecision(file, scopeHint) {
+  let text;
+  try {
+    text = await readFile(file, 'utf-8');
+  } catch {
+    return null;
+  }
+  const fm = parseFrontmatter(text) || {};
+  return {
+    file,
+    slug: basename(file, '.md'),
+    date: fm.date || null,
+    topic: fm.topic || basename(file, '.md'),
+    chose: fm.chose || '',
+    reason: fm.reason || '',
+    alternatives: fm.alternatives_considered || [],
+    scope: fm.scope || scopeHint,
+    deepDive: fm.deep_dive_done === 'yes' || fm.deep_dive_done === true,
+    text,
+  };
+}
+
+/**
+ * Collect decisions from global + project roots. Newest first by `date:`.
+ *
+ * @param {object} opts
+ * @param {string} [opts.cwd] - Project root (default: process.cwd())
+ * @param {'global'|'project'|'all'} [opts.scope] - Filter
+ */
+export async function listDecisions({ cwd = process.cwd(), scope = 'all' } = {}) {
+  const out = [];
+
+  if (scope === 'global' || scope === 'all') {
+    for (const name of await readDir(globalDecisionsDir())) {
+      if (!name.endsWith('.md')) continue;
+      const d = await loadDecision(join(globalDecisionsDir(), name), 'global');
+      if (d) out.push(d);
+    }
+  }
+
+  if (scope === 'project' || scope === 'all') {
+    const pdir = projectDecisionsDir(cwd);
+    for (const name of await readDir(pdir)) {
+      if (!name.endsWith('.md')) continue;
+      const d = await loadDecision(join(pdir, name), 'project');
+      if (d) out.push(d);
+    }
+  }
+
+  out.sort((a, b) => {
+    if (!a.date && !b.date) return 0;
+    if (!a.date) return 1;
+    if (!b.date) return -1;
+    return b.date.localeCompare(a.date);
+  });
+  return out;
+}
+
+/**
+ * Show one decision by slug or substring. Returns the full file text.
+ */
+export async function showDecision(idOrSlug, { cwd = process.cwd() } = {}) {
+  if (!idOrSlug) throw new Error('Usage: claudenv decisions show <id-or-slug>');
+  const all = await listDecisions({ cwd });
+  // Exact slug match first, then substring on slug, then substring on topic.
+  let match = all.find((d) => d.slug === idOrSlug);
+  if (!match) match = all.find((d) => d.slug.includes(idOrSlug));
+  if (!match) match = all.find((d) => d.topic.toLowerCase().includes(idOrSlug.toLowerCase()));
+  if (!match) {
+    const err = new Error(`No decision matching: ${idOrSlug}`);
+    err.notFound = true;
+    throw err;
+  }
+  return match;
+}
+
+/**
+ * Substring search across topic and reason fields.
+ */
+export async function searchDecisions(query, { cwd = process.cwd() } = {}) {
+  if (!query) throw new Error('Usage: claudenv decisions search <query>');
+  const q = query.toLowerCase();
+  const all = await listDecisions({ cwd });
+  return all.filter(
+    (d) =>
+      d.topic.toLowerCase().includes(q) ||
+      d.reason.toLowerCase().includes(q) ||
+      d.chose.toLowerCase().includes(q)
+  );
+}
+
+/**
+ * Move a decision file to `<scope-dir>/archive/`. Preserves frontmatter.
+ */
+export async function archiveDecision(idOrSlug, { cwd = process.cwd() } = {}) {
+  const target = await showDecision(idOrSlug, { cwd });
+  const archiveDir = join(dirname(target.file), 'archive');
+  await mkdir(archiveDir, { recursive: true });
+  const dest = join(archiveDir, basename(target.file));
+  await rename(target.file, dest);
+  return { from: target.file, to: dest };
+}
+
+/**
+ * Format a list for terminal output.
+ */
+export function formatDecisionList(decisions) {
+  if (decisions.length === 0) return 'No decisions yet.';
+  const lines = [];
+  for (const d of decisions) {
+    const date = d.date ? d.date.slice(0, 10) : '         ';
+    const scope = d.scope === 'project' ? '[project]' : '[global] ';
+    const deep = d.deepDive ? ' ⛏' : '';
+    lines.push(`${date} ${scope} ${d.topic} → ${d.chose} (${d.slug})${deep}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Format one decision for terminal output (full).
+ */
+export function formatDecisionDetail(d) {
+  const lines = [];
+  lines.push(`# ${d.topic}`);
+  lines.push('');
+  lines.push(`- **slug:** ${d.slug}`);
+  lines.push(`- **date:** ${d.date || '(none)'}`);
+  lines.push(`- **scope:** ${d.scope}`);
+  lines.push(`- **chose:** ${d.chose}`);
+  lines.push(`- **reason:** ${d.reason}`);
+  if (Array.isArray(d.alternatives) && d.alternatives.length) {
+    lines.push(`- **alternatives:** ${d.alternatives.join(', ')}`);
+  }
+  lines.push(`- **deep dive done:** ${d.deepDive ? 'yes' : 'no'}`);
+  lines.push(`- **file:** ${d.file}`);
+  return lines.join('\n');
+}