sandtable 0.3.1 → 1.0.1

package/src/check/check.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { scan } = require('../scanner/scan');
+const { loadContract } = require('../contract/loader');
+const { buildTracks } = require('../progress/parser');
+
+function check(projectRoot) {
+  try {
+    const results = [];
+    const { contract, config } = loadContract(projectRoot);
+    const scanResult = scan(projectRoot);
+
+    // Check 1: Classification completeness
+    const unclassified = scanResult.files.filter(f => f.category === 'unknown');
+    results.push({
+      id: 'classification',
+      status: unclassified.length === 0 ? 'pass' : 'warning',
+      detail: unclassified.length > 0
+        ? unclassified.length + ' files unclassified: ' + unclassified.map(f => f.path).slice(0, 10).join(', ') + (unclassified.length > 10 ? '...' : '')
+        : 'All files classified'
+    });
+
+    // Check 2: MECE completeness
+    const catCounts = {};
+    for (const f of scanResult.files) {
+      catCounts[f.category] = (catCounts[f.category] || 0) + 1;
+    }
+    const emptyCats = (contract.categories || []).filter(c => !catCounts[c.id]);
+    results.push({
+      id: 'mece',
+      status: emptyCats.length === 0 ? 'pass' : 'warning',
+      detail: emptyCats.length > 0
+        ? 'Empty categories: ' + emptyCats.map(c => c.label).join(', ')
+        : 'All categories have files'
+    });
+
+    // Check 3: Progress consistency (if progressSources configured)
+    const progressSources = config._progressSources || [];
+    if (progressSources.length > 0) {
+      const { tracks } = buildTracks(progressSources, projectRoot);
+      results.push({
+        id: 'progress',
+        status: 'pass',
+        detail: tracks.length + ' tracks parsed'
+      });
+
+      // Check for status conflicts between tracks
+      const conflicts = [];
+      for (let i = 0; i < tracks.length; i++) {
+        for (let j = i + 1; j < tracks.length; j++) {
+          const idsA = new Set(tracks[i].phases.map(p => p.id));
+          for (const phase of tracks[j].phases) {
+            if (idsA.has(phase.id)) {
+              const other = tracks[i].phases.find(p => p.id === phase.id);
+              if (other && other.status !== phase.status) {
+                conflicts.push(phase.id + ': ' + tracks[i].id + '=' + other.status + ' vs ' + tracks[j].id + '=' + phase.status);
+              }
+            }
+          }
+        }
+      }
+      if (conflicts.length > 0) {
+        results.push({
+          id: 'consistency',
+          status: 'warning',
+          detail: 'Status conflicts: ' + conflicts.join('; ')
+        });
+      }
+    }
+
+    // Check 4: SUMMARY coverage
+    const withSummary = scanResult.files.filter(f => f.hasSummary).length;
+    const total = scanResult.files.length;
+    const pct = Math.round(withSummary / Math.max(total, 1) * 100);
+    results.push({
+      id: 'summary',
+      status: pct > 20 ? 'pass' : 'info',
+      detail: withSummary + '/' + total + ' (' + pct + '%) files have SUMMARY'
+    });
+
+    // Check 5: Meta exclusion
+    results.push({
+      id: 'exclusion',
+      status: 'pass',
+      detail: (scanResult.metaExcluded || 0) + ' meta files excluded'
+    });
+
+    // Overall
+    const hasWarning = results.some(r => r.status === 'warning');
+    const hasError = results.some(r => r.status === 'error');
+
+    return {
+      passed: !hasWarning && !hasError,
+      project: path.basename(projectRoot),
+      timestamp: new Date().toISOString(),
+      results
+    };
+  } catch (e) {
+    return {
+      passed: false,
+      project: path.basename(projectRoot),
+      timestamp: new Date().toISOString(),
+      results: [{
+        id: 'fatal',
+        status: 'error',
+        detail: 'Check failed: ' + e.message
+      }]
+    };
+  }
+}
+
+// Human-readable output
+function printCheck(report) {
+  console.log('\n=== Sandtable Check ===');
+  for (const r of report.results) {
+    const icon = r.status === 'pass' ? '\u2713' : r.status === 'warning' ? '\u26A0' : '\u2717';
+    console.log(icon + ' ' + r.id + ': ' + r.detail);
+  }
+  console.log('\nexit code: ' + (report.passed ? 0 : 1));
+}
+
+module.exports = { check, printCheck };
+
+if (require.main === module) {
+  const root = process.argv[2] || process.cwd();
+  const report = check(root);
+  printCheck(report);
+
+  // Write JSON report
+  const dataDir = path.join(root, 'data');
+  if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+  fs.writeFileSync(path.join(dataDir, 'check-report.json'), JSON.stringify(report, null, 2));
+  process.exit(report.passed ? 0 : 1);
+}

package/src/cli/sandtable.js

@@ -8,7 +8,7 @@ const { exec } = require('child_process');
 const { scan } = require('../scanner/scan');
 const { build, EVENT_TYPES, classifyEventPriority } = require('../builder/build');
 
-const VERSION = '0.3.1';
+const VERSION = '0.4.0';
 const command = process.argv[2] || 'help';
 const root = process.argv[3] || process.cwd();
 
@@ -279,6 +279,79 @@ function removeFromMainDoc(filePath, dryRun) {
   return true;
 }
 
+// ---- appendToGitignore: 自动追加 sandtable 条目到 .gitignore ----
+// 使用 # sandtable:begin/end 标记包裹，uninstall 时精确擦除
+function appendToGitignore(projectRoot, dryRun) {
+  var gitignorePath = path.join(projectRoot, '.gitignore');
+  var beginMark = '# sandtable:begin';
+  var endMark = '# sandtable:end';
+  var existing = '';
+  if (fs.existsSync(gitignorePath)) {
+    existing = fs.readFileSync(gitignorePath, 'utf-8');
+    if (existing.indexOf(beginMark) !== -1) {
+      if (!dryRun) console.log('  - .gitignore 已有 sandtable 标记，跳过');
+      return false;
+    }
+  }
+
+  var block = [
+    '',
+    beginMark,
+    '# Sandtable 自动生成条目 — 请勿手动编辑此块',
+    'data/',
+    '.sandtable/token-log.jsonl',
+    '.sandtable/audit.log',
+    '.sandtable/.token',
+    endMark,
+    '',
+  ].join('\n');
+
+  if (dryRun) {
+    console.log('  [DRY-RUN] 将追加到 .gitignore:');
+    console.log('  --- diff ---');
+    console.log('  + ' + block.replace(/\n/g, '\n  + '));
+    console.log('  --- end ---');
+    return true;
+  }
+
+  writeWithBackup(gitignorePath, existing + block);
+  return true;
+}
+
+// ---- removeFromGitignore: uninstall 时擦除 sandtable gitignore 块 ----
+function removeFromGitignore(projectRoot, dryRun) {
+  var gitignorePath = path.join(projectRoot, '.gitignore');
+  var beginMark = '# sandtable:begin';
+  var endMark = '# sandtable:end';
+
+  if (!fs.existsSync(gitignorePath)) return false;
+
+  var content = fs.readFileSync(gitignorePath, 'utf-8');
+  var beginIdx = content.indexOf(beginMark);
+  var endIdx = content.indexOf(endMark);
+
+  if (beginIdx === -1 || endIdx === -1) return false;
+
+  var beforeBegin = content.lastIndexOf('\n', beginIdx);
+  if (beforeBegin === -1) beforeBegin = 0;
+
+  var afterEnd = endIdx + endMark.length;
+  if (content[afterEnd] === '\n') afterEnd++;
+  if (content[afterEnd] === '\n') afterEnd++; // consume trailing blank line
+
+  if (dryRun) {
+    console.log('  [DRY-RUN] 将从 .gitignore 移除 sandtable 块:');
+    console.log('  --- to remove ---');
+    console.log(content.substring(beforeBegin, afterEnd).replace(/^/gm, '  - '));
+    console.log('  --- end ---');
+    return true;
+  }
+
+  var cleaned = content.substring(0, beforeBegin) + content.substring(afterEnd);
+  writeWithBackup(gitignorePath, cleaned);
+  return true;
+}
+
 // ---- writeClaudeCodeHook: 创建 SessionStart 强提醒 hook ----
 function writeClaudeCodeHook(projectRoot, lang) {
   var hooksDir = path.join(projectRoot, '.claude', 'hooks');
@@ -432,7 +505,7 @@ function initCommand(projectRoot, applyMode, lang, hooksMode, injectAgentsMd) {
 
   // 2. Write .sandtable/config.json
   var config = {
-    version: '0.3.1',
+    version: '0.4.0',
     createdAt: new Date().toISOString(),
     projectRoot: projectRoot,
     paths: {
@@ -510,6 +583,13 @@ function initCommand(projectRoot, applyMode, lang, hooksMode, injectAgentsMd) {
     console.log('  ✓ 安装 SessionStart 强提醒 hook → .claude/hooks/sandtable-reminder.sh');
   }
 
+  // 8. Append sandtable entries to .gitignore (auto, always)
+  var gitignoreDryRun = !applyMode;
+  appendToGitignore(projectRoot, gitignoreDryRun);
+  if (applyMode && fs.existsSync(path.join(projectRoot, '.gitignore'))) {
+    console.log('  ✓ 追加 sandtable 条目至 .gitignore');
+  }
+
   console.log('');
   console.log('✓ 初始化完成。运行 sandtable build 生成数据，然后 sandtable serve 查看仪表盘。');
 
@@ -592,7 +672,9 @@ function enableWatchMode(projectRoot) {
   }
 }
 
-function startServer(projectRoot, port, openBrowser, watchMode) {
+function startServer(projectRoot, port, openBrowser, watchMode, host, token) {
+  host = host || '127.0.0.1';
+  token = token || '';
   const MIME = {
     '.html': 'text/html; charset=utf-8',
     '.css': 'text/css; charset=utf-8',
@@ -629,6 +711,27 @@ function startServer(projectRoot, port, openBrowser, watchMode) {
   }
 
   http.createServer(function(req, res) {
+    // Token authentication (when binding to public interface)
+    if (token) {
+      var qIdx = req.url.indexOf('?');
+      var hasToken = false;
+      if (qIdx !== -1) {
+        var qs = req.url.substring(qIdx + 1);
+        var pairs = qs.split('&');
+        for (var pi = 0; pi < pairs.length; pi++) {
+          var kv = pairs[pi].split('=');
+          if (decodeURIComponent(kv[0]) === 'token' && kv[1] === token) {
+            hasToken = true;
+            break;
+          }
+        }
+      }
+      if (!hasToken) {
+        res.writeHead(401, { 'Content-Type': 'text/plain; charset=utf-8' });
+        return res.end('401 Unauthorized — 请在 URL 后添加 ?token=' + token);
+      }
+    }
+
     var url = req.url === '/' ? '/dashboard/dashboard.html' : req.url;
     url = url.replace(/^\/(css|js)\//, '/dashboard/$1/');
 
@@ -666,9 +769,12 @@ function startServer(projectRoot, port, openBrowser, watchMode) {
       res.writeHead(500, { 'Content-Type': 'text/plain' });
       res.end('500: ' + e.message);
     }
-  }).listen(port, function() {
-    console.log('Sandtable v' + VERSION + ' — http://localhost:' + port);
+  }).listen(port, host, function() {
+    console.log('Sandtable v' + VERSION + ' — http://' + host + ':' + port);
     console.log('Project: ' + projectRoot);
+    if (token) {
+      console.log('Token: ' + token + '  (访问需携带 ?token=' + token + ')');
+    }
 
     if (watchMode) enableWatchMode(projectRoot);
 
@@ -708,6 +814,40 @@ switch (command) {
     initCommand(process.cwd(), applyMode, lang, hooksMode, injectAgentsMd);
     break;
   }
+  case 'check': {
+    const { check, printCheck } = require('../check/check');
+    const projectRoot = process.argv[3] || process.cwd();
+    const report = check(projectRoot);
+    printCheck(report);
+
+    // Write JSON report
+    const dataDir = path.join(projectRoot, 'data');
+    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(path.join(dataDir, 'check-report.json'), JSON.stringify(report, null, 2));
+    process.exit(report.passed ? 0 : 1);
+  }
+  case 'test': {
+    const fixtureIdx = process.argv.indexOf('--fixture');
+    if (fixtureIdx === -1) {
+      console.log('用法: sandtable test --fixture <项目路径>');
+      console.log('  以指定项目为 golden fixture 运行回归验证');
+      process.exit(1);
+    }
+    const fixturePath = process.argv[fixtureIdx + 1];
+    if (!fixturePath) {
+      console.log('错误：--fixture 需要指定项目路径');
+      process.exit(1);
+    }
+    // Run the fixture test
+    const testScript = require('path').join(__dirname, '..', '..', 'tests', 'run-libero-validation.js');
+    if (require('fs').existsSync(testScript)) {
+      require(testScript).run(fixturePath);
+    } else {
+      console.log('Fixture test script not found (' + testScript + '). Run from Sandtable repo root.');
+      process.exit(1);
+    }
+    break;
+  }
   case 'summarize': {
     const scanResult = scan(root);
     const missing = scanResult.files.filter(f => !f.hasSummary);
@@ -731,7 +871,40 @@ switch (command) {
   case 'serve': {
     var port = parseInt(process.argv[3], 10) || 5199;
     var watchMode = process.argv.indexOf('--watch') !== -1;
-    startServer(process.cwd(), port, true, watchMode);
+
+    // Parse --host (default: 127.0.0.1, safe by default)
+    var hostIdx = process.argv.indexOf('--host');
+    var host = '127.0.0.1';
+    if (hostIdx !== -1 && process.argv[hostIdx + 1] && process.argv[hostIdx + 1].indexOf('--') !== 0) {
+      host = process.argv[hostIdx + 1];
+    }
+
+    // Parse --token (required when binding to 0.0.0.0)
+    var tokenIdx = process.argv.indexOf('--token');
+    var token = '';
+    var tokenPath = path.join(process.cwd(), '.sandtable', '.token');
+    if (tokenIdx !== -1) {
+      var nextArg = process.argv[tokenIdx + 1];
+      if (nextArg && nextArg.indexOf('--') !== 0) {
+        token = nextArg;
+        // Persist user-provided token
+        try { fs.writeFileSync(tokenPath, token, 'utf-8'); } catch(e) {}
+      } else {
+        token = require('crypto').randomBytes(16).toString('hex');
+        try { fs.writeFileSync(tokenPath, token, 'utf-8'); } catch(e) {}
+      }
+    }
+    if ((host === '0.0.0.0' || host === '::') && !token) {
+      // Try to load persisted token first
+      try { if (fs.existsSync(tokenPath)) token = fs.readFileSync(tokenPath, 'utf-8').trim(); } catch(e) {}
+      if (!token) {
+        token = require('crypto').randomBytes(16).toString('hex');
+        try { fs.writeFileSync(tokenPath, token, 'utf-8'); } catch(e) {}
+      }
+      console.log('⚠ 绑定 ' + host + ' 将暴露服务到网络，token: ' + token);
+    }
+
+    startServer(process.cwd(), port, true, watchMode, host, token);
     break;
   }
       case 'event-log': {
@@ -902,7 +1075,9 @@ switch (command) {
 
       var slugName = TYPE_SLUG_NAMES[typeId] || '';
       console.log('event-log: [' + event.priority + '] ' + event.type + ' — ' + title + (threadId ? ' (thread: ' + threadId + ')' : ''));
-      console.log('  (提示: 位置参数已弃用，下次推荐: --type ' + slugName + ' --title "...")');
+      if (!isNamedMode) {
+        console.log('  (提示: 位置参数已弃用，下次推荐: --type ' + slugName + ' --title "...")');
+      }
 
       // --tokens-in + --tokens-out: auto-log token usage
       if (tokensIn > 0 || tokensOut > 0) {
@@ -1060,6 +1235,18 @@ case 'token-log': {
       console.log('主文档中未找到 sandtable 注入标记。');
     }
 
+    // Check for sandtable gitignore block
+    var gitignorePath = path.join(projectRoot, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      var giContent = fs.readFileSync(gitignorePath, 'utf-8');
+      if (giContent.indexOf('# sandtable:begin') !== -1) {
+        if (dryRun) {
+          console.log('');
+          removeFromGitignore(projectRoot, true);
+        }
+      }
+    }
+
     if (dryRun) {
       console.log('');
       console.log('以上为 dry-run 预览。要实际删除，请运行:');
@@ -1067,6 +1254,7 @@ case 'token-log': {
       console.log('');
       console.log('注意：');
       console.log('  - sandtable 注入标记 (<!-- sandtable:begin/end -->) 可被 uninstall --apply 精确擦除');
+      console.log('  - .gitignore 中 sandtable 条目 (# sandtable:begin/end) 也会被移除');
       console.log('  - 如果你在 AGENTS.md/CLAUDE.md 中手动添加了其他 sandtable 内容，请自行删除');
       break;
     }
@@ -1080,6 +1268,10 @@ case 'token-log': {
       }
     }
 
+    // --apply: remove sandtable gitignore block
+    var giRemoved = removeFromGitignore(projectRoot, false);
+    if (giRemoved) console.log('  ✓ 从 .gitignore 移除 sandtable 条目');
+
     // --apply: delete files
     console.log('');
     console.log('正在删除...');
@@ -1132,7 +1324,9 @@ case 'token-log': {
     console.log('  sandtable init       [--apply] [--lang zh|en]  扫描环境 + 准备规则文件');
     console.log('  sandtable scan       [projectRoot]             扫描文档目录');
     console.log('  sandtable build      [projectRoot]             生成 data/*.json');
-    console.log('  sandtable serve      [port] [--watch]          启动服务 + 打开浏览器');
+    console.log('  sandtable serve      [port] [--watch] [--host <ip>] [--token <token>]  启动服务 + 打开浏览器');
+    console.log('  sandtable check      [projectRoot]             一致性校验');
+    console.log('  sandtable test       --fixture <path>           golden fixture 回归测试');
     console.log('  sandtable summarize  [projectRoot]             列出缺少摘要块的文件');
     console.log('  sandtable event-log  <typeId> <title> [...]    记录人机协同事件');
     console.log('  sandtable token-log  <skill> <in> <out> [...]  追加 token 消耗日志');

package/src/contract/default-contract.json

@@ -0,0 +1,21 @@
+{
+  "schema": "sandtable-default",
+  "categories": [
+    { "id": "roadmap", "label": "路线图与进度", "order": 1,
+      "paths": ["docs/plan/**", "docs/specs/*roadmap*", "docs/specs/*phase*", "docs/specs/*bug-collect*"] },
+    { "id": "decision", "label": "决策记录", "order": 2,
+      "paths": ["docs/specs/decisions/**"] },
+    { "id": "spec", "label": "业务规格", "order": 3,
+      "paths": ["docs/specs/**"] },
+    { "id": "convention", "label": "协作纪律", "order": 4,
+      "paths": ["docs/skills/**", "docs/agents/**", "docs/conventions/**", "AGENTS.md", "CLAUDE.md"] },
+    { "id": "ops", "label": "运维与基建", "order": 5,
+      "paths": ["docs/runbooks/**"] },
+    { "id": "archive", "label": "历史档案", "order": 6,
+      "paths": ["docs/plans/**", "docs/journal/**", "docs/archive/**"], "defaultHidden": true }
+  ],
+  "meta": [
+    "docs/*-reference.md",
+    "docs/*-glossary.md"
+  ]
+}

package/src/contract/loader.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---- Glob to Regex ----
+const regexCache = {};
+
+function globToRegex(pattern) {
+  if (regexCache[pattern]) return regexCache[pattern];
+
+  let re = '';
+  const parts = pattern.split('/');
+  let skipSep = false;
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '**') {
+      if (i === 0 && parts.length > 1) {
+        // Leading ** with more parts: match zero or more leading directories
+        re += '(?:.*\\/)?';
+        skipSep = true;
+      } else if (i > 0 && i < parts.length - 1) {
+        // Middle **: required / + optional wildcard dirs including trailing /
+        re += '\\/(?:.*\\/)?';
+        skipSep = true;
+      } else {
+        if (i > 0) re += '\\/';
+        re += '.*';
+      }
+    } else {
+      if (i > 0 && !skipSep) {
+        re += '\\/';
+      }
+      skipSep = false;
+      let seg = parts[i]
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\?/g, '.')
+        .replace(/\*/g, '[^/]*');
+      re += seg;
+    }
+  }
+  if (pattern.endsWith('/**')) {
+    re += '(?:\\/.*)?';
+  }
+  // Case-insensitive matching for cross-platform compatibility
+  const regex = new RegExp('^' + re + '$', 'i');
+  regexCache[pattern] = regex;
+  return regex;
+}
+
+// ---- Load contract: user config > built-in default ----
+function loadContract(projectRoot) {
+  const configPath = path.join(projectRoot, '.sandtable.json');
+  let userContract = null;
+
+  let config = {
+    _progressSources: [],
+    _events: { gitLog: true, maxGitLogEntries: 100 },
+    _exclude: null
+  };
+
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (config.docContract) {
+        userContract = config.docContract;
+      }
+      config._progressSources = config.progressSources || [];
+      config._events = config.events || { gitLog: true, maxGitLogEntries: 100 };
+      config._exclude = config.exclude || null;
+    } catch (e) {
+      // Config parse error — fall through to default
+      console.warn('sandtable: .sandtable.json parse error, using default contract —', e.message);
+    }
+  }
+
+  // Fallback: built-in default contract when no user contract found
+  if (!userContract) {
+    const defaultPath = path.join(__dirname, 'default-contract.json');
+    userContract = JSON.parse(fs.readFileSync(defaultPath, 'utf-8'));
+  }
+
+  return { contract: userContract, config };
+}
+
+// ---- Classify a single file by docContract ----
+// Returns { category, elementType, isMeta } or null if excluded
+function classifyFile(relativePath, contract, summaryBlock) {
+  if (!contract) return null;
+
+  // 1. Check meta exclusion
+  const meta = contract.meta || [];
+  for (const m of meta) {
+    const re = globToRegex(m);
+    if (re.test(relativePath)) {
+      return { category: 'meta', elementType: 'meta', isMeta: true };
+    }
+  }
+
+  // 2. SUMMARY block explicit category override (highest priority)
+  if (summaryBlock && summaryBlock.category) {
+    const cat = contract.categories.find(c => c.id === summaryBlock.category);
+    if (cat) {
+      return {
+        category: cat.id,
+        elementType: summaryBlock.type || 'unknown',
+        isMeta: false
+      };
+    }
+  }
+
+  // 3. Longest-match glob across all category paths
+  let bestMatch = null;
+  let bestLen = 0;
+
+  for (const cat of contract.categories) {
+    for (const pat of (cat.paths || [])) {
+      const re = globToRegex(pat);
+      if (re.test(relativePath)) {
+        if (pat.length > bestLen) {
+          bestLen = pat.length;
+          bestMatch = cat;
+        }
+      }
+    }
+  }
+
+  if (bestMatch) {
+    return {
+      category: bestMatch.id,
+      elementType: inferElementType(relativePath, bestMatch.id),
+      isMeta: false
+    };
+  }
+
+  // 4. Unknown
+  return { category: 'unknown', elementType: 'unknown', isMeta: false };
+}
+
+// ---- Element type inference map (module-level to avoid re-creation) ----
+const ELEMENT_TYPE_MAP = {
+  roadmap: [
+    { test: /roadmap|execution-plan/, type: 'roadmap' },
+    { test: /bug-collect/, type: 'backlog' },
+    { test: /phase/, type: 'phase' }
+  ],
+  decision: [
+    { test: /\d{4}-\d{2}-\d{2}/, type: 'decision' },
+    { test: /refactor/i, type: 'refactor' }
+  ],
+  spec: [
+    { test: /intents?\//, type: 'intent' },
+    { test: /refactors?\//, type: 'refactor' },
+    { test: /testing\//, type: 'spec' },
+    { test: /prompts?\//, type: 'prompt' },
+    { test: /template/, type: 'template' },
+    { test: /architecture/, type: 'spec' }
+  ],
+  convention: [
+    { test: /skills?\//, type: 'convention' },
+    { test: /agents?\//, type: 'convention' },
+    { test: /AGENTS\.md|CLAUDE\.md/, type: 'convention' }
+  ],
+  ops: [
+    { test: /runbooks?\//, type: 'runbook' }
+  ],
+  archive: [
+    { test: /journal/, type: 'journal' },
+    { test: /plans?\//, type: 'plan_doc' },
+    { test: /handover/, type: 'handover' }
+  ]
+};
+
+// ---- Infer elementType from category + path ----
+function inferElementType(relativePath, category) {
+  const rp = relativePath.toLowerCase();
+  const rules = ELEMENT_TYPE_MAP[category] || [];
+  for (const rule of rules) {
+    if (rule.test.test(rp)) return rule.type;
+  }
+  return category;
+}
+
+// ---- Get ordered list of categories for UI ----
+function getCategoryList(contract) {
+  if (!contract) return [];
+  return [...contract.categories].sort((a, b) => a.order - b.order);
+}
+
+// ---- Check if a file path should be excluded ----
+function isExcluded(relativePath, excludeConfig) {
+  if (!excludeConfig) return false;
+  const patternRes = (excludeConfig.patterns || []).map(p => globToRegex(p));
+  for (const re of patternRes) {
+    if (re.test(relativePath)) return true;
+  }
+  return false;
+}
+
+module.exports = {
+  loadContract, classifyFile, getCategoryList,
+  isExcluded, globToRegex, inferElementType
+};