atris 3.80.1 → 3.82.2

package/lib/recall-exam.js

@@ -0,0 +1,171 @@
+'use strict';
+
+// Recall exam: how fast can an agent find the right note by following links?
+//
+// The reader starts with the boot files, then keeps opening the linked
+// markdown file whose link text and line best match the question, the way an
+// agent scans an index and follows the line that says when to open it. It never
+// greps the whole tree. A question is found when an opened file contains the
+// question's needle, an exact answer phrase. Needles survive a file move, so the
+// same exam scores a layout before and after notes are split or merged.
+
+const fs = require('fs');
+const path = require('path');
+
+const STOP_WORDS = new Set(('the and for are was were where what which who how does did can could should would this that these those '
+  + 'with from into about find have has had there here when why our you your its it is be do to of in on at or an a i im me my we us '
+  + 'if not no any all one get got make need needs want am will just then than so but by as up out over use using used new before after '
+  + 'first next way thing things something someone mid work working about while also only very much more most some same each every').split(' '));
+const DEFAULT_MAX_OPENS = 6;
+// A real file reader stops after this many lines unless asked for more.
+const READ_LINE_CAP = 2000;
+
+function stem(word) {
+  return word.replace(/(?:ing|ed|es|s)$/u, '') || word;
+}
+
+function keywords(text) {
+  return [...new Set((String(text).toLowerCase().match(/[\p{L}\p{N}]+/gu) || [])
+    .filter(word => word.length >= 3 && !STOP_WORDS.has(word)).map(stem))];
+}
+
+function normalize(text) {
+  return String(text).toLowerCase().replace(/\s+/g, ' ');
+}
+
+function readCapped(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
+  const lines = text.split('\n');
+  return lines.length > READ_LINE_CAP ? lines.slice(0, READ_LINE_CAP).join('\n') : text;
+}
+
+// Every markdown file a line points at, with the words an agent sees beside it.
+function linksIn(text, fromFile, root) {
+  const links = [];
+  const fromDir = path.dirname(fromFile);
+  let heading = '';
+  for (const line of text.split('\n')) {
+    const head = line.match(/^#{1,6}\s+(.*)/);
+    if (head) heading = head[1];
+    const targets = [];
+    for (const match of line.matchAll(/\[([^\]]*)\]\(([^)\s]+)\)/g)) targets.push({ label: match[1], target: match[2] });
+    for (const match of line.matchAll(/\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g)) targets.push({ label: '', target: match[1] });
+    for (const match of line.matchAll(/`([^`\s]+\.md)(?:#[^`]*)?`/g)) targets.push({ label: '', target: match[1] });
+    for (const { label, target } of targets) {
+      const clean = target.replace(/#.*$/, '').replace(/:\d+(?:-\d+)?$/, '');
+      if (!/\.md$/i.test(clean) || clean.includes('://')) continue;
+      const candidates = [path.resolve(fromDir, clean), path.resolve(root, clean)];
+      const resolved = candidates.find(file => file.startsWith(root + path.sep) && fs.existsSync(file));
+      if (!resolved) continue;
+      links.push({ file: resolved, context: `${label} ${line} ${heading} ${path.basename(clean, '.md')}` });
+    }
+  }
+  return links;
+}
+
+function scoreContext(context, words) {
+  const have = new Set(keywords(context));
+  return words.filter(word => have.has(word)).length;
+}
+
+function examineQuestion(root, question, { bootFiles, maxOpens = DEFAULT_MAX_OPENS }) {
+  const words = keywords(question.q);
+  const needle = normalize(question.needle);
+  const opened = [];
+  let charsRead = 0;
+  let foundIn = null;
+  const seen = new Set();
+  const frontier = new Map();
+  // The file whose link led to each opened file, so the path to the answer is known.
+  const via = new Map();
+  const absorb = (file, text) => {
+    seen.add(file);
+    for (const link of linksIn(text, file, root)) {
+      if (seen.has(link.file)) continue;
+      const score = scoreContext(link.context, words);
+      const prior = frontier.get(link.file);
+      if (!prior || score > prior.score) frontier.set(link.file, { score, order: prior ? prior.order : frontier.size, from: file });
+    }
+    if (!foundIn && normalize(text).includes(needle)) foundIn = path.relative(root, file);
+  };
+  for (const rel of bootFiles) {
+    const file = path.resolve(root, rel);
+    const text = readCapped(file);
+    if (text === null) continue;
+    absorb(file, text);
+  }
+  while (!foundIn && opened.length < maxOpens) {
+    let best = null;
+    for (const [file, entry] of frontier) {
+      if (seen.has(file) || entry.score === 0) continue;
+      if (!best || entry.score > best.score || (entry.score === best.score && entry.order < best.order)) best = { file, ...entry };
+    }
+    if (!best) break;
+    frontier.delete(best.file);
+    via.set(best.file, best.from);
+    const text = readCapped(best.file) || '';
+    opened.push(path.relative(root, best.file));
+    charsRead += text.length;
+    absorb(best.file, text);
+  }
+  // An index opened on the way to the answer was needed; every other open was not.
+  const needed = new Set();
+  for (let at = foundIn && path.resolve(root, foundIn); at && via.has(at); at = via.get(at)) needed.add(path.relative(root, at));
+  return {
+    id: question.id, area: question.area || null, found: Boolean(foundIn), found_in: foundIn,
+    files_opened: opened.length, opened, tokens_opened: Math.round(charsRead / 4),
+    wrong_opens: opened.filter(rel => !needed.has(rel)).length,
+  };
+}
+
+function readQuestions(file) {
+  const questions = [];
+  const invalid = [];
+  const text = fs.readFileSync(file, 'utf8');
+  text.split(/\r?\n/).forEach((line, index) => {
+    if (!line.trim()) return;
+    let row;
+    try { row = JSON.parse(line); } catch { row = null; }
+    if (!row || typeof row.q !== 'string' || typeof row.needle !== 'string' || !row.needle.trim()) invalid.push(index + 1);
+    else questions.push(row);
+  });
+  return { questions, invalid };
+}
+
+function median(values) {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+function runRecallExam(root, questionsFile, { bootFiles, maxOpens = DEFAULT_MAX_OPENS } = {}) {
+  const { questions, invalid } = readQuestions(questionsFile);
+  const bootChars = bootFiles.reduce((sum, rel) => sum + (readCapped(path.resolve(root, rel)) || '').length, 0);
+  const results = questions.map(question => examineQuestion(root, question, { bootFiles, maxOpens }));
+  const found = results.filter(result => result.found);
+  const opens = results.map(result => result.files_opened);
+  const tokens = results.map(result => result.tokens_opened);
+  const wrong = results.map(result => result.wrong_opens);
+  const byArea = {};
+  for (const result of results) {
+    const area = result.area || 'none';
+    byArea[area] = byArea[area] || { total: 0, found: 0 };
+    byArea[area].total++;
+    if (result.found) byArea[area].found++;
+  }
+  return {
+    questions: results.length, invalid_lines: invalid, max_opens: maxOpens,
+    boot_tokens: Math.round(bootChars / 4),
+    found: found.length, found_share: results.length ? found.length / results.length : null,
+    files_opened: { total: opens.reduce((a, b) => a + b, 0), median: median(opens), mean: results.length ? opens.reduce((a, b) => a + b, 0) / results.length : null },
+    wrong_opens: { total: wrong.reduce((a, b) => a + b, 0), median: median(wrong), mean: results.length ? wrong.reduce((a, b) => a + b, 0) / results.length : null },
+    tokens_opened: { total: tokens.reduce((a, b) => a + b, 0), median: median(tokens), mean: results.length ? Math.round(tokens.reduce((a, b) => a + b, 0) / results.length) : null },
+    tokens_opened_when_found: { median: median(found.map(result => result.tokens_opened)) },
+    by_area: byArea,
+    results,
+  };
+}
+
+module.exports = { runRecallExam, keywords };

package/lib/roster-markdown.js

@@ -8,10 +8,10 @@
 //
 // Two shapes read side by side. The sectioned shape, which assign writes:
 //   ## build
-//   - claude code, model: opus 5.5
+//   - claude code, model: opus
 //   - codex, effort: medium
 // and the older one-line shape, still read as before:
-//   build: claude opus 5.5, backup codex
+//   build: claude opus, backup codex
 
 const OLD_ROSTER_NOTE = '> edit any time. each line is job: engine and model, an optional effort (low, medium, high, xhigh, max), then optional "backup <engine and model>", "max 20 min", and "until 2026-10-24" (the year is required).';
 const ROSTER_NOTE = '> edit any time. each "## job" lists its workers in order, one per line: "- tool, model: name", then optional "effort: medium", "max: 20 min", "prep: search" (that job reads the task first and hands this worker a short brief), and "until 2026-10-24" (the year is required). the first ready worker leads and the rest back it up.';

package/lib/runner-command.js

@@ -95,7 +95,7 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
   }),
   haiku: Object.freeze({
     bin: 'claude',
-    model: 'claude-haiku-5-5',
+    model: DEFAULT_CLAUDE_RUNNER_MODEL,
     commandTemplate: '',
     effortFlag: '--effort',
     efforts: CLAUDE_EFFORTS,
@@ -109,8 +109,8 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
     model: '',
     commandTemplate: '{bin} -p {pinnedModelFlag} -- {prompt}',
   }),
