atris 3.45.1 → 3.46.1

package/lib/task-explanation.js

@@ -0,0 +1,229 @@
+'use strict';
+
+// One plain-language explanation for every task, on every surface.
+//
+// Three questions a person can answer without reading metadata: what changes,
+// why it matters, what done looks like. Callers may write these fields
+// explicitly; everything else is derived from what the task already carries
+// (title, goal, verifier, parent). Nothing here invents a claim: when a task
+// never recorded a reason, the surface says so instead of guessing one.
+//
+// This is the first layer only. Title, metadata, requirements, events, proof,
+// verify commands, status, and approval gating are untouched and stay
+// inspectable underneath.
+
+const EXPLANATION_FIELDS = ['what_changes', 'why_it_matters', 'done_looks_like'];
+
+const EXPLANATION_LABELS = {
+  what_changes: 'What changes',
+  why_it_matters: 'Why it matters',
+  done_looks_like: 'Done looks like',
+};
+
+const NO_REASON_RECORDED = 'No reason recorded yet.';
+const NO_TITLE_RECORDED = 'Not written down yet.';
+
+const PLAIN_REPLACEMENTS = [
+  [/\bidempotent\b/gi, 'safe to repeat'],
+  [/\bdeterministic\b/gi, 'predictable'],
+  [/\bsubstrate\b/gi, 'base'],
+  [/\borchestration\b/gi, 'coordination'],
+  [/\binvariant\b/gi, 'rule'],
+  [/\bcanonical\b/gi, 'main'],
+  [/\bmateriali[sz]e\b/gi, 'create'],
+  [/\bheuristic\b/gi, 'rule of thumb'],
+  [/\bprojection\b/gi, 'shared view'],
+  [/\bschema\b/gi, 'data format'],
+  [/\b(?:CLI|API)\b/g, match => match === 'CLI' ? 'command tool' : 'connection'],
+];
+
+function cleanText(value) {
+  return String(value == null ? '' : value).replace(/\s+/g, ' ').trim();
+}
+
+function endSentence(value) {
+  const text = cleanText(value);
+  if (!text) return '';
+  return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+
+// The original value always remains in title/metadata/events. This copy is
+// only the simple face, so identifiers and common internal terms are expanded
+// here without weakening or rewriting the durable task record.
+function plainText(value) {
+  let text = cleanText(value)
+    .replace(/\s*[—–]\s*/g, ', ')
+    .replace(/--([a-z][a-z-]*)/g, (_match, flag) => flag.replace(/-/g, ' '))
+    .replace(/\b[a-z0-9]+(?:_[a-z0-9]+)+\b/gi, match => match.replace(/_/g, ' '))
+    .replace(/\b[a-z]+(?:[A-Z][A-Za-z0-9]*)+\b/g, match => match.replace(/([a-z0-9])([A-Z])/g, '$1 $2'))
+    .replace(/\b[A-Z]{2,5}-\d+\b/g, '')
+    .replace(/\b[0-9A-HJKMNP-TV-Z]{20,}\b/g, '')
+    .replace(/(?:^|\s)(?:[\w.-]+\/)+[\w.-]+(?=\s|$|[.,;:!?])/g, ' the named file');
+  for (const [pattern, replacement] of PLAIN_REPLACEMENTS) text = text.replace(pattern, replacement);
+  return cleanText(text).replace(/\s+([,.;:!?])/g, '$1');
+}
+
+// Explicit fields arrive either nested (metadata.explanation, written at
+// creation) or flat (metadata.what_changes, written by a caller flag). A
+// stored field only counts as explicit when its recorded source says so, so a
+// derived default persisted at creation never masquerades as an author's words
+// and never goes stale after a retitle.
+function explicitExplanationFields(metadata) {
+  const out = {};
+  if (!metadata || typeof metadata !== 'object') return out;
+  const nested = metadata.explanation && typeof metadata.explanation === 'object' ? metadata.explanation : {};
+  const nestedSources = nested.sources && typeof nested.sources === 'object' ? nested.sources : null;
+  for (const field of EXPLANATION_FIELDS) {
+    const authored = !nestedSources || nestedSources[field] === 'explicit';
+    const value = (authored ? cleanText(nested[field]) : '') || cleanText(metadata[field]);
+    if (value) out[field] = value;
+  }
+  return out;
+}
+
+function explanationGoalText(task) {
+  const metadata = task && task.metadata || {};
+  return cleanText(metadata.task_goal || metadata.goal_objective || (task && task.objective) || metadata.objective);
+}
+
+function derivedWhatChanges(task) {
+  const title = plainText(task && task.title);
+  return title ? endSentence(title) : NO_TITLE_RECORDED;
+}
+
+function derivedWhyItMatters(task) {
+  const goal = plainText(explanationGoalText(task));
+  if (goal) return endSentence(goal);
+  const parent = plainText(task && task.lineage && task.lineage.parent_title);
+  if (parent) return endSentence(`This helps finish the larger work: ${parent}`);
+  return 'The task does not say why this matters yet.';
+}
+
+function derivedDoneLooksLike(task) {
+  const metadata = task && task.metadata || {};
+  const review = task && task.review || {};
+  const result = plainText(
+    task && task.result
+    || metadata.result
+    || review.result && review.result.changed
+    || review.landing && review.landing.happened
+  );
+  if (result) return endSentence(result);
+  const exit = plainText(metadata.exit_condition);
+  if (exit) return endSentence(exit);
+  const verify = cleanText(metadata.verify);
+  if (verify) return 'The required check passes, the proof is attached, and review clears the work.';
+  return 'The owner shows proof the work is real and it clears review.';
+}
+
+// Task in, plain explanation out. Works on a raw task row, a projection task,
+// or a bare { title, tag, metadata } shape, so every surface reads the same
+// three sentences.
+function taskExplanation(task) {
+  const explicit = explicitExplanationFields(task && task.metadata);
+  const derived = {
+    what_changes: derivedWhatChanges(task),
+    why_it_matters: derivedWhyItMatters(task),
+    done_looks_like: derivedDoneLooksLike(task),
+  };
+  const explanation = { sources: {} };
+  for (const field of EXPLANATION_FIELDS) {
+    explanation[field] = endSentence(plainText(explicit[field])) || derived[field];
+    explanation.sources[field] = explicit[field] ? 'explicit' : 'derived';
+  }
+  explanation.authored = EXPLANATION_FIELDS.every(field => explanation.sources[field] === 'explicit');
+  explanation.reason_recorded = Boolean(explicit.why_it_matters || explanationGoalText(task));
+  return explanation;
+}
+
+// Pull caller-supplied explanation fields off an options bag or an API body.
+// Only the exact field names count, so ordinary metadata keys can never be
+// mistaken for an author's sentence.
+function explanationFieldsFromInput(input) {
+  const out = {};
+  if (!input || typeof input !== 'object') return out;
+  const nested = input.explanation && typeof input.explanation === 'object' ? input.explanation : {};
+  for (const field of EXPLANATION_FIELDS) {
+    const camel = field.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+    for (const key of [field, camel]) {
+      const value = cleanText(nested[key] !== undefined ? nested[key] : input[key]);
+      if (value) { out[field] = value; break; }
+    }
+  }
+  return out;
+}
+
+// Dense rows (list, day, desk, TODO) already print the title on the line
+// above. Pass that title and a derived what_changes, which is the title, drops
+// out instead of echoing. An authored what_changes always survives, because it
+// says something the title does not.
+function explanationFieldList(explanation, { title = null } = {}) {
+  if (title == null) return EXPLANATION_FIELDS;
+  const echo = endSentence(title);
+  return EXPLANATION_FIELDS.filter(field => !(field === 'what_changes' && explanation.what_changes === echo));
+}
+
+function explanationLines(explanation, { indent = '', title = null } = {}) {
+  return explanationFieldList(explanation, { title })
+    .map(field => `${indent}${EXPLANATION_LABELS[field]}: ${explanation[field]}`);
+}
+
+function explanationMarkdownLines(explanation, { indent = '  ', title = null } = {}) {
+  return explanationFieldList(explanation, { title })
+    .map(field => `${indent}**${EXPLANATION_LABELS[field]}:** ${explanation[field]}`);
+}
+
+// The approval half of the first layer: approve the work, or ask for a change.
+// The caller passes the answer from the existing certification gate; this
+// helper only labels it. It can never widen what acceptance allows.
+function taskApprovalControls({
+  question = null,
+  approveLabel = 'Approve this work',
+  acceptEnabled = false,
+  acceptCommand = null,
+  requestChangeEnabled = false,
+  requestChangeCommand = null,
+  blockedReason = null,
+  waitingOn = null,
+} = {}) {
+  const approveEnabled = Boolean(acceptEnabled && acceptCommand);
+  return {
+    question: question || (approveEnabled || requestChangeEnabled
+      ? 'Approve this work, or ask for a change?'
+      : 'Nothing to approve yet.'),
+    approve: {
+      label: approveLabel,
+      enabled: approveEnabled,
+      command: approveEnabled ? acceptCommand : null,
+      human_only: true,
+      blocked_reason: approveEnabled ? null : (blockedReason || null),
+    },
+    request_change: {
+      label: 'Ask for a change',
+      enabled: Boolean(requestChangeEnabled && requestChangeCommand),
+      command: requestChangeEnabled ? requestChangeCommand : null,
+    },
+    waiting_on: waitingOn || null,
+  };
+}
+
+function approvalLines(approval, { indent = '' } = {}) {
+  const lines = [`${indent}${approval.question}`];
+  if (approval.approve.enabled) lines.push(`${indent}Approve: ${approval.approve.command}`);
+  else if (approval.approve.blocked_reason) lines.push(`${indent}Cannot approve yet: ${approval.approve.blocked_reason}`);
+  if (approval.request_change.enabled) lines.push(`${indent}Ask for a change: ${approval.request_change.command}`);
+  return lines;
+}
+
+module.exports = {
+  EXPLANATION_FIELDS,
+  EXPLANATION_LABELS,
+  NO_REASON_RECORDED,
+  plainText,
+  taskExplanation,
+  explanationFieldsFromInput,
+  explanationLines,
+  explanationMarkdownLines,
+  taskApprovalControls,
+  approvalLines,
+};

package/lib/todo-fallback.js

@@ -125,6 +125,12 @@ function parseSection(content, sectionName) {
 
     const verifyMatch = line.match(/\*\*Verify:\*\*\s*(.+)$/) || line.match(/Verify:\s*(.+)$/);
     if (verifyMatch) { current.verify = verifyMatch[1].trim(); continue; }
+
+    // Generated task boards lead with the plain explanation, then keep the
+    // exact original title here. The TODO-only fallback must restore that
+    // original title so presentation never weakens task identity or logic.
+    const technicalDetailsMatch = line.match(/\*\*Technical details:\*\*\s*(.+)$/i);
+    if (technicalDetailsMatch) { current.title = technicalDetailsMatch[1].trim(); continue; }
   }
 
   if (current) tasks.push(current);

package/lib/voice-card.js

@@ -0,0 +1,258 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const VOICE_CARD_START = '<!-- ATRIS_VOICE_CARD:START -->';
+const VOICE_CARD_END = '<!-- ATRIS_VOICE_CARD:END -->';
+const BRAIN_START = '<!-- ATRIS_BRAIN_COMPILE:START -->';
+const BRAIN_END = '<!-- ATRIS_BRAIN_COMPILE:END -->';
+const CLAUDE_VOICE_HOOK_COMMAND = 'command -v atris >/dev/null 2>&1 && atris voice card --hook || true';
+
+function extractVoiceDoctrine(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  const start = lines.findIndex((line) => /^## voice\s*$/i.test(line));
+  if (start === -1) return '';
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index])) {
+      end = index;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').trim();
+}
+
+function readVoiceDoctrine(root = process.cwd()) {
+  const candidates = [
+    path.join(root, 'atris.md'),
+    path.join(root, 'atris', 'atris.md'),
+  ];
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    const doctrine = extractVoiceDoctrine(fs.readFileSync(file, 'utf8'));
+    if (doctrine) return doctrine;
+  }
+  return '';
+}
+
+function principleSentence(doctrine, label, fallback) {
+  const line = String(doctrine || '')
+    .split(/\r?\n/)
+    .find((candidate) => candidate.startsWith('- **') && label.test(candidate));
+  if (!line) return fallback;
+  const body = line.replace(/^- \*\*[^*]+\*\*\s*/, '').trim();
+  const sentence = body.match(/^.*?[.!?](?:\s|$)/);
+  return (sentence ? sentence[0] : body)
+    .replace(/`/g, '')
+    .replace(/\s+/g, ' ')
+    .trim() || fallback;
+}
+
+function naturalLead(source) {
+  if (source === 'Answer first, support after.') {
+    return 'Start with the answer, then give the reader only what helps them act.';
+  }
+  return source;
+}
+
+function naturalSpecific(source) {
+  if (source === 'Name the exact thing.') {
+    return 'Name the exact thing in plain words, like you are talking to a person.';
+  }
+  return source;
+}
+
+function composeVoiceCard(doctrine = readVoiceDoctrine(PACKAGE_ROOT)) {
+  const lead = naturalLead(principleSentence(
+    doctrine,
+    /Lead with the move/i,
+    'Start with the answer, then give the reader only what helps them act.',
+  ));
+  const specific = naturalSpecific(principleSentence(
+    doctrine,
+    /Specific over buzzy/i,
+    'Name the exact thing in plain words, like you are talking to a person.',
+  ));
+
+  return `${lead} ${specific}
+
+Keep each paragraph to one or two sentences and leave a blank line between thoughts. Use a comma or period instead of an em dash.
+
+Status example:
+The reply check is built. I am running the final checks now, so the result is not ready yet.
+
+Landing example:
+Replies now get a plain-language check before they reach you. The checks passed, and the change is ready.`;
+}
+
+const VOICE_CARD = composeVoiceCard();
+
+function voiceCardForRoot(root = process.cwd()) {
+  const doctrine = readVoiceDoctrine(root) || readVoiceDoctrine(PACKAGE_ROOT);
+  return composeVoiceCard(doctrine);
+}
+
+function buildVoiceCardHookJson(card = VOICE_CARD) {
+  return {
+    suppressOutput: true,
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: card,
+    },
+  };
+}
+
+function renderVoiceCardBlock(card = VOICE_CARD) {
+  return `${VOICE_CARD_START}
+## Voice card
+
+${card}
+${VOICE_CARD_END}`;
+}
+
+function replaceOrAppendVoiceBlock(source, card) {
+  const block = renderVoiceCardBlock(card);
+  const start = source.indexOf(VOICE_CARD_START);
+  const end = source.indexOf(VOICE_CARD_END, start + VOICE_CARD_START.length);
+  if (start !== -1 && end !== -1) {
+    return `${source.slice(0, start)}${block}${source.slice(end + VOICE_CARD_END.length)}`;
+  }
+  const separator = source.trim() ? '\n\n' : '';
+  return `${source.trimEnd()}${separator}${block}\n`;
+}
+
+function ensureAlwaysApplyFrontmatter(source) {
+  if (!source.startsWith('---\n') && !source.startsWith('---\r\n')) {
+    return `---\nalwaysApply: true\n---\n\n${source.replace(/^\s+/, '')}`;
+  }
+
+  const normalized = source.replace(/\r\n/g, '\n');
+  const closing = normalized.indexOf('\n---', 4);
+  if (closing === -1) {
+    return `---\nalwaysApply: true\n---\n\n${source}`;
+  }
+
+  const frontmatter = normalized.slice(4, closing).split('\n');
+  const alwaysApply = frontmatter.findIndex((line) => /^alwaysApply\s*:/.test(line));
+  if (alwaysApply === -1) frontmatter.push('alwaysApply: true');
+  else frontmatter[alwaysApply] = 'alwaysApply: true';
+  return `---\n${frontmatter.join('\n')}\n---${normalized.slice(closing + 4)}`;
+}
+
+function upsertCursorVoiceCard(filePath, card = VOICE_CARD, options = {}) {
+  const source = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const withFrontmatter = ensureAlwaysApplyFrontmatter(source);
+  const content = replaceOrAppendVoiceBlock(withFrontmatter, card);
+  const changed = content !== source;
+  if (changed && !options.dryRun) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+  return { action: source ? (changed ? 'updated' : 'unchanged') : 'created', content };
+}
+
+function upsertAgentVoiceCard(filePath, card = VOICE_CARD, options = {}) {
+  const source = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const brainStart = source.indexOf(BRAIN_START);
+  const brainEnd = source.indexOf(BRAIN_END, brainStart + BRAIN_START.length);
+  let content;
+
+  if (brainStart !== -1 && brainEnd !== -1) {
+    const block = source.slice(brainStart, brainEnd + BRAIN_END.length);
+    const updatedBlock = replaceOrAppendVoiceBlock(
+      block.slice(0, -BRAIN_END.length).trimEnd(),
+      card,
+    ).trimEnd() + `\n${BRAIN_END}`;
+    content = `${source.slice(0, brainStart)}${updatedBlock}${source.slice(brainEnd + BRAIN_END.length)}`;
+  } else {
+    const prefix = source.trimEnd() || '# AGENTS';
+    content = `${prefix}\n\n${BRAIN_START}\n## Atris Brain Compile\n\n${renderVoiceCardBlock(card)}\n${BRAIN_END}\n`;
+  }
+
+  const changed = content !== source;
+  if (changed && !options.dryRun) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+  return { action: source ? (changed ? 'updated' : 'unchanged') : 'created', content };
+}
+
+function voiceHookEntry() {
+  return {
+    hooks: [
+      {
+        type: 'command',
+        command: CLAUDE_VOICE_HOOK_COMMAND,
+      },
+    ],
+  };
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function invalidSettings(filePath, warn, reason) {
+  const warning = `could not add the atris voice hook to ${path.relative(process.cwd(), filePath) || filePath} because ${reason}; the file was left unchanged.`;
+  warn(warning);
+  return { action: 'skipped', warning };
+}
+
+function upsertClaudeVoiceHook(filePath, options = {}) {
+  const exists = fs.existsSync(filePath);
+  const source = exists ? fs.readFileSync(filePath, 'utf8') : null;
+  const warn = options.warn || console.warn;
+  let settings;
+
+  if (exists) {
+    try {
+      settings = JSON.parse(source);
+    } catch {
+      return invalidSettings(filePath, warn, 'it is not valid json');
+    }
+  } else {
+    settings = JSON.parse(JSON.stringify(options.initialSettings || {}));
+  }
+
+  if (!isPlainObject(settings)) {
+    return invalidSettings(filePath, warn, 'its top level is not an object');
+  }
+  if (settings.hooks === undefined) settings.hooks = {};
+  if (!isPlainObject(settings.hooks)) {
+    return invalidSettings(filePath, warn, 'its hooks value is not an object');
+  }
+  if (settings.hooks.UserPromptSubmit === undefined) settings.hooks.UserPromptSubmit = [];
+  if (!Array.isArray(settings.hooks.UserPromptSubmit)) {
+    return invalidSettings(filePath, warn, 'its UserPromptSubmit hooks are not a list');
+  }
+
+  const present = settings.hooks.UserPromptSubmit.some((group) => (
+    group && Array.isArray(group.hooks) && group.hooks.some((hook) => (
+      hook && typeof hook.command === 'string' && hook.command.includes('atris voice card --hook')
+    ))
+  ));
+  if (present) return { action: 'unchanged', content: source };
+
+  settings.hooks.UserPromptSubmit.push(voiceHookEntry());
+  const content = `${JSON.stringify(settings, null, 2)}\n`;
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+  return { action: exists ? 'updated' : 'created', content };
+}
+
+module.exports = {
+  CLAUDE_VOICE_HOOK_COMMAND,
+  VOICE_CARD,
+  buildVoiceCardHookJson,
+  composeVoiceCard,
+  readVoiceDoctrine,
+  renderVoiceCardBlock,
+  upsertAgentVoiceCard,
+  upsertClaudeVoiceHook,
+  upsertCursorVoiceCard,
+  voiceCardForRoot,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.45.1",
+  "version": "3.46.1",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "main": "bin/atris.js",
   "bin": {

package/templates/research-canonical/atris.md

@@ -25,6 +25,12 @@ Use `atris task` when available. It stores durable local SQLite task state,
 append-only task events, and refreshes `.atris/state/tasks.projection.json` for
 desktop/web/agent views.
 
+Every task view leads with what changes, why it matters, and what done looks
+like in plain words. Exact titles, requirements, sources, commands, events,
+proof, and approval rules remain underneath unchanged. Planned work uses the
+existing approve-or-change path; completed work still needs the existing proof
+and human acceptance gates.
+
 `atris/TODO.md` is the readable fallback/projection. It can be rebuilt with
 `atris task render --out atris/TODO.md`; do not rely on manual TODO.md edits for
 ownership. In cloud business workspaces, Supabase `tasks` is the source of truth