atris 3.2.0 → 3.5.0

package/commands/sync.js

@@ -48,6 +48,79 @@ function _substituteParams(content, params) {
     .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') {
@@ -58,7 +131,7 @@ function resolveWorkspaceTemplate(templateName = 'business') {
   return { key: normalized, ...template };
 }
 
-function _ensureWorkspaceState(targetRoot, params, options = {}) {
+function ensureWorkspaceStateFiles(targetRoot, params, options = {}) {
   const dryRun = options.dryRun === true;
   const metaDir = path.join(targetRoot, '.atris');
   const stateDir = path.join(metaDir, 'state');
@@ -164,12 +237,22 @@ function syncWorkspaceTemplate(targetRoot, bizMeta, options = {}) {
     }
   }
 
-  const stateAddedList = _ensureWorkspaceState(targetRoot, params, { dryRun });
+  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) {
@@ -324,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');
@@ -654,10 +665,195 @@ function syncSkills({ silent = false } = {}) {
   return updated;
 }
 
+/**
+ * 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

@@ -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
 };

package/commands/wiki.js

@@ -8,10 +8,14 @@ const {
   PRIVATE_WIKI_ROOT,
   getWikiRoot,
   ensureWikiScaffold,
+  ensureContextScaffold,
   findLocalWikiDir,
+  stageWikiIngest,
   buildIngestPrompt,
   buildQueryPrompt,
   buildLintPrompt,
+  writeWikiStatus,
+  appendWikiLog,
 } = require('../lib/wiki');
 
 function autoDetectSlug() {
@@ -170,9 +174,30 @@ async function wikiIngest(mode, slug, sourceValue) {
   if (mode === 'local' || mode === 'private') {
     const wikiMode = mode === 'private' ? 'private' : 'public';
     const wikiDir = ensureWikiScaffold(process.cwd(), wikiMode);
-    printLocalPrompt(mode === 'private' ? 'Private wiki ingest' : 'Local wiki ingest', buildIngestPrompt(sourceValue, wikiMode), getWikiRoot(wikiMode), [
+    const contextDir = ensureContextScaffold(process.cwd(), wikiMode);
+    const staged = stageWikiIngest(process.cwd(), sourceValue, wikiMode);
+    writeWikiStatus(process.cwd(), {
+      health: `ingest staged from ${staged.packPath}`,
+      nextMove: `compile ${staged.promptSource} into ${getWikiRoot(wikiMode)}`,
+    }, wikiMode, { lastIngest: staged.manifest.ingested_at });
+    appendWikiLog(
+      process.cwd(),
+      `${staged.manifest.entries.length} source item(s) staged from ${sourceValue}`,
+      [
+        `context ${contextDir}`,
+        `pack ${staged.packPath}`,
+        `manifest ${staged.manifestPath}`,
+        ...staged.manifest.entries.map((entry) => `${entry.kind} ${entry.staged}`),
+      ],
+      wikiMode,
+      'INGEST'
+    );
+    printLocalPrompt(mode === 'private' ? 'Private wiki ingest' : 'Local wiki ingest', buildIngestPrompt(staged.promptSource, wikiMode), getWikiRoot(wikiMode), [
       `Wiki dir: ${wikiDir}`,
-      `Sources: ${sourceValue}`,
+      `Context dir: ${contextDir}`,
+      `Pack: ${staged.packPath}`,
+      `Manifest: ${staged.manifestPath}`,
+      `Sources: ${staged.promptSource}`,
     ]);
     return;
   }

package/lib/file-ops.js

@@ -1,7 +1,11 @@
 const fs = require('fs');
 const path = require('path');
 
-// Log file operations
+/**
+ * Get the path components for a journal log file.
+ * @param {string} [dateStr] - Optional date string (defaults to today)
+ * @returns {Object} Object with logsDir, yearDir, logFile, dateFormatted
+ */
 function getLogPath(dateStr) {
   const targetDir = path.join(process.cwd(), 'atris');
   const date = dateStr ? new Date(dateStr) : new Date();
@@ -17,6 +21,9 @@ function getLogPath(dateStr) {
   return { logsDir, yearDir, logFile, dateFormatted };
 }
 
+/**
+ * Ensure the logs directory structure exists.
+ */
 function ensureLogDirectory() {
   const { logsDir, yearDir } = getLogPath();
 
@@ -29,6 +36,11 @@ function ensureLogDirectory() {
   }
 }
 
+/**
+ * Create a new daily log file, carrying forward unfinished items from yesterday.
+ * @param {string} logFile - Path to the log file to create
+ * @param {string} dateFormatted - Date string in YYYY-MM-DD format
+ */
 function createLogFile(logFile, dateFormatted) {
   let carryInProgress = '';
   let carryBacklog = '';

package/lib/journal.js

@@ -4,6 +4,12 @@ const path = require('path');
 const os = require('os');
 const { spawnSync } = require('child_process');
 
+/**
+ * Check if two timestamps are effectively the same (within 5ms).
+ * @param {string} a - First timestamp
+ * @param {string} b - Second timestamp
+ * @returns {boolean} True if timestamps are within 5ms of each other
+ */
 function isSameTimestamp(a, b) {
   if (!a || !b) return false;
   const ta = new Date(a).getTime();
@@ -12,6 +18,11 @@ function isSameTimestamp(a, b) {
   return Math.abs(ta - tb) < 5;
 }
 
+/**
+ * Compute a SHA-256 hash of content with normalized line endings.
+ * @param {string} content - Content to hash
+ * @returns {string|null} Hex hash or null if invalid input
+ */
 function computeContentHash(content) {
   if (typeof content !== 'string') {
     return null;
@@ -20,6 +31,11 @@ function computeContentHash(content) {
   return crypto.createHash('sha256').update(normalized).digest('hex');
 }
 
+/**
+ * Parse journal content into named sections (by ## headers).
+ * @param {string} content - Journal markdown content
+ * @returns {Object} Map of section name to content
+ */
 function parseJournalSections(content) {
   const sections = {};
   const lines = content.split('\n');
@@ -48,6 +64,13 @@ function parseJournalSections(content) {
   return sections;
 }
 
+/**
+ * Merge local and remote journal sections, detecting conflicts.
+ * @param {Object} localSections - Local section map
+ * @param {Object} remoteSections - Remote section map
+ * @param {string} knownRemoteHash - Hash of remote at last sync
+ * @returns {{merged: Object, conflicts: Array}} Merged sections and conflicts
+ */
 function mergeSections(localSections, remoteSections, knownRemoteHash) {
   const merged = {};
   const conflicts = [];

package/lib/scorecard.js

@@ -4,16 +4,31 @@ const { parseTodo } = require('./todo');
 
 const PRIVATE_MEMORY_ROOT = '.atris/presidio';
 
+/**
+ * Ensure the private memory directory exists.
+ * @param {string} atrisDir - Path to the atris directory
+ * @returns {string} Path to the private memory directory
+ */
 function ensurePrivateMemoryDir(atrisDir) {
   const privateDir = path.join(path.dirname(atrisDir), PRIVATE_MEMORY_ROOT);
   fs.mkdirSync(privateDir, { recursive: true });
   return privateDir;
 }
 
+/**
+ * Get the path to the scorecards file.
+ * @param {string} atrisDir - Path to the atris directory
+ * @returns {string} Path to scorecards.md
+ */
 function getScorecardsPath(atrisDir) {
   return path.join(ensurePrivateMemoryDir(atrisDir), 'scorecards.md');
 }
 
+/**
+ * Parse a "picked at" timestamp from scorecard data.
+ * @param {string} value - Timestamp string in YYYY-MM-DD [HH:MM] format
+ * @returns {Date|null} Parsed date or null if invalid
+ */
 function parsePickedAt(value) {
   if (!value) return null;
   const match = String(value).trim().match(/^(\d{4}-\d{2}-\d{2})(?:\s+(\d{2}:\d{2}))?/);
@@ -24,6 +39,12 @@ function parsePickedAt(value) {
   return Number.isNaN(parsed.getTime()) ? null : parsed;
 }
 
+/**
+ * Parse a tick timestamp combining date and time label.
+ * @param {string} dateStr - Date in YYYY-MM-DD format
+ * @param {string} timeLabel - Time label like "2:30 PM"
+ * @returns {Date|null} Parsed date or null if invalid
+ */
 function parseTickDate(dateStr, timeLabel) {
   const match = String(timeLabel || '').trim().toLowerCase().match(/^(\d{1,2}):(\d{2})(?:\s*(am|pm))?$/);
   if (!match) return null;
@@ -40,6 +61,13 @@ function parseTickDate(dateStr, timeLabel) {
   return Number.isNaN(parsed.getTime()) ? null : parsed;
 }
 
+/**
+ * List journal log files within a date range.
+ * @param {string} atrisDir - Path to the atris directory
+ * @param {Date} startDate - Start of date range
+ * @param {Date} [endDate] - End of date range (defaults to today)
+ * @returns {Array} Array of log file paths
+ */
 function listLogFiles(atrisDir, startDate, endDate = new Date()) {
   const logsDir = path.join(atrisDir, 'logs');
   if (!fs.existsSync(logsDir)) return [];
@@ -153,16 +181,20 @@ function buildScorecardData(atrisDir, { slug, pickedAt } = {}) {
   const todo = parseTodo(todoPath);
   const startAt = parsePickedAt(pickedAt) || new Date();
   const rewardStats = collectRewardStats(atrisDir, pickedAt);
-  const completedEndgame = todo.completed.filter(t => t.tag === 'endgame').length;
+  // Count shipped tasks from journal completions (tasks get deleted from TODO.md after completion)
+  const completedFromTodo = todo.completed.filter(t => t.tag === 'endgame').length;
   const activeEndgame = todo.backlog.filter(t => t.tag === 'endgame').length
     + todo.inProgress.filter(t => t.tag === 'endgame').length;
+  // Fall back to reward tick count if TODO completions were already pruned
+  const shipped = completedFromTodo > 0 ? completedFromTodo : rewardStats.totalTicks - rewardStats.haltedTicks;
+  const attempted = shipped + activeEndgame + rewardStats.haltedTicks;
 
   return {
     slug,
     startDate: startAt.toISOString().slice(0, 10),
     endDate: new Date().toISOString().slice(0, 10),
-    tasksShipped: completedEndgame,
-    tasksAttempted: completedEndgame + activeEndgame,
+    tasksShipped: Math.max(shipped, 0),
+    tasksAttempted: Math.max(attempted, shipped),
     wallClockHours: Math.max(0, (Date.now() - startAt.getTime()) / (1000 * 60 * 60)),
     haltRatio: rewardStats.totalTicks > 0 ? rewardStats.haltedTicks / rewardStats.totalTicks : 0,
     totalReward: rewardStats.totalReward,
@@ -205,6 +237,12 @@ function writeScorecard(atrisDir, data) {
 
   const scorecardsPath = getScorecardsPath(atrisDir);
 
+  // Dedupe guard: don't write the same slug twice
+  const existing = readScorecards(atrisDir);
+  if (existing.some(sc => sc.slug === slug)) {
+    return; // already written
+  }
+
   // Ensure scorecards.md exists
   if (!fs.existsSync(scorecardsPath)) {
     const template = `# scorecards.md — Endgame Results\n\n> Append-only. One line per closed endgame. Records outcome metrics from the horizon.\n\n---\n\n`;
@@ -263,7 +301,7 @@ function readScorecards(atrisDir) {
   const scorecards = [];
 
   for (const line of content.split('\n')) {
-    const match = line.match(/^- \*\*\[(.+?)\]\s+(.+?)\*\*\s*—\s*shipped:\s*(\d+)\/(\d+)\s*—\s*wall-clock:\s*(.+?)\s*—\s*halt:\s*(\d+)%\s*—\s*reward:\s*(\d+)\s*—\s*lessons:\s*(\d+)$/);
+    const match = line.match(/^- \*\*\[(.+?)\]\s+(.+?)\*\*\s*—\s*shipped:\s*(\d+)\/(\d+)\s*—\s*wall-clock:\s*(.+?)\s*—\s*halt:\s*(\d+)%\s*—\s*reward:\s*(-?\d+)\s*—\s*lessons:\s*(\d+)$/);
     if (!match) continue;
 
     const [, endDate, slug, shipped, attempted, wallClockStr, haltPercent, reward, lessons] = match;