superlab 0.1.11 → 0.1.12

package/README.md

@@ -151,7 +151,7 @@ superlab doctor
 
 ## Auto Mode
 
-First fill `.lab/context/auto-mode.md` with the bounded contract, the per-stage commands, and the policy check commands for the campaign, then arm it for the current project:
+First fill `.lab/context/auto-mode.md` with the bounded contract, the per-stage commands, the stage output contracts, and the policy check commands for the campaign, then arm it for the current project:
 
 ```bash
 superlab auto start
@@ -169,7 +169,15 @@ Stop the current auto-mode run:
 superlab auto stop
 ```
 
-`/lab:auto` is an orchestration mode layered on top of approved execution stages. It reuses `run`, `iterate`, `review`, `report`, and optional `write` inside the limits defined by `.lab/context/auto-mode.md` and `.lab/context/auto-status.md`. `superlab auto start` runs the configured stage commands in the foreground, polls for completion, enforces `success/stop/promotion` check commands, and guards the configured frozen core. It does not replace manual `idea`, `data`, `framing`, or `spec` decisions.
+`/lab:auto` is an orchestration mode layered on top of approved execution stages. It reuses `run`, `iterate`, `review`, `report`, and optional `write` inside the limits defined by `.lab/context/auto-mode.md` and `.lab/context/auto-status.md`. `superlab auto start` runs the configured stage commands in the foreground, polls for completion, enforces `success/stop/promotion` check commands, guards the configured frozen core, and validates stage-specific contracts:
+
+- `run` and `iterate` must change persistent outputs under `results_root`
+- `review` must update canonical review context
+- `report` must write `<deliverables_root>/report.md`
+- `write` must produce LaTeX output under `<deliverables_root>/paper/`
+- a successful promotion must write back into `.lab/context/data-decisions.md`, `.lab/context/decisions.md`, `.lab/context/state.md`, and `.lab/context/session-brief.md`
+
+It does not replace manual `idea`, `data`, `framing`, or `spec` decisions.
 
 ## Version
 

package/README.zh-CN.md

@@ -149,7 +149,7 @@ superlab doctor
 
 ## 自动模式
 
-先填写 `.lab/context/auto-mode.md`，明确本次自治执行的边界契约、各阶段命令，以及 success/stop/promotion 的检查命令，再启动当前项目的自动模式：
+先填写 `.lab/context/auto-mode.md`，明确本次自治执行的边界契约、各阶段命令、阶段产物约束，以及 success/stop/promotion 的检查命令，再启动当前项目的自动模式：
 
 ```bash
 superlab auto start
@@ -167,7 +167,15 @@ superlab auto status
 superlab auto stop
 ```
 
-`/lab:auto` 是叠加在现有执行阶段之上的编排模式。它会在 `.lab/context/auto-mode.md` 和 `.lab/context/auto-status.md` 的约束下，复用 `run`、`iterate`、`review`、`report`，以及可选的 `write`。`superlab auto start` 会在前台执行这些已配置阶段命令、轮询完成情况，并真正执行 success/stop/promotion 检查命令，同时保护已声明的 frozen core。它不会替代手动的 `idea`、`data`、`framing`、`spec` 决策。
+`/lab:auto` 是叠加在现有执行阶段之上的编排模式。它会在 `.lab/context/auto-mode.md` 和 `.lab/context/auto-status.md` 的约束下，复用 `run`、`iterate`、`review`、`report`，以及可选的 `write`。`superlab auto start` 会在前台执行这些已配置阶段命令、轮询完成情况，并真正执行 success/stop/promotion 检查命令，同时保护已声明的 frozen core，并校验各阶段的产物约束：
+
+- `run` 和 `iterate` 必须更新 `results_root` 下的持久输出
+- `review` 必须更新规范的审查上下文
+- `report` 必须写出 `<deliverables_root>/report.md`
+- `write` 必须写出 `<deliverables_root>/paper/` 下的 LaTeX 论文产物
+- promotion 成功后必须写回 `.lab/context/data-decisions.md`、`.lab/context/decisions.md`、`.lab/context/state.md` 和 `.lab/context/session-brief.md`
+
+它不会替代手动的 `idea`、`data`、`framing`、`spec` 决策。
 
 ## 版本查询
 

package/lib/auto.cjs

@@ -17,6 +17,18 @@ const FROZEN_CORE_ALIASES = {
   claims: [path.join(".lab", "context", "terminology-lock.md")],
   "terminology-lock": [path.join(".lab", "context", "terminology-lock.md")],
 };
+const REVIEW_CONTEXT_FILES = [
+  path.join(".lab", "context", "decisions.md"),
+  path.join(".lab", "context", "state.md"),
+  path.join(".lab", "context", "open-questions.md"),
+  path.join(".lab", "context", "evidence-index.md"),
+];
+const PROMOTION_CANONICAL_FILES = [
+  path.join(".lab", "context", "data-decisions.md"),
+  path.join(".lab", "context", "decisions.md"),
+  path.join(".lab", "context", "state.md"),
+  path.join(".lab", "context", "session-brief.md"),
+];
 
 function contextFile(targetDir, name) {
   return path.join(targetDir, ".lab", "context", name);
@@ -160,7 +172,15 @@ function hashPathState(filePath) {
 
   const stat = fs.statSync(filePath);
   if (stat.isDirectory()) {
-    return "__dir__";
+    const entries = fs
+      .readdirSync(filePath)
+      .sort((left, right) => left.localeCompare(right))
+      .map((entry) => {
+        const childPath = path.join(filePath, entry);
+        return `${entry}:${hashPathState(childPath)}`;
+      })
+      .join("|");
+    return crypto.createHash("sha256").update(entries).digest("hex");
   }
 
   return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
@@ -367,6 +387,117 @@ function readWorkflowLanguage(targetDir) {
   }
 }
 
+function readWorkflowConfig(targetDir) {
+  const configPath = path.join(targetDir, ".lab", "config", "workflow.json");
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function resolveProjectPath(targetDir, configuredPath, fallbackRelativePath) {
+  if (typeof configuredPath !== "string" || configuredPath.trim() === "") {
+    return path.join(targetDir, fallbackRelativePath);
+  }
+  return path.isAbsolute(configuredPath)
+    ? configuredPath
+    : path.resolve(targetDir, configuredPath);
+}
+
+function snapshotPaths(targetDir, relativePaths) {
+  const snapshot = new Map();
+  for (const relativePath of relativePaths) {
+    const absolutePath = path.resolve(targetDir, relativePath);
+    snapshot.set(absolutePath, hashPathState(absolutePath));
+  }
+  return snapshot;
+}
+
+function changedSnapshotPaths(snapshot) {
+  const changed = [];
+  for (const [absolutePath, previousHash] of snapshot.entries()) {
+    if (hashPathState(absolutePath) !== previousHash) {
+      changed.push(absolutePath);
+    }
+  }
+  return changed;
+}
+
+function stageContractSnapshot(targetDir, stage) {
+  const workflowConfig = readWorkflowConfig(targetDir);
+  const resultsRoot = resolveProjectPath(targetDir, workflowConfig.results_root, "results");
+  const deliverablesRoot = resolveProjectPath(targetDir, workflowConfig.deliverables_root, path.join("docs", "research"));
+  const trackedPathsByStage = {
+    run: [resultsRoot],
+    iterate: [resultsRoot],
+    review: REVIEW_CONTEXT_FILES.map((relativePath) => path.resolve(targetDir, relativePath)),
+    report: [path.join(deliverablesRoot, "report.md")],
+    write: [
+      path.join(deliverablesRoot, "paper", "main.tex"),
+      path.join(deliverablesRoot, "paper", "sections"),
+    ],
+  };
+
+  const absolutePaths = trackedPathsByStage[stage] || [];
+  const snapshot = new Map();
+  for (const absolutePath of absolutePaths) {
+    snapshot.set(absolutePath, hashPathState(absolutePath));
+  }
+  return {
+    stage,
+    absolutePaths,
+    snapshot,
+  };
+}
+
+function verifyStageContract({ stage, snapshot }) {
+  const changedPaths = [];
+  for (const [absolutePath, previousHash] of snapshot.entries()) {
+    if (hashPathState(absolutePath) !== previousHash) {
+      changedPaths.push(absolutePath);
+    }
+  }
+
+  if (stage === "review") {
+    if (changedPaths.length === 0) {
+      throw new Error(
+        "review stage did not update canonical review context (.lab/context/decisions.md, state.md, open-questions.md, or evidence-index.md)"
+      );
+    }
+    return;
+  }
+
+  if (stage === "report") {
+    if (changedPaths.length === 0) {
+      throw new Error("report stage did not produce the deliverable report.md under deliverables_root");
+    }
+    return;
+  }
+
+  if (stage === "write") {
+    if (changedPaths.length === 0) {
+      throw new Error("write stage did not produce LaTeX output under deliverables_root/paper");
+    }
+    return;
+  }
+
+  if ((stage === "run" || stage === "iterate") && changedPaths.length === 0) {
+    throw new Error(`${stage} stage did not produce persistent outputs under results_root`);
+  }
+}
+
+function verifyPromotionWriteback(targetDir, snapshot) {
+  const changedPaths = changedSnapshotPaths(snapshot);
+  if (changedPaths.length !== PROMOTION_CANONICAL_FILES.length) {
+    throw new Error(
+      `promotion did not update canonical context: ${PROMOTION_CANONICAL_FILES.filter(
+        (relativePath) => !changedPaths.includes(path.resolve(targetDir, relativePath))
+      ).join(", ")}`
+    );
+  }
+}
+
 async function runCommandWithPolling({ targetDir, stage, command, pollIntervalMs, deadlineMs, startedAt, status, lang }) {
   const child = spawn(command, {
     cwd: targetDir,
@@ -564,6 +695,79 @@ async function startAutoMode({ targetDir, now = new Date() }) {
     throw new Error(message);
   };
 
+  const stageExecutors = {
+    run: async () => {
+      const contract = stageContractSnapshot(targetDir, "run");
+      await runCommandWithPolling({
+        targetDir,
+        stage: "run",
+        command: mode.stageCommands.run,
+        pollIntervalMs,
+        deadlineMs,
+        startedAt,
+        status: currentStatus,
+        lang,
+      });
+      verifyStageContract({ stage: "run", snapshot: contract.snapshot });
+    },
+    iterate: async () => {
+      const contract = stageContractSnapshot(targetDir, "iterate");
+      await runCommandWithPolling({
+        targetDir,
+        stage: "iterate",
+        command: mode.stageCommands.iterate,
+        pollIntervalMs,
+        deadlineMs,
+        startedAt,
+        status: currentStatus,
+        lang,
+      });
+      verifyStageContract({ stage: "iterate", snapshot: contract.snapshot });
+    },
+    review: async () => {
+      const contract = stageContractSnapshot(targetDir, "review");
+      await runCommandWithPolling({
+        targetDir,
+        stage: "review",
+        command: mode.stageCommands.review,
+        pollIntervalMs,
+        deadlineMs,
+        startedAt,
+        status: currentStatus,
+        lang,
+      });
+      verifyStageContract({ stage: "review", snapshot: contract.snapshot });
+    },
+    report: async () => {
+      const contract = stageContractSnapshot(targetDir, "report");
+      await runCommandWithPolling({
+        targetDir,
+        stage: "report",
+        command: mode.stageCommands.report,
+        pollIntervalMs,
+        deadlineMs,
+        startedAt,
+        status: currentStatus,
+        lang,
+      });
+      verifyStageContract({ stage: "report", snapshot: contract.snapshot });
+    },
+    write: async () => {
+      const contract = stageContractSnapshot(targetDir, "write");
+      await runCommandWithPolling({
+        targetDir,
+        stage: "write",
+        command: mode.stageCommands.write,
+        pollIntervalMs,
+        deadlineMs,
+        startedAt,
+        status: currentStatus,
+        lang,
+      });
+      verifyStageContract({ stage: "write", snapshot: contract.snapshot });
+    },
+  };
+
   const executeStage = async (stage) => {
     const command = mode.stageCommands[stage];
     if (!isMeaningful(command)) {
@@ -573,16 +777,11 @@ async function startAutoMode({ targetDir, now = new Date() }) {
     let stageCompleted = false;
     while (!stageCompleted) {
       try {
-        await runCommandWithPolling({
-          targetDir,
-          stage,
-          command,
-          pollIntervalMs,
-          deadlineMs,
-          startedAt,
-          status: currentStatus,
-          lang,
-        });
+        const executor = stageExecutors[stage];
+        if (!executor) {
+          throw new Error(`unsupported auto stage executor: ${stage}`);
+        }
+        await executor();
         executedStages.push(stage);
         writeRunningStatus({
           currentStage: stage,
@@ -653,6 +852,7 @@ async function startAutoMode({ targetDir, now = new Date() }) {
         deadlineMs,
       });
       if (promotionCheck.matched) {
+        const promotionSnapshot = snapshotPaths(targetDir, PROMOTION_CANONICAL_FILES);
         await runCommandWithPolling({
           targetDir,
           stage: "promotion",
@@ -663,17 +863,18 @@ async function startAutoMode({ targetDir, now = new Date() }) {
           status: currentStatus,
           lang,
         });
+        writeRunningStatus({
+          currentStage: stagesPerIteration.at(-1) || currentStatus.currentStage,
+          currentCommand: mode.promotionCommand,
+          decision: `promotion policy matched after iteration ${iteration}`,
+        });
         promotionApplied = true;
         refreshContext({ targetDir });
+        verifyPromotionWriteback(targetDir, promotionSnapshot);
         const frozenCoreChangesAfterPromotion = detectFrozenCoreChanges(frozenCoreSnapshot);
         if (frozenCoreChangesAfterPromotion.length > 0) {
           failAutoMode(`frozen core changed: ${frozenCoreChangesAfterPromotion.join(", ")}`);
         }
-        writeRunningStatus({
-          currentStage: stagesPerIteration.at(-1) || currentStatus.currentStage,
-          currentCommand: mode.promotionCommand,
-          decision: `promotion policy matched after iteration ${iteration}`,
-        });
       }
     }
 

package/lib/i18n.cjs

@@ -941,6 +941,14 @@ const ZH_SKILL_FILES = {
 - Promotion check command:
 - Promotion command:
 
+## 阶段产物约束
+
+- Run stage contract: write persistent outputs under \`results_root\`.
+- Iterate stage contract: update persistent outputs under \`results_root\`.
+- Review stage contract: update canonical review context such as \`.lab/context/decisions.md\`、\`state.md\`、\`open-questions.md\` or \`evidence-index.md\`.
+- Report stage contract: write the final report to \`<deliverables_root>/report.md\`.
+- Write stage contract: write LaTeX output under \`<deliverables_root>/paper/\`.
+
 ## 升格策略
 
 - Promotion policy:
@@ -954,6 +962,7 @@ const ZH_SKILL_FILES = {
 
 - Stop conditions:
 - Escalation conditions:
+- Canonical promotion writeback: update \`.lab/context/data-decisions.md\`、\`.lab/context/decisions.md\`、\`.lab/context/state.md\` and \`.lab/context/session-brief.md\`.
 `,
   [path.join(".lab", "context", "auto-status.md")]:
 `# 自动模式状态
@@ -1794,6 +1803,12 @@ ZH_CONTENT[path.join(".codex", "skills", "lab", "stages", "auto.md")] = `# \`/la
 - 可以在 exploration envelope 内增加数据集、benchmark 和 comparison methods。
 - 只有在 auto-mode 契约中的升格策略满足时，才允许把 exploratory addition 自动升格为 primary package。
 - 长任务必须通过轮询推进，直到完成、超时或命中停止条件。
+- 不要只看命令退出码；必须检查阶段产物约束：
+  - \`run\` 和 \`iterate\` 更新 \`results_root\`
+  - \`review\` 更新规范审查上下文
+  - \`report\` 写出 \`<deliverables_root>/report.md\`
+  - \`write\` 写出 \`<deliverables_root>/paper/\` 下的 LaTeX 产物
+- promotion 成功后，必须写回 \`data-decisions.md\`、\`decisions.md\`、\`state.md\` 和 \`session-brief.md\`。
 
 ## 最小流程
 

package/package-assets/shared/lab/context/auto-mode.md

@@ -27,6 +27,14 @@ Use this file to define the bounded autonomous execution envelope for `/lab:auto
 - Promotion check command:
 - Promotion command:
 
+## Stage Output Contracts
+
+- Run stage contract: write persistent outputs under `results_root`.
+- Iterate stage contract: update persistent outputs under `results_root`.
+- Review stage contract: update canonical review context such as `.lab/context/decisions.md`, `state.md`, `open-questions.md`, or `evidence-index.md`.
+- Report stage contract: write the final report to `<deliverables_root>/report.md`.
+- Write stage contract: write LaTeX output under `<deliverables_root>/paper/`.
+
 ## Promotion Policy
 
 - Promotion policy:
@@ -40,3 +48,4 @@ Use this file to define the bounded autonomous execution envelope for `/lab:auto
 
 - Stop conditions:
 - Escalation conditions:
+- Canonical promotion writeback: update `.lab/context/data-decisions.md`, `.lab/context/decisions.md`, `.lab/context/state.md`, and `.lab/context/session-brief.md`.

package/package-assets/shared/skills/lab/stages/auto.md

@@ -40,6 +40,12 @@
 - Poll long-running commands until they finish, hit a timeout, or hit a stop condition.
 - Keep a poll-based waiting loop instead of sleeping blindly.
 - Reuse the existing `/lab:run`, `/lab:iterate`, `/lab:review`, `/lab:report`, and optional `/lab:write` contracts instead of inventing a parallel workflow.
+- Enforce stage contracts, not just exit codes:
+  - `run` and `iterate` must change persistent outputs under `results_root`
+  - `review` must update canonical review context
+  - `report` must produce `<deliverables_root>/report.md`
+  - `write` must produce LaTeX output under `<deliverables_root>/paper/`
+- Treat promotion as incomplete unless it writes back to `data-decisions.md`, `decisions.md`, `state.md`, and `session-brief.md`.
 
 ## Minimum Procedure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlab",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Strict /lab research workflow installer for Codex and Claude",
   "keywords": [
     "codex",