atris 3.16.1 → 3.22.0

package/commands/theme.js

@@ -0,0 +1,217 @@
+// atris theme — brand themes for the whole design system. Define your colors and
+// fonts once in .atris/theme.json; every deck, HTML page, and site uses them.
+//
+//   atris theme create        guided interview -> your own theme (alias: new)
+//   atris theme edit <name>   re-run the interview to tweak an existing theme
+//   atris theme init          scaffold a starter .atris/theme.json
+//   atris theme list          list built-in + project themes
+//   atris theme show <name>   print a resolved theme
+
+const readline = require('readline');
+const {
+  mergedThemes, writeStarterTheme, loadProjectThemes, loadThemeRecipe, PROJECT_THEME_FILE,
+  MOODS, MOOD_NAMES, FONT_PERSONALITIES, buildTheme, themeWarnings, upsertProjectTheme,
+  resolveMode, isHex, normHex, hexToRgb,
+} = require('../lib/theme');
+const { THEMES: HTML_THEMES } = require('../lib/html-render');
+
+// ---------- small terminal helpers ----------
+function parseFlags(argv) {
+  const flags = {}; const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-y' || a === '--yes') { flags.yes = true; continue; }
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next != null && !next.startsWith('--')) { flags[key] = next; i++; }
+      else flags[key] = true;
+      continue;
+    }
+    pos.push(a);
+  }
+  return { flags, pos };
+}
+
+// a colored block when we're on a real terminal, two blank cells otherwise (clean pipes)
+function sw(hex) {
+  const c = hexToRgb(hex);
+  if (!c || !process.stdout.isTTY) return '  ';
+  return `\x1b[48;2;${c.r};${c.g};${c.b}m  \x1b[0m`;
+}
+
+function printPreview(name, answers, theme) {
+  const c = theme.color;
+  const mode = resolveMode(answers.mood || 'editorial', answers.mode);
+  console.log(`\n  ${name}  ·  ${answers.mood || 'editorial'} ${mode}`);
+  const row = (label, hex) => console.log(`   ${sw(hex)} ${label.padEnd(8)} ${hex}`);
+  row('bg', c.bg);
+  row('ink', c.ink);
+  row('accent', c.accent);
+  row('accent2', c.accent2);
+  console.log(`      ${theme.fonts.display} display, ${theme.fonts.body} body`);
+}
+
+// ---------- the guided interview (tasteful vocabulary) ----------
+async function interview(defaults = {}) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((res) => rl.question(q, res));
+  const ans = {};
+  try {
+    console.log('\n  let\'s make your theme. five quick choices, all changeable later.\n');
+
+    const dn = defaults.name || 'brand';
+    ans.name = (await ask(`  1/5  name it [${dn}]: `)).trim() || dn;
+
+    console.log('\n  2/5  what should it feel like?');
+    MOOD_NAMES.forEach((m, i) => console.log(`     ${i + 1}. ${m.padEnd(10)} ${MOODS[m].blurb}`));
+    const dmIdx = Math.max(0, MOOD_NAMES.indexOf(defaults.mood || 'editorial'));
+    const moodPick = (await ask(`     pick 1-${MOOD_NAMES.length} [${dmIdx + 1}]: `)).trim();
+    ans.mood = MOOD_NAMES[(parseInt(moodPick, 10) - 1)] || MOOD_NAMES[dmIdx];
+    const mood = MOODS[ans.mood];
+
+    if (mood.forceMode) {
+      ans.mode = mood.forceMode;
+      console.log(`     (${ans.mood} is ${mood.forceMode}-only)`);
+    } else {
+      const dmode = defaults.mode || mood.defaultMode;
+      const mp = (await ask(`\n  3/5  light or dark? [${dmode[0]}]: `)).trim().toLowerCase();
+      ans.mode = mp.startsWith('l') ? 'light' : mp.startsWith('d') ? 'dark' : dmode;
+    }
+
+    console.log('\n  4/5  your accent — the one color that is unmistakably yours:');
+    mood.swatches.forEach((s, i) => console.log(`     ${i + 1}. ${sw(s)} ${s}`));
+    const dac = normHex(defaults.accent) || mood.swatches[0];
+    const ap = (await ask(`     pick 1-${mood.swatches.length}, or paste a hex [${dac}]: `)).trim();
+    if (!ap) ans.accent = dac;
+    else if (/^[1-9]$/.test(ap) && mood.swatches[parseInt(ap, 10) - 1]) ans.accent = mood.swatches[parseInt(ap, 10) - 1];
+    else if (isHex(ap)) ans.accent = normHex(ap);
+    else { console.log(`     '${ap}' is not 1-${mood.swatches.length} or a hex, keeping ${dac}`); ans.accent = dac; }
+
+    console.log('\n  5/5  type personality:');
+    const fontKeys = Object.keys(FONT_PERSONALITIES);
+    fontKeys.forEach((k, i) => console.log(`     ${i + 1}. ${k.padEnd(15)} ${FONT_PERSONALITIES[k].display} / ${FONT_PERSONALITIES[k].body}`));
+    const dfIdx = fontKeys.indexOf(typeof defaults.fonts === 'string' ? defaults.fonts : mood.fonts);
+    const fp = (await ask(`     pick 1-${fontKeys.length} [${(dfIdx < 0 ? 0 : dfIdx) + 1}]: `)).trim();
+    ans.fonts = fontKeys[(parseInt(fp, 10) - 1)] || fontKeys[dfIdx < 0 ? 0 : dfIdx];
+  } finally {
+    rl.close();
+  }
+  return ans;
+}
+
+function confirmSync(q) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => rl.question(q, (a) => { rl.close(); res(!String(a).trim().toLowerCase().startsWith('n')); }));
+}
+
+// shared create/edit flow. defaults seed an edit; flags override anything; interactive
+// only when there's a TTY and no defining flags.
+async function createFlow({ name, defaults = {}, flags }) {
+  const answers = { ...defaults };
+  if (flags.mood) answers.mood = flags.mood;
+  if (flags.mode) answers.mode = flags.mode;
+  if (flags.accent) answers.accent = flags.accent;
+  if (flags.accent2) answers.accent2 = flags.accent2;
+  if (flags.fonts) answers.fonts = flags.fonts;
+  let themeName = name || flags.name || defaults.name || 'brand';
+
+  const hasDefiningFlag = Boolean(flags.mood || flags.mode || flags.accent || flags.accent2 || flags.fonts || flags.name);
+  const interactive = Boolean(process.stdin.isTTY) && !flags.yes && !hasDefiningFlag;
+
+  if (interactive) {
+    const r = await interview({ name: themeName, ...answers });
+    Object.assign(answers, r);
+    themeName = r.name || themeName;
+  }
+  themeName = String(themeName).trim() || 'brand';
+
+  if (answers.mood && !MOODS[answers.mood]) { console.error(`  unknown mood "${answers.mood}". try: ${MOOD_NAMES.join(', ')}`); return 2; }
+  if (answers.accent && !isHex(answers.accent)) { console.error(`  not a hex color: ${answers.accent}`); return 2; }
+  if (answers.accent2 && !isHex(answers.accent2)) { console.error(`  not a hex color: ${answers.accent2}`); return 2; }
+  if (answers.fonts && typeof answers.fonts === 'string' && !FONT_PERSONALITIES[answers.fonts]) {
+    console.error(`  unknown font personality "${answers.fonts}". try: ${Object.keys(FONT_PERSONALITIES).join(', ')}`); return 2;
+  }
+
+  const theme = buildTheme(answers);
+  printPreview(themeName, answers, theme);
+  const warns = themeWarnings(theme);
+  if (warns.length) { console.log('\n  heads up:'); warns.forEach((w) => console.log(`   ! ${w}`)); }
+
+  if (interactive) {
+    const ok = await confirmSync('\n  save this theme? [enter = yes, n = cancel] ');
+    if (!ok) { console.log('  cancelled, nothing written.\n'); return 0; }
+  }
+
+  const recipe = {
+    mood: answers.mood || 'editorial',
+    mode: resolveMode(answers.mood || 'editorial', answers.mode),
+    accent: theme.color.accent,
+    accent2: theme.color.accent2,
+    fonts: typeof answers.fonts === 'string' ? answers.fonts : (MOODS[answers.mood || 'editorial'].fonts),
+  };
+
+  let res;
+  try { res = upsertProjectTheme(themeName, theme, process.cwd(), recipe); }
+  catch (e) { console.error(`  ${e.message}`); return 1; }
+
+  console.log(`\n  ✓ ${res.action} theme "${res.name}" in ${PROJECT_THEME_FILE}  (${res.count} theme${res.count === 1 ? '' : 's'})`);
+  console.log('    use it anywhere:');
+  console.log(`      atris deck from doc.md --html --theme ${res.name}`);
+  console.log(`      atris site ./docs --theme ${res.name}`);
+  console.log(`    tweak it later:  atris theme edit ${res.name}\n`);
+  return 0;
+}
+
+async function run(argv) {
+  const sub = argv[0];
+  const rest = argv.slice(1);
+
+  if (sub === 'create' || sub === 'new') {
+    const { flags, pos } = parseFlags(rest);
+    return createFlow({ name: pos[0], flags });
+  }
+
+  if (sub === 'edit') {
+    const { flags, pos } = parseFlags(rest);
+    const name = pos[0] || flags.name;
+    if (!name) { console.error('  usage: atris theme edit <name>'); return 2; }
+    const existing = loadProjectThemes()[name];
+    if (!existing) { console.error(`  no project theme "${name}". make one with: atris theme create ${name}`); return 2; }
+    // prefer the saved recipe; otherwise seed from the resolved colors/fonts
+    const recipe = loadThemeRecipe(name);
+    const defaults = recipe || { accent: existing.color.accent, accent2: existing.color.accent2, fonts: existing.fonts };
+    defaults.name = name;
+    return createFlow({ name, defaults, flags });
+  }
+
+  if (sub === 'init') {
+    const { file, already } = writeStarterTheme();
+    console.log(already
+      ? `\n  already exists: ${file}\n  customize it with: atris theme edit brand\n`
+      : `\n  ✓ brand theme scaffolded: ${file}\n    or build one by feel:  atris theme create\n`);
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const name = rest[0];
+    const t = mergedThemes(HTML_THEMES)[name];
+    if (!t) { console.error(`  unknown theme "${name}"`); return 2; }
+    console.log(JSON.stringify(t, null, 2));
+    return 0;
+  }
+
+  // list (default)
+  const project = loadProjectThemes();
+  const all = mergedThemes(HTML_THEMES);
+  console.log('\n  atris themes:\n');
+  for (const name of Object.keys(all)) {
+    const tag = project[name] ? 'project' : 'built-in';
+    console.log(`  ${sw(all[name].color.accent)} ${name.padEnd(12)} accent ${all[name].color.accent}  bg ${all[name].color.bg}  (${tag})`);
+  }
+  console.log(`\n  make your own by feel:  atris theme create`);
+  console.log(`  themes live in ${PROJECT_THEME_FILE}. Used by deck, html, and site.\n`);
+  return 0;
+}
+
+module.exports = { run };

package/commands/verify.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const escapeRegExp = require('../lib/escape-regexp');
 
 /**
  * atris verify [task] - Validate work is actually done
@@ -354,7 +355,8 @@ function checkDocsVsChanges(cwd, atrisDir) {
  */
 function findTaskInContent(content, taskId) {
   // Try exact ID match (T1, T2, etc.)
-  const idPattern = new RegExp(`### (T${taskId}|Task ${taskId})[:\\s]([\\s\\S]*?)(?=\\n###|\\n##|$)`, 'i');
+  const safeId = escapeRegExp(taskId);
+  const idPattern = new RegExp(`### (T${safeId}|Task ${safeId})[:\\s]([\\s\\S]*?)(?=\\n###|\\n##|$)`, 'i');
   let match = content.match(idPattern);
 
   if (match) {
@@ -506,7 +508,7 @@ function verifyRubric(slug, section, opts = {}) {
   const content = fs.readFileSync(validateFile, 'utf8');
   // Match "## <section>" (case-insensitive, anchored), skipping optional
   // prose until the first ```bash or ```sh fence. Extract until the closing ```.
-  const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const escaped = escapeRegExp(section);
   const pattern = new RegExp(
     `^##\\s+${escaped}\\s*$[\\s\\S]*?\\n\`\`\`(?:bash|sh)?\\s*\\n([\\s\\S]*?)\\n\`\`\``,
     'mi'
@@ -531,5 +533,7 @@ function verifyRubric(slug, section, opts = {}) {
 
 module.exports = {
   verifyAtris,
-  verifyRubric
+  verifyRubric,
+  findTaskInContent,
+  escapeRegExp
 };

package/lib/activity-stream.js

@@ -0,0 +1,166 @@
+'use strict';
+
+// Activity stream: normalize the workspace's receipt channels into ONE
+// time-ordered feed of what the agent actually did, plus a heartbeat summary.
+// The task board shows a static inventory of tasks; this turns the same data
+// into "what happened, in order" — the stream you watch for hours.
+
+const TS_KEYS = ['ts', 'at', 'created_at', 'accepted_at', 'timestamp', 'updated_at'];
+
+function pickTs(row) {
+  for (const k of TS_KEYS) {
+    if (row && row[k]) {
+      const ms = Date.parse(row[k]);
+      if (Number.isFinite(ms)) return { iso: String(row[k]), ms };
+    }
+  }
+  return { iso: null, ms: 0 };
+}
+
+function clip(value, n = 100) {
+  const t = String(value == null ? '' : value).replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+}
+
+function num(v) {
+  return v == null || v === '' || Number.isNaN(Number(v)) ? null : Number(v);
+}
+
+// --- per-channel normalizers (each returns a uniform event or null) ---
+
+function normalizePulse(row) {
+  if (!row || row.phase !== 'finished') return null; // only completed ticks are events
+  const { iso, ms } = pickTs(row);
+  const reward = num(row.reward);
+  return {
+    ts: iso, ms,
+    source: 'pulse',
+    kind: row.actor === 'autopilot' ? 'autopilot' : 'heartbeat',
+    title: clip(row.what || `pulse tick #${row.tick_index}`),
+    detail: row.verify_passed == null ? '' : (row.verify_passed ? 'verify pass' : 'verify FAIL'),
+    status: row.verify_passed === false ? 'bad' : (reward > 0 ? 'good' : 'neutral'),
+    reward,
+  };
+}
+
+function normalizeScorecard(row) {
+  if (!row) return null;
+  const { iso, ms } = pickTs(row);
+  const reward = num(row.reward);
+  return {
+    ts: iso, ms,
+    source: 'reward',
+    kind: row.source || row.member || 'tick',
+    title: clip(row.what_shipped || 'tick scored'),
+    detail: reward == null ? '' : `reward ${reward}`,
+    status: reward != null && reward > 0 ? 'good' : (reward != null && reward < 0 ? 'bad' : 'neutral'),
+    reward,
+  };
+}
+
+function normalizeTaskEpisode(row) {
+  if (!row) return null;
+  const { iso, ms } = pickTs(row);
+  const state = row.state || {};
+  const action = row.action || state.status || 'updated';
+  const reward = num(row.reward);
+  return {
+    ts: iso, ms,
+    source: 'task',
+    kind: state.status || action,
+    title: clip(state.title || row.task_id),
+    detail: row.lesson ? clip(`lesson: ${row.lesson}`, 70) : clip(action, 24),
+    status: reward != null && reward < 0 ? 'bad' : (state.status === 'review' ? 'review' : 'neutral'),
+    reward,
+  };
+}
+
+function normalizeXp(row) {
+  if (!row) return null;
+  const { iso, ms } = pickTs(row);
+  return {
+    ts: iso, ms,
+    source: 'xp',
+    kind: row.outcome || 'accepted',
+    title: clip(row.title || 'work accepted'),
+    detail: `+${row.xp || 0} XP${row.actor ? ` · ${row.actor}` : ''}`,
+    status: 'good',
+    reward: num(row.reward),
+  };
+}
+
+function normalizeMissionEvent(row) {
+  if (!row) return null;
+  const { iso, ms } = pickTs(row);
+  const type = row.type || 'event';
+  const p = row.payload || {};
+  return {
+    ts: iso, ms,
+    source: 'mission',
+    kind: type,
+    title: clip(p.summary || p.objective || p.reason || p.next_action || type),
+    detail: clip(row.actor || '', 24),
+    status: /error|fail|halt|stop|paused/i.test(type) ? 'bad' : 'neutral',
+    reward: null,
+  };
+}
+
+// --- the feed ---
+
+function buildActivityStream(sources = {}, opts = {}) {
+  const limit = opts.limit || 60;
+  const events = [];
+  const push = (rows, fn) => {
+    for (const r of rows || []) {
+      const e = fn(r);
+      if (e && e.ms) events.push(e);
+    }
+  };
+  push(sources.pulseReceipts, normalizePulse);
+  push(sources.scorecards, normalizeScorecard);
+  push(sources.taskEpisodes, normalizeTaskEpisode);
+  push(sources.xpReceipts, normalizeXp);
+  push(sources.missionEvents, normalizeMissionEvent);
+  events.sort((a, b) => (b.ms - a.ms) || a.source.localeCompare(b.source)); // newest first, stable
+  return events.slice(0, limit);
+}
+
+// --- heartbeat: is the agent alive, and what did it just do ---
+
+function buildHeartbeat(pulseReceipts, now = Date.now()) {
+  const { summarizePulse } = require('./pulse');
+  const s = summarizePulse(pulseReceipts || [], now);
+  const lastMs = s.last_tick_ts ? Date.parse(s.last_tick_ts) : null;
+  const ageMin = Number.isFinite(lastMs) ? Math.max(0, Math.round((now - lastMs) / 60000)) : null;
+  const finished = (pulseReceipts || []).filter((r) => r && r.phase === 'finished');
+  const last = finished.length ? finished[finished.length - 1] : null;
+  let state = 'idle';
+  if (s.stale.stale) state = 'stale';
+  else if (s.total_ticks > 0) state = 'alive';
+  return {
+    state, // 'alive' | 'stale' | 'idle'
+    alive: state === 'alive',
+    stale_reason: s.stale.stale ? s.stale.reason : null,
+    last_tick_ts: s.last_tick_ts,
+    last_tick_age_min: ageMin,
+    last_what: last ? last.what : null,
+    last_reward: last ? num(last.reward) : null,
+    total_ticks: s.total_ticks,
+    reward_sum: s.reward_sum,
+    verify_pass: s.verify_pass,
+    verify_fail: s.verify_fail,
+    orphan_ticks: s.orphan_ticks,
+  };
+}
+
+module.exports = {
+  pickTs,
+  clip,
+  normalizePulse,
+  normalizeScorecard,
+  normalizeTaskEpisode,
+  normalizeXp,
+  normalizeMissionEvent,
+  buildActivityStream,
+  buildHeartbeat,
+};

package/lib/auto-accept-certified.js

@@ -54,6 +54,28 @@ function safeNodePathArgs(args) {
   return args.every(token => safeRelativePathToken(token));
 }
 
+function safeNodeTestArgs(args) {
+  let expectPattern = false;
+  for (const token of args) {
+    if (expectPattern) {
+      if (!safeVerifyToken(token) || hasUnsafePathSegment(token)) return false;
+      expectPattern = false;
+      continue;
+    }
+    if (token === '--test-name-pattern') {
+      expectPattern = true;
+      continue;
+    }
+    if (String(token || '').startsWith('--test-name-pattern=')) {
+      const pattern = String(token).slice('--test-name-pattern='.length);
+      if (!pattern || !safeVerifyToken(pattern) || hasUnsafePathSegment(pattern)) return false;
+      continue;
+    }
+    if (!safeRelativePathToken(token)) return false;
+  }
+  return !expectPattern;
+}
+
 function safeGitDiffCheckArgs(args) {
   return args.length === 0 || (args.length <= 2 && args.every(safeGitRevToken));
 }
@@ -182,7 +204,7 @@ function parseVerifyCommand(verify) {
     || (first === 'run' && Boolean(second) && !second.startsWith('-') && argv.length === 3)
   ))
     || (bin === 'node' && (
-      (first === '--test' && safeNodePathArgs(argv.slice(2)))
+      (first === '--test' && safeNodeTestArgs(argv.slice(2)))
       || (first === '--check' && argv.length === 3 && safeRelativePathToken(second))
       || (/^scripts\/[a-zA-Z0-9_./-]+$/.test(first || '') && safeNodePathArgs(argv.slice(1)))
     ))

package/lib/context-gatherer.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PROFILE_REL_PATH = path.join('.atris', 'state', 'context_profile.json');
+
+function profilePath(root = process.cwd()) {
+  return path.join(root, PROFILE_REL_PATH);
+}
+
+function loadContextProfile(root = process.cwd()) {
+  const target = profilePath(root);
+  if (!fs.existsSync(target)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(target, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function hasContextProfile(root = process.cwd()) {
+  const profile = loadContextProfile(root);
+  return Boolean(profile && String(profile.first_answer || '').trim());
+}
+
+function compactText(value, max = 160) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (!text) return '';
+  return text.length > max ? `${text.slice(0, Math.max(0, max - 3)).trim()}...` : text;
+}
+
+function inferDomain(answer) {
+  const text = String(answer || '').toLowerCase();
+  if (/college|application|essay|common app|school/.test(text)) return 'school';
+  if (/code|coding|program|website|app|project/.test(text)) return 'building';
+  if (/week|schedule|calendar|plan|homework/.test(text)) return 'planning';
+  return 'general';
+}
+
+function normalizeQuestionText(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^\w\s']/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isAtrisMetaQuestion(value) {
+  const text = normalizeQuestionText(value);
+  if (!text) return false;
+
+  const taskVerb = /\b(add|audit|build|change|create|debug|deploy|edit|fix|implement|make|patch|refactor|remove|review|run|ship|test|update|write)\b/;
+  if (taskVerb.test(text)) return false;
+
+  return [
+    /^(what'?s|what is|what are|who is|who are)\s+(atris|you|this)\b/,
+    /^what\s+atris\s+is\b/,
+    /^(what|how)\s+(does|do|can)\s+(atris|you|this)\b/,
+    /^(explain|describe|define)\s+(atris|this)\b/,
+    /^tell me\s+(about|what)\s+(atris|this)\b/,
+    /^why\s+atris\b/,
+  ].some((pattern) => pattern.test(text));
+}
+
+function starterTaskTitle(answer) {
+  const summary = compactText(answer, 80) || 'first useful path';
+  return `First useful step: ${summary}`;
+}
+
+function saveContextProfile(root, answer, { source = 'first_contact' } = {}) {
+  const text = compactText(answer, 500);
+  if (!text) return null;
+  const target = profilePath(root);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const existing = loadContextProfile(root) || {};
+  const profile = {
+    schema: 'atris.context_profile.v1',
+    created_at: existing.created_at || new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    source,
+    first_answer: text,
+    inferred_domain: inferDomain(text),
+  };
+  fs.writeFileSync(target, `${JSON.stringify(profile, null, 2)}\n`, 'utf8');
+  return profile;
+}
+
+function createStarterTask(root, answer) {
+  const atrisDir = path.join(root, 'atris');
+  if (!fs.existsSync(atrisDir)) return null;
+  try {
+    const taskDb = require('./task-db');
+    const db = taskDb.open();
+    const workspaceRoot = taskDb.workspaceRoot(root);
+    const title = starterTaskTitle(answer);
+    const sourceKey = taskDb.sourceKey('context-gatherer:first-task', title);
+    const added = taskDb.addTask(db, {
+      title,
+      tag: 'onboarding',
+      workspaceRoot,
+      sourceKey,
+      metadata: {
+        source: 'context_gatherer',
+        first_answer: compactText(answer, 500),
+      },
+    });
+    const rows = taskDb.listTasks(db, { workspaceRoot });
+    const displayRows = taskDb.withTaskDisplayRefs(rows);
+    const task = displayRows.find(row => row.id === added.id) || null;
+    try {
+      const todoPath = path.join(root, 'atris', 'TODO.md');
+      fs.writeFileSync(todoPath, taskDb.renderTodoMarkdown(rows, { title: 'TODO.md' }), 'utf8');
+    } catch {}
+    return {
+      id: added.id,
+      inserted: added.inserted,
+      display_id: task && task.display_id || null,
+      title,
+    };
+  } catch (error) {
+    return {
+      error: error && error.message ? error.message : String(error),
+      title: starterTaskTitle(answer),
+    };
+  }
+}
+
+function shouldGatherContext({
+  root = process.cwd(),
+  userInput = '',
+  mapStatus = 'ready',
+  liveMissionsCount = 0,
+  wipCount = 0,
+  backlogCount = 0,
+  inboxCount = 0,
+} = {}) {
+  if (hasContextProfile(root)) return false;
+  if (String(userInput || '').trim()) return true;
+  if (mapStatus !== 'ready') return true;
+  if (liveMissionsCount > 0 || wipCount > 0 || backlogCount > 0 || inboxCount > 0) return false;
+  return true;
+}
+
+function renderPrompt({ projectName = 'this workspace' } = {}) {
+  return [
+    '',
+    'Context gatherer',
+    '----------------',
+    `Hi. I am Atris, and I want to understand ${projectName} before I suggest a path.`,
+    '',
+    'What are you trying to make easier right now: school, college apps, coding, a personal project, or something else?',
+    'Answer in one sentence. I will turn it into the first useful step.',
+  ].join('\n');
+}
+
+module.exports = {
+  PROFILE_REL_PATH,
+  profilePath,
+  loadContextProfile,
+  hasContextProfile,
+  isAtrisMetaQuestion,
+  saveContextProfile,
+  createStarterTask,
+  shouldGatherContext,
+  renderPrompt,
+  starterTaskTitle,
+  inferDomain,
+};