@mcptoolshop/style-dataset-lab 1.2.0 → 2.0.0

package/README.zh.md

@@ -13,91 +13,133 @@
 
 # style-dataset-lab
 
-视觉数据集工厂 -- 用于生成、整理和导出多模态训练数据，以进行大型视觉语言模型（VLM）的微调。
+一个用于创建视觉数据集的生产流水线，从规范规则到结构化提示，再到 ComfyUI 生成，最终得到经过筛选、符合规范的训练数据。
 
 ## 这是什么
 
-一个用于**构建可训练的视觉真理**的工具集。每个资源都包含以下三方面：
+一个用于构建结构化视觉训练数据集的**流水线**。 您可以编写风格规则（规范），编写提示，使用 ComfyUI 生成图像，并根据每个维度进行评分进行筛选，将判断结果与规范规则关联，并通过 [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 以 10 种格式导出。
 
-1. **图像像素** -- 由 ComfyUI 生成，并包含完整的溯源信息（检查点、LoRA、种子、采样器、CFG）。
-2. **规范解释** -- 解释为什么该图像符合或不符合特定风格，并基于风格规范进行判断。
-3. **质量评估** -- 经过批准/拒绝，并提供每个维度的评分以及引用规则。
+该流水线不依赖于特定的游戏。 每个游戏都有自己的数据目录，位于 `games/<name>/` 目录下；13 个脚本和空白模板是共享的。 每个生成的资源都包含以下三项：
 
-输出结果通过 [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 生成多模态训练数据，提供 10 种格式：TRL、LLaVA、Qwen2-VL、Axolotl、LLaMA-Factory、ShareGPT、RLHF 对、DPO、图像描述和分类。
+1. **图像像素**：由 ComfyUI 生成，包含完整的溯源信息（检查点、LoRA、种子、采样器、CFG）。
+2. **规范解释**：解释为什么该图像符合或不符合风格，并基于风格规范进行说明。
+3. **质量判断**：通过批准/拒绝，并根据每个维度的评分引用相关规则。
 
 ## 安全模型
 
-**仅本地运行。** style-dataset-lab 只与本地 `localhost:8188` 上的 ComfyUI 进行通信，不会进行任何外部网络请求。没有遥测数据，没有分析功能，不会向外部发送数据。图像生成完全在您的 GPU 上进行。记录和规范数据都存储在您的文件系统中。
+**仅本地运行。** `style-dataset-lab` 只与本地 `localhost:8188` 上的 ComfyUI 进行通信，不会进行任何外部网络请求。 没有遥测数据，没有分析功能，不会向外部发送数据。 图像生成完全在您的 GPU 上进行。 记录和规范数据都存储在您的文件系统中。
 
-## 数据集统计信息
+## npm 包包含的内容
 
-| 指标 | 数值 |
-|--------|-------|
-| 整理记录 | 1,182 |
-| 总资源数 | 2,571 (其中 893 个已批准，887 个为绘画风格变体) |
-| 提示词组合 | 28 |
-| 视觉类别 | 18 种 (包括：服装、船只、室内、设备、环境、物种、站点、标识、照明、货物、**架构**、生物、表面、日常生活、行星、损坏/修复、外星生物、细节)。 |
-| 成对比较 | 6 个人工标注 + 71 个合成数据 |
-| 不同类型的拒绝 | 30+ |
-| 身份包系统 | 具有派系 DNA、等级和视觉特征的命名角色。 |
-| 导出格式 | 10 种 (通过 `@mcptoolshop/repo-dataset`) |
+`npm install @mcptoolshop/style-dataset-lab` 会为您提供：
+
+- **13 个脚本**：用于生成、筛选、比较、与规范关联、生成绘画风格图像、生成身份图像、使用 ControlNet/IP-Adapter 生成图像、批量筛选、数据迁移。
+- **空白模板**：位于 `templates/` 目录下，包含起始规范、审查标准和示例提示包。
+
+该 npm 包**不包含**游戏数据。 如果您想使用 Star Freight 示例，请克隆该仓库（包含 1182 条记录，28 个提示集，18 个视觉类别）。
 
 ## 安装
 
 ```bash
-npm install -g @mcptoolshop/style-dataset-lab
+# Get the pipeline scripts + templates
+npm install @mcptoolshop/style-dataset-lab
+
+# Or clone the repo for the Star Freight example data
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+npm install
 ```
 
-然后克隆一个项目或初始化一个新的数据集工作区：
+要从模板开始一个新的游戏：
 
 ```bash
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab my-dataset
-cd my-dataset
-npm install
+# Copy templates into your game directory
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+# Edit the canon and prompts, then generate
+```
+
+## 单仓库结构
+
+流水线位于 `scripts/` 和 `templates/` 目录下。 每个游戏位于 `games/<name>/` 目录下，包含自己的规范、记录和资源。 脚本接受 `--game <name>` 参数（默认为 `star-freight`）。
+
 ```
+style-dataset-lab/
+  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
+  templates/                Blank starting point for new games
+    canon/                  Starter constitution + review rubric
+    inputs/prompts/         Example prompt pack
+  games/
+    star-freight/           Star Freight example (1,182 records, repo-only)
+      canon/                Style constitution, review rubric, species canon
+      records/              Per-asset JSON (provenance + judgment + canon)
+      comparisons/          A-vs-B preference judgments
+      inputs/               Prompt packs, identity packets, references
+      outputs/              Generated images (gitignored)
+      exports/              repo-dataset output (gitignored)
+    <your-game>/            Add more games with the same structure
+```
+
+## 流水线工作流程
 
-## 工作流程
+从规范到训练数据导出的完整流水线：
 
 ```bash
-# 1. Start ComfyUI
-# (point it at your checkpoint + LoRA setup)
+# 1. Write your canon -- style constitution + review rubric
+#    (start from templates/ or write from scratch)
 
-# 2. Generate candidates from a prompt pack
-npm run generate -- inputs/prompts/wave1.json
-npm run generate -- inputs/prompts/wave1.json --dry-run
+# 2. Create prompt packs in inputs/prompts/
+#    (see templates/inputs/prompts/example-wave.json)
 
-# 3. Generate identity-packet characters
-npm run generate:identity -- inputs/identity-packets/wave27a-identity-spine.json
+# 3. Start ComfyUI and generate candidates
+npm run generate -- --game star-freight inputs/prompts/wave1.json
+npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
 
-# 4. Generate painterly variants of approved assets
-npm run painterly -- <asset_id>
+# 4. Generate identity-packet characters (named subjects)
+npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
 
 # 5. Curate -- approve, reject, or mark borderline
-npm run curate -- <asset_id> approved "explanation" --scores "silhouette:0.9,palette:0.8"
-npm run curate -- <asset_id> rejected "explanation" --failures "too_clean,wrong_material"
+npm run curate -- --game star-freight <asset_id> approved "explanation"
+npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+
+# 6. Generate painterly variants of approved assets
+npm run painterly -- --game star-freight
 
-# 6. Bind canon explanations to assets
-npm run canon-bind -- <asset_id>
+# 7. Bind canon explanations to curated assets
+npm run canon-bind -- --game star-freight
 
-# 7. Record pairwise comparisons
-npm run compare -- <asset_a> <asset_b> a "A has better faction read because..."
+# 8. Record pairwise comparisons
+npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
 
-# 8. Export training data via repo-dataset
-npm run export
-npm run inspect
-npm run validate
+# 9. Export training data via repo-dataset
+repo-dataset visual generate ./games/star-freight --format trl
+repo-dataset visual inspect ./games/star-freight
 ```
 
-## 目录结构
+## 添加新的游戏
+
+```bash
+# Create structure and copy blank templates
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+
+# Edit your canon/constitution.md and canon/review-rubric.md
+# Edit your prompt pack, then run the pipeline with --game my-game
+```
+
+## 每个游戏目录的布局
+
+每个 `games/<name>/` 目录包含：
 
 ```
-canon/                  Style constitution, review rubric, identity gates, species canon
+canon/                  Style constitution, review rubric, species canon, identity gates
 inputs/
   prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
   references/           IP-Adapter reference images
-  control/              ControlNet control images
   control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines (faction DNA, rank, visual anchors)
+  identity-packets/     Named character identity spines
 outputs/
   candidates/           Raw generations (gitignored)
   approved/             Curated approved (gitignored)
@@ -107,8 +149,6 @@ outputs/
 records/                Per-asset JSON (provenance + judgment + canon binding)
 comparisons/            A-vs-B preference judgments
 exports/                repo-dataset output (gitignored)
-scripts/                generate, curate, compare, canon-bind, painterly, identity gen
-workflows/              Reusable ComfyUI workflow templates
 ```
 
 ## 生成设置
@@ -124,7 +164,7 @@ scheduler: karras
 speed: ~9s per image (RTX 5080)
 ```
 
-其他生成模式：ControlNet（姿势/深度引导）、IP-Adapter（参考驱动）以及身份包（命名角色一致性）。
+其他生成模式：ControlNet（姿势/深度引导）、IP-Adapter（参考驱动）和身份包（用于保持角色一致性）。
 
 ## 要求
 

package/bin/sdlab.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * sdlab — CLI entry point for Style Dataset Lab.
+ *
+ * Thin dispatcher that routes subcommands to existing scripts.
+ * Each script exports run(argv) and is lazy-loaded on demand.
+ */
+
+const COMMANDS = {
+  'init':                '../scripts/init.js',
+  'generate':            '../scripts/generate.js',
+  'generate:identity':   '../scripts/generate-identity.js',
+  'generate:controlnet': '../scripts/generate-controlnet.js',
+  'generate:ipadapter':  '../scripts/generate-ipadapter.js',
+  'curate':              '../scripts/curate.js',
+  'compare':             '../scripts/compare.js',
+  'bind':                '../scripts/canon-bind.js',
+  'canon-bind':          '../scripts/canon-bind.js',
+  'painterly':           '../scripts/painterly.js',
+  'painterly:test':      '../scripts/painterly-test.js',
+  'migrate':             '../scripts/migrate-records.js',
+};
+
+// Two-word commands under "project" namespace
+const PROJECT_COMMANDS = {
+  'doctor':  '../scripts/doctor.js',
+  'migrate': '../scripts/migrate-records.js',
+};
+
+function printHelp() {
+  console.log(`\x1b[1msdlab\x1b[0m — Style Dataset Lab CLI\n`);
+  console.log('Usage: sdlab <command> [options]\n');
+  console.log('Project:');
+  console.log('  init <name>          Scaffold a new project from a domain template');
+  console.log('  project doctor       Validate project config and structure');
+  console.log('  project migrate      Migrate record schemas');
+  console.log('');
+  console.log('Pipeline:');
+  console.log('  generate             Generate candidates from a prompt pack');
+  console.log('  generate:identity    Generate named-subject identity images');
+  console.log('  generate:controlnet  ControlNet-guided structural generation');
+  console.log('  generate:ipadapter   IP-Adapter reference-guided generation');
+  console.log('  curate               Move candidate to approved/rejected/borderline');
+  console.log('  compare              Record pairwise A-vs-B comparison');
+  console.log('  bind                 Bind approved records to constitution rules');
+  console.log('  painterly            Post-processing painterly style pass');
+  console.log('  painterly:test       Test denoise levels on reference images');
+  console.log('');
+  console.log('Options:');
+  console.log('  --project <name>     Project to operate on (default: star-freight)');
+  console.log('  --game <name>        Deprecated alias for --project');
+  console.log('  --help               Show this help');
+  console.log('');
+  console.log('Examples:');
+  console.log('  sdlab init my-project --domain character-design');
+  console.log('  sdlab generate inputs/prompts/wave1.json --project star-freight');
+  console.log('  sdlab bind --stats --project star-freight');
+  console.log('  sdlab project doctor --project star-freight');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  let command = args[0];
+  let commandArgs = args.slice(1);
+
+  // Handle "project <subcommand>" two-word form
+  if (command === 'project' && args[1] && PROJECT_COMMANDS[args[1]]) {
+    commandArgs = args.slice(2);
+    const modulePath = PROJECT_COMMANDS[args[1]];
+    try {
+      const mod = await import(modulePath);
+      await mod.run(commandArgs);
+    } catch (err) {
+      console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const modulePath = COMMANDS[command];
+  if (!modulePath) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run "sdlab --help" for available commands.`);
+    process.exit(1);
+  }
+
+  try {
+    const mod = await import(modulePath);
+    await mod.run(commandArgs);
+  } catch (err) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/args.js

@@ -0,0 +1,106 @@
+/**
+ * Unified CLI argument parser.
+ *
+ * Supports:
+ *   --flag value       (space-separated)
+ *   --flag=value       (equals form)
+ *   --boolean-flag     (boolean)
+ *   positional args    (collected in order)
+ *   deprecated aliases (warns once, maps to canonical name)
+ */
+
+import { warnDeprecated } from './deprecation.js';
+
+/**
+ * @typedef {Object} ArgSpec
+ * @property {Object<string, {type: 'string'|'boolean', default?: any, alias?: string}>} flags
+ * @property {string[]} [positionals] - names for positional args (in order)
+ * @property {Object<string, string>} [deprecated] - old flag name → new flag name
+ */
+
+/**
+ * Parse CLI arguments.
+ * @param {string[]} argv — typically process.argv.slice(2)
+ * @param {ArgSpec} spec
+ * @returns {{ flags: Object, positionals: string[], rest: string[] }}
+ */
+export function parseArgs(argv, spec = {}) {
+  const flagDefs = spec.flags || {};
+  const deprecated = spec.deprecated || {};
+  const positionalNames = spec.positionals || [];
+
+  const flags = {};
+  const positionals = [];
+
+  // Set defaults
+  for (const [name, def] of Object.entries(flagDefs)) {
+    if (def.default !== undefined) flags[name] = def.default;
+    else if (def.type === 'boolean') flags[name] = false;
+    else flags[name] = undefined;
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (arg.startsWith('--')) {
+      let key, value;
+
+      if (arg.includes('=')) {
+        const eqIdx = arg.indexOf('=');
+        key = arg.slice(2, eqIdx);
+        value = arg.slice(eqIdx + 1);
+      } else {
+        key = arg.slice(2);
+        value = undefined;
+      }
+
+      // Handle deprecated aliases
+      if (deprecated[key]) {
+        warnDeprecated(key, deprecated[key]);
+        key = deprecated[key];
+      }
+
+      // Handle short aliases defined in flagDefs
+      const canonical = Object.entries(flagDefs).find(([, def]) => def.alias === key);
+      if (canonical) key = canonical[0];
+
+      // Normalize kebab-case to camelCase for lookup
+      const camelKey = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const def = flagDefs[key] || flagDefs[camelKey];
+
+      if (def?.type === 'boolean') {
+        flags[key in flagDefs ? key : camelKey] = true;
+      } else if (value !== undefined) {
+        flags[key in flagDefs ? key : camelKey] = value;
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+        flags[key in flagDefs ? key : camelKey] = argv[++i];
+      } else {
+        flags[key in flagDefs ? key : camelKey] = true;
+      }
+    } else {
+      positionals.push(arg);
+    }
+    i++;
+  }
+
+  // Map positionals to named keys
+  const named = {};
+  for (let j = 0; j < positionalNames.length && j < positionals.length; j++) {
+    named[positionalNames[j]] = positionals[j];
+  }
+
+  return { flags, positionals, named, rest: positionals.slice(positionalNames.length) };
+}
+
+/**
+ * Extract the --project (or deprecated --game) value from argv.
+ * Convenience for scripts that just need the project name.
+ */
+export function getProjectName(argv) {
+  const { flags } = parseArgs(argv, {
+    flags: { project: { type: 'string', default: 'star-freight' } },
+    deprecated: { game: 'project' },
+  });
+  return flags.project;
+}

package/lib/comfyui.js

@@ -0,0 +1,109 @@
+/**
+ * ComfyUI HTTP API client — extracted from 5 generation scripts.
+ *
+ * All functions take comfyUrl as a parameter so projects can override
+ * the default localhost:8188 endpoint.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+const DEFAULT_URL = 'http://127.0.0.1:8188';
+const MAX_POLL_MS = 600_000; // 10 minutes
+
+/**
+ * Check if ComfyUI is reachable.
+ * @param {string} [comfyUrl]
+ * @returns {Promise<boolean>}
+ */
+export async function comfyHealth(comfyUrl = DEFAULT_URL) {
+  try {
+    const res = await fetch(`${comfyUrl}/system_stats`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Submit a workflow and poll until complete.
+ * @param {Object} workflow — ComfyUI prompt graph
+ * @param {string} [comfyUrl]
+ * @param {{ clientPrefix?: string, timeoutMs?: number }} [opts]
+ * @returns {Promise<Object>} — history entry
+ */
+export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {}) {
+  const { clientPrefix = 'sdl', timeoutMs = MAX_POLL_MS } = opts;
+  const clientId = `${clientPrefix}-${Date.now()}`;
+
+  const res = await fetch(`${comfyUrl}/prompt`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt: workflow, client_id: clientId }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`ComfyUI submit failed: ${res.status} ${text}`);
+  }
+
+  const { prompt_id: promptId } = await res.json();
+
+  const start = Date.now();
+  while (true) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`ComfyUI poll timeout after ${timeoutMs / 1000}s for prompt ${promptId}`);
+    }
+    await new Promise(r => setTimeout(r, 1000));
+    const histRes = await fetch(`${comfyUrl}/history/${promptId}`);
+    if (!histRes.ok) continue;
+    const history = await histRes.json();
+    const entry = history[promptId];
+    if (!entry) continue;
+    if (entry.status?.completed) return entry;
+    if (entry.status?.status_str === 'error') {
+      throw new Error(`ComfyUI generation failed: ${JSON.stringify(entry.status)}`);
+    }
+  }
+}
+
+/**
+ * Download a generated image from ComfyUI.
+ * @param {string} filename
+ * @param {string} [subfolder]
+ * @param {string} [comfyUrl]
+ * @param {string} [type='output']
+ * @returns {Promise<Buffer>}
+ */
+export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output') {
+  const url = `${comfyUrl}/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder || '')}&type=${type}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Upload an image to ComfyUI's input folder.
+ * @param {string} filePath — local file to upload
+ * @param {string} filename — name to assign in ComfyUI
+ * @param {string} [comfyUrl]
+ * @returns {Promise<string>} — assigned name from ComfyUI
+ */
+export async function uploadImage(filePath, filename, comfyUrl = DEFAULT_URL) {
+  const data = await readFile(filePath);
+  const formData = new FormData();
+  formData.append('image', new Blob([data], { type: 'image/png' }), filename);
+  formData.append('overwrite', 'true');
+
+  const res = await fetch(`${comfyUrl}/upload/image`, {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Upload failed: ${res.status} ${text}`);
+  }
+
+  const result = await res.json();
+  return result.name;
+}

package/lib/config.js

@@ -0,0 +1,104 @@
+/**
+ * Per-project config loader.
+ *
+ * Loads JSON config files from a project root directory.
+ * Falls back to sensible defaults when files don't exist,
+ * so unmigrated projects (pre-v2.0) still work.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+function loadJsonFile(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Failed to parse ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Load project.json — project identity and generation defaults.
+ */
+export function loadProjectMeta(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'project.json'));
+  if (!data) {
+    return {
+      name: 'unknown',
+      display_name: 'Unknown Project',
+      domain: 'generic',
+      version: '0.0.0',
+      defaults: {},
+    };
+  }
+  return data;
+}
+
+/**
+ * Load constitution.json — array of rule objects.
+ */
+export function loadConstitution(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'constitution.json'));
+  if (!data) return { rules: [] };
+  if (Array.isArray(data)) return { rules: data };
+  if (!data.rules) throw new Error(`constitution.json must have a "rules" array`);
+  return data;
+}
+
+/**
+ * Load lanes.json — lane definitions with detection patterns.
+ */
+export function loadLanes(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'lanes.json'));
+  if (!data) {
+    return { default_lane: 'default', lanes: [] };
+  }
+  if (!data.lanes) throw new Error(`lanes.json must have a "lanes" array`);
+  return data;
+}
+
+/**
+ * Load rubric.json — scoring dimensions, thresholds, failure modes.
+ */
+export function loadRubric(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'rubric.json'));
+  if (!data) {
+    return {
+      dimensions: [],
+      thresholds: { pass: 0.7, partial: 0.5, fail_ceiling: 0.4 },
+      failure_to_rules: {},
+    };
+  }
+  return data;
+}
+
+/**
+ * Load terminology.json — group vocabulary and detection patterns.
+ */
+export function loadTerminology(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'terminology.json'));
+  if (!data) {
+    return {
+      group_label: 'group',
+      groups: {},
+      cross_group_patterns: {},
+      edge_defaults: {},
+      prompt_fallbacks: {},
+    };
+  }
+  return data;
+}
+
+/**
+ * Load all project config files at once.
+ */
+export function loadProjectConfig(projectRoot) {
+  return {
+    meta: loadProjectMeta(projectRoot),
+    constitution: loadConstitution(projectRoot),
+    lanes: loadLanes(projectRoot),
+    rubric: loadRubric(projectRoot),
+    terminology: loadTerminology(projectRoot),
+  };
+}

package/lib/deprecation.js

@@ -0,0 +1,14 @@
+/**
+ * Deprecation warning helper — fires once per flag per process.
+ */
+
+const warned = new Set();
+
+export function warnDeprecated(oldFlag, newFlag) {
+  const key = `${oldFlag}→${newFlag}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  process.stderr.write(
+    `\x1b[33m⚠ --${oldFlag} is deprecated and will be removed in v3.0. Use --${newFlag} instead.\x1b[0m\n`
+  );
+}

package/lib/paths.js

@@ -0,0 +1,38 @@
+/**
+ * Path resolution — single source of truth for repo root and project paths.
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Absolute path to the repository root. */
+export const REPO_ROOT = join(__dirname, '..');
+
+/**
+ * Resolve the root directory for a named project.
+ * @param {string} name — project name (e.g. 'star-freight')
+ * @returns {string} absolute path to projects/<name>/
+ */
+export function getProjectRoot(name) {
+  const root = join(REPO_ROOT, 'projects', name);
+  if (!existsSync(root)) {
+    throw new Error(
+      `Project "${name}" not found at ${root}.\n` +
+      `Run: sdlab init ${name} --domain <domain>`
+    );
+  }
+  return root;
+}
+
+/**
+ * Join segments onto a project root.
+ * @param {string} name — project name
+ * @param {...string} segments — path segments
+ */
+export function resolveProjectPath(name, ...segments) {
+  return join(getProjectRoot(name), ...segments);
+}