atris 3.53.0 → 3.56.0

package/lib/workspace-scaffold.js

@@ -0,0 +1,270 @@
+const fs = require('fs');
+const path = require('path');
+const { ensureWikiScaffold } = require('./wiki');
+
+const PACKAGE_ATRIS_MD = path.join(__dirname, '..', 'atris.md');
+
+function mapPlaceholder() {
+  return '# MAP.md\n\n> Generated by your AI agent after reading atris.md\n\nRun your AI agent with atris.md to populate this file.\n';
+}
+
+function todoPlaceholder() {
+  return `# TODO.md
+
+> Working task queue for this project. Target state = 0.
+> Note: Daily tasks also appear in \`atris/logs/YYYY/YYYY-MM-DD.md\`
+
+---
+
+## Backlog
+
+- **T1:** Generate MAP.md — scan codebase, create navigation index with file:line refs
+
+---
+
+## In Progress
+
+(empty)
+
+---
+
+## Completed
+
+(Validator deletes after verification)
+
+---
+`;
+}
+
+function firstJournalMarkdown(today) {
+  return `# Log — ${today}
+
+## Completed ✅
+
+---
+
+## In Progress 🔄
+
+---
+
+## Backlog
+
+- **T1:** Generate MAP.md — scan codebase, create navigation index with file:line refs
+
+---
+
+## Notes
+
+**Bootstrap:** Say "atris next" to start. After MAP.md is generated, system will brainstorm ideas for your first build.
+
+---
+
+## Inbox
+
+`;
+}
+
+function posixRel(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join('/');
+}
+
+function writeIfMissing(filePath, content) {
+  if (fs.existsSync(filePath)) return false;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, { encoding: 'utf8', flag: 'wx' });
+  return true;
+}
+
+function copyIfMissing(sourcePath, destPath) {
+  if (fs.existsSync(destPath) || !fs.existsSync(sourcePath)) return false;
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  fs.copyFileSync(sourcePath, destPath);
+  return true;
+}
+
+function ensureDir(dirPath) {
+  if (fs.existsSync(dirPath)) return false;
+  fs.mkdirSync(dirPath, { recursive: true });
+  return true;
+}
+
+function hasDatedLog(logsDir) {
+  if (!fs.existsSync(logsDir)) return false;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (walk(full)) return true;
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        return true;
+      }
+    }
+    return false;
+  };
+  return walk(logsDir);
+}
+
+function workspaceBrainPresent(projectRoot = process.cwd()) {
+  const atrisDir = path.join(projectRoot, 'atris');
+  const required = ['MAP.md', 'TODO.md', 'now.md', 'atris.md', path.join('wiki', 'index.md')];
+  if (!required.every((rel) => fs.existsSync(path.join(atrisDir, rel)))) return false;
+  try {
+    if (!fs.statSync(path.join(atrisDir, 'team')).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return hasDatedLog(path.join(atrisDir, 'logs'));
+}
+
+function ensureWorkspaceBrain(projectRoot = process.cwd(), { now = new Date() } = {}) {
+  const created = [];
+  const atrisDir = path.join(projectRoot, 'atris');
+  const note = (filePath) => created.push(posixRel(projectRoot, filePath));
+
+  ensureDir(atrisDir);
+
+  const wikiIndex = path.join(atrisDir, 'wiki', 'index.md');
+  const wikiMissing = !fs.existsSync(wikiIndex);
+  ensureWikiScaffold(projectRoot);
+  if (wikiMissing && fs.existsSync(wikiIndex)) note(wikiIndex);
+
+  const mapFile = path.join(atrisDir, 'MAP.md');
+  if (writeIfMissing(mapFile, mapPlaceholder())) note(mapFile);
+
+  const todoFile = path.join(atrisDir, 'TODO.md');
+  if (writeIfMissing(todoFile, todoPlaceholder())) note(todoFile);
+
+  const nowFile = path.join(atrisDir, 'now.md');
+  if (!fs.existsSync(nowFile)) {
+    const { renderDefaultNow } = require('../commands/now');
+    if (writeIfMissing(nowFile, renderDefaultNow(projectRoot))) note(nowFile);
+  }
+
+  const year = String(now.getFullYear());
+  const today = now.toISOString().split('T')[0];
+  const journalFile = path.join(atrisDir, 'logs', year, `${today}.md`);
+  if (writeIfMissing(journalFile, firstJournalMarkdown(today))) note(journalFile);
+
+  const teamDir = path.join(atrisDir, 'team');
+  if (ensureDir(teamDir)) created.push(posixRel(projectRoot, teamDir) + '/');
+
+  const atrisMd = path.join(atrisDir, 'atris.md');
+  if (copyIfMissing(PACKAGE_ATRIS_MD, atrisMd)) note(atrisMd);
+
+  const taskSeed = seedInitTaskPlane(projectRoot, { todoFile, journalFile });
+
+  return { created, atrisDir, taskSeed };
+}
+
+/**
+ * Seed the SQLite task plane from TODO.md + today's journal so status/task list agree.
+ * Idempotent via source_key and normalized-title dedupe.
+ */
+function seedInitTaskPlane(projectRoot, { todoFile, journalFile } = {}) {
+  try {
+    const taskDb = require('./task-db');
+    const { parseTodoFile, parseSection } = require('./todo-fallback');
+    const { parseInboxItems } = require('./file-ops');
+    const db = taskDb.open();
+    const workspaceRoot = taskDb.workspaceRoot(projectRoot);
+    const existing = taskDb.listTasks(db, { workspaceRoot, limit: 500 });
+    const knownTitles = new Set(existing.map((row) => taskDb.normalizeTitle(row.title)));
+
+    const candidates = [];
+    const todoPath = todoFile || path.join(projectRoot, 'atris', 'TODO.md');
+    if (fs.existsSync(todoPath)) {
+      const parsed = parseTodoFile(todoPath);
+      for (const t of parsed.backlog || []) {
+        candidates.push({ ...t, importStatus: 'open', sourceFile: todoPath });
+      }
+      for (const t of parsed.inProgress || []) {
+        candidates.push({ ...t, importStatus: 'claimed', sourceFile: todoPath });
+      }
+      for (const t of parsed.review || []) {
+        candidates.push({ ...t, importStatus: 'review', sourceFile: todoPath });
+      }
+    }
+
+    const journalPath = journalFile || null;
+    if (journalPath && fs.existsSync(journalPath)) {
+      const content = fs.readFileSync(journalPath, 'utf8');
+      for (const t of parseSection(content, 'Backlog')) {
+        candidates.push({ ...t, importStatus: 'open', sourceFile: journalPath });
+      }
+      for (const t of parseSection(content, 'In Progress')) {
+        candidates.push({ ...t, importStatus: 'claimed', sourceFile: journalPath });
+      }
+      for (const item of parseInboxItems(content)) {
+        candidates.push({
+          id: `I${item.id}`,
+          title: item.text,
+          tag: 'inbox',
+          importStatus: 'open',
+          sourceFile: journalPath,
+        });
+      }
+    }
+
+    let inserted = 0;
+    let skipped = 0;
+    for (const t of candidates) {
+      if (!t.title) continue;
+      const normalized = taskDb.normalizeTitle(t.title);
+      if (knownTitles.has(normalized)) {
+        skipped += 1;
+        continue;
+      }
+      const sk = taskDb.sourceKey(t.sourceFile, t.title);
+      const result = taskDb.addTask(db, {
+        title: t.title,
+        tag: t.tag || null,
+        workspaceRoot,
+        sourceKey: sk,
+        status: t.importStatus || 'open',
+        claimedBy: t.claimed || null,
+        metadata: {
+          source: 'init_seed',
+          todo_id: t.id || null,
+          todo_tags: t.tags || [],
+        },
+      });
+      if (result.inserted) {
+        inserted += 1;
+        knownTitles.add(normalized);
+      } else {
+        skipped += 1;
+      }
+    }
+
+    const rows = taskDb.listTasks(db, { workspaceRoot, limit: 500 });
+    const projection = taskDb.taskProjection(db, { workspaceRoot, limit: 500 });
+    const projectionPath = path.join(projectRoot, '.atris', 'state', 'tasks.projection.json');
+    fs.mkdirSync(path.dirname(projectionPath), { recursive: true });
+    fs.writeFileSync(projectionPath, `${JSON.stringify(projection, null, 2)}\n`, 'utf8');
+    try {
+      fs.writeFileSync(
+        path.join(projectRoot, 'atris', 'TODO.md'),
+        taskDb.renderTodoMarkdown(rows, { title: 'TODO.md' }),
+        'utf8'
+      );
+    } catch {}
+
+    return { ok: true, inserted, skipped, count: rows.length, projectionPath };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error && error.message ? error.message : String(error),
+    };
+  }
+}
+
+module.exports = {
+  ensureWorkspaceBrain,
+  workspaceBrainPresent,
+};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "atris",
-  "version": "3.53.0",
+  "version": "3.56.0",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "main": "bin/atris.js",
   "bin": {
-    "atris": "bin/atris.js",
+    "atris": "bin/atris",
     "ax": "ax"
   },
   "files": [
@@ -55,6 +55,7 @@
     "atris/team/opus-overnight/START_HERE.md",
     "atris/team/opus-overnight/STEERING.md",
     "atris/team/_template/MEMBER.md",
+    "atris/team/_template/SOUL.md",
     "atris/features/_templates/",
     "atris/features/company-brain-sync/",
     "atris/policies/",

package/scripts/det/checklist-score.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+'use strict';
+
+// Pareto-3 checklist quality score.
+//
+// Measures the three front doors a brand-new person actually hits, the way
+// they would hit them: from an empty folder, with no context, reading only
+// what the tool prints. Every point is earned by a live probe, never opinion.
+//
+//   1. onboard  - `atris init --yes` in a fresh folder
+//   2. chat     - one real answered message through `ax`
+//   3. mission  - the end-to-end loop drill in its own sandbox
+//
+// Rubric per feature (100 points):
+//   cold start works, zero setup ......... 40
+//   speed to first value ................. 20  (full marks at target, 0 at 4x)
+//   plain language on the first screen ... 20  (fraction of clean lines)
+//   graceful failure on wrong input ...... 20  (honest exit + plain reason,
+//                                               no stack trace)
+//
+// Usage: node scripts/det/checklist-score.js [--json]
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+const cliPath = path.join(repoRoot, 'bin', 'atris.js');
+const axPath = path.join(repoRoot, 'ax');
+const { scanText } = require(path.join(repoRoot, 'lib', 'voice-gate'));
+
+// System nouns a person with no idea should never have to decode on a first
+// screen. Backticked command examples are exempt (they are copy targets).
+const SYSTEM_NOUNS = /\b(?:verifier|worktree|subagent|jsonl|projection|runner[- ]profile|heartbeat|orchestrat\w+|frontmatter|monorepo)\b/i;
+const STACK_FRAME = /^\s+at .+:\d+:\d+\)?$/;
+
+function run(cmd, args, options = {}) {
+  const started = Date.now();
+  const result = spawnSync(cmd, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    timeout: options.timeoutMs || 180000,
+    env: { ...process.env, ATRIS_SKIP_UPDATE_CHECK: '1', ...(options.env || {}) },
+  });
+  return {
+    status: result.status,
+    error: result.error || null,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    ms: Date.now() - started,
+  };
+}
+
+function speedPoints(ms, targetMs) {
+  if (ms <= targetMs) return 20;
+  const over = (ms - targetMs) / (targetMs * 3);
+  return Math.max(0, Math.round(20 * (1 - over)));
+}
+
+function plainPoints(text) {
+  const lines = String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 30);
+  if (!lines.length) return { points: 0, dirty: ['(no output at all)'] };
+  const dirty = [];
+  for (const line of lines) {
+    // Command examples are copy targets, not prose; the reader with no idea
+    // reads the description column, so scan only the human words.
+    if (/^`.*`$/.test(line) || /^\$\s/.test(line) || /^(?:ax|atris|npx)\s/.test(line)) continue;
+    const bare = line
+      .replace(/`[^`]*`/g, '')
+      .replace(/--[\w-]+/g, '')
+      .replace(/\[[^\]]*\]/g, '')
+      .replace(/<[^>]*>/g, '');
+    if (STACK_FRAME.test(line) || /\u2014/.test(bare) || SYSTEM_NOUNS.test(bare) || scanText(bare).length) {
+      dirty.push(line.slice(0, 80));
+    }
+  }
+  const clean = lines.length - dirty.length;
+  return { points: Math.round((20 * clean) / lines.length), dirty };
+}
+
+function failurePoints(result) {
+  const text = `${result.stdout}\n${result.stderr}`;
+  const honest = result.status !== 0 && !result.error;
+  const noStack = !text.split(/\r?\n/).some((line) => STACK_FRAME.test(line))
+    && !/\b(?:TypeError|ReferenceError|SyntaxError)\b/.test(text);
+  const saysWhy = /\b(?:unknown|not found|no such|missing|usage|help|try|error)\b/i.test(text);
+  let points = 0;
+  if (honest) points += 8;
+  if (noStack) points += 6;
+  if (saysWhy) points += 6;
+  return points;
+}
+
+function scoreOnboard(base) {
+  const dir = fs.mkdtempSync(path.join(base, 'onboard-'));
+  const cold = run(process.execPath, [cliPath, 'init', '--yes'], { cwd: dir });
+  const artifact = fs.existsSync(path.join(dir, 'atris'));
+  const coldPoints = cold.status === 0 && artifact ? 40 : 0;
+  const plain = plainPoints(cold.stdout);
+  const bad = run(process.execPath, [cliPath, 'definitely-not-a-command'], { cwd: dir });
+  return {
+    feature: 'onboard: atris init in an empty folder',
+    dir,
+    cold: coldPoints,
+    speed: speedPoints(cold.ms, 10000),
+    plain: plain.points,
+    failure: failurePoints(bad),
+    ms: cold.ms,
+    dirty_lines: plain.dirty,
+  };
+}
+
+function scoreChat(base, workspaceDir) {
+  const cold = run(process.execPath, [axPath, '--fast', '--print', 'Reply with exactly: checklist-ok'], {
+    cwd: workspaceDir,
+    timeoutMs: 120000,
+  });
+  let answered = false;
+  try {
+    const payload = JSON.parse(cold.stdout.slice(cold.stdout.indexOf('{')));
+    answered = payload.ok === true && /checklist-ok/.test(String(payload.output || ''));
+  } catch {}
+  const helpScreen = run(process.execPath, [axPath, '--help'], { cwd: workspaceDir, timeoutMs: 30000 });
+  const plain = plainPoints(helpScreen.stdout);
+  const bad = run(process.execPath, [axPath, '--fast', '--print'], { cwd: workspaceDir, timeoutMs: 30000 });
+  return {
+    feature: 'chat: one real answered message through ax',
+    cold: cold.status !== null && answered ? 40 : 0,
+    speed: speedPoints(cold.ms, 15000),
+    plain: plain.points,
+    failure: failurePoints(bad),
+    ms: cold.ms,
+    dirty_lines: plain.dirty,
+  };
+}
+
+function scoreMission(base, workspaceDir) {
+  const cold = run(process.execPath, [cliPath, 'drill', '--json'], { cwd: workspaceDir, timeoutMs: 300000 });
+  let passed = false;
+  let stages = 0;
+  try {
+    const payload = JSON.parse(cold.stdout.slice(cold.stdout.indexOf('{')));
+    passed = payload.pass === true;
+    stages = Array.isArray(payload.stages) ? payload.stages.length : 0;
+  } catch {}
+  const status = run(process.execPath, [cliPath, 'mission'], { cwd: workspaceDir, timeoutMs: 60000 });
+  const plain = plainPoints(status.stdout);
+  const bad = run(process.execPath, [cliPath, 'mission', 'run', '9999'], { cwd: workspaceDir, timeoutMs: 60000 });
+  return {
+    feature: `mission: full loop drill (${stages} stages) plus status screen`,
+    cold: passed ? 40 : 0,
+    speed: speedPoints(cold.ms, 90000),
+    plain: plain.points,
+    failure: failurePoints(bad),
+    ms: cold.ms,
+    dirty_lines: plain.dirty,
+  };
+}
+
+function main() {
+  const asJson = process.argv.includes('--json');
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'atris-checklist-'));
+  const onboard = scoreOnboard(base);
+  const chat = scoreChat(base, onboard.dir);
+  const mission = scoreMission(base, onboard.dir);
+  const features = [onboard, chat, mission].map((f) => ({
+    ...f,
+    total: f.cold + f.speed + f.plain + f.failure,
+  }));
+  const overall = Math.round(features.reduce((sum, f) => sum + f.total, 0) / features.length);
+  const report = { schema: 'atris.checklist_score.v1', overall, features };
+  fs.rmSync(base, { recursive: true, force: true });
+  if (asJson) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log('Pareto-3 checklist quality score\n');
+  for (const f of features) {
+    console.log(`  ${f.feature}`);
+    console.log(`    cold start ${f.cold}/40 · speed ${f.speed}/20 (${(f.ms / 1000).toFixed(1)}s) · plain words ${f.plain}/20 · graceful failure ${f.failure}/20  =>  ${f.total}/100`);
+    if (f.dirty_lines.length) console.log(`    lines that need plain words: ${f.dirty_lines.length}`);
+  }
+  console.log(`\n  overall: ${overall}/100`);
+}
+
+main();

package/scripts/det/ytsearch

@@ -0,0 +1,31 @@
+#!/bin/bash
+# ytsearch <query> [limit]: free YouTube discovery via yt-dlp ytsearchN.
+# Zero Atris credits. Prints one line per video:
+#   title | channel | duration | views | upload_date | https://youtu.be/ID
+# upload_date is YYYYMMDD (or NA) so callers can apply a freshness gate.
+set -euo pipefail
+
+USAGE='usage: ytsearch "<query>" [limit]'
+
+QUERY="${1:-}"
+LIMIT="${2:-5}"
+
+if [ -z "$QUERY" ] || [ "$QUERY" = '-h' ] || [ "$QUERY" = '--help' ] || [ "$QUERY" = 'help' ]; then
+  echo "$USAGE" >&2
+  exit 2
+fi
+
+if ! [[ "$LIMIT" =~ ^[1-9][0-9]*$ ]]; then
+  echo "limit must be a positive integer" >&2
+  exit 2
+fi
+
+if ! command -v yt-dlp >/dev/null 2>&1; then
+  echo "yt-dlp not found on PATH" >&2
+  exit 2
+fi
+
+# flat-playlist keeps this a metadata-only discovery call (no download).
+yt-dlp --no-update --flat-playlist --no-warnings \
+  --print '%(title)s | %(channel)s | %(duration_string)s | %(view_count)s | %(upload_date)s | https://youtu.be/%(id)s' \
+  "ytsearch${LIMIT}:${QUERY}"

package/utils/update-check.js

@@ -293,6 +293,20 @@ function formatInstallGitWarning(state) {
     'npm install -g atris@latest may not change the code currently on PATH; resolve that checkout before trusting upgrade status.';
 }
 
+/**
+ * Human version line. Published/sealed installs stay plain.
+ * Git checkouts append `(git <sha> [dirty] <branch>)`.
+ */
+function formatCliVersionLine(version, packageRoot = path.join(__dirname, '..')) {
+  const base = String(version || 'unknown').replace(/^v/, '');
+  if (!isGitCheckout(packageRoot)) return `atris v${base}`;
+  const state = inspectInstallGitState(packageRoot);
+  const sha = state.head || 'unknown';
+  const branch = state.detached ? 'detached' : (state.branch || 'unknown');
+  if (state.dirty) return `atris v${base} (git ${sha} dirty ${branch})`;
+  return `atris v${base} (git ${sha} ${branch})`;
+}
+
 function normalizeAutoUpdateMode(env = process.env) {
   const raw = String(env.ATRIS_AUTO_UPDATE || '').trim().toLowerCase();
   if (['0', 'false', 'no', 'off', 'notify'].includes(raw)) return 'off';
@@ -349,6 +363,7 @@ module.exports = {
   shouldAutoUpdate,
   inspectInstallGitState,
   formatInstallGitWarning,
+  formatCliVersionLine,
   isGitCheckout,
   getNpmSelfUpdateCommand,
   getNpmSelfUpdateSpawnArgs,