-  // No hard pin: a pinned grok-4.6 went stale when the grok CLI moved its
-  // own default to grok-4.7-build-fast, so an unpinned run rides the CLI.
+  // No hard pin: a pinned grok version went stale when the grok CLI moved its
+  // own default to a newer build, so an unpinned run rides the CLI.
   // Grok runs only xAI models, so a claude model name never reaches it.
   grok: Object.freeze({
     bin: 'grok',
@@ -123,7 +123,7 @@ const RUNNER_PROFILE_DEFS = Object.freeze({
   agy: Object.freeze({
     bin: 'agy',
     // No hard pin: the agy CLI keeps its own session model, so an unpinned
-    // run rides that and a roster line names gemini 3.8 flash (the 2026-09-04
+    // run rides that and a roster line names its own gemini model (the 2026-09-04
     // bake-off pick) when it wants it. --add-dir or agy edits its own scratch
     // folder; the headless note or gemini stops to ask "may I edit?" and
     // exits 0 having changed nothing.
@@ -319,7 +319,7 @@ function runnerModelFor(engineId, model) {
   // Required here, not at the top: engine-registry requires this file.
   const { isClaudeFamilyModel } = require('./engine-registry');
   const name = String(engineId || '').trim().toLowerCase();
-  // A display name like "opus 5.5" only becomes an id for the claude cli (or
+  // A spaced display name only becomes an id for the claude cli (or
   // an unnamed engine). Any other engine's model name is handed over as is.
   const canonical = RUNNER_PROFILE_ALIASES[name] || name;
   const claudeCli = !canonical || canonical === 'claude' || canonical === 'fable' || canonical === 'haiku';

package/lib/task-db.js

@@ -545,7 +545,7 @@ function rowInWorkspace(row, ws) {
   return Boolean(rowRoot) && workspaceViewRoots(ws).includes(rowRoot);
 }
 
-function listTasks(db, { workspaceRoot: ws, status, claimedBy, limit }) {
+function listTasks(db, { workspaceRoot: ws, status, claimedBy, limit, orderBy }) {
   const where = [];
   const args = [];
   if (ws) {
@@ -560,6 +560,7 @@ function listTasks(db, { workspaceRoot: ws, status, claimedBy, limit }) {
     FROM tasks
     ${where.length ? 'WHERE ' + where.join(' AND ') : ''}
     ORDER BY
+      ${orderBy === 'updated_at' ? 'updated_at DESC,' : ''}
       CASE status WHEN 'open' THEN 0 WHEN 'claimed' THEN 1 WHEN 'review' THEN 2 WHEN 'failed' THEN 3 WHEN 'done' THEN 4 WHEN 'archived' THEN 5 ELSE 6 END,
       CASE WHEN tag='endgame' THEN 0 ELSE 1 END,
       created_at DESC
@@ -826,6 +827,13 @@ function pidAlive(pid) {
   try { process.kill(pid, 0); return true; } catch (err) { return err.code === 'EPERM'; }
 }
 
+// A claim made by hand (`atris task claim` with no --lease-minutes) has no lease, so before this nothing ever let
+// it go: a session that died holding one kept the job off the board for good. Such a claim is let go once its job
+// has seen no activity (no event of any kind) for this many days, whatever --stale-days says. It is measured by
+// activity, not by a clock set at claim time, so a claim someone is still working on is never taken away, and it
+// is long enough that the narrower --stale-days rule (fleet claims, or one named claimer) still decides first.
+const UNLEASED_CLAIM_STALE_DAYS = 30;
+
 function expireLeases(db, { now = Date.now(), staleDays, claimer, dryRun = false, isAlive = pidAlive } = {}) {
   const timestamp = now instanceof Date ? now.getTime() : typeof now === 'string' ? Date.parse(now) : Number(now);
   if (!Number.isFinite(timestamp)) throw new Error('invalid now');
@@ -846,6 +854,9 @@ function expireLeases(db, { now = Date.now(), staleDays, claimer, dryRun = false
     } else if (!lease && staleDays != null && row.last_seen_at != null && row.last_seen_at < timestamp - Number(staleDays) * 86400000 && (claimer ? row.claimed_by === claimer : String(row.claimed_by || '').startsWith('fleet-'))) {
       reason = `stranded with no activity for over ${staleDays} days`;
       leaseUntil = new Date(row.last_seen_at + 3600000).toISOString();
+    } else if (!lease && row.last_seen_at != null && row.last_seen_at < timestamp - UNLEASED_CLAIM_STALE_DAYS * 86400000) {
+      reason = `stranded with no activity for over ${UNLEASED_CLAIM_STALE_DAYS} days`;
+      leaseUntil = new Date(row.last_seen_at + 3600000).toISOString();
     } else continue;
     const lastSeen = lease && Number.isFinite(until) && Number.isFinite(Number(lease.minutes))
       ? until - Number(lease.minutes) * 60000 : row.last_seen_at;
@@ -1130,7 +1141,7 @@ function reopenTask(db, { id, actor, reason, metadata: metadataPatch, fromReview
   return { reopened: true, event, row: updated };
 }
 
-function doneTask(db, { id, status, actor, allowReview = false, action, proof, autoAccepted = false } = {}) {
+function doneTask(db, { id, status, actor, allowReview = false, action, proof, autoAccepted = false, deferLogs = false } = {}) {
   if (!id) throw new Error('id required');
   const final = status || 'done';
   if (!['done', 'failed'].includes(final)) throw new Error('status must be done|failed');
@@ -1139,18 +1150,22 @@ function doneTask(db, { id, status, actor, allowReview = false, action, proof, a
   // read as a real failure. See archiveTask() below.
   const now = Date.now();
   const allowedStatuses = allowReview ? "'open', 'claimed', 'review'" : "'open', 'claimed'";
-  const result = withBusyRetry(() => db.prepare(`
-    UPDATE tasks
-       SET status = ?, done_at = ?, updated_at = ?
-     WHERE id = ?
-       AND status IN (${allowedStatuses})
-  `).run(final, now, now, id));
-  if (result.changes === 1) {
-    const row = getTask(db, id);
+  const eventActor = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
+  // The status change and its event are one write: a crash between them used to leave a done job with no
+  // completed event. The daily log is a file, written only after the write is saved.
+  const row = inWriteTransaction(db, () => {
+    const result = withBusyRetry(() => db.prepare(`
+      UPDATE tasks
+         SET status = ?, done_at = ?, updated_at = ?
+       WHERE id = ?
+         AND status IN (${allowedStatuses})
+    `).run(final, now, now, id));
+    if (result.changes !== 1) return null;
+    const updated = getTask(db, id);
     appendTaskEvent(db, {
       taskId: id,
-      workspaceRoot: row.workspace_root,
-      actor: actor || process.env.ATRIS_AGENT_ID || process.env.USER || null,
+      workspaceRoot: updated.workspace_root,
+      actor: eventActor,
       eventType: final === 'done' ? 'completed' : 'blocked',
       payload: {
         status: final,
@@ -1158,17 +1173,40 @@ function doneTask(db, { id, status, actor, allowReview = false, action, proof, a
         ...(autoAccepted ? { auto_accepted: true } : {}),
       },
     });
-    const logs = appendTaskCompletionLogs(db, row, {
-      status: final,
-      actor: actor || process.env.ATRIS_AGENT_ID || process.env.USER || null,
-      action: action || final,
-      proof,
-    });
+    return updated;
+  });
+  if (row) {
+    const logInput = { status: final, actor: eventActor, action: action || final, proof };
+    // A caller that holds its own transaction (acceptTask) writes the log once that is saved.
+    if (deferLogs) return { updated: true, row, logInput };
+    const logs = appendTaskCompletionLogs(db, row, logInput);
     return { updated: true, logs };
   }
   return { updated: false };
 }
 
+// Accepting a job is two writes, the job marked done and the review that records it as accepted with its
+// reward. They are one transaction: a crash between them used to leave a done job with approval still
+// pending, and nothing scans done jobs to finish the accept (autoland reads only review). The daily log
+// is a file and is written once the transaction is saved.
+function acceptTask(db, { id, actor, proof, reward, lesson = '', nextTask = '', autoAccepted = false, careerXpEligible = true, clearedFields = [] } = {}) {
+  if (!id) throw new Error('id required');
+  const out = inWriteTransaction(db, () => {
+    const done = doneTask(db, { id, status: 'done', actor, allowReview: true, action: 'accepted', proof, autoAccepted, deferLogs: true });
+    if (!done.updated) return { updated: false };
+    const reviewed = reviewTask(db, { id, actor, reward, lesson, nextTask, proof, careerXpEligible, clearedFields, autoAccepted });
+    return { updated: true, reviewed, row: done.row, logInput: done.logInput };
+  });
+  if (!out.updated) return { updated: false };
+  let logs = {};
+  try {
+    logs = appendTaskCompletionLogs(db, out.row, out.logInput);
+  } catch (err) {
+    if (process.env.ATRIS_DEBUG) process.stderr.write(`accept log failed: ${String(err?.message ?? err).replace(/[\r\n]+/g, ' ')}\n`);
+  }
+  return { updated: true, reviewed: out.reviewed, logs };
+}
+
 function reapMissionBlockerTasks(db, { workspaceRoot: ws, missions = [], actor, rows = null, skipLogs = false } = {}) {
   const missionById = new Map((Array.isArray(missions) ? missions : [])
     .filter(mission => mission && mission.id)
@@ -1825,32 +1863,55 @@ function releaseClosedPullRequest(db, { id, actor, workspaceRoot: ws, expected,
   return { released: true, row: out.row, event: out.event };
 }
 
+// Read a job's metadata, change it, and write it back with the write lock held, so two writers that each
+// read the whole JSON cannot drop each other's keys. The mutator gets a copy and changes it in place or
+// returns a new object; returning false writes nothing. Keep the mutator fast and free of I/O: it runs
+// inside BEGIN IMMEDIATE. touch: false leaves updated_at as it was.
+// Returns null when the job does not exist, else { row, metadata, changed }.
+function updateTaskMetadata(db, id, mutator, { touch = true, now = Date.now() } = {}) {
+  if (!id) throw new Error('id required');
+  if (typeof mutator !== 'function') throw new Error('mutator required');
+  return inWriteTransaction(db, () => {
+    const row = getTask(db, id);
+    if (!row) return null;
+    const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
+    const out = mutator(metadata, row);
+    if (out === false) return { row, metadata, changed: false };
+    const next = out && typeof out === 'object' ? out : metadata;
+    const text = JSON.stringify(next);
+    withBusyRetry(() => (touch
+      ? db.prepare('UPDATE tasks SET metadata = ?, updated_at = ? WHERE id = ?').run(text, now, id)
+      : db.prepare('UPDATE tasks SET metadata = ? WHERE id = ?').run(text, id)));
+    return { row, metadata: next, changed: true };
+  });
+}
+
 function setTaskResult(db, { id, actor, result }) {
   if (!id) throw new Error('id required');
   const text = cleanLandingText(result);
   if (!text) throw new Error('result required');
-  const row = getTask(db, id);
-  if (!row) return { saved: false, reason: 'not_found' };
   const now = Date.now();
-  const metadata = row.metadata && typeof row.metadata === 'object' ? { ...row.metadata } : {};
-  metadata.result = text;
-  metadata.result_at = new Date(now).toISOString();
-  metadata.result_by = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
-  const updated = withBusyRetry(() => db.prepare(`
-    UPDATE tasks
-       SET metadata = ?,
-           updated_at = ?
-     WHERE id = ?
-  `).run(JSON.stringify(metadata), now, id));
-  if (updated.changes !== 1) return { saved: false, reason: 'stale_task_state' };
-  const latest = getTask(db, id);
-  const event = appendTaskEvent(db, {
-    taskId: id,
-    workspaceRoot: latest.workspace_root,
-    actor: metadata.result_by,
-    eventType: 'result_set',
-    payload: { result: text },
+  const resultBy = actor || process.env.ATRIS_AGENT_ID || process.env.USER || null;
+  // The metadata write and its event are one transaction, and the metadata is read under the lock.
+  const out = inWriteTransaction(db, () => {
+    const saved = updateTaskMetadata(db, id, (metadata) => {
+      metadata.result = text;
+      metadata.result_at = new Date(now).toISOString();
+      metadata.result_by = resultBy;
+    }, { now });
+    if (!saved) return null;
+    const row = getTask(db, id);
+    const written = appendTaskEvent(db, {
+      taskId: id,
+      workspaceRoot: row.workspace_root,
+      actor: resultBy,
+      eventType: 'result_set',
+      payload: { result: text },
+    });
+    return { latest: row, event: written };
   });
+  if (!out) return { saved: false, reason: 'not_found' };
+  const { latest, event } = out;
   return { saved: true, event, row: latest };
 }
 
@@ -3053,6 +3114,11 @@ function taskProjection(db, {
   };
 }
 
+// Status names: the database keeps `failed` (doneTask writes it, its event is `blocked`), and
+// TODO.md shows those rows under "## Blocked". The words differ on purpose and the stored value
+// is not renamed: every reader, filter, and old database already says `failed`, and a person
+// reads "blocked" as "needs someone", which is what a failed job is. `atris task list --status
+// failed` is how to list them.
 function renderTodoMarkdown(rows, { title = 'TODO.md', doneLimit = TODO_RENDER_DONE_LIMIT, failedLimit = TODO_RENDER_FAILED_LIMIT, refRows = rows, preservedSections = [] } = {}) {
   const displayRows = withTaskDisplayRefs(rows, refRows);
   const buckets = {
@@ -3192,6 +3258,7 @@ module.exports = {
   renewLease,
   clearLease,
   expireLeases,
+  UNLEASED_CLAIM_STALE_DAYS,
   previewExpiredLeases,
   sweepExpiredLeases,
   releaseTask,
@@ -3201,6 +3268,7 @@ module.exports = {
   backlogTask,
   clearPlanTasks,
   doneTask,
+  acceptTask,
   reapMissionBlockerTasks,
   archiveTask,
   archiveNotNeeded,
@@ -3212,6 +3280,7 @@ module.exports = {
   landHeldMerge,
   releaseClosedPullRequest,
   setTaskResult,
+  updateTaskMetadata,
   reviseTask,
   stageTask,
   noteTask,

package/lib/taste-notes.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// Taste is personal, so it lives outside the shipped skill: the project's
+// atris/taste/TASTE.md and the person's ~/.atris/taste/TASTE.md. Sync replaces
+// atris/skills/ on every update and never touches either file. Init and update
+// only create the project starter when it is missing.
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_TASTE_FILE = path.join('taste', 'TASTE.md');
+
+const STARTER = `# Taste
+
+How this project should look and read: its brand and its voice. Agents read this before making anything a person will see. The person's own taste in \`~/.atris/taste/TASTE.md\` comes second.
+
+Each line gives the rule in plain words and links to a short note with the reason and real examples. \`atris/skills/taste/notes.md\` shows the shape.
+
+## The list
+
+- (Nothing recorded yet. When someone corrects how something looks or reads, add the rule here.)
+`;
+
+// Returns true when the starter was written (or would be, in a dry run).
+function ensureProjectTasteFile(atrisDir, { dryRun = false } = {}) {
+  const file = path.join(atrisDir, PROJECT_TASTE_FILE);
+  if (fs.existsSync(file)) return false;
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, STARTER, { flag: 'wx' });
+  }
+  return true;
+}
+
+module.exports = { ensureProjectTasteFile };

package/lib/team-lineup.js

@@ -19,15 +19,15 @@ function orderJobs(rows) {
   return [...builtIn, ...list.filter((row) => !builtIn.includes(row))];
 }
 
-// "opus 5.5" for a claude model, "codex gpt-6-astra" for anything else, and
+// Friendly label for a claude model, "<tool> <model>" for anything else, and
 // just the tool when it runs its own default.
 function shortRuns(view) {
   if (!view || !view.engine) return '';
   const tool = rosterToolLabel(view.engine);
   if (!view.model) return tool;
   const label = modelLabel(view.model);
-  // "atris:fast" on atris fast says the tool twice; "grok 4.7 fast" on grok
-  // already names it.
+  // "atris:fast" on atris fast says the tool twice; a label starting with the
+  // tool name already names it.
   const plain = (text) => String(text).toLowerCase().replace(/[^a-z0-9.]+/g, ' ').trim();
   if (plain(label) === plain(tool)) return tool;
   if (CLAUDE_FAMILY.includes(view.engine) || plain(label).startsWith(`${plain(tool)} `)) return label;

package/lib/todo.js

@@ -61,6 +61,8 @@ function dbBuckets(workspaceRoot) {
     if (r.status === 'open') backlog.push(shaped);
     else if (r.status === 'claimed') inProgress.push(shaped);
     else if (r.status === 'review') review.push(shaped);
+    // `failed` is the stored name for a job TODO.md shows under "Blocked" (see renderTodoMarkdown
+    // in lib/task-db.js); this shim has no blocked bucket, so it files them with the finished rows.
     else if (r.status === 'done' || r.status === 'failed') completed.push(shaped);
   }
   return { backlog, inProgress, review, completed, sourceKeys, sourceRefs };

package/lib/wiki.js

@@ -71,12 +71,17 @@ Turn raw project context into a living memory the next agent can pick up cold.
 - Add cross-references with \`[[${wikiLinkRoot}/...]]\` links.
 - Keep \`index.md\`, \`log.md\`, and \`STATUS.md\` in sync with page changes.
 - If something is unclear or contradictory, say so directly.
+- One idea per page, under about 80 lines, with real examples right under the rule they prove.
+- Each \`index.md\` line gives the rule or answer and says when to open the page. Never a bare topic name.
+- Keep \`index.md\` to one screen. Move text instead of rewriting it, and list anything deleted in \`log.md\`.
 `;
 }
 
 function indexMarkdown() {
   return `# Atris Wiki Index
 
+Each line gives the rule or answer and says when to open the page behind it.
+
 ## People
 
 ## Systems
@@ -874,7 +879,9 @@ Rules:
 - Merge new info into existing pages instead of replacing them
 - Keep index.md, log.md, and STATUS.md current
 - Flag contradictions directly instead of smoothing them over
-- Never modify the raw source documents you ingested`;
+- Never modify the raw source documents you ingested
+- One idea per page, under about 80 lines, with examples under the rule they prove
+- An index line gives the rule or answer, then says when to open the page`;
 }
 
 function buildIngestPrompt(sourceValue, mode = 'public') {
@@ -889,7 +896,7 @@ Workflow:
 3. Extract people, systems, and concepts worth preserving
 4. Create or update pages under ${wikiRoot}/, merging with existing facts instead of replacing them
 5. Add cross-references using [[${wikiLinkRoot}/...]] links
-6. Update ${wikiRoot}/index.md with one-line descriptions of touched pages
+6. Update ${wikiRoot}/index.md with one line per touched page: the rule or answer, then when to open it
 7. Append an INGEST entry to ${wikiRoot}/log.md under today's date
 8. Refresh ${wikiRoot}/STATUS.md in plain English for a non-technical reader
 
@@ -945,7 +952,8 @@ Keep rules:
 - Entries marked as user-stated conventions or explicit remember-this survive.
 - Every kept entry keeps its provenance as a source link or date.
 
-Consolidate overlapping entries, preserve the strongest source-backed version, and leave index.md and page links consistent.`;
+Consolidate overlapping entries, preserve the strongest source-backed version, and leave index.md and page links consistent.
+Split any page over about 80 lines or holding two ideas. Rewrite bare topic lines in index.md so each says when to open the page.`;
 }
 
 module.exports = {