atris 2.6.2 → 3.0.0

package/commands/workflow.js

@@ -2,6 +2,45 @@ const fs = require('fs');
 const path = require('path');
 const { getLogPath } = require('../lib/journal');
 
+function wrapWorkflowText(text, width = 76) {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!normalized) return [''];
+
+  const words = normalized.split(' ');
+  const lines = [];
+  let current = '';
+
+  for (const word of words) {
+    if (!current) {
+      current = word;
+      continue;
+    }
+    if ((current + ' ' + word).length <= width) {
+      current += ' ' + word;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+
+  if (current) lines.push(current);
+  return lines;
+}
+
+function printWorkflowBrief(lines) {
+  console.log('');
+  for (const line of lines) {
+    if (!line) {
+      console.log('');
+      continue;
+    }
+    for (const wrapped of wrapWorkflowText(line)) {
+      console.log(wrapped);
+    }
+  }
+  console.log('');
+}
+
 async function planAtris(userInput = null) {
   const { loadConfig } = require('../utils/config');
   const { loadCredentials } = require('../utils/auth');
@@ -78,7 +117,10 @@ async function planAtris(userInput = null) {
   const inboxCount = inboxContext
     ? inboxContext
         .split('\n')
-        .filter((line) => line.trim().startsWith('-'))
+        .filter((line) => {
+          const t = line.trim();
+          return t.startsWith('- ') && t.length > 2;
+        })
         .length
     : 0;
 
@@ -122,6 +164,20 @@ async function planAtris(userInput = null) {
   const lessonsRef = fs.existsSync(lessonsPath) ? path.relative(process.cwd(), lessonsPath) : null;
   console.log(`- Lessons: ${lessonsRef || 'atris/lessons.md (none yet)'}`);
   console.log(`- Journal (today): ${journalPath}`);
+
+  // Show top learnings if available
+  try {
+    const { loadLearnings } = require('../lib/learnings');
+    const learnings = loadLearnings().filter(e => e._effectiveConfidence >= 7 && e.insight !== '[REMOVED]').slice(0, 3);
+    if (learnings.length > 0) {
+      console.log('');
+      console.log('🧠 Prior learnings (high confidence):');
+      for (const l of learnings) {
+        console.log(`  [${l._effectiveConfidence}/10] ${l.type}/${l.key}: ${l.insight}`);
+      }
+    }
+  } catch {}
+
   console.log('');
   console.log(`📥 Inbox items: ${inboxCount}`);
   console.log('');
@@ -442,6 +498,20 @@ async function doAtris() {
   console.log(`- MAP: ${mapDisplay}`);
   console.log(`- TODO: ${taskSourcePath || 'atris/TODO.md (missing)'}`);
   console.log(`- Features index: ${featuresReadmeRef || 'atris/features/README.md (missing)'}`);
+
+  // Show top learnings during execution
+  try {
+    const { loadLearnings } = require('../lib/learnings');
+    const learnings = loadLearnings().filter(e => e._effectiveConfidence >= 7 && e.insight !== '[REMOVED]').slice(0, 3);
+    if (learnings.length > 0) {
+      console.log('');
+      console.log('🧠 Prior learnings (apply during build):');
+      for (const l of learnings) {
+        console.log(`  [${l._effectiveConfidence}/10] ${l.type}/${l.key}: ${l.insight}`);
+      }
+    }
+  } catch {}
+
   console.log('');
 
   const backlogCount = workspaceSummary && Array.isArray(workspaceSummary.backlogTasks)
@@ -766,64 +836,89 @@ async function reviewAtris() {
     }
   }
 
-  console.log('');
-  console.log('┌─────────────────────────────────────────────────────────────┐');
-  console.log('│ Atris Review — Validator Agent Activated                    │');
-  console.log('└─────────────────────────────────────────────────────────────┘');
-  console.log('');
-
-  console.log('📁 CONTEXT FILES (agent should read):');
-  console.log(`- Validator spec: ${validatorPath}`);
-  console.log(`- Testing guide: ${testingGuideRef || '(none found)'}`);
-  console.log(`- Persona: ${personaRef || 'atris/PERSONA.md (missing)'}`);
   const mapDisplay = mapPath
     ? `${mapPath}${mapIsPlaceholder ? ' (placeholder — generate first)' : ''}`
     : 'atris/MAP.md (missing)';
-  console.log(`- MAP: ${mapDisplay}`);
-  console.log(`- TODO: ${todoPathRef || 'atris/TODO.md (missing)'}`);
-  console.log(`- Journal (today): ${journalPathRef}`);
-  console.log(`- Features index: ${featuresReadmeRef || 'atris/features/README.md (missing)'}`);
-  console.log('');
 
-  console.log(`🧪 Feature validate scripts found: ${featureValidateRefs.length}`);
-  if (featureValidateRefs.length > 0) {
-    featureValidateRefs.slice(0, 3).forEach((ref) => console.log(`- ${ref}`));
-    if (featureValidateRefs.length > 3) {
-      console.log(`- ... (+${featureValidateRefs.length - 3} more)`);
+  if (showFull) {
+    console.log('');
+    console.log('┌─────────────────────────────────────────────────────────────┐');
+    console.log('│ Atris Review — Validator Agent Activated                    │');
+    console.log('└─────────────────────────────────────────────────────────────┘');
+    console.log('');
+
+    console.log('📁 CONTEXT FILES (agent should read):');
+    console.log(`- Validator spec: ${validatorPath}`);
+    console.log(`- Testing guide: ${testingGuideRef || '(none found)'}`);
+    console.log(`- Persona: ${personaRef || 'atris/PERSONA.md (missing)'}`);
+    console.log(`- MAP: ${mapDisplay}`);
+    console.log(`- TODO: ${todoPathRef || 'atris/TODO.md (missing)'}`);
+    console.log(`- Journal (today): ${journalPathRef}`);
+    console.log(`- Features index: ${featuresReadmeRef || 'atris/features/README.md (missing)'}`);
+    console.log('');
+
+    console.log(`🧪 Feature validate scripts found: ${featureValidateRefs.length}`);
+    if (featureValidateRefs.length > 0) {
+      featureValidateRefs.slice(0, 3).forEach((ref) => console.log(`- ${ref}`));
+      if (featureValidateRefs.length > 3) {
+        console.log(`- ... (+${featureValidateRefs.length - 3} more)`);
+      }
     }
-  }
-  console.log('');
+    console.log('');
 
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('📋 COPY/PASTE PROMPT FOR YOUR CODING AGENT:');
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('');
-  console.log('You are the Validator.');
-  console.log('');
-  console.log('Read these files:');
-  console.log(`- ${validatorPath}`);
-  if (testingGuideRef) console.log(`- ${testingGuideRef}`);
-  if (personaRef) console.log(`- ${personaRef}`);
-  if (mapPath) console.log(`- ${mapPath}`);
-  if (todoPathRef) console.log(`- ${todoPathRef}`);
-  console.log(`- ${journalPathRef}`);
-  if (featuresReadmeRef) console.log(`- ${featuresReadmeRef}`);
-  console.log('');
-  if (!mapPath || mapIsPlaceholder) {
-    console.log('Note: If `atris/MAP.md` is missing or placeholder, generate it from `atris/atris.md` before validating file:line references.');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('📋 COPY/PASTE PROMPT FOR YOUR CODING AGENT:');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+  } else {
+    const readinessBits = [
+      `MAP is ${mapPath ? 'present' : 'missing'}`,
+      `TODO is ${todoPathRef ? 'present' : 'missing'}`,
+      `${featureValidateRefs.length} feature validate script${featureValidateRefs.length === 1 ? '' : 's'} ${featureValidateRefs.length === 1 ? 'is' : 'are'} queued`
+    ];
+    const decision = (mapPath && todoPathRef)
+      ? 'Decision: hold final approval until the validator run finishes.'
+      : 'Decision: hold. Review setup is incomplete and needs fixing first.';
+
+    printWorkflowBrief([
+      'I checked the review setup.',
+      readinessBits.join(', ') + '.',
+      '',
+      'This step prepares the validator. It does not mean the change has passed review yet.',
+      'Next I will run tests, walk each validate.md, and clear completed tasks out of TODO.',
+      '',
+      decision,
+      'Run `atris review --verbose` for the full prompt and appendix.'
+    ]);
+  }
+  if (showFull) {
+    console.log('You are the Validator.');
+    console.log('');
+    console.log('Read these files:');
+    console.log(`- ${validatorPath}`);
+    if (testingGuideRef) console.log(`- ${testingGuideRef}`);
+    if (personaRef) console.log(`- ${personaRef}`);
+    if (mapPath) console.log(`- ${mapPath}`);
+    if (todoPathRef) console.log(`- ${todoPathRef}`);
+    console.log(`- ${journalPathRef}`);
+    if (featuresReadmeRef) console.log(`- ${featuresReadmeRef}`);
+    console.log('');
+    if (!mapPath || mapIsPlaceholder) {
+      console.log('Note: If `atris/MAP.md` is missing or placeholder, generate it from `atris/atris.md` before validating file:line references.');
+      console.log('');
+    }
+    console.log('Workflow:');
+    console.log('1) Run the project test suite (follow TESTING_GUIDE if present).');
+    console.log('2) Execute any `atris/features/*/validate.md` scripts; if a step fails, fix + rerun.');
+    console.log('3) Clean TODO.md: delete completed tasks. Target state = 0.');
+    console.log('   If a task fails validation, move back to ## Backlog with note.');
+    console.log('4) Log to atris/team/validator/journal/YYYY-MM-DD.md');
+    console.log('   (Task, Result, Issues found, Learned)');
+    console.log('5) If anything surprised you, append to atris/lessons.md.');
+    console.log('');
+    console.log('Done when: ✅ All good. TODO.md clean. Ready for human testing.');
     console.log('');
   }
-  console.log('Workflow:');
-  console.log('1) Run the project test suite (follow TESTING_GUIDE if present).');
-  console.log('2) Execute any `atris/features/*/validate.md` scripts; if a step fails, fix + rerun.');
-  console.log('3) Clean TODO.md: delete completed tasks. Target state = 0.');
-  console.log('   If a task fails validation, move back to ## Backlog with note.');
-  console.log('4) Log to atris/team/validator/journal/YYYY-MM-DD.md');
-  console.log('   (Task, Result, Issues found, Learned)');
-  console.log('5) If anything surprised you, append to atris/lessons.md.');
-  console.log('');
-  console.log('Done when: ✅ All good. TODO.md clean. Ready for human testing.');
-  console.log('');
 
   if (showFull) {
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
@@ -851,13 +946,12 @@ async function reviewAtris() {
     }
   }
 
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('💡 Next: Run "atris do" to fix any issues, then "atris review" again');
-  if (!showFull) {
-    console.log('   Tip: `atris review --full` prints full spec/context for copy/paste.');
+  if (showFull) {
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('💡 Next: Run "atris do" to fix any issues, then "atris review" again');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
   }
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('');
   
   // Check execution mode
   if (executionMode === 'agent') {
@@ -981,19 +1075,25 @@ async function reviewAtris() {
     const hasHandoff = /## Handoff[\s\S]*?\*\*Context:\*\*/.test(journalContent);
 
     if (hasCompletions && !hasHandoff) {
-      console.log('');
-      console.log('┌─────────────────────────────────────────────────────────────┐');
-      console.log('│ 📝 SESSION HANDOFF                                          │');
-      console.log('├─────────────────────────────────────────────────────────────┤');
-      console.log('│ You have completions today. Write a handoff for next session│');
-      console.log('│                                                             │');
-      console.log('│ Add to ## Handoff section in today\'s journal:               │');
-      console.log('│   **Context:** [2 lines - what was accomplished]            │');
-      console.log('│   **Blockers:** [any issues hit, or "none"]                 │');
-      console.log('│   **Next:** [1 clear action for next session]               │');
-      console.log('│   **Learned:** [key insight or pattern discovered]          │');
-      console.log('└─────────────────────────────────────────────────────────────┘');
-      console.log('');
+      if (showFull) {
+        console.log('');
+        console.log('┌─────────────────────────────────────────────────────────────┐');
+        console.log('│ 📝 SESSION HANDOFF                                          │');
+        console.log('├─────────────────────────────────────────────────────────────┤');
+        console.log('│ You have completions today. Write a handoff for next session│');
+        console.log('│                                                             │');
+        console.log('│ Add to ## Handoff section in today\'s journal:               │');
+        console.log('│   **Context:** [2 lines - what was accomplished]            │');
+        console.log('│   **Blockers:** [any issues hit, or "none"]                 │');
+        console.log('│   **Next:** [1 clear action for next session]               │');
+        console.log('│   **Learned:** [key insight or pattern discovered]          │');
+        console.log('└─────────────────────────────────────────────────────────────┘');
+        console.log('');
+      } else {
+        console.log('');
+        console.log('you have completions today. add a ## Handoff block to the journal (context / blockers / next / learned).');
+        console.log('');
+      }
     }
   }
 
@@ -1001,10 +1101,14 @@ async function reviewAtris() {
   if (!process.stdin.isTTY) return;
 
   console.log('');
-  console.log('┌─────────────────────────────────────────────────────────────┐');
-  console.log('│ 💡 Any learnings?                                           │');
-  console.log('│ (Enter insight, or press Enter to skip)                     │');
-  console.log('└─────────────────────────────────────────────────────────────┘');
+  if (showFull) {
+    console.log('┌─────────────────────────────────────────────────────────────┐');
+    console.log('│ 💡 Any learnings?                                           │');
+    console.log('│ (Enter insight, or press Enter to skip)                     │');
+    console.log('└─────────────────────────────────────────────────────────────┘');
+  } else {
+    console.log('any learnings? (enter to skip)');
+  }
 
   const readline = require('readline');
   const rl = readline.createInterface({
@@ -1035,6 +1139,19 @@ async function reviewAtris() {
           console.log('');
           console.log(`✓ Logged to journal: ${learning}`);
         }
+
+        // Also log to structured learnings (if learnings module exists)
+        try {
+          const { addLearning } = require('../lib/learnings');
+          const insight = answer.trim();
+          // Auto-classify: starts with "don't" or "never" or "avoid" → pitfall, else pattern
+          const type = /^(don't|never|avoid|watch out|careful)/i.test(insight) ? 'pitfall' : 'pattern';
+          const key = insight.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).slice(0, 4).join('-');
+          addLearning({ type, key, insight, confidence: 7, source: 'review', files: [] });
+          console.log(`✓ Saved to learnings: [7/10] ${type}/${key}`);
+        } catch {
+          // learnings module not available — skip silently
+        }
       }
 
       console.log('');

package/commands/workspace-clean.js

@@ -63,7 +63,7 @@ async function cleanWorkspace() {
     workspaceId = businesses[slug].workspace_id;
     businessName = businesses[slug].name || slug;
   } else {
-    const listResult = await apiRequestJson('/businesses/', { method: 'GET', token: creds.token });
+    const listResult = await apiRequestJson('/business/', { method: 'GET', token: creds.token });
     if (!listResult.ok) {
       console.error(`Failed to fetch businesses: ${listResult.error || listResult.status}`);
       process.exit(1);
@@ -100,7 +100,7 @@ async function cleanWorkspace() {
   console.log(`Scanning ${businessName}...`);
 
   const result = await apiRequestJson(
-    `/businesses/${businessId}/workspaces/${workspaceId}/snapshot?include_content=false`,
+    `/business/${businessId}/workspaces/${workspaceId}/snapshot?include_content=false`,
     { method: 'GET', token: creds.token, timeoutMs: 60000 }
   );
 
@@ -220,7 +220,7 @@ async function cleanWorkspace() {
     const batch = filesToDelete.slice(i, i + BATCH_SIZE);
 
     const syncResult = await apiRequestJson(
-      `/businesses/${businessId}/workspaces/${workspaceId}/sync`,
+      `/business/${businessId}/workspaces/${workspaceId}/sync`,
       {
         method: 'POST',
         token: creds.token,

package/lib/endstate.js

@@ -0,0 +1,259 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const RESULTS_HEADER = 'timestamp\ttrack\trepo\ttask\tstatus\tscore\treviewed\ttests\tartifacts\tinterventions\tnotes\n';
+
+function readTextIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function runGit(repoDir, args) {
+  if (!repoDir || !fs.existsSync(repoDir)) return null;
+  const result = spawnSync('git', ['-C', repoDir, ...args], { encoding: 'utf8' });
+  if (result.error || result.status !== 0) return null;
+  return (result.stdout || '').trim();
+}
+
+function getGitHead(repoDir) {
+  return runGit(repoDir, ['rev-parse', 'HEAD']);
+}
+
+function collectChangedFiles(repoDir, beforeSha, afterSha, prefix = '') {
+  const changed = new Set();
+
+  const addLines = (output) => {
+    if (!output) return;
+    output.split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .forEach((line) => changed.add(prefix + line));
+  };
+
+  if (beforeSha && afterSha && beforeSha !== afterSha) {
+    addLines(runGit(repoDir, ['diff', '--name-only', `${beforeSha}..${afterSha}`]));
+  }
+
+  addLines(runGit(repoDir, ['diff', '--name-only']));
+  addLines(runGit(repoDir, ['diff', '--cached', '--name-only']));
+  addLines(runGit(repoDir, ['ls-files', '--others', '--exclude-standard']));
+
+  return [...changed].sort();
+}
+
+function buildRunId(track) {
+  return `${new Date().toISOString().replace(/[:.]/g, '-')}-${track}`;
+}
+
+function buildWikiArtifact(beforeText, afterText) {
+  if (!beforeText && !afterText) {
+    return { status: 'missing' };
+  }
+
+  if (beforeText === afterText) {
+    return { status: 'not_applicable', before: beforeText || '', after: afterText || '' };
+  }
+
+  return { status: 'updated', before: beforeText || '', after: afterText || '' };
+}
+
+function summarizeReview(text) {
+  const clean = (text || '').trim().replace(/\s+/g, ' ');
+  if (!clean) return 'no review output captured';
+  return clean.length > 400 ? `${clean.slice(0, 397)}...` : clean;
+}
+
+function inferTestResults(text) {
+  const lines = (text || '').split('\n');
+  const matches = [];
+
+  for (const line of lines) {
+    if (!/(npm|pnpm|yarn|node\s+--test|pytest|python\s+-m|cargo test|go test)/i.test(line)) {
+      continue;
+    }
+
+    let status = 'not_run';
+    if (/\b(pass|passed|green|clean)\b/i.test(line)) status = 'pass';
+    if (/\b(fail|failed|error)\b/i.test(line)) status = 'fail';
+
+    matches.push({
+      command: line.trim(),
+      status,
+    });
+  }
+
+  if (matches.length > 0) return matches;
+
+  return [{
+    command: '(no explicit test command captured)',
+    status: 'not_run',
+  }];
+}
+
+function scoreEndstateArtifact(artifact) {
+  const breakdown = {
+    reviewed_completion: artifact.review?.status === 'pass' ? 40 : 0,
+    test_outcome: 0,
+    artifact_completeness: 0,
+    wiki_memory: artifact.wiki?.status === 'missing' ? 0 : 10,
+    operator_load: Math.max(0, 10 - ((artifact.interventions?.count || 0) * 2)),
+  };
+
+  const tests = Array.isArray(artifact.tests) ? artifact.tests : [];
+  const executed = tests.filter((test) => test.status !== 'not_run');
+  if (executed.length > 0) {
+    const passed = executed.filter((test) => test.status === 'pass').length;
+    breakdown.test_outcome = Math.round((passed / executed.length) * 25);
+  }
+
+  const required = [
+    'run_id',
+    'track',
+    'repo_commits',
+    'task_brief',
+    'prompt_context',
+    'changed_files',
+    'tests',
+    'review',
+    'wiki',
+    'elapsed_seconds',
+    'interventions',
+  ];
+  const present = required.filter((key) => Object.prototype.hasOwnProperty.call(artifact, key)).length;
+  breakdown.artifact_completeness = Math.round((present / required.length) * 15);
+
+  const total = Object.values(breakdown).reduce((sum, value) => sum + value, 0);
+  return { total, breakdown };
+}
+
+function getArtifactScore(artifact) {
+  if (typeof artifact?.score === 'number') return artifact.score;
+  return scoreEndstateArtifact(artifact).total;
+}
+
+function getReviewRank(artifact) {
+  const status = artifact?.review?.status;
+  if (status === 'pass') return 2;
+  if (status === 'draft') return 1;
+  return 0;
+}
+
+function readLatestArtifact(packDir) {
+  const artifactsDir = path.join(packDir, 'artifacts');
+  if (!fs.existsSync(artifactsDir)) {
+    throw new Error(`No artifacts found at ${artifactsDir}`);
+  }
+
+  const files = fs.readdirSync(artifactsDir)
+    .filter((file) => file.endsWith('.json'))
+    .sort();
+
+  if (files.length === 0) {
+    throw new Error(`No artifact JSON files found at ${artifactsDir}`);
+  }
+
+  const filePath = path.join(artifactsDir, files[files.length - 1]);
+  return {
+    filePath,
+    artifact: JSON.parse(fs.readFileSync(filePath, 'utf8')),
+  };
+}
+
+function compareEndstateArtifacts(baselineEntry, stackEntry) {
+  const baselineScore = getArtifactScore(baselineEntry.artifact);
+  const stackScore = getArtifactScore(stackEntry.artifact);
+  const baselineReview = getReviewRank(baselineEntry.artifact);
+  const stackReview = getReviewRank(stackEntry.artifact);
+
+  const stackWins = stackScore > baselineScore && stackReview >= baselineReview;
+  const leader = stackScore === baselineScore
+    ? 'tie'
+    : (stackScore > baselineScore ? 'stack' : 'baseline');
+
+  let reason = '';
+  if (stackWins) {
+    reason = `Stack leads ${stackScore} to ${baselineScore} and does not lose reviewed completion.`;
+  } else if (stackScore === baselineScore) {
+    reason = `Scores are tied at ${stackScore}/100. The stack must beat the baseline on total score.`;
+  } else if (stackScore < baselineScore) {
+    reason = `Baseline leads ${baselineScore} to ${stackScore}. The stack must beat the baseline on total score.`;
+  } else {
+    reason = 'The stack improved total score but lost reviewed completion, so it does not clear the Level 1 rule.';
+  }
+
+  return {
+    winner: stackWins ? 'stack' : 'none',
+    leader,
+    reason,
+    baselineScore,
+    stackScore,
+  };
+}
+
+function ensureResultsFile(resultsPath) {
+  if (!fs.existsSync(resultsPath)) {
+    fs.writeFileSync(resultsPath, RESULTS_HEADER, 'utf8');
+    return;
+  }
+
+  const content = fs.readFileSync(resultsPath, 'utf8');
+  if (!content.trim()) {
+    fs.writeFileSync(resultsPath, RESULTS_HEADER, 'utf8');
+  }
+}
+
+function toTsvField(value) {
+  return String(value ?? '')
+    .replace(/\t/g, ' ')
+    .replace(/\r?\n/g, ' ')
+    .trim();
+}
+
+function appendResultsRow(resultsPath, artifactPath, artifact, score) {
+  ensureResultsFile(resultsPath);
+
+  const tests = Array.isArray(artifact.tests) ? artifact.tests : [];
+  const passed = tests.filter((test) => test.status === 'pass').length;
+  const ran = tests.filter((test) => test.status !== 'not_run').length;
+
+  const row = [
+    new Date().toISOString(),
+    artifact.track,
+    'atris-cli+atrisos-backend',
+    artifact.task_brief,
+    artifact.review?.status || 'draft',
+    score.total,
+    artifact.review?.status === 'pass' ? 'yes' : 'no',
+    ran > 0 ? `${passed}/${ran} pass` : 'not-run',
+    path.relative(path.dirname(resultsPath), artifactPath),
+    artifact.interventions?.count || 0,
+    artifact.notes || '',
+  ].map(toTsvField).join('\t');
+
+  fs.appendFileSync(resultsPath, `${row}\n`, 'utf8');
+}
+
+function writeArtifact(packDir, artifact) {
+  const artifactsDir = path.join(packDir, 'artifacts');
+  fs.mkdirSync(artifactsDir, { recursive: true });
+  const filePath = path.join(artifactsDir, `${artifact.run_id}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(artifact, null, 2), 'utf8');
+  return filePath;
+}
+
+module.exports = {
+  appendResultsRow,
+  buildRunId,
+  buildWikiArtifact,
+  compareEndstateArtifacts,
+  collectChangedFiles,
+  getArtifactScore,
+  getGitHead,
+  inferTestResults,
+  readLatestArtifact,
+  readTextIfExists,
+  scoreEndstateArtifact,
+  summarizeReview,
+  writeArtifact,
+};