superlab 0.1.6 → 0.1.8

package/README.md

@@ -8,7 +8,7 @@ It combines:
 
 - command adapters for Codex and Claude
 - a shared `/lab` skill with stage-specific rules
-- lab-native change artifacts under `.superlab/changes/`
+- lab-native change artifacts under `.lab/changes/`
 - bounded Ralph Wiggum style iteration for experiments
 - helper scripts for run registration and evaluation summaries
 
@@ -22,6 +22,8 @@ cd your-project
 superlab init
 ```
 
+After `init` or `update`, start a new Codex or Claude session. If the new `/lab:*` commands still do not show up, restart the app.
+
 If the package has not been published yet, install from GitHub instead:
 
 ```bash
@@ -45,11 +47,14 @@ This writes:
 - `.codex/skills/lab/`
 - `.claude/commands/lab/*.md`
 - `.claude/skills/lab/`
-- `.superlab/config/workflow.json`
-- `.superlab/changes/`
-- `.superlab/templates/`
-- `.superlab/scripts/`
-- `.superlab/examples/`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.lab/system/core.md`
+- `.lab/config/workflow.json`
+- `.lab/context/`
+- `.lab/changes/`
+- `.lab/.managed/templates/`
+- `.lab/.managed/scripts/`
 
 If you prefer non-interactive use:
 
@@ -88,7 +93,70 @@ Refresh every registered project initialized from this user account:
 superlab update --all-projects
 ```
 
-`superlab init` writes `.superlab/install.json` inside each project and registers the project in the user-level registry so `update --all-projects` knows what to refresh.
+`superlab init` writes `.lab/.managed/install.json` inside each project and registers the project in the user-level registry so `update --all-projects` knows what to refresh.
+
+Legacy projects from older `superlab` versions may already contain `.codex/`, `.claude/`, or `.superlab/` assets without `.lab/.managed/install.json`. `superlab update` now reconstructs that metadata and upgrades the project in place.
+
+## Context Tools
+
+Refresh the compressed handoff layer from live project context:
+
+```bash
+superlab context refresh
+```
+
+Prune resolved or stale active-context entries:
+
+```bash
+superlab context prune
+```
+
+Archive cold iteration and writing history:
+
+```bash
+superlab context archive
+```
+
+Print the minimal handoff bundle for a new AI session:
+
+```bash
+superlab handoff
+```
+
+Check that the managed `.lab` layout is healthy:
+
+```bash
+superlab doctor
+```
+
+`doctor` validates:
+
+- required `.lab` files
+- `workflow.json` schema
+- `deliverables_root` placement
+- LaTeX-first paper output layout under `<deliverables_root>/paper/`
+
+## Version
+
+Show the CLI version and the current project asset version:
+
+```bash
+superlab version
+```
+
+Show only the current project asset version:
+
+```bash
+superlab version --project
+```
+
+Show a specific project:
+
+```bash
+superlab version --target /path/to/project
+```
+
+If a project still uses an older pre-metadata installation, `superlab version` reports `project: legacy` until you run `superlab update`.
 
 ## Language
 
@@ -101,11 +169,12 @@ superlab init --lang zh
 superlab init --lang en
 ```
 
-This installer also writes `.superlab/config/workflow.json`, which is the global contract for:
+This installer also writes `.lab/config/workflow.json`, which is the global contract for:
 
 - `workflow_language`
 - `paper_language`
 - `paper_format`
+- `deliverables_root`
 
 Stages should follow that file rather than guess language locally.
 
@@ -120,12 +189,14 @@ Stages should follow that file rather than guess language locally.
 ## Command Set
 
 - `/lab:idea` researches an idea, critiques it, and writes the initial research framing.
-- `/lab:spec` converts the approved idea into one `.superlab/changes/<change-id>/` directory.
+- `/lab:framing` locks paper-facing method names, module names, titles, and contribution wording before drafting.
+- `/lab:spec` converts the approved idea into one `.lab/changes/<change-id>/` directory.
 - `/lab:run` executes a small-scale validation run and establishes the evaluation pipeline.
 - `/lab:iterate` runs bounded experiment loops with fixed mission, explicit thresholds, and per-round reports.
 - `/lab:review` audits documents and results in reviewer mode.
 - `/lab:report` produces the final report from accumulated artifacts.
 - `/lab:write` converts stable report artifacts into paper sections through small writing rounds.
+  It requires an approved `/lab:framing` artifact before drafting.
   It reads vendored section references derived from `Research-Paper-Writing-Skills`.
 
 See the source command docs in [commands/codex/lab.md](/Users/zhouhao119/coding/write/commands/codex/lab.md) and [commands/claude/lab.md](/Users/zhouhao119/coding/write/commands/claude/lab.md). The npm package installs real command assets from `package-assets/`.
@@ -139,7 +210,7 @@ See the source command docs in [commands/codex/lab.md](/Users/zhouhao119/coding/
 - `scripts/` contains reproducibility helpers.
 - `tests/` contains minimal regression coverage for the helper scripts.
 - `examples/` contains a minimal end-to-end usage example.
-- `docs/` contains the design spec and generated reports.
+- `docs/` contains the design spec and release notes.
 
 ## Typical Flow
 
@@ -149,17 +220,20 @@ See the source command docs in [commands/codex/lab.md](/Users/zhouhao119/coding/
 4. Run `/lab:iterate` to improve against fixed targets using bounded iterations.
 5. Run `/lab:review` whenever you need reviewer-grade critique.
 6. Run `/lab:report` to synthesize the final report.
-7. Run `/lab:write` to draft paper sections from stable report evidence.
+7. Run `/lab:framing` to lock naming, title, and contribution wording.
+8. Run `/lab:write` to draft paper sections from stable report evidence.
 
-`/lab:write` writes final manuscript output to:
+`/lab:write` writes final manuscript output under the configured `deliverables_root` (default: `docs/research`):
 
-- `docs/paper/paper.tex`
-- `docs/paper/sections/*.tex`
+- `docs/research/report.md`
+- `docs/research/paper/main.tex`
+- `docs/research/paper/sections/*.tex`
 
 Internal writing-control artifacts stay under:
 
-- `.superlab/write/plan.md`
-- `.superlab/write/iterations/*.md`
+- `.lab/writing/framing.md`
+- `.lab/writing/plan.md`
+- `.lab/writing/iterations/*.md`
 
 ## Helper Scripts
 

package/README.zh-CN.md

@@ -20,6 +20,8 @@ cd your-project
 superlab init
 ```
 
+执行完 `init` 或 `update` 后，请新开一个 Codex 或 Claude 会话；如果新的 `/lab:*` 命令仍未生效，再重启应用。
+
 如果 npm 还没发布，也可以直接从 GitHub 安装：
 
 ```bash
@@ -43,11 +45,14 @@ npx github:zhouhaoUCAS/superlab init
 - `.codex/skills/lab/`
 - `.claude/commands/lab/*.md`
 - `.claude/skills/lab/`
-- `.superlab/config/workflow.json`
-- `.superlab/changes/`
-- `.superlab/templates/`
-- `.superlab/scripts/`
-- `.superlab/examples/`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.lab/system/core.md`
+- `.lab/config/workflow.json`
+- `.lab/context/`
+- `.lab/changes/`
+- `.lab/.managed/templates/`
+- `.lab/.managed/scripts/`
 
 如果你更喜欢非交互方式，也可以直接传参：
 
@@ -86,7 +91,70 @@ superlab update --target /path/to/project
 superlab update --all-projects
 ```
 
-`superlab init` 会在项目内写入 `.superlab/install.json`，并在用户级 registry 里登记项目路径，所以 `update --all-projects` 才知道要刷新哪些项目。
+`superlab init` 会在项目内写入 `.lab/.managed/install.json`，并在用户级 registry 里登记项目路径，所以 `update --all-projects` 才知道要刷新哪些项目。
+
+较老版本的 `superlab` 项目可能已经有 `.codex/`、`.claude/` 或 `.superlab/` 资产，但还没有 `.lab/.managed/install.json`。现在 `superlab update` 会自动重建这份 metadata，然后原地升级该项目。
+
+## 上下文工具
+
+根据当前项目上下文重建压缩后的 handoff 层：
+
+```bash
+superlab context refresh
+```
+
+清理已解决或已过期的 active-context 内容：
+
+```bash
+superlab context prune
+```
+
+把冷历史迭代和写作轮次归档出去：
+
+```bash
+superlab context archive
+```
+
+输出新 AI 会话最小接手包：
+
+```bash
+superlab handoff
+```
+
+检查当前 `.lab` 受管布局是否健康：
+
+```bash
+superlab doctor
+```
+
+`doctor` 目前会校验：
+
+- 必需的 `.lab` 文件是否存在
+- `workflow.json` 结构是否合法
+- `deliverables_root` 是否放在合理位置
+- `<deliverables_root>/paper/` 下是否仍然满足 LaTeX-first 输出约束
+
+## 版本查询
+
+查看当前 CLI 版本和当前目录项目的资产版本：
+
+```bash
+superlab version
+```
+
+只看当前项目资产版本：
+
+```bash
+superlab version --project
+```
+
+查看指定项目：
+
+```bash
+superlab version --target /path/to/project
+```
+
+如果项目还是旧的 pre-metadata 安装，`superlab version` 会显示 `project: legacy`；执行一次 `superlab update` 后就会切换到正式版本号。
 
 ## 语言
 
@@ -99,11 +167,12 @@ superlab init --lang zh
 superlab init --lang en
 ```
 
-安装器还会写入 `.superlab/config/workflow.json`。这个文件是全局约束，至少控制：
+安装器还会写入 `.lab/config/workflow.json`。这个文件是全局约束，至少控制：
 
 - `workflow_language`
 - `paper_language`
 - `paper_format`
+- `deliverables_root`
 
 后续 stage 应该按这个配置决定语言和论文格式，而不是各模板自己猜。
 
@@ -118,12 +187,14 @@ superlab init --lang en
 ## 命令集合
 
 - `/lab:idea` 调研 idea、文献、数据集、指标和 baseline，并输出初始方案。
-- `/lab:spec` 把批准后的方案转换成一个统一的 `.superlab/changes/<change-id>/` 目录。
+- `/lab:framing` 在正式写作前收紧方法名、模块名、论文题目和 contribution wording。
+- `/lab:spec` 把批准后的方案转换成一个统一的 `.lab/changes/<change-id>/` 目录。
 - `/lab:run` 执行最小可运行实验，并建立首版评估链路。
 - `/lab:iterate` 以固定 mission、固定阈值和最大轮次做有边界的实验迭代。
 - `/lab:review` 以审稿人模式检查方法、对照、公平性、泄漏和统计问题。
 - `/lab:report` 根据累积工件生成最终实验报告。
 - `/lab:write` 把稳定的 report 工件转成论文 section，并按小步方式逐轮修改。
+  它要求先有一个经批准的 `/lab:framing` 工件。
   它会读取随 `lab` 一起安装的 vendored 章节参考，这些参考来源于 `Research-Paper-Writing-Skills`。
 
 ## 使用流程
@@ -135,17 +206,20 @@ superlab init --lang en
 5. 用 `/lab:iterate` 进行多轮迭代。
 6. 在关键节点运行 `/lab:review`。
 7. 最后用 `/lab:report` 产出总报告。
-8. 用 `/lab:write` 把稳定结果写成论文各 section。
+8. 用 `/lab:framing` 收紧题目、命名和 contribution wording。
+9. 用 `/lab:write` 把稳定结果写成论文各 section。
 
-`/lab:write` 最终只把论文写入：
+`/lab:write` 会把最终可交付物写到 `deliverables_root` 指定的目录，默认是 `docs/research`：
 
-- `docs/paper/paper.tex`
-- `docs/paper/sections/*.tex`
+- `docs/research/report.md`
+- `docs/research/paper/main.tex`
+- `docs/research/paper/sections/*.tex`
 
 内部写作控制工件放在：
 
-- `.superlab/write/plan.md`
-- `.superlab/write/iterations/*.md`
+- `.lab/writing/framing.md`
+- `.lab/writing/plan.md`
+- `.lab/writing/iterations/*.md`
 
 ## 仓库内容
 
@@ -156,6 +230,7 @@ superlab init --lang en
 - `scripts/` 是运行登记、评估汇总和结果校验脚本。
 - `tests/` 是脚本与安装器测试。
 - `examples/` 是最小端到端示例。
+- `docs/` 存放设计文档和发布说明。
 - `docs/release.md` 是发布到 npm 的操作说明。
 - `.github/workflows/ci.yml` 会在 `main` 和 PR 上自动执行 `npm run release:check`。
 - `.github/workflows/publish.yml` 支持在配置好 `NPM_TOKEN` 后手动从 GitHub Actions 发布到 npm。

package/bin/superlab.cjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const fs = require("node:fs");
 const path = require("node:path");
 const {
   PACKAGE_VERSION,
@@ -9,8 +10,20 @@ const {
   updateAllProjects,
   updateSuperlabProject,
 } = require("../lib/install.cjs");
+const {
+  archiveContext,
+  pruneContext,
+  refreshContext,
+} = require("../lib/context.cjs");
 const { promptSelect } = require("../lib/init_tui.cjs");
 
+function restartReminder(lang) {
+  if (lang === "zh") {
+    return "项目资产已更新。请新开一个 Codex/Claude 会话；如果仍未生效，再重启应用。";
+  }
+  return "Project assets updated. Start a new Codex/Claude session; if changes still do not appear, restart the app.";
+}
+
 function printHelp() {
   console.log(`superlab
 
@@ -20,12 +33,20 @@ Usage:
   superlab update [--target <dir>]
   superlab update --all-projects
   superlab version [--target <dir>] [--global|--project]
+  superlab handoff [--target <dir>]
+  superlab doctor [--target <dir>]
+  superlab context refresh [--target <dir>]
+  superlab context prune [--target <dir>]
+  superlab context archive [--target <dir>]
 
 Commands:
   init      Initialize /lab commands, skills, templates, and scripts in a target
   install   Backward-compatible alias for init
   update    Refresh an initialized project or all registered projects
   version   Show installed CLI version and project asset version
+  handoff   Print the minimal context handoff bundle for a project
+  doctor    Check project health for the managed .lab layout
+  context   Maintain project context summaries and archives
   help      Show this help message
 `);
 }
@@ -121,6 +142,35 @@ function parseVersionArgs(argv) {
   return options;
 }
 
+function parseTargetOnlyArgs(argv) {
+  const options = {
+    targetDir: process.cwd(),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--target") {
+      options.targetDir = path.resolve(argv[index + 1]);
+      index += 1;
+    } else {
+      throw new Error(`Unknown option: ${value}`);
+    }
+  }
+
+  return options;
+}
+
+function parseContextArgs(argv) {
+  const [action, ...rest] = argv;
+  if (!["refresh", "prune", "archive"].includes(action || "")) {
+    throw new Error(`Unknown context action: ${action || "(missing)"}`);
+  }
+  return {
+    action,
+    ...parseTargetOnlyArgs(rest),
+  };
+}
+
 function printVersion(options) {
   const lines = [];
   if (!options.projectOnly) {
@@ -143,6 +193,167 @@ function printVersion(options) {
   console.log(lines.join("\n"));
 }
 
+function printHandoff(options) {
+  const handoffFiles = [
+    ".lab/context/session-brief.md",
+    ".lab/context/mission.md",
+    ".lab/context/state.md",
+    ".lab/context/evidence-index.md",
+  ];
+  const sessionBriefPath = path.join(options.targetDir, handoffFiles[0]);
+  if (!fs.existsSync(sessionBriefPath)) {
+    throw new Error(`No handoff brief found in ${options.targetDir}. Run 'superlab init' first.`);
+  }
+
+  const sessionBrief = fs.readFileSync(sessionBriefPath, "utf8").trimEnd();
+  console.log(`target: ${options.targetDir}`);
+  console.log("read-order:");
+  for (const filePath of handoffFiles) {
+    console.log(`- ${filePath}`);
+  }
+  console.log("");
+  console.log(sessionBrief);
+}
+
+function listFilesRecursive(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listFilesRecursive(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function readWorkflowConfig(targetDir) {
+  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
+  try {
+    return {
+      config: JSON.parse(fs.readFileSync(configPath, "utf8")),
+      issues: [],
+    };
+  } catch (error) {
+    return {
+      config: null,
+      issues: [`invalid workflow.json: ${error.message}`],
+    };
+  }
+}
+
+function validateWorkflowConfig(config) {
+  const issues = [];
+  if (!config || typeof config !== "object") {
+    return issues;
+  }
+  if (!["en", "zh"].includes(config.workflow_language)) {
+    issues.push("invalid workflow_language");
+  }
+  if (!["en", "zh"].includes(config.paper_language)) {
+    issues.push("invalid paper_language");
+  }
+  if (config.paper_format !== "latex") {
+    issues.push("unsupported paper_format");
+  }
+  if (typeof config.deliverables_root !== "string" || config.deliverables_root.trim() === "") {
+    issues.push("invalid deliverables_root");
+  } else {
+    const normalized = config.deliverables_root.replace(/\\/g, "/");
+    if (normalized === ".lab" || normalized.startsWith(".lab/")) {
+      issues.push("deliverables_root must not point inside .lab");
+    }
+  }
+  return issues;
+}
+
+function validateDeliverables(targetDir, config) {
+  const issues = [];
+  if (!config || typeof config.deliverables_root !== "string" || config.deliverables_root.trim() === "") {
+    return issues;
+  }
+
+  const deliverablesRoot = path.join(targetDir, config.deliverables_root);
+  const paperDir = path.join(deliverablesRoot, "paper");
+  const mainTexPath = path.join(paperDir, "main.tex");
+  const mainMdPath = path.join(paperDir, "main.md");
+  const sectionsDir = path.join(paperDir, "sections");
+
+  if (fs.existsSync(mainMdPath)) {
+    issues.push("paper main manuscript must be main.tex");
+  }
+
+  if (fs.existsSync(paperDir) && !fs.existsSync(mainTexPath)) {
+    issues.push("paper output is missing paper/main.tex");
+  }
+
+  if (fs.existsSync(sectionsDir)) {
+    const nonTexFiles = listFilesRecursive(sectionsDir)
+      .filter((filePath) => path.extname(filePath) !== ".tex")
+      .map((filePath) => path.relative(targetDir, filePath));
+    if (nonTexFiles.length > 0) {
+      issues.push(`paper sections must be .tex files: ${nonTexFiles.join(", ")}`);
+    }
+  }
+
+  return issues;
+}
+
+function printDoctor(options) {
+  const projectInfo = getProjectVersionInfo({ targetDir: options.targetDir });
+  const requiredPaths = [
+    ".lab/system/core.md",
+    ".lab/config/workflow.json",
+    ".lab/context/mission.md",
+    ".lab/context/state.md",
+    ".lab/context/decisions.md",
+    ".lab/context/evidence-index.md",
+    ".lab/context/open-questions.md",
+    ".lab/context/terminology-lock.md",
+    ".lab/context/summary.md",
+    ".lab/context/next-action.md",
+    ".lab/context/session-brief.md",
+    ".lab/.managed/install.json",
+  ];
+  const missing = requiredPaths.filter((relativePath) => !fs.existsSync(path.join(options.targetDir, relativePath)));
+  const { config, issues: configReadIssues } = readWorkflowConfig(options.targetDir);
+  const configIssues = configReadIssues.concat(validateWorkflowConfig(config));
+  const deliverableIssues = validateDeliverables(options.targetDir, config);
+
+  if (projectInfo.status === "missing") {
+    console.log("status: missing");
+    console.log(`target: ${options.targetDir}`);
+    console.log("project: not initialized");
+    return;
+  }
+
+  if (missing.length > 0 || configIssues.length > 0 || deliverableIssues.length > 0) {
+    console.log("status: degraded");
+    console.log(`target: ${options.targetDir}`);
+    console.log(`project: ${projectInfo.package_version}`);
+    console.log(`platform: ${projectInfo.platform}`);
+    console.log(`language: ${projectInfo.lang}`);
+    console.log(`missing: ${missing.length > 0 ? missing.join(", ") : "none"}`);
+    console.log(`config: ${configIssues.length > 0 ? configIssues.join(" | ") : "none"}`);
+    console.log(`outputs: ${deliverableIssues.length > 0 ? deliverableIssues.join(" | ") : "none"}`);
+    return;
+  }
+
+  console.log("status: ok");
+  console.log(`target: ${options.targetDir}`);
+  console.log(`cli: ${PACKAGE_VERSION}`);
+  console.log(`project: ${projectInfo.package_version}`);
+  console.log(`platform: ${projectInfo.platform}`);
+  console.log(`language: ${projectInfo.lang}`);
+  console.log("missing: none");
+  console.log("config: none");
+  console.log("outputs: none");
+}
+
 function shouldUseInteractiveInit(options) {
   if (options.lang && options.platform) {
     return false;
@@ -194,7 +405,7 @@ async function main() {
     return;
   }
 
-  if (!["init", "install", "update", "version"].includes(command)) {
+  if (!["init", "install", "update", "version", "handoff", "doctor", "context"].includes(command)) {
     throw new Error(`Unknown command: ${command}`);
   }
 
@@ -203,6 +414,33 @@ async function main() {
     return;
   }
 
+  if (command === "handoff") {
+    printHandoff(parseTargetOnlyArgs(rest));
+    return;
+  }
+
+  if (command === "doctor") {
+    printDoctor(parseTargetOnlyArgs(rest));
+    return;
+  }
+
+  if (command === "context") {
+    const options = parseContextArgs(rest);
+    if (options.action === "refresh") {
+      refreshContext({ targetDir: options.targetDir });
+      console.log(`context refreshed in ${options.targetDir}`);
+      return;
+    }
+    if (options.action === "prune") {
+      pruneContext({ targetDir: options.targetDir });
+      console.log(`context pruned in ${options.targetDir}`);
+      return;
+    }
+    const result = archiveContext({ targetDir: options.targetDir });
+    console.log(`context archived in ${result.archivePath}`);
+    return;
+  }
+
   if (command === "update") {
     const options = parseUpdateArgs(rest);
     if (options.allProjects) {
@@ -214,6 +452,7 @@ async function main() {
       for (const project of result.skipped) {
         console.log(`skipped: ${project.path} (${project.reason})`);
       }
+      console.log(restartReminder(detectLanguage()));
       return;
     }
 
@@ -224,6 +463,7 @@ async function main() {
     if (metadata.migration) {
       console.log(`migration: ${metadata.migration}`);
     }
+    console.log(restartReminder(metadata.lang));
     return;
   }
 
@@ -236,6 +476,7 @@ async function main() {
   console.log(`superlab installed into ${options.targetDir}`);
   console.log(`platform: ${options.platform}`);
   console.log(`language: ${options.lang}`);
+  console.log(restartReminder(options.lang));
 }
 
 main().catch((error) => {