atris 3.1.0 → 3.5.0

package/commands/sync.js

@@ -3,7 +3,17 @@ const path = require('path');
 const os = require('os');
 const { ensureWikiScaffold } = require('../lib/wiki');
 
-const BUSINESS_TEMPLATE_DIR = path.join(__dirname, '..', 'templates', 'business-canonical');
+const TEMPLATE_ROOT_DIR = path.join(__dirname, '..', 'templates');
+const WORKSPACE_TEMPLATES = {
+  business: {
+    dir: path.join(TEMPLATE_ROOT_DIR, 'business-starter'),
+    label: 'business environment',
+  },
+  research: {
+    dir: path.join(TEMPLATE_ROOT_DIR, 'research-canonical'),
+    label: 'research lab environment',
+  },
+};
 
 /**
  * Walk a directory and return relative file paths.
@@ -25,7 +35,7 @@ function _walkTemplateDir(dir, base = dir) {
 }
 
 /**
- * Substitute {{name}}, {{slug}}, {{owner_email}} in template content.
+ * Substitute workspace metadata in template content.
  */
 function _substituteParams(content, params) {
   return content
@@ -33,7 +43,129 @@ function _substituteParams(content, params) {
     .replace(/\{\{slug\}\}/g, params.slug || 'business')
     .replace(/\{\{owner_email\}\}/g, params.owner_email || '')
     .replace(/\{\{business_id\}\}/g, params.business_id || '')
-    .replace(/\{\{workspace_id\}\}/g, params.workspace_id || '');
+    .replace(/\{\{workspace_id\}\}/g, params.workspace_id || '')
+    .replace(/\{\{today\}\}/g, params.today || new Date().toISOString().slice(0, 10))
+    .replace(/\{\{workspace_template\}\}/g, params.workspace_template || 'business');
+}
+
+/**
+ * Sync the canonical skill set from atris-cli/atris/skills/* into a
+ * workspace's atris/skills/* (plus ensure .claude/skills/ symlinks).
+ *
+ * Shared by business mode (via syncWorkspaceTemplate) and legacy/dev mode
+ * (via syncAtris). Single source of truth = atris-cli/atris/skills/.
+ *
+ * Returns the number of files updated (0 if everything was up to date).
+ */
+function syncPackageSkills(targetAtrisDir, opts = {}) {
+  const packageSkillsDir = path.join(__dirname, '..', 'atris', 'skills');
+  const userSkillsDir = path.join(targetAtrisDir, 'skills');
+  const claudeSkillsBaseDir = path.join(path.dirname(targetAtrisDir), '.claude', 'skills');
+  const verbose = opts.verbose !== false;
+  let updated = 0;
+
+  if (!fs.existsSync(packageSkillsDir)) return 0;
+
+  if (!fs.existsSync(userSkillsDir)) fs.mkdirSync(userSkillsDir, { recursive: true });
+  if (!fs.existsSync(claudeSkillsBaseDir)) fs.mkdirSync(claudeSkillsBaseDir, { recursive: true });
+
+  const skillFolders = fs.readdirSync(packageSkillsDir).filter(f => {
+    try { return fs.statSync(path.join(packageSkillsDir, f)).isDirectory(); }
+    catch { return false; }
+  });
+
+  for (const skill of skillFolders) {
+    const srcSkillDir = path.join(packageSkillsDir, skill);
+    const destSkillDir = path.join(userSkillsDir, skill);
+    const symlinkPath = path.join(claudeSkillsBaseDir, skill);
+
+    const syncRecursive = (src, dest, skillName, basePath = '') => {
+      if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+      for (const entry of fs.readdirSync(src)) {
+        const srcPath = path.join(src, entry);
+        const destPath = path.join(dest, entry);
+        const relPath = basePath ? `${basePath}/${entry}` : entry;
+        if (fs.statSync(srcPath).isDirectory()) {
+          syncRecursive(srcPath, destPath, skillName, relPath);
+        } else {
+          const srcContent = fs.readFileSync(srcPath, 'utf8');
+          const destContent = fs.existsSync(destPath) ? fs.readFileSync(destPath, 'utf8') : '';
+          if (srcContent !== destContent) {
+            fs.writeFileSync(destPath, srcContent);
+            if (entry.endsWith('.sh')) fs.chmodSync(destPath, 0o755);
+            if (verbose) console.log(`✓ Updated atris/skills/${skillName}/${relPath}`);
+            updated++;
+          }
+        }
+      }
+    };
+
+    syncRecursive(srcSkillDir, destSkillDir, skill);
+
+    if (!fs.existsSync(symlinkPath)) {
+      const relativePath = path.relative(claudeSkillsBaseDir, destSkillDir);
+      try {
+        fs.symlinkSync(relativePath, symlinkPath);
+        if (verbose) console.log(`✓ Linked .claude/skills/${skill}`);
+      } catch (e) {
+        fs.mkdirSync(symlinkPath, { recursive: true });
+        const skillFile = path.join(destSkillDir, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+          fs.copyFileSync(skillFile, path.join(symlinkPath, 'SKILL.md'));
+        }
+        if (verbose) console.log(`✓ Copied .claude/skills/${skill} (symlink failed)`);
+      }
+    }
+  }
+
+  return updated;
+}
+
+function resolveWorkspaceTemplate(templateName = 'business') {
+  const normalized = String(templateName || 'business').toLowerCase();
+  if (normalized === 'research-lab' || normalized === 'researchlab' || normalized === 'lab') {
+    return { key: 'research', ...WORKSPACE_TEMPLATES.research };
+  }
+  const template = WORKSPACE_TEMPLATES[normalized];
+  if (!template) return null;
+  return { key: normalized, ...template };
+}
+
+function ensureWorkspaceStateFiles(targetRoot, params, options = {}) {
+  const dryRun = options.dryRun === true;
+  const metaDir = path.join(targetRoot, '.atris');
+  const stateDir = path.join(metaDir, 'state');
+  const created = [];
+
+  const files = [
+    {
+      relPath: '_sync.json',
+      content: `${JSON.stringify({
+        workspace_slug: params.slug || 'business',
+        business_id: params.business_id || '',
+        workspace_id: params.workspace_id || '',
+        workspace_template: params.workspace_template || 'business',
+        status: 'initialized-local',
+        updated_at: new Date().toISOString(),
+        source: 'workspace template bootstrap',
+      }, null, 2)}\n`,
+    },
+    { relPath: 'events.jsonl', content: '' },
+    { relPath: 'episodes.jsonl', content: '' },
+    { relPath: 'scorecards.jsonl', content: '' },
+  ];
+
+  for (const file of files) {
+    const fullPath = path.join(stateDir, file.relPath);
+    if (fs.existsSync(fullPath)) continue;
+    created.push(path.join('.atris', 'state', file.relPath));
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.writeFileSync(fullPath, file.content);
+    }
+  }
+
+  return created;
 }
 
 /**
@@ -43,36 +175,44 @@ function _substituteParams(content, params) {
  * Default: NEVER overwrites existing files (preserves customizations).
  * --force: overwrites existing canonical files (bumps to latest).
  */
-function syncBusinessCanonical(targetRoot, bizMeta, options = {}) {
+function syncWorkspaceTemplate(targetRoot, bizMeta, options = {}) {
+  const template = resolveWorkspaceTemplate(options.templateName || bizMeta.workspace_template || 'business');
+  if (!template) {
+    console.error(`✗ Unknown workspace template: ${options.templateName || bizMeta.workspace_template}`);
+    process.exit(1);
+  }
+
   const params = {
     slug: bizMeta.slug || 'business',
     name: bizMeta.name || bizMeta.slug || 'this business',
     owner_email: bizMeta.owner_email || '',
     business_id: bizMeta.business_id || '',
     workspace_id: bizMeta.workspace_id || '',
+    today: new Date().toISOString().slice(0, 10),
+    workspace_template: template.key,
   };
   const force = options.force != null ? options.force : process.argv.includes('--force');
   const dryRun = options.dryRun != null ? options.dryRun : process.argv.includes('--dry-run');
   const targetAtrisDir = path.join(targetRoot, 'atris');
 
-  if (!fs.existsSync(BUSINESS_TEMPLATE_DIR)) {
-    console.error(`✗ Canonical template directory not found: ${BUSINESS_TEMPLATE_DIR}`);
+  if (!fs.existsSync(template.dir)) {
+    console.error(`✗ Workspace template directory not found: ${template.dir}`);
     console.error('  Your atris-cli installation may be incomplete.');
     process.exit(1);
   }
 
   console.log('');
-  console.log(`Updating ${params.name} (${params.slug}) from canonical templates...`);
+  console.log(`Updating ${params.name} (${params.slug}) from ${template.label} templates...`);
   console.log(`  Target: ${targetAtrisDir}/`);
-  console.log(`  Source: ${BUSINESS_TEMPLATE_DIR}`);
+  console.log(`  Source: ${template.dir}`);
   console.log('');
 
-  const templateFiles = _walkTemplateDir(BUSINESS_TEMPLATE_DIR).sort();
+  const templateFiles = _walkTemplateDir(template.dir).sort();
   let added = 0, updated = 0, skipped = 0, preserved = 0;
   const addedList = [], updatedList = [], preservedList = [];
 
   for (const relPath of templateFiles) {
-    const templatePath = path.join(BUSINESS_TEMPLATE_DIR, relPath);
+    const templatePath = path.join(template.dir, relPath);
     const targetPath = path.join(targetAtrisDir, relPath);
     let templateContent;
     try { templateContent = fs.readFileSync(templatePath, 'utf-8'); } catch { continue; }
@@ -97,10 +237,22 @@ function syncBusinessCanonical(targetRoot, bizMeta, options = {}) {
     }
   }
 
+  const stateAddedList = ensureWorkspaceStateFiles(targetRoot, params, { dryRun });
+
+  // Skills: sync the canonical skill set from atris-cli package into the
+  // customer workspace. Business-starter template ships skill infra (README,
+  // folders) but skill files live in atris-cli/atris/skills/ — single source
+  // of truth. Any new skill (e.g. AEO) auto-propagates to every customer.
+  let skillsUpdated = 0;
+  if (!dryRun) {
+    skillsUpdated = syncPackageSkills(targetAtrisDir, { verbose: false });
+  }
+
   console.log(`  Added:     ${added}`);
   console.log(`  Updated:   ${updated} ${force ? '' : '(--force to enable)'}`);
   console.log(`  Preserved: ${preserved} (existing customizations kept)`);
   console.log(`  Skipped:   ${skipped} (already match template)`);
+  console.log(`  Skills:    ${skillsUpdated} updated from atris-cli/atris/skills/`);
   console.log('');
 
   if (addedList.length > 0) {
@@ -115,10 +267,15 @@ function syncBusinessCanonical(targetRoot, bizMeta, options = {}) {
     if (updatedList.length > 15) console.log(`    ... +${updatedList.length - 15} more`);
     console.log('');
   }
+  if (stateAddedList.length > 0) {
+    console.log('  State files:');
+    stateAddedList.forEach(p => console.log(`    + ${p}`));
+    console.log('');
+  }
 
   if (dryRun) {
     console.log('  (--dry-run, no changes made)');
-  } else if (added === 0 && updated === 0) {
+  } else if (added === 0 && updated === 0 && stateAddedList.length === 0) {
     ensureWikiScaffold(targetRoot);
     console.log('  ✓ Already up to date');
   } else {
@@ -127,13 +284,22 @@ function syncBusinessCanonical(targetRoot, bizMeta, options = {}) {
   }
 }
 
+function syncBusinessCanonical(targetRoot, bizMeta, options = {}) {
+  return syncWorkspaceTemplate(targetRoot, bizMeta, {
+    ...options,
+    templateName: options.templateName || bizMeta.workspace_template || 'business',
+  });
+}
+
 function syncAtris() {
   // Business mode detection: if .atris/business.json exists, use canonical templates
   const bizFile = path.join(process.cwd(), '.atris', 'business.json');
   if (fs.existsSync(bizFile)) {
     try {
       const bizMeta = JSON.parse(fs.readFileSync(bizFile, 'utf8'));
-      return syncBusinessCanonical(process.cwd(), bizMeta);
+      return syncWorkspaceTemplate(process.cwd(), bizMeta, {
+        templateName: bizMeta.workspace_template || 'business',
+      });
     } catch (e) {
       console.error(`✗ Failed to read .atris/business.json: ${e.message}`);
       process.exit(1);
@@ -241,80 +407,8 @@ function syncAtris() {
     console.log('✓ Migrated TASK_CONTEXTS.md to TODO.md');
   }
 
-  // Sync all skills from package to user's project
-  const packageSkillsDir = path.join(__dirname, '..', 'atris', 'skills');
-  const userSkillsDir = path.join(targetDir, 'skills');
-  const claudeSkillsBaseDir = path.join(process.cwd(), '.claude', 'skills');
-
-  if (fs.existsSync(packageSkillsDir)) {
-    // Ensure directories exist
-    if (!fs.existsSync(userSkillsDir)) {
-      fs.mkdirSync(userSkillsDir, { recursive: true });
-    }
-    if (!fs.existsSync(claudeSkillsBaseDir)) {
-      fs.mkdirSync(claudeSkillsBaseDir, { recursive: true });
-    }
-
-    // Get all skill folders from package
-    const skillFolders = fs.readdirSync(packageSkillsDir).filter(f => {
-      const skillPath = path.join(packageSkillsDir, f);
-      return fs.statSync(skillPath).isDirectory();
-    });
-
-    for (const skill of skillFolders) {
-      const srcSkillDir = path.join(packageSkillsDir, skill);
-      const destSkillDir = path.join(userSkillsDir, skill);
-      const symlinkPath = path.join(claudeSkillsBaseDir, skill);
-
-      // Recursive sync function for skills (handles subdirs like hooks/)
-      const syncRecursive = (src, dest, skillName, basePath = '') => {
-        if (!fs.existsSync(dest)) {
-          fs.mkdirSync(dest, { recursive: true });
-        }
-        const entries = fs.readdirSync(src);
-        for (const entry of entries) {
-          const srcPath = path.join(src, entry);
-          const destPath = path.join(dest, entry);
-          const relPath = basePath ? `${basePath}/${entry}` : entry;
-
-          if (fs.statSync(srcPath).isDirectory()) {
-            syncRecursive(srcPath, destPath, skillName, relPath);
-          } else {
-            const srcContent = fs.readFileSync(srcPath, 'utf8');
-            const destContent = fs.existsSync(destPath) ? fs.readFileSync(destPath, 'utf8') : '';
-            if (srcContent !== destContent) {
-              fs.writeFileSync(destPath, srcContent);
-              // Preserve executable permission for shell scripts
-              if (entry.endsWith('.sh')) {
-                fs.chmodSync(destPath, 0o755);
-              }
-              console.log(`✓ Updated atris/skills/${skillName}/${relPath}`);
-              updated++;
-            }
-          }
-        }
-      };
-
-      syncRecursive(srcSkillDir, destSkillDir, skill);
-
-      // Create symlink if doesn't exist
-      if (!fs.existsSync(symlinkPath)) {
-        const relativePath = path.join('..', '..', 'atris', 'skills', skill);
-        try {
-          fs.symlinkSync(relativePath, symlinkPath);
-          console.log(`✓ Linked .claude/skills/${skill}`);
-        } catch (e) {
-          // Fallback: copy instead of symlink
-          fs.mkdirSync(symlinkPath, { recursive: true });
-          const skillFile = path.join(destSkillDir, 'SKILL.md');
-          if (fs.existsSync(skillFile)) {
-            fs.copyFileSync(skillFile, path.join(symlinkPath, 'SKILL.md'));
-          }
-          console.log(`✓ Copied .claude/skills/${skill} (symlink failed)`);
-        }
-      }
-    }
-  }
+  // Sync all skills from package to user's project via shared helper.
+  updated += syncPackageSkills(targetDir, { verbose: true });
 
   // Update .claude/skills/atris/SKILL.md (legacy - now handled above, keeping for compatibility)
   const claudeSkillsDir = path.join(process.cwd(), '.claude', 'skills', 'atris');
@@ -571,4 +665,195 @@ function syncSkills({ silent = false } = {}) {
   return updated;
 }
 
-module.exports = { syncAtris, syncSkills, syncBusinessCanonical };
+/**
+ * Discover atris-managed projects under a root directory.
+ * A project is any directory whose immediate child `atris/` folder contains `atris.md`.
+ * Skips noise: node_modules, .git, .claude, dist, build, _archive, worktrees.
+ */
+function _findAtrisProjects(rootDir, maxDepth = 8) {
+  const skip = new Set([
+    'node_modules', '.git', '.claude', '.next', 'dist', 'build',
+    '_archive', 'worktrees', '.codex', '.venv', 'venv', '__pycache__',
+  ]);
+  const found = [];
+  function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    const atrisMd = path.join(dir, 'atris', 'atris.md');
+    if (fs.existsSync(atrisMd)) found.push(dir);
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (skip.has(e.name)) continue;
+      if (e.name.startsWith('.')) continue;
+      walk(path.join(dir, e.name), depth + 1);
+    }
+  }
+  walk(path.resolve(rootDir), 0);
+  return found;
+}
+
+/**
+ * Sync canonical atris.md (and core docs) across every atris project under cwd.
+ * Walks the subtree, finds every `atris/atris.md`, copies the package source.
+ *
+ * Flags: --dry-run (preview only), --yes/--force (skip confirm).
+ * Skips business workspaces (they use syncWorkspaceTemplate via syncAtris).
+ */
+// Canonical files shipped from the package root. Must match syncAtris's filesToSync.
+const SYNC_ALL_FILES = [
+  { source: 'atris.md', target: 'atris.md' },
+  { source: 'atris/atrisDev.md', target: 'atrisDev.md' },
+  { source: 'PERSONA.md', target: 'PERSONA.md' },
+  { source: 'GETTING_STARTED.md', target: 'GETTING_STARTED.md' },
+  { source: 'atris/CLAUDE.md', target: 'CLAUDE.md' },
+];
+
+/**
+ * Pure function: build the sync plan for every atris project under root.
+ * No console output, no writes. Returns { projects, plan } for inspection.
+ * Plan entries: { projectRoot, isBusiness, isCustomized, changes }.
+ *
+ * Exported for tests — the production syncAtrisAll wraps this.
+ */
+function buildSyncAllPlan({ root, pkgRoot, filesToSync = SYNC_ALL_FILES } = {}) {
+  const projects = _findAtrisProjects(root);
+  const plan = [];
+  for (const projectRoot of projects) {
+    const atrisDir = path.join(projectRoot, 'atris');
+    const bizFile = path.join(projectRoot, '.atris', 'business.json');
+    const isSelf = path.resolve(projectRoot) === path.resolve(pkgRoot);
+    const isInBusinessDir = projectRoot.split(path.sep).includes('atris-business');
+    let isBusiness = isInBusinessDir || (fs.existsSync(bizFile) && !isSelf);
+    if (isBusiness && !isInBusinessDir) {
+      try {
+        const head = fs.readFileSync(path.join(atrisDir, 'atris.md'), 'utf8').slice(0, 300);
+        if (!/^#\s+Atris Boot Protocol/i.test(head)) isBusiness = false;
+      } catch {}
+    }
+    let isCustomized = false;
+    if (!isSelf && !isBusiness) {
+      try {
+        const head = fs.readFileSync(path.join(atrisDir, 'atris.md'), 'utf8').slice(0, 500);
+        const isNewCanonical = /^#\s+atris\s*\n\nAtris exists because/m.test(head);
+        const isOldGeneric = /^#\s+atris\.md\s*\n\n>\s+Drop this file anywhere/m.test(head);
+        if (!isNewCanonical && !isOldGeneric) isCustomized = true;
+      } catch {}
+    }
+    const changes = [];
+    for (const { source, target } of filesToSync) {
+      const sourceFile = path.join(pkgRoot, source);
+      const targetFile = path.join(atrisDir, target);
+      if (!fs.existsSync(sourceFile)) continue;
+      const newContent = fs.readFileSync(sourceFile, 'utf8');
+      const currentContent = fs.existsSync(targetFile) ? fs.readFileSync(targetFile, 'utf8') : '';
+      if (currentContent !== newContent) changes.push(target);
+    }
+    plan.push({ projectRoot, isBusiness, isCustomized, changes });
+  }
+  return { projects, plan };
+}
+
+function syncAtrisAll({ dryRun = false, force = false } = {}) {
+  const root = process.cwd();
+  const pkgRoot = path.join(__dirname, '..');
+
+  console.log('');
+  console.log(`Scanning ${root} for atris projects...`);
+
+  const filesToSync = SYNC_ALL_FILES;
+  const { projects, plan: initialPlan } = buildSyncAllPlan({ root, pkgRoot, filesToSync });
+
+  if (projects.length === 0) {
+    console.log('No atris projects found under current directory.');
+    return;
+  }
+
+  const plan = initialPlan;
+
+  // Report.
+  console.log(`Found ${projects.length} project(s).`);
+  console.log('');
+  let wouldUpdate = 0, unchanged = 0, skipped = 0;
+  for (const p of plan) {
+    const rel = path.relative(root, p.projectRoot) || '.';
+    if (p.isBusiness) {
+      console.log(`  ⏭  ${rel} (business workspace — run "atris update" in that dir)`);
+      skipped++;
+    } else if (p.isCustomized) {
+      console.log(`  ⏭  ${rel} (customized atris.md — review manually)`);
+      skipped++;
+    } else if (p.changes.length === 0) {
+      console.log(`  ·  ${rel} (up to date)`);
+      unchanged++;
+    } else {
+      console.log(`  →  ${rel} — ${p.changes.length} file(s): ${p.changes.join(', ')}`);
+      wouldUpdate++;
+    }
+  }
+  console.log('');
+
+  if (dryRun) {
+    console.log(`Dry run: ${wouldUpdate} project(s) would update, ${unchanged} unchanged, ${skipped} skipped.`);
+    return;
+  }
+
+  if (wouldUpdate === 0) {
+    console.log('Nothing to sync.');
+    return;
+  }
+
+  // Confirm unless forced.
+  if (!force) {
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      rl.question(`Sync ${wouldUpdate} project(s)? (y/N) `, (answer) => {
+        rl.close();
+        if (!/^y(es)?$/i.test(answer.trim())) {
+          console.log('Cancelled.');
+          resolve();
+          return;
+        }
+        _executeSyncAll(plan, pkgRoot, filesToSync, root);
+        resolve();
+      });
+    });
+  }
+
+  _executeSyncAll(plan, pkgRoot, filesToSync, root);
+}
+
+function _executeSyncAll(plan, pkgRoot, filesToSync, root) {
+  let updated = 0;
+  for (const p of plan) {
+    if (p.isBusiness || p.isCustomized || p.changes.length === 0) continue;
+    const atrisDir = path.join(p.projectRoot, 'atris');
+    for (const { source, target } of filesToSync) {
+      const sourceFile = path.join(pkgRoot, source);
+      const targetFile = path.join(atrisDir, target);
+      if (!fs.existsSync(sourceFile)) continue;
+      const newContent = fs.readFileSync(sourceFile, 'utf8');
+      const currentContent = fs.existsSync(targetFile) ? fs.readFileSync(targetFile, 'utf8') : '';
+      if (currentContent === newContent) continue;
+      fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+      fs.copyFileSync(sourceFile, targetFile);
+    }
+    updated++;
+  }
+  console.log('');
+  console.log(`✓ Synced ${updated} project(s).`);
+}
+
+module.exports = {
+  syncAtris,
+  syncAtrisAll,
+  buildSyncAllPlan,
+  SYNC_ALL_FILES,
+  syncSkills,
+  syncBusinessCanonical,
+  syncWorkspaceTemplate,
+  resolveWorkspaceTemplate,
+  ensureWorkspaceStateFiles,
+};

package/commands/verify.js

@@ -444,11 +444,11 @@ function verifyChange(cwd, change) {
     };
   }
 
-  // Generic check - always pass (can't verify without specifics)
+  // No specific check possible — refuse to auto-pass
   return {
-    pass: true,
+    pass: false,
     description: change.description,
-    details: 'Manual verification recommended'
+    details: 'No verifiable check for this change type. Add an explicit verify command.'
   };
 }
 
@@ -479,6 +479,55 @@ function checkMapForFiles(atrisDir, changes) {
   return { documented: documented >= fileChanges.length / 2 };
 }
 
+/**
+ * atris verify <slug> --section <name>
+ *
+ * Extract the first fenced bash block under "## <name>" in
+ * atris/features/<slug>/validate.md and execute it. Returns the exit code
+ * from bash. Used as the machine-checkable Verify command in TODO.md tasks.
+ *
+ * Contract (per atris.md): the rubric must be read-only, deterministic, and
+ * reference only the working tree. The command fails loudly when the rubric
+ * or section is missing — that prevents silent "trivial Verify" regressions.
+ */
+function verifyRubric(slug, section, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  if (!slug || !section) {
+    console.error('Usage: atris verify <feature-slug> --section <name>');
+    return 2;
+  }
+  const validateFile = path.join(cwd, 'atris', 'features', slug, 'validate.md');
+  if (!fs.existsSync(validateFile)) {
+    console.error(`✗ No rubric at ${path.relative(cwd, validateFile)}`);
+    return 2;
+  }
+  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 pattern = new RegExp(
+    `^##\\s+${escaped}\\s*$[\\s\\S]*?\\n\`\`\`(?:bash|sh)?\\s*\\n([\\s\\S]*?)\\n\`\`\``,
+    'mi'
+  );
+  const match = content.match(pattern);
+  if (!match) {
+    console.error(`✗ No fenced bash block under "## ${section}" in ${path.relative(cwd, validateFile)}`);
+    return 2;
+  }
+  const script = match[1];
+  const os = require('os');
+  const tmpFile = path.join(os.tmpdir(), `atris-verify-${Date.now()}-${Math.floor(Math.random() * 1e6)}.sh`);
+  fs.writeFileSync(tmpFile, `#!/usr/bin/env bash\nset -e\n${script}\n`);
+  fs.chmodSync(tmpFile, 0o755);
+  try {
+    const proc = spawnSync('bash', [tmpFile], { cwd, stdio: opts.silent ? 'pipe' : 'inherit' });
+    return typeof proc.status === 'number' ? proc.status : 1;
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch {}
+  }
+}
+
 module.exports = {
-  verifyAtris
+  verifyAtris,
+  verifyRubric
 